@absolutejs/sync 1.19.0 → 1.20.0

package/dist/engine/syncEngine.d.ts

@@ -414,6 +414,17 @@ export declare class CdcConsumerSlowError extends Error {
     readonly lastDeliveredVersion: number;
     constructor(maxBuffer: number, lastDeliveredVersion: number);
 }
+/**
+ * Thrown by `runMutation` / `runMutations` when `mutationConcurrency` is
+ * saturated AND the waiting queue is already at `mutationQueueLimit`. The
+ * caller sees this immediately (no queue time) so the host can shed load
+ * with a clean 429 instead of letting the queue grow unboundedly. Added
+ * in 1.20.0.
+ */
+export declare class MutationQueueOverflowError extends Error {
+    readonly queueLimit: number;
+    constructor(queueLimit: number);
+}
 /**
  * Serializable snapshot of an engine's change log + monotonic version, returned
  * by {@link SyncEngine.exportChangeLog} and consumed by
@@ -557,6 +568,35 @@ export type SyncEngineOptions = {
      * `createSyncEngine` returns. Added in 1.19.0.
      */
     initialChangeLog?: ChangeLogSnapshot;
+    /**
+     * Maximum concurrent in-flight mutations (`runMutation` + `runMutations`).
+     * Calls beyond the limit wait in a FIFO queue and run as slots free up;
+     * `engine.metrics().mutations.queued` surfaces the queue depth.
+     *
+     * A single tenant flooding `runMutation` can otherwise drive unbounded
+     * memory growth (per-mutation `actions` buffers, retry timers, sandbox
+     * invocations queued against the isolate pool). Set this to a value
+     * appropriate for the host's tenant tier — e.g. `32` for a free tier,
+     * `256` for paid. Without this option the engine is unbounded
+     * (matching pre-1.20 behavior).
+     *
+     * Sandboxed mutations are gated by the same semaphore. If you need
+     * finer-grained control (sandbox-only throttling), see
+     * `@absolutejs/isolated-jsc`'s pool size — that's the lower layer.
+     *
+     * Added in 1.20.0.
+     */
+    mutationConcurrency?: number;
+    /**
+     * Cap on the queue of waiting mutations once `mutationConcurrency` is
+     * saturated. Calls beyond this cap throw {@link MutationQueueOverflowError}
+     * immediately instead of queueing — the host can surface a clean 429 or
+     * apply a tenant-specific shed policy. Defaults to unbounded (queue
+     * never rejects). Only meaningful when `mutationConcurrency` is set.
+     *
+     * Added in 1.20.0.
+     */
+    mutationQueueLimit?: number;
 };
 /**
  * The Tier 3 sync engine: a registry of collections plus the view syncer. It is

package/dist/index.js

@@ -1152,6 +1152,15 @@ class CdcConsumerSlowError extends Error {
     this.lastDeliveredVersion = lastDeliveredVersion;
   }
 }
+
+class MutationQueueOverflowError extends Error {
+  queueLimit;
+  constructor(queueLimit) {
+    super(`Mutation queue overflowed (limit ${queueLimit}); the engine is at ` + `its mutationConcurrency cap and the waiting queue is full. ` + `Retry later or shed load at the gateway.`);
+    this.name = "MutationQueueOverflowError";
+    this.queueLimit = queueLimit;
+  }
+}
 var defaultKey = (row) => row.id;
 var shallowEqual3 = (a, b) => {
   if (a === b) {
@@ -1268,6 +1277,40 @@ var createSyncEngine = (options = {}) => {
   let mutationsFailed = 0;
   let mutationsRetried = 0;
   let mutationsInFlight = 0;
+  const mutationWaiters = [];
+  let mutationsQueued = 0;
+  const acquireMutationSlot = async () => {
+    const limit = options.mutationConcurrency;
+    if (limit === undefined) {
+      mutationsInFlight += 1;
+      return;
+    }
+    if (mutationsInFlight < limit && mutationWaiters.length === 0) {
+      mutationsInFlight += 1;
+      return;
+    }
+    const queueLimit = options.mutationQueueLimit;
+    if (queueLimit !== undefined && mutationsQueued >= queueLimit) {
+      throw new MutationQueueOverflowError(queueLimit);
+    }
+    mutationsQueued += 1;
+    try {
+      await new Promise((resolve) => {
+        mutationWaiters.push(resolve);
+      });
+    } finally {
+      mutationsQueued -= 1;
+    }
+    mutationsInFlight += 1;
+  };
+  const releaseMutationSlot = () => {
+    mutationsInFlight -= 1;
+    if (options.mutationConcurrency === undefined)
+      return;
+    const next = mutationWaiters.shift();
+    if (next !== undefined)
+      next();
+  };
   const reactiveCacheMax = options.reactiveCache?.max ?? 256;
   const reactiveCacheTtlMs = options.reactiveCache?.ttlMs ?? 60000;
   const cachedReruns = new Map;
@@ -2295,6 +2338,7 @@ var createSyncEngine = (options = {}) => {
           throw new UnauthorizedError(`run mutation "${name}"`);
         }
       }
+      await acquireMutationSlot();
       const sandboxRunner = sandboxRunners.get(name);
       const invokeHandler = sandboxRunner !== undefined ? sandboxRunner : (a, c, actions) => Promise.resolve(mutation.handler(a, c, actions));
       const runHandler = async (tx) => {
@@ -2310,7 +2354,6 @@ var createSyncEngine = (options = {}) => {
       const startedAt = Date.now();
       let lastError;
       let attemptsMade = 0;
-      mutationsInFlight += 1;
       try {
         for (let attempt = 1;attempt <= maxAttempts; attempt++) {
           attemptsMade = attempt;
@@ -2363,7 +2406,7 @@ var createSyncEngine = (options = {}) => {
         }
         throw lastError;
       } finally {
-        mutationsInFlight -= 1;
+        releaseMutationSlot();
       }
     },
     runMutations: async (specs, ctx) => {
@@ -2376,6 +2419,7 @@ var createSyncEngine = (options = {}) => {
         }
         return { args: spec.args, mutation, name: spec.name };
       });
+      await acquireMutationSlot();
       const runBatch = async (tx) => {
         const results = [];
         const accumulated = [];
@@ -2413,6 +2457,8 @@ var createSyncEngine = (options = {}) => {
           status: "error"
         });
         throw error;
+      } finally {
+        releaseMutationSlot();
       }
     },
     registerSchedule: (schedule) => {
@@ -2632,6 +2678,7 @@ var createSyncEngine = (options = {}) => {
           completed: mutationsCompleted,
           failed: mutationsFailed,
           inFlight: mutationsInFlight,
+          queued: mutationsQueued,
           retried: mutationsRetried
         },
         reactiveCache: {
@@ -3025,5 +3072,5 @@ export {
   createPresenceHub
 };
 
-//# debugId=EB8C381967D0311A64756E2164756E21
+//# debugId=9DD57DF563EB9CB564756E2164756E21
 //# sourceMappingURL=index.js.map