Items, edges and tables

Read, search and write the items, edges, tags, extensions and table rows a working copy holds.

A working copy answers reads from its store with no request, and queues every write, which shows in the copy at once and reaches the server on the next drain. Each write returns its QueuedWrite. The parts are copy.items, copy.edges, copy.tags, copy.metadata, copy.extensions and copy.tables. Write in a working copy explains the model.

Read items

CallAnswers
items.list(_ ListFilters, sort:)Rows<Item>, the held items the filters select.
items.get(_ id)Item?: nil for an item in the bin or not held. Throws hydrationIncomplete while a hydration fills the copy.
items.get(_ ids, includingBin:)Rows<Item>, each held item once, in the order named, from one snapshot. It answers .partial during a hydration instead of throwing.
copy.search(_ text, filters:limit:)Rows<SearchHit>, each with item, score and snippet. limit defaults to 20.
items.links(in:)BodyLinks: each link and embed in the body, and what it names. Takes one ID or a list.
items.displays(of:), items.displays(for:)An ItemDisplay for each item: name, nil where the server says "Untitled", and preview, at most 240 characters.
items.linkCandidates(of:in:)For each [[link]] target being typed, its LinkState and the held items it could name.
linkParts(in:)A free function: every [[link]] in a text, with the range of each part in UTF-16 units.
items.thumbnail(_:)The held row's Thumbnail, with no request.
items.original(ofConflictedCopy:), items.conflictedCopies(of:)The two ends of a conflicted copy's derived-from edge.
copy.counts(of:_ Counted)An ItemCount for each ID.

An Item has the fields the API gives it, with title and body read from the type's fields. Two are the copy's own:

  • readOnly is the server's advice that the item can't be edited, such as an item a connector owns. Neither the server nor the copy refuses a write for it. The copy asks again at the end of a catch-up and when a held stream reaches the head, at most once every 15 minutes, so the value can be older. An item the server hasn't answered yet holds false.
  • unreadableProperties says why properties is empty where the store holds a row the copy can't read. A hydration replaces it.

Filters

ListFilters and SearchFilters share types, states, allStates, tier, tags, occurredAfter, occurredBefore, filter and beneath. A list adds source, updatedAfter, updatedBefore, limit and offset.

FilterRule
typesUp to ten, each with its subtree. Empty, more than ten, or a type the copy doesn't hold is refused.
statesnil is active only. [.trashed] lists the bin from the copy, newest first. Empty, or beside allStates, is refused validationError.
filterThe server's listing grammar, refused where the server refuses it. A backref term is refused invalid.
beneathAn item and everything it reaches along parent-of, as far as the copy holds.
updatedAfterOrders by update time, oldest first. A sort naming another order is refused.

Sort(field:direction:) takes .createdAt, .updatedAt, .occurredAt or .property(name:). The default is createdAt descending. Ties go by ID. List, filter and search has the grammar.

Counts

Counted is .edge(edgeType:) for items linking in, such as a collection's members, .backref(edgeType:) for items linked out to, such as parent-of children, or .rows(table:).

  • Each ItemCount has total, statusGroups (nil for rows) and held, which says the copy answered. Only active items count.
  • The copy asks its server for what it can't be sure of, 100 IDs to a request.
  • Where neither can answer, it throws CountError.unavailable(cause:). Show no count, never 0.
  • A call during use(_:) throws keyChanging.
  • Server.itemCounts(of:_:) asks the server directly, for an app with no copy.

copy.catalog.statusGroup(of:) gives an item's StatusGroup: .notStarted, .inProgress, .completed or .canceled.

Write items

let write = try await copy.items.create(Draft(
    type: "core.bookmark",
    properties: ["title": "Tide tables", "url": "https://tides.example.com/harbor"],
    tags: ["coast"]))

let bookmark = try await copy.items.get(write.itemId!)!
try await copy.items.update(bookmark.id, Edit(properties: ["title": "Tide tables, harbor"], baseVersion: bookmark.version))
CallQueues
items.create(_ Draft)A create. Each tag is a write of its own, addTag.
items.update(_:_ Edit)An update. Throws invalid unless baseVersion is the version the copy holds, before anything is queued.
items.updateAsRead(_:_ Edit)An update based on an older version, which the server merges against what was read. Use it for an editor that held a row while the copy caught up. It takes version 0 for an item this copy created, once the server has answered the create.
items.delete(_:)A move to the bin.
items.restore(_:)A restore. An item the copy doesn't hold, such as one from the server's bin, is held once the server answers.
items.transition(_:to:)A change of ItemState: .active, .archived, .trashed or .revoked.

Draft takes type, properties, tags, tier, state, id, source, sourceId, occurredAt, captureLatitude, captureLongitude and edges.

Edit takes properties, replaceProperties, clearProperties, baseVersion, sourceId, type, tier, occurredAt and clearOccurredAt:

  • A null in properties clears nothing. Name a property in clearProperties to remove it.
  • type moves the item to another type.
  • clearOccurredAt beside occurredAt is refused.

The copy checks properties against the type before it queues. A value of the wrong kind throws validation with the code invalid_properties.

The bin

CallDoes
items.bin(type:after:limit:)One BinPage of the server's bin, read online whatever the slice. limit is held to 1 through 100. A short page can still have a nextCursor.
items.purge(_:version:)Destroys an item in the bin on the server now. Never queued, so it needs the server.

purge is sent at version, or at the version the copy holds, so an item changed since throws versionConflict. Before sending, it throws:

  • notFound with not_held, for an item the copy doesn't hold and no version.
  • validation with invalid_transition, for an item the copy shows outside the bin.
  • invalid, for an item with a write still waiting.

Offline it throws network, and with no server noServer. The key needs items.purge.

Edges

CallDoes
edges.from(_:), edges.to(_:)The held edges at one end of an item, unsent ones included.
edges.ofType(_:)Every held edge of one type, oldest first.
edges.get(_:)One edge, or several in the order named.
edges.create(from:to:type:properties:id:)Queues an edge.
edges.check(from:to:type:properties:id:)Throws what create would throw now, and queues nothing.
edges.update(_:_ EdgeEdit)Changes properties, moves one end, or both. Returns nil and queues nothing for an edit that changes nothing.
edges.check(_:moving:)Throws what a move would throw now. A move onto the end the edge holds returns.
edges.delete(_:)Queues a delete.

Every edge read and write throws hydrationIncomplete until the copy is whole: during a hydration, and while a stale copy refills.

An Edge has fromId, toId, edgeType, properties and version. A queued edge write names its from end in itemId and its to end in toId.

EdgeEdit(_ properties:baseVersion:move:) moves one end with .from(_ id) or .to(_ id). Each property given replaces its whole value.

  • A move of the from end expires the copy once the server accepts it. The drain sends the writes behind the move, then throws copyExpired with reach_changed, and the app hydrates again.
  • A move of the to end doesn't expire the copy.
  • A move to an item whose create is still queued waits for that create.

Refusals

create, check and a move refuse in the server's order, with the server's code, judged from what the copy holds:

RefusalError and code
An edge from an item to itselfvalidation, edge_cycle
An end in the binnotFound, item_not_found
An end of a type the edge type doesn't admit, then nesting under a flat typevalidation, edge_constraint_violation
The same type, from end and to end as an edge the copy showsedge_constraint_violation, details.constraint is "duplicate"
An end that already holds its one edge of the type, such as a second parent-of parentedge_constraint_violation, details.constraint is "cardinality", with details.from_id or details.to_id
A cycle through held edgesedge_cycle
A move where the end that stays may hold more than one edge, such as aboutvalidation_error
do {
    try await copy.edges.check(from: note.id, to: note.id, type: "references")
} catch MarfaError.validation(let code, _, let details, _) {
    // code is "edge_cycle", details is ["edge_type": "references"]
}

Returning isn't the server's verdict. Where the copy doesn't hold what decides a refusal, such as a cycle outside its slice, the check returns and the queued write meets the server. A type's writtenFrom says which end an edge is written from (EdgeWrittenFrom is .from, .to or .none). Edges in a working copy covers drag and drop.

Tags and extensions

CallQueues
tags.add(_:to:)One tag, leaving the others. An item that would hold more than 100 tags throws validation_error, and earlier adds stay queued.
tags.remove(_:from:)One tag's removal.
metadata.replaceTags(of:with:)Every tag in one write.
extensions.write(_ namespace:_ body:on:)An extension's whole body.
extensions.delete(_ namespace:from:)An extension's removal.

Tables

An item of a type that declares a table, or one carrying its own columns, has rows in it. A row is never an item: it has no version, tags or edges. The copy holds a table whole or not at all, and reads one it doesn't hold from the server. Tables explains them.

CallDoes
tables.hold(_ table:ofType:)Holds that table of every held item of the type, or a pattern of types, and fills it. Returns TableHold with wasHeld and fill, which is nil where another call holds the stream and fills it. Throws invalid for a table no such type declares.
tables.letGo(_:ofType:)Drops the choice, and the rows no other choice holds. Queued writes stay queued.
tables.held()HeldTables: the choices, and each held table's state and rows.
tables.fill()One pass over the tables not yet whole. TableFill counts whole, online, unfilled and failed, with the last failure.
tables.rows(of:in:_ RowsQuery)TableAnswer<TableRowPage>, with rows and nextCursor.
tables.row(_:of:in:)One TableRow. Throws notFound for a row the table doesn't hold.
tables.totals(of:in:filter:)TableTotals: rowCount, and each adding column's sum, count, average, min or max.
tables.write(_ [RowOperation]:to:of:)Queues one batch and shows it at once.
tables.undo(batch:in:of:)Queues the undo of a batch the server took. No row changes until the server's event arrives.

TableState is .owed, .filling, .whole, or .online for a table past the cap on rows a copy holds. A TableAnswer sets held when the copy answered it, with waiting writes laid over the rows. Otherwise the server answered, which a copy offline can't reach. Before each such request, the copy checks that the server is the instance it was built from. If another instance answers at the address, the read throws copyExpired, the copy expires, and no item ID is sent. A lookup of a linked item by ID is checked the same way.

RowsQuery takes limit (1 through 1,000), cursor, filter (the item grammar, with values.<column>, id and updated_at), sort (.id, .updatedAt or .column(_:)) and direction. A TableRow has id, values, updatedAt and withheld, the columns naming an item the key can't read.

RowOperation is .put(id:values:), which writes the whole row, .patch(id:values:), where null clears a column, or .delete(id:).

  • The server takes all of a batch or none of it. A drain sends consecutive batches to one table in one request, each with its own verdict: accepted, conflicted with the replaced cells in conflicts, or refused.
  • The accepted write's rowBatch is the batch to pass to undo.
  • write throws notFound with item_not_found or table_not_found, or validation, and queues nothing.

A held table is read and written offline. Changed tables arrive in Reread.Parts.rows.tables and CatchUpReport.changedTables, and a stream hears .refreshed(.tables). The rules are in the contract's tables chapter.

On this page