@syncular/client 0.4.0 → 0.5.0

package/README.md

@@ -73,9 +73,9 @@ it holds the lock, spawns the worker, and runs the core (the single-tab
 path, unchanged — the lock IS the exactly-one-core invariant, and a worker
 is *never* spawned without it). Every other tab is a **follower**: it opens
 a `BroadcastChannel` to the leader and proxies the whole logical API over
-it (`req`/`res`), while the leader fans its worker events —
-invalidate / presence / conflict / sync-needed / synced / upgrading — out
-to all followers (`event`). Queries forward to the leader's one DB; rows
+it (`req`/`res`), while the leader fans its worker events — exact revisioned
+change batches plus presence / conflict / sync-needed / synced / upgrading —
+out to all followers (`event`). Queries forward to the leader's one DB; rows
 (including `bytes` columns) ride back through structured clone.
 
 **Promotion.** When the leader tab closes, its lock releases. Followers are
@@ -224,7 +224,7 @@ any divergence from the contract.
 `init`, `call`, `ready`, `result`, `error`, `event` — every API method
 multiplexes over `call` (typed end-to-end from the single `WorkerApi`
 shape in `worker-protocol.ts`); `event` carries `sync-needed`,
-`conflict` and `synced`. Query-result blobs transfer (not copy) when
+`change`, `conflict` and `synced`. Query-result blobs transfer (not copy) when
 they own their buffer.
 
 ## Package layout

package/dist/apply.d.ts

@@ -7,6 +7,8 @@ import { type CommitFrame, type RowsSegment, type RowValue, type ScopeMap } from
 import type { ClientDatabase } from './database.js';
 import type { EncryptionConfig } from './encryption.js';
 import { type CompiledClientSchema, type CompiledClientTable } from './schema.js';
+/** Lets the client wrap the physical write in its revision transaction. */
+export type ApplyTransaction = <T>(fn: () => T) => T;
 export declare function upsertLocalRow(db: ClientDatabase, table: CompiledClientTable, values: readonly RowValue[], syncVersion: number): void;
 export declare function deleteLocalRow(db: ClientDatabase, table: CompiledClientTable, rowId: string): void;
 /**
@@ -21,7 +23,7 @@ export declare function deleteLocalRow(db: ClientDatabase, table: CompiledClient
  * (`client.decrypt_failed`) aborts before any local write, so the commit
  * never half-applies.
  */
-export declare function applyCommitFrame(db: ClientDatabase, schema: CompiledClientSchema, frame: CommitFrame, encryption?: EncryptionConfig): Promise<void>;
+export declare function applyCommitFrame(db: ClientDatabase, schema: CompiledClientSchema, frame: CommitFrame, encryption?: EncryptionConfig, transaction?: ApplyTransaction): Promise<void>;
 /**
  * §5.2: the segment's column table must match the generated schema for
  * (table, schemaVersion) — order, names, types, nullability. A mismatch is
@@ -65,6 +67,7 @@ export interface SqliteSegmentDescriptor {
 export declare function applySqliteSegment(db: ClientDatabase, schema: CompiledClientSchema, table: CompiledClientTable, bytes: Uint8Array, descriptor: SqliteSegmentDescriptor, options: {
     readonly clearFirst: boolean;
     readonly effective: ScopeMap;
+    readonly transaction?: ApplyTransaction;
 }): number;
 /**
  * Apply a decoded rows segment: each block in one local transaction
@@ -77,4 +80,5 @@ export declare function applySqliteSegment(db: ClientDatabase, schema: CompiledC
 export declare function applyRowsSegment(db: ClientDatabase, schema: CompiledClientSchema, table: CompiledClientTable, segment: RowsSegment, options: {
     readonly clearFirst: boolean;
     readonly effective: ScopeMap;
+    readonly transaction?: ApplyTransaction;
 }, encryption?: EncryptionConfig): Promise<number>;

package/dist/apply.js

@@ -32,7 +32,7 @@ export function deleteLocalRow(db, table, rowId) {
  * (`client.decrypt_failed`) aborts before any local write, so the commit
  * never half-applies.
  */
-export async function applyCommitFrame(db, schema, frame, encryption) {
+export async function applyCommitFrame(db, schema, frame, encryption, transaction = (fn) => db.transaction(fn)) {
     const resolved = [];
     for (const change of frame.changes) {
         const tableName = frame.tables[change.tableIndex];
@@ -62,7 +62,7 @@ export async function applyCommitFrame(db, schema, frame, encryption) {
             rowVersion: change.rowVersion,
         });
     }
-    db.transaction(() => {
+    transaction(() => {
         for (const change of resolved) {
             if (change.op === 'delete') {
                 deleteLocalRow(db, change.table, change.rowId);
@@ -241,7 +241,7 @@ export function applySqliteSegment(db, schema, table, bytes, descriptor, options
         }
         // 3. One transaction: fresh-bootstrap clear, then replace-or-upsert.
         const names = table.columns.map((column) => quoteIdent(column.name));
-        return db.transaction(() => {
+        return (options.transaction ?? ((fn) => db.transaction(fn)))(() => {
             if (options.clearFirst) {
                 deleteScopedRows(db, table, options.effective);
             }
@@ -287,7 +287,9 @@ export async function applyRowsSegment(db, schema, table, segment, options, encr
         }
         const clearThisBlock = first && options.clearFirst;
         first = false;
-        db.transaction(() => {
+        if (!clearThisBlock && rows.length === 0)
+            continue;
+        (options.transaction ?? ((fn) => db.transaction(fn)))(() => {
             if (clearThisBlock) {
                 deleteScopedRows(db, table, options.effective);
             }

package/dist/client.d.ts

@@ -11,7 +11,7 @@ import { type RowValue, type ScopeMap, type WakeReason } from '@syncular/core';
 import { type BlobRef, type BlobTransport, type CachedBlob } from './blob.js';
 import type { ClientDatabase, SqlRow, SqlValue } from './database.js';
 import type { EncryptionConfig } from './encryption.js';
-import { type InvalidationListener } from './invalidation.js';
+import { type ClientChangeListener, type CommandResult, type InvalidationListener, type LocalRevision, type SyncIntent, type SyncStatusSnapshot } from './invalidation.js';
 import { type LeaderLock } from './leader-lock.js';
 import { type OutboxCommit, type OutboxOperation } from './outbox.js';
 import { type ClientSchema } from './schema.js';
@@ -136,7 +136,10 @@ export interface SyncClientConfig {
     readonly limits?: SyncClientLimits;
     readonly now?: () => number;
     /** §8: hello `requiresSync` or a wake-up — run a pull soon. */
-    readonly onSyncNeeded?: (reason: 'hello' | WakeReason) => void;
+    readonly onSyncNeeded?: (reason: 'startup' | 'hello' | WakeReason) => void;
+    /** Exact core-owned scheduling intent. Hosts consume this to run an
+     * event-driven retry deadline without polling or inferring sync state. */
+    readonly onSyncIntent?: (intent: SyncIntent) => void;
     readonly onConflict?: (conflict: ConflictRecord) => void;
     /**
      * §7.4.5: the schema-bump `upgrading` state changed. `true` when a reset
@@ -191,6 +194,30 @@ export interface WindowState {
      */
     readonly pending: readonly string[];
 }
+/** One generated/raw query's required window units (SPEC §7.5). */
+export interface WindowCoverage {
+    readonly base: WindowBase;
+    readonly units: readonly string[];
+}
+export interface WindowUnitRef {
+    readonly baseKey: string;
+    readonly unit: string;
+}
+export interface CoverageSnapshot {
+    readonly complete: boolean;
+    readonly pending: readonly WindowUnitRef[];
+    readonly missing: readonly WindowUnitRef[];
+}
+export interface QueryReadSpec {
+    readonly sql: string;
+    readonly params?: readonly SqlValue[];
+    readonly coverage?: readonly WindowCoverage[];
+}
+export interface QuerySnapshot<Row = SqlRow> {
+    readonly revision: LocalRevision;
+    readonly rows: readonly Row[];
+    readonly coverage: CoverageSnapshot;
+}
 /**
  * True iff `unit` is windowed-in AND its bootstrap completed (§4.8 I3):
  * registered and not pending. A unit with zero server rows still becomes
@@ -215,6 +242,14 @@ export declare class SyncClient {
      * internals read `this.#db` directly and skip this method by design.
      */
     query(sql: string, params?: readonly SqlValue[]): SqlRow[];
+    /** Current durable local observer revision (SPEC §7.5). */
+    get localRevision(): LocalRevision;
+    /**
+     * Read rows, window answerability, and revision from one SQLite snapshot.
+     * Reactive integrations use this instead of composing `query()` and
+     * `windowState()` across separate worker/IPC calls.
+     */
+    querySnapshot<Row = SqlRow>(spec: QueryReadSpec): QuerySnapshot<Row>;
     /**
      * Subscribe to fine-grained invalidation. The callback fires ONCE per
      * apply batch (never per row, I1) with the `{tables, scopeKeys}` touched
@@ -227,6 +262,10 @@ export declare class SyncClient {
      * per-row scopes (COMMIT changes) or a scope map (segments/purge).
      */
     onInvalidate(listener: InvalidationListener): () => void;
+    /** Subscribe to exact revisioned observer transactions (SPEC §7.5). */
+    onChange(listener: ClientChangeListener): () => void;
+    /** One call for the complete status domain used by reactive hosts. */
+    statusSnapshot(): SyncStatusSnapshot;
     /**
      * Stage a blob for attachment (§5.9.7): hash the bytes into the content
      * address, cache them locally, and queue the upload (flushed before the
@@ -315,6 +354,8 @@ export declare class SyncClient {
      * re-registers realtime at round end (§8.7). No socket cycle needed.
      */
     setWindow(base: WindowBase, units: readonly string[]): Promise<void>;
+    /** Exact core command result consumed by automatic host loops (§7.5). */
+    setWindowCommand(base: WindowBase, units: readonly string[]): Promise<CommandResult<void>>;
     /**
      * The completeness oracle (§4.8 I3): which units of a base are windowed-in
      * locally, which of those are still bootstrap-pending, and thereby the
@@ -332,6 +373,8 @@ export declare class SyncClient {
      * Returns the generated `clientCommitId`.
      */
     mutate(mutations: readonly MutationInput[]): string;
+    /** Host-facing mutation result with explicit network work intent (§7.5). */
+    mutateCommand(mutations: readonly MutationInput[]): CommandResult<string>;
     /**
      * Partial-update convenience over the §6.1 full-row wire: read the
      * current LOCAL row, merge `partial` over it, and record one full-row
@@ -343,6 +386,10 @@ export declare class SyncClient {
     patch(table: string, rowId: string, partial: Readonly<Record<string, unknown>>, options?: {
         readonly baseVersion?: number;
     }): string;
+    /** Host-facing patch result with explicit network work intent (§7.5). */
+    patchCommand(table: string, rowId: string, partial: Readonly<Record<string, unknown>>, options?: {
+        readonly baseVersion?: number;
+    }): CommandResult<string>;
     /**
      * One combined push+pull round (§1.5, §7.2). The core owns one loop: a
      * concurrent `sync()` while one is already outstanding is rejected loudly