@absolutejs/sync 1.12.3 → 1.14.0

package/dist/engine/syncEngine.d.ts

@@ -7,7 +7,7 @@ import type { PermissionsDefinition, TablePermissions } from './permissions';
 import type { SyncPack } from './pack';
 import type { SearchCollectionDefinition } from './search';
 import type { ScheduleDefinition } from './schedule';
-import type { EngineActivity, EngineInspection } from './devtools';
+import type { EngineActivity, EngineInspection, EngineMetrics } from './devtools';
 import type { SchemaDefinition, TableSchema } from './schema';
 import type { CrdtMergeable } from '../crdt';
 import type { ClusterBus } from './cluster';
@@ -206,6 +206,16 @@ export type SyncEngine = {
      * writers, the change-feed version, and recent changes. See `syncDevtools`.
      */
     inspect: () => EngineInspection;
+    /**
+     * Operator-shaped engine metrics — counters + memory estimates + throughput
+     * totals since engine start. Distinct from {@link SyncEngine.inspect}: this
+     * is what a PaaS host scrapes on an interval to answer "is this engine
+     * healthy" and "what's its resource footprint." Feed it to
+     * `@absolutejs/metering` for per-engine cost attribution.
+     *
+     * Added in 1.13.0.
+     */
+    metrics: () => EngineMetrics;
     /**
      * Subscribe to the live engine activity stream (changes, mutation outcomes,
      * subscribe/unsubscribe). Returns an unsubscribe. Powers the devtools feed.
@@ -259,6 +269,13 @@ export type LoggedChange = {
     version: number;
     table: string;
     change: RowChange<unknown>;
+    /**
+     * Wall-clock when this change was logged (Date.now()). Used by the
+     * engine's time-based retention sweep (`changeLogRetainMs`) and
+     * surfaced as the change-log age in {@link SyncEngine.metrics}.
+     * Added in 1.13.0; pre-1.13.0 consumers of `LoggedChange` ignore it.
+     */
+    at: number;
 };
 /** Thrown by {@link SyncEngine.streamChanges} when `since` is older than the
  * oldest entry retained in the bounded change log (i.e. the consumer was
@@ -305,6 +322,16 @@ export type SyncEngineOptions = {
      * snapshot. Defaults to 1024.
      */
     changeLogSize?: number;
+    /**
+     * Time-based change-log retention: drop entries older than this many ms,
+     * in addition to the count cap above. Lets a high-throughput engine keep
+     * a SHORT log (e.g. "60s of changes") regardless of count, which both
+     * bounds memory and bounds the catch-up work on reconnect. Defaults to
+     * `null` — only the count cap (`changeLogSize`) applies.
+     *
+     * Added in 1.13.0.
+     */
+    changeLogRetainMs?: number | null;
     /**
      * Run every mutation inside your database's transaction (see
      * {@link TransactionRunner}): the handler's writes commit all-or-nothing, and

package/dist/index.js

@@ -1130,8 +1130,14 @@ var createSyncEngine = (options = {}) => {
   const active = new Map;
   const tableIndex = new Map;
   const changeLogSize = options.changeLogSize ?? 1024;
+  const changeLogRetainMs = options.changeLogRetainMs ?? null;
   const changeLog = [];
   let version = 0;
+  const engineStartedAt = Date.now();
+  let mutationsCompleted = 0;
+  let mutationsFailed = 0;
+  let mutationsRetried = 0;
+  let mutationsInFlight = 0;
   const reactiveCacheMax = options.reactiveCache?.max ?? 256;
   const reactiveCacheTtlMs = options.reactiveCache?.ttlMs ?? 60000;
   const cachedReruns = new Map;
@@ -1542,6 +1548,12 @@ var createSyncEngine = (options = {}) => {
     if (changeLog.length > changeLogSize) {
       changeLog.shift();
     }
+    if (changeLogRetainMs !== null && changeLogRetainMs > 0) {
+      const cutoff = entry.at - changeLogRetainMs;
+      while (changeLog.length > 0 && changeLog[0].at < cutoff) {
+        changeLog.shift();
+      }
+    }
     for (const subscriber of streamSubscribers) {
       subscriber(entry);
     }
@@ -1549,10 +1561,11 @@ var createSyncEngine = (options = {}) => {
   const applyChange = async (table, change, shouldBroadcast = true) => {
     version += 1;
     const changeVersion = version;
-    logChange(changeVersion, { version: changeVersion, table, change });
+    const at = Date.now();
+    logChange(changeVersion, { version: changeVersion, table, change, at });
     emitActivity({
       type: "change",
-      at: Date.now(),
+      at,
       table,
       op: change.op,
       version: changeVersion
@@ -1583,11 +1596,12 @@ var createSyncEngine = (options = {}) => {
     const batchVersion = version;
     const perSubscription = new Map;
     const reactiveChanges = [];
+    const batchAt = Date.now();
     for (const { table, change } of changes) {
-      logChange(batchVersion, { version: batchVersion, table, change });
+      logChange(batchVersion, { version: batchVersion, table, change, at: batchAt });
       emitActivity({
         type: "change",
-        at: Date.now(),
+        at: batchAt,
         table,
         op: change.op,
         version: batchVersion
@@ -2038,53 +2052,61 @@ var createSyncEngine = (options = {}) => {
       const startedAt = Date.now();
       let lastError;
       let attemptsMade = 0;
-      for (let attempt = 1;attempt <= maxAttempts; attempt++) {
-        attemptsMade = attempt;
-        try {
-          const { buffered, result } = runInTransaction !== undefined ? await runInTransaction((tx) => runHandler(tx)) : await runHandler(undefined);
-          await applyChangeBatch(buffered);
-          emitActivity({
-            type: "mutation",
-            at: Date.now(),
-            name,
-            status: "ok"
-          });
-          return result;
-        } catch (error) {
-          lastError = error;
-          const elapsedMs = Date.now() - startedAt;
-          const canRetry = attempt < maxAttempts && isRetryable(error) && elapsedMs < maxElapsedMs;
-          if (!canRetry)
-            break;
-          const rawDelay = computeDelay(attempt);
-          const remaining = maxElapsedMs - elapsedMs;
-          if (remaining <= 0)
-            break;
-          const delayMs = Math.max(0, Math.min(rawDelay, remaining));
-          emitActivity({
-            type: "mutationRetry",
-            at: Date.now(),
-            name,
-            attempt,
-            delayMs,
-            errorName: error instanceof Error ? error.name : "Error",
-            errorMessage: error instanceof Error ? error.message : String(error)
-          });
-          if (delayMs > 0) {
-            await new Promise((resolve) => setTimeout(resolve, delayMs));
+      mutationsInFlight += 1;
+      try {
+        for (let attempt = 1;attempt <= maxAttempts; attempt++) {
+          attemptsMade = attempt;
+          try {
+            const { buffered, result } = runInTransaction !== undefined ? await runInTransaction((tx) => runHandler(tx)) : await runHandler(undefined);
+            await applyChangeBatch(buffered);
+            mutationsCompleted += 1;
+            emitActivity({
+              type: "mutation",
+              at: Date.now(),
+              name,
+              status: "ok"
+            });
+            return result;
+          } catch (error) {
+            lastError = error;
+            const elapsedMs = Date.now() - startedAt;
+            const canRetry = attempt < maxAttempts && isRetryable(error) && elapsedMs < maxElapsedMs;
+            if (!canRetry)
+              break;
+            mutationsRetried += 1;
+            const rawDelay = computeDelay(attempt);
+            const remaining = maxElapsedMs - elapsedMs;
+            if (remaining <= 0)
+              break;
+            const delayMs = Math.max(0, Math.min(rawDelay, remaining));
+            emitActivity({
+              type: "mutationRetry",
+              at: Date.now(),
+              name,
+              attempt,
+              delayMs,
+              errorName: error instanceof Error ? error.name : "Error",
+              errorMessage: error instanceof Error ? error.message : String(error)
+            });
+            if (delayMs > 0) {
+              await new Promise((resolve) => setTimeout(resolve, delayMs));
+            }
           }
         }
+        mutationsFailed += 1;
+        emitActivity({
+          type: "mutation",
+          at: Date.now(),
+          name,
+          status: "error"
+        });
+        if (attemptsMade > 1) {
+          throw new RetriesExhaustedError(attemptsMade, Date.now() - startedAt, lastError);
+        }
+        throw lastError;
+      } finally {
+        mutationsInFlight -= 1;
       }
-      emitActivity({
-        type: "mutation",
-        at: Date.now(),
-        name,
-        status: "error"
-      });
-      if (attemptsMade > 1) {
-        throw new RetriesExhaustedError(attemptsMade, Date.now() - startedAt, lastError);
-      }
-      throw lastError;
     },
     runMutations: async (specs, ctx) => {
       if (specs.length === 0)
@@ -2323,6 +2345,45 @@ var createSyncEngine = (options = {}) => {
         }))
       };
     },
+    metrics: () => {
+      const now = Date.now();
+      const byCollection = {};
+      let totalSubscriptions = 0;
+      for (const [name, subs] of active) {
+        byCollection[name] = subs.size;
+        totalSubscriptions += subs.size;
+      }
+      const oldest = changeLog[0];
+      return {
+        at: now,
+        changeLog: {
+          capacity: changeLogSize,
+          entries: changeLog.length,
+          oldestAgeMs: oldest ? now - oldest.at : null,
+          oldestVersion: oldest ? oldest.version : null,
+          retainMs: changeLogRetainMs
+        },
+        mutations: {
+          completed: mutationsCompleted,
+          failed: mutationsFailed,
+          inFlight: mutationsInFlight,
+          retried: mutationsRetried
+        },
+        reactiveCache: {
+          capacity: reactiveCacheMax,
+          entries: cachedReruns.size
+        },
+        schedules: {
+          registered: schedules.size
+        },
+        subscriptions: {
+          byCollection,
+          total: totalSubscriptions
+        },
+        uptimeMs: now - engineStartedAt,
+        version
+      };
+    },
     onActivity: (listener) => {
       activityListeners.add(listener);
       return () => {
@@ -2698,5 +2759,5 @@ export {
   createPresenceHub
 };
 
-//# debugId=D6679B754081BCC764756E2164756E21
+//# debugId=202C826A4AA9A02264756E2164756E21
 //# sourceMappingURL=index.js.map