@absolutejs/sync 1.12.3 → 1.13.0

package/dist/engine/devtools.d.ts

@@ -48,6 +48,59 @@ export type EngineInspection = {
         readsTables: string[];
     }[];
 };
+/**
+ * Operator-shaped point-in-time engine state (see {@link SyncEngine.metrics}) —
+ * numeric counters + memory estimates + throughput totals since engine start.
+ *
+ * Distinct from {@link EngineInspection}, which is devtools-shaped (named
+ * collections, recent-change tail, registered packs). `metrics()` 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` to
+ * attribute cost per engine.
+ */
+export type EngineMetrics = {
+    /** `Date.now()` when this snapshot was taken. */
+    at: number;
+    /** How long this engine has been running, in milliseconds. */
+    uptimeMs: number;
+    /** Current change-feed version (monotonic). */
+    version: number;
+    changeLog: {
+        /** Number of entries currently retained. */
+        entries: number;
+        /** Hard cap on entries (from `SyncEngineOptions.changeLogSize`). */
+        capacity: number;
+        /** Time-based retention window, when set (`SyncEngineOptions.changeLogRetainMs`). */
+        retainMs: number | null;
+        /** Version of the oldest retained entry, or `null` when empty. */
+        oldestVersion: number | null;
+        /** Wall-clock age of the oldest retained entry in ms, or `null` when empty. */
+        oldestAgeMs: number | null;
+    };
+    subscriptions: {
+        /** Active subscriptions across every collection. */
+        total: number;
+        /** Per-collection breakdown — the values sum to `total`. */
+        byCollection: Record<string, number>;
+    };
+    reactiveCache: {
+        entries: number;
+        capacity: number;
+    };
+    mutations: {
+        /** Mutations completed successfully since engine start. */
+        completed: number;
+        /** Mutations that exhausted their retry budget and failed. */
+        failed: number;
+        /** Per-attempt retries fired since start (a single mutation may bump this multiple times). */
+        retried: number;
+        /** Currently running, not yet committed or failed. */
+        inFlight: number;
+    };
+    schedules: {
+        registered: number;
+    };
+};
 /**
  * A live engine event (see {@link SyncEngine.onActivity}): a committed change or
  * a mutation outcome. `at` is `Date.now()`. (Live subscription counts come from

package/dist/engine/index.d.ts

@@ -54,7 +54,7 @@ export type { SyncCdcOptions } from './cdc';
 export type { CrdtMergeable } from '../crdt';
 export { defineSchema, field } from './schema';
 export type { FieldValidator, SchemaDefinition, TableSchema } from './schema';
-export type { CollectionInspection, CollectionKind, EngineActivity, EngineInspection } from './devtools';
+export type { CollectionInspection, CollectionKind, EngineActivity, EngineInspection, EngineMetrics } from './devtools';
 export { hydrateRoute, mutateRoute } from './routes';
 export type { SyncRouteContext } from './routes';
 export { createSyncConnection } from './connection';

package/dist/engine/index.js

@@ -1492,8 +1492,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;
@@ -1904,6 +1910,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);
     }
@@ -1911,10 +1923,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
@@ -1945,11 +1958,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
@@ -2400,53 +2414,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)
@@ -2685,6 +2707,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 () => {
@@ -3161,5 +3222,5 @@ export {
   CdcConsumerSlowError
 };
 
-//# debugId=3473D89C765057E364756E2164756E21
+//# debugId=61A7A6BDD6B4D12064756E2164756E21
 //# sourceMappingURL=index.js.map