@syncular/server 0.0.1 → 0.0.2-127

package/src/{shapes → handlers}/create-handler.ts

@@ -5,11 +5,20 @@
 import type {
   ScopePattern,
   ScopeValues,
+  ScopeValuesFromPatterns,
   ScopeDefinition as SimpleScopeDefinition,
   StoredScopes,
   SyncOperation,
 } from '@syncular/core';
-import { extractScopeVars, normalizeScopes } from '@syncular/core';
+import {
+  applyCodecsFromDbRow,
+  applyCodecsToDbRow,
+  type ColumnCodecDialect,
+  type ColumnCodecSource,
+  extractScopeVars,
+  normalizeScopes,
+  toTableColumnCodecs,
+} from '@syncular/core';
 import type {
   DeleteQueryBuilder,
   DeleteResult,
@@ -39,6 +48,24 @@ type AuthorizeResult =
   | true
   | { error: string; code: string; retriable?: boolean };
 
+function classifyConstraintViolationCode(message: string): string {
+  const normalized = message.toLowerCase();
+  if (normalized.includes('not null')) return 'NOT_NULL_CONSTRAINT';
+  if (normalized.includes('unique')) return 'UNIQUE_CONSTRAINT';
+  if (normalized.includes('foreign key')) return 'FOREIGN_KEY_CONSTRAINT';
+  return 'CONSTRAINT_VIOLATION';
+}
+
+function isConstraintViolationError(message: string): boolean {
+  const normalized = message.toLowerCase();
+  return (
+    normalized.includes('constraint') ||
+    normalized.includes('not null') ||
+    normalized.includes('foreign key') ||
+    normalized.includes('unique')
+  );
+}
+
 /**
  * Scope definition for a column - maps scope variable to column name.
  */
@@ -51,6 +78,8 @@ export interface CreateServerHandlerOptions<
   ServerDB extends SyncCoreDb,
   ClientDB,
   TableName extends keyof ServerDB & keyof ClientDB & string,
+  ScopeDefs extends
+    readonly SimpleScopeDefinition[] = readonly SimpleScopeDefinition[],
 > {
   /** Table name in the database */
   table: TableName;
@@ -70,7 +99,7 @@ export interface CreateServerHandlerOptions<
    * ]
    * ```
    */
-  scopes: SimpleScopeDefinition[];
+  scopes: ScopeDefs;
 
   /** Primary key column name (default: 'id') */
   primaryKey?: string;
@@ -94,7 +123,9 @@ export interface CreateServerHandlerOptions<
    *   project_id: await getProjectsForUser(ctx.db, ctx.actorId),
    * })
    */
-  resolveScopes: (ctx: ServerContext<ServerDB>) => Promise<ScopeValues>;
+  resolveScopes: (
+    ctx: ServerContext<ServerDB>
+  ) => Promise<ScopeValuesFromPatterns<ScopeDefs>>;
 
   /**
    * Transform inbound row from client to server format.
@@ -112,6 +143,20 @@ export interface CreateServerHandlerOptions<
     row: Selectable<ServerDB[TableName]>
   ) => ClientDB[TableName];
 
+  /**
+   * Optional column codec resolver.
+   * Receives `{ table, column, sqlType?, dialect? }` and returns a codec.
+   * Only used by default snapshot/apply paths when the corresponding
+   * transform hook is not provided.
+   */
+  columnCodecs?: ColumnCodecSource;
+
+  /**
+   * Dialect used for codec dialect overrides.
+   * Default: 'sqlite'
+   */
+  codecDialect?: ColumnCodecDialect;
+
   /**
    * Authorize an operation before applying.
    * Return true to allow, or an error object to reject.
@@ -168,8 +213,10 @@ export function createServerHandler<
   ServerDB extends SyncCoreDb,
   ClientDB,
   TableName extends keyof ServerDB & keyof ClientDB & string,
+  ScopeDefs extends
+    readonly SimpleScopeDefinition[] = readonly SimpleScopeDefinition[],
 >(
-  options: CreateServerHandlerOptions<ServerDB, ClientDB, TableName>
+  options: CreateServerHandlerOptions<ServerDB, ClientDB, TableName, ScopeDefs>
 ): ServerTableHandler<ServerDB> {
   type OverloadParameters<T> = T extends (...args: infer A) => unknown
     ? A
@@ -192,9 +239,25 @@ export function createServerHandler<
     resolveScopes,
     transformInbound,
     transformOutbound,
+    columnCodecs,
+    codecDialect = 'sqlite',
     authorize,
     extractScopes: customExtractScopes,
   } = options;
+  const codecCache = new Map<string, ReturnType<typeof toTableColumnCodecs>>();
+  const resolveTableCodecs = (row: Record<string, unknown>) => {
+    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 and extract patterns/columns
   const scopeColumnMap = normalizeScopes(scopeDefs);
@@ -234,6 +297,53 @@ export function createServerHandler<
 
   const extractScopesImpl = customExtractScopes ?? defaultExtractScopes;
 
+  const resolveScopesImpl = async (
+    ctx: ServerContext<ServerDB>
+  ): Promise<ScopeValues> => {
+    const resolved = await resolveScopes(ctx);
+    const normalized: ScopeValues = {};
+    for (const [scopeKey, scopeValue] of Object.entries(resolved)) {
+      if (typeof scopeValue === 'string' || Array.isArray(scopeValue)) {
+        normalized[scopeKey] = scopeValue;
+      }
+    }
+    return normalized;
+  };
+
+  const applyOutboundTransform = (
+    row: Selectable<ServerDB[TableName]>
+  ): ClientDB[TableName] => {
+    if (transformOutbound) {
+      return transformOutbound(row);
+    }
+
+    const recordRow = row as Record<string, unknown>;
+    const transformed = applyCodecsFromDbRow(
+      recordRow,
+      resolveTableCodecs(recordRow),
+      codecDialect
+    );
+    return transformed as ClientDB[TableName];
+  };
+
+  const applyInboundTransform = (
+    row: Record<string, unknown>,
+    schemaVersion: number | undefined
+  ): Updateable<ServerDB[TableName]> => {
+    if (transformInbound) {
+      return transformInbound(row as ClientDB[TableName], {
+        schemaVersion,
+      });
+    }
+
+    const transformed = applyCodecsToDbRow(
+      row,
+      resolveTableCodecs(row),
+      codecDialect
+    );
+    return transformed as Updateable<ServerDB[TableName]>;
+  };
+
   // Default snapshot implementation
   const defaultSnapshot = async (
     ctx: ServerSnapshotContext<ServerDB>,
@@ -290,11 +400,9 @@ export function createServerHandler<
       : null;
 
     // Transform outbound if provided
-    const outputRows = transformOutbound
-      ? pageRows.map((r) =>
-          transformOutbound(r as Selectable<ServerDB[TableName]>)
-        )
-      : pageRows;
+    const outputRows = pageRows.map((r) =>
+      applyOutboundTransform(r as Selectable<ServerDB[TableName]>)
+    );
 
     return {
       rows: outputRows,
@@ -390,11 +498,11 @@ export function createServerHandler<
 
     // Handle upsert
     const rawPayload = op.payload ?? {};
-    const payload = transformInbound
-      ? transformInbound(rawPayload as ClientDB[TableName], {
-          schemaVersion: ctx.schemaVersion,
-        })
-      : (rawPayload as Updateable<ServerDB[TableName]>);
+    const payloadRecord =
+      rawPayload !== null && typeof rawPayload === 'object'
+        ? (rawPayload as Record<string, unknown>)
+        : {};
+    const payload = applyInboundTransform(payloadRecord, ctx.schemaVersion);
 
     // Check for existing row
     const existing = await (
@@ -423,9 +531,24 @@ export function createServerHandler<
           status: 'conflict',
           message: `Version conflict: server=${existingVersion}, base=${op.base_version}`,
           server_version: existingVersion,
-          server_row: transformOutbound
-            ? transformOutbound(existing as Selectable<ServerDB[TableName]>)
-            : existing,
+          server_row: applyOutboundTransform(
+            existing as Selectable<ServerDB[TableName]>
+          ),
+        },
+        emittedChanges: [],
+      };
+    }
+
+    // If the client provided a base version, they expected this row to exist.
+    // A missing row usually indicates stale local state after a server reset.
+    if (!existing && op.base_version != null) {
+      return {
+        result: {
+          opIndex,
+          status: 'error',
+          error: 'ROW_NOT_FOUND_FOR_BASE_VERSION',
+          code: 'ROW_MISSING',
+          retriable: false,
         },
         emittedChanges: [],
       };
@@ -433,69 +556,101 @@ export function createServerHandler<
 
     const nextVersion = existingVersion + 1;
 
-    if (existing) {
-      // Update - merge payload with existing
-      const updateSet: Record<string, unknown> = {
-        ...payload,
-        [versionColumn]: nextVersion,
-      };
-      // Don't update primary key or scope columns
-      delete updateSet[primaryKey];
-      for (const col of Object.values(scopeColumns)) {
-        delete updateSet[col];
+    let updated: Record<string, unknown> | undefined;
+    let constraintError: { message: string; code: string } | null = null;
+
+    try {
+      if (existing) {
+        // Update - merge payload with existing
+        const updateSet: Record<string, unknown> = {
+          ...payload,
+          [versionColumn]: nextVersion,
+        };
+        // Don't update primary key or scope columns
+        delete updateSet[primaryKey];
+        for (const col of Object.values(scopeColumns)) {
+          delete updateSet[col];
+        }
+
+        await (
+          trx.updateTable(table) as UpdateQueryBuilder<
+            ServerDB,
+            TableName,
+            TableName,
+            UpdateResult
+          >
+        )
+          .set(updateSet as UpdateSetObject)
+          .where(ref<string>(primaryKey), '=', op.row_id)
+          .execute();
+      } else {
+        // Insert
+        const insertValues: Record<string, unknown> = {
+          ...payload,
+          [primaryKey]: op.row_id,
+          [versionColumn]: 1,
+        };
+
+        await (
+          trx.insertInto(table) as InsertQueryBuilder<
+            ServerDB,
+            TableName,
+            InsertResult
+          >
+        )
+          .values(insertValues as Insertable<ServerDB[TableName]>)
+          .execute();
       }
 
-      await (
-        trx.updateTable(table) as UpdateQueryBuilder<
+      // Read back the updated row
+      updated = await (
+        trx.selectFrom(table).selectAll() as SelectQueryBuilder<
           ServerDB,
-          TableName,
-          TableName,
-          UpdateResult
+          keyof ServerDB & string,
+          Record<string, unknown>
         >
       )
-        .set(updateSet as UpdateSetObject)
         .where(ref<string>(primaryKey), '=', op.row_id)
-        .execute();
-    } else {
-      // Insert
-      const insertValues: Record<string, unknown> = {
-        ...payload,
-        [primaryKey]: op.row_id,
-        [versionColumn]: 1,
+        .executeTakeFirstOrThrow();
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      if (!isConstraintViolationError(message)) {
+        throw err;
+      }
+
+      constraintError = {
+        message,
+        code: classifyConstraintViolationCode(message),
       };
+    }
 
-      await (
-        trx.insertInto(table) as InsertQueryBuilder<
-          ServerDB,
-          TableName,
-          InsertResult
-        >
-      )
-        .values(insertValues as Insertable<ServerDB[TableName]>)
-        .execute();
+    if (constraintError) {
+      return {
+        result: {
+          opIndex,
+          status: 'error',
+          error: constraintError.message,
+          code: constraintError.code,
+          retriable: false,
+        },
+        emittedChanges: [],
+      };
     }
 
-    // Read back the updated row
-    const updated = await (
-      trx.selectFrom(table).selectAll() as SelectQueryBuilder<
-        ServerDB,
-        keyof ServerDB & string,
-        Record<string, unknown>
-      >
-    )
-      .where(ref<string>(primaryKey), '=', op.row_id)
-      .executeTakeFirstOrThrow();
+    if (!updated) {
+      throw new Error('Updated row is missing after applyOperation');
+    }
 
-    const updatedRow = updated as Record<string, unknown>;
+    const updatedRow = updated;
     const rowVersion = (updatedRow[versionColumn] as number) ?? 1;
 
     // Extract scopes from updated row
     const scopes = extractScopesImpl(updatedRow);
 
     // Transform outbound for emitted change
-    const rowJson = transformOutbound
-      ? transformOutbound(updated as Selectable<ServerDB[TableName]>)
-      : updated;
+    const rowJson = applyOutboundTransform(
+      updated as Selectable<ServerDB[TableName]>
+    );
 
     const emitted: EmittedChange = {
       table,
@@ -517,7 +672,7 @@ export function createServerHandler<
     scopePatterns,
     dependsOn,
     snapshotChunkTtlMs,
-    resolveScopes,
+    resolveScopes: resolveScopesImpl,
     extractScopes: extractScopesImpl,
     snapshot: options.snapshot ?? defaultSnapshot,
     applyOperation: options.applyOperation ?? defaultApplyOperation,

package/src/{shapes → handlers}/types.ts

@@ -1,6 +1,7 @@
 import type {
   ScopePattern,
   ScopeValues,
+  ScopeValuesForKeys,
   StoredScopes,
   SyncOp,
   SyncOperation,
@@ -50,12 +51,14 @@ export interface ServerContext<DB extends SyncCoreDb = SyncCoreDb> {
 /**
  * Context passed to snapshot method.
  */
-export interface ServerSnapshotContext<DB extends SyncCoreDb = SyncCoreDb>
-  extends ServerContext<DB> {
+export interface ServerSnapshotContext<
+  DB extends SyncCoreDb = SyncCoreDb,
+  ScopeKeys extends string = string,
+> extends ServerContext<DB> {
   /** Database executor for the snapshot */
   db: DbExecutor<DB>;
   /** Effective scope values for this subscription */
-  scopeValues: ScopeValues;
+  scopeValues: ScopeValuesForKeys<ScopeKeys>;
   /** Pagination cursor (row_id for keyset pagination) */
   cursor: string | null;
   /** Max rows to return */
@@ -120,9 +123,9 @@ interface ServerScopeConfig {
 }
 
 /**
- * Server shape options - configuration for a table's sync behavior.
+ * Server handler options - configuration for a table's sync behavior.
  */
-export interface ServerShapeOptions<
+export interface ServerHandlerOptions<
   DB extends SyncCoreDb = SyncCoreDb,
   Scopes extends Record<ScopePattern, Record<string, string>> = Record<
     ScopePattern,
@@ -132,7 +135,7 @@ export interface ServerShapeOptions<
   Params extends ZodSchema = ZodSchema,
 > {
   /**
-   * Scope patterns this shape uses.
+   * Scope patterns this handler uses.
    * Array of pattern keys from SharedScopes.
    */
   scopes: (keyof Scopes)[];
@@ -225,7 +228,7 @@ export interface ServerTableHandler<DB extends SyncCoreDb = SyncCoreDb> {
   /** Table name */
   table: string;
 
-  /** Scope patterns used by this shape */
+  /** Scope patterns used by this handler */
   scopePatterns: ScopePattern[];
 
   /**

package/src/helpers/conflict.ts

@@ -4,7 +4,7 @@
  * Helper for building conflict results in server table handlers.
  */
 
-import type { ApplyOperationResult } from '../shapes/types';
+import type { ApplyOperationResult } from '../handlers/types';
 
 export interface BuildConflictResultArgs {
   /** Index of the operation in the batch */

package/src/helpers/emitted-change.ts

@@ -5,7 +5,7 @@
  */
 
 import type { StoredScopes } from '@syncular/core';
-import type { EmittedChange } from '../shapes/types';
+import type { EmittedChange } from '../handlers/types';
 
 export interface CreateEmittedChangeArgs {
   /** Table name */

package/src/index.ts

@@ -13,15 +13,16 @@ export * from './blobs';
 export * from './clients';
 export * from './compaction';
 export * from './dialect';
+export * from './handlers';
 export * from './helpers';
 export * from './migrate';
+export * from './notify';
 export * from './proxy';
 export * from './prune';
 export * from './pull';
 export * from './push';
 export * from './realtime';
 export * from './schema';
-export * from './shapes';
 export * from './snapshot-chunks';
 export type { SnapshotChunkStorage } from './snapshot-chunks/types';
 export * from './stats';