v0.2.6-alpha.3

Swift: Types

Importing KizunaSync brings in the client, the configuration structs, the query and write builders, the scheduler, the inspector, and the records the engine answers with. The records are typealiases over the generated UniFFI types, so their fields carry the names the generator produced.

// TodoApp/TodoSync.swift (excerpt)
import KizunaSync

Client and configuration#

Name	Type	Required	Description
`KizunaSyncClient`	`final class`	—	The client itself. Every method except `from(_:)` is `async throws` and hops off the calling thread. `from(_:)` is synchronous and throws `UNKNOWN_TABLE` eagerly, and `dispose()` is `async` but never throws. See Initializing.
`KizunaSyncClientConfig`	`struct`	—	Whole client configuration: `clientId`, `schemaVersion`, `tables`, `databasePath`, `remote`, `attachmentRoot`, `defaultLimit`, `attachmentAttempts`. `declaresAttachments` reports whether any table declares an attachment column, and `jsonObject()` and `jsonString()` produce the payload handed to the engine.
`KizunaSyncTableConfig`	`struct`	—	One synced table: `bucket` (default `.none`), `attachments`, `softDeleteColumn`, `conflictMode`, `syncMode`, and `key` (default `["id"]`, the table's primary-key columns in key order).
`KizunaSyncBucket`	`enum`	—	Which rows of a table the device pulls: `.none`, `.byOwner(String)` for a column that holds the owning user's id, which the engine fills from the session token, or `.byColumn(String)` for a column whose value the app sets with Set bucket. Default: `.none`. See Initializing.
`KizunaSyncAttachmentSpec`	`struct`	—	One attachment column: `storageBucket` and `ownerColumn`.
`KizunaSyncRemoteConfig`	`struct`	—	The PostgREST remote: `url`, `publishableKey`, `accessToken`, `schema`, and `localOnlyColumns`.
`KizunaSyncConflictMode`	`enum String`	—	`.arrival` trusts server order; `.hlc` compares the origin clock stamp `apply` attaches. Default: `.arrival`. See Initializing.
`KizunaSyncSyncMode`	`enum String`	—	`.readWrite` pulls the table and pushes its local writes; `.pullOnly` pulls it and has the engine refuse every local write with `LOCAL_UNSUPPORTED`. The raw values are the wire names `"read-write"` and `"pull-only"`. Default: `.readWrite`. See Initializing.

Writes and queries#

Name	Type	Required	Description
`KizunaSyncTable`	`final class`	—	The fluent surface of one table, returned by `KizunaSyncClient.from(_:)`: `insert(_:)`, `update(_:transforms:precondition:)`, `delete(precondition:)`, and `select(_:head:count:)`. See Insert data, Update data, and Delete data.
`KizunaSyncSelectBuilder`	`final class`	—	Fluent read over one table, returned by `KizunaSyncTable.select(_:head:count:)`. Chains every filter and builder operator in Using filters plus `order(_:ascending:nullsFirst:)`, `limit(_:)`, `range(from:to:)`, `includeDeleted()`, `stripNulls()`, and `retry(enabled:)`, then `execute()`, `single()`, `maybeSingle()`, or `csv() -> String`.
`KizunaSyncCountOption`	`enum String`	—	`.exact`, `.planned`, `.estimated`, the `count` options `select(_:head:count:)` takes. Every one returns the exact local count.
`KizunaSyncWriteBuilder`	`final class`	—	Fluent filter-targeted write, returned by `KizunaSyncTable.update(_:transforms:precondition:)` and `KizunaSyncTable.delete(precondition:)`. Chains the same filters as `KizunaSyncSelectBuilder` except `search` and `textSearch`, which stay read-only, plus `maxAffected(_:)`, then `execute() -> [String]` or `select(_:)`. See Write with filters.
`KizunaSyncWriteSelectBuilder`	`final class`	—	A write chained with `select(_:)`: `execute() -> Any` answers the rows it reached, and `single()` and `maybeSingle()` one row. Chains `stripNulls()` and `retry(enabled:)`. See Update data.
`KizunaSyncOp`	`enum String`	—	`.insert`, `.update`, `.delete`. The raw values are the wire names.
`KizunaSyncTextSearchType`	`enum String`	—	`.plain`, `.phrase`, `.websearch`, the parse modes `textSearch` accepts. Default `.plain`. See Using filters.
`KizunaSyncQuery`	`enum`	—	Static plan builders: `eq(_:_:)`, `neq(_:_:)`, `gt(_:_:)`, `gte(_:_:)`, `lt(_:_:)`, `lte(_:_:)`, `like(_:_:)`, `ilike(_:_:)`, `is(_:_:)`, `in(_:_:)`, `contains(_:_:)`, `containedBy(_:_:)`, `and(_:)`, `or(_:)`, `not(_:)`, `search(_:columns:)`, `textSearch(_:_:type:)`, `order(_:ascending:nullsFirst:)`, `plan(filters:order:limit:projection:cardinality:includeDeleted:)`, `many(filters:)`, `single(filters:)`, and `maybeSingle(filters:)`. They serialize the plan; they do not evaluate it. `is(_:_:)` takes `Bool?`, nil is the null test, and every other helper's operand is `Any`, with `NSNull()` as the explicit null value where one is accepted. See Using filters.

Kotlin's eq, neq, isValue, and inValues take Any? and accept null directly; its ordered and containment helpers (gt, gte, lt, lte, contains, containedBy) take a non-null Any, the same requirement Swift has for every operand but is.

Records the engine answers with#

Name	Type	Required	Description
`KizunaSyncCheckpoint`	`struct`	—	`cursor`, `softBlocked`, and `softBlockReason`. See Checkpoint.
`KizunaSyncRejection`	`struct`	—	`mutationId`, `table`, `pk`, `kind`, `reason`, `changedColumns`, `serverRowJson`, `at`, `dismissed`. See List rejections.
`KizunaSyncOverwrite`	`struct`	—	`id`, `table`, `pk`, `column`, `loserValueJson`, `winnerMutationId`, `conflictMode`, `winnerSeq`, `at`, `dismissed`. See List overwrites.
`KizunaSyncAttachmentStatus`	`struct`	—	`state`, `progress`, `error`, `localPath`, `permanent`, `errorCode`. `state` is `queued`, `uploading`, `downloading`, `synced`, `failed`, `orphaned`, `evicted` (this device dropped its copy and the object stays in Storage), or `missing`. `errorCode` (`String?`) is the catalog code of the last recorded failure, and nil while the row records none. See Get attachment status.
`KizunaSyncFromFileResult`	`struct`	—	`reference`, `sha256`, `size`, `mediaType`, `localPath`. See Attach a file.
`KizunaSyncEngineEvent`	`enum`	—	`.localChanged`, `.queueDepth`, `.mutationRejected`, `.batchAborted`, `.deadLetter`, `.columnOverwritten`, `.checkpointExpired`, `.resetRequired`. See Subscribe to events.

Inspector#

Name	Type	Required	Description
`KizunaSyncInspector`	`final class`	—	Devtools over one client, built and memoized by `KizunaSyncClient.inspector()`: `snapshot()`, `verdicts()`, `subscribe(_:)`, and `clear()`. See Inspect the client and Inspector.
`KizunaSyncInspectorSnapshot`	`struct`	—	`queued`, `depth`, `lastMutationId`, `cursor`, `clientId`. The same five fields `KizunaSyncClient.inspect()` answers raw.
`KizunaSyncInspectorVerdict`	`struct`	—	`mutationId`, `kind`, `reason`, `at`. One entry of the 50-entry ring.
`KizunaSyncInspectorVerdictKind`	`enum String`	—	`.rejected` for a `MUTATION_REJECTED` event, `.aborted` for a `BATCH_ABORTED` event, `.overwritten` for a `COLUMN_OVERWRITTEN` event.

Scheduling and errors#

Name	Type	Required	Description
`KizunaSyncScheduler`	`final class`	—	The host loop over one client: it takes the client, `refreshSession`, and an optional `sync` closure, and syncs at start, after every local write, on its timer, on the network path, and on the foreground signal. See Host scheduler.
`KizunaSyncWakeReason`	`enum String`	—	`.poll`, `.foreground`, `.path`, `.doorbell`, `.localWrite`, `.start`. It names the trigger of a run.
`KizunaSyncSyncPhase`	`enum String`	—	`.idle`, `.syncing`, `.backoff`, `.stalled`, `.offline`. What the loop is doing right now.
`KizunaSyncSyncHealth`	`struct`	—	`phase`, `consecutiveFailures`, `nextAttemptAt`, `attemptStartedAt`, `lastSuccessAt`, `lastError`, `needsReset`. An observable snapshot of the loop. `nextAttemptAt`, `attemptStartedAt`, and `lastSuccessAt` are `Date?`; `needsReset` is `Bool`, `false` on a scheduler built with no `needsReset` closure.
`KizunaSyncSyncHealthError`	`struct`	—	`code` (`String?`), `message`, `at` (`Date`). The failure the last attempt reported; `code` is the catalog code when the failure was a `KizunaSyncError`, and nil for anything else the `sync` closure threw.
`KizunaSyncPathMonitor`	`protocol`	—	The network-path source the scheduler gates on: `start(onSatisfied:)` and `cancel()`. See Path monitoring.
`KizunaSyncNetworkPathMonitor`	`final class`	—	The default `KizunaSyncPathMonitor`, backed by `NWPathMonitor`. `KizunaSyncScheduler` builds one when the caller passes no `pathMonitor`.
`KizunaSyncForegroundSource`	`protocol`	—	The return-to-foreground source the scheduler wakes on: `start(onForeground:)` and `stop()`. See Foreground wake.
`KizunaSyncNotificationForegroundSource`	`final class`	—	The default `KizunaSyncForegroundSource`, backed by the platform's did-become-active notification. `KizunaSyncScheduler` builds one when `observeForeground` is `true` and the caller passes no `foregroundSource`.
`KizunaSyncRealtimeSubscription`	`protocol`	—	One subscription the scheduler holds and releases: `cancel()`, idempotent.
`KizunaSyncRealtimeWakeup`	`protocol`	—	The realtime doorbell the app implements: `subscribe(topics:onWake:)`. See Realtime wake.
`KizunaSyncError`	`enum`	—	The client's own error, with the single case `.engine(code: String, message: String)`. `code` is the stable catalog code an app switches on; `description` reads `"CODE: message"`.

Notes#

KizunaSyncClient never lets the generated KizunaSyncFfiError escape: every call runs on a dedicated dispatch queue, catches it there, and rethrows KizunaSyncError.engine, whose code is the value each page's Errors table lists. It raises the same type for the checks it makes itself, such as ATTACHMENT_PORTS_MISSING in Initializing and LOCAL_UNSUPPORTED for an empty table or pk on apply. Match on code, not on description, to switch on it.

← Inspector

Found a problem? Edit this page on GitHub