@syncular/server 0.0.6-55 → 0.0.6-66

package/src/handlers/create-handler.ts

@@ -39,6 +39,7 @@ import type {
   ServerContext,
   ServerSnapshotContext,
   ServerTableHandler,
+  SyncServerAuth,
 } from './types';
 
 /**
@@ -78,6 +79,7 @@ export interface CreateServerHandlerOptions<
   ServerDB extends SyncCoreDb,
   ClientDB,
   TableName extends keyof ServerDB & keyof ClientDB & string,
+  Auth extends SyncServerAuth = SyncServerAuth,
   ScopeDefs extends
     readonly SimpleScopeDefinition[] = readonly SimpleScopeDefinition[],
 > {
@@ -124,7 +126,7 @@ export interface CreateServerHandlerOptions<
    * })
    */
   resolveScopes: (
-    ctx: ServerContext<ServerDB>
+    ctx: ServerContext<ServerDB, Auth>
   ) => Promise<ScopeValuesFromPatterns<ScopeDefs>>;
 
   /**
@@ -132,7 +134,7 @@ export interface CreateServerHandlerOptions<
    * Use ctx.schemaVersion to handle older client versions.
    */
   transformInbound?: (
-    row: ClientDB[TableName],
+    row: Selectable<ClientDB[TableName]>,
     ctx: { schemaVersion?: number }
   ) => Updateable<ServerDB[TableName]>;
 
@@ -141,7 +143,7 @@ export interface CreateServerHandlerOptions<
    */
   transformOutbound?: (
     row: Selectable<ServerDB[TableName]>
-  ) => ClientDB[TableName];
+  ) => Selectable<ClientDB[TableName]>;
 
   /**
    * Optional column codec resolver.
@@ -162,19 +164,19 @@ export interface CreateServerHandlerOptions<
    * Return true to allow, or an error object to reject.
    */
   authorize?: (
-    ctx: ServerApplyOperationContext<ServerDB>,
+    ctx: ServerApplyOperationContext<ServerDB, Auth>,
     op: SyncOperation
   ) => Promise<AuthorizeResult>;
 
   /**
    * Override: Build snapshot query.
    */
-  snapshot?: ServerTableHandler<ServerDB>['snapshot'];
+  snapshot?: ServerTableHandler<ServerDB, Auth>['snapshot'];
 
   /**
    * Override: Apply operation.
    */
-  applyOperation?: ServerTableHandler<ServerDB>['applyOperation'];
+  applyOperation?: ServerTableHandler<ServerDB, Auth>['applyOperation'];
 
   /**
    * Custom scope extraction from row (for complex scope logic).
@@ -213,11 +215,18 @@ export function createServerHandler<
   ServerDB extends SyncCoreDb,
   ClientDB,
   TableName extends keyof ServerDB & keyof ClientDB & string,
+  Auth extends SyncServerAuth = SyncServerAuth,
   ScopeDefs extends
     readonly SimpleScopeDefinition[] = readonly SimpleScopeDefinition[],
 >(
-  options: CreateServerHandlerOptions<ServerDB, ClientDB, TableName, ScopeDefs>
-): ServerTableHandler<ServerDB> {
+  options: CreateServerHandlerOptions<
+    ServerDB,
+    ClientDB,
+    TableName,
+    Auth,
+    ScopeDefs
+  >
+): ServerTableHandler<ServerDB, Auth> {
   type OverloadParameters<T> = T extends (...args: infer A) => unknown
     ? A
     : never;
@@ -298,7 +307,7 @@ export function createServerHandler<
   const extractScopesImpl = customExtractScopes ?? defaultExtractScopes;
 
   const resolveScopesImpl = async (
-    ctx: ServerContext<ServerDB>
+    ctx: ServerContext<ServerDB, Auth>
   ): Promise<ScopeValues> => {
     const resolved = await resolveScopes(ctx);
     const normalized: ScopeValues = {};
@@ -312,7 +321,7 @@ export function createServerHandler<
 
   const applyOutboundTransform = (
     row: Selectable<ServerDB[TableName]>
-  ): ClientDB[TableName] => {
+  ): Selectable<ClientDB[TableName]> => {
     if (transformOutbound) {
       return transformOutbound(row);
     }
@@ -323,7 +332,7 @@ export function createServerHandler<
       resolveTableCodecs(recordRow),
       codecDialect
     );
-    return transformed as ClientDB[TableName];
+    return transformed as Selectable<ClientDB[TableName]>;
   };
 
   const applyInboundTransform = (
@@ -331,7 +340,7 @@ export function createServerHandler<
     schemaVersion: number | undefined
   ): Updateable<ServerDB[TableName]> => {
     if (transformInbound) {
-      return transformInbound(row as ClientDB[TableName], {
+      return transformInbound(row as Selectable<ClientDB[TableName]>, {
         schemaVersion,
       });
     }
@@ -346,7 +355,7 @@ export function createServerHandler<
 
   // Default snapshot implementation
   const defaultSnapshot = async (
-    ctx: ServerSnapshotContext<ServerDB>,
+    ctx: ServerSnapshotContext<ServerDB, string, Auth>,
     _params: Record<string, unknown> | undefined
   ): Promise<{ rows: unknown[]; nextCursor: string | null }> => {
     const trx = ctx.db;
@@ -415,7 +424,7 @@ export function createServerHandler<
 
   // Default applyOperation implementation
   const defaultApplyOperation = async (
-    ctx: ServerApplyOperationContext<ServerDB>,
+    ctx: ServerApplyOperationContext<ServerDB, Auth>,
     op: SyncOperation,
     opIndex: number
   ): Promise<ApplyOperationResult> => {

package/src/handlers/index.ts

@@ -1,3 +1,3 @@
+export * from './collection';
 export * from './create-handler';
-export * from './registry';
 export * from './types';

package/src/handlers/types.ts

@@ -11,6 +11,11 @@ import type { ZodSchema, z } from 'zod';
 import type { DbExecutor } from '../dialect/types';
 import type { SyncCoreDb } from '../schema';
 
+export interface SyncServerAuth {
+  actorId: string;
+  partitionId?: string;
+}
+
 /**
  * Emitted change to be stored in the oplog.
  * Uses JSONB scopes instead of scope_keys array.
@@ -41,11 +46,16 @@ export interface ApplyOperationResult {
 /**
  * Context for server operations.
  */
-export interface ServerContext<DB extends SyncCoreDb = SyncCoreDb> {
+export interface ServerContext<
+  DB extends SyncCoreDb = SyncCoreDb,
+  Auth extends SyncServerAuth = SyncServerAuth,
+> {
   /** Database connection (transaction in applyOperation) */
   db: DbExecutor<DB>;
   /** Actor ID (user ID from auth) */
   actorId: string;
+  /** Full auth payload returned by authenticate */
+  auth: Auth;
 }
 
 /**
@@ -54,7 +64,8 @@ export interface ServerContext<DB extends SyncCoreDb = SyncCoreDb> {
 export interface ServerSnapshotContext<
   DB extends SyncCoreDb = SyncCoreDb,
   ScopeKeys extends string = string,
-> extends ServerContext<DB> {
+  Auth extends SyncServerAuth = SyncServerAuth,
+> extends ServerContext<DB, Auth> {
   /** Database executor for the snapshot */
   db: DbExecutor<DB>;
   /** Effective scope values for this subscription */
@@ -68,8 +79,10 @@ export interface ServerSnapshotContext<
 /**
  * Context passed to applyOperation method.
  */
-export interface ServerApplyOperationContext<DB extends SyncCoreDb = SyncCoreDb>
-  extends ServerContext<DB> {
+export interface ServerApplyOperationContext<
+  DB extends SyncCoreDb = SyncCoreDb,
+  Auth extends SyncServerAuth = SyncServerAuth,
+> extends ServerContext<DB, Auth> {
   /** Database executor for the operation */
   trx: DbExecutor<DB>;
   /** Client/device identifier */
@@ -127,6 +140,7 @@ interface ServerScopeConfig {
  */
 export interface ServerHandlerOptions<
   DB extends SyncCoreDb = SyncCoreDb,
+  Auth extends SyncServerAuth = SyncServerAuth,
   Scopes extends Record<ScopePattern, Record<string, string>> = Record<
     ScopePattern,
     Record<string, string>
@@ -159,7 +173,7 @@ export interface ServerHandlerOptions<
    *   project_id: ctx.user.projectIds,
    * })
    */
-  resolveScopes: (ctx: ServerContext<DB>) => Promise<ScopeValues>;
+  resolveScopes: (ctx: ServerContext<DB, Auth>) => Promise<ScopeValues>;
 
   /**
    * Optional Zod schema for subscription parameters.
@@ -191,7 +205,7 @@ export interface ServerHandlerOptions<
    */
   transformInbound?: (
     payload: Record<string, unknown>,
-    ctx: ServerApplyOperationContext<DB>
+    ctx: ServerApplyOperationContext<DB, Auth>
   ) => Partial<DB[TableName & keyof DB]>;
 
   /**
@@ -206,7 +220,7 @@ export interface ServerHandlerOptions<
    * Default uses keyset pagination ordered by primary key.
    */
   snapshot?: (
-    ctx: ServerSnapshotContext<DB>,
+    ctx: ServerSnapshotContext<DB, string, Auth>,
     params: Params extends ZodSchema ? z.infer<Params> : undefined
   ) => Promise<{ rows: unknown[]; nextCursor: string | null }>;
 
@@ -214,7 +228,7 @@ export interface ServerHandlerOptions<
    * Custom apply operation implementation.
    */
   applyOperation?: (
-    ctx: ServerApplyOperationContext<DB>,
+    ctx: ServerApplyOperationContext<DB, Auth>,
     op: SyncOperation,
     opIndex: number
   ) => Promise<ApplyOperationResult>;
@@ -224,7 +238,10 @@ export interface ServerHandlerOptions<
  * Server-side table handler for snapshots and mutations.
  * This is the internal handler interface used by the sync engine.
  */
-export interface ServerTableHandler<DB extends SyncCoreDb = SyncCoreDb> {
+export interface ServerTableHandler<
+  DB extends SyncCoreDb = SyncCoreDb,
+  Auth extends SyncServerAuth = SyncServerAuth,
+> {
   /** Table name */
   table: string;
 
@@ -244,7 +261,7 @@ export interface ServerTableHandler<DB extends SyncCoreDb = SyncCoreDb> {
   /**
    * Resolve allowed scope values for the current actor.
    */
-  resolveScopes: (ctx: ServerContext<DB>) => Promise<ScopeValues>;
+  resolveScopes: (ctx: ServerContext<DB, Auth>) => Promise<ScopeValues>;
 
   /**
    * Extract stored scopes from a row.
@@ -255,7 +272,7 @@ export interface ServerTableHandler<DB extends SyncCoreDb = SyncCoreDb> {
    * Build a bootstrap snapshot page.
    */
   snapshot(
-    ctx: ServerSnapshotContext<DB>,
+    ctx: ServerSnapshotContext<DB, string, Auth>,
     params: Record<string, unknown> | undefined
   ): Promise<{ rows: unknown[]; nextCursor: string | null }>;
 
@@ -263,7 +280,7 @@ export interface ServerTableHandler<DB extends SyncCoreDb = SyncCoreDb> {
    * Apply a single operation.
    */
   applyOperation(
-    ctx: ServerApplyOperationContext<DB>,
+    ctx: ServerApplyOperationContext<DB, Auth>,
     op: SyncOperation,
     opIndex: number
   ): Promise<ApplyOperationResult>;

package/src/index.ts

@@ -27,3 +27,4 @@ export * from './snapshot-chunks';
 export type { SnapshotChunkStorage } from './snapshot-chunks/types';
 export * from './stats';
 export * from './subscriptions';
+export * from './sync';

package/src/notify.test.ts

@@ -1,8 +1,7 @@
 import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
 import { createBunSqliteDb } from '../../dialect-bun-sqlite/src';
 import { createSqliteServerDialect } from '../../server-dialect-sqlite/src';
-import { createServerHandler } from './handlers';
-import { TableRegistry } from './handlers/registry';
+import { createServerHandler, createServerHandlerCollection } from './handlers';
 import { ensureSyncSchema } from './migrate';
 import { EXTERNAL_CLIENT_ID, notifyExternalDataChange } from './notify';
 import { pull } from './pull';
@@ -227,15 +226,14 @@ describe('pull re-bootstrap after external data change', () => {
       resolveScopes: async () => ({ catalog_id: '*' }),
     });
 
-    const handlers = new TableRegistry<TestDb>();
-    handlers.register(codesHandler);
+    const handlers = createServerHandlerCollection<TestDb>([codesHandler]);
 
     // 1. Initial bootstrap pull
     const firstPull = await pull({
       db,
       dialect,
       handlers,
-      actorId: 'u1',
+      auth: { actorId: 'u1' },
       request: {
         clientId: 'client-1',
         limitCommits: 10,
@@ -262,7 +260,7 @@ describe('pull re-bootstrap after external data change', () => {
       db,
       dialect,
       handlers,
-      actorId: 'u1',
+      auth: { actorId: 'u1' },
       request: {
         clientId: 'client-1',
         limitCommits: 10,
@@ -296,7 +294,7 @@ describe('pull re-bootstrap after external data change', () => {
       db,
       dialect,
       handlers,
-      actorId: 'u1',
+      auth: { actorId: 'u1' },
       request: {
         clientId: 'client-1',
         limitCommits: 10,
@@ -341,16 +339,17 @@ describe('pull re-bootstrap after external data change', () => {
       resolveScopes: async () => ({ catalog_id: '*' }),
     });
 
-    const handlers = new TableRegistry<TestDb>();
-    handlers.register(tasksHandler);
-    handlers.register(codesHandler);
+    const handlers = createServerHandlerCollection<TestDb>([
+      tasksHandler,
+      codesHandler,
+    ]);
 
     // 1. Bootstrap pull for tasks
     const firstPull = await pull({
       db,
       dialect,
       handlers,
-      actorId: 'u1',
+      auth: { actorId: 'u1' },
       request: {
         clientId: 'client-1',
         limitCommits: 10,
@@ -382,7 +381,7 @@ describe('pull re-bootstrap after external data change', () => {
       db,
       dialect,
       handlers,
-      actorId: 'u1',
+      auth: { actorId: 'u1' },
       request: {
         clientId: 'client-1',
         limitCommits: 10,
@@ -437,16 +436,17 @@ describe('pull re-bootstrap after external data change', () => {
       resolveScopes: async () => ({ catalog_id: '*' }),
     });
 
-    const handlers = new TableRegistry<TestDb>();
-    handlers.register(tasksHandler);
-    handlers.register(codesHandler);
+    const handlers = createServerHandlerCollection<TestDb>([
+      tasksHandler,
+      codesHandler,
+    ]);
 
     // 1. Bootstrap both subscriptions
     const firstPull = await pull({
       db,
       dialect,
       handlers,
-      actorId: 'u1',
+      auth: { actorId: 'u1' },
       request: {
         clientId: 'client-1',
         limitCommits: 10,
@@ -480,7 +480,7 @@ describe('pull re-bootstrap after external data change', () => {
       db,
       dialect,
       handlers,
-      actorId: 'u1',
+      auth: { actorId: 'u1' },
       request: {
         clientId: 'client-1',
         limitCommits: 10,

package/src/proxy/collection.ts

@@ -0,0 +1,39 @@
+import type { ProxyTableHandler } from './types';
+
+export interface ProxyHandlerCollection {
+  handlers: ProxyTableHandler[];
+  byTable: ReadonlyMap<string, ProxyTableHandler>;
+}
+
+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);
+  }
+  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.test.ts

@@ -4,8 +4,8 @@ import { createBunSqliteDb } from '../../../dialect-bun-sqlite/src';
 import { createSqliteServerDialect } from '../../../server-dialect-sqlite/src';
 import { ensureSyncSchema } from '../migrate';
 import type { SyncCoreDb } from '../schema';
+import { createProxyHandlerCollection } from './collection';
 import { executeProxyQuery } from './handler';
-import { ProxyTableRegistry } from './registry';
 
 interface TasksTable {
   id: string;
@@ -21,12 +21,14 @@ interface ProxyTestDb extends SyncCoreDb {
 describe('executeProxyQuery', () => {
   let db: Kysely<ProxyTestDb>;
   const dialect = createSqliteServerDialect();
-  const handlers = new ProxyTableRegistry().register({
-    table: 'tasks',
-    computeScopes: (row) => ({
-      user_id: String(row.user_id),
-    }),
-  });
+  const handlers = createProxyHandlerCollection([
+    {
+      table: 'tasks',
+      computeScopes: (row) => ({
+        user_id: String(row.user_id),
+      }),
+    },
+  ]);
 
   beforeEach(async () => {
     db = createBunSqliteDb<ProxyTestDb>({ path: ':memory:' });

package/src/proxy/handler.ts

@@ -8,6 +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 {
   appendReturning,
   detectMutation,
@@ -15,7 +16,6 @@ import {
   hasReturningWildcard,
 } from './mutation-detector';
 import { createOplogEntries } from './oplog';
-import type { ProxyTableRegistry } from './registry';
 import type { ProxyQueryContext } from './types';
 
 export interface ExecuteProxyQueryArgs<DB extends SyncCoreDb = SyncCoreDb> {
@@ -23,8 +23,8 @@ export interface ExecuteProxyQueryArgs<DB extends SyncCoreDb = SyncCoreDb> {
   db: Kysely<DB>;
   /** Server sync dialect */
   dialect: ServerSyncDialect;
-  /** Proxy table registry for oplog generation */
-  handlers: ProxyTableRegistry;
+  /** Proxy table handlers for oplog generation */
+  handlers: ProxyHandlerCollection;
   /** Query context (actor/client IDs) */
   ctx: ProxyQueryContext;
   /** SQL query string */
@@ -111,7 +111,7 @@ export async function executeProxyQuery<DB extends SyncCoreDb>(
   }
 
   // Check if this table has a registered handler
-  const handler = handlers.get(mutation.tableName);
+  const handler = getProxyHandler(handlers, mutation.tableName);
   if (!handler) {
     // No handler registered - execute without oplog
     // This allows proxy operations on non-synced tables

package/src/proxy/index.ts

@@ -4,6 +4,14 @@
  * Server-side proxy functionality for database access.
  */
 
+// Oplog creation
+// Collections
+export {
+  createProxyHandlerCollection,
+  getProxyHandler,
+  getProxyHandlerOrThrow,
+  type ProxyHandlerCollection,
+} from './collection';
 // Query execution
 export {
   type ExecuteProxyQueryArgs,
@@ -12,7 +20,4 @@ export {
 } from './handler';
 // Mutation detection
 export { type DetectedMutation, detectMutation } from './mutation-detector';
-// Oplog creation
-// Registry
-export { ProxyTableRegistry } from './registry';
 // Types

package/src/pull.ts

@@ -22,7 +22,12 @@ import {
 } from '@syncular/core';
 import type { Kysely } from 'kysely';
 import type { DbExecutor, ServerSyncDialect } from './dialect/types';
-import type { TableRegistry } from './handlers/registry';
+import {
+  getServerBootstrapOrderFor,
+  getServerHandlerOrThrow,
+  type ServerHandlerCollection,
+} from './handlers/collection';
+import type { ServerTableHandler, SyncServerAuth } from './handlers/types';
 import { EXTERNAL_CLIENT_ID } from './notify';
 import type { SyncCoreDb } from './schema';
 import {
@@ -241,12 +246,14 @@ async function readExternalDataChanges<DB extends SyncCoreDb>(
   }));
 }
 
-export async function pull<DB extends SyncCoreDb>(args: {
+export async function pull<
+  DB extends SyncCoreDb,
+  Auth extends SyncServerAuth,
+>(args: {
   db: Kysely<DB>;
   dialect: ServerSyncDialect;
-  handlers: TableRegistry<DB>;
-  actorId: string;
-  partitionId?: string;
+  handlers: ServerHandlerCollection<DB, Auth>;
+  auth: Auth;
   request: SyncPullRequest;
   /**
    * Optional snapshot chunk storage adapter.
@@ -257,7 +264,7 @@ export async function pull<DB extends SyncCoreDb>(args: {
 }): Promise<PullResult> {
   const { request, dialect } = args;
   const db = args.db;
-  const partitionId = args.partitionId ?? 'default';
+  const partitionId = args.auth.partitionId ?? 'default';
   const requestedSubscriptionCount = Array.isArray(request.subscriptions)
     ? request.subscriptions.length
     : 0;
@@ -293,7 +300,7 @@ export async function pull<DB extends SyncCoreDb>(args: {
         // Resolve effective scopes for each subscription
         const resolved = await resolveEffectiveScopesForSubscriptions({
           db,
-          actorId: args.actorId,
+          auth: args.auth,
           subscriptions: request.subscriptions ?? [],
           handlers: args.handlers,
         });
@@ -347,7 +354,7 @@ export async function pull<DB extends SyncCoreDb>(args: {
           for (const sub of resolved) {
             const cursor = Math.max(-1, sub.cursor ?? -1);
             // Validate table handler exists (throws if not registered)
-            args.handlers.getOrThrow(sub.table);
+            getServerHandlerOrThrow(args.handlers, sub.table);
 
             if (
               sub.status === 'revoked' ||
@@ -379,9 +386,10 @@ export async function pull<DB extends SyncCoreDb>(args: {
                 latestExternalCommitForTable > cursor);
 
             if (needsBootstrap) {
-              const tables = args.handlers
-                .getBootstrapOrderFor(sub.table)
-                .map((handler) => handler.table);
+              const tables = getServerBootstrapOrderFor(
+                args.handlers,
+                sub.table
+              ).map((handler) => handler.table);
 
               const initState: SyncBootstrapState = {
                 asOfCommitSeq: maxCommitSeq,
@@ -539,7 +547,8 @@ export async function pull<DB extends SyncCoreDb>(args: {
               ) {
                 if (!nextState) break;
 
-                const nextTableName = nextState.tables[nextState.tableIndex];
+                const nextTableName: string | undefined =
+                  nextState.tables[nextState.tableIndex];
                 if (!nextTableName) {
                   if (activeBundle) {
                     activeBundle.isLastPage = true;
@@ -550,7 +559,8 @@ export async function pull<DB extends SyncCoreDb>(args: {
                   break;
                 }
 
-                const tableHandler = args.handlers.getOrThrow(nextTableName);
+                const tableHandler: ServerTableHandler<DB, Auth> =
+                  getServerHandlerOrThrow(args.handlers, nextTableName);
                 if (!activeBundle || activeBundle.table !== nextTableName) {
                   if (activeBundle) {
                     await flushSnapshotBundle(activeBundle);
@@ -568,16 +578,18 @@ export async function pull<DB extends SyncCoreDb>(args: {
                   };
                 }
 
-                const page = await tableHandler.snapshot(
-                  {
-                    db: trx,
-                    actorId: args.actorId,
-                    scopeValues: effectiveScopes,
-                    cursor: nextState.rowCursor,
-                    limit: limitSnapshotRows,
-                  },
-                  sub.params
-                );
+                const page: { rows: unknown[]; nextCursor: string | null } =
+                  await tableHandler.snapshot(
+                    {
+                      db: trx,
+                      actorId: args.auth.actorId,
+                      auth: args.auth,
+                      scopeValues: effectiveScopes,
+                      cursor: nextState.rowCursor,
+                      limit: limitSnapshotRows,
+                    },
+                    sub.params
+                  );
 
                 const rowFrames = encodeSnapshotRowFrames(page.rows ?? []);
                 activeBundle.rowFrameParts.push(rowFrames);