@absolutejs/sync 2.0.1 → 2.2.0

package/dist/engine/collection.d.ts

@@ -1,4 +1,4 @@
-import type { RowKey } from './types';
+import type { RowChange, RowKey } from './types';
 /**
  * App-provided context for a subscription — typically the authenticated session
  * (user id, roles). Passed to `authorize`, `hydrate`, and `match` so a
@@ -32,6 +32,19 @@ export type CollectionDefinition<T, P = void, Ctx = CollectionContext> = {
      * two in lockstep — the planned adapter convenience.)
      */
     match?: (row: T, params: P, ctx: Ctx) => boolean;
+    /**
+     * Refetch-fallback gate (multi-table / shape-mismatched collections that can't
+     * use `match`). Without it, ANY change to a read table re-hydrates EVERY
+     * subscription — even ones the change can't touch. Given the RAW change (the
+     * source row, which may differ from `T` and be partial), return `false` ONLY
+     * when the change provably can't affect this subscription's result, to skip
+     * its re-hydrate; the fan-out drops from O(all subscribers) to O(affected).
+     *
+     * Conservative: a `false` that should have been `true` DROPS an update, so
+     * default to `true` when unsure (e.g. a delete whose row lacks your scope
+     * field). Ignored when `match` is set (incremental routing is already exact).
+     */
+    affects?: (change: RowChange<unknown>, params: P, ctx: Ctx) => boolean;
     /**
      * Access control: return `false` (or throw) to deny the subscription. Runs
      * before `hydrate`. Without it a collection is world-readable, so treat it as

package/dist/engine/devtools.d.ts

@@ -113,6 +113,21 @@ export type EngineMetrics = {
     schedules: {
         registered: number;
     };
+    /**
+     * Change-source liveness, aggregated across every `connectSource` (e.g. a
+     * CDC adapter). Lets a health check distinguish a healthy-but-quiet feed
+     * from a wired-but-silent or disconnected one. Added in 2.1.0.
+     */
+    source: {
+        /** Currently-connected change sources (0 once all have disconnected). */
+        connected: number;
+        /** Total changes delivered by connected sources since engine start. */
+        changesReceived: number;
+        /** `Date.now()` of the most recent source change, or `null` if none yet. */
+        lastChangeAt: number | null;
+        /** Wall-clock age of the most recent source change in ms, or `null`. */
+        lastChangeAgeMs: number | null;
+    };
 };
 /**
  * A live engine event (see {@link SyncEngine.onActivity}): a committed change or

package/dist/engine/index.js

@@ -1611,6 +1611,9 @@ var createSyncEngine = (options = {}) => {
   let mutationsFailed = 0;
   let mutationsRetried = 0;
   let mutationsInFlight = 0;
+  let connectedSources = 0;
+  let sourceChangesReceived = 0;
+  let sourceLastChangeAt = null;
   const mutationWaiters = [];
   let mutationsQueued = 0;
   const activeFences = new Set;
@@ -1796,6 +1799,9 @@ var createSyncEngine = (options = {}) => {
         return subscription.view.reset(await subscription.rehydrate());
       }
     }
+    if (subscription.affects && !subscription.affects(change)) {
+      return EMPTY_DIFF;
+    }
     return subscription.view.reset(await subscription.rehydrate());
   };
   const subscriptionsForTable = function* (table) {
@@ -2588,6 +2594,7 @@ var createSyncEngine = (options = {}) => {
             return readRule ? rows.filter((row) => readRule(ctx, row)) : rows;
           };
           const incremental = match !== undefined && tables.length === 1;
+          const boundAffects = !incremental && definition.affects ? (change) => definition.affects(change, params, ctx) : undefined;
           const boundMatch = incremental ? (row) => match(row, params, ctx) && (readRule ? readRule(ctx, row) : true) : () => true;
           const view = createMaterializedView({
             key,
@@ -2602,6 +2609,7 @@ var createSyncEngine = (options = {}) => {
             view,
             incremental,
             rehydrate,
+            ...boundAffects ? { affects: boundAffects } : {},
             key,
             onDiff: typedOnDiff
           };
@@ -2664,8 +2672,18 @@ var createSyncEngine = (options = {}) => {
     },
     applyChange: (table, change) => applyChange(table, change),
     connectSource: async (source) => {
-      await source.start((table, change) => applyChange(table, change));
+      await source.start((table, change) => {
+        sourceChangesReceived += 1;
+        sourceLastChangeAt = Date.now();
+        return applyChange(table, change);
+      });
+      connectedSources += 1;
+      let stopped = false;
       return async () => {
+        if (!stopped) {
+          stopped = true;
+          connectedSources -= 1;
+        }
         await source.stop();
       };
     },
@@ -3226,6 +3244,12 @@ var createSyncEngine = (options = {}) => {
         schedules: {
           registered: schedules.size
         },
+        source: {
+          changesReceived: sourceChangesReceived,
+          connected: connectedSources,
+          lastChangeAgeMs: sourceLastChangeAt === null ? null : now - sourceLastChangeAt,
+          lastChangeAt: sourceLastChangeAt
+        },
         subscriptions: {
           byCollection,
           byTenant: Object.fromEntries(subscriptionsByTenant),
@@ -3769,5 +3793,5 @@ export {
   CdcConsumerSlowError
 };
 
-//# debugId=6D23BAC246E5201264756E2164756E21
+//# debugId=40999B3553DAC88C64756E2164756E21
 //# sourceMappingURL=index.js.map