Views and folders
Read and write saved views and folder settings from a working copy, and keep folders of files in step on a Mac.
A saved view is a system.view item, and a folder's settings are a system.folder item. A working copy reads both from its store, and writes them through the server at once, never through the queue. Folders keeps directories on a Mac in step with a folder's settings.
Saved views
SavedView is a view with id, version, state and settings. It isn't called View, which would clash with SwiftUI's. Hydrate with system.view in the slice, or pin a view, to hold it.
| Call | Answers |
|---|---|
items.views() | Rows<SavedView>, every held view. |
items.view(_:) | SavedView?: nil where the copy doesn't hold it. |
items.list(inView:limit:offset:) | The view's items in its sort order, ties in ascending ID order. |
items.groups(inView:timeZone:) | Rows<ViewGroup>, each key with its count. |
copy.search(_:inView:limit:) | A search narrowed to what the view lists. |
A view's reads never answer in part. They throw:
hydrationIncompletewhile a hydration fills the copy or the copy is stale.notFoundwithnot_heldfor a view the copy doesn't hold.invalidwhere the copy can't answer the whole view: a type or tier the slice doesn't hold,beneathwithoutparent-ofheld whole, abackrefor a group byedge[<type>]orbackref[<type>]of an edge type not held whole, or a revoked view.
Groups come in the view's order first, then by ascending key, with the null group last. Groups in hidden are left out, but their items still list. A view that groups nothing answers one null group. Date groups follow timeZone, or the device's.
Read a view shows a view on screen, and LiveQuery has readings for each call.
View settings
| Type | Fields |
|---|---|
ViewSettings | title, query, sort (first key first; empty keeps the server's order), group (nil groups nothing). |
ViewQuery | types (empty is every type but system.*), tier (nil is both), states (nil is active and archived), filter, beneath. |
ViewSort | by, an own field such as created_at or properties.<name>, and direction. |
ViewGrouping | by, a field or edge[<type>] or backref[<type>]; bucket (.day, .week from Monday, .month or .year); order; hidden. |
A filter takes the status_group term: status_group neq "completed" AND status_group neq "canceled" holds the open items.
Write a view
| Call | Does |
|---|---|
copy.createView(_ ViewSettings, idempotencyKey:) | Creates a view and returns it. |
copy.changeView(_:_ ViewSettingsChange, baseVersion:idempotencyKey:) | Replaces each setting the change names. |
copy.deleteView(_:idempotencyKey:) | Deletes a view for good, revoked ones included. |
ViewSettingsChange replaces each field it names whole. An empty sort removes the sort, and group: .clear removes the grouping.
- With no server the call throws
noServer, and offlinenetwork. Nothing waits to be sent. - After a
networkfailure, retry with the sameidempotencyKey. The server may have made the change, and the key answers it rather than writing twice. - A query the server refuses throws
validationwithvalidation_error. A key that may not writesystem.viewthrowsforbiddenwithtype_not_permitted. - A setting changed since
baseVersionthrowsversionConflict, and the copy keeps the view it held. Settings nobody else changed are merged. - A revoked view throws
validationwithinvalid_transition. A view the server doesn't have throwsnotFoundwithitem_not_found.
Save a view explains views.
Folder settings
items.folder(_:) reads a held Folder, with id, version, state and settings. It throws invalid for an item that isn't a system.folder.
FolderSettings field | Holds |
|---|---|
title | Required to create a folder. |
query | FolderQuery: types, tier (nil is the library tier), states (nil is active and archived), filter and beneath, an item ID or the path of one of the folder's own files. |
defaults | FolderDefaults for a new file: type, tier, properties, tags, and edges from edge type to item IDs. |
include, ignore | Gitignore patterns for the paths taken and left alone. ignore wins. |
firstPlacement | Where an item of a type made elsewhere first appears, from type to directory. |
removalThreshold | RemovalThreshold(files:fraction:), nil being 10 files and 0.25. |
additionThreshold | AdditionThreshold(files:fraction:), nil being 50 files and 0.25. |
outsideQuery | OutsideQuery: .send makes a new file outside the query an item and flags it unmatched; .hold leaves it on the disk. |
The server's removal threshold also has a ceiling, 100 files when unset. The Swift type doesn't carry it yet, so a change that names a removalThreshold sends none.
| Call | Does |
|---|---|
copy.createFolder(_ FolderSettings, idempotencyKey:) | Creates a folder and returns it. |
copy.changeFolder(_:_ FolderSettingsChange, baseVersion:idempotencyKey:) | Replaces each setting the change names. |
copy.revokeFolder(_:idempotencyKey:) | Revokes a folder. A revoked folder changes no more. |
These are sent as view writes are, and answer the same way to a network failure, a changed baseVersion and a revoked folder. Before sending, they throw invalid for settings no folder follows, and validation for a filter that doesn't parse or a default tag or property name the server refuses. Each tells held streams .refreshed(.folderWritten).
Folders on a Mac
Folders(server:) works the Mac's folders through the same registry as the marfa command line, so a folder added in either shows in both. Without a server, only list(), status(of:), confirmFirstSync(in:), confirmRemoval(in:), restoreRemoval(in:) and remove(_:) work.
| Call | Does |
|---|---|
add(_ directory:following:) | Makes a directory follow a system.folder, making the directory if needed. Returns AddedFolder. |
list() | Every ListedFolder in the registry, with directory and folderId. |
status(of:) | FolderStatus from the folder's own store, with no request. |
sync(_:) | One pass: sends disk changes, catches up, writes out what the query matches, and sends placements. Returns FolderSyncResult. |
confirmFirstSync(in:) | Lets the first sync go. Returns whether it was waiting. |
confirmRemoval(in:) | Lets a paused large removal and a paused drop of new files go. Returns ConfirmedFolder. |
restoreRemoval(in:) | Cancels a paused removal and writes the files back. Returns RestoredRemoval. |
remove(_:) | Takes the folder off the Mac and leaves plain files. Throws invalid while writes wait to be sent: sync first. |
watch(_:) | Keeps the folder in step while the app runs. Returns a FolderWatch. |
A new folder's first sync waits for the person. Until confirmFirstSync(in:), sync(_:) only reads the folder and returns .awaitingConfirmation(FirstSyncPlan), and watch(_:) throws firstSyncWaiting. The plan counts what it will write and send, the files it writes beside a file at the same path, and the items it leaves (left).
One process works a folder at a time. A call that finds a watch holding the folder asks it to let go and waits up to 10 seconds, then throws readingHandle. watch(_:) throws readingHandle at once. status(of:) answers beside a watch.
AddedFolder.storage and FolderEvent.watching give a StorageCause for a directory in iCloud Drive, a cloud service or a network file system. It's a warning, not a refusal. Show its warning once for each folder in a session.
What a sync reports
.synced(FolderSync) holds hydrated, catchUpError (why it couldn't catch up; it still writes out what the copy holds) and a FolderPass:
FolderPass field | Holds |
|---|---|
settings | The settings file: sent, written, flagged, unwritten. |
scan | FolderScan: what it read from the disk. |
drain | The DrainReport. A conflicted edit is .conflicted naming the copy that took its text. |
rebased, gaveWay | Edits sent again on the held version, and placements another Mac made first. |
pull | FolderPull: what it wrote to the disk. nil where the copy expired and couldn't be hydrated. |
flagged | Each held file once, as FlaggedFile with path, flag, reason and the pull's item. |
FolderScan counts created, updated, renamed, unchanged, waiting, missing, deleted, skipped, movedAway, paused, pausedAdditions and heldOutside, and lists trashed and secrets, the files not sent because their names are ones secrets use.
FolderPull counts written, rewritten, moved, unchanged, skipped, removed, purged, kept, unwritten, absent, unplaced, unmatched and paused.
- Two items with names that compare as one, and no placement yet: the one created later gets the numbered name, such as
Plan (2).md, on every device. A file already at the plain name keeps it. - A link lookup that finds the copy expired, or the call stopped, ends the sync with
copyExpired,streamIncompleteorcanceled.
Status
FolderStatus has files, paused and firstSync. Each FileStatus has path, itemId, state, waits, flag, reason and warning.
FileState | Means |
|---|---|
.inStep | The file and its item agree. |
.waiting | A write for it waits to be sent. |
.held | Not sent; reason says why. |
.unmatched | Its item no longer matches the query. |
.unreached | The scan didn't reach it, so it's held rather than deleted. |
.outside | It lies where the folder takes no files. |
FolderPaused counts disk (deletes not sent), pull (files whose items left elsewhere), additions and outsideQuery. isPaused is set while a removal or a drop of new files waits, and outsideQuery doesn't count toward it.
Watch
let watch = try await Folders(server: server).watch(directory)
for try await event in watch {
if case .passed(let pass) = event { show(pass) }
}FolderEvent | Means |
|---|---|
.watching(_:storage:) | Passes begin. |
.passed(FolderPass) | A pass changed something or found something to report. |
.unreachable(reason:), .reachable | The server stopped or started answering. Told when it changes. |
.retrying(_:after:) | Hydrating failed; it tries again after the wait. |
.watcherFailed(message:) | The file system reported an error; the watch goes on. |
.waiting(reason:) | The directory is gone, and the watch waits for it. |
.handedOver, .heldElsewhere, .takenBack | The watch let the folder go, to a call or to another process, and took it back. No pass runs in between. |
.removed, .unlisted | A call removed the folder or took it off the registry. The watch ends. |
The sequence ends after stop(), .removed or .unlisted, and throws a MarfaError when the watch fails, such as unauthorized. Leaving a loop early doesn't stop the watch: call stop(), which returns once the folder is let go.
Sync a folder and How a folder treats files explain folders, and the rules are in the contract's folder sync and folder guards chapters.