Skip to content
Kizuna Sync

Docs Client library reference JavaScript

v0.2.6-alpha.3

JavaScript: Types

Every type below is exported from kizunasync and can be imported as a type. The list covers what an application annotates: the client, the config, the values methods return, and the closed unions it branches on.

Examples#

// kizunasync
import type { IKizunaSync, ISyncHealth, TKizunaSyncConfig, TOverwriteRecord, TRejectionRecord } from 'kizunasync'

The client and its options#

NameTypeRequiredDescription
IKizunaSyncinterface—The client Initializing returns, with every member listed there. Its connectivity member is the network signal the automatic loop follows: the connectivity option, else the driver's platformPorts.connectivity, else alwaysOnline. Reading it opens nothing.
IKizunaSyncOptionsinterface—The options createKizunaSync accepts, which is the Supabase composition's option set minus the members that belong to it.
IInspectorinterface—The development handle on Inspector, with IInspectorSnapshot and IInspectorVerdict for its two reads.

Config#

NameTypeRequiredDescription
TKizunaSyncConfigtype—The resolved value Define config returns.
IKizunaSyncConfigInputinterface—What that function accepts, generic over the generated Database.
ITableConfig and IResolvedTableConfiginterface—One table before and after the defaults are applied.
TBucketSpec and TBucketKindtype—What byOwner() and byColumn() return, and which of the two it is. EBucketKind is the runtime object of the same two values.
TAttachmentSpectype—What attachment() returns.
TSyncModetype—'read-write' | 'pull-only'.
TConflictModetype—'arrival' | 'hlc'.
TDatabasetype—The structural mirror of a generated supabase-js Database the config is typed against.

Queries and writes#

NameTypeRequiredDescription
ILocalFromBuilderinterface—What from(table) returns.
ILocalSelectBuilder<TRow, THead>interface—The read chain on Fetch data, generic over its row type (default TColumnValues) and over whether select() asked for head (default false). returns() and overrideTypes() change TRow; nothing changes at runtime.
ISelectOptionsinterface—The count and head options select() takes.
ISelectSingleQuery<TRow> and ISelectMaybeSingleQuery<TRow>interface—What single() and maybeSingle() return: a query evaluated only when awaited, carrying cardinality ('single' or 'maybeSingle') so a binding can pick its initial data before the read runs.
ISelectCsvQueryinterface—What csv() returns, evaluated when awaited.
ISelectResult, ISelectOneResult, ISelectMaybeOneResult, ISelectCsvResultinterface—The read envelopes, for the default await, the two one-row terminals, and csv(). Each carries count, null unless select() asked for one.
ITypeMismatchinterface—What returns() and overrideTypes() produce when the new type contradicts the result shape, such as a row type on a list. It is no query, so a mismatch fails to compile where the result is used.
ILocalWriteBuilderinterface—The filter chain on Update data and Delete data.
ILocalWriteSelectBuilder<TRow>interface—That chain after select(), which returns the rows the write reached.
ILocalInsertQuery and IInsertSelectQuery<TRow>interface—What insert() returns, a promise that also carries select(), and the query select() returns.
IWriteResult and IWriteOptionsinterface—The write envelope, with count, and the options carrying the compare-and-set mask and the count mode.
IWriteRowsResult, IWriteOneResult, IWriteMaybeOneResultinterface—The envelopes of a write chained with select(), select().single(), and select().maybeSingle().
TInsertOptionstype—The options insert() takes: count, and the supabase-js options it refuses by name.
TUpdateValuestype—An update's values map: assignments plus the sentinels on Using transforms.
TIncrementSentinel, TArrayUnionSentinel, TArrayRemoveSentineltype—What increment(), arrayUnion(), and arrayRemove() each return, listed on Using transforms.
TFieldTransformSentineltype—The union of the three sentinel types above, the value shape TUpdateValues admits beside a plain column assignment.
TContainsValuetype—The argument shape the two containment filters accept.
TColumnValue and TColumnValuestype—One stored value, including a scalar array, and a row's column map.
TLocalRow and TLocalMutationtype—A committed local row, and the write request the engine applies.
TOutboxEntrytype—One queued mutation, as Outbox depth and Inspector report it.
TQueryPlan, TQueryFilter, TQueryOrder, TQueryCompareOptype—The plan a select builder sends to the kernel: predicates, sort keys, the rows to skip (offset), a row cap, the columns to keep, the requested cardinality, and whether to count the matches, evaluated over local SQLite when the read runs.
TQueryResult and TCountedQueryResulttype—What query answers: an array for many, one row for single, a row or null for maybeSingle, and { rows, count } around it when the plan sets count.
TApplyWhereRequesttype—One filter-targeted write: the kernel resolves the rows the filters match and applies the same mutation to each in one apply_where call. maxAffected caps the rows it may reach, and returning answers those rows instead of their keys.

Sync state#

NameTypeRequiredDescription
TCheckpointStatetype—What Checkpoint returns. INITIAL_CHECKPOINT_STATE is the placeholder a binding shows before the first read resolves.
TSoftBlockReasontype—'reset_required' | 'identity_changed', why sync is soft-blocked. ESoftBlockReason is the runtime object of the same two values.
ISyncHealth, ISyncHealthError, TSyncPhasetype—What Sync health returns, and its five phases.
TBucketParamstype—The map Set bucket takes.
TCursor, TSeq, TUuid, TIsoTimestamptype—The wire scalars: the opaque cursor, a sequence value, an identifier, and a timestamp.
TEngineEventtype—The closed union Subscribe to events delivers.

Rejections, overwrites, and errors#

NameTypeRequiredDescription
TRejectionRecord and TRejectionKindtype—A journal row and its four kinds, listed on List rejections. ERejectionKind is the runtime object of the same values.
TOverwriteRecordtype—A journal row of a column a peer's write replaced, listed on List overwrites.
TRejectReasontype—The five verdict reasons, with ERejectReason as the runtime object.
TEngineErrorclass—The thrown error, carrying code and an optional detail.
TEngineErrorCodetype—Every code the engine throws, with EEngineErrorCode as the runtime object.
TTransferErrorCodetype—The non-terminal transfer outcomes, with ETransferError as the runtime object.

Ports#

NameTypeRequiredDescription
IStoreLocator, TNativeEngineLoadResult, and TStoreDurabilityinterface / type—The store locator port: the database file the Rust kernel opens, or null for a private in-memory store, implemented by Open the browser driver and Expo: Open the SQLite driver. Its optional platformPorts carries the platform's own connectivity and foreground signals, which the app client uses when the options pass none. Its optional loadNativeEngine loads the engine a React Native build links and answers a TNativeEngineLoadResult, { ok: true, handle } or { ok: false, message }. TStoreDurability is how a locator reports what an acknowledged write survives.
IEngineTransport and TEngineTransportFactoryinterface / type—The engine a locator carries directly, for a driver such as the browser worker that runs its own transport instead of only naming a file.
IProtocolRemoteinterface—The pull and push pair, implemented by Create the RPC remote.
IFileStore and IFileStoreCapabilitiesinterface—The byte sandbox, implemented by Browser file store.
IFileStatinterface—What IFileStore.stat returns: size and modifiedAt.
ITransfer, IUploadHandle, IUploadTargetinterface—The byte mover, implemented by Create the Storage transfer.
IWakeupinterface—The doorbell, implemented by Create the Realtime wakeup.
IConnectivityinterface—The network signal, implemented by Browser connectivity, which the browser driver hands over as platformPorts.connectivity. alwaysOnline is the default when neither the options nor the driver supply one.
IForegroundinterface—The app-became-visible signal. The Expo driver hands one over as platformPorts.foreground on a device, and the Supabase composition observes the document in a browser.
ILogger and ILoggerOptionsinterface—The diagnostics sink and the logging option that builds it.
TUniffiHandle and TUniffiEventObservertype—The React Native engine contract: what uniffiHandle has to implement, and what the linked Turbo Module hands the observer.

Diagnostics and utilities#

NameTypeRequiredDescription
TLogLeveltype—'debug' | 'info' | 'warn' | 'error' | 'silent', the level createConsoleLogger and the logging.level option on Initializing take.
createSha256, sha256Hex, ISha256function / interface—createSha256() returns an incremental ISha256 hasher (update, digest); sha256Hex hashes a whole ArrayBuffer or Uint8Array in one call. Both return a lowercase hex digest.
verdictToMessage, subscribeVerdictToasts, IVerdictMessage, TVerdictLevelfunction / interface / type—verdictToMessage(event) maps a rejection or dead-letter event to { level, title, message } | null; subscribeVerdictToasts wires that mapping onto kizunasync.on directly. TVerdictLevel is 'error' | 'warning'.
MISSING_CLIENT_MESSAGEconst—The exact text every binding throws when a hook or composable resolves no client, documented on React: useKizunaSync.

Attachments#

NameTypeRequiredDescription
IAttachmentClientinterface—The eight methods on kizunasync.attachments, starting at Attach a file.
TFromFileArgs and TFromFileResulttype—That method's argument and result.
TAttachmentStatus and TAttachmentStatetype—The snapshot, with permanent, attempts, and errorCode, and the seven states on Get attachment status.

Notes#

kizunasync exports the wire message types as well, including TPullRequest, TPullResponse, TPushRequest, TPushResponse, TPushBatch, TMutation, TOp, TRowChange, TSignal, TSignalType, TVerdict, TVerdictKind, TVerdictApplied, TVerdictRejected, TBatchAbort, TBatchOutcome, TBucket, and TTombstone. EOp, ESignalType, EVerdictKind, and EBatchOutcome are the runtime objects for their closed unions. The protocol schemas generate all of them, so an application that reads them couples itself to the wire rather than to the client. Protocol reference defines them.

TEngineConfig and TTableConfig are the engine config createKizunaSync derives from the value Define config returns. TTableConfig.bucketOwner is true for a byOwner table, the flag that tells the engine to fill that bucket with the store owner instead of waiting for Set bucket.

kizunasync/supabase exports its own option types beside the factories: ISupabaseKizunaSyncOptions, IRpcRemoteOptions, IRealtimeWakeupOptions, IRecoverableAuth, IRecoverAnonymousSessionOptions, and TTusUploadOptions / TTusUploadResult for Upload with TUS.

← InspectorUtilities →

Found a problem? Edit this page on GitHub