@syncular/server 0.1.3 → 0.2.0

package/src/proxy/collection.ts

@@ -1,17 +0,0 @@
-import { createTableLookup } from '@syncular/core';
-import type { ProxyTableHandler } from './types';
-
-export interface ProxyHandlerCollection {
-  handlers: ProxyTableHandler[];
-  byTable: ReadonlyMap<string, ProxyTableHandler>;
-}
-
-export function createProxyHandlerCollection(
-  handlers: ProxyTableHandler[]
-): ProxyHandlerCollection {
-  const byTable = createTableLookup(
-    handlers,
-    (table) => `Proxy table handler already registered: ${table}`
-  );
-  return { handlers, byTable };
-}

package/src/proxy/handler.ts

@@ -1,159 +0,0 @@
-/**
- * @syncular/server - Proxy Query Handler
- *
- * Executes proxied queries with automatic oplog generation for mutations.
- */
-
-import type { Kysely, RawBuilder } from 'kysely';
-import { sql } from 'kysely';
-import type { ServerSyncDialect } from '../dialect/types';
-import type { SyncCoreDb } from '../schema';
-import type { ProxyHandlerCollection } from './collection';
-import {
-  appendReturning,
-  detectMutation,
-  hasReturningClause,
-  hasReturningWildcard,
-} from './mutation-detector';
-import { createOplogEntries } from './oplog';
-import type { ProxyQueryContext } from './types';
-
-export interface ExecuteProxyQueryArgs<DB extends SyncCoreDb = SyncCoreDb> {
-  /** Database connection or transaction */
-  db: Kysely<DB>;
-  /** Server sync dialect */
-  dialect: ServerSyncDialect;
-  /** Proxy table handlers for oplog generation */
-  handlers: ProxyHandlerCollection;
-  /** Query context (actor/client IDs) */
-  ctx: ProxyQueryContext;
-  /** SQL query string */
-  sqlQuery: string;
-  /** Query parameters */
-  parameters: readonly unknown[];
-}
-
-export interface ExecuteProxyQueryResult {
-  /** Query result rows (for SELECT or RETURNING) */
-  rows?: unknown[];
-  /** Number of affected rows (for mutations) */
-  rowCount?: number;
-  /** Commit sequence if oplog was created */
-  commitSeq?: number;
-  /** Affected tables if oplog was created */
-  affectedTables?: string[];
-}
-
-/**
- * Build a raw SQL query with parameters using Kysely's sql helper.
- *
- * This converts parameterized SQL (using $1, $2, etc.) to Kysely's format.
- */
-function buildRawQuery(
-  sqlQuery: string,
-  parameters: readonly unknown[]
-): RawBuilder<unknown> {
-  // If no parameters, just use sql.raw
-  if (parameters.length === 0) {
-    return sql.raw(sqlQuery);
-  }
-
-  // Parse the SQL and split by parameter placeholders ($1, $2, etc.)
-  // Then use sql.join to build the query with proper parameter binding
-  const parts: RawBuilder<unknown>[] = [];
-  let lastIndex = 0;
-  const paramRegex = /\$(\d+)/g;
-  let match: RegExpExecArray | null;
-
-  while ((match = paramRegex.exec(sqlQuery)) !== null) {
-    // Add the SQL before this parameter
-    if (match.index > lastIndex) {
-      parts.push(sql.raw(sqlQuery.slice(lastIndex, match.index)));
-    }
-    // Add the parameter value (1-indexed in SQL, 0-indexed in array)
-    const paramIndex = Number.parseInt(match[1]!, 10) - 1;
-    if (paramIndex >= 0 && paramIndex < parameters.length) {
-      // Use sql.value to create a proper parameter binding
-      parts.push(sql.val(parameters[paramIndex]));
-    } else {
-      // Keep the original placeholder if out of bounds (shouldn't happen)
-      parts.push(sql.raw(match[0]));
-    }
-    lastIndex = match.index + match[0].length;
-  }
-
-  // Add remaining SQL after last parameter
-  if (lastIndex < sqlQuery.length) {
-    parts.push(sql.raw(sqlQuery.slice(lastIndex)));
-  }
-
-  // Join all parts together
-  return sql.join(parts, sql.raw(''));
-}
-
-/**
- * Execute a proxied query with automatic oplog generation for mutations.
- *
- * - Read queries: Execute directly and return rows
- * - Mutations: Append RETURNING *, execute, create oplog entries
- */
-export async function executeProxyQuery<DB extends SyncCoreDb>(
-  args: ExecuteProxyQueryArgs<DB>
-): Promise<ExecuteProxyQueryResult> {
-  const { db, dialect, handlers, ctx, sqlQuery, parameters } = args;
-
-  const mutation = detectMutation(sqlQuery);
-
-  if (!mutation) {
-    // Read query - execute directly
-    const result = await buildRawQuery(sqlQuery, parameters).execute(db);
-    return { rows: result.rows };
-  }
-
-  // Check if this table has a registered handler
-  const handler = handlers.byTable.get(mutation.tableName);
-  if (!handler) {
-    // No handler registered - execute without oplog
-    // This allows proxy operations on non-synced tables
-    const result = await buildRawQuery(sqlQuery, parameters).execute(db);
-    return {
-      rows: result.rows,
-      rowCount: Number(result.numAffectedRows ?? 0),
-    };
-  }
-
-  // Mutation with registered handler - append RETURNING * and create oplog
-  const hasReturning = hasReturningClause(sqlQuery);
-  if (hasReturning && !hasReturningWildcard(sqlQuery)) {
-    throw new Error(
-      `Proxy mutation on synced table "${mutation.tableName}" must use RETURNING * (or omit RETURNING)`
-    );
-  }
-
-  const finalSql = hasReturning ? sqlQuery : appendReturning(sqlQuery);
-
-  const result = await buildRawQuery(finalSql, parameters).execute(db);
-  const affectedRows = result.rows as Record<string, unknown>[];
-
-  if (affectedRows.length === 0) {
-    return { rowCount: 0 };
-  }
-
-  // Create oplog entries
-  const { commitSeq, affectedTables } = await createOplogEntries({
-    trx: db,
-    dialect,
-    actorId: ctx.actorId,
-    clientId: ctx.clientId,
-    partitionId: ctx.partitionId,
-    handler,
-    operation: mutation.operation,
-    rows: affectedRows,
-  });
-
-  return {
-    rowCount: affectedRows.length,
-    commitSeq,
-    affectedTables,
-  };
-}

package/src/proxy/index.ts

@@ -1,21 +0,0 @@
-/**
- * @syncular/server - Proxy Exports
- *
- * Server-side proxy functionality for database access.
- */
-
-// Oplog creation
-// Collections
-export {
-  createProxyHandlerCollection,
-  type ProxyHandlerCollection,
-} from './collection';
-// Query execution
-export {
-  type ExecuteProxyQueryArgs,
-  type ExecuteProxyQueryResult,
-  executeProxyQuery,
-} from './handler';
-// Mutation detection
-export { type DetectedMutation, detectMutation } from './mutation-detector';
-// Types

package/src/proxy/mutation-detector.ts

@@ -1,281 +0,0 @@
-/**
- * @syncular/server - Mutation Detector
- *
- * Detects whether a SQL query is a mutation (INSERT/UPDATE/DELETE).
- */
-
-import type { SyncOp } from '@syncular/core';
-
-export interface DetectedMutation {
-  /** Operation type */
-  operation: SyncOp;
-  /** Table name being modified */
-  tableName: string;
-}
-
-function isWordStart(ch: string): boolean {
-  return /[A-Za-z_]/.test(ch);
-}
-
-function isWordPart(ch: string): boolean {
-  return /[A-Za-z0-9_$]/.test(ch);
-}
-
-function skipLeadingNoise(sql: string): string {
-  let index = 0;
-  while (index < sql.length) {
-    while (index < sql.length && /[\s;]/.test(sql[index]!)) {
-      index += 1;
-    }
-
-    if (sql.startsWith('--', index)) {
-      index += 2;
-      while (index < sql.length && sql[index] !== '\n') {
-        index += 1;
-      }
-      continue;
-    }
-
-    if (sql.startsWith('/*', index)) {
-      const end = sql.indexOf('*/', index + 2);
-      if (end === -1) return '';
-      index = end + 2;
-      continue;
-    }
-
-    break;
-  }
-
-  return sql.slice(index);
-}
-
-function extractMainStatement(sql: string): string {
-  const normalized = skipLeadingNoise(sql);
-  if (!normalized.toLowerCase().startsWith('with')) {
-    return normalized;
-  }
-
-  const lower = normalized.toLowerCase();
-  const rootKeywords = new Set(['insert', 'update', 'delete', 'select']);
-
-  let index = 0;
-  let depth = 0;
-  let inSingleQuote = false;
-  let inDoubleQuote = false;
-  let inLineComment = false;
-  let inBlockComment = false;
-
-  while (index < normalized.length) {
-    const ch = normalized[index]!;
-    const next = normalized[index + 1];
-
-    if (inLineComment) {
-      if (ch === '\n') inLineComment = false;
-      index += 1;
-      continue;
-    }
-    if (inBlockComment) {
-      if (ch === '*' && next === '/') {
-        inBlockComment = false;
-        index += 2;
-        continue;
-      }
-      index += 1;
-      continue;
-    }
-    if (inSingleQuote) {
-      if (ch === "'" && next === "'") {
-        index += 2;
-        continue;
-      }
-      if (ch === "'") inSingleQuote = false;
-      index += 1;
-      continue;
-    }
-    if (inDoubleQuote) {
-      if (ch === '"' && next === '"') {
-        index += 2;
-        continue;
-      }
-      if (ch === '"') inDoubleQuote = false;
-      index += 1;
-      continue;
-    }
-
-    if (ch === '-' && next === '-') {
-      inLineComment = true;
-      index += 2;
-      continue;
-    }
-    if (ch === '/' && next === '*') {
-      inBlockComment = true;
-      index += 2;
-      continue;
-    }
-    if (ch === "'") {
-      inSingleQuote = true;
-      index += 1;
-      continue;
-    }
-    if (ch === '"') {
-      inDoubleQuote = true;
-      index += 1;
-      continue;
-    }
-    if (ch === '(') {
-      depth += 1;
-      index += 1;
-      continue;
-    }
-    if (ch === ')') {
-      if (depth > 0) depth -= 1;
-      index += 1;
-      continue;
-    }
-
-    if (depth === 0 && isWordStart(ch)) {
-      const tokenStart = index;
-      index += 1;
-      while (index < normalized.length && isWordPart(normalized[index]!)) {
-        index += 1;
-      }
-      const token = lower.slice(tokenStart, index);
-      if (
-        token !== 'with' &&
-        token !== 'recursive' &&
-        rootKeywords.has(token)
-      ) {
-        return normalized.slice(tokenStart);
-      }
-      continue;
-    }
-
-    index += 1;
-  }
-
-  return normalized;
-}
-
-function parseIdentifier(
-  input: string,
-  startIndex: number
-): { name: string; nextIndex: number } | null {
-  let index = startIndex;
-  while (index < input.length && /\s/.test(input[index]!)) {
-    index += 1;
-  }
-  if (index >= input.length) return null;
-
-  if (input[index] === '"') {
-    index += 1;
-    let value = '';
-    while (index < input.length) {
-      const ch = input[index]!;
-      if (ch === '"' && input[index + 1] === '"') {
-        value += '"';
-        index += 2;
-        continue;
-      }
-      if (ch === '"') {
-        index += 1;
-        return { name: value, nextIndex: index };
-      }
-      value += ch;
-      index += 1;
-    }
-    return null;
-  }
-
-  if (!isWordStart(input[index]!)) return null;
-  const first = index;
-  index += 1;
-  while (index < input.length && isWordPart(input[index]!)) {
-    index += 1;
-  }
-  return { name: input.slice(first, index), nextIndex: index };
-}
-
-function parseTargetTable(input: string): string | null {
-  const first = parseIdentifier(input, 0);
-  if (!first) return null;
-
-  let index = first.nextIndex;
-  while (index < input.length && /\s/.test(input[index]!)) {
-    index += 1;
-  }
-  if (input[index] !== '.') {
-    return first.name;
-  }
-
-  const second = parseIdentifier(input, index + 1);
-  if (!second) return null;
-  return second.name;
-}
-
-/**
- * Detect if a SQL query is a mutation and extract table info.
- *
- * @param sql - The SQL query string
- * @returns Mutation info if detected, null for read queries
- */
-export function detectMutation(sql: string): DetectedMutation | null {
-  const statement = extractMainStatement(sql).trimStart();
-  const lower = statement.toLowerCase();
-
-  if (lower.startsWith('insert')) {
-    const tableName = parseTargetTable(
-      statement.replace(/^insert\s+into\s+/i, '')
-    );
-    if (!tableName) return null;
-    return { operation: 'upsert', tableName };
-  }
-
-  if (lower.startsWith('update')) {
-    const tableName = parseTargetTable(statement.replace(/^update\s+/i, ''));
-    if (!tableName) return null;
-    return { operation: 'upsert', tableName };
-  }
-
-  if (lower.startsWith('delete')) {
-    const tableName = parseTargetTable(
-      statement.replace(/^delete\s+from\s+/i, '')
-    );
-    if (!tableName) return null;
-    return { operation: 'delete', tableName };
-  }
-
-  return null;
-}
-
-/**
- * Check if SQL already has a RETURNING clause.
- */
-export function hasReturningClause(sql: string): boolean {
-  // Simple check - look for RETURNING keyword not in a string
-  return /\bRETURNING\b/i.test(sql);
-}
-
-/**
- * Check if SQL has a wildcard RETURNING clause (RETURNING * or alias.*).
- */
-export function hasReturningWildcard(sql: string): boolean {
-  const match = sql.match(/\bRETURNING\b([\s\S]*)$/i);
-  if (!match) return false;
-  return /(^|,)\s*(?:[A-Za-z_][A-Za-z0-9_$]*\.)?\*/i.test(match[1]);
-}
-
-/**
- * Append RETURNING * to a mutation query if not already present.
- *
- * @param sql - The SQL query string
- * @returns Modified SQL with RETURNING *
- */
-export function appendReturning(sql: string): string {
-  if (hasReturningClause(sql)) {
-    return sql;
-  }
-
-  // Remove trailing semicolon if present
-  const trimmed = sql.trim().replace(/;\s*$/, '');
-  return `${trimmed} RETURNING *`;
-}

package/src/proxy/oplog.ts

@@ -1,181 +0,0 @@
-/**
- * @syncular/server - Oplog Creation
- *
- * Creates sync oplog entries for proxy mutations.
- */
-
-import { randomId, type SyncOp } from '@syncular/core';
-import { type Kysely, sql } from 'kysely';
-import { finalizeCommitIntegrity } from '../commit-integrity';
-import { toDialectJsonValue } from '../dialect/helpers';
-import type { ServerSyncDialect } from '../dialect/types';
-import { createScopeCommitIndexEntries } from '../helpers/scope-commit-index';
-import type { SyncCoreDb } from '../schema';
-import type { ProxyTableHandler } from './types';
-
-/**
- * Create oplog entries for affected rows.
- *
- * This is called after a mutation to record the changes in the sync oplog,
- * making them visible to sync clients.
- */
-export async function createOplogEntries<DB extends SyncCoreDb>(args: {
-  trx: Kysely<DB>;
-  dialect: ServerSyncDialect;
-  actorId: string;
-  clientId: string;
-  partitionId?: string;
-  handler: ProxyTableHandler;
-  operation: SyncOp;
-  rows: Record<string, unknown>[];
-}): Promise<{ commitSeq: number; affectedTables: string[] }> {
-  const { trx, dialect, actorId, clientId, handler, operation, rows } = args;
-  const partitionId = args.partitionId ?? 'default';
-
-  if (rows.length === 0) {
-    return { commitSeq: 0, affectedTables: [] };
-  }
-
-  const pk = handler.primaryKey ?? 'id';
-  const versionCol = handler.versionColumn ?? 'server_version';
-
-  // Create commit record
-  const commitResult = await sql<{ commit_seq: number }>`
-    insert into ${sql.table('sync_commits')} (
-      partition_id,
-      actor_id,
-      client_id,
-      client_commit_id,
-      meta,
-      result_json
-    )
-    values (
-      ${partitionId},
-      ${actorId},
-      ${clientId},
-      ${`proxy:${randomId()}`},
-      ${null},
-      ${null}
-    )
-    returning commit_seq
-  `.execute(trx);
-
-  const commitRow = commitResult.rows[0];
-  if (!commitRow) {
-    throw new Error('Failed to insert sync_commits row');
-  }
-  const commitSeq = Number(commitRow.commit_seq);
-
-  // Compute scopes for all rows and collect changes
-  const affectedTablesSet = new Set<string>();
-  affectedTablesSet.add(handler.table);
-
-  const changes = rows.map((row) => {
-    const scopes = handler.computeScopes(row);
-
-    return {
-      commit_seq: commitSeq,
-      partition_id: partitionId,
-      table: handler.table,
-      row_id: String(row[pk]),
-      op: operation,
-      row_json:
-        operation === 'delete' ? null : toDialectJsonValue(dialect, row),
-      row_version: row[versionCol] != null ? Number(row[versionCol]) : null,
-      raw_scopes: scopes,
-      scopes: dialect.scopesToDb(scopes),
-    };
-  });
-
-  // Insert changes
-  await sql`
-	    insert into ${sql.table('sync_changes')} (
-	      commit_seq,
-	      partition_id,
-	      "table",
-	      row_id,
-	      op,
-	      row_json,
-	      row_version,
-	      scopes
-    )
-    values ${sql.join(
-      changes.map(
-        (c) => sql`(
-          ${c.commit_seq},
-          ${c.partition_id},
-          ${c.table},
-          ${c.row_id},
-          ${c.op},
-          ${c.row_json},
-          ${c.row_version},
-          ${c.scopes}
-        )`
-      ),
-      sql`, `
-    )}
-  `.execute(trx);
-
-  const scopeEntries = createScopeCommitIndexEntries(
-    changes.map((change) => ({
-      table: change.table,
-      scopes: change.raw_scopes,
-    }))
-  );
-  if (scopeEntries.length > 0) {
-    await sql`
-      insert into ${sql.table('sync_scope_commits')} (
-        partition_id,
-        "table",
-        scope_key,
-        commit_seq
-      )
-      values ${sql.join(
-        scopeEntries.map(
-          (entry) => sql`(
-            ${partitionId},
-            ${entry.table},
-            ${entry.scopeKey},
-            ${commitSeq}
-          )`
-        ),
-        sql`, `
-      )}
-      on conflict (partition_id, "table", scope_key, commit_seq) do nothing
-    `.execute(trx);
-  }
-
-  // Update commit with affected tables
-  const affectedTables = Array.from(affectedTablesSet);
-  const sortedAffectedTables = affectedTables.sort();
-  await sql`
-    update ${sql.table('sync_commits')}
-    set
-      change_count = ${rows.length},
-      affected_tables = ${dialect.arrayToDb(sortedAffectedTables)}
-    where commit_seq = ${commitSeq}
-  `.execute(trx);
-
-  // Insert table commits for subscription filtering
-  if (affectedTables.length > 0) {
-    await sql`
-	      insert into ${sql.table('sync_table_commits')} (partition_id, "table", commit_seq)
-	      values ${sql.join(
-          sortedAffectedTables.map(
-            (table) => sql`(${partitionId}, ${table}, ${commitSeq})`
-          ),
-          sql`, `
-        )}
-	      on conflict (partition_id, "table", commit_seq) do nothing
-    `.execute(trx);
-  }
-
-  await finalizeCommitIntegrity({
-    db: trx,
-    dialect,
-    partitionId,
-    commitSeq,
-  });
-
-  return { commitSeq, affectedTables };
-}

package/src/proxy/types.ts

@@ -1,46 +0,0 @@
-/**
- * @syncular/server - Proxy Types
- *
- * Types for database proxy with automatic oplog generation.
- */
-
-import type { StoredScopes } from '@syncular/core';
-
-/**
- * Proxy table handler for mutations.
- *
- * Defines how to compute scopes for rows affected by proxy operations.
- */
-export interface ProxyTableHandler {
-  /** Database table name */
-  table: string;
-  /** Primary key column name (default: 'id') */
-  primaryKey?: string;
-  /** Version column name (default: 'server_version') */
-  versionColumn?: string;
-  /**
-   * Compute scope values for a row.
-   *
-   * This determines which sync subscriptions will see changes to this row.
-   * Returns a JSONB-compatible object of scope key-value pairs.
-   *
-   * @example
-   * computeScopes: (row) => ({
-   *   user_id: String(row.user_id),
-   *   project_id: String(row.project_id),
-   * })
-   */
-  computeScopes(row: Record<string, unknown>): StoredScopes;
-}
-
-/**
- * Context for executing a proxied query.
- */
-export interface ProxyQueryContext {
-  /** Actor ID for oplog tracking */
-  actorId: string;
-  /** Client ID for oplog tracking */
-  clientId: string;
-  /** Logical partition key (default: 'default') */
-  partitionId?: string;
-}