@syncular/testkit 0.1.2 → 0.2.0

package/src/project-scoped-tasks.ts

@@ -1,351 +0,0 @@
-import {
-  isRecord,
-  type SyncOperation,
-  type SyncSubscriptionRequest,
-} from '@syncular/core';
-import type {
-  ApplyOperationResult,
-  EmittedChange,
-  ServerTableHandler,
-  SyncCoreDb,
-} from '@syncular/server';
-import type { Kysely } from 'kysely';
-import { sql } from 'kysely';
-
-export interface ProjectScopedTasksRow {
-  id: string;
-  title: string;
-  completed: number;
-  user_id: string;
-  project_id: string;
-  server_version: number;
-}
-
-export interface ProjectScopedTasksDb extends SyncCoreDb {
-  tasks: ProjectScopedTasksRow;
-}
-
-export const PROJECT_SCOPED_TASKS_DDL = `
-  CREATE TABLE IF NOT EXISTS tasks (
-    id TEXT PRIMARY KEY,
-    title TEXT NOT NULL DEFAULT '',
-    completed INTEGER NOT NULL DEFAULT 0,
-    user_id TEXT NOT NULL,
-    project_id TEXT NOT NULL,
-    server_version INTEGER NOT NULL DEFAULT 1
-  )
-`;
-
-export interface ProjectScopedTasksHandlerOptions {
-  projectScopeCount?: number;
-}
-
-function parseProjectScopedTaskPayload(payload: SyncOperation['payload']): {
-  title?: string;
-  completed?: number;
-  project_id?: string;
-} {
-  if (!isRecord(payload)) {
-    return {};
-  }
-
-  return {
-    title: typeof payload.title === 'string' ? payload.title : undefined,
-    completed:
-      typeof payload.completed === 'number' ? payload.completed : undefined,
-    project_id:
-      typeof payload.project_id === 'string' ? payload.project_id : undefined,
-  };
-}
-
-export async function ensureProjectScopedTasksTable<
-  DB extends SyncCoreDb & { tasks: ProjectScopedTasksRow },
->(db: Kysely<DB>): Promise<void> {
-  await sql.raw(PROJECT_SCOPED_TASKS_DDL).execute(db);
-}
-
-export function createProjectScopedTasksHandler<
-  DB extends SyncCoreDb & { tasks: ProjectScopedTasksRow },
->(options: ProjectScopedTasksHandlerOptions = {}): ServerTableHandler<DB> {
-  const projectScopeCount = Math.max(1, options.projectScopeCount ?? 100);
-
-  return {
-    table: 'tasks',
-    scopePatterns: ['user:{user_id}:project:{project_id}'],
-
-    async resolveScopes(ctx) {
-      return {
-        user_id: ctx.actorId,
-        project_id: Array.from(
-          { length: projectScopeCount },
-          (_, index) => `p${index}`
-        ),
-      };
-    },
-
-    extractScopes(row: Record<string, unknown>) {
-      return {
-        user_id: String(row.user_id ?? ''),
-        project_id: String(row.project_id ?? ''),
-      };
-    },
-
-    async snapshot(ctx) {
-      const userIdValue = ctx.scopeValues.user_id;
-      const projectIdValue = ctx.scopeValues.project_id;
-      const userId = Array.isArray(userIdValue) ? userIdValue[0] : userIdValue;
-      const projectId = Array.isArray(projectIdValue)
-        ? projectIdValue[0]
-        : projectIdValue;
-
-      if (!userId || userId !== ctx.actorId) {
-        return { rows: [], nextCursor: null };
-      }
-
-      if (!projectId) {
-        return { rows: [], nextCursor: null };
-      }
-
-      const pageSize = Math.max(1, Math.min(10_000, ctx.limit));
-      const cursor = ctx.cursor;
-
-      const cursorFilter =
-        cursor && cursor.length > 0
-          ? sql`and ${sql.ref('id')} > ${sql.val(cursor)}`
-          : sql``;
-
-      const result = await sql<ProjectScopedTasksRow>`
-        select id, title, completed, user_id, project_id, server_version
-        from tasks
-        where user_id = ${sql.val(userId)}
-          and project_id = ${sql.val(projectId)}
-        ${cursorFilter}
-        order by id asc
-        limit ${sql.val(pageSize + 1)}
-      `.execute(ctx.db);
-
-      const rows = result.rows;
-      const hasMore = rows.length > pageSize;
-      const pageRows = hasMore ? rows.slice(0, pageSize) : rows;
-      const nextCursor = hasMore
-        ? (pageRows[pageRows.length - 1]?.id ?? null)
-        : null;
-
-      return {
-        rows: pageRows,
-        nextCursor:
-          typeof nextCursor === 'string' && nextCursor.length > 0
-            ? nextCursor
-            : null,
-      };
-    },
-
-    async applyOperation(
-      ctx,
-      op: SyncOperation,
-      opIndex: number
-    ): Promise<ApplyOperationResult> {
-      if (op.table !== 'tasks') {
-        return {
-          result: {
-            opIndex,
-            status: 'error',
-            error: `Unknown table: ${op.table}`,
-            code: 'sync.unknown_table',
-            retriable: false,
-          },
-          emittedChanges: [],
-        };
-      }
-
-      if (op.op === 'delete') {
-        const existingResult = await sql<{ id: string; project_id: string }>`
-          select id, project_id from tasks
-          where id = ${sql.val(op.row_id)} and user_id = ${sql.val(ctx.actorId)}
-          limit 1
-        `.execute(ctx.trx);
-        const existing = existingResult.rows[0];
-
-        if (!existing) {
-          return { result: { opIndex, status: 'applied' }, emittedChanges: [] };
-        }
-
-        await sql`
-          delete from tasks
-          where id = ${sql.val(op.row_id)} and user_id = ${sql.val(ctx.actorId)}
-        `.execute(ctx.trx);
-
-        const emitted: EmittedChange = {
-          table: 'tasks',
-          row_id: op.row_id,
-          op: 'delete',
-          row_json: null,
-          row_version: null,
-          scopes: { user_id: ctx.actorId, project_id: existing.project_id },
-        };
-
-        return {
-          result: { opIndex, status: 'applied' },
-          emittedChanges: [emitted],
-        };
-      }
-
-      const payload = parseProjectScopedTaskPayload(op.payload);
-
-      const existingResult = await sql<{
-        id: string;
-        title: string;
-        completed: number;
-        project_id: string;
-        server_version: number;
-      }>`
-        select id, title, completed, project_id, server_version
-        from tasks
-        where id = ${sql.val(op.row_id)} and user_id = ${sql.val(ctx.actorId)}
-        limit 1
-      `.execute(ctx.trx);
-      const existing = existingResult.rows[0];
-
-      if (
-        existing &&
-        op.base_version != null &&
-        existing.server_version !== op.base_version
-      ) {
-        return {
-          result: {
-            opIndex,
-            status: 'conflict',
-            message: `Version conflict: server=${existing.server_version}, base=${op.base_version}`,
-            code: 'sync.version_conflict',
-            server_version: existing.server_version,
-            server_row: {
-              id: existing.id,
-              title: existing.title,
-              completed: existing.completed,
-              user_id: ctx.actorId,
-              project_id: existing.project_id,
-              server_version: existing.server_version,
-            },
-          },
-          emittedChanges: [],
-        };
-      }
-
-      const projectId = payload.project_id ?? existing?.project_id;
-      if (!projectId) {
-        return {
-          result: {
-            opIndex,
-            status: 'error',
-            error: 'Missing project id',
-            code: 'sync.invalid_request',
-            retriable: false,
-          },
-          emittedChanges: [],
-        };
-      }
-
-      if (existing) {
-        const nextVersion = existing.server_version + 1;
-        await sql`
-          update tasks set
-            title = ${sql.val(payload.title ?? existing.title)},
-            completed = ${sql.val(payload.completed ?? existing.completed)},
-            server_version = ${sql.val(nextVersion)}
-          where id = ${sql.val(op.row_id)} and user_id = ${sql.val(ctx.actorId)}
-        `.execute(ctx.trx);
-      } else {
-        await sql`
-          insert into tasks (id, title, completed, user_id, project_id, server_version)
-          values (
-            ${sql.val(op.row_id)},
-            ${sql.val(payload.title ?? '')},
-            ${sql.val(payload.completed ?? 0)},
-            ${sql.val(ctx.actorId)},
-            ${sql.val(projectId)},
-            ${sql.val(1)}
-          )
-        `.execute(ctx.trx);
-      }
-
-      const updatedResult = await sql<ProjectScopedTasksRow>`
-        select id, title, completed, user_id, project_id, server_version
-        from tasks
-        where id = ${sql.val(op.row_id)} and user_id = ${sql.val(ctx.actorId)}
-        limit 1
-      `.execute(ctx.trx);
-      const updated = updatedResult.rows[0];
-      if (!updated) {
-        throw new Error('TASKS_ROW_NOT_FOUND');
-      }
-
-      const emitted: EmittedChange = {
-        table: 'tasks',
-        row_id: op.row_id,
-        op: 'upsert',
-        row_json: {
-          id: updated.id,
-          title: updated.title,
-          completed: updated.completed,
-          user_id: updated.user_id,
-          project_id: updated.project_id,
-          server_version: updated.server_version,
-        },
-        row_version: updated.server_version,
-        scopes: { user_id: ctx.actorId, project_id: updated.project_id },
-      };
-
-      return {
-        result: { opIndex, status: 'applied' },
-        emittedChanges: [emitted],
-      };
-    },
-  };
-}
-
-export interface CreateProjectScopedTasksSubscriptionOptions {
-  id?: string;
-  userId: string;
-  projectId?: string;
-  cursor?: number;
-}
-
-export function createProjectScopedTasksSubscription(
-  options: CreateProjectScopedTasksSubscriptionOptions
-): SyncSubscriptionRequest {
-  return {
-    id: options.id ?? 'sub-tasks',
-    table: 'tasks',
-    scopes: {
-      user_id: options.userId,
-      project_id: options.projectId ?? 'p0',
-    },
-    cursor: options.cursor ?? 0,
-    bootstrapState: null,
-    crdtStateVectors: [],
-  };
-}
-
-export interface CreateProjectScopedTaskUpsertOperationOptions {
-  taskId: string;
-  title: string;
-  completed?: number;
-  projectId?: string;
-  baseVersion?: number | null;
-}
-
-export function createProjectScopedTaskUpsertOperation(
-  options: CreateProjectScopedTaskUpsertOperationOptions
-): SyncOperation {
-  return {
-    table: 'tasks',
-    row_id: options.taskId,
-    op: 'upsert',
-    payload: {
-      title: options.title,
-      completed: options.completed ?? 0,
-      project_id: options.projectId ?? 'p0',
-    },
-    base_version: options.baseVersion ?? null,
-  };
-}

package/src/realtime-ws.ts

@@ -1,354 +0,0 @@
-import { isRecord } from '@syncular/core';
-import {
-  type AsyncDisposableResource,
-  createAsyncDisposableResource,
-  type ResourceRunner,
-  withAsyncDisposableFactory,
-} from './disposable';
-
-export type RealtimeWsQueryValue = string | number | boolean | null | undefined;
-
-export interface CreateRealtimeWsUrlOptions {
-  baseUrl: string;
-  clientId: string;
-  actorId: string;
-  actorQueryParam?: string;
-  path?: string;
-  query?: Record<string, RealtimeWsQueryValue>;
-}
-
-export interface WebSocketConstructor {
-  new (url: string, protocols?: string | string[]): WebSocket;
-}
-
-export interface OpenRealtimeWsOptions extends CreateRealtimeWsUrlOptions {
-  WebSocketCtor?: WebSocketConstructor;
-  protocols?: string | string[];
-}
-
-export interface OpenRealtimeWsResourceOptions extends OpenRealtimeWsOptions {
-  waitForOpen?: boolean;
-  openTimeoutMs?: number;
-  close?: CloseWsSafeOptions;
-}
-
-function appendQueryParam(
-  url: URL,
-  key: string,
-  value: RealtimeWsQueryValue
-): void {
-  if (value === null || value === undefined) {
-    return;
-  }
-
-  url.searchParams.set(key, String(value));
-}
-
-function toWsProtocol(protocol: string): string {
-  if (protocol === 'http:') {
-    return 'ws:';
-  }
-
-  if (protocol === 'https:') {
-    return 'wss:';
-  }
-
-  return protocol;
-}
-
-export function createRealtimeWsUrl(
-  options: CreateRealtimeWsUrlOptions
-): string {
-  const url = new URL(options.baseUrl);
-  url.protocol = toWsProtocol(url.protocol);
-
-  const path = options.path ?? '/sync/realtime';
-  url.pathname = path.startsWith('/') ? path : `/${path}`;
-  url.search = '';
-
-  appendQueryParam(url, 'clientId', options.clientId);
-  appendQueryParam(url, options.actorQueryParam ?? 'userId', options.actorId);
-
-  for (const [key, value] of Object.entries(options.query ?? {})) {
-    appendQueryParam(url, key, value);
-  }
-
-  return url.toString();
-}
-
-export function openRealtimeWs(options: OpenRealtimeWsOptions): WebSocket {
-  const WebSocketCtor = options.WebSocketCtor ?? globalThis.WebSocket;
-  if (!WebSocketCtor) {
-    throw new Error('WebSocket constructor is unavailable in this runtime');
-  }
-
-  return new WebSocketCtor(createRealtimeWsUrl(options), options.protocols);
-}
-
-export interface WaitForWsOpenOptions {
-  timeoutMs?: number;
-}
-
-export function waitForWsOpen(
-  ws: WebSocket,
-  options: WaitForWsOpenOptions = {}
-): Promise<void> {
-  const timeoutMs = options.timeoutMs ?? 10_000;
-
-  return new Promise<void>((resolve, reject) => {
-    const cleanup = () => {
-      clearTimeout(timeout);
-      ws.removeEventListener('open', onOpen);
-      ws.removeEventListener('error', onError);
-      ws.removeEventListener('close', onClose);
-    };
-
-    const onOpen = () => {
-      cleanup();
-      resolve();
-    };
-
-    const onError = () => {
-      cleanup();
-      reject(new Error('WebSocket emitted an error before opening'));
-    };
-
-    const onClose = (event: CloseEvent) => {
-      cleanup();
-      reject(
-        new Error(
-          `WebSocket closed before opening (code=${event.code} reason=${event.reason || 'none'})`
-        )
-      );
-    };
-
-    const timeout = setTimeout(() => {
-      cleanup();
-      reject(
-        new Error(`Timed out waiting for WebSocket open (${timeoutMs}ms)`)
-      );
-    }, timeoutMs);
-
-    ws.addEventListener('open', onOpen);
-    ws.addEventListener('error', onError);
-    ws.addEventListener('close', onClose);
-  });
-}
-
-export interface WaitForWsMessageOptions {
-  timeoutMs?: number;
-  predicate?: (event: MessageEvent) => boolean;
-}
-
-export function waitForWsMessage(
-  ws: WebSocket,
-  options: WaitForWsMessageOptions = {}
-): Promise<MessageEvent> {
-  const timeoutMs = options.timeoutMs ?? 10_000;
-
-  return new Promise<MessageEvent>((resolve, reject) => {
-    const cleanup = () => {
-      clearTimeout(timeout);
-      ws.removeEventListener('message', onMessage);
-      ws.removeEventListener('error', onError);
-      ws.removeEventListener('close', onClose);
-    };
-
-    const onMessage = (event: MessageEvent) => {
-      if (options.predicate && !options.predicate(event)) {
-        return;
-      }
-
-      cleanup();
-      resolve(event);
-    };
-
-    const onError = () => {
-      cleanup();
-      reject(new Error('WebSocket emitted an error before a message arrived'));
-    };
-
-    const onClose = (event: CloseEvent) => {
-      cleanup();
-      reject(
-        new Error(
-          `WebSocket closed before receiving a matching message (code=${event.code} reason=${event.reason || 'none'})`
-        )
-      );
-    };
-
-    const timeout = setTimeout(() => {
-      cleanup();
-      reject(
-        new Error(`Timed out waiting for WebSocket message (${timeoutMs}ms)`)
-      );
-    }, timeoutMs);
-
-    ws.addEventListener('message', onMessage);
-    ws.addEventListener('error', onError);
-    ws.addEventListener('close', onClose);
-  });
-}
-
-function readTextPayload(data: MessageEvent['data']): string | null {
-  if (typeof data === 'string') {
-    return data;
-  }
-
-  if (data instanceof ArrayBuffer) {
-    return new TextDecoder().decode(new Uint8Array(data));
-  }
-
-  if (ArrayBuffer.isView(data)) {
-    return new TextDecoder().decode(
-      new Uint8Array(data.buffer, data.byteOffset, data.byteLength)
-    );
-  }
-
-  return null;
-}
-
-export function parseWsJsonMessage(
-  event: MessageEvent
-): Record<string, unknown> | null {
-  const payload = readTextPayload(event.data);
-  if (!payload) {
-    return null;
-  }
-
-  try {
-    const parsed = JSON.parse(payload);
-    return isRecord(parsed) ? parsed : null;
-  } catch {
-    return null;
-  }
-}
-
-export interface WaitForWsJsonMessageOptions {
-  timeoutMs?: number;
-  predicate?: (message: Record<string, unknown>) => boolean;
-}
-
-export function waitForWsJsonMessage(
-  ws: WebSocket,
-  options: WaitForWsJsonMessageOptions = {}
-): Promise<Record<string, unknown>> {
-  const timeoutMs = options.timeoutMs ?? 10_000;
-
-  return new Promise<Record<string, unknown>>((resolve, reject) => {
-    const cleanup = () => {
-      clearTimeout(timeout);
-      ws.removeEventListener('message', onMessage);
-      ws.removeEventListener('error', onError);
-      ws.removeEventListener('close', onClose);
-    };
-
-    const onMessage = (event: MessageEvent) => {
-      const parsed = parseWsJsonMessage(event);
-      if (!parsed) {
-        return;
-      }
-
-      if (options.predicate && !options.predicate(parsed)) {
-        return;
-      }
-
-      cleanup();
-      resolve(parsed);
-    };
-
-    const onError = () => {
-      cleanup();
-      reject(new Error('WebSocket emitted an error before JSON message'));
-    };
-
-    const onClose = (event: CloseEvent) => {
-      cleanup();
-      reject(
-        new Error(
-          `WebSocket closed before receiving JSON message (code=${event.code} reason=${event.reason || 'none'})`
-        )
-      );
-    };
-
-    const timeout = setTimeout(() => {
-      cleanup();
-      reject(
-        new Error(
-          `Timed out waiting for WebSocket JSON message (${timeoutMs}ms)`
-        )
-      );
-    }, timeoutMs);
-
-    ws.addEventListener('message', onMessage);
-    ws.addEventListener('error', onError);
-    ws.addEventListener('close', onClose);
-  });
-}
-
-export interface CloseWsSafeOptions {
-  code?: number;
-  reason?: string;
-  timeoutMs?: number;
-}
-
-const WS_CLOSING = 2;
-const WS_CLOSED = 3;
-
-export async function closeWsSafe(
-  ws: WebSocket,
-  options: CloseWsSafeOptions = {}
-): Promise<void> {
-  if (ws.readyState === WS_CLOSED) {
-    return;
-  }
-
-  const timeoutMs = options.timeoutMs ?? 2_000;
-
-  await new Promise<void>((resolve) => {
-    const cleanup = () => {
-      clearTimeout(timeout);
-      ws.removeEventListener('close', onClose);
-      resolve();
-    };
-
-    const onClose = () => {
-      cleanup();
-    };
-
-    const timeout = setTimeout(() => {
-      cleanup();
-    }, timeoutMs);
-
-    ws.addEventListener('close', onClose);
-
-    if (ws.readyState !== WS_CLOSING) {
-      try {
-        ws.close(options.code, options.reason);
-      } catch {
-        cleanup();
-      }
-    }
-  });
-}
-
-export async function openRealtimeWsResource(
-  options: OpenRealtimeWsResourceOptions
-): Promise<AsyncDisposableResource<WebSocket>> {
-  const ws = openRealtimeWs(options);
-
-  if (options.waitForOpen) {
-    await waitForWsOpen(ws, { timeoutMs: options.openTimeoutMs });
-  }
-
-  return createAsyncDisposableResource(ws, () =>
-    closeWsSafe(ws, options.close)
-  );
-}
-
-export async function withRealtimeWs<TResult>(
-  options: OpenRealtimeWsResourceOptions,
-  run: ResourceRunner<WebSocket, TResult>
-): Promise<TResult> {
-  return withAsyncDisposableFactory(() => openRealtimeWsResource(options), run);
-}