@absolutejs/sync 1.7.4 → 1.7.6

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. */
@@ -60,15 +114,30 @@ export type SandboxConfig = {
 };
 /**
  * Build a lazy runner for one mutation's sandboxed source. The first call
- * compiles the isolate + context + callable; subsequent calls reuse all
- * three and only pack the per-call args (`args`, `ctx`, and a fresh
- * dispatch Reference closed over this call's `actions`). If the isolate
- * has been disposed (timeout, memory cap), the next call re-spawns
- * transparently.
+ * compiles the isolate + context + dispatch Reference + callable;
+ * subsequent calls only generate a fresh callId, register the per-call
+ * `actions` in the callMap, and invoke `callable.call([callId, args,
+ * ctx])`. Per-call cost on FFI: one JSObjectCallAsFunction + three
+ * cheap primitive packings. No per-call Reference allocation, no
+ * setGlobal, no eval.
+ *
+ * Concurrency-safe by construction: each call has its own callId →
+ * its own actions slot in the callMap.
+ *
+ * If the isolate has been disposed (timeout, memory cap), the next
+ * call re-spawns transparently.
+ */
+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.
  *
- * Concurrency-safe by construction: every call gets its own fresh
- * dispatch Reference closed over its own `actions`. No shared slot, no
- * promise queue needed. (Reference allocation cost is ~0.003 ms per
- * call — negligible.)
+ * `mutationName` only matters when `onMetrics` is set — it's the
+ * `mutationName` field of the emitted record.
  */
-export declare const makeSandboxedHandler: (source: string, config?: SandboxConfig) => ((args: unknown, ctx: unknown, actions: MutationActions) => Promise<unknown>);
+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

@@ -725,7 +725,7 @@ var loadIsolatedJsc = async () => {
   }
 };
 var wrap = (source) => `
-	function (args, ctx, __dispatch) {
+	function (__callId, args, ctx) {
 		const userFn = (${source});
 		if (typeof userFn !== 'function') {
 			throw new Error(
@@ -734,30 +734,52 @@ var wrap = (source) => `
 			);
 		}
 		const actions = {
-			insert: (table, data) => __dispatch('insert', table, data),
-			update: (table, data) => __dispatch('update', table, data),
-			delete: (table, row) => __dispatch('delete', table, row),
-			change: (collection, change) => __dispatch('change', collection, change)
+			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)
 		};
 		return userFn(args, ctx, actions);
 	}
 `;
 var compile = async (source, config) => {
-  const { createIsolate } = await loadIsolatedJsc();
+  const { createIsolate, Reference } = await loadIsolatedJsc();
   const isolate = await createIsolate({
     backend: config.backend ?? "auto",
     memoryLimit: config.memoryLimit ?? 32
   });
   const context = await isolate.createContext();
+  const callMap = new Map;
+  const dispatch = new Reference((callId, op, ...rest) => {
+    const a = callMap.get(callId);
+    if (a === undefined) {
+      throw new Error(`__dispatch invoked for orphan callId ${String(callId)}`);
+    }
+    switch (op) {
+      case "insert":
+        return a.insert(rest[0], rest[1]);
+      case "update":
+        return a.update(rest[0], rest[1]);
+      case "delete":
+        return a.delete(rest[0], rest[1]);
+      case "change":
+        return a.change(rest[0], rest[1]);
+      default:
+        throw new Error(`unknown sandbox action op: ${String(op)}`);
+    }
+  });
+  await context.setGlobal("__dispatch", dispatch);
   const callable = await context.compileCallable(wrap(source));
   return {
     callable,
+    callMap,
     context,
     isolate,
+    nextCallId: 1,
     timeoutMs: config.timeout ?? 5000
   };
 };
-var makeSandboxedHandler = (source, config = {}) => {
+var makeSandboxedHandler = (source, config = {}, metricsHook) => {
   let pending;
   const getCompiled = async () => {
     if (pending !== undefined) {
@@ -770,27 +792,62 @@ var makeSandboxedHandler = (source, config = {}) => {
     return pending;
   };
   return async (args, ctx, actions) => {
-    const { Reference } = await loadIsolatedJsc();
     const compiled = await getCompiled();
-    const dispatch = new Reference((op, ...rest) => {
-      switch (op) {
-        case "insert":
-          return actions.insert(rest[0], rest[1]);
-        case "update":
-          return actions.update(rest[0], rest[1]);
-        case "delete":
-          return actions.delete(rest[0], rest[1]);
-        case "change":
-          return actions.change(rest[0], rest[1]);
-        default:
-          throw new Error(`unknown sandbox action op: ${String(op)}`);
+    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);
       }
-    });
-    return compiled.callable.call([args, ctx, dispatch], {
-      timeout: compiled.timeoutMs
-    });
+    }
+    const startedAt = performance.now();
+    const id = makeRandomId();
+    try {
+      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";
@@ -1786,7 +1843,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) => {
@@ -2310,5 +2370,5 @@ export {
   createPresenceHub
 };
 
-//# debugId=E4BD5E29981CFB6664756E2164756E21
+//# debugId=9570274420A04D4164756E2164756E21
 //# sourceMappingURL=index.js.map