@syncular/client 0.0.6-95 → 0.1.0

package/src/plugins/incrementing-version.ts

@@ -1,133 +0,0 @@
-import type {
-  SyncOperation,
-  SyncPushRequest,
-  SyncPushResponse,
-} from '@syncular/core';
-import type { SyncClientPlugin, SyncClientPluginContext } from './types';
-
-export interface IncrementingVersionPluginOptions {
-  /**
-   * Plugin name (used for debugging).
-   * Defaults to "incrementing-version".
-   */
-  name?: string;
-  /**
-   * Maximum number of rows to track in memory.
-   * Defaults to 10_000.
-   */
-  maxTrackedRows?: number;
-}
-
-function makeRowKey(op: Pick<SyncOperation, 'table' | 'row_id'>): string {
-  return `${op.table}\u001f${op.row_id}`;
-}
-
-function touchLru(
-  map: Map<string, number>,
-  key: string,
-  value: number,
-  max: number
-): void {
-  // Maintain insertion order as an LRU.
-  map.delete(key);
-  map.set(key, value);
-  if (map.size <= max) return;
-  const firstKey = map.keys().next().value as string | undefined;
-  if (firstKey) map.delete(firstKey);
-}
-
-/**
- * Automatically advances `base_version` for sequential operations on the same row.
- *
- * Why this exists:
- * - UI code often reads a row once and can enqueue multiple updates quickly.
- * - The server rejects stale `base_version` values (optimistic concurrency).
- * - When those updates all originate from the same client and are pushed in-order,
- *   later ops are effectively based on the earlier ops.
- *
- * Assumptions:
- * - The server's row version is an integer that increments by 1 per applied upsert.
- * - Operations are pushed in commit order for a given client (outbox ordering).
- *
- * This plugin:
- * - Tracks the "next expected server version" per (table, row_id) based on
- *   successfully applied pushes.
- * - Rewrites outgoing `base_version` to that expected version when it is higher
- *   than the caller-provided value, preventing "self-conflicts" on hot rows.
- */
-export function createIncrementingVersionPlugin(
-  options: IncrementingVersionPluginOptions = {}
-): SyncClientPlugin {
-  const name = options.name ?? 'incrementing-version';
-  const maxTrackedRows = Math.max(
-    1,
-    Math.min(1_000_000, options.maxTrackedRows ?? 10_000)
-  );
-  const nextExpectedBaseVersionByRow = new Map<string, number>();
-
-  return {
-    name,
-
-    beforePush(
-      _ctx: SyncClientPluginContext,
-      request: SyncPushRequest
-    ): SyncPushRequest {
-      const operations = request.operations.map((op) => {
-        if (typeof op.base_version !== 'number') return op;
-
-        const key = makeRowKey(op);
-        const nextExpected = nextExpectedBaseVersionByRow.get(key);
-        if (typeof nextExpected !== 'number') return op;
-
-        if (nextExpected > op.base_version) {
-          return { ...op, base_version: nextExpected };
-        }
-
-        return op;
-      });
-
-      return { ...request, operations };
-    },
-
-    afterPush(
-      _ctx: SyncClientPluginContext,
-      args: { request: SyncPushRequest; response: SyncPushResponse }
-    ): SyncPushResponse {
-      // Rejected commits are rolled back by the server; nothing is applied.
-      if (
-        args.response.status !== 'applied' &&
-        args.response.status !== 'cached'
-      ) {
-        return args.response;
-      }
-
-      for (const result of args.response.results ?? []) {
-        if (result.status !== 'applied') continue;
-
-        const op = args.request.operations[result.opIndex];
-        if (!op) continue;
-
-        const key = makeRowKey(op);
-
-        if (op.op === 'delete') {
-          nextExpectedBaseVersionByRow.delete(key);
-          continue;
-        }
-
-        if (typeof op.base_version === 'number') {
-          touchLru(
-            nextExpectedBaseVersionByRow,
-            key,
-            op.base_version + 1,
-            maxTrackedRows
-          );
-        } else {
-          // Insert case: most tables start at version 1.
-          touchLru(nextExpectedBaseVersionByRow, key, 1, maxTrackedRows);
-        }
-      }
-
-      return args.response;
-    },
-  };
-}

package/src/plugins/index.ts

@@ -1,2 +0,0 @@
-export * from './incrementing-version';
-export * from './types';

package/src/plugins/types.ts

@@ -1,63 +0,0 @@
-import type {
-  SyncPullRequest,
-  SyncPullResponse,
-  SyncPushRequest,
-  SyncPushResponse,
-} from '@syncular/core';
-
-export interface SyncClientPluginContext {
-  actorId: string;
-  clientId: string;
-}
-
-/**
- * Plugin priority levels for ordering execution.
- * Lower numbers execute first.
- */
-export const PluginPriority = {
-  /** Compression should run early (before encryption) */
-  COMPRESSION: 10,
-  /** Encryption should run after compression but before transport */
-  ENCRYPTION: 20,
-  /** Default priority for general plugins */
-  DEFAULT: 50,
-  /** Logging/telemetry should run last */
-  TELEMETRY: 100,
-} as const;
-
-export interface SyncClientPlugin {
-  name: string;
-
-  /**
-   * Plugin priority for ordering. Lower numbers execute first.
-   * @default PluginPriority.DEFAULT (50)
-   */
-  priority?: number;
-
-  /**
-   * Called before sending a push request to the server.
-   * Use this for client-side encryption, payload shaping, etc.
-   */
-  beforePush?(
-    ctx: SyncClientPluginContext,
-    request: SyncPushRequest
-  ): Promise<SyncPushRequest> | SyncPushRequest;
-
-  /**
-   * Called after receiving a push response from the server.
-   * Receives both the request and the response to allow opIndex correlation.
-   */
-  afterPush?(
-    ctx: SyncClientPluginContext,
-    args: { request: SyncPushRequest; response: SyncPushResponse }
-  ): Promise<SyncPushResponse> | SyncPushResponse;
-
-  /**
-   * Called after receiving a pull response from the server (and after any
-   * snapshot chunk materialization), but before applying it to the local DB.
-   */
-  afterPull?(
-    ctx: SyncClientPluginContext,
-    args: { request: SyncPullRequest; response: SyncPullResponse }
-  ): Promise<SyncPullResponse> | SyncPullResponse;
-}

package/src/proxy/connection.ts

@@ -1,191 +0,0 @@
-/**
- * @syncular/client - Proxy Connection
- *
- * DatabaseConnection implementation that proxies queries over WebSocket.
- */
-
-import type {
-  ProxyHandshake,
-  ProxyHandshakeAck,
-  ProxyMessage,
-  ProxyResponse,
-} from '@syncular/core';
-import type { CompiledQuery, DatabaseConnection, QueryResult } from 'kysely';
-
-/**
- * WebSocket wrapper that handles reconnection and message correlation.
- */
-export class ProxyConnection implements DatabaseConnection {
-  private ws: WebSocket;
-  private messageId = 0;
-  private pendingRequests = new Map<
-    string,
-    {
-      resolve: (response: ProxyResponse) => void;
-      reject: (error: Error) => void;
-    }
-  >();
-  private handshakeComplete = false;
-  private handshakePromise: Promise<void>;
-  private handshakeResolve: (() => void) | null = null;
-  private handshakeReject: ((error: Error) => void) | null = null;
-  private closed = false;
-
-  constructor(
-    ws: WebSocket,
-    private actorId: string,
-    private clientId: string
-  ) {
-    this.ws = ws;
-
-    this.handshakePromise = new Promise((resolve, reject) => {
-      this.handshakeResolve = resolve;
-      this.handshakeReject = reject;
-    });
-
-    this.ws.onmessage = (event) => {
-      this.handleMessage(event.data as string);
-    };
-
-    this.ws.onerror = (_event) => {
-      const error = new Error('WebSocket error');
-      this.rejectAllPending(error);
-      if (!this.handshakeComplete) {
-        this.handshakeReject?.(error);
-      }
-    };
-
-    this.ws.onclose = () => {
-      this.closed = true;
-      const error = new Error('WebSocket closed');
-      this.rejectAllPending(error);
-      if (!this.handshakeComplete) {
-        this.handshakeReject?.(error);
-      }
-    };
-
-    // Send handshake
-    const handshake: ProxyHandshake = {
-      type: 'handshake',
-      actorId: this.actorId,
-      clientId: this.clientId,
-    };
-    this.ws.send(JSON.stringify(handshake));
-  }
-
-  private handleMessage(data: string): void {
-    try {
-      const message = JSON.parse(data);
-
-      // Handle handshake acknowledgement
-      if (message.type === 'handshake_ack') {
-        const ack = message as ProxyHandshakeAck;
-        if (ack.ok) {
-          this.handshakeComplete = true;
-          this.handshakeResolve?.();
-        } else {
-          this.handshakeReject?.(new Error(ack.error ?? 'Handshake failed'));
-        }
-        return;
-      }
-
-      // Handle query responses
-      const response = message as ProxyResponse;
-      const pending = this.pendingRequests.get(response.id);
-      if (pending) {
-        this.pendingRequests.delete(response.id);
-        pending.resolve(response);
-      }
-    } catch {
-      // Ignore malformed messages
-    }
-  }
-
-  private rejectAllPending(error: Error): void {
-    for (const pending of this.pendingRequests.values()) {
-      pending.reject(error);
-    }
-    this.pendingRequests.clear();
-  }
-
-  private async send(message: ProxyMessage): Promise<ProxyResponse> {
-    // Wait for handshake to complete
-    await this.handshakePromise;
-
-    if (this.closed) {
-      throw new Error('Connection is closed');
-    }
-
-    return new Promise((resolve, reject) => {
-      this.pendingRequests.set(message.id, { resolve, reject });
-      this.ws.send(JSON.stringify(message));
-    });
-  }
-
-  private nextMessageId(): string {
-    return `${++this.messageId}`;
-  }
-
-  async executeQuery<R>(query: CompiledQuery): Promise<QueryResult<R>> {
-    const response = await this.send({
-      id: this.nextMessageId(),
-      type: 'query',
-      sql: query.sql,
-      parameters: query.parameters,
-    });
-
-    if (response.type === 'error') {
-      throw new Error(response.error ?? 'Query failed');
-    }
-
-    return {
-      rows: (response.rows ?? []) as R[],
-      numAffectedRows:
-        response.rowCount != null ? BigInt(response.rowCount) : undefined,
-    };
-  }
-
-  async beginTransaction(): Promise<void> {
-    const response = await this.send({
-      id: this.nextMessageId(),
-      type: 'begin',
-    });
-
-    if (response.type === 'error') {
-      throw new Error(response.error ?? 'Failed to begin transaction');
-    }
-  }
-
-  async commitTransaction(): Promise<void> {
-    const response = await this.send({
-      id: this.nextMessageId(),
-      type: 'commit',
-    });
-
-    if (response.type === 'error') {
-      throw new Error(response.error ?? 'Failed to commit transaction');
-    }
-  }
-
-  async rollbackTransaction(): Promise<void> {
-    const response = await this.send({
-      id: this.nextMessageId(),
-      type: 'rollback',
-    });
-
-    if (response.type === 'error') {
-      throw new Error(response.error ?? 'Failed to rollback transaction');
-    }
-  }
-
-  streamQuery<R>(): AsyncIterableIterator<QueryResult<R>> {
-    throw new Error('Streaming queries are not supported over proxy');
-  }
-
-  close(): void {
-    if (!this.closed) {
-      this.closed = true;
-      this.ws.close();
-    }
-  }
-}

package/src/proxy/dialect.ts

@@ -1,76 +0,0 @@
-/**
- * @syncular/client - Proxy Dialect
- *
- * Kysely Dialect that proxies queries over WebSocket to a sync server.
- */
-
-import type {
-  DatabaseIntrospector,
-  Dialect,
-  DialectAdapter,
-  Driver,
-  Kysely,
-  QueryCompiler,
-} from 'kysely';
-import {
-  PostgresAdapter,
-  PostgresIntrospector,
-  PostgresQueryCompiler,
-} from 'kysely';
-import { ProxyDriver, type ProxyDriverConfigWithFactory } from './driver';
-
-interface ProxyDialectConfig extends ProxyDriverConfigWithFactory {}
-
-/**
- * Creates a Kysely dialect that proxies queries over WebSocket.
- *
- * This dialect uses PostgreSQL query compilation and adapters since
- * the proxy server typically runs against a PostgreSQL database.
- *
- * @example
- * ```typescript
- * import { Kysely } from 'kysely';
- * import { createProxyDialect } from '@syncular/client/proxy';
- *
- * const db = new Kysely<MySchema>({
- *   dialect: createProxyDialect({
- *     endpoint: 'wss://api.example.com/proxy',
- *     actorId: 'admin:worker',
- *     clientId: 'cf-worker-123',
- *     headers: { authorization: 'Bearer ...' },
- *   }),
- * });
- *
- * // Full Kysely API works
- * const tasks = await db.selectFrom('tasks').selectAll().execute();
- *
- * // Transactions work
- * await db.transaction().execute(async (trx) => {
- *   const user = await trx.selectFrom('users')
- *     .where('id', '=', 'u1')
- *     .executeTakeFirst();
- *   await trx.insertInto('tasks')
- *     .values({ id: 'x', user_id: user.id, title: 'New' })
- *     .execute();
- * });
- * ```
- */
-export function createProxyDialect(config: ProxyDialectConfig): Dialect {
-  return {
-    createDriver(): Driver {
-      return new ProxyDriver(config);
-    },
-
-    createQueryCompiler(): QueryCompiler {
-      return new PostgresQueryCompiler();
-    },
-
-    createAdapter(): DialectAdapter {
-      return new PostgresAdapter();
-    },
-
-    createIntrospector(db: Kysely<any>): DatabaseIntrospector {
-      return new PostgresIntrospector(db);
-    },
-  };
-}

package/src/proxy/driver.ts

@@ -1,126 +0,0 @@
-/**
- * @syncular/client - Proxy Driver
- *
- * Kysely Driver that creates WebSocket connections for query execution.
- */
-
-import type { DatabaseConnection, Driver } from 'kysely';
-import { ProxyConnection } from './connection';
-
-interface ProxyDriverConfig {
-  /** WebSocket endpoint URL (wss://...) */
-  endpoint: string;
-  /** Actor ID for oplog tracking */
-  actorId: string;
-  /** Client ID for oplog tracking */
-  clientId: string;
-  /** Optional headers for authentication */
-  headers?: Record<string, string>;
-}
-
-/**
- * Custom WebSocket factory type for environments that need it.
- */
-export type WebSocketFactory = (
-  url: string,
-  protocols?: string | string[]
-) => WebSocket;
-
-/**
- * Extended config with optional WebSocket factory.
- */
-export interface ProxyDriverConfigWithFactory extends ProxyDriverConfig {
-  /** Optional WebSocket factory for custom environments */
-  createWebSocket?: WebSocketFactory;
-}
-
-export class ProxyDriver implements Driver {
-  private connection: ProxyConnection | null = null;
-
-  constructor(private config: ProxyDriverConfigWithFactory) {}
-
-  async init(): Promise<void> {
-    // No initialization needed
-  }
-
-  async acquireConnection(): Promise<DatabaseConnection> {
-    // Reuse existing connection if available
-    if (this.connection) {
-      return this.connection as DatabaseConnection;
-    }
-
-    const ws = await this.createWebSocket();
-    this.connection = new ProxyConnection(
-      ws,
-      this.config.actorId,
-      this.config.clientId
-    );
-    return this.connection as DatabaseConnection;
-  }
-
-  private async createWebSocket(): Promise<WebSocket> {
-    return new Promise((resolve, reject) => {
-      // Build URL with auth info if needed
-      const url = new URL(this.config.endpoint);
-
-      // Note: WebSocket doesn't support custom headers directly,
-      // so auth is typically done via query params or after connection
-      // The server should handle auth during the handshake
-      if (this.config.headers?.authorization) {
-        url.searchParams.set(
-          'authorization',
-          this.config.headers.authorization
-        );
-      }
-
-      let ws: WebSocket;
-      if (this.config.createWebSocket) {
-        ws = this.config.createWebSocket(url.toString());
-      } else {
-        ws = new WebSocket(url.toString());
-      }
-
-      ws.onopen = () => {
-        resolve(ws);
-      };
-
-      ws.onerror = (_event) => {
-        reject(new Error('Failed to connect to proxy endpoint'));
-      };
-
-      // Set a connection timeout
-      const timeout = setTimeout(() => {
-        ws.close();
-        reject(new Error('Connection timeout'));
-      }, 30000);
-
-      ws.onopen = () => {
-        clearTimeout(timeout);
-        resolve(ws);
-      };
-    });
-  }
-
-  async beginTransaction(connection: DatabaseConnection): Promise<void> {
-    await (connection as ProxyConnection).beginTransaction();
-  }
-
-  async commitTransaction(connection: DatabaseConnection): Promise<void> {
-    await (connection as ProxyConnection).commitTransaction();
-  }
-
-  async rollbackTransaction(connection: DatabaseConnection): Promise<void> {
-    await (connection as ProxyConnection).rollbackTransaction();
-  }
-
-  async releaseConnection(): Promise<void> {
-    // Keep the connection alive for reuse
-  }
-
-  async destroy(): Promise<void> {
-    if (this.connection) {
-      this.connection.close();
-      this.connection = null;
-    }
-  }
-}

package/src/proxy/index.ts

@@ -1,10 +0,0 @@
-/**
- * @syncular/client - Proxy Dialect Exports
- *
- * Kysely dialect for proxying queries over WebSocket to a sync server.
- */
-
-export * from './connection';
-export * from './dialect';
-export * from './driver';
-export * from './mutations';

package/src/proxy/mutations.ts

@@ -1,18 +0,0 @@
-/**
- * @syncular/client - Proxy mutations
- *
- * Exposes the same Proxy-based mutation interface as the offline client,
- * but pushes commits to the server immediately (no local outbox/db writes).
- */
-
-import {
-  createPushMutations,
-  type MutationsApi,
-  type PushCommitConfig,
-} from '../mutations';
-
-export function createProxyMutations<DB extends Record<string, any>>(
-  config: PushCommitConfig
-): MutationsApi<DB, undefined> {
-  return createPushMutations(config);
-}