@syncular/server 0.0.1-98 → 0.0.2-126

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,
@@ -69,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;
@@ -88,7 +99,7 @@ export interface CreateServerHandlerOptions<
    * ]
    * ```
    */
-  scopes: SimpleScopeDefinition[];
+  scopes: ScopeDefs;
 
   /** Primary key column name (default: 'id') */
   primaryKey?: string;
@@ -112,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.
@@ -130,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.
@@ -186,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
@@ -210,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);
@@ -252,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>,
@@ -308,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,
@@ -408,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 (
@@ -441,9 +531,9 @@ 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: [],
       };
@@ -558,9 +648,9 @@ export function createServerHandler<
     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,
@@ -582,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';