@syncular/client 0.1.3 → 0.2.1

package/src/bridge-client.ts

@@ -1,512 +0,0 @@
-import {
-  randomId,
-  type SyncAuthLeaseIssueRequest,
-  type SyncOperation,
-} from '@syncular/core';
-import {
-  type CompiledQuery,
-  type DatabaseConnection,
-  type Dialect,
-  Kysely,
-  type QueryResult,
-} from 'kysely';
-import { BaseSqliteDialect, BaseSqliteDriver } from 'kysely-generic-sqlite';
-import type {
-  SyncularBlobClientLike,
-  SyncularClientLike,
-  SyncularClientStatus,
-} from './client';
-import {
-  createMutationsApi,
-  type MutationReceipt,
-  type MutationsApi,
-  type MutationsCommitFn,
-  type MutationsTx,
-} from './mutations';
-import { assertSyncularReadonlySql } from './sql-safety';
-import type {
-  SyncularAuthLeaseRecord,
-  SyncularClientEventSink,
-  SyncularClientEventType,
-  SyncularConflictResolution,
-  SyncularConflictStats,
-  SyncularConflictSummary,
-  SyncularConnectionState,
-  SyncularDiagnosticSnapshot,
-  SyncularLifecycleState,
-  SyncularOutboxStats,
-  SyncularPresenceEntry,
-  SyncularPresenceSink,
-  SyncularSubscriptionSpec,
-  SyncularSyncRequestOptions,
-  SyncularSyncResult,
-} from './types';
-
-export interface SyncularBridgeQueryRequest {
-  sql: string;
-  parameters: readonly unknown[];
-}
-
-export interface SyncularBridgeQueryResult<
-  Row extends Record<string, unknown> = Record<string, unknown>,
-> {
-  rows: Row[];
-  numAffectedRows?: bigint | number | string;
-  insertId?: bigint | number | string | null;
-}
-
-export interface SyncularBridgeMutationBatch {
-  operations: SyncOperation[];
-}
-
-export interface SyncularBridgeStatus {
-  lifecycle?: SyncularLifecycleState;
-  connection?: SyncularConnectionState;
-  outbox?: SyncularOutboxStats | null;
-  conflicts?: SyncularConflictStats | null;
-}
-
-export interface SyncularBridgePresence {
-  get<TMetadata = Record<string, unknown>>(
-    scopeKey: string
-  ): SyncularPresenceEntry<TMetadata>[];
-  join(scopeKey: string, metadata?: Record<string, unknown>): void;
-  leave(scopeKey: string): void;
-  updateMetadata(scopeKey: string, metadata: Record<string, unknown>): void;
-  onChange<TMetadata = Record<string, unknown>>(
-    listener: SyncularPresenceSink<TMetadata>
-  ): () => void;
-}
-
-export interface SyncularBridgeConflicts {
-  list(): Promise<SyncularConflictSummary[]>;
-  retryKeepLocal(id: string): Promise<string>;
-  resolve(id: string, resolution: SyncularConflictResolution): Promise<void>;
-}
-
-export interface SyncularBridge {
-  open?(): Promise<void> | void;
-  close?(): Promise<void> | void;
-  executeSql<Row extends Record<string, unknown> = Record<string, unknown>>(
-    request: SyncularBridgeQueryRequest
-  ): Promise<SyncularBridgeQueryResult<Row>> | SyncularBridgeQueryResult<Row>;
-  applyMutationsCommit(
-    batch: SyncularBridgeMutationBatch
-  ): Promise<string | MutationReceipt> | string | MutationReceipt;
-  applyLeasedMutationsCommit?(
-    batch: SyncularBridgeMutationBatch
-  ): Promise<string | MutationReceipt> | string | MutationReceipt;
-  sync?(): Promise<SyncularSyncResult>;
-  resumeFromBackground?(
-    options?: SyncularSyncRequestOptions
-  ): Promise<SyncularSyncResult>;
-  start?(): Promise<void>;
-  stop?(): Promise<void>;
-  setSubscriptions?(
-    subscriptions: readonly SyncularSubscriptionSpec[]
-  ): Promise<void>;
-  getStatus?(): Promise<SyncularBridgeStatus> | SyncularBridgeStatus;
-  issueAuthLease?(
-    request: SyncAuthLeaseIssueRequest
-  ): Promise<SyncularAuthLeaseRecord>;
-  upsertAuthLease?(lease: SyncularAuthLeaseRecord): Promise<void>;
-  authLease?(leaseId: string): Promise<SyncularAuthLeaseRecord | null>;
-  activeAuthLeases?(
-    actorId?: string | null,
-    nowMs?: number
-  ): Promise<SyncularAuthLeaseRecord[]>;
-  diagnosticSnapshot?(): Promise<SyncularDiagnosticSnapshot>;
-  on?<T extends SyncularClientEventType>(
-    event: T,
-    listener: SyncularClientEventSink<T>
-  ): () => void;
-  presence?: SyncularBridgePresence;
-  conflicts?: SyncularBridgeConflicts;
-  blobs?: Partial<SyncularBlobClientLike>;
-}
-
-export interface CreateSyncularBridgeClientOptions {
-  bridge: SyncularBridge;
-  sync?: {
-    autoSyncAfterMutation?: boolean;
-  };
-  idColumn?: string;
-  versionColumn?: string | null;
-  omitColumns?: readonly string[];
-}
-
-export function createSyncularBridgeDialect(bridge: SyncularBridge): Dialect {
-  return new BaseSqliteDialect(() => new SyncularBridgeDriver(bridge));
-}
-
-export async function createSyncularBridgeClient<DB>(
-  options: CreateSyncularBridgeClientOptions
-): Promise<SyncularClientLike<DB>> {
-  await options.bridge.open?.();
-  const dialect = createSyncularBridgeDialect(options.bridge);
-  const db = new Kysely<DB>({ dialect });
-  let closed = false;
-  const syncAfterMutation = options.sync?.autoSyncAfterMutation !== false;
-
-  const client: SyncularClientLike<DB> = {
-    db,
-    dialect,
-    mutations: createSyncularBridgeMutations<DB>(options, async () => {
-      if (syncAfterMutation) await client.sync().catch(() => undefined);
-    }),
-    leasedMutations: createSyncularBridgeMutations<DB>(
-      options,
-      async () => {
-        if (syncAfterMutation) await client.sync().catch(() => undefined);
-      },
-      { leased: true }
-    ),
-    blobs: createBridgeBlobs(options.bridge),
-    on: (event, listener) => options.bridge.on?.(event, listener) ?? noop,
-    getStatus: () => resolveBridgeStatusSnapshot(options.bridge),
-    setSubscriptions: async (subscriptions) => {
-      await options.bridge.setSubscriptions?.(subscriptions);
-    },
-    resumeFromBackground: (syncOptions) =>
-      requireBridgeMethod(
-        options.bridge.resumeFromBackground,
-        'resumeFromBackground'
-      )(syncOptions),
-    issueAuthLease: (request) =>
-      requireBridgeMethod(
-        options.bridge.issueAuthLease,
-        'issueAuthLease'
-      )(request),
-    upsertAuthLease: (lease) =>
-      requireBridgeMethod(
-        options.bridge.upsertAuthLease,
-        'upsertAuthLease'
-      )(lease),
-    authLease: (leaseId) =>
-      requireBridgeMethod(options.bridge.authLease, 'authLease')(leaseId),
-    activeAuthLeases: (actorId, nowMs) =>
-      requireBridgeMethod(options.bridge.activeAuthLeases, 'activeAuthLeases')(
-        actorId,
-        nowMs
-      ),
-    diagnosticSnapshot: () =>
-      requireBridgeMethod(
-        options.bridge.diagnosticSnapshot,
-        'diagnosticSnapshot'
-      )(),
-    presence: createBridgePresence(options.bridge),
-    conflicts: createBridgeConflicts(options.bridge),
-    start: async () => {
-      await options.bridge.start?.();
-    },
-    stop: async () => {
-      await options.bridge.stop?.();
-    },
-    sync: async () => {
-      if (!options.bridge.sync) {
-        throw new Error('Syncular bridge does not implement sync().');
-      }
-      return await options.bridge.sync();
-    },
-    async close() {
-      if (closed) return;
-      closed = true;
-      await options.bridge.stop?.();
-      await db.destroy();
-      await options.bridge.close?.();
-    },
-  };
-
-  return client;
-}
-
-function createSyncularBridgeMutations<DB>(
-  options: CreateSyncularBridgeClientOptions,
-  afterCommit: () => Promise<void>,
-  mode: { leased?: boolean } = {}
-): MutationsApi<DB, undefined> {
-  const commit = createSyncularBridgeCommit<DB>(options, afterCommit, mode);
-  return createMutationsApi(commit);
-}
-
-function createSyncularBridgeCommit<DB>(
-  options: CreateSyncularBridgeClientOptions,
-  afterCommit: () => Promise<void>,
-  mode: { leased?: boolean } = {}
-): MutationsCommitFn<DB, { operations: SyncOperation[] }, undefined> {
-  const idColumn = options.idColumn ?? 'id';
-  const versionColumn = options.versionColumn ?? 'server_version';
-  const omitColumns = options.omitColumns ?? [];
-
-  return async (fn) => {
-    const operations: SyncOperation[] = [];
-    const makeTxTable = (table: string) => ({
-      async insert(values: unknown) {
-        const raw = objectRecord(values);
-        const id =
-          typeof raw[idColumn] === 'string' && raw[idColumn]
-            ? raw[idColumn]
-            : randomId();
-        operations.push({
-          table,
-          row_id: id,
-          op: 'upsert',
-          payload: sanitizeOperationPayload({ ...raw, [idColumn]: id }, [
-            idColumn,
-            ...(versionColumn ? [versionColumn] : []),
-            ...omitColumns,
-          ]),
-          base_version: null,
-        });
-        return id;
-      },
-      async insertMany(rows: unknown[]) {
-        const ids: string[] = [];
-        for (const row of rows) ids.push(await this.insert(row));
-        return ids;
-      },
-      async update(
-        id: string,
-        patch: unknown,
-        opts?: { baseVersion?: number | null }
-      ) {
-        operations.push(upsertOperation(table, id, patch, opts));
-      },
-      async delete(id: string, opts?: { baseVersion?: number | null }) {
-        operations.push({
-          table,
-          row_id: id,
-          op: 'delete',
-          payload: null,
-          base_version: opts?.baseVersion ?? null,
-        });
-      },
-      async upsert(
-        id: string,
-        patch: unknown,
-        opts?: { baseVersion?: number | null }
-      ) {
-        operations.push(upsertOperation(table, id, patch, opts));
-      },
-    });
-
-    const tx = new Proxy(
-      {},
-      {
-        get(_target, prop) {
-          if (prop === 'then') return undefined;
-          return typeof prop === 'string' ? makeTxTable(prop) : undefined;
-        },
-      }
-    ) as MutationsTx<DB>;
-
-    const result = await fn(tx);
-    if (operations.length === 0) throw new Error('No mutations were enqueued');
-    const commitFn = mode.leased
-      ? requireBridgeMethod(
-          options.bridge.applyLeasedMutationsCommit,
-          'applyLeasedMutationsCommit'
-        )
-      : options.bridge.applyMutationsCommit.bind(options.bridge);
-    const receipt = normalizeMutationReceipt(await commitFn({ operations }));
-    await afterCommit();
-    return { result, receipt, meta: { operations } };
-  };
-
-  function upsertOperation(
-    table: string,
-    id: string,
-    patch: unknown,
-    opts?: { baseVersion?: number | null }
-  ): SyncOperation {
-    return {
-      table,
-      row_id: id,
-      op: 'upsert',
-      payload: sanitizeOperationPayload(objectRecord(patch), [
-        idColumn,
-        ...(versionColumn ? [versionColumn] : []),
-        ...omitColumns,
-      ]),
-      base_version: opts?.baseVersion ?? null,
-    };
-  }
-}
-
-class SyncularBridgeDriver extends BaseSqliteDriver {
-  constructor(bridge: SyncularBridge) {
-    super(async () => {
-      this.conn = new SyncularBridgeConnection(bridge);
-    });
-  }
-
-  async destroy(): Promise<void> {
-    this.conn = undefined;
-  }
-}
-
-class SyncularBridgeConnection implements DatabaseConnection {
-  constructor(private readonly bridge: SyncularBridge) {}
-
-  async executeQuery<R>(compiledQuery: CompiledQuery): Promise<QueryResult<R>> {
-    assertSyncularReadonlySql(compiledQuery.sql);
-    const result = await this.bridge.executeSql<R & Record<string, unknown>>({
-      sql: compiledQuery.sql,
-      parameters: compiledQuery.parameters,
-    });
-    return {
-      rows: result.rows as R[],
-      numAffectedRows:
-        result.numAffectedRows == null
-          ? undefined
-          : BigInt(result.numAffectedRows),
-      insertId: result.insertId == null ? undefined : BigInt(result.insertId),
-    };
-  }
-
-  streamQuery<R>(
-    _compiledQuery: CompiledQuery,
-    _chunkSize?: number
-  ): AsyncIterableIterator<QueryResult<R>> {
-    throw new Error('Syncular bridge dialect does not support streaming.');
-  }
-}
-
-function createBridgePresence(bridge: SyncularBridge): SyncularBridgePresence {
-  return (
-    bridge.presence ?? {
-      get: () => [],
-      join: unsupportedFn('presence.join'),
-      leave: unsupportedFn('presence.leave'),
-      updateMetadata: unsupportedFn('presence.updateMetadata'),
-      onChange: () => noop,
-    }
-  );
-}
-
-function createBridgeConflicts(
-  bridge: SyncularBridge
-): SyncularBridgeConflicts {
-  return (
-    bridge.conflicts ?? {
-      list: async () => [],
-      retryKeepLocal: unsupportedFn('conflicts.retryKeepLocal'),
-      resolve: unsupportedFn('conflicts.resolve'),
-    }
-  );
-}
-
-function createBridgeBlobs(bridge: SyncularBridge): SyncularBlobClientLike {
-  return {
-    getUploadQueueStats: async () =>
-      bridge.blobs?.getUploadQueueStats?.() ?? {
-        pending: 0,
-        uploading: 0,
-        failed: 0,
-      },
-    processUploadQueue: async (options) =>
-      bridge.blobs?.processUploadQueue?.(options) ?? { uploaded: 0, failed: 0 },
-    retrieve:
-      bridge.blobs?.retrieve ??
-      (async () => {
-        throw new Error('Syncular bridge does not implement blob retrieval.');
-      }),
-  };
-}
-
-function resolveBridgeStatusSnapshot(
-  bridge: SyncularBridge
-): SyncularClientStatus {
-  const snapshot = readSynchronousStatus(bridge);
-  const connection = snapshot.connection ?? {
-    closed: false,
-    pendingRequests: 0,
-    realtime: 'disconnected',
-  };
-  const lifecycle = snapshot.lifecycle ?? {
-    phase: connection.closed ? 'closed' : 'offline',
-    realtime: connection.realtime,
-    online: connection.realtime === 'connected',
-    requiresAction: false,
-    pendingRequests: connection.pendingRequests,
-    ...(snapshot.outbox ? { outbox: snapshot.outbox } : {}),
-    ...(snapshot.conflicts ? { conflicts: snapshot.conflicts } : {}),
-  };
-  const outbox = snapshot.outbox ?? lifecycle.outbox ?? null;
-  const conflicts = snapshot.conflicts ?? lifecycle.conflicts ?? null;
-  return {
-    lifecycle,
-    connection,
-    outbox,
-    conflicts,
-    isConnected: connection.realtime === 'connected' && !connection.closed,
-    isSyncing:
-      lifecycle.phase === 'syncing' || lifecycle.phase === 'recovering',
-    hasPendingMutations: (outbox?.pending ?? 0) + (outbox?.sending ?? 0) > 0,
-    hasConflicts: (conflicts?.unresolved ?? 0) > 0,
-    requiresAction: lifecycle.requiresAction,
-  };
-}
-
-function readSynchronousStatus(bridge: SyncularBridge): SyncularBridgeStatus {
-  if (!bridge.getStatus) return {};
-  const snapshot = bridge.getStatus();
-  if (isPromiseLike(snapshot)) {
-    throw new Error(
-      'Syncular bridge getStatus() must be synchronous for React snapshots.'
-    );
-  }
-  return snapshot;
-}
-
-function normalizeMutationReceipt(
-  value: string | MutationReceipt
-): MutationReceipt {
-  if (typeof value === 'string')
-    return { commitId: value, clientCommitId: value };
-  return value;
-}
-
-function sanitizeOperationPayload(
-  payload: Record<string, unknown>,
-  omitColumns: readonly string[]
-): Record<string, unknown> {
-  const omit = new Set(omitColumns);
-  const out: Record<string, unknown> = {};
-  for (const [key, value] of Object.entries(payload)) {
-    if (!omit.has(key)) out[key] = value;
-  }
-  return out;
-}
-
-function objectRecord(value: unknown): Record<string, unknown> {
-  return value && typeof value === 'object' && !Array.isArray(value)
-    ? { ...(value as Record<string, unknown>) }
-    : {};
-}
-
-function unsupportedFn<Args extends unknown[], Result>(
-  method: string
-): (...args: Args) => Result {
-  return () => {
-    throw new Error(`Syncular bridge does not implement ${method}.`);
-  };
-}
-
-function requireBridgeMethod<Fn extends (...args: any[]) => any>(
-  fn: Fn | undefined,
-  method: string
-): Fn {
-  if (typeof fn === 'function') return fn;
-  return unsupportedFn(method) as Fn;
-}
-
-function isPromiseLike(value: unknown): value is Promise<unknown> {
-  return (
-    value != null &&
-    typeof value === 'object' &&
-    typeof (value as { then?: unknown }).then === 'function'
-  );
-}
-
-function noop(): void {}

package/src/client-config.ts

@@ -1,29 +0,0 @@
-import type {
-  ResolvedSyncularClientConfig,
-  SyncularClientConfig,
-  SyncularStorage,
-} from './types';
-
-export const SYNCULAR_DEFAULT_STORAGE = 'opfsSahPool' satisfies SyncularStorage;
-export const SYNCULAR_LOCAL_DISABLED_BASE_URL = 'syncular-local://disabled';
-
-export function resolveSyncularClientConfig(
-  config: SyncularClientConfig
-): ResolvedSyncularClientConfig {
-  const mode = config.mode ?? 'remote';
-  if (mode === 'remote' && !config.baseUrl) {
-    throw new Error('Syncular remote clients require config.baseUrl');
-  }
-  return {
-    ...config,
-    mode,
-    baseUrl: config.baseUrl ?? SYNCULAR_LOCAL_DISABLED_BASE_URL,
-    storage: config.storage ?? SYNCULAR_DEFAULT_STORAGE,
-  };
-}
-
-export function isSyncularRemoteMode(
-  config: Pick<ResolvedSyncularClientConfig, 'mode'>
-): boolean {
-  return config.mode === 'remote';
-}