@syncular/client 0.0.6-95 → 0.1.0

package/src/subscription-state.ts

@@ -1,259 +0,0 @@
-/**
- * @syncular/client - Subscription state helpers
- *
- * Stable accessors for sync subscription metadata.
- */
-
-import type { ScopeValues, SyncBootstrapState } from '@syncular/core';
-import { isRecord } from '@syncular/core';
-import type { Kysely } from 'kysely';
-import { sql } from 'kysely';
-import type {
-  SubscriptionStatus,
-  SyncClientDb,
-  SyncSubscriptionStateTable,
-} from './schema';
-
-export const DEFAULT_SYNC_STATE_ID = 'default';
-
-export interface SubscriptionState {
-  stateId: string;
-  subscriptionId: string;
-  table: string;
-  scopes: ScopeValues;
-  params: Record<string, unknown>;
-  cursor: number;
-  bootstrapState: SyncBootstrapState | null;
-  status: SubscriptionStatus;
-  createdAt: number;
-  updatedAt: number;
-}
-
-export interface ListSubscriptionStatesOptions {
-  stateId?: string;
-  table?: string;
-  status?: SubscriptionStatus;
-}
-
-export interface GetSubscriptionStateOptions {
-  stateId?: string;
-  subscriptionId: string;
-}
-
-export interface UpsertSubscriptionStateInput {
-  stateId?: string;
-  subscriptionId: string;
-  table: string;
-  scopes: ScopeValues;
-  params?: Record<string, unknown>;
-  cursor: number;
-  bootstrapState?: SyncBootstrapState | null;
-  status?: SubscriptionStatus;
-  nowMs?: number;
-}
-
-function isScopeValues(value: unknown): value is ScopeValues {
-  if (!isRecord(value)) return false;
-
-  for (const entry of Object.values(value)) {
-    if (typeof entry === 'string') continue;
-    if (Array.isArray(entry) && entry.every((v) => typeof v === 'string')) {
-      continue;
-    }
-    return false;
-  }
-
-  return true;
-}
-
-export function parseBootstrapState(
-  value: string | object | null | undefined
-): SyncBootstrapState | null {
-  if (!value) return null;
-
-  try {
-    const parsed: unknown =
-      typeof value === 'string' ? JSON.parse(value) : value;
-
-    if (!isRecord(parsed)) return null;
-    if (typeof parsed.asOfCommitSeq !== 'number') return null;
-    if (!Array.isArray(parsed.tables)) return null;
-    if (!parsed.tables.every((table) => typeof table === 'string')) return null;
-    if (typeof parsed.tableIndex !== 'number') return null;
-    if (parsed.rowCursor !== null && typeof parsed.rowCursor !== 'string') {
-      return null;
-    }
-
-    return {
-      asOfCommitSeq: parsed.asOfCommitSeq,
-      tables: parsed.tables,
-      tableIndex: parsed.tableIndex,
-      rowCursor: parsed.rowCursor,
-    };
-  } catch {
-    return null;
-  }
-}
-
-function parseScopes(value: string): ScopeValues {
-  try {
-    const parsed: unknown = JSON.parse(value);
-    return isScopeValues(parsed) ? parsed : {};
-  } catch {
-    return {};
-  }
-}
-
-function parseParams(value: string): Record<string, unknown> {
-  try {
-    const parsed: unknown = JSON.parse(value);
-    return isRecord(parsed) ? parsed : {};
-  } catch {
-    return {};
-  }
-}
-
-function mapSubscriptionState(
-  row: SyncSubscriptionStateTable
-): SubscriptionState {
-  return {
-    stateId: row.state_id,
-    subscriptionId: row.subscription_id,
-    table: row.table,
-    scopes: parseScopes(row.scopes_json),
-    params: parseParams(row.params_json),
-    cursor: row.cursor,
-    bootstrapState: parseBootstrapState(row.bootstrap_state_json),
-    status: row.status,
-    createdAt: row.created_at,
-    updatedAt: row.updated_at,
-  };
-}
-
-export async function listSubscriptionStates<DB extends SyncClientDb>(
-  db: Kysely<DB>,
-  options: ListSubscriptionStatesOptions = {}
-): Promise<SubscriptionState[]> {
-  const filters: Array<ReturnType<typeof sql>> = [];
-  if (options.stateId) {
-    filters.push(sql`${sql.ref('state_id')} = ${sql.val(options.stateId)}`);
-  }
-  if (options.table) {
-    filters.push(sql`${sql.ref('table')} = ${sql.val(options.table)}`);
-  }
-  if (options.status) {
-    filters.push(sql`${sql.ref('status')} = ${sql.val(options.status)}`);
-  }
-
-  const whereClause =
-    filters.length > 0 ? sql`where ${sql.join(filters, sql` and `)}` : sql``;
-
-  const rows = await sql<SyncSubscriptionStateTable>`
-    select
-      ${sql.ref('state_id')},
-      ${sql.ref('subscription_id')},
-      ${sql.ref('table')},
-      ${sql.ref('scopes_json')},
-      ${sql.ref('params_json')},
-      ${sql.ref('cursor')},
-      ${sql.ref('bootstrap_state_json')},
-      ${sql.ref('status')},
-      ${sql.ref('created_at')},
-      ${sql.ref('updated_at')}
-    from ${sql.table('sync_subscription_state')}
-    ${whereClause}
-    order by ${sql.ref('state_id')} asc, ${sql.ref('subscription_id')} asc
-  `.execute(db);
-
-  return rows.rows.map((row) => mapSubscriptionState(row));
-}
-
-export async function getSubscriptionState<DB extends SyncClientDb>(
-  db: Kysely<DB>,
-  options: GetSubscriptionStateOptions
-): Promise<SubscriptionState | null> {
-  const stateId = options.stateId ?? DEFAULT_SYNC_STATE_ID;
-
-  const rows = await sql<SyncSubscriptionStateTable>`
-    select
-      ${sql.ref('state_id')},
-      ${sql.ref('subscription_id')},
-      ${sql.ref('table')},
-      ${sql.ref('scopes_json')},
-      ${sql.ref('params_json')},
-      ${sql.ref('cursor')},
-      ${sql.ref('bootstrap_state_json')},
-      ${sql.ref('status')},
-      ${sql.ref('created_at')},
-      ${sql.ref('updated_at')}
-    from ${sql.table('sync_subscription_state')}
-    where
-      ${sql.ref('state_id')} = ${sql.val(stateId)}
-      and ${sql.ref('subscription_id')} = ${sql.val(options.subscriptionId)}
-    limit 1
-  `.execute(db);
-
-  const row = rows.rows[0];
-  return row ? mapSubscriptionState(row) : null;
-}
-
-export async function upsertSubscriptionState<DB extends SyncClientDb>(
-  db: Kysely<DB>,
-  input: UpsertSubscriptionStateInput
-): Promise<SubscriptionState> {
-  const now = input.nowMs ?? Date.now();
-  const stateId = input.stateId ?? DEFAULT_SYNC_STATE_ID;
-
-  const bootstrapStateJson =
-    input.bootstrapState === null || input.bootstrapState === undefined
-      ? null
-      : JSON.stringify(input.bootstrapState);
-
-  await sql`
-    insert into ${sql.table('sync_subscription_state')} (
-      ${sql.ref('state_id')},
-      ${sql.ref('subscription_id')},
-      ${sql.ref('table')},
-      ${sql.ref('scopes_json')},
-      ${sql.ref('params_json')},
-      ${sql.ref('cursor')},
-      ${sql.ref('bootstrap_state_json')},
-      ${sql.ref('status')},
-      ${sql.ref('created_at')},
-      ${sql.ref('updated_at')}
-    ) values (
-      ${sql.val(stateId)},
-      ${sql.val(input.subscriptionId)},
-      ${sql.val(input.table)},
-      ${sql.val(JSON.stringify(input.scopes ?? {}))},
-      ${sql.val(JSON.stringify(input.params ?? {}))},
-      ${sql.val(input.cursor)},
-      ${sql.val(bootstrapStateJson)},
-      ${sql.val(input.status ?? 'active')},
-      ${sql.val(now)},
-      ${sql.val(now)}
-    )
-    on conflict (${sql.join([sql.ref('state_id'), sql.ref('subscription_id')])})
-    do update set
-      ${sql.ref('table')} = ${sql.val(input.table)},
-      ${sql.ref('scopes_json')} = ${sql.val(JSON.stringify(input.scopes ?? {}))},
-      ${sql.ref('params_json')} = ${sql.val(JSON.stringify(input.params ?? {}))},
-      ${sql.ref('cursor')} = ${sql.val(input.cursor)},
-      ${sql.ref('bootstrap_state_json')} = ${sql.val(bootstrapStateJson)},
-      ${sql.ref('status')} = ${sql.val(input.status ?? 'active')},
-      ${sql.ref('updated_at')} = ${sql.val(now)}
-  `.execute(db);
-
-  const next = await getSubscriptionState(db, {
-    stateId,
-    subscriptionId: input.subscriptionId,
-  });
-
-  if (!next) {
-    throw new Error(
-      `[subscription-state] Failed to load upserted state for "${input.subscriptionId}"`
-    );
-  }
-
-  return next;
-}

package/src/sync-loop.ts

@@ -1,379 +0,0 @@
-/**
- * @syncular/client - High-level sync loops
- *
- * Helpers that run push/pull repeatedly until the client is caught up.
- */
-
-import type {
-  SyncPullResponse,
-  SyncPullSubscriptionResponse,
-  SyncPushRequest,
-  SyncPushResponse,
-  SyncSubscriptionRequest,
-  SyncTransport,
-} from '@syncular/core';
-import type { Kysely } from 'kysely';
-import { upsertConflictsForRejectedCommit } from './conflicts';
-import type { ClientHandlerCollection } from './handlers/collection';
-import {
-  getNextSendableOutboxCommit,
-  markOutboxCommitAcked,
-  markOutboxCommitFailed,
-  markOutboxCommitPending,
-} from './outbox';
-import type { SyncClientPluginContext } from './plugins/types';
-import {
-  applyPullResponse,
-  buildPullRequest,
-  createFollowupPullState,
-  type SyncPullOnceOptions,
-  type SyncPullRequestState,
-  syncPullOnce,
-} from './pull-engine';
-import { type SyncPushOnceOptions, syncPushOnce } from './push-engine';
-import type { SyncClientDb } from './schema';
-
-interface SyncPushUntilSettledOptions extends SyncPushOnceOptions {
-  /** Max outbox commits to attempt per call. Default: 20 */
-  maxCommits?: number;
-}
-
-interface SyncPushUntilSettledResult {
-  pushedCount: number;
-}
-
-async function syncPushUntilSettled<DB extends SyncClientDb>(
-  db: Kysely<DB>,
-  transport: SyncTransport,
-  options: SyncPushUntilSettledOptions
-): Promise<SyncPushUntilSettledResult> {
-  const maxCommits = Math.max(1, Math.min(1000, options.maxCommits ?? 20));
-
-  let pushedCount = 0;
-  for (let i = 0; i < maxCommits; i++) {
-    const res = await syncPushOnce(db, transport, {
-      clientId: options.clientId,
-      actorId: options.actorId,
-      plugins: options.plugins,
-    });
-    if (!res.pushed) break;
-    pushedCount += 1;
-  }
-
-  return { pushedCount };
-}
-
-interface SyncPullUntilSettledOptions extends SyncPullOnceOptions {
-  /** Max pull rounds per call. Default: 20 */
-  maxRounds?: number;
-  /** Optional prebuilt state from a prior pull round in the same sync cycle. */
-  initialPullState?: SyncPullRequestState;
-}
-
-interface SyncPullUntilSettledResult {
-  response: SyncPullResponse;
-  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;
-    if (sub.bootstrap) return true;
-    if ((sub.commits?.length ?? 0) > 0) return true;
-  }
-  return false;
-}
-
-function mergePullResponse(
-  targetBySubId: Map<string, SyncPullSubscriptionResponse>,
-  res: SyncPullResponse
-): void {
-  for (const sub of res.subscriptions ?? []) {
-    const prev = targetBySubId.get(sub.id);
-    if (!prev) {
-      const merged: SyncPullSubscriptionResponse = {
-        ...sub,
-        commits: [...(sub.commits ?? [])],
-        snapshots: [...(sub.snapshots ?? [])],
-      };
-      targetBySubId.set(sub.id, merged);
-      continue;
-    }
-
-    const merged: SyncPullSubscriptionResponse = {
-      ...prev,
-      ...sub,
-      commits: [...(prev.commits ?? []), ...(sub.commits ?? [])],
-      snapshots: [...(prev.snapshots ?? []), ...(sub.snapshots ?? [])],
-    };
-    targetBySubId.set(sub.id, merged);
-  }
-}
-
-async function syncPullUntilSettled<DB extends SyncClientDb>(
-  db: Kysely<DB>,
-  transport: SyncTransport,
-  handlers: ClientHandlerCollection<DB>,
-  options: SyncPullUntilSettledOptions
-): Promise<SyncPullUntilSettledResult> {
-  const maxRounds = Math.max(1, Math.min(1000, options.maxRounds ?? 20));
-
-  const aggregatedBySubId = new Map<string, SyncPullSubscriptionResponse>();
-  let pullState =
-    options.initialPullState ?? (await buildPullRequest(db, options));
-  let rounds = 0;
-
-  for (let i = 0; i < maxRounds; i++) {
-    rounds += 1;
-    const res = await syncPullOnce(db, transport, handlers, options, pullState);
-    mergePullResponse(aggregatedBySubId, res);
-
-    if (!needsAnotherPull(res)) break;
-    pullState = createFollowupPullState(pullState, res);
-  }
-
-  return {
-    // Return an aggregate response so callers can see what was applied across
-    // all pull rounds (the last round is often empty by design).
-    response: {
-      ok: true,
-      subscriptions: Array.from(aggregatedBySubId.values()),
-    },
-    rounds,
-  };
-}
-
-export interface SyncOnceOptions {
-  clientId: string;
-  actorId?: string;
-  plugins?: SyncPushOnceOptions['plugins'];
-  subscriptions: Array<Omit<SyncSubscriptionRequest, 'cursor'>>;
-  limitCommits?: number;
-  limitSnapshotRows?: number;
-  maxSnapshotPages?: number;
-  dedupeRows?: boolean;
-  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 {
-  pushedCommits: number;
-  pullRounds: number;
-  pullResponse: SyncPullResponse;
-}
-
-/**
- * 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,
-  handlers: ClientHandlerCollection<DB>,
-  options: SyncOnceOptions
-): Promise<SyncOnceResult> {
-  const pullOpts: SyncPullOnceOptions = {
-    clientId: options.clientId,
-    actorId: options.actorId,
-    plugins: options.plugins,
-    subscriptions: options.subscriptions,
-    limitCommits: options.limitCommits,
-    limitSnapshotRows: options.limitSnapshotRows,
-    maxSnapshotPages: options.maxSnapshotPages,
-    dedupeRows: options.dedupeRows,
-    stateId: options.stateId,
-    sha256: options.sha256,
-  };
-
-  // 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,
-        initialPullState: createFollowupPullState(pullState, pullResponse),
-      });
-      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: ClientHandlerCollection<DB>,
-  options: SyncOnceOptions
-): Promise<SyncOnceResult> {
-  return syncOnceCombined(db, transport, handlers, options);
-}