@syncular/client 0.0.1 → 0.0.2-126

package/src/handlers/create-handler.ts

@@ -2,8 +2,21 @@
  * @syncular/client - Declarative client handler helper
  */
 
-import type { ScopeDefinition, SyncChange, SyncSnapshot } from '@syncular/core';
-import { normalizeScopes } from '@syncular/core';
+import type {
+  ColumnCodecDialect,
+  ColumnCodecSource,
+  ScopeDefinition,
+  ScopeKeysFromDefinitions,
+  ScopeValuesFromPatterns,
+  SyncChange,
+  SyncSnapshot,
+} from '@syncular/core';
+import {
+  applyCodecsToDbRow,
+  isRecord,
+  normalizeScopes,
+  toTableColumnCodecs,
+} from '@syncular/core';
 import { sql } from 'kysely';
 import type { SyncClientDb } from '../schema';
 import type {
@@ -13,20 +26,7 @@ import type {
   ClientTableHandler,
 } from './types';
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
-/**
- * Coerce a value for SQL parameter binding.
- * PostgreSQL (PGlite) does not implicitly cast booleans to integers,
- * so we convert them to 0/1 before binding.
- */
-function coerceForSql(value: unknown): unknown {
-  if (value === undefined) return null;
-  if (typeof value === 'boolean') return value ? 1 : 0;
-  return value;
-}
+const MAX_INSERT_BIND_PARAMETERS = 900;
 
 /**
  * Options for creating a declarative client handler.
@@ -34,6 +34,7 @@ function coerceForSql(value: unknown): unknown {
 export interface CreateClientHandlerOptions<
   DB extends SyncClientDb,
   TableName extends keyof DB & string,
+  ScopeDefs extends readonly ScopeDefinition[] = readonly ScopeDefinition[],
 > {
   /** Table name in the database */
   table: TableName;
@@ -53,7 +54,7 @@ export interface CreateClientHandlerOptions<
    * ]
    * ```
    */
-  scopes: ScopeDefinition[];
+  scopes: ScopeDefs;
 
   /**
    * Subscription configuration for this table.
@@ -64,7 +65,7 @@ export interface CreateClientHandlerOptions<
   subscribe?:
     | boolean
     | {
-        scopes?: Record<string, string | string[]>;
+        scopes?: ScopeValuesFromPatterns<ScopeDefs>;
         params?: Record<string, unknown>;
       };
 
@@ -77,6 +78,18 @@ export interface CreateClientHandlerOptions<
    */
   versionColumn?: keyof DB[TableName] & string;
 
+  /**
+   * Optional column codec resolver.
+   * Receives `{ table, column, sqlType?, dialect? }` and returns a codec.
+   */
+  columnCodecs?: ColumnCodecSource;
+
+  /**
+   * Dialect used for codec dialect overrides.
+   * Default: 'sqlite'
+   */
+  codecDialect?: ColumnCodecDialect;
+
   /**
    * Override: Apply a snapshot.
    * Default: upsert all rows (no delete on isFirstPage).
@@ -154,13 +167,30 @@ export interface CreateClientHandlerOptions<
 export function createClientHandler<
   DB extends SyncClientDb,
   TableName extends keyof DB & string,
+  ScopeDefs extends readonly ScopeDefinition[] = readonly ScopeDefinition[],
 >(
-  options: CreateClientHandlerOptions<DB, TableName>
-): ClientTableHandler<DB, TableName> {
+  options: CreateClientHandlerOptions<DB, TableName, ScopeDefs>
+): ClientTableHandler<DB, TableName, ScopeKeysFromDefinitions<ScopeDefs>> {
   const { table, scopes: scopeDefs } = options;
   const primaryKey =
     options.primaryKey ?? ('id' as keyof DB[TableName] & string);
   const versionColumn = options.versionColumn;
+  const codecDialect = options.codecDialect ?? 'sqlite';
+  const codecCache = new Map<string, ReturnType<typeof toTableColumnCodecs>>();
+  const resolveTableCodecs = (row: Record<string, unknown>) => {
+    const columnCodecs = options.columnCodecs;
+    if (!columnCodecs) return {};
+    const columns = Object.keys(row);
+    if (columns.length === 0) return {};
+    const cacheKey = columns.slice().sort().join('\u0000');
+    const cached = codecCache.get(cacheKey);
+    if (cached) return cached;
+    const resolved = toTableColumnCodecs(table, columnCodecs, columns, {
+      dialect: codecDialect,
+    });
+    codecCache.set(cacheKey, resolved);
+    return resolved;
+  };
 
   // Normalize scopes to pattern map (stored for metadata)
   const scopeColumnMap = normalizeScopes(scopeDefs);
@@ -174,7 +204,7 @@ export function createClientHandler<
     const rows: Array<Record<string, unknown>> = [];
     for (const row of snapshot.rows ?? []) {
       if (!isRecord(row)) continue;
-      rows.push(row);
+      rows.push(applyCodecsToDbRow(row, resolveTableCodecs(row), codecDialect));
     }
 
     if (rows.length === 0) return;
@@ -194,20 +224,33 @@ export function createClientHandler<
             sql`, `
           )}`;
 
-    await sql`
-      insert into ${sql.table(table)} (${sql.join(columns.map((c) => sql.ref(c)))})
-      values ${sql.join(
-        rows.map(
-          (row) =>
-            sql`(${sql.join(
-              columns.map((col) => sql.val(coerceForSql(row[col]))),
-              sql`, `
-            )})`
-        ),
-        sql`, `
-      )}
-      on conflict (${sql.ref(primaryKey)}) ${onConflict}
-    `.execute(ctx.trx);
+    const maxRowsPerInsert = Math.max(
+      1,
+      Math.floor(MAX_INSERT_BIND_PARAMETERS / columns.length)
+    );
+
+    for (
+      let startIndex = 0;
+      startIndex < rows.length;
+      startIndex += maxRowsPerInsert
+    ) {
+      const batchRows = rows.slice(startIndex, startIndex + maxRowsPerInsert);
+
+      await sql`
+        insert into ${sql.table(table)} (${sql.join(columns.map((c) => sql.ref(c)))})
+        values ${sql.join(
+          batchRows.map(
+            (row) =>
+              sql`(${sql.join(
+                columns.map((col) => sql.val(row[col] ?? null)),
+                sql`, `
+              )})`
+          ),
+          sql`, `
+        )}
+        on conflict (${sql.ref(primaryKey)}) ${onConflict}
+      `.execute(ctx.trx);
+    }
   };
 
   // Default applyChange: upsert on upsert, delete on delete
@@ -223,7 +266,13 @@ export function createClientHandler<
       return;
     }
 
-    const row = isRecord(change.row_json) ? change.row_json : {};
+    const row = isRecord(change.row_json)
+      ? applyCodecsToDbRow(
+          change.row_json,
+          resolveTableCodecs(change.row_json),
+          codecDialect
+        )
+      : {};
     const insertRow: Record<string, unknown> = {
       ...row,
       [primaryKey]: change.row_id,
@@ -252,7 +301,7 @@ export function createClientHandler<
     await sql`
       insert into ${sql.table(table)} (${sql.join(columns.map((c) => sql.ref(c)))})
       values (${sql.join(
-        columns.map((col) => sql.val(coerceForSql(insertRow[col]))),
+        columns.map((col) => sql.val(insertRow[col] ?? null)),
         sql`, `
       )})
       on conflict (${sql.ref(primaryKey)}) ${onConflict}

package/src/handlers/types.ts

@@ -2,7 +2,12 @@
  * @syncular/client - Sync client table handler interface
  */
 
-import type { ScopeValues, SyncChange, SyncSnapshot } from '@syncular/core';
+import type {
+  ScopeValues,
+  ScopeValuesForKeys,
+  SyncChange,
+  SyncSnapshot,
+} from '@syncular/core';
 import type { Transaction } from 'kysely';
 
 /**
@@ -35,9 +40,9 @@ export interface ClientClearContext<DB> extends ClientHandlerContext<DB> {
 /**
  * Subscription configuration for a handler.
  */
-export interface HandlerSubscriptionConfig {
+export interface HandlerSubscriptionConfig<ScopeKeys extends string = string> {
   /** Scope values for this subscription */
-  scopes?: Record<string, string | string[]>;
+  scopes?: ScopeValuesForKeys<ScopeKeys>;
   /** Params for this subscription */
   params?: Record<string, unknown>;
 }
@@ -48,6 +53,7 @@ export interface HandlerSubscriptionConfig {
 export interface ClientTableHandler<
   DB,
   TableName extends keyof DB & string = keyof DB & string,
+  ScopeKeys extends string = string,
 > {
   /** Table name (used as identifier in sync operations) */
   table: TableName;
@@ -64,7 +70,7 @@ export interface ClientTableHandler<
    * - `false`: Don't subscribe (local-only handler)
    * - Object: Subscribe with custom scopes/params
    */
-  subscribe?: boolean | HandlerSubscriptionConfig;
+  subscribe?: boolean | HandlerSubscriptionConfig<ScopeKeys>;
 
   /**
    * Apply a snapshot page for this table.

package/src/migrate.ts

@@ -2,9 +2,188 @@
  * @syncular/client - Sync migrations (SQLite reference)
  */
 
-import type { Kysely } from 'kysely';
+import { type Kysely, sql } from 'kysely';
 import type { SyncClientDb } from './schema';
 
+type SyncInternalTable =
+  | 'sync_subscription_state'
+  | 'sync_outbox_commits'
+  | 'sync_conflicts';
+
+function toErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function isMissingTableError(message: string): boolean {
+  const normalized = message.toLowerCase();
+  return (
+    normalized.includes('no such table') ||
+    (normalized.includes('relation') && normalized.includes('does not exist'))
+  );
+}
+
+function isMissingColumnError(message: string): boolean {
+  const normalized = message.toLowerCase();
+  return (
+    normalized.includes('no such column') ||
+    (normalized.includes('column') && normalized.includes('does not exist'))
+  );
+}
+
+function isDuplicateColumnError(message: string): boolean {
+  const normalized = message.toLowerCase();
+  return (
+    normalized.includes('duplicate column name') ||
+    (normalized.includes('column') && normalized.includes('already exists'))
+  );
+}
+
+async function getColumnNames<DB extends SyncClientDb>(
+  db: Kysely<DB>,
+  tableName: SyncInternalTable
+): Promise<Set<string> | null> {
+  try {
+    const sqlite = await sql<{ name: string }>`
+      select name from pragma_table_info(${sql.val(tableName)})
+    `.execute(db);
+    return new Set(sqlite.rows.map((row) => String(row.name)));
+  } catch {
+    // Not SQLite or pragma unavailable.
+  }
+
+  try {
+    const postgres = await sql<{ name: string }>`
+      select column_name as name
+      from information_schema.columns
+      where table_name = ${sql.val(tableName)}
+    `.execute(db);
+    return new Set(postgres.rows.map((row) => String(row.name)));
+  } catch {
+    // Introspection unavailable; caller falls back to probing.
+  }
+
+  return null;
+}
+
+async function hasColumn<DB extends SyncClientDb>(
+  db: Kysely<DB>,
+  tableName: SyncInternalTable,
+  columnName: string
+): Promise<boolean> {
+  const columns = await getColumnNames(db, tableName);
+  if (columns) {
+    return columns.has(columnName);
+  }
+
+  try {
+    await sql`select ${sql.ref(columnName)} from ${sql.table(tableName)} limit 1`.execute(
+      db
+    );
+    return true;
+  } catch (error) {
+    const message = toErrorMessage(error);
+    if (isMissingTableError(message) || isMissingColumnError(message)) {
+      return false;
+    }
+    throw error;
+  }
+}
+
+async function addColumnIfMissing<DB extends SyncClientDb>(
+  db: Kysely<DB>,
+  tableName: SyncInternalTable,
+  columnName: string,
+  addColumn: () => Promise<void>
+): Promise<void> {
+  if (await hasColumn(db, tableName, columnName)) {
+    return;
+  }
+  try {
+    await addColumn();
+  } catch (error) {
+    const message = toErrorMessage(error);
+    if (isDuplicateColumnError(message)) {
+      return;
+    }
+    throw error;
+  }
+}
+
+async function ensureClientSyncSchemaCompat<DB extends SyncClientDb>(
+  db: Kysely<DB>
+): Promise<void> {
+  const hasTableColumn = await hasColumn(
+    db,
+    'sync_subscription_state',
+    'table'
+  );
+  if (
+    !hasTableColumn &&
+    (await hasColumn(db, 'sync_subscription_state', 'shape'))
+  ) {
+    try {
+      await sql`alter table ${sql.table('sync_subscription_state')} rename column ${sql.ref('shape')} to ${sql.ref('table')}`.execute(
+        db
+      );
+    } catch {
+      await addColumnIfMissing(
+        db,
+        'sync_subscription_state',
+        'table',
+        async () => {
+          await db.schema
+            .alterTable('sync_subscription_state')
+            .addColumn('table', 'text', (col) => col.notNull().defaultTo(''))
+            .execute();
+        }
+      );
+      await sql`update ${sql.table('sync_subscription_state')}
+        set ${sql.ref('table')} = ${sql.ref('shape')}
+        where ${sql.ref('table')} = ${sql.val('')}`.execute(db);
+    }
+  }
+
+  await addColumnIfMissing(
+    db,
+    'sync_subscription_state',
+    'bootstrap_state_json',
+    async () => {
+      await db.schema
+        .alterTable('sync_subscription_state')
+        .addColumn('bootstrap_state_json', 'text')
+        .execute();
+    }
+  );
+
+  await addColumnIfMissing(
+    db,
+    'sync_outbox_commits',
+    'schema_version',
+    async () => {
+      await db.schema
+        .alterTable('sync_outbox_commits')
+        .addColumn('schema_version', 'integer', (col) =>
+          col.notNull().defaultTo(1)
+        )
+        .execute();
+    }
+  );
+
+  await addColumnIfMissing(db, 'sync_conflicts', 'resolved_at', async () => {
+    await db.schema
+      .alterTable('sync_conflicts')
+      .addColumn('resolved_at', 'bigint')
+      .execute();
+  });
+
+  await addColumnIfMissing(db, 'sync_conflicts', 'resolution', async () => {
+    await db.schema
+      .alterTable('sync_conflicts')
+      .addColumn('resolution', 'text')
+      .execute();
+  });
+}
+
 /**
  * Ensures the client sync schema exists in the database.
  * Safe to call multiple times (idempotent).
@@ -14,13 +193,13 @@ import type { SyncClientDb } from './schema';
 export async function ensureClientSyncSchema<DB extends SyncClientDb>(
   db: Kysely<DB>
 ): Promise<void> {
-  // Schema builder doesn't need typed access - operates on raw SQL
+  // Schema builder doesn't need typed access - operates on raw SQL.
   await db.schema
     .createTable('sync_subscription_state')
     .ifNotExists()
     .addColumn('state_id', 'text', (col) => col.notNull())
     .addColumn('subscription_id', 'text', (col) => col.notNull())
-    .addColumn('shape', 'text', (col) => col.notNull())
+    .addColumn('table', 'text', (col) => col.notNull())
     .addColumn('scopes_json', 'text', (col) => col.notNull().defaultTo('{}'))
     .addColumn('params_json', 'text', (col) => col.notNull())
     .addColumn('cursor', 'bigint', (col) => col.notNull())
@@ -30,21 +209,6 @@ export async function ensureClientSyncSchema<DB extends SyncClientDb>(
     .addColumn('updated_at', 'bigint', (col) => col.notNull())
     .execute();
 
-  await db.schema
-    .createIndex('idx_sync_subscription_state_state_sub')
-    .ifNotExists()
-    .on('sync_subscription_state')
-    .columns(['state_id', 'subscription_id'])
-    .unique()
-    .execute();
-
-  await db.schema
-    .createIndex('idx_sync_subscription_state_state')
-    .ifNotExists()
-    .on('sync_subscription_state')
-    .columns(['state_id', 'updated_at'])
-    .execute();
-
   await db.schema
     .createTable('sync_outbox_commits')
     .ifNotExists()
@@ -61,21 +225,6 @@ export async function ensureClientSyncSchema<DB extends SyncClientDb>(
     .addColumn('schema_version', 'integer', (col) => col.notNull().defaultTo(1))
     .execute();
 
-  await db.schema
-    .createIndex('idx_sync_outbox_commits_client_commit_id')
-    .ifNotExists()
-    .on('sync_outbox_commits')
-    .columns(['client_commit_id'])
-    .unique()
-    .execute();
-
-  await db.schema
-    .createIndex('idx_sync_outbox_commits_status_created_at')
-    .ifNotExists()
-    .on('sync_outbox_commits')
-    .columns(['status', 'created_at'])
-    .execute();
-
   await db.schema
     .createTable('sync_conflicts')
     .ifNotExists()
@@ -93,6 +242,39 @@ export async function ensureClientSyncSchema<DB extends SyncClientDb>(
     .addColumn('resolution', 'text')
     .execute();
 
+  // Apply framework-managed compatibility upgrades for legacy sync tables.
+  await ensureClientSyncSchemaCompat(db);
+
+  await db.schema
+    .createIndex('idx_sync_subscription_state_state_sub')
+    .ifNotExists()
+    .on('sync_subscription_state')
+    .columns(['state_id', 'subscription_id'])
+    .unique()
+    .execute();
+
+  await db.schema
+    .createIndex('idx_sync_subscription_state_state')
+    .ifNotExists()
+    .on('sync_subscription_state')
+    .columns(['state_id', 'updated_at'])
+    .execute();
+
+  await db.schema
+    .createIndex('idx_sync_outbox_commits_client_commit_id')
+    .ifNotExists()
+    .on('sync_outbox_commits')
+    .columns(['client_commit_id'])
+    .unique()
+    .execute();
+
+  await db.schema
+    .createIndex('idx_sync_outbox_commits_status_created_at')
+    .ifNotExists()
+    .on('sync_outbox_commits')
+    .columns(['status', 'created_at'])
+    .execute();
+
   await db.schema
     .createIndex('idx_sync_conflicts_outbox_commit')
     .ifNotExists()