@syncular/testkit 0.8.0 → 0.10.0

package/README.md

@@ -16,15 +16,10 @@ green test here is real sync behaviour, not a fake.
 
 ## Install
 
-Workspace-internal only:
-
-```jsonc
-// package.json
-{
-  "devDependencies": {
-    "@syncular/testkit": "workspace:*"
-  }
-}
+Install it as a development dependency:
+
+```bash
+bun add --dev @syncular/testkit
 ```
 
 Requires the Bun runtime (the in-memory client backend is `bun:sqlite`). The
@@ -71,6 +66,7 @@ adds the test-only controls below.
 | `partition`     | `"test"`               | the §1.1 partition every client lives in                      |
 | `actorId`       | `"test-actor"`         | default actor a client authenticates as                       |
 | `resolveScopes` | grant-all              | host authorization (§3.2); omit to grant `'*'` for every var  |
+| `validators`    | off                    | real per-table write validators (§6.7), including structured rejection details |
 | `startMs`       | `1_750_000_000_000`    | epoch ms the shared virtual clock starts at                   |
 
 `TestSync`:
@@ -168,6 +164,41 @@ await a.sync();                     // the hub fans the commit to b as a delta
 
 `goOffline()` also drops the socket; reconnect with `connectRealtime()`.
 
+### Multi-client conflicts and correction metadata
+
+Create the common server row, let both clients pull it, then make their edits
+from the same observed version. Push one client first so the second write is a
+deterministic conflict—no timers or transport mocks are needed:
+
+```ts
+await sync.syncAll();
+const [{ version }] = a.api.query(
+  'SELECT _sync_version AS version FROM notes WHERE id = ?',
+  ['n1'],
+) as Array<{ version: number }>;
+
+a.api.patch('notes', 'n1', { body: 'A' }, { baseVersion: version });
+b.api.patch('notes', 'n1', { body: 'B' }, { baseVersion: version });
+
+await a.sync(); // wins version + 1
+await b.sync(); // loses against the stale base
+
+expect(b.api.conflicts[0]?.serverRow.body).toBe('A');
+expect(b.api.conflicts[0]?.operation?.changedFields).toEqual(['body']);
+```
+
+Pass `validators` to `createTestSync` to exercise the same business rules as
+production. A `ValidationRejection` with structured details reaches
+`client.api.rejections` through both loopback and socket sync rounds, so app
+tests can assert field focus and correction routing without displaying server
+diagnostics.
+
+Pass `commitValidator` to test aggregate invariants with the same
+transaction-scoped candidate view as production. Throw
+`CommitValidationRejection` to select the operation that correction UI should
+focus. The test server uses real SQLite transaction serialization and shares
+the callback across loopback and socket rounds.
+
 ## React
 
 `@syncular/react`'s `SyncProvider` already takes any `SyncClient`, so

package/dist/create-test-sync.d.ts

@@ -15,7 +15,7 @@
  *     await sync.dispose();
  */
 import type { ClientSchema, SyncClientConfig } from '@syncular/client';
-import type { ResolveScopes } from '@syncular/server';
+import type { CommitValidator, ResolveScopes, ValidatorRegistry } from '@syncular/server';
 import { type TestClient } from './client.js';
 import { type VirtualClock } from './clock.js';
 import { type TestServer } from './server.js';
@@ -37,6 +37,10 @@ export interface CreateTestSyncOptions {
      * in the server exactly as it would in production.
      */
     readonly resolveScopes?: ResolveScopes;
+    /** Optional §6.7 write validators, executed by the real test server. */
+    readonly validators?: ValidatorRegistry;
+    /** Optional §6.8 whole-commit validator, executed by the real test server. */
+    readonly commitValidator?: CommitValidator;
     /** Epoch ms the shared virtual clock starts at (default 1_750_000_000_000). */
     readonly startMs?: number;
 }

package/dist/create-test-sync.js

@@ -28,6 +28,12 @@ export async function createTestSync(options) {
         ...(options.resolveScopes !== undefined
             ? { resolveScopes: options.resolveScopes }
             : {}),
+        ...(options.validators !== undefined
+            ? { validators: options.validators }
+            : {}),
+        ...(options.commitValidator !== undefined
+            ? { commitValidator: options.commitValidator }
+            : {}),
     });
     const clients = [];
     let autoId = 0;

package/dist/server.d.ts

@@ -8,7 +8,7 @@
  * directly.
  */
 import { type ClientSchema } from '@syncular/client';
-import { MemorySegmentStore, type RealtimeHub, type ResolveScopes, SqliteServerStorage, type SyncRequestContext } from '@syncular/server';
+import { type CommitValidator, MemorySegmentStore, type RealtimeHub, type ResolveScopes, SqliteServerStorage, type SyncRequestContext, type ValidatorRegistry } from '@syncular/server';
 import type { VirtualClock } from './clock.js';
 /** Default partition every actor lives in (apps override via options). */
 export declare const DEFAULT_PARTITION = "test";
@@ -27,6 +27,10 @@ export interface TestServerOptions {
     readonly partition: string;
     /** Defaults to {@link allowAllScopes}. */
     readonly resolveScopes?: ResolveScopes;
+    /** Optional §6.7 validators, shared by HTTP-like and socket rounds. */
+    readonly validators?: ValidatorRegistry;
+    /** Optional §6.8 whole-commit validator, shared by both transports. */
+    readonly commitValidator?: CommitValidator;
 }
 /**
  * The server half of a test sync. `ctxFor(actorId)` builds the per-request

package/dist/server.js

@@ -45,6 +45,12 @@ export function createTestServer(options) {
         resolveScopes,
         clock: clockFn,
         segments,
+        ...(options.validators !== undefined
+            ? { validators: options.validators }
+            : {}),
+        ...(options.commitValidator !== undefined
+            ? { commitValidator: options.commitValidator }
+            : {}),
     });
     return {
         storage,
@@ -58,6 +64,12 @@ export function createTestServer(options) {
             storage,
             segments,
             resolveScopes,
+            ...(options.validators !== undefined
+                ? { validators: options.validators }
+                : {}),
+            ...(options.commitValidator !== undefined
+                ? { commitValidator: options.commitValidator }
+                : {}),
             clock: clockFn,
             realtime: hub,
         }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/testkit",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Syncular test kit: in-process loopback server + clients for integration scenarios",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -64,8 +64,8 @@
     "test": "bun test --preload ./test/setup.ts"
   },
   "dependencies": {
-    "@syncular/server": "0.8.0",
-    "@syncular/client": "0.8.0"
+    "@syncular/server": "0.10.0",
+    "@syncular/client": "0.10.0"
   },
   "peerDependencies": {
     "react": ">=18.0.0"
@@ -77,8 +77,8 @@
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^15.11.0",
-    "@syncular/core": "0.8.0",
-    "@syncular/react": "0.8.0",
+    "@syncular/core": "0.10.0",
+    "@syncular/react": "0.10.0",
     "@testing-library/react": "^16.1.0",
     "@types/react": "^18.3.0",
     "react": "^18.3.1",

package/src/create-test-sync.ts

@@ -16,7 +16,11 @@
  */
 
 import type { ClientSchema, SyncClientConfig } from '@syncular/client';
-import type { ResolveScopes } from '@syncular/server';
+import type {
+  CommitValidator,
+  ResolveScopes,
+  ValidatorRegistry,
+} from '@syncular/server';
 import { buildTestClient, type TestClient } from './client';
 import { createVirtualClock, type VirtualClock } from './clock';
 import {
@@ -44,6 +48,10 @@ export interface CreateTestSyncOptions {
    * in the server exactly as it would in production.
    */
   readonly resolveScopes?: ResolveScopes;
+  /** Optional §6.7 write validators, executed by the real test server. */
+  readonly validators?: ValidatorRegistry;
+  /** Optional §6.8 whole-commit validator, executed by the real test server. */
+  readonly commitValidator?: CommitValidator;
   /** Epoch ms the shared virtual clock starts at (default 1_750_000_000_000). */
   readonly startMs?: number;
 }
@@ -98,6 +106,12 @@ export async function createTestSync(
     ...(options.resolveScopes !== undefined
       ? { resolveScopes: options.resolveScopes }
       : {}),
+    ...(options.validators !== undefined
+      ? { validators: options.validators }
+      : {}),
+    ...(options.commitValidator !== undefined
+      ? { commitValidator: options.commitValidator }
+      : {}),
   });
 
   const clients: TestClient[] = [];

package/src/server.ts

@@ -10,6 +10,7 @@
 
 import { type ClientSchema, compileClientSchema } from '@syncular/client';
 import {
+  type CommitValidator,
   createRealtimeHub,
   MemorySegmentStore,
   type RealtimeHub,
@@ -17,6 +18,7 @@ import {
   type ServerSchema,
   SqliteServerStorage,
   type SyncRequestContext,
+  type ValidatorRegistry,
 } from '@syncular/server';
 import type { VirtualClock } from './clock';
 
@@ -50,6 +52,10 @@ export interface TestServerOptions {
   readonly partition: string;
   /** Defaults to {@link allowAllScopes}. */
   readonly resolveScopes?: ResolveScopes;
+  /** Optional §6.7 validators, shared by HTTP-like and socket rounds. */
+  readonly validators?: ValidatorRegistry;
+  /** Optional §6.8 whole-commit validator, shared by both transports. */
+  readonly commitValidator?: CommitValidator;
 }
 
 /**
@@ -79,6 +85,12 @@ export function createTestServer(options: TestServerOptions): TestServer {
     resolveScopes,
     clock: clockFn,
     segments,
+    ...(options.validators !== undefined
+      ? { validators: options.validators }
+      : {}),
+    ...(options.commitValidator !== undefined
+      ? { commitValidator: options.commitValidator }
+      : {}),
   });
   return {
     storage,
@@ -92,6 +104,12 @@ export function createTestServer(options: TestServerOptions): TestServer {
       storage,
       segments,
       resolveScopes,
+      ...(options.validators !== undefined
+        ? { validators: options.validators }
+        : {}),
+      ...(options.commitValidator !== undefined
+        ? { commitValidator: options.commitValidator }
+        : {}),
       clock: clockFn,
       realtime: hub,
     }),