@absolutejs/sync 1.7.5 → 1.7.7

package/dist/engine/mutation.d.ts

@@ -45,6 +45,28 @@ export type MutationActions = {
     delete: (table: string, row: unknown) => Promise<void>;
     /** Escape hatch: emit a change you persisted yourself (no writer call). */
     change: <T>(collection: string, change: RowChange<T>) => Promise<void>;
+    /**
+     * Wall-clock timestamp the handler should use instead of `Date.now()`.
+     * Returns a `number` (ms since epoch).
+     *
+     * Why an injected clock? Two forward-looking reasons:
+     *
+     *   1. **Replay / rebase determinism.** When the engine re-runs a
+     *      mutation against an updated state (Replicache-style mutator
+     *      replay), `actions.now()` returns the ORIGINAL call's timestamp
+     *      instead of the current wall clock. `Date.now()` would silently
+     *      diverge between client-optimistic and server-canonical runs;
+     *      `actions.now()` doesn't.
+     *
+     *   2. **Test determinism.** Test harnesses can pin time by passing a
+     *      custom `now()` through {@link MutationActions} — the handler
+     *      observes whatever the test wants.
+     *
+     * If the engine doesn't override it (the common case today), it just
+     * returns `Date.now()`. Use it everywhere you'd reach for
+     * `Date.now()` inside a mutation handler.
+     */
+    now: () => number;
 };
 export type MutationHandler<Args, Ctx, Result> = (args: Args, ctx: Ctx, actions: MutationActions) => Promise<Result> | Result;
 export type MutationDefinition<Args = unknown, Ctx = CollectionContext, Result = unknown> = {

package/dist/engine/sandbox.d.ts

@@ -37,6 +37,60 @@
  * needed — the OS reaps the workers when the engine's host process exits.
  */
 import type { MutationActions } from './mutation';
+/**
+ * Per-call metrics record emitted by `sandboxedHandler` when the engine
+ * is configured with {@link SyncEngineOptions.handlerMetrics}. One record
+ * per invocation, fired AFTER the call completes (success or failure).
+ *
+ * Use this for per-tenant dashboards ("which tenant is burning the most
+ * CPU?"), runtime alerting ("this handler is timing out repeatedly"),
+ * cost attribution, and post-mortem replay of slow / failed mutations.
+ *
+ * Sample wiring pattern — publish to a sync collection users can
+ * subscribe to like any other:
+ *
+ * ```ts
+ * const engine = createSyncEngine({
+ *   handlerMetrics: (record) => {
+ *     metricsCollection.insert(record);  // your own collection / sink
+ *   },
+ * });
+ * ```
+ */
+export type HandlerMetricsRecord = {
+    /** Globally-unique id for this call (random). Useful as a join key. */
+    id: string;
+    /** Name passed to `defineMutation`. */
+    mutationName: string;
+    /** Wall-clock duration from call entry to result resolution (ms). */
+    durationMs: number;
+    /**
+     * CPU time spent inside the JSC sandbox (ms). Comes from
+     * `Script.runWithMetrics` — does NOT include host-side message-passing
+     * overhead on the Worker backend. Sub-millisecond runs round to 0.
+     */
+    cpuMs: number;
+    /**
+     * Heap size (bytes) measured immediately after the script returned.
+     * Not the run's peak — a true peak needs continuous polling.
+     */
+    heapBytes: number;
+    /** `true` if the handler returned normally; `false` if it threw. */
+    ok: boolean;
+    /** Error name (`TimeoutError`, `MemoryLimitError`, `Error`, …) on failure. */
+    errorName?: string;
+    /** Error message on failure. */
+    errorMessage?: string;
+    /** `Date.now()` at the moment the call ended. */
+    timestamp: number;
+};
+/**
+ * Per-call hook invoked once each `sandboxedHandler` invocation finishes
+ * (success or failure). Synchronous return is the common case; an async
+ * return is awaited but its rejection is swallowed (a metrics hook that
+ * crashes must NOT also crash the caller's mutation path).
+ */
+export type HandlerMetricsHook = (record: HandlerMetricsRecord) => void | Promise<void>;
 /** Per-mutation sandbox configuration. */
 export type SandboxConfig = {
     /** Heap memory cap (MB). Default 32. */
@@ -73,4 +127,17 @@ export type SandboxConfig = {
  * If the isolate has been disposed (timeout, memory cap), the next
  * call re-spawns transparently.
  */
-export declare const makeSandboxedHandler: (source: string, config?: SandboxConfig) => ((args: unknown, ctx: unknown, actions: MutationActions) => Promise<unknown>);
+export declare const makeSandboxedHandler: (source: string, config?: SandboxConfig, 
+/**
+ * Optional hook + tagging. When `onMetrics` is supplied, every call
+ * uses `callable.callWithMetrics` (slightly costlier) and fires the
+ * hook on completion. Without it, the cheap `callable.call` path is
+ * used and nothing changes vs the pre-1.7.6 contract.
+ *
+ * `mutationName` only matters when `onMetrics` is set — it's the
+ * `mutationName` field of the emitted record.
+ */
+metricsHook?: {
+    mutationName: string;
+    onMetrics: HandlerMetricsHook;
+}) => ((args: unknown, ctx: unknown, actions: MutationActions) => Promise<unknown>);

package/dist/engine/syncEngine.d.ts

@@ -2,6 +2,7 @@ import type { CollectionContext, CollectionDefinition, JoinCollectionDefinition
 import type { GraphCollectionDefinition } from './graph';
 import type { MutationDefinition, TableWriter, TransactionRunner } from './mutation';
 import type { ReactiveQueryDefinition, TableReader } from './reactive';
+import { type HandlerMetricsHook } from './sandbox';
 import type { PermissionsDefinition, TablePermissions } from './permissions';
 import type { SearchCollectionDefinition } from './search';
 import type { ScheduleDefinition } from './schedule';
@@ -308,6 +309,23 @@ export type SyncEngineOptions = {
         max?: number;
         ttlMs?: number;
     };
+    /**
+     * Per-call telemetry for `sandboxedHandler` mutations. When set, every
+     * sandboxed call fires `onMetrics(record)` after completion with
+     * `{ id, mutationName, durationMs, cpuMs, heapBytes, ok, errorName,
+     * errorMessage, timestamp }`. Wire to a sync collection, your
+     * observability backend, a Drizzle table, anything you want.
+     *
+     * Hook failures are swallowed (a misbehaving metrics sink must NOT
+     * crash the caller's mutation). Adding the hook switches the runner
+     * to `callable.callWithMetrics`, which is a small per-call cost
+     * (~0.05 ms) — disable for hot-path mutations that don't need it.
+     *
+     * Off by default.
+     *
+     * @see {@link HandlerMetricsRecord}
+     */
+    handlerMetrics?: HandlerMetricsHook;
 };
 /**
  * The Tier 3 sync engine: a registry of collections plus the view syncer. It is

package/dist/index.js

@@ -737,7 +737,8 @@ var wrap = (source) => `
 			insert: (table, data) => __dispatch(__callId, 'insert', table, data),
 			update: (table, data) => __dispatch(__callId, 'update', table, data),
 			delete: (table, row) => __dispatch(__callId, 'delete', table, row),
-			change: (collection, change) => __dispatch(__callId, 'change', collection, change)
+			change: (collection, change) => __dispatch(__callId, 'change', collection, change),
+			now: () => __dispatch(__callId, 'now')
 		};
 		return userFn(args, ctx, actions);
 	}
@@ -764,6 +765,8 @@ var compile = async (source, config) => {
         return a.delete(rest[0], rest[1]);
       case "change":
         return a.change(rest[0], rest[1]);
+      case "now":
+        return a.now();
       default:
         throw new Error(`unknown sandbox action op: ${String(op)}`);
     }
@@ -779,7 +782,7 @@ var compile = async (source, config) => {
     timeoutMs: config.timeout ?? 5000
   };
 };
-var makeSandboxedHandler = (source, config = {}) => {
+var makeSandboxedHandler = (source, config = {}, metricsHook) => {
   let pending;
   const getCompiled = async () => {
     if (pending !== undefined) {
@@ -795,15 +798,59 @@ var makeSandboxedHandler = (source, config = {}) => {
     const compiled = await getCompiled();
     const callId = compiled.nextCallId++;
     compiled.callMap.set(callId, actions);
+    if (metricsHook === undefined) {
+      try {
+        return await compiled.callable.call([callId, args, ctx], {
+          timeout: compiled.timeoutMs
+        });
+      } finally {
+        compiled.callMap.delete(callId);
+      }
+    }
+    const startedAt = performance.now();
+    const id = makeRandomId();
     try {
-      return await compiled.callable.call([callId, args, ctx], {
-        timeout: compiled.timeoutMs
+      const { result, metrics } = await compiled.callable.callWithMetrics([callId, args, ctx], { timeout: compiled.timeoutMs });
+      fireMetrics(metricsHook.onMetrics, {
+        cpuMs: metrics.cpuMs,
+        durationMs: performance.now() - startedAt,
+        heapBytes: metrics.heapBytes,
+        id,
+        mutationName: metricsHook.mutationName,
+        ok: true,
+        timestamp: Date.now()
+      });
+      return result;
+    } catch (error) {
+      fireMetrics(metricsHook.onMetrics, {
+        cpuMs: 0,
+        durationMs: performance.now() - startedAt,
+        errorMessage: error instanceof Error ? error.message : String(error),
+        errorName: error instanceof Error ? error.name : "Error",
+        heapBytes: 0,
+        id,
+        mutationName: metricsHook.mutationName,
+        ok: false,
+        timestamp: Date.now()
       });
+      throw error;
     } finally {
       compiled.callMap.delete(callId);
     }
   };
 };
+var makeRandomId = () => `hm_${Date.now().toString(36)}${Math.random().toString(36).slice(2, 10)}`;
+var fireMetrics = (hook, record) => {
+  let outcome;
+  try {
+    outcome = hook(record);
+  } catch {
+    return;
+  }
+  if (outcome instanceof Promise) {
+    outcome.catch(() => {});
+  }
+};
 
 // src/engine/search.ts
 var SEARCH_SCORE_FIELD = "_score";
@@ -1242,7 +1289,8 @@ var createSyncEngine = (options = {}) => {
         }
         await writerFor(table).delete(row, ctx, tx);
         buffered.push({ table, change: { op: "delete", row } });
-      }
+      },
+      now: () => Date.now()
     };
     return { actions, buffered };
   };
@@ -1799,7 +1847,10 @@ var createSyncEngine = (options = {}) => {
       }
       mutations.set(mutation.name, mutation);
       if (mutation.sandboxedHandler !== undefined) {
-        sandboxRunners.set(mutation.name, makeSandboxedHandler(mutation.sandboxedHandler, mutation.sandbox));
+        sandboxRunners.set(mutation.name, makeSandboxedHandler(mutation.sandboxedHandler, mutation.sandbox, options.handlerMetrics === undefined ? undefined : {
+          mutationName: mutation.name,
+          onMetrics: options.handlerMetrics
+        }));
       }
     },
     registerWriter: (table, writer) => {
@@ -2323,5 +2374,5 @@ export {
   createPresenceHub
 };
 
-//# debugId=B9056CA0A3DAE81164756E2164756E21
+//# debugId=0583BD887ED853F264756E2164756E21
 //# sourceMappingURL=index.js.map