@syncular/server 0.0.6-159 → 0.0.6-167

package/src/blobs/migrate.ts

@@ -21,7 +21,8 @@ async function ensureBlobUploadsSchemaPostgres<DB extends SyncBlobUploadsDb>(
   await db.schema
     .createTable('sync_blob_uploads')
     .ifNotExists()
-    .addColumn('hash', 'text', (col) => col.primaryKey())
+    .addColumn('partition_id', 'text', (col) => col.notNull())
+    .addColumn('hash', 'text', (col) => col.notNull())
     .addColumn('size', 'bigint', (col) => col.notNull())
     .addColumn('mime_type', 'text', (col) => col.notNull())
     .addColumn('status', 'text', (col) => col.notNull())
@@ -31,20 +32,21 @@ async function ensureBlobUploadsSchemaPostgres<DB extends SyncBlobUploadsDb>(
     )
     .addColumn('expires_at', 'timestamptz', (col) => col.notNull())
     .addColumn('completed_at', 'timestamptz')
+    .addPrimaryKeyConstraint('pk_sync_blob_uploads', ['partition_id', 'hash'])
     .execute();
 
   await db.schema
     .createIndex('idx_sync_blob_uploads_status')
     .ifNotExists()
     .on('sync_blob_uploads')
-    .columns(['status'])
+    .columns(['partition_id', 'status'])
     .execute();
 
   await db.schema
     .createIndex('idx_sync_blob_uploads_expires_at')
     .ifNotExists()
     .on('sync_blob_uploads')
-    .columns(['expires_at'])
+    .columns(['partition_id', 'expires_at'])
     .execute();
 }
 
@@ -60,7 +62,8 @@ async function ensureBlobUploadsSchemasSqlite<DB extends SyncBlobUploadsDb>(
   await db.schema
     .createTable('sync_blob_uploads')
     .ifNotExists()
-    .addColumn('hash', 'text', (col) => col.primaryKey())
+    .addColumn('partition_id', 'text', (col) => col.notNull())
+    .addColumn('hash', 'text', (col) => col.notNull())
     .addColumn('size', 'integer', (col) => col.notNull())
     .addColumn('mime_type', 'text', (col) => col.notNull())
     .addColumn('status', 'text', (col) => col.notNull())
@@ -70,20 +73,21 @@ async function ensureBlobUploadsSchemasSqlite<DB extends SyncBlobUploadsDb>(
     )
     .addColumn('expires_at', 'text', (col) => col.notNull())
     .addColumn('completed_at', 'text')
+    .addPrimaryKeyConstraint('pk_sync_blob_uploads', ['partition_id', 'hash'])
     .execute();
 
   await db.schema
     .createIndex('idx_sync_blob_uploads_status')
     .ifNotExists()
     .on('sync_blob_uploads')
-    .columns(['status'])
+    .columns(['partition_id', 'status'])
     .execute();
 
   await db.schema
     .createIndex('idx_sync_blob_uploads_expires_at')
     .ifNotExists()
     .on('sync_blob_uploads')
-    .columns(['expires_at'])
+    .columns(['partition_id', 'expires_at'])
     .execute();
 }
 
@@ -103,13 +107,15 @@ export async function ensureBlobStorageSchemaPostgres<DB extends SyncBlobDb>(
   await db.schema
     .createTable('sync_blobs')
     .ifNotExists()
-    .addColumn('hash', 'text', (col) => col.primaryKey())
+    .addColumn('partition_id', 'text', (col) => col.notNull())
+    .addColumn('hash', 'text', (col) => col.notNull())
     .addColumn('size', 'bigint', (col) => col.notNull())
     .addColumn('mime_type', 'text', (col) => col.notNull())
     .addColumn('body', 'bytea', (col) => col.notNull())
     .addColumn('created_at', 'timestamptz', (col) =>
       col.notNull().defaultTo(sql`now()`)
     )
+    .addPrimaryKeyConstraint('pk_sync_blobs', ['partition_id', 'hash'])
     .execute();
 }
 
@@ -129,13 +135,15 @@ export async function ensureBlobStorageSchemaSqlite<DB extends SyncBlobDb>(
   await db.schema
     .createTable('sync_blobs')
     .ifNotExists()
-    .addColumn('hash', 'text', (col) => col.primaryKey())
+    .addColumn('partition_id', 'text', (col) => col.notNull())
+    .addColumn('hash', 'text', (col) => col.notNull())
     .addColumn('size', 'integer', (col) => col.notNull())
     .addColumn('mime_type', 'text', (col) => col.notNull())
     .addColumn('body', 'blob', (col) => col.notNull())
     .addColumn('created_at', 'text', (col) =>
       col.notNull().defaultTo(sql`(datetime('now'))`)
     )
+    .addPrimaryKeyConstraint('pk_sync_blobs', ['partition_id', 'hash'])
     .execute();
 }
 

package/src/blobs/types.ts

@@ -13,6 +13,8 @@ import type { Generated } from 'kysely';
  * Tracks initiated uploads and their completion status.
  */
 export interface SyncBlobUploadsTable {
+  /** Partition/tenant namespace */
+  partition_id: string;
   /** SHA-256 hash with prefix: "sha256:<hex>" */
   hash: string;
   /** Expected size in bytes */
@@ -44,6 +46,8 @@ export interface SyncBlobUploadsDb {
  * Stores blob content directly in the database.
  */
 export interface SyncBlobsTable {
+  /** Partition/tenant namespace */
+  partition_id: string;
   /** SHA-256 hash with prefix: "sha256:<hex>" */
   hash: string;
   /** Size in bytes */

package/src/dialect/helpers.ts

@@ -5,6 +5,7 @@
  */
 
 import type { StoredScopes } from '@syncular/core';
+import type { ServerSyncDialect } from './types';
 
 export function coerceNumber(value: unknown): number | null {
   if (value === null || value === undefined) return null;
@@ -24,6 +25,24 @@ export function coerceIsoString(value: unknown): string {
   return String(value);
 }
 
+export function parseJsonValue(value: unknown): unknown {
+  if (typeof value !== 'string') return value;
+  try {
+    return JSON.parse(value);
+  } catch {
+    return value;
+  }
+}
+
+export function toDialectJsonValue(
+  dialect: Pick<ServerSyncDialect, 'family'>,
+  value: unknown
+): unknown {
+  if (value === null || value === undefined) return null;
+  if (dialect.family === 'sqlite') return JSON.stringify(value);
+  return value;
+}
+
 export function parseScopes(value: unknown): StoredScopes {
   if (value === null || value === undefined) return {};
   if (typeof value === 'object' && !Array.isArray(value)) {

package/src/handlers/collection.ts

@@ -1,3 +1,8 @@
+import {
+  assertKnownTableDependencies,
+  createTableLookup,
+  topologicallySortTablesByDependencies,
+} from '@syncular/core';
 import type { SyncCoreDb } from '../schema';
 import type { ServerTableHandler, SyncServerAuth } from './types';
 
@@ -13,101 +18,27 @@ export function createServerHandlerCollection<
   DB extends SyncCoreDb = SyncCoreDb,
   Auth extends SyncServerAuth = SyncServerAuth,
 >(handlers: ServerTableHandler<DB, Auth>[]): ServerHandlerCollection<DB, Auth> {
-  const byTable = new Map<string, ServerTableHandler<DB, Auth>>();
-
-  for (const handler of handlers) {
-    if (byTable.has(handler.table)) {
-      throw new Error(`Table "${handler.table}" is already registered`);
-    }
-    byTable.set(handler.table, handler);
-  }
-
-  for (const handler of handlers) {
-    for (const dep of handler.dependsOn ?? []) {
-      if (!byTable.has(dep)) {
-        throw new Error(
-          `Table "${handler.table}" depends on unknown table "${dep}"`
-        );
-      }
-    }
-  }
+  const byTable = createTableLookup(
+    handlers,
+    (table) => `Table "${table}" is already registered`
+  );
+  assertKnownTableDependencies(
+    handlers,
+    byTable,
+    (table, dependency) =>
+      `Table "${table}" depends on unknown table "${dependency}"`
+  );
 
   return { handlers, byTable };
 }
 
-export function getServerHandler<
-  DB extends SyncCoreDb = SyncCoreDb,
-  Auth extends SyncServerAuth = SyncServerAuth,
->(
-  collection: ServerHandlerCollection<DB, Auth>,
-  table: string
-): ServerTableHandler<DB, Auth> | undefined {
-  return collection.byTable.get(table);
-}
-
-export function getServerHandlerOrThrow<
-  DB extends SyncCoreDb = SyncCoreDb,
-  Auth extends SyncServerAuth = SyncServerAuth,
->(
-  collection: ServerHandlerCollection<DB, Auth>,
-  table: string
-): ServerTableHandler<DB, Auth> {
-  const handler = collection.byTable.get(table);
-  if (!handler) throw new Error(`Unknown table: ${table}`);
-  return handler;
-}
-
-function topoSortTables<
-  DB extends SyncCoreDb = SyncCoreDb,
-  Auth extends SyncServerAuth = SyncServerAuth,
->(
-  collection: ServerHandlerCollection<DB, Auth>,
-  targetTable?: string
-): ServerTableHandler<DB, Auth>[] {
-  const visited = new Set<string>();
-  const visiting = new Set<string>();
-  const sorted: ServerTableHandler<DB, Auth>[] = [];
-
-  const visit = (table: string) => {
-    if (visited.has(table)) return;
-    if (visiting.has(table)) {
-      throw new Error(
-        `Circular dependency detected involving table "${table}"`
-      );
-    }
-
-    const handler = collection.byTable.get(table);
-    if (!handler) {
-      throw new Error(`Unknown table: ${table}`);
-    }
-
-    visiting.add(table);
-    for (const dep of handler.dependsOn ?? []) {
-      visit(dep);
-    }
-    visiting.delete(table);
-    visited.add(table);
-    sorted.push(handler);
-  };
-
-  if (targetTable) {
-    visit(targetTable);
-    return sorted;
-  }
-
-  for (const table of collection.byTable.keys()) {
-    visit(table);
-  }
-  return sorted;
-}
-
 export function getServerBootstrapOrder<
   DB extends SyncCoreDb = SyncCoreDb,
   Auth extends SyncServerAuth = SyncServerAuth,
 >(
   collection: ServerHandlerCollection<DB, Auth>
 ): ServerTableHandler<DB, Auth>[] {
-  return topoSortTables(collection);
+  return topologicallySortTablesByDependencies(collection.byTable);
 }
 
 export function getServerBootstrapOrderFor<
@@ -117,5 +48,5 @@ export function getServerBootstrapOrderFor<
   collection: ServerHandlerCollection<DB, Auth>,
   table: string
 ): ServerTableHandler<DB, Auth>[] {
-  return topoSortTables(collection, table);
+  return topologicallySortTablesByDependencies(collection.byTable, table);
 }

package/src/handlers/create-handler.ts

@@ -3,7 +3,6 @@
  */
 
 import type {
-  ScopePattern,
   ScopeValues,
   ScopeValuesFromPatterns,
   ScopeDefinition as SimpleScopeDefinition,
@@ -15,9 +14,8 @@ import {
   applyCodecsToDbRow,
   type ColumnCodecDialect,
   type ColumnCodecSource,
-  extractScopeVars,
-  normalizeScopes,
-  toTableColumnCodecs,
+  createSingleVariableScopeMetadata,
+  createTableColumnCodecsResolver,
 } from '@syncular/core';
 import type {
   DeleteQueryBuilder,
@@ -77,11 +75,6 @@ function isMissingColumnReferenceError(message: string): boolean {
   );
 }
 
-/**
- * Scope definition for a column - maps scope variable to column name.
- */
-export type ScopeColumnMap = Record<string, string>;
-
 /**
  * Options for creating a declarative server handler.
  */
@@ -274,44 +267,16 @@ export function createServerHandler<
     authorize,
     extractScopes: customExtractScopes,
   } = options;
-  const codecCache = new Map<string, ReturnType<typeof toTableColumnCodecs>>();
+  const resolveRowCodecs = createTableColumnCodecsResolver(codecs, {
+    dialect: codecDialect,
+  });
   const primaryKeyColumn = primaryKey as keyof ServerDB[TableName] & string;
   const qualifiedVersionRef = `${table}.${versionColumn}`;
-  const resolveTableCodecs = (row: Record<string, unknown>) => {
-    if (!codecs) 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, codecs, columns, {
-      dialect: codecDialect,
-    });
-    codecCache.set(cacheKey, resolved);
-    return resolved;
-  };
+  const resolveTableCodecs = (row: Record<string, unknown>) =>
+    resolveRowCodecs(table, row);
 
-  // Normalize scopes to pattern map and extract patterns/columns
-  const scopeColumnMap = normalizeScopes(scopeDefs);
-  const scopePatterns = Object.keys(scopeColumnMap) as ScopePattern[];
-  const scopeColumns: ScopeColumnMap = {};
-
-  for (const [pattern, columnName] of Object.entries(scopeColumnMap)) {
-    const vars = extractScopeVars(pattern);
-    if (vars.length !== 1) {
-      throw new Error(
-        `Scope pattern "${pattern}" must contain exactly one placeholder (got ${vars.length}).`
-      );
-    }
-    const varName = vars[0]!;
-    const existing = scopeColumns[varName];
-    if (existing && existing !== columnName) {
-      throw new Error(
-        `Scope variable "${varName}" is mapped to multiple columns: "${existing}" and "${columnName}".`
-      );
-    }
-    scopeColumns[varName] = columnName;
-  }
+  const { scopePatterns, scopeColumnsByVariable: scopeColumns } =
+    createSingleVariableScopeMetadata(scopeDefs);
 
   // Default extractScopes from scope columns
   const defaultExtractScopes = (row: Record<string, unknown>): StoredScopes => {

package/src/notify.ts

@@ -10,6 +10,7 @@
 
 import { randomId } from '@syncular/core';
 import type { Insertable, Kysely } from 'kysely';
+import { coerceNumber, toDialectJsonValue } from './dialect/helpers';
 import type { ServerSyncDialect } from './dialect/types';
 import type { SyncCoreDb } from './schema';
 
@@ -19,31 +20,6 @@ import type { SyncCoreDb } from './schema';
  */
 export const EXTERNAL_CLIENT_ID = '__external__';
 
-function toDialectJsonValue(
-  dialect: ServerSyncDialect,
-  value: unknown
-): unknown {
-  if (value === null || value === undefined) return null;
-  if (dialect.family === 'sqlite') return JSON.stringify(value);
-  return value;
-}
-
-function coerceNumber(value: unknown): number | null {
-  if (value === null || value === undefined) return null;
-  if (typeof value === 'number') {
-    return Number.isFinite(value) ? value : null;
-  }
-  if (typeof value === 'bigint') {
-    const coerced = Number(value);
-    return Number.isFinite(coerced) ? coerced : null;
-  }
-  if (typeof value === 'string') {
-    const coerced = Number(value);
-    return Number.isFinite(coerced) ? coerced : null;
-  }
-  return null;
-}
-
 export interface NotifyExternalDataChangeArgs<DB extends SyncCoreDb> {
   db: Kysely<DB>;
   dialect: ServerSyncDialect;
@@ -80,8 +56,11 @@ export async function notifyExternalDataChange<DB extends SyncCoreDb>(
   const { db, dialect, tables } = args;
   const partitionId = args.partitionId ?? 'default';
   const actorId = args.actorId ?? EXTERNAL_CLIENT_ID;
+  const uniqueTables = Array.from(
+    new Set(tables.filter((table) => typeof table === 'string'))
+  );
 
-  if (tables.length === 0) {
+  if (uniqueTables.length === 0) {
     throw new Error('notifyExternalDataChange: tables must not be empty');
   }
 
@@ -103,7 +82,7 @@ export async function notifyExternalDataChange<DB extends SyncCoreDb>(
       meta: null,
       result_json: toDialectJsonValue(dialect, { ok: true, status: 'applied' }),
       change_count: 0,
-      affected_tables: dialect.arrayToDb(tables) as string[],
+      affected_tables: dialect.arrayToDb(uniqueTables) as string[],
     };
 
     let commitSeq = 0;
@@ -136,7 +115,7 @@ export async function notifyExternalDataChange<DB extends SyncCoreDb>(
 
     // 2. Insert sync_table_commits entries for each affected table
     const tableCommits: Array<Insertable<SyncCoreDb['sync_table_commits']>> =
-      tables.map((table) => ({
+      uniqueTables.map((table) => ({
         partition_id: partitionId,
         table,
         commit_seq: commitSeq,
@@ -150,21 +129,17 @@ export async function notifyExternalDataChange<DB extends SyncCoreDb>(
       )
       .execute();
 
-    // 3. Delete cached snapshot chunks for affected tables
-    let deletedChunks = 0;
-    for (const table of tables) {
-      const result = await syncTrx
-        .deleteFrom('sync_snapshot_chunks')
-        .where('partition_id', '=', partitionId)
-        .where('scope', '=', table)
-        .executeTakeFirst();
-
-      deletedChunks += Number(result?.numDeletedRows ?? 0);
-    }
+    // 3. Delete cached snapshot chunks for affected tables.
+    const deletedResult = await syncTrx
+      .deleteFrom('sync_snapshot_chunks')
+      .where('partition_id', '=', partitionId)
+      .where('scope', 'in', uniqueTables)
+      .executeTakeFirst();
+    const deletedChunks = Number(deletedResult?.numDeletedRows ?? 0);
 
     return {
       commitSeq,
-      tables,
+      tables: uniqueTables,
       deletedChunks,
     };
   });

package/src/proxy/collection.ts

@@ -1,3 +1,4 @@
+import { createTableLookup } from '@syncular/core';
 import type { ProxyTableHandler } from './types';
 
 export interface ProxyHandlerCollection {
@@ -8,32 +9,9 @@ export interface ProxyHandlerCollection {
 export function createProxyHandlerCollection(
   handlers: ProxyTableHandler[]
 ): ProxyHandlerCollection {
-  const byTable = new Map<string, ProxyTableHandler>();
-  for (const handler of handlers) {
-    if (byTable.has(handler.table)) {
-      throw new Error(
-        `Proxy table handler already registered: ${handler.table}`
-      );
-    }
-    byTable.set(handler.table, handler);
-  }
+  const byTable = createTableLookup(
+    handlers,
+    (table) => `Proxy table handler already registered: ${table}`
+  );
   return { handlers, byTable };
 }
-
-export function getProxyHandler(
-  collection: ProxyHandlerCollection,
-  tableName: string
-): ProxyTableHandler | undefined {
-  return collection.byTable.get(tableName);
-}
-
-export function getProxyHandlerOrThrow(
-  collection: ProxyHandlerCollection,
-  tableName: string
-): ProxyTableHandler {
-  const handler = collection.byTable.get(tableName);
-  if (!handler) {
-    throw new Error(`No proxy table handler for table: ${tableName}`);
-  }
-  return handler;
-}

package/src/proxy/handler.ts

@@ -8,7 +8,7 @@ import type { Kysely, RawBuilder } from 'kysely';
 import { sql } from 'kysely';
 import type { ServerSyncDialect } from '../dialect/types';
 import type { SyncCoreDb } from '../schema';
-import { getProxyHandler, type ProxyHandlerCollection } from './collection';
+import type { ProxyHandlerCollection } from './collection';
 import {
   appendReturning,
   detectMutation,
@@ -111,7 +111,7 @@ export async function executeProxyQuery<DB extends SyncCoreDb>(
   }
 
   // Check if this table has a registered handler
-  const handler = getProxyHandler(handlers, mutation.tableName);
+  const handler = handlers.byTable.get(mutation.tableName);
   if (!handler) {
     // No handler registered - execute without oplog
     // This allows proxy operations on non-synced tables

package/src/proxy/index.ts

@@ -8,8 +8,6 @@
 // Collections
 export {
   createProxyHandlerCollection,
-  getProxyHandler,
-  getProxyHandlerOrThrow,
   type ProxyHandlerCollection,
 } from './collection';
 // Query execution

package/src/proxy/oplog.ts

@@ -6,19 +6,11 @@
 
 import { randomId, type SyncOp } from '@syncular/core';
 import { type Kysely, sql } from 'kysely';
+import { toDialectJsonValue } from '../dialect/helpers';
 import type { ServerSyncDialect } from '../dialect/types';
 import type { SyncCoreDb } from '../schema';
 import type { ProxyTableHandler } from './types';
 
-function toDialectJsonValue(
-  dialect: ServerSyncDialect,
-  value: unknown
-): unknown {
-  if (value === null || value === undefined) return null;
-  if (dialect.family === 'sqlite') return JSON.stringify(value);
-  return value;
-}
-
 /**
  * Create oplog entries for affected rows.
  *

package/src/prune.ts

@@ -18,22 +18,11 @@ import type {
   SqlBool,
 } from 'kysely';
 import { sql } from 'kysely';
+import { coerceNumber } from './dialect/helpers';
 import type { SyncCoreDb } from './schema';
 
 type EmptySelection = Record<string, never>;
 
-function coerceNumber(value: unknown): number | null {
-  if (value === null || value === undefined) return null;
-  if (typeof value === 'number') return Number.isFinite(value) ? value : null;
-  if (typeof value === 'bigint')
-    return Number.isFinite(Number(value)) ? Number(value) : null;
-  if (typeof value === 'string') {
-    const n = Number(value);
-    return Number.isFinite(n) ? n : null;
-  }
-  return null;
-}
-
 export interface PruneOptions {
   /** Clients with updated_at older than this are ignored for watermark. Default: 14 days. */
   activeWindowMs?: number;