@absolutejs/sync 1.10.0 → 1.12.0

package/dist/engine/sandbox.d.ts

@@ -171,6 +171,52 @@ export type SandboxConfig = {
      * reachable (e.g. CI with a known image).
      */
     backend?: 'auto' | 'ffi' | 'worker';
+    /**
+     * **Escape hatch.** Map of host functions the sandboxed handler may
+     * call as `unsafeHost.fnName(...args)`. The name is deliberately
+     * loud: anyone reading the source must see immediately that a
+     * sandboxed mutation is reaching through to non-deterministic host
+     * code (third-party API, queue push, email send, anything that
+     * touches the outside world).
+     *
+     * Without this option, the sandbox is hermetic — only `args`,
+     * `ctx`, and `actions` are reachable. Declare an entry here, name
+     * it visibly (e.g. `chargeStripe`, `sendSlackPing`), and the engine
+     * exposes it on the sandbox-side `unsafeHost` Proxy. The fn runs on
+     * the host; its return value is structured-cloned back across the
+     * isolate boundary; thrown errors propagate into the sandbox as
+     * normal JS errors the handler can catch.
+     *
+     * The deterministic-mutation guarantees stop at the call site —
+     * retries WILL re-fire these host fns (they're outside the
+     * transaction). Treat them as side effects and either make them
+     * idempotent or pair them with explicit compensation in the
+     * handler. Convex's actions are the same model; this is the same
+     * trade.
+     *
+     * @example
+     * ```ts
+     * defineMutation({
+     *   name: 'payments:checkout',
+     *   sandboxedHandler: `async (args, ctx, actions, unsafeHost) => {
+     *     const order = await actions.insert('orders', { ...args, status: 'pending' });
+     *     const receipt = await unsafeHost.chargeStripe({
+     *       amount: order.amount,
+     *       token: args.token,
+     *     });
+     *     await actions.update('orders', { id: order.id, status: 'paid', receipt });
+     *     return order;
+     *   }`,
+     *   sandbox: {
+     *     unsafeHost: {
+     *       chargeStripe: ({ amount, token }) =>
+     *         stripe.charges.create({ amount, source: token }),
+     *     },
+     *   },
+     * });
+     * ```
+     */
+    unsafeHost?: Record<string, (...args: any[]) => unknown | Promise<unknown>>;
 };
 /**
  * Build a lazy runner for one mutation's sandboxed source. The first call

package/dist/engine/syncEngine.d.ts

@@ -178,6 +178,28 @@ export type SyncEngine = {
      * mutation / a handler throw. Drive this from the transport's mutate frame.
      */
     runMutation: (name: string, args: unknown, ctx: unknown) => Promise<unknown>;
+    /**
+     * Atomically run N mutations in a single transaction (sync 1.11+).
+     * Each `{ name, args }` spec is authorized, then handlers fire in
+     * order against shared buffered changes. If any handler throws, the
+     * entire transaction rolls back — no partial commits, no fanned-out
+     * diffs. On success the accumulated changes apply as ONE live batch
+     * and the per-mutation results return in order.
+     *
+     * No retry policy applies to batches in v0.2; configure per-mutation
+     * retries on individual `runMutation` calls when atomicity isn't
+     * needed. A failed batch passes the original error through with no
+     * wrapping.
+     *
+     * Requires `transaction` to be set in {@link SyncEngineOptions} for
+     * actual DB-level atomicity; without it the batch still buffers
+     * changes into one fan-out but the underlying adapter writes
+     * piecemeal.
+     */
+    runMutations: (specs: Array<{
+        name: string;
+        args: unknown;
+    }>, ctx: unknown) => Promise<unknown[]>;
     /**
      * A point-in-time snapshot of the engine for devtools: registered collections
      * (+ kind, tables, live subscription counts), mutations, schedules, readers,

package/dist/index.js

@@ -740,7 +740,7 @@ var wrap = (source) => `
 		const userFn = (${source});
 		if (typeof userFn !== 'function') {
 			throw new Error(
-				'sandboxedHandler must evaluate to (args, ctx, actions) => result; got ' +
+				'sandboxedHandler must evaluate to (args, ctx, actions, unsafeHost) => result; got ' +
 					typeof userFn
 			);
 		}
@@ -752,12 +752,24 @@ var wrap = (source) => `
 			now: () => __dispatch(__callId, 'now'),
 			fetch: (url, init) => __dispatch(__callId, 'fetch', url, init)
 		};
-		return userFn(args, ctx, actions);
+		// Escape hatch \u2014 host fns the mutation explicitly opted in to.
+		// The Proxy means every property access is a host call; the
+		// engine throws if the property name isn't declared in the
+		// mutation's sandbox.unsafeHost map.
+		const unsafeHost = new Proxy({}, {
+			get: (_target, fnName) => {
+				if (typeof fnName !== 'string') return undefined;
+				return (...callArgs) =>
+					__dispatch(__callId, 'unsafeHost', fnName, callArgs);
+			}
+		});
+		return userFn(args, ctx, actions, unsafeHost);
 	}
 `;
 var compile = async (source, config, bridgeFetch) => {
   const { Reference, createIsolatedRunner, resolveIsolatePolicy } = await loadIsolatedJsc();
   const callMap = new Map;
+  const unsafeHost = config.unsafeHost;
   const dispatch = new Reference((callId, op, ...rest) => {
     const a = callMap.get(callId);
     if (a === undefined) {
@@ -776,6 +788,14 @@ var compile = async (source, config, bridgeFetch) => {
         return a.now();
       case "fetch":
         return runBridgeFetch(bridgeFetch, rest[0], rest[1]);
+      case "unsafeHost": {
+        const fnName = rest[0];
+        const callArgs = rest[1] ?? [];
+        if (unsafeHost === undefined || typeof unsafeHost[fnName] !== "function") {
+          throw new Error(`sandboxedHandler called unsafeHost.${fnName}() but it was not declared in the mutation's sandbox.unsafeHost config. Declare it (and only the host fns you intend to expose) to opt in to the escape hatch.`);
+        }
+        return unsafeHost[fnName](...callArgs);
+      }
       default:
         throw new Error(`unknown sandbox action op: ${String(op)}`);
     }
@@ -2065,6 +2085,55 @@ var createSyncEngine = (options = {}) => {
       }
       throw lastError;
     },
+    runMutations: async (specs, ctx) => {
+      if (specs.length === 0)
+        return [];
+      const resolved = specs.map((spec) => {
+        const mutation = mutations.get(spec.name);
+        if (mutation === undefined) {
+          throw new Error(`Unknown mutation "${spec.name}"`);
+        }
+        return { args: spec.args, mutation, name: spec.name };
+      });
+      const runBatch = async (tx) => {
+        const results = [];
+        const accumulated = [];
+        for (const { args, mutation, name } of resolved) {
+          if (mutation.authorize !== undefined) {
+            const allowed = await mutation.authorize(args, ctx);
+            if (!allowed) {
+              throw new UnauthorizedError(`run mutation "${name}"`);
+            }
+          }
+          const sandboxRunner = sandboxRunners.get(name);
+          const invokeHandler = sandboxRunner !== undefined ? sandboxRunner : (a, c, actions2) => Promise.resolve(mutation.handler(a, c, actions2));
+          const { actions, buffered } = makeActions(tx, ctx, true);
+          const result = await invokeHandler(args, ctx, actions);
+          results.push(result);
+          accumulated.push(...buffered);
+        }
+        return { accumulated, results };
+      };
+      try {
+        const { accumulated, results } = runInTransaction !== undefined ? await runInTransaction((tx) => runBatch(tx)) : await runBatch(undefined);
+        await applyChangeBatch(accumulated);
+        emitActivity({
+          type: "mutationBatch",
+          at: Date.now(),
+          names: resolved.map((entry) => entry.name),
+          status: "ok"
+        });
+        return results;
+      } catch (error) {
+        emitActivity({
+          type: "mutationBatch",
+          at: Date.now(),
+          names: resolved.map((entry) => entry.name),
+          status: "error"
+        });
+        throw error;
+      }
+    },
     registerSchedule: (schedule) => {
       schedules.set(schedule.name, schedule);
     },
@@ -2626,5 +2695,5 @@ export {
   createPresenceHub
 };
 
-//# debugId=2C8AB0508E99C22364756E2164756E21
+//# debugId=DA5074BFF8CB679464756E2164756E21
 //# sourceMappingURL=index.js.map