@feltdb/core 0.6.8 → 0.6.10

package/dist/collection.d.ts

@@ -8,9 +8,27 @@
  * for efficient, real-time state propagation.
  */
 import type { JsDb } from './feltdb.js';
-import type { IndexConfig } from './index-types.js';
+import { type FreshnessCapability, type Revision } from './freshness.js';
+import type { IndexConfig, CollectionQueryPlan } from './index-types.js';
 export type Predicate<T> = (item: T) => boolean;
 export type Subscriber<T> = (items: T[]) => void;
+/**
+ * How a refresh decided whether the local cache could be reused.
+ *
+ * Reporting only, and deliberately explicit about *why* the runtime was
+ * queried, so a benchmark or a caller can tell a validated cache hit from a
+ * fallback that happens to be fast.
+ */
+export interface FreshnessCheck {
+    /** `revision` when a revision decided it; `refresh` when the runtime was asked for the data. */
+    validation: 'revision' | 'refresh';
+    /** True only when the runtime was not queried for the collection at all. */
+    servedFromCache: boolean;
+    /** The revision the cache now corresponds to, when there is one. */
+    revision?: Revision;
+    /** Why a revision was not used. */
+    reason?: string;
+}
 /**
  * Result of an atomic version-checked update operation.
  * Represents either a successful commit or a version conflict.
@@ -49,6 +67,26 @@ export declare class Collection<T> {
     private indexBackend;
     private indexStore;
     private indexesLoaded;
+    /** Incremented whenever `cache` is replaced, so the index can tell it is stale. */
+    private cacheGeneration;
+    /** The cache generation the index entries currently reflect, or -1 for none. */
+    private indexedGeneration;
+    private lastPlan;
+    /** Cache records addressed by id, valid for `indexedGeneration`. */
+    private recordsById;
+    /** Raw payload the cache was parsed from, used to detect that nothing changed. */
+    private lastRawSnapshot;
+    /**
+     * The runtime revision the cache was built from, when the runtime offers one.
+     *
+     * Captured *before* the query that produced the cache, never after. A write
+     * landing between the two then makes this older than the data it labels,
+     * which costs one unnecessary refresh. Capturing it after would make it
+     * newer than the data, and the cache would look current forever.
+     */
+    private cachedRevision;
+    /** How the last refresh decided the cache was usable. Reporting only. */
+    private lastFreshness;
     constructor(db: JsDb, name: string, predicate?: Predicate<T>, parent?: Collection<T>, loadIndexes?: boolean);
     /**
      * Load indexes that were persisted from a previous session.
@@ -59,8 +97,46 @@ export declare class Collection<T> {
      * Returns cached results (live-updated).
      */
     all(): Promise<T[]>;
-    /** Find records whose fields match the supplied query. */
+    /**
+     * Find records whose fields match the supplied query.
+     *
+     * When a hash index covers one of the queried fields, the index supplies the
+     * candidate records and the remaining fields are checked on those candidates
+     * only. Otherwise every record is examined.
+     *
+     * The result is identical either way. The index is a projection of the same
+     * cached array a scan would walk, rebuilt whenever that array is replaced,
+     * so an indexed lookup cannot return a record a scan would miss or resolve
+     * an id the cache no longer holds.
+     *
+     * `lastQueryPlan()` reports which path ran.
+     */
     find(query?: Partial<T>): Promise<T[]>;
+    /**
+     * How the most recent `find` was answered.
+     *
+     * Exposed so an application — and the benchmark — can confirm that the index
+     * was actually consulted rather than inferring it from timing.
+     */
+    lastQueryPlan(): CollectionQueryPlan | null;
+    /** A hash index covering one of the queried fields, if there is one. */
+    private indexFor;
+    /**
+     * Candidate records from an index, or null when the index cannot be trusted.
+     *
+     * Returning null makes the caller fall back to a scan, which is always
+     * correct. That is the safe direction: a wrong answer is far worse than a
+     * slow one.
+     */
+    private indexCandidates;
+    /**
+     * Rebuild the index from the current cache when the cache has moved on.
+     *
+     * The index is only ever a projection of `this.cache`. Deriving it from the
+     * same array a scan walks is what makes the two paths agree by construction,
+     * rather than by hoping every write path remembered to update the index.
+     */
+    private ensureIndexReflectsCache;
     /**
      * Create an index on this collection for faster queries.
      * @example
@@ -159,6 +235,38 @@ export declare class Collection<T> {
     subscribe(subscriber: Subscriber<T>, _pollInterval?: number): () => void;
     /** Release runtime subscriptions owned by this live collection. */
     close(): void;
+    /**
+     * What this collection's runtime can tell it about staleness.
+     *
+     * This is a *validation mechanism*, not a guarantee that the cache is fresh.
+     * `validation: 'revision'` means a cheap staleness check exists; it says
+     * nothing about whether this collection's cache currently passes it.
+     *
+     * @example
+     * const capability = await people.freshness();
+     * // 'revision' -> a cheap staleness check exists
+     * // 'refresh'  -> re-read is the only honest answer, and `reason` says why
+     */
+    freshness(): Promise<FreshnessCapability>;
+    /**
+     * How the last refresh decided the cache was usable.
+     *
+     * `servedFromCache` is true only when the runtime was never asked for this
+     * collection's data. Reporting only; it exists so a benchmark can tell a
+     * validated cache hit from a fallback that merely happened to be fast.
+     */
+    lastFreshnessCheck(): FreshnessCheck | null;
+    /**
+     * Read the runtime's current revision, or explain why there isn't one.
+     *
+     * The capability is re-checked on every call rather than remembered, because
+     * a deployment can change underneath a live collection: switching on
+     * replication revokes revision authority, and a collection holding a cached
+     * capability would keep trusting a number that stopped meaning anything.
+     * Any refusal — no capability, a topology change, a transport failure —
+     * lands here as a reason, and the caller falls back to a full refresh.
+     */
+    private currentRevision;
     /**
      * Refresh data from the database and notify subscribers.
      */

package/dist/collection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"collection.d.ts","sourceRoot":"","sources":["../src/collection.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"collection.d.ts","sourceRoot":"","sources":["../src/collection.ts"],"names":[],"mappings":"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"}

package/dist/collection.js

@@ -7,6 +7,7 @@
  * Collections now use reactive dependency graphs instead of polling
  * for efficient, real-time state propagation.
  */
+import { describeFreshness, isCacheCurrent, readRevision, } from './freshness.js';
 import { getReactiveDependencyGraph } from './reactive-graph.js';
 import { IndexBackend } from './index-backend.js';
 import { IndexStore } from './index-store.js';
@@ -29,6 +30,26 @@ export class Collection {
         this.runtimeUnsubscribe = null;
         this.indexBackend = new IndexBackend();
         this.indexesLoaded = false;
+        /** Incremented whenever `cache` is replaced, so the index can tell it is stale. */
+        this.cacheGeneration = 0;
+        /** The cache generation the index entries currently reflect, or -1 for none. */
+        this.indexedGeneration = -1;
+        this.lastPlan = null;
+        /** Cache records addressed by id, valid for `indexedGeneration`. */
+        this.recordsById = null;
+        /** Raw payload the cache was parsed from, used to detect that nothing changed. */
+        this.lastRawSnapshot = null;
+        /**
+         * The runtime revision the cache was built from, when the runtime offers one.
+         *
+         * Captured *before* the query that produced the cache, never after. A write
+         * landing between the two then makes this older than the data it labels,
+         * which costs one unnecessary refresh. Capturing it after would make it
+         * newer than the data, and the cache would look current forever.
+         */
+        this.cachedRevision = null;
+        /** How the last refresh decided the cache was usable. Reporting only. */
+        this.lastFreshness = null;
         this.db = db;
         this.name = name;
         this.collectionId = `${name}-${Math.random().toString(36).substr(2, 9)}`;
@@ -71,11 +92,132 @@ export class Collection {
         await this.refresh();
         return [...this.cache];
     }
-    /** Find records whose fields match the supplied query. */
+    /**
+     * Find records whose fields match the supplied query.
+     *
+     * When a hash index covers one of the queried fields, the index supplies the
+     * candidate records and the remaining fields are checked on those candidates
+     * only. Otherwise every record is examined.
+     *
+     * The result is identical either way. The index is a projection of the same
+     * cached array a scan would walk, rebuilt whenever that array is replaced,
+     * so an indexed lookup cannot return a record a scan would miss or resolve
+     * an id the cache no longer holds.
+     *
+     * `lastQueryPlan()` reports which path ran.
+     */
     async find(query = {}) {
         const items = await this.all();
         const entries = Object.entries(query);
-        return items.filter((item) => entries.every(([field, expected]) => item[field] === expected));
+        if (entries.length === 0) {
+            this.lastPlan = { strategy: 'scan', reason: 'no query fields', candidatesExamined: items.length, recordsReturned: items.length };
+            return items;
+        }
+        const matches = (item) => entries.every(([field, expected]) => item[field] === expected);
+        const usable = this.indexFor(entries);
+        if (usable) {
+            const candidates = this.indexCandidates(usable.indexName, usable.field, usable.value);
+            if (candidates) {
+                const found = candidates.filter(matches);
+                this.lastPlan = {
+                    strategy: 'index',
+                    indexName: usable.indexName,
+                    field: usable.field,
+                    candidatesExamined: candidates.length,
+                    recordsReturned: found.length,
+                };
+                return found;
+            }
+        }
+        const found = items.filter(matches);
+        this.lastPlan = {
+            strategy: 'scan',
+            reason: usable ? 'index could not be trusted for this snapshot' : 'no index covers the queried fields',
+            candidatesExamined: items.length,
+            recordsReturned: found.length,
+        };
+        return found;
+    }
+    /**
+     * How the most recent `find` was answered.
+     *
+     * Exposed so an application — and the benchmark — can confirm that the index
+     * was actually consulted rather than inferring it from timing.
+     */
+    lastQueryPlan() {
+        return this.lastPlan;
+    }
+    /** A hash index covering one of the queried fields, if there is one. */
+    indexFor(entries) {
+        for (const config of this.indexBackend.listIndexes()) {
+            // Only equality on a single-field hash index is planned today. Sorted,
+            // compound, and text indexes are maintained but not yet used for reads.
+            if (config.type !== 'hash' || !config.field)
+                continue;
+            const entry = entries.find(([field]) => field === config.field);
+            if (entry)
+                return { indexName: config.name, field: config.field, value: entry[1] };
+        }
+        return null;
+    }
+    /**
+     * Candidate records from an index, or null when the index cannot be trusted.
+     *
+     * Returning null makes the caller fall back to a scan, which is always
+     * correct. That is the safe direction: a wrong answer is far worse than a
+     * slow one.
+     */
+    indexCandidates(indexName, field, value) {
+        if (!this.ensureIndexReflectsCache())
+            return null;
+        let ids;
+        try {
+            ids = this.indexBackend.queryIndex(indexName, { field, operator: 'eq', value });
+        }
+        catch {
+            return null;
+        }
+        const records = [];
+        for (const id of ids) {
+            const record = this.recordsById?.get(id);
+            if (record === undefined)
+                return null; // the index disagrees with the cache
+            records.push(record);
+        }
+        return records;
+    }
+    /**
+     * Rebuild the index from the current cache when the cache has moved on.
+     *
+     * The index is only ever a projection of `this.cache`. Deriving it from the
+     * same array a scan walks is what makes the two paths agree by construction,
+     * rather than by hoping every write path remembered to update the index.
+     */
+    ensureIndexReflectsCache() {
+        if (this.indexedGeneration === this.cacheGeneration)
+            return this.recordsById !== null;
+        if (!this.indexBackend.resetEntries()) {
+            this.recordsById = null;
+            return false;
+        }
+        const byId = new Map();
+        for (const item of this.cache) {
+            const recordId = item?.id;
+            // A record without a stable id cannot be resolved from an index result,
+            // so the whole snapshot is treated as unindexable rather than partially
+            // indexed.
+            if (recordId === undefined || recordId === null) {
+                this.recordsById = null;
+                this.indexedGeneration = this.cacheGeneration;
+                return false;
+            }
+            const key = String(recordId);
+            byId.set(key, item);
+            this.indexBackend.updateRecord(key, null, item);
+        }
+        this.recordsById = byId;
+        this.indexedGeneration = this.cacheGeneration;
+        return true;
     }
     /**
      * Create an index on this collection for faster queries.
@@ -424,13 +566,93 @@ export class Collection {
             unsubscribe();
         this.unsubscribeFunctions.clear();
     }
+    /**
+     * What this collection's runtime can tell it about staleness.
+     *
+     * This is a *validation mechanism*, not a guarantee that the cache is fresh.
+     * `validation: 'revision'` means a cheap staleness check exists; it says
+     * nothing about whether this collection's cache currently passes it.
+     *
+     * @example
+     * const capability = await people.freshness();
+     * // 'revision' -> a cheap staleness check exists
+     * // 'refresh'  -> re-read is the only honest answer, and `reason` says why
+     */
+    freshness() {
+        return describeFreshness(this.db);
+    }
+    /**
+     * How the last refresh decided the cache was usable.
+     *
+     * `servedFromCache` is true only when the runtime was never asked for this
+     * collection's data. Reporting only; it exists so a benchmark can tell a
+     * validated cache hit from a fallback that merely happened to be fast.
+     */
+    lastFreshnessCheck() {
+        return this.lastFreshness;
+    }
+    /**
+     * Read the runtime's current revision, or explain why there isn't one.
+     *
+     * The capability is re-checked on every call rather than remembered, because
+     * a deployment can change underneath a live collection: switching on
+     * replication revokes revision authority, and a collection holding a cached
+     * capability would keep trusting a number that stopped meaning anything.
+     * Any refusal — no capability, a topology change, a transport failure —
+     * lands here as a reason, and the caller falls back to a full refresh.
+     */
+    async currentRevision() {
+        try {
+            return { revision: await readRevision(this.db) };
+        }
+        catch (error) {
+            return { reason: error instanceof Error ? error.message : String(error) };
+        }
+    }
     /**
      * Refresh data from the database and notify subscribers.
      */
     async refresh() {
         try {
+            // The revision is read *before* the query, so it can only ever be older
+            // than the data it ends up labelling. The reverse ordering would let a
+            // write that lands between the query and the revision read produce a
+            // cache tagged with a revision it does not contain, and that cache would
+            // then validate as current forever.
+            const observed = await this.currentRevision();
+            if ('revision' in observed) {
+                if (this.isInitialized && this.cachedRevision
+                    && isCacheCurrent(this.cachedRevision, observed.revision)) {
+                    // The runtime is not queried at all. This is the only path in this
+                    // method that skips the round trip, and it is reachable only when
+                    // the runtime advertised an authoritative revision for its domain.
+                    this.lastFreshness = { validation: 'revision', servedFromCache: true, revision: observed.revision };
+                    return;
+                }
+            }
+            else {
+                // No usable revision: the existing behaviour, unchanged.
+                this.cachedRevision = null;
+            }
             const result = await this.db.query(this.name);
+            this.lastFreshness = 'revision' in observed
+                ? { validation: 'revision', servedFromCache: false, revision: observed.revision }
+                : { validation: 'refresh', servedFromCache: false, reason: observed.reason };
             if (result.success && result.data) {
+                // Record the revision only once the data it labels is actually in
+                // hand. A failed query must not leave the cache tagged as current.
+                this.cachedRevision = 'revision' in observed ? observed.revision : null;
+                // The runtime returned exactly what it returned last time, so the data
+                // has not changed. Re-parsing it would produce an identical array,
+                // discard the cache, and invalidate any index derived from it — paying
+                // twice to learn nothing.
+                //
+                // This remains useful for runtimes with no revision, and as a second
+                // line for those that have one: it is what keeps the index valid when
+                // some *other* collection's write moved a store-wide revision.
+                if (this.isInitialized && result.data === this.lastRawSnapshot) {
+                    return;
+                }
                 try {
                     let items = JSON.parse(result.data);
                     // Apply predicate if this is a derived collection
@@ -444,8 +666,11 @@ export class Collection {
                             }
                         });
                     }
-                    // Update cache with all results
+                    // Update cache with all results. The index is a projection of this
+                    // array, so replacing it invalidates the index entries.
                     this.cache = items;
+                    this.cacheGeneration += 1;
+                    this.lastRawSnapshot = result.data;
                     this.isInitialized = true;
                 }
                 catch (err) {

package/dist/create/package-versions.js

@@ -1,4 +1,4 @@
 // One release train keeps generated applications installable. The repository
 // validation script checks these values against every workspace manifest.
-export const FELTDB_PACKAGE_VERSION = '0.6.8';
+export const FELTDB_PACKAGE_VERSION = '0.6.10';
 export const feltdbPackageRange = `^${FELTDB_PACKAGE_VERSION}`;