@syncular/testkit 0.0.2-135 → 0.0.2-137

package/src/scenario-flow.ts

@@ -0,0 +1,143 @@
+import {
+  type ClientTableRegistry,
+  enqueueOutboxCommit,
+  type SyncClientDb,
+  type SyncOnceOptions,
+  type SyncOnceResult,
+  type SyncPullOnceOptions,
+  type SyncPullResponse,
+  type SyncPushOnceOptions,
+  type SyncPushOnceResult,
+  syncOnce,
+  syncPullOnce,
+  syncPushOnce,
+} from '@syncular/client';
+import type {
+  SyncCombinedRequest,
+  SyncCombinedResponse,
+  SyncTransport,
+} from '@syncular/core';
+import type { Kysely } from 'kysely';
+
+export interface ScenarioFlowClient<DB extends SyncClientDb> {
+  db: Kysely<DB>;
+  transport: SyncTransport;
+  handlers: ClientTableRegistry<DB>;
+  clientId: string;
+  actorId?: string;
+}
+
+export interface PushThenPullOptions<DB extends SyncClientDb> {
+  enqueue?: Parameters<typeof enqueueOutboxCommit<DB>>[1];
+  push?: Omit<SyncPushOnceOptions, 'clientId' | 'actorId'>;
+  pull: Omit<SyncPullOnceOptions, 'clientId' | 'actorId'>;
+}
+
+export interface PushThenPullResult<DB extends SyncClientDb> {
+  enqueueResult?: { id: string; clientCommitId: string };
+  pushResult: SyncPushOnceResult;
+  pullResult: SyncPullResponse;
+  client: ScenarioFlowClient<DB>;
+}
+
+export interface ScenarioFlow<DB extends SyncClientDb> {
+  client: ScenarioFlowClient<DB>;
+  enqueue: (
+    args: Parameters<typeof enqueueOutboxCommit<DB>>[1]
+  ) => Promise<{ id: string; clientCommitId: string }>;
+  push: (
+    options?: Omit<SyncPushOnceOptions, 'clientId' | 'actorId'>
+  ) => Promise<SyncPushOnceResult>;
+  pull: (
+    options: Omit<SyncPullOnceOptions, 'clientId' | 'actorId'>
+  ) => Promise<SyncPullResponse>;
+  sync: (
+    options: Omit<SyncOnceOptions, 'clientId' | 'actorId'>
+  ) => Promise<SyncOnceResult>;
+  transportSync: (
+    request: Omit<SyncCombinedRequest, 'clientId'>
+  ) => Promise<SyncCombinedResponse>;
+  pushThenPull: (
+    options: PushThenPullOptions<DB>
+  ) => Promise<PushThenPullResult<DB>>;
+}
+
+function withClientIdentity<
+  DB extends SyncClientDb,
+  T extends Record<string, unknown>,
+>(
+  values: T,
+  client: ScenarioFlowClient<DB>
+): T & { clientId: string; actorId?: string } {
+  return {
+    ...values,
+    clientId: client.clientId,
+    ...(client.actorId ? { actorId: client.actorId } : {}),
+  };
+}
+
+export function createScenarioFlow<DB extends SyncClientDb>(
+  client: ScenarioFlowClient<DB>
+): ScenarioFlow<DB> {
+  const enqueue: ScenarioFlow<DB>['enqueue'] = (args) =>
+    enqueueOutboxCommit(client.db, args);
+
+  const push: ScenarioFlow<DB>['push'] = (options) =>
+    syncPushOnce(
+      client.db,
+      client.transport,
+      withClientIdentity(options ?? {}, client)
+    );
+
+  const pull: ScenarioFlow<DB>['pull'] = (options) =>
+    syncPullOnce(
+      client.db,
+      client.transport,
+      client.handlers,
+      withClientIdentity(options, client)
+    );
+
+  const sync: ScenarioFlow<DB>['sync'] = (options) =>
+    syncOnce(
+      client.db,
+      client.transport,
+      client.handlers,
+      withClientIdentity(options, client)
+    );
+
+  const transportSync: ScenarioFlow<DB>['transportSync'] = (request) =>
+    client.transport.sync({ clientId: client.clientId, ...request });
+
+  const pushThenPull: ScenarioFlow<DB>['pushThenPull'] = async (options) => {
+    const enqueueResult = options.enqueue
+      ? await enqueueOutboxCommit(client.db, options.enqueue)
+      : undefined;
+
+    const pushResult = await push(options.push);
+    const pullResult = await pull(options.pull);
+
+    return {
+      enqueueResult,
+      pushResult,
+      pullResult,
+      client,
+    };
+  };
+
+  return {
+    client,
+    enqueue,
+    push,
+    pull,
+    sync,
+    transportSync,
+    pushThenPull,
+  };
+}
+
+export async function runPushPullCycle<DB extends SyncClientDb>(
+  client: ScenarioFlowClient<DB>,
+  options: PushThenPullOptions<DB>
+): Promise<PushThenPullResult<DB>> {
+  return createScenarioFlow(client).pushThenPull(options);
+}

package/src/sync-builders.ts

@@ -0,0 +1,128 @@
+import type {
+  SyncCombinedRequest,
+  SyncOperation,
+  SyncPullRequest,
+  SyncPushRequest,
+  SyncSubscriptionRequest,
+} from '@syncular/core';
+
+export interface CreateSyncUpsertOperationOptions {
+  table: string;
+  rowId: string;
+  payload: Record<string, unknown>;
+  baseVersion?: number | null;
+}
+
+export function createSyncUpsertOperation(
+  options: CreateSyncUpsertOperationOptions
+): SyncOperation {
+  return {
+    table: options.table,
+    row_id: options.rowId,
+    op: 'upsert',
+    payload: options.payload,
+    base_version: options.baseVersion ?? null,
+  };
+}
+
+export interface CreateSyncDeleteOperationOptions {
+  table: string;
+  rowId: string;
+  baseVersion?: number | null;
+}
+
+export function createSyncDeleteOperation(
+  options: CreateSyncDeleteOperationOptions
+): SyncOperation {
+  return {
+    table: options.table,
+    row_id: options.rowId,
+    op: 'delete',
+    payload: null,
+    base_version: options.baseVersion ?? null,
+  };
+}
+
+export interface CreateSyncSubscriptionOptions {
+  id: string;
+  table: string;
+  scopes: SyncSubscriptionRequest['scopes'];
+  params?: SyncSubscriptionRequest['params'];
+  cursor?: number;
+  bootstrapState?: SyncSubscriptionRequest['bootstrapState'];
+}
+
+export function createSyncSubscription(
+  options: CreateSyncSubscriptionOptions
+): SyncSubscriptionRequest {
+  return {
+    id: options.id,
+    table: options.table,
+    scopes: options.scopes,
+    ...(options.params ? { params: options.params } : {}),
+    cursor: options.cursor ?? 0,
+    bootstrapState: options.bootstrapState ?? null,
+  };
+}
+
+export interface CreateSyncPushRequestOptions {
+  clientId: string;
+  clientCommitId: string;
+  operations: SyncOperation[];
+  schemaVersion?: number;
+}
+
+export function createSyncPushRequest(
+  options: CreateSyncPushRequestOptions
+): SyncPushRequest {
+  return {
+    clientId: options.clientId,
+    clientCommitId: options.clientCommitId,
+    operations: options.operations,
+    schemaVersion: options.schemaVersion ?? 1,
+  };
+}
+
+export interface CreateSyncPullRequestOptions {
+  clientId: string;
+  subscriptions: SyncSubscriptionRequest[];
+  limitCommits?: number;
+  limitSnapshotRows?: number;
+  maxSnapshotPages?: number;
+  dedupeRows?: boolean;
+}
+
+export function createSyncPullRequest(
+  options: CreateSyncPullRequestOptions
+): SyncPullRequest {
+  return {
+    clientId: options.clientId,
+    subscriptions: options.subscriptions,
+    limitCommits: options.limitCommits ?? 50,
+    ...(options.limitSnapshotRows !== undefined
+      ? { limitSnapshotRows: options.limitSnapshotRows }
+      : {}),
+    ...(options.maxSnapshotPages !== undefined
+      ? { maxSnapshotPages: options.maxSnapshotPages }
+      : {}),
+    ...(options.dedupeRows !== undefined
+      ? { dedupeRows: options.dedupeRows }
+      : {}),
+  };
+}
+
+export interface CreateSyncCombinedRequestOptions {
+  clientId: string;
+  push?: Omit<SyncPushRequest, 'clientId'>;
+  pull?: Omit<SyncPullRequest, 'clientId'>;
+}
+
+export function createSyncCombinedRequest(
+  options: CreateSyncCombinedRequestOptions
+): SyncCombinedRequest {
+  return {
+    clientId: options.clientId,
+    ...(options.push ? { push: options.push } : {}),
+    ...(options.pull ? { pull: options.pull } : {}),
+  };
+}

package/src/sync-http.ts

@@ -6,6 +6,11 @@ import type {
   SyncPushRequest,
   SyncPushResponse,
 } from '@syncular/core';
+import {
+  parseSyncCombinedResponse,
+  parseSyncPullResponse,
+  parseSyncPushResponse,
+} from './sync-parse';
 
 export interface JsonActorHeadersOptions {
   actorId: string;
@@ -66,7 +71,11 @@ export interface PostSyncCombinedRequestOptions {
 export async function postSyncCombinedRequest(
   options: PostSyncCombinedRequestOptions
 ): Promise<PostJsonWithActorResult<SyncCombinedResponse>> {
-  return postJsonWithActor<SyncCombinedRequest, SyncCombinedResponse>(options);
+  const result = await postJsonWithActor<SyncCombinedRequest, unknown>(options);
+  return {
+    response: result.response,
+    json: parseSyncCombinedResponse(result.json),
+  };
 }
 
 export interface PostSyncPushRequestOptions {
@@ -81,7 +90,11 @@ export interface PostSyncPushRequestOptions {
 export async function postSyncPushRequest(
   options: PostSyncPushRequestOptions
 ): Promise<PostJsonWithActorResult<SyncPushResponse>> {
-  return postJsonWithActor<SyncPushRequest, SyncPushResponse>(options);
+  const result = await postJsonWithActor<SyncPushRequest, unknown>(options);
+  return {
+    response: result.response,
+    json: parseSyncPushResponse(result.json),
+  };
 }
 
 export interface PostSyncPullRequestOptions {
@@ -96,5 +109,9 @@ export interface PostSyncPullRequestOptions {
 export async function postSyncPullRequest(
   options: PostSyncPullRequestOptions
 ): Promise<PostJsonWithActorResult<SyncPullResponse>> {
-  return postJsonWithActor<SyncPullRequest, SyncPullResponse>(options);
+  const result = await postJsonWithActor<SyncPullRequest, unknown>(options);
+  return {
+    response: result.response,
+    json: parseSyncPullResponse(result.json),
+  };
 }

package/src/sync-parse.ts

@@ -0,0 +1,86 @@
+import {
+  type SyncCombinedResponse,
+  SyncCombinedResponseSchema,
+  type SyncPullResponse,
+  SyncPullResponseSchema,
+  type SyncPushResponse,
+  SyncPushResponseSchema,
+} from '@syncular/core';
+
+interface ParseIssue {
+  path: ReadonlyArray<PropertyKey>;
+  message: string;
+}
+
+type ParseResult<T> =
+  | { success: true; data: T }
+  | { success: false; error: { issues: ReadonlyArray<ParseIssue> } };
+
+function formatIssue(issue: ParseIssue): string {
+  const path =
+    issue.path.length > 0
+      ? issue.path
+          .map((segment) =>
+            typeof segment === 'symbol' ? segment.toString() : String(segment)
+          )
+          .join('.')
+      : 'root';
+  return `${path}: ${issue.message}`;
+}
+
+function formatIssues(issues: ReadonlyArray<ParseIssue>): string {
+  return issues.map((issue) => formatIssue(issue)).join('; ');
+}
+
+function parseOrThrow<T>(
+  label: string,
+  value: unknown,
+  parse: (input: unknown) => ParseResult<T>
+): T {
+  const parsed = parse(value);
+  if (parsed.success) {
+    return parsed.data;
+  }
+
+  throw new Error(
+    `${label} validation failed: ${formatIssues(parsed.error.issues)}`
+  );
+}
+
+export function parseSyncCombinedResponse(
+  value: unknown
+): SyncCombinedResponse {
+  return parseOrThrow('SyncCombinedResponse', value, (input) =>
+    SyncCombinedResponseSchema.safeParse(input)
+  );
+}
+
+export function parseSyncPushResponse(value: unknown): SyncPushResponse {
+  return parseOrThrow('SyncPushResponse', value, (input) =>
+    SyncPushResponseSchema.safeParse(input)
+  );
+}
+
+export function parseSyncPullResponse(value: unknown): SyncPullResponse {
+  return parseOrThrow('SyncPullResponse', value, (input) =>
+    SyncPullResponseSchema.safeParse(input)
+  );
+}
+
+export async function readSyncCombinedResponse(
+  response: Response
+): Promise<SyncCombinedResponse> {
+  return parseSyncCombinedResponse(await response.json());
+}
+
+export async function readSyncPushResponse(
+  response: Response
+): Promise<SyncPushResponse> {
+  return parseSyncPushResponse(await response.json());
+}
+
+export async function readSyncPullResponse(
+  response: Response
+): Promise<SyncPullResponse> {
+  return parseSyncPullResponse(await response.json());
+}