@absolutejs/sync 1.18.2 → 1.20.0

package/dist/engine/devtools.d.ts

@@ -96,6 +96,11 @@ export type EngineMetrics = {
         retried: number;
         /** Currently running, not yet committed or failed. */
         inFlight: number;
+        /**
+         * Waiting in the `mutationConcurrency` queue. Always `0` when
+         * `mutationConcurrency` is unset (no semaphore). Added in 1.20.0.
+         */
+        queued: number;
     };
     schedules: {
         registered: number;

package/dist/engine/index.d.ts

@@ -47,8 +47,8 @@ export type { MutationActions, MutationDefinition, MutationHandler, TableWriter,
 export type { BridgeFetchConfig, BridgeFetchEndpoint, BridgeFetchResponse, HandlerMetricsHook, HandlerMetricsRecord, SandboxConfig } from './sandbox';
 export { exponentialBackoff, isSerializationFailure, RetriesExhaustedError } from './retry';
 export type { ExponentialBackoffOptions, RetryPolicy } from './retry';
-export { CdcConsumerSlowError, createSyncEngine, MissedChangesError, SchemaError, UnauthorizedError } from './syncEngine';
-export type { CrdtFields, LoggedChange, StreamChangesOptions, SubscribeArgs, Subscription, SyncEngine } from './syncEngine';
+export { CdcConsumerSlowError, createSyncEngine, MissedChangesError, MutationQueueOverflowError, SchemaError, UnauthorizedError } from './syncEngine';
+export type { ChangeLogSnapshot, CrdtFields, LoggedChange, StreamChangesOptions, SubscribeArgs, Subscription, SyncEngine, SyncEngineOptions } from './syncEngine';
 export { syncCdc } from './cdc';
 export type { SyncCdcOptions } from './cdc';
 export type { CrdtMergeable } from '../crdt';

package/dist/engine/index.js

@@ -1410,6 +1410,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 shallowEqual4 = (a, b) => {
   if (a === b) {
@@ -1526,6 +1535,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;
@@ -1567,6 +1610,31 @@ var createSyncEngine = (options = {}) => {
   const runInTransaction = options.transaction;
   const instanceId = options.instanceId ?? globalThis.crypto?.randomUUID?.() ?? `i${Math.random()}`;
   let clusterBus;
+  const importChangeLog = (snapshot) => {
+    if (version !== 0) {
+      throw new Error(`[sync] importChangeLog: engine already has version ${version}; ` + `restore must happen before any local writes commit.`);
+    }
+    if (snapshot.instanceId !== instanceId) {
+      throw new Error(`[sync] importChangeLog: snapshot instanceId "${snapshot.instanceId}" ` + `does not match this engine's instanceId "${instanceId}". ` + `Pass options.instanceId = "${snapshot.instanceId}" to createSyncEngine.`);
+    }
+    version = snapshot.version;
+    for (const entry of snapshot.entries) {
+      changeLog.push(entry);
+    }
+    while (changeLog.length > changeLogSize) {
+      changeLog.shift();
+    }
+    if (changeLogRetainMs !== null && changeLogRetainMs > 0) {
+      const cutoff = Date.now() - changeLogRetainMs;
+      while (changeLog.length > 0 && changeLog[0].at < cutoff) {
+        changeLog.shift();
+      }
+    }
+    return snapshot.entries.length;
+  };
+  if (options.initialChangeLog !== undefined) {
+    importChangeLog(options.initialChangeLog);
+  }
   const broadcast = (changes, originVersion) => {
     if (clusterBus !== undefined && changes.length > 0) {
       clusterBus.publish({ changes, origin: instanceId, originVersion });
@@ -2528,6 +2596,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) => {
@@ -2543,7 +2612,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;
@@ -2596,7 +2664,7 @@ var createSyncEngine = (options = {}) => {
         }
         throw lastError;
       } finally {
-        mutationsInFlight -= 1;
+        releaseMutationSlot();
       }
     },
     runMutations: async (specs, ctx) => {
@@ -2609,6 +2677,7 @@ var createSyncEngine = (options = {}) => {
         }
         return { args: spec.args, mutation, name: spec.name };
       });
+      await acquireMutationSlot();
       const runBatch = async (tx) => {
         const results = [];
         const accumulated = [];
@@ -2646,6 +2715,8 @@ var createSyncEngine = (options = {}) => {
           status: "error"
         });
         throw error;
+      } finally {
+        releaseMutationSlot();
       }
     },
     registerSchedule: (schedule) => {
@@ -2836,6 +2907,13 @@ var createSyncEngine = (options = {}) => {
         }))
       };
     },
+    exportChangeLog: () => ({
+      entries: changeLog.slice(),
+      exportedAt: Date.now(),
+      instanceId,
+      version
+    }),
+    importChangeLog,
     metrics: () => {
       const now = Date.now();
       const byCollection = {};
@@ -2858,6 +2936,7 @@ var createSyncEngine = (options = {}) => {
           completed: mutationsCompleted,
           failed: mutationsFailed,
           inFlight: mutationsInFlight,
+          queued: mutationsQueued,
           retried: mutationsRetried
         },
         reactiveCache: {
@@ -3402,9 +3481,10 @@ export {
   RetriesExhaustedError,
   PackTableConflictError,
   PackMissingDependencyError,
+  MutationQueueOverflowError,
   MissedChangesError,
   CdcConsumerSlowError
 };
 
-//# debugId=83816548811B9BFD64756E2164756E21
+//# debugId=E104F5FFDBD631C764756E2164756E21
 //# sourceMappingURL=index.js.map