@syncular/client 0.0.6-144 → 0.0.6-152

package/src/mutations.ts

@@ -31,6 +31,7 @@ import type { Insertable, Kysely, Transaction, Updateable } from 'kysely';
 import { sql } from 'kysely';
 import { enqueueOutboxCommit } from './outbox';
 import type {
+  SyncClientLocalMutationArgs,
   SyncClientPlugin,
   SyncClientPluginContext,
 } from './plugins/types';
@@ -402,6 +403,9 @@ export interface OutboxCommitConfig<DB extends SyncClientDb> {
   omitColumns?: string[];
   codecs?: ColumnCodecSource;
   codecDialect?: ColumnCodecDialect;
+  plugins?: SyncClientPlugin[];
+  actorId?: string;
+  clientId?: string;
 }
 
 export function createOutboxCommit<DB extends SyncClientDb>(
@@ -411,6 +415,11 @@ export function createOutboxCommit<DB extends SyncClientDb>(
   const versionColumn = config.versionColumn ?? 'server_version';
   const omitColumns = config.omitColumns ?? [];
   const codecDialect = config.codecDialect ?? 'sqlite';
+  const sortedPlugins = sortPlugins(config.plugins ?? []);
+  const pluginContext: SyncClientPluginContext = {
+    actorId: config.actorId ?? 'unknown',
+    clientId: config.clientId ?? 'unknown',
+  };
 
   return async (fn) => {
     const operations: SyncOperation[] = [];
@@ -420,6 +429,42 @@ export function createOutboxCommit<DB extends SyncClientDb>(
       op: SyncOpKind;
     }> = [];
 
+    const transformLocalOperation = async (
+      operation: SyncOperation
+    ): Promise<SyncOperation> => {
+      if (sortedPlugins.length === 0) return operation;
+
+      const transformed = await runBeforeApplyLocalMutationsPlugins({
+        plugins: sortedPlugins,
+        ctx: pluginContext,
+        operations: [operation],
+      });
+
+      if (transformed.length !== 1) {
+        throw new Error(
+          'beforeApplyLocalMutations must return exactly one operation per input operation'
+        );
+      }
+
+      const [nextOperation] = transformed;
+      if (!nextOperation) {
+        throw new Error(
+          'beforeApplyLocalMutations returned an empty operation'
+        );
+      }
+      if (
+        nextOperation.table !== operation.table ||
+        nextOperation.row_id !== operation.row_id ||
+        nextOperation.op !== operation.op
+      ) {
+        throw new Error(
+          'beforeApplyLocalMutations cannot change operation table, row_id, or op'
+        );
+      }
+
+      return nextOperation;
+    };
+
     const { result, receipt } = await config.db
       .transaction()
       .execute(async (trx) => {
@@ -469,14 +514,6 @@ export function createOutboxCommit<DB extends SyncClientDb>(
                 typeof rawId === 'string' && rawId ? rawId : randomId();
 
               const row = { ...raw, [idColumn]: id };
-              const dbRow = applyCodecsToDbRow(
-                row,
-                resolveTableCodecs(table, row),
-                codecDialect
-              );
-
-              await dynamicInsert(trx, table, dbRow);
-
               const payload = sanitizePayload(row, {
                 omit: [
                   idColumn,
@@ -484,6 +521,27 @@ export function createOutboxCommit<DB extends SyncClientDb>(
                   ...omitColumns,
                 ],
               });
+              const localSanitized = sanitizePayload(row, {
+                omit: [idColumn, ...(versionColumn ? [versionColumn] : [])],
+              });
+              const localOp = await transformLocalOperation({
+                table,
+                row_id: id,
+                op: 'upsert',
+                payload: localSanitized,
+                base_version: null,
+              });
+              const localPayload = isRecord(localOp.payload)
+                ? localOp.payload
+                : {};
+              const localRow = { ...localPayload, [idColumn]: id };
+              const dbRow = applyCodecsToDbRow(
+                localRow,
+                resolveTableCodecs(table, localRow),
+                codecDialect
+              );
+
+              await dynamicInsert(trx, table, dbRow);
 
               operations.push({
                 table: table,
@@ -503,6 +561,7 @@ export function createOutboxCommit<DB extends SyncClientDb>(
               }
               const ids: string[] = [];
               const toInsert: Record<string, unknown>[] = [];
+              const toLocalInsert: Record<string, unknown>[] = [];
 
               for (const values of rows) {
                 const raw = isRecord(values) ? values : {};
@@ -513,18 +572,6 @@ export function createOutboxCommit<DB extends SyncClientDb>(
                 toInsert.push({ ...raw, [idColumn]: id });
               }
 
-              const dbRows = toInsert.map((row) =>
-                applyCodecsToDbRow(
-                  row,
-                  resolveTableCodecs(table, row),
-                  codecDialect
-                )
-              );
-
-              if (dbRows.length > 0) {
-                await dynamicInsert(trx, table, dbRows);
-              }
-
               for (let i = 0; i < toInsert.length; i++) {
                 const row = toInsert[i]!;
                 const id = ids[i]!;
@@ -535,6 +582,20 @@ export function createOutboxCommit<DB extends SyncClientDb>(
                     ...omitColumns,
                   ],
                 });
+                const localSanitized = sanitizePayload(row, {
+                  omit: [idColumn, ...(versionColumn ? [versionColumn] : [])],
+                });
+                const localOp = await transformLocalOperation({
+                  table,
+                  row_id: id,
+                  op: 'upsert',
+                  payload: localSanitized,
+                  base_version: null,
+                });
+                const localPayload = isRecord(localOp.payload)
+                  ? localOp.payload
+                  : {};
+                toLocalInsert.push({ ...localPayload, [idColumn]: id });
 
                 operations.push({
                   table: table,
@@ -547,6 +608,18 @@ export function createOutboxCommit<DB extends SyncClientDb>(
                 localMutations.push({ table, rowId: id, op: 'upsert' });
               }
 
+              const dbRows = toLocalInsert.map((row) =>
+                applyCodecsToDbRow(
+                  row,
+                  resolveTableCodecs(table, row),
+                  codecDialect
+                )
+              );
+
+              if (dbRows.length > 0) {
+                await dynamicInsert(trx, table, dbRows);
+              }
+
               return ids;
             },
 
@@ -559,12 +632,25 @@ export function createOutboxCommit<DB extends SyncClientDb>(
                   ...omitColumns,
                 ],
               });
+              const localSanitized = sanitizePayload(rawPatch, {
+                omit: [idColumn, ...(versionColumn ? [versionColumn] : [])],
+              });
 
               const hasExplicitBaseVersion =
                 !!opts && hasOwn(opts, 'baseVersion');
+              const localOp = await transformLocalOperation({
+                table,
+                row_id: id,
+                op: 'upsert',
+                payload: localSanitized,
+                base_version: null,
+              });
+              const localPayload = isRecord(localOp.payload)
+                ? localOp.payload
+                : {};
               const dbPatch = applyCodecsToDbRow(
-                sanitized,
-                resolveTableCodecs(table, sanitized),
+                localPayload,
+                resolveTableCodecs(table, localPayload),
                 codecDialect
               );
 
@@ -630,12 +716,25 @@ export function createOutboxCommit<DB extends SyncClientDb>(
                   ...omitColumns,
                 ],
               });
+              const localSanitized = sanitizePayload(rawPatch, {
+                omit: [idColumn, ...(versionColumn ? [versionColumn] : [])],
+              });
 
               const hasExplicitBaseVersion =
                 !!opts && hasOwn(opts, 'baseVersion');
+              const localOp = await transformLocalOperation({
+                table,
+                row_id: id,
+                op: 'upsert',
+                payload: localSanitized,
+                base_version: null,
+              });
+              const localPayload = isRecord(localOp.payload)
+                ? localOp.payload
+                : {};
               const dbPatch = applyCodecsToDbRow(
-                sanitized,
-                resolveTableCodecs(table, sanitized),
+                localPayload,
+                resolveTableCodecs(table, localPayload),
                 codecDialect
               );
 
@@ -732,6 +831,43 @@ function clonePushRequest(request: SyncPushRequest): SyncPushRequest {
   return JSON.parse(JSON.stringify(request)) as SyncPushRequest;
 }
 
+function cloneLocalMutationArgs(
+  args: SyncClientLocalMutationArgs
+): SyncClientLocalMutationArgs {
+  if (typeof structuredClone === 'function') {
+    return structuredClone(args);
+  }
+  return JSON.parse(JSON.stringify(args)) as SyncClientLocalMutationArgs;
+}
+
+function sortPlugins(plugins: readonly SyncClientPlugin[]): SyncClientPlugin[] {
+  return [...plugins].sort((a, b) => (a.priority ?? 50) - (b.priority ?? 50));
+}
+
+async function runBeforeApplyLocalMutationsPlugins(args: {
+  plugins: readonly SyncClientPlugin[];
+  ctx: SyncClientPluginContext;
+  operations: SyncOperation[];
+}): Promise<SyncOperation[]> {
+  if (args.plugins.length === 0) {
+    return args.operations;
+  }
+
+  let transformedArgs: SyncClientLocalMutationArgs = cloneLocalMutationArgs({
+    operations: args.operations,
+  });
+
+  for (const plugin of args.plugins) {
+    if (!plugin.beforeApplyLocalMutations) continue;
+    transformedArgs = await plugin.beforeApplyLocalMutations(
+      args.ctx,
+      transformedArgs
+    );
+  }
+
+  return transformedArgs.operations;
+}
+
 export function createPushCommit<DB = AnyDb>(
   config: PushCommitConfig
 ): MutationsCommitFn<DB, PushCommitMeta, undefined> {
@@ -915,10 +1051,7 @@ export function createPushCommit<DB = AnyDb>(
     };
 
     const plugins = config.plugins ?? [];
-    // Sort plugins by priority (lower numbers first, default 50)
-    const sortedPlugins = [...plugins].sort(
-      (a, b) => (a.priority ?? 50) - (b.priority ?? 50)
-    );
+    const sortedPlugins = sortPlugins(plugins);
     const ctx: SyncClientPluginContext = {
       actorId: config.actorId ?? 'unknown',
       clientId: config.clientId,

package/src/plugins/types.ts

@@ -1,4 +1,6 @@
 import type {
+  SyncChange,
+  SyncOperation,
   SyncPullRequest,
   SyncPullResponse,
   SyncPushRequest,
@@ -10,6 +12,22 @@ export interface SyncClientPluginContext {
   clientId: string;
 }
 
+export interface SyncClientWsDeliveryMetadata {
+  commitSeq?: number;
+  actorId?: string | null;
+  createdAt?: string | null;
+}
+
+export interface SyncClientWsDeliveryArgs {
+  changes: SyncChange[];
+  cursor: number;
+  metadata?: SyncClientWsDeliveryMetadata;
+}
+
+export interface SyncClientLocalMutationArgs {
+  operations: SyncOperation[];
+}
+
 /**
  * Plugin priority levels for ordering execution.
  * Lower numbers execute first.
@@ -43,6 +61,16 @@ export interface SyncClientPlugin {
     request: SyncPushRequest
   ): Promise<SyncPushRequest> | SyncPushRequest;
 
+  /**
+   * Called before applying local optimistic mutations to the local DB.
+   * Use this when local payloads need shaping different from server push payloads
+   * (for example CRDT envelopes that should not be written as SQL columns).
+   */
+  beforeApplyLocalMutations?(
+    ctx: SyncClientPluginContext,
+    args: SyncClientLocalMutationArgs
+  ): Promise<SyncClientLocalMutationArgs> | SyncClientLocalMutationArgs;
+
   /**
    * Called after receiving a push response from the server.
    * Receives both the request and the response to allow opIndex correlation.
@@ -60,4 +88,14 @@ export interface SyncClientPlugin {
     ctx: SyncClientPluginContext,
     args: { request: SyncPullRequest; response: SyncPullResponse }
   ): Promise<SyncPullResponse> | SyncPullResponse;
+
+  /**
+   * Called for inline WS-delivered changes before applying to the local DB.
+   * Use this when a plugin needs equivalent transforms for realtime payloads
+   * (for example decryption or CRDT materialization).
+   */
+  beforeApplyWsChanges?(
+    ctx: SyncClientPluginContext,
+    args: SyncClientWsDeliveryArgs
+  ): Promise<SyncClientWsDeliveryArgs> | SyncClientWsDeliveryArgs;
 }