@syncular/testkit 0.1.3 → 0.2.0

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@syncular/testkit",
-  "version": "0.1.3",
-  "description": "Testing fixtures and utilities for Syncular",
+  "version": "0.2.0",
+  "description": "Syncular test kit: in-process loopback server + clients for integration scenarios",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
   "homepage": "https://syncular.dev",
   "repository": {
     "type": "git",
     "url": "https://github.com/syncular/syncular.git",
-    "directory": "packages/testkit"
+    "directory": "packages/testing"
   },
   "bugs": {
     "url": "https://github.com/syncular/syncular/issues"
@@ -16,88 +16,72 @@
   "keywords": [
     "sync",
     "offline-first",
-    "testing",
-    "testkit",
+    "realtime",
+    "database",
     "typescript"
   ],
-  "private": false,
+  "type": "module",
+  "sideEffects": false,
   "publishConfig": {
     "access": "public"
   },
-  "type": "module",
   "exports": {
     ".": {
       "bun": "./src/index.ts",
+      "browser": "./src/index.ts",
       "import": {
         "types": "./dist/index.d.ts",
         "default": "./dist/index.js"
       }
     },
-    "./client-bridge": {
-      "bun": "./src/client-bridge.ts",
+    "./react": {
+      "bun": "./src/react.ts",
+      "browser": "./src/react.ts",
       "import": {
-        "types": "./dist/client-bridge.d.ts",
-        "default": "./dist/client-bridge.js"
+        "types": "./dist/react.d.ts",
+        "default": "./dist/react.js"
       }
     },
-    "./server": {
-      "bun": "./src/server.ts",
+    "./faults": {
+      "bun": "./src/faults.ts",
+      "browser": "./src/faults.ts",
       "import": {
-        "types": "./dist/server.d.ts",
-        "default": "./dist/server.js"
+        "types": "./dist/faults.d.ts",
+        "default": "./dist/faults.js"
       }
     }
   },
-  "scripts": {
-    "test": "bun test --pass-with-no-tests",
-    "tsgo": "tsgo --noEmit",
-    "build": "tsgo",
-    "release": "syncular-publish"
-  },
-  "dependencies": {
-    "@syncular/core": "0.1.3"
-  },
-  "peerDependencies": {
-    "@electric-sql/pglite": "^0.3.15",
-    "@syncular/client": "0.1.3",
-    "@syncular/server": "0.1.3",
-    "hono": "^4.12.15",
-    "kysely": "^0.28.0"
-  },
-  "devDependencies": {
-    "@electric-sql/pglite": "^0.3.15",
-    "@syncular/client": "0.1.3",
-    "@syncular/config": "0.0.0",
-    "@syncular/server": "0.1.3",
-    "hono": "^4.12.15",
-    "kysely": "*"
-  },
   "files": [
     "dist",
     "src",
+    "README.md",
     "!src/**/*.test.ts",
     "!src/**/*.test.tsx",
-    "!src/**/__tests__/**",
-    "!dist/**/*.test.*",
-    "!dist/**/__tests__/**",
-    "!test/**",
-    "!tests/**"
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts"
   ],
+  "scripts": {
+    "test": "bun test --preload ./test/setup.ts"
+  },
+  "dependencies": {
+    "@syncular/server": "0.2.0",
+    "@syncular/client": "0.2.0"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
   "peerDependenciesMeta": {
-    "@electric-sql/pglite": {
-      "optional": true
-    },
-    "@syncular/client": {
-      "optional": true
-    },
-    "@syncular/server": {
-      "optional": true
-    },
-    "hono": {
-      "optional": true
-    },
-    "kysely": {
+    "react": {
       "optional": true
     }
+  },
+  "devDependencies": {
+    "@happy-dom/global-registrator": "^15.11.0",
+    "@syncular/core": "0.2.0",
+    "@syncular/react": "0.2.0",
+    "@testing-library/react": "^16.1.0",
+    "@types/react": "^18.3.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
   }
 }

package/src/client.ts

@@ -0,0 +1,218 @@
+/**
+ * The client half of a test sync: a real `SyncClient` on bun:sqlite wired
+ * to the {@link TestServer} through an in-process loopback seam. No HTTP —
+ * the transport calls `handleSyncRequest` directly, the segment downloader
+ * calls `handleSegmentDownload`, and (when realtime is on) the connector
+ * attaches a `RealtimeSession` to the hub. Every hop passes through a fault
+ * gate so an app test can drop / duplicate / corrupt individual exchanges,
+ * and an offline flag that makes every hop reject like a lost network.
+ *
+ * The fault controller is the conformance harness's `TransportFaults`,
+ * re-exported (see `index.ts`) — the SAME vocabulary the reference pairing
+ * arms, not a parallel one.
+ */
+
+import {
+  type ClientSchema,
+  type RealtimeConnector,
+  type SegmentDownloader,
+  type SegmentFetchRequest,
+  SyncClient,
+  type SyncClientConfig,
+  type SyncTransport,
+} from '@syncular/client';
+import { BunClientDatabase } from '@syncular/client/bun';
+import { handleSegmentDownload, handleSyncRequest } from '@syncular/server';
+import type { VirtualClock } from './clock';
+import { seededRandom, TransportFault, TransportFaults } from './faults';
+import type { TestServer } from './server';
+
+/** A client-facing offline error: rejects a hop the way a dead network does. */
+class OfflineError extends Error {
+  override readonly name = 'OfflineError';
+  readonly code = 'sync.transport_failed';
+  readonly retryable = true;
+  constructor() {
+    super('injected: client is offline');
+  }
+}
+
+/**
+ * A test client. Everything an app test needs to script a scenario:
+ * the real `SyncClient` (`api`, or spread it — see the getters), the fault
+ * controller, and the connectivity toggle.
+ */
+export interface TestClient {
+  /** The stable client id (§1.5). */
+  readonly id: string;
+  /** The actor this client authenticates as (§1.1). */
+  readonly actorId: string;
+  /** The underlying `SyncClient` — the full shipped client API. */
+  readonly api: SyncClient;
+  /** Transport-seam faults: drop / duplicate / corrupt the next exchange. */
+  readonly faults: TransportFaults;
+  /** True while the client is offline (every hop rejects). */
+  readonly offline: boolean;
+  /** Cut the network: sync / segment / realtime hops reject until online. */
+  goOffline(): void;
+  /** Restore the network. Does NOT auto-sync — call `sync()` yourself. */
+  goOnline(): void;
+  /** Push the outbox and pull to quiescence (`SyncClient.syncUntilIdle`). */
+  sync(): Promise<void>;
+  /** Attach a realtime socket to the hub (deltas, presence, socket rounds). */
+  connectRealtime(): Promise<void>;
+  /** Detach the realtime socket. */
+  disconnectRealtime(): void;
+  /** Close the client and its database. */
+  close(): Promise<void>;
+}
+
+export interface TestClientOptions {
+  readonly server: TestServer;
+  readonly schema: ClientSchema;
+  readonly clock: VirtualClock;
+  readonly id: string;
+  readonly actorId: string;
+  /**
+   * Extra `SyncClient` config merged over the loopback defaults — e.g.
+   * `onConflict`, `limits`. `database`, `schema`, `clientId`, `now`,
+   * `transport`, `segments`, and `realtime` are owned by the kit.
+   */
+  readonly clientConfig?: Partial<
+    Omit<
+      SyncClientConfig,
+      | 'database'
+      | 'schema'
+      | 'clientId'
+      | 'now'
+      | 'transport'
+      | 'segments'
+      | 'realtime'
+    >
+  >;
+}
+
+/**
+ * Build a `TestClient`. The client is NOT started — the caller (or
+ * `createTestSync`) awaits `api.start()`. Split out so `createTestSync` can
+ * construct and start in one place.
+ */
+export function buildTestClient(options: TestClientOptions): {
+  client: TestClient;
+  start: () => Promise<void>;
+} {
+  const { server, schema, clock, id, actorId } = options;
+  const db = new BunClientDatabase();
+  const faults = new TransportFaults(seededRandom(hashSeed(id)));
+  const state = { offline: false };
+  const ctx = () => server.ctxFor(actorId);
+
+  const transport: SyncTransport = async (request) => {
+    if (state.offline) throw new OfflineError();
+    if (faults.dropNextRequests > 0) {
+      faults.dropNextRequests -= 1;
+      throw new TransportFault('injected: request lost');
+    }
+    if (faults.duplicateNextRequest) {
+      faults.duplicateNextRequest = false;
+      // First delivery is processed by the server; its response is discarded
+      // (the §6 idempotency cache absorbs the replay on the second delivery).
+      await handleSyncRequest(request, ctx());
+    }
+    const bytes = await handleSyncRequest(request, ctx());
+    if (faults.dropNextResponses > 0) {
+      faults.dropNextResponses -= 1;
+      throw new TransportFault('injected: response lost');
+    }
+    if (faults.truncateNextResponse) {
+      faults.truncateNextResponse = false;
+      return faults.truncate(bytes);
+    }
+    return bytes;
+  };
+
+  const segments: SegmentDownloader = async (request: SegmentFetchRequest) => {
+    if (state.offline) throw new OfflineError();
+    if (faults.dropNextSegmentRequests > 0) {
+      faults.dropNextSegmentRequests -= 1;
+      throw new TransportFault('injected: segment request lost');
+    }
+    const result = await handleSegmentDownload(ctx(), {
+      segmentId: request.segmentId,
+      scopesHeader: request.requestedScopesJson,
+    });
+    if (faults.truncateNextSegmentDownload) {
+      faults.truncateNextSegmentDownload = false;
+      return faults.truncate(result.bytes);
+    }
+    return result.bytes;
+  };
+
+  const realtime: RealtimeConnector = async (handlers) => {
+    if (state.offline) throw new OfflineError();
+    const session = await server.hub.connect({
+      partition: server.partition,
+      actorId,
+      clientId: id,
+      send: (data) => {
+        if (typeof data === 'string') handlers.onText(data);
+        else handlers.onBinary(data);
+      },
+    });
+    return {
+      send: (text) => session.handleMessage(text),
+      sendBytes: (bytes) => session.handleBinary(bytes),
+      close: () => {
+        session.close();
+        handlers.onClose?.();
+      },
+    };
+  };
+
+  const api = new SyncClient({
+    database: db,
+    schema,
+    clientId: id,
+    now: () => clock.now(),
+    transport,
+    segments,
+    realtime,
+    ...options.clientConfig,
+  });
+
+  const client: TestClient = {
+    id,
+    actorId,
+    api,
+    faults,
+    get offline() {
+      return state.offline;
+    },
+    goOffline: () => {
+      state.offline = true;
+      api.disconnectRealtime();
+    },
+    goOnline: () => {
+      state.offline = false;
+    },
+    sync: async () => {
+      await api.syncUntilIdle();
+    },
+    connectRealtime: () => api.connectRealtime(),
+    disconnectRealtime: () => api.disconnectRealtime(),
+    close: () => api.close(),
+  };
+
+  return { client, start: () => api.start() };
+}
+
+/** Deterministic per-client fault seed from the client id (mirrors the
+ * conformance harness's per-scenario seeding). */
+function hashSeed(name: string): number {
+  let hash = 2166136261;
+  for (let i = 0; i < name.length; i++) {
+    hash ^= name.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return hash >>> 0;
+}

package/src/clock.ts

@@ -0,0 +1,45 @@
+/**
+ * A virtual clock the whole test sync shares — server, every client, and
+ * the realtime hub read the same `now()`. Time only moves when the test
+ * moves it, so §5.1 TTLs, §5.4 signed-URL expiry, and §7.3 lease windows
+ * are exercised deterministically with no wall-clock flake.
+ *
+ * This is deliberately NOT a fake-timers shim: it does not intercept
+ * `setTimeout`. It is the single epoch-ms source that Syncular's clock seam
+ * (`SyncServerConfig.clock`, `SyncClientConfig.now`) reads. Presence rate
+ * caps and heartbeats, which use real `setTimeout`, are out of scope — the
+ * kit targets sync/offline/fault behaviour, not wall-clock scheduling.
+ */
+
+/** The default epoch (ms) a fresh clock starts at — a fixed, readable point
+ * so golden values and TTL maths are stable across runs. */
+export const DEFAULT_EPOCH_MS = 1_750_000_000_000;
+
+export interface VirtualClock {
+  /** Current time in epoch ms — the value the clock seam returns. */
+  now(): number;
+  /** Move time forward by `ms` (must be ≥ 0). Returns the new `now()`. */
+  advance(ms: number): number;
+  /** Jump to an absolute epoch-ms instant. Returns the new `now()`. */
+  set(ms: number): number;
+}
+
+export function createVirtualClock(startMs = DEFAULT_EPOCH_MS): VirtualClock {
+  let ms = startMs;
+  return {
+    now: () => ms,
+    advance: (delta) => {
+      if (delta < 0) {
+        throw new Error(
+          `clock.advance: time cannot move backwards (${delta}ms)`,
+        );
+      }
+      ms += delta;
+      return ms;
+    },
+    set: (next) => {
+      ms = next;
+      return ms;
+    },
+  };
+}

package/src/create-test-sync.ts

@@ -0,0 +1,158 @@
+/**
+ * `createTestSync` — the one call an app test makes. It stands up an
+ * in-memory Syncular backend and hands back a factory for N real clients,
+ * all sharing one virtual clock, all talking to the server through an
+ * in-process loopback (no HTTP unless you ask). Everything is the SHIPPED
+ * core; the kit is wiring, not a mock.
+ *
+ *     const sync = await createTestSync({ schema });
+ *     const a = await sync.client('a');
+ *     const b = await sync.client('b');
+ *     a.api.subscribe({ id: 's', table: 'notes', scopes: { list_id: ['x'] } });
+ *     b.api.subscribe({ id: 's', table: 'notes', scopes: { list_id: ['x'] } });
+ *     a.api.mutate([{ table: 'notes', op: 'upsert', values: … }]);
+ *     await sync.syncAll();           // both converge
+ *     await sync.dispose();
+ */
+
+import type { ClientSchema, SyncClientConfig } from '@syncular/client';
+import type { ResolveScopes } from '@syncular/server';
+import { buildTestClient, type TestClient } from './client';
+import { createVirtualClock, type VirtualClock } from './clock';
+import {
+  createTestServer,
+  DEFAULT_ACTOR,
+  DEFAULT_PARTITION,
+  type TestServer,
+} from './server';
+
+export interface CreateTestSyncOptions {
+  /**
+   * The generated schema (`syncular.generated.ts`'s `schema`, or any
+   * `ClientSchema`). The same object feeds the server and every client — a
+   * single-version, matched-schema world, which is what an app test wants.
+   */
+  readonly schema: ClientSchema;
+  /** Partition every client lives in (§1.1); defaults to `"test"`. */
+  readonly partition?: string;
+  /** Default actor a client authenticates as; defaults to `"test-actor"`. */
+  readonly actorId?: string;
+  /**
+   * Host authorization (§3.2 step 3). Omit for "grant everything" — the
+   * default resolver returns `'*'` for every scope variable the schema
+   * declares. Provide your own to test scope-scoping / revocation; it runs
+   * in the server exactly as it would in production.
+   */
+  readonly resolveScopes?: ResolveScopes;
+  /** Epoch ms the shared virtual clock starts at (default 1_750_000_000_000). */
+  readonly startMs?: number;
+}
+
+export interface TestClientOverrides {
+  /** Actor id for this client (defaults to the sync-wide actor). */
+  readonly actorId?: string;
+  /** Extra `SyncClient` config (e.g. `onConflict`, `limits`). */
+  readonly clientConfig?: Partial<
+    Omit<
+      SyncClientConfig,
+      | 'database'
+      | 'schema'
+      | 'clientId'
+      | 'now'
+      | 'transport'
+      | 'segments'
+      | 'realtime'
+    >
+  >;
+}
+
+export interface TestSync {
+  /** The shared virtual clock — server + every client read it. */
+  readonly clock: VirtualClock;
+  /** The in-memory server (storage / segments / realtime hub). */
+  readonly server: TestServer;
+  /** Every client created so far, in creation order. */
+  readonly clients: readonly TestClient[];
+  /**
+   * Create and start one client. `id` is its stable client id (§1.5);
+   * omit for an auto-generated one. Returns once `start()` has run, so the
+   * client is ready to `subscribe` / `mutate` immediately.
+   */
+  client(id?: string, overrides?: TestClientOverrides): Promise<TestClient>;
+  /** `syncUntilIdle` on every online client — the "let them converge" step. */
+  syncAll(): Promise<void>;
+  /** Close every client and the server. Idempotent. */
+  dispose(): Promise<void>;
+}
+
+export async function createTestSync(
+  options: CreateTestSyncOptions,
+): Promise<TestSync> {
+  const partition = options.partition ?? DEFAULT_PARTITION;
+  const defaultActor = options.actorId ?? DEFAULT_ACTOR;
+  const clock = createVirtualClock(options.startMs);
+  const server = createTestServer({
+    schema: options.schema,
+    clock,
+    partition,
+    ...(options.resolveScopes !== undefined
+      ? { resolveScopes: options.resolveScopes }
+      : {}),
+  });
+
+  const clients: TestClient[] = [];
+  let autoId = 0;
+  let disposed = false;
+
+  const sync: TestSync = {
+    clock,
+    server,
+    clients,
+    client: async (id, overrides) => {
+      const clientId = id ?? `client-${++autoId}`;
+      const { client, start } = buildTestClient({
+        server,
+        schema: options.schema,
+        clock,
+        id: clientId,
+        actorId: overrides?.actorId ?? defaultActor,
+        ...(overrides?.clientConfig !== undefined
+          ? { clientConfig: overrides.clientConfig }
+          : {}),
+      });
+      await start();
+      clients.push(client);
+      return client;
+    },
+    syncAll: async () => {
+      // Sequential, not parallel: the reference server serializes anyway, and
+      // sequential rounds make cross-client convergence order deterministic.
+      // Repeat until no online client still has pending commits — one pass of
+      // A's push may be another's pull.
+      for (let pass = 0; pass < 20; pass++) {
+        let progressed = false;
+        for (const client of clients) {
+          if (client.offline) continue;
+          const before = client.api.pendingCommits().length;
+          await client.sync();
+          if (before > 0) progressed = true;
+        }
+        if (!progressed) return;
+      }
+    },
+    dispose: async () => {
+      if (disposed) return;
+      disposed = true;
+      for (const client of clients) {
+        try {
+          await client.close();
+        } catch {
+          // best-effort teardown; keep closing the rest
+        }
+      }
+      server.close();
+    },
+  };
+
+  return sync;
+}