@syncular/client 0.0.1 → 0.0.2-126

package/src/query/tracked-select.ts

@@ -10,7 +10,7 @@ import type { Kysely } from 'kysely';
 import type { FingerprintCollector } from './FingerprintCollector';
 
 /** Portable type alias for Kysely's selectFrom method signature */
-export type TrackedSelectFrom<DB> = Kysely<DB>['selectFrom'];
+type TrackedSelectFrom<DB> = Kysely<DB>['selectFrom'];
 
 import {
   computeRowFingerprint,

package/src/schema.ts

@@ -26,8 +26,8 @@ export interface SyncSubscriptionStateTable {
   state_id: string;
   /** Subscription identifier (client-chosen) */
   subscription_id: string;
-  /** Shape name (table) for this subscription */
-  shape: string;
+  /** Table name for this subscription */
+  table: string;
   /** JSON string of ScopeValues for this subscription */
   scopes_json: string;
   /** JSON string of params */

package/src/sync-loop.ts

@@ -7,12 +7,27 @@
 import type {
   SyncPullResponse,
   SyncPullSubscriptionResponse,
+  SyncPushRequest,
+  SyncPushResponse,
   SyncSubscriptionRequest,
   SyncTransport,
 } from '@syncular/core';
 import type { Kysely } from 'kysely';
+import { upsertConflictsForRejectedCommit } from './conflicts';
 import type { ClientTableRegistry } from './handlers/registry';
-import { type SyncPullOnceOptions, syncPullOnce } from './pull-engine';
+import {
+  getNextSendableOutboxCommit,
+  markOutboxCommitAcked,
+  markOutboxCommitFailed,
+  markOutboxCommitPending,
+} from './outbox';
+import type { SyncClientPluginContext } from './plugins/types';
+import {
+  applyPullResponse,
+  buildPullRequest,
+  type SyncPullOnceOptions,
+  syncPullOnce,
+} from './pull-engine';
 import { type SyncPushOnceOptions, syncPushOnce } from './push-engine';
 import type { SyncClientDb } from './schema';
 
@@ -56,6 +71,16 @@ interface SyncPullUntilSettledResult {
   rounds: number;
 }
 
+interface TransportWithWsPush extends SyncTransport {
+  pushViaWs(request: SyncPushRequest): Promise<SyncPushResponse | null>;
+}
+
+function hasPushViaWs(
+  transport: SyncTransport
+): transport is TransportWithWsPush {
+  return 'pushViaWs' in transport && typeof transport.pushViaWs === 'function';
+}
+
 function needsAnotherPull(res: SyncPullResponse): boolean {
   for (const sub of res.subscriptions ?? []) {
     if (sub.status !== 'active') continue;
@@ -94,7 +119,7 @@ function mergePullResponse(
 async function syncPullUntilSettled<DB extends SyncClientDb>(
   db: Kysely<DB>,
   transport: SyncTransport,
-  shapes: ClientTableRegistry<DB>,
+  handlers: ClientTableRegistry<DB>,
   options: SyncPullUntilSettledOptions
 ): Promise<SyncPullUntilSettledResult> {
   const maxRounds = Math.max(1, Math.min(1000, options.maxRounds ?? 20));
@@ -104,7 +129,7 @@ async function syncPullUntilSettled<DB extends SyncClientDb>(
 
   for (let i = 0; i < maxRounds; i++) {
     rounds += 1;
-    const res = await syncPullOnce(db, transport, shapes, options);
+    const res = await syncPullOnce(db, transport, handlers, options);
     mergePullResponse(aggregatedBySubId, res);
 
     if (!needsAnotherPull(res)) break;
@@ -133,6 +158,10 @@ export interface SyncOnceOptions {
   stateId?: string;
   maxPushCommits?: number;
   maxPullRounds?: number;
+  /** When 'ws', peek outbox first and skip push if empty. */
+  trigger?: 'ws' | 'local' | 'poll';
+  /** Custom SHA-256 hash function (for platforms without crypto.subtle) */
+  sha256?: (bytes: Uint8Array) => Promise<string>;
 }
 
 export interface SyncOnceResult {
@@ -141,20 +170,22 @@ export interface SyncOnceResult {
   pullResponse: SyncPullResponse;
 }
 
-export async function syncOnce<DB extends SyncClientDb>(
+/**
+ * Sync once using a WS-first push strategy for the first outbox commit.
+ *
+ * - If transport supports `pushViaWs` and the commit succeeds over WS, this call
+ *   sends only an HTTP pull request.
+ * - Otherwise it falls back to combined HTTP push+pull.
+ *
+ * Remaining outbox commits are then settled via `syncPushUntilSettled`.
+ */
+async function syncOnceCombined<DB extends SyncClientDb>(
   db: Kysely<DB>,
   transport: SyncTransport,
-  shapes: ClientTableRegistry<DB>,
+  handlers: ClientTableRegistry<DB>,
   options: SyncOnceOptions
 ): Promise<SyncOnceResult> {
-  const pushed = await syncPushUntilSettled(db, transport, {
-    clientId: options.clientId,
-    actorId: options.actorId,
-    plugins: options.plugins,
-    maxCommits: options.maxPushCommits,
-  });
-
-  const pulled = await syncPullUntilSettled(db, transport, shapes, {
+  const pullOpts: SyncPullOnceOptions = {
     clientId: options.clientId,
     actorId: options.actorId,
     plugins: options.plugins,
@@ -164,12 +195,177 @@ export async function syncOnce<DB extends SyncClientDb>(
     maxSnapshotPages: options.maxSnapshotPages,
     dedupeRows: options.dedupeRows,
     stateId: options.stateId,
-    maxRounds: options.maxPullRounds,
-  });
+    sha256: options.sha256,
+  };
 
-  return {
-    pushedCommits: pushed.pushedCount,
-    pullRounds: pulled.rounds,
-    pullResponse: pulled.response,
+  // Build pull request (reads subscription state)
+  const pullState = await buildPullRequest(db, pullOpts);
+  const { clientId } = pullState.request;
+
+  // Grab at most one outbox commit
+  const outbox = await getNextSendableOutboxCommit(db);
+
+  const plugins = options.plugins ?? [];
+  const ctx: SyncClientPluginContext = {
+    actorId: options.actorId ?? 'unknown',
+    clientId,
   };
+
+  // Build push request, running beforePush plugins
+  let pushRequest: SyncPushRequest | undefined;
+  if (outbox) {
+    pushRequest = {
+      clientId,
+      clientCommitId: outbox.client_commit_id,
+      operations: outbox.operations,
+      schemaVersion: outbox.schema_version,
+    };
+    for (const plugin of plugins) {
+      if (!plugin.beforePush) continue;
+      pushRequest = await plugin.beforePush(ctx, pushRequest);
+    }
+  }
+
+  // Try WS push first for the first outbox commit (if realtime transport supports it).
+  // Fall back to HTTP push in the combined request when WS is unavailable or fails.
+  let wsPushResponse: SyncPushResponse | null = null;
+  if (pushRequest && hasPushViaWs(transport)) {
+    try {
+      wsPushResponse = await transport.pushViaWs(pushRequest);
+    } catch {
+      wsPushResponse = null;
+    }
+  }
+
+  const combined = await transport.sync({
+    clientId,
+    ...(pushRequest && !wsPushResponse
+      ? {
+          push: {
+            clientCommitId: pushRequest.clientCommitId,
+            operations: pushRequest.operations,
+            schemaVersion: pushRequest.schemaVersion,
+          },
+        }
+      : {}),
+    pull: {
+      limitCommits: pullState.request.limitCommits,
+      limitSnapshotRows: pullState.request.limitSnapshotRows,
+      maxSnapshotPages: pullState.request.maxSnapshotPages,
+      dedupeRows: pullState.request.dedupeRows,
+      subscriptions: pullState.request.subscriptions,
+    },
+  });
+
+  // Process push response
+  let pushedCommits = 0;
+  if (outbox && pushRequest) {
+    let pushRes = wsPushResponse ?? combined.push;
+    if (!pushRes) {
+      await markOutboxCommitPending(db, {
+        id: outbox.id,
+        error: 'MISSING_PUSH_RESPONSE',
+      });
+      throw new Error('Server returned no push response');
+    }
+
+    // Run afterPush plugins
+    for (const plugin of plugins) {
+      if (!plugin.afterPush) continue;
+      pushRes = await plugin.afterPush(ctx, {
+        request: pushRequest,
+        response: pushRes,
+      });
+    }
+
+    const responseJson = JSON.stringify(pushRes);
+
+    if (pushRes.status === 'applied' || pushRes.status === 'cached') {
+      await markOutboxCommitAcked(db, {
+        id: outbox.id,
+        commitSeq: pushRes.commitSeq ?? null,
+        responseJson,
+      });
+      pushedCommits = 1;
+    } else {
+      // Check if all errors are retriable
+      const errorResults = pushRes.results.filter((r) => r.status === 'error');
+      const allRetriable =
+        errorResults.length > 0 &&
+        errorResults.every((r) => r.retriable === true);
+
+      if (allRetriable) {
+        await markOutboxCommitPending(db, {
+          id: outbox.id,
+          error: 'Retriable',
+          responseJson,
+        });
+        pushedCommits = 1;
+      } else {
+        await upsertConflictsForRejectedCommit(db, {
+          outboxCommitId: outbox.id,
+          clientCommitId: outbox.client_commit_id,
+          response: pushRes,
+        });
+        await markOutboxCommitFailed(db, {
+          id: outbox.id,
+          error: 'REJECTED',
+          responseJson,
+        });
+        pushedCommits = 1;
+      }
+    }
+
+    // Settle remaining outbox commits
+    const remaining = await syncPushUntilSettled(db, transport, {
+      clientId: options.clientId,
+      actorId: options.actorId,
+      plugins: options.plugins,
+      maxCommits: (options.maxPushCommits ?? 20) - 1,
+    });
+    pushedCommits += remaining.pushedCount;
+  }
+
+  // Process pull response
+  let pullResponse: SyncPullResponse = { ok: true, subscriptions: [] };
+  let pullRounds = 0;
+  if (combined.pull) {
+    pullResponse = await applyPullResponse(
+      db,
+      transport,
+      handlers,
+      pullOpts,
+      pullState,
+      combined.pull
+    );
+    pullRounds = 1;
+
+    // Continue pulling if more data
+    if (needsAnotherPull(pullResponse)) {
+      const aggregatedBySubId = new Map<string, SyncPullSubscriptionResponse>();
+      mergePullResponse(aggregatedBySubId, pullResponse);
+
+      const more = await syncPullUntilSettled(db, transport, handlers, {
+        ...pullOpts,
+        maxRounds: (options.maxPullRounds ?? 20) - 1,
+      });
+      pullRounds += more.rounds;
+      mergePullResponse(aggregatedBySubId, more.response);
+      pullResponse = {
+        ok: true,
+        subscriptions: Array.from(aggregatedBySubId.values()),
+      };
+    }
+  }
+
+  return { pushedCommits, pullRounds, pullResponse };
+}
+
+export async function syncOnce<DB extends SyncClientDb>(
+  db: Kysely<DB>,
+  transport: SyncTransport,
+  handlers: ClientTableRegistry<DB>,
+  options: SyncOnceOptions
+): Promise<SyncOnceResult> {
+  return syncOnceCombined(db, transport, handlers, options);
 }