@absolutejs/sync 1.7.5 → 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. */
@@ -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

@@ -779,7 +779,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 +795,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";
@@ -1799,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) => {
@@ -2323,5 +2370,5 @@ export {
   createPresenceHub
 };
 
-//# debugId=B9056CA0A3DAE81164756E2164756E21
+//# debugId=9570274420A04D4164756E2164756E21
 //# sourceMappingURL=index.js.map