live-cache 0.1.0

package/dist/index.umd.js

@@ -0,0 +1,1274 @@
+(function (global, factory) {
+    typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports, require('react')) :
+    typeof define === 'function' && define.amd ? define(['exports', 'react'], factory) :
+    (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global.LiveCache = {}, global.React));
+})(this, (function (exports, React) { 'use strict';
+
+    /******************************************************************************
+    Copyright (c) Microsoft Corporation.
+
+    Permission to use, copy, modify, and/or distribute this software for any
+    purpose with or without fee is hereby granted.
+
+    THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+    REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+    AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+    INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+    LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+    OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+    PERFORMANCE OF THIS SOFTWARE.
+    ***************************************************************************** */
+    /* global Reflect, Promise, SuppressedError, Symbol, Iterator */
+
+
+    function __rest(s, e) {
+        var t = {};
+        for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+            t[p] = s[p];
+        if (s != null && typeof Object.getOwnPropertySymbols === "function")
+            for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+                if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                    t[p[i]] = s[p[i]];
+            }
+        return t;
+    }
+
+    function __awaiter(thisArg, _arguments, P, generator) {
+        function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+        return new (P || (P = Promise))(function (resolve, reject) {
+            function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+            function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+            function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+            step((generator = generator.apply(thisArg, _arguments || [])).next());
+        });
+    }
+
+    typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+        var e = new Error(message);
+        return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+    };
+
+    /*
+     * A Single Model stores the data for a single item.
+     */
+    /**
+     * A single stored record.
+     *
+     * `Document<T>` wraps raw data and adds:
+     * - a generated `_id` (MongoDB-style ObjectId)
+     * - `updatedAt` timestamp, refreshed on updates
+     *
+     * Use `toModel()` when you need a plain object including `_id`
+     * (this is what `Controller` publishes and persists).
+     *
+     * @typeParam TVariable - data shape without `_id`
+     */
+    class Document {
+        constructor(data, counter = 0 * 0xffffff) {
+            this._id = Document.generateId(counter);
+            this.data = data;
+            this.updatedAt = Date.now();
+        }
+        updateData(data) {
+            this.data = Object.assign(Object.assign({}, this.data), data);
+            this.updatedAt = Date.now();
+        }
+        /**
+         * Convert to a plain model including `_id`.
+         */
+        toModel() {
+            return Object.assign({ _id: this._id }, this.data);
+        }
+        /**
+         * Convert to raw data (without `_id`).
+         */
+        toData() {
+            return Object.assign({}, this.data);
+        }
+        /**
+         * Generate a MongoDB-style ObjectId (24 hex characters).
+         *
+         * Format: timestamp (4 bytes) + random process id (5 bytes) + counter (3 bytes)
+         */
+        static generateId(_counter) {
+            // MongoDB ObjectId structure (12 bytes = 24 hex chars):
+            // - 4 bytes: timestamp (seconds since Unix epoch)
+            // - 5 bytes: random process identifier
+            // - 3 bytes: incrementing counter
+            // 1. Timestamp (4 bytes) - seconds since Unix epoch
+            const timestamp = Math.floor(Date.now() / 1000);
+            // 2. Process identifier (5 bytes) - random value
+            const processId = this.processId;
+            // 3. Counter (3 bytes) - incrementing counter with wraparound
+            const counter = (_counter + 1) % 0xffffff;
+            // Convert to hexadecimal strings with proper padding
+            const timestampHex = timestamp.toString(16).padStart(8, "0");
+            const processIdHex = processId.toString(16).padStart(10, "0");
+            const counterHex = counter.toString(16).padStart(6, "0");
+            // Combine into 24-character hex string
+            return timestampHex + processIdHex + counterHex;
+        }
+    }
+    // Random value generated once per process (5 bytes)
+    Document.processId = Math.floor(Math.random() * 0xffffffffff);
+
+    /*
+     * A List Model stores a list of items.
+     */
+    /**
+     * An in-memory collection of documents with simple hash-based indexes.
+     *
+     * - Insert/update/delete operations keep indexes consistent.
+     * - `find()` / `findOne()` attempt indexed lookups first and fall back to linear scan.
+     *
+     * This is commonly used via `Controller.collection`.
+     *
+     * @typeParam TVariable - the data shape stored in the collection (without `_id`)
+     * @typeParam TName - the collection name (string-literal type)
+     */
+    class Collection {
+        constructor(name) {
+            this.name = name;
+            // hash of conditions mapping to _id
+            this.dataMap = {};
+            this.indexes = {};
+            this.counter = 0;
+        }
+        /**
+         * Clear all in-memory documents and indexes.
+         */
+        clear() {
+            this.dataMap = {};
+            this.indexes = {};
+            this.counter = 0;
+        }
+        /**
+         * Add a document to all relevant indexes
+         */
+        addToIndexes(doc) {
+            const model = doc.toModel();
+            // Create index entries for each property
+            for (const [key, value] of Object.entries(model)) {
+                if (key === "_id")
+                    continue; // Skip _id as it's the primary key
+                const indexKey = Collection.hash({ [key]: value });
+                if (!this.indexes[indexKey]) {
+                    this.indexes[indexKey] = [];
+                }
+                // Add document _id to index if not already present
+                if (!this.indexes[indexKey].includes(doc._id)) {
+                    this.indexes[indexKey].push(doc._id);
+                }
+            }
+            // Also create a compound index for the full document conditions
+            const fullIndexKey = Collection.hash(model);
+            if (!this.indexes[fullIndexKey]) {
+                this.indexes[fullIndexKey] = [];
+            }
+            if (!this.indexes[fullIndexKey].includes(doc._id)) {
+                this.indexes[fullIndexKey].push(doc._id);
+            }
+        }
+        /**
+         * Remove a document from all indexes
+         */
+        removeFromIndexes(doc) {
+            const model = doc.toModel();
+            // Remove from all property indexes
+            for (const [key, value] of Object.entries(model)) {
+                if (key === "_id")
+                    continue;
+                const indexKey = Collection.hash({ [key]: value });
+                if (this.indexes[indexKey]) {
+                    this.indexes[indexKey] = this.indexes[indexKey].filter((id) => id !== doc._id);
+                    // Clean up empty indexes
+                    if (this.indexes[indexKey].length === 0) {
+                        delete this.indexes[indexKey];
+                    }
+                }
+            }
+            // Remove from compound index
+            const fullIndexKey = Collection.hash(model);
+            if (this.indexes[fullIndexKey]) {
+                this.indexes[fullIndexKey] = this.indexes[fullIndexKey].filter((id) => id !== doc._id);
+                if (this.indexes[fullIndexKey].length === 0) {
+                    delete this.indexes[fullIndexKey];
+                }
+            }
+        }
+        /**
+         * Find a single document by _id or by matching conditions (optimized with indexes)
+         */
+        findOne(where) {
+            var _a;
+            if (typeof where === "string") {
+                return this.dataMap[where] || null;
+            }
+            // Try to use index for faster lookup
+            const indexKey = Collection.hash(where);
+            if (this.indexes[indexKey] && this.indexes[indexKey].length > 0) {
+                const docId = this.indexes[indexKey][0];
+                const doc = this.dataMap[docId];
+                // Verify the document still matches (in case of hash collision)
+                if (doc && this.matchesConditions(doc, where)) {
+                    return doc;
+                }
+            }
+            // Fallback to linear search if index lookup fails
+            return ((_a = Object.values(this.dataMap).find((doc) => this.matchesConditions(doc, where))) !== null && _a !== void 0 ? _a : null);
+        }
+        /**
+         * Find all documents matching the conditions (optimized with indexes)
+         */
+        find(where) {
+            // If no conditions, return all documents
+            if (!where || Object.keys(where).length === 0) {
+                return Object.values(this.dataMap);
+            }
+            if (typeof where === "string") {
+                const doc = this.dataMap[where];
+                return doc ? [doc] : [];
+            }
+            // Try to use index for faster lookup
+            const indexKey = Collection.hash(where);
+            if (this.indexes[indexKey]) {
+                // Get candidate documents from index
+                const candidateDocs = this.indexes[indexKey]
+                    .map((id) => this.dataMap[id])
+                    .filter((doc) => doc && this.matchesConditions(doc, where));
+                if (candidateDocs.length > 0) {
+                    return candidateDocs;
+                }
+            }
+            // Fallback to linear search
+            return Object.values(this.dataMap).filter((doc) => this.matchesConditions(doc, where));
+        }
+        /**
+         * Helper method to check if a document matches the conditions
+         */
+        matchesConditions(doc, where) {
+            const model = doc.toModel();
+            return Object.entries(where).every(([key, value]) => {
+                if (!(key in model))
+                    return false;
+                return (Collection.hash(model[key]) ===
+                    Collection.hash(value));
+            });
+        }
+        /**
+         * Insert a new document into the collection
+         */
+        insertOne(data) {
+            const doc = new Document(data, this.counter++);
+            this.dataMap[doc._id] = doc;
+            // Add to indexes
+            this.addToIndexes(doc);
+            return doc;
+        }
+        /**
+         * Delete a document by _id or by matching conditions
+         */
+        deleteOne(where) {
+            const doc = this.findOne(where);
+            if (!doc) {
+                return false;
+            }
+            // Remove from indexes first
+            this.removeFromIndexes(doc);
+            // Remove from dataMap
+            delete this.dataMap[doc._id];
+            return true;
+        }
+        /**
+         * Find a document and update it with new data
+         *
+         * @example
+         * ```ts
+         * users.findOneAndUpdate({ id: 1 }, { name: "Updated" });
+         * ```
+         */
+        findOneAndUpdate(where, update) {
+            const doc = this.findOne(where);
+            if (!update)
+                return doc;
+            if (!doc) {
+                // If document not found, insert a new one with the provided update data
+                const newDoc = this.insertOne(update);
+                this.addToIndexes(newDoc);
+                return newDoc;
+            }
+            // Keep indexes consistent: remove old index entries, update, then re-index
+            this.removeFromIndexes(doc);
+            doc.updateData(update);
+            this.addToIndexes(doc);
+            return doc;
+        }
+        /**
+         * Insert multiple documents into the collection at once
+         * @param dataArray Array of data objects to insert
+         * @returns Array of inserted documents
+         */
+        insertMany(dataArray) {
+            const insertedDocs = [];
+            for (const data of dataArray) {
+                const doc = new Document(data, this.counter++);
+                this.dataMap[doc._id] = doc;
+                // Add to indexes
+                this.addToIndexes(doc);
+                insertedDocs.push(doc);
+            }
+            return insertedDocs;
+        }
+        /**
+         * Serialize the collection to a plain object for storage
+         * @returns A plain object representation of the collection
+         */
+        serialize() {
+            const data = {
+                counter: this.counter,
+                documents: Object.values(this.dataMap).map((doc) => doc.toModel()),
+            };
+            return JSON.stringify(data);
+        }
+        /**
+         * Deserialize and restore collection data from storage
+         * @param serializedData The serialized collection data
+         * @returns A new Collection instance with the restored data
+         */
+        static deserialize(name, serializedData) {
+            const collection = new Collection(name);
+            try {
+                const data = JSON.parse(serializedData);
+                // Restore counter
+                collection.counter = data.counter || 0;
+                // Restore documents
+                if (data.documents && Array.isArray(data.documents)) {
+                    for (let i = 0; i < data.documents.length; i++) {
+                        const docData = data.documents[i];
+                        const { _id } = docData, rest = __rest(docData, ["_id"]);
+                        // Create document without counter increment. Internal _id is generated.
+                        const doc = new Document(rest, i);
+                        // Add to dataMap using the generated internal id
+                        collection.dataMap[doc._id] = doc;
+                        // Rebuild indexes for this document
+                        collection.addToIndexes(doc);
+                    }
+                }
+            }
+            catch (error) {
+                console.error("Failed to deserialize collection data:", error);
+            }
+            return collection;
+        }
+        /**
+         * Hydrate the current collection instance with data from storage
+         * This clears existing data and replaces it with the deserialized data
+         * @param serializedData The serialized collection data
+         */
+        hydrate(serializedData) {
+            try {
+                const data = JSON.parse(serializedData);
+                // Clear existing data
+                this.dataMap = {};
+                this.indexes = {};
+                this.counter = data.counter || 0;
+                // Restore documents
+                if (data.documents && Array.isArray(data.documents)) {
+                    for (let i = 0; i < data.documents.length; i++) {
+                        const docData = data.documents[i];
+                        const { _id } = docData, rest = __rest(docData, ["_id"]);
+                        // Create document without counter increment. Internal _id is generated.
+                        const doc = new Document(rest, i);
+                        // Add to dataMap using the generated internal id
+                        this.dataMap[_id] = doc;
+                        // Rebuild indexes for this document
+                        this.addToIndexes(doc);
+                    }
+                }
+            }
+            catch (error) {
+                console.error("Failed to hydrate collection:", error);
+            }
+        }
+        /**
+         * Dehydrate the collection to a format suitable for storage
+         * This is an alias for serialize() for semantic clarity
+         * @returns A serialized string representation of the collection
+         */
+        dehydrate() {
+            return this.serialize();
+        }
+        static hash(data) {
+            // Browser-safe hashing: stable stringify + FNV-1a (32-bit).
+            return Collection.fnv1a(Collection.stableStringify(data));
+        }
+        static stableStringify(value) {
+            const type = typeof value;
+            if (value === null)
+                return "null";
+            if (type === "string")
+                return JSON.stringify(value);
+            if (type === "number") {
+                if (Number.isFinite(value))
+                    return String(value);
+                return JSON.stringify(String(value));
+            }
+            if (type === "boolean")
+                return value ? "true" : "false";
+            if (type === "undefined")
+                return "undefined";
+            if (type === "bigint")
+                return JSON.stringify(`bigint:${value.toString()}`);
+            if (type === "symbol")
+                return JSON.stringify(`symbol:${String(value)}`);
+            if (type === "function")
+                return JSON.stringify("function");
+            if (Array.isArray(value)) {
+                return ("[" + value.map((v) => Collection.stableStringify(v)).join(",") + "]");
+            }
+            if (value instanceof Date) {
+                return '{"$date":' + JSON.stringify(value.toISOString()) + "}";
+            }
+            // Plain object: sort keys for determinism
+            const keys = Object.keys(value).sort();
+            return ("{" +
+                keys
+                    .map((k) => JSON.stringify(k) + ":" + Collection.stableStringify(value[k]))
+                    .join(",") +
+                "}");
+        }
+        static fnv1a(input) {
+            // FNV-1a 32-bit
+            let hash = 0x811c9dc5;
+            for (let i = 0; i < input.length; i++) {
+                hash ^= input.charCodeAt(i);
+                hash = Math.imul(hash, 0x01000193);
+            }
+            // Unsigned + fixed-width hex to keep index keys uniform
+            return (hash >>> 0).toString(16).padStart(8, "0");
+        }
+    }
+
+    /**
+     * Storage adapter used by `Controller` to persist and hydrate snapshots.
+     *
+     * A controller stores a **full snapshot** (array of models) keyed by `name`.
+     * Implementations should be resilient: reads should return `[]` on failure.
+     */
+    class StorageManager {
+    }
+    /**
+     * No-op storage manager.
+     *
+     * Useful in environments where you don’t want persistence (tests, ephemeral caches, etc).
+     */
+    class DefaultStorageManager {
+        get(_name) {
+            return __awaiter(this, void 0, void 0, function* () {
+                return Promise.resolve([]);
+            });
+        }
+        set(_name, _models) {
+            return __awaiter(this, void 0, void 0, function* () {
+                return Promise.resolve();
+            });
+        }
+        delete(_name) {
+            return __awaiter(this, void 0, void 0, function* () {
+                return Promise.resolve();
+            });
+        }
+    }
+
+    /**
+     * Controller is the recommended integration layer for server-backed resources.
+     *
+     * It wraps a `Collection` with:
+     * - hydration (`initialise()`)
+     * - persistence (`commit()` writes a full snapshot using the configured `StorageManager`)
+     * - subscriptions (`publish()`)
+     * - invalidation hooks (`invalidate()`, `refetch()`)
+     *
+     * The intended mutation pattern is:
+     * 1) mutate `this.collection` (insert/update/delete)
+     * 2) call `await this.commit()` so subscribers update and storage persists
+     *
+     * @typeParam TVariable - the “data” shape stored in the collection (without `_id`)
+     * @typeParam TName - a stable, string-literal name for this controller/collection
+     *
+     * @example
+     * ```ts
+     * type User = { id: number; name: string };
+     *
+     * class UsersController extends Controller<User, "users"> {
+     *   async fetchAll(): Promise<[User[], number]> {
+     *     const res = await fetch("/api/users");
+     *     const data = (await res.json()) as User[];
+     *     return [data, data.length];
+     *   }
+     *
+     *   invalidate(): () => void {
+     *     this.abort();
+     *     void this.refetch();
+     *     return () => {};
+     *   }
+     *
+     *   async renameUser(id: number, name: string) {
+     *     this.collection.findOneAndUpdate({ id }, { name });
+     *     await this.commit();
+     *   }
+     * }
+     * ```
+     */
+    class Controller {
+        /**
+         * Abort any in-flight work owned by this controller (typically network fetches).
+         *
+         * This method also installs a new `AbortController` so subclasses can safely
+         * pass `this.abortController.signal` to the next request.
+         */
+        abort() {
+            if (this.abortController) {
+                this.abortController.abort();
+            }
+            this.abortController = new AbortController();
+        }
+        updateTotal(total) {
+            this.total = total;
+        }
+        updatePageSize(pageSize) {
+            this.pageSize = pageSize;
+        }
+        /**
+         * Fetch the complete dataset for this controller.
+         *
+         * Subclasses must implement this. Return `[rows, total]` where `total` is the
+         * total number of rows available on the backend (useful for pagination).
+         */
+        fetchAll() {
+            return __awaiter(this, void 0, void 0, function* () {
+                throw Error("Not Implemented");
+            });
+        }
+        /**
+         * Initialise (hydrate) the controller's collection.
+         *
+         * Resolution order:
+         * 1) If the in-memory collection is already non-empty: do nothing.
+         * 2) Else, try `storageManager.get(name)` and hydrate from persisted snapshot.
+         * 3) Else, call `fetchAll()` and populate from the backend.
+         *
+         * A successful initialise ends with `commit()` so subscribers receive the latest snapshot.
+         */
+        initialise() {
+            return __awaiter(this, void 0, void 0, function* () {
+                // If the collection is not empty, return.
+                let data = this.collection.find().map((doc) => doc.toData());
+                if (data.length !== 0)
+                    return;
+                // If the collection is empty, check the storage manager.
+                data = yield this.storageManager.get(this.name);
+                if (data.length !== 0) {
+                    this.updateTotal(this.collection.find().length);
+                    this.collection.insertMany(data);
+                    yield this.commit();
+                    return;
+                }
+                // If the storage manager is empty, fetch the data from the server.
+                try {
+                    this.loading = true;
+                    const [_data, total] = yield this.fetchAll();
+                    this.collection.insertMany(_data);
+                    this.updateTotal(total);
+                }
+                catch (error) {
+                    this.error = error;
+                }
+                finally {
+                    this.loading = false;
+                }
+                yield this.commit();
+            });
+        }
+        /**
+         * Subscribe to controller updates.
+         *
+         * The callback receives the full snapshot (`ModelType<TVariable>[]`) each time `commit()` runs.
+         * Returns an unsubscribe function.
+         *
+         * @example
+         * ```ts
+         * const unsubscribe = controller.publish((rows) => console.log(rows.length));
+         * // later...
+         * unsubscribe();
+         * ```
+         */
+        publish(onChange) {
+            this.subscribers.add(onChange);
+            return () => this.subscribers.delete(onChange);
+        }
+        /**
+         * Persist the latest snapshot and notify all subscribers.
+         *
+         * This is intentionally private: consumers should use `commit()` which computes the snapshot.
+         */
+        subscribe(model) {
+            return __awaiter(this, void 0, void 0, function* () {
+                // Persist the full cache snapshot for hydration.
+                yield this.storageManager.set(this.name, this.collection.find().map((doc) => doc.toModel()));
+                this.subscribers.forEach((sub) => {
+                    sub(model);
+                });
+            });
+        }
+        /**
+         * Publish + persist the current snapshot.
+         *
+         * Call this after any local mutation of `this.collection` so:
+         * - subscribers are updated (UI refresh)
+         * - the `StorageManager` has the latest snapshot for future hydration
+         */
+        commit() {
+            return __awaiter(this, void 0, void 0, function* () {
+                const models = this.collection.find().map((doc) => doc.toModel());
+                yield this.subscribe(models);
+            });
+        }
+        /**
+         * Refetch data using the controller's initialise flow.
+         *
+         * Subclasses typically use this inside `invalidate()`.
+         */
+        refetch() {
+            return this.initialise();
+        }
+        /**
+         * Invalidate the cache for this controller.
+         *
+         * Subclasses must implement this. Common patterns:
+         * - TTL based: refetch when expired
+         * - SWR: revalidate in background
+         * - push: refetch or patch based on websocket messages
+         *
+         * This method should return a cleanup function that unregisters any timers/listeners/sockets
+         * created as part of invalidation wiring.
+         */
+        invalidate(...data) {
+            throw Error("Not Implemented");
+        }
+        /**
+         * Clear in-memory cache and delete persisted snapshot.
+         * Publishes an empty snapshot to subscribers.
+         */
+        reset() {
+            void this.storageManager.delete(this.name);
+            this.collection.clear();
+            this.updateTotal(0);
+            this.updatePageSize(-1);
+            this.error = null;
+            this.loading = false;
+            void this.subscribe([]);
+        }
+        /**
+         * Create a controller.
+         *
+         * @param name - stable controller/collection name
+         * @param initialise - whether to run `initialise()` immediately
+         * @param storageManager - where snapshots are persisted (defaults to no-op)
+         * @param pageSize - optional pagination hint (userland)
+         */
+        constructor(name, initialise = true, storageManager = new DefaultStorageManager(), pageSize = -1) {
+            this.subscribers = new Set();
+            this.loading = false;
+            this.error = null;
+            this.total = -1;
+            this.pageSize = -1;
+            this.abortController = null;
+            this.collection = new Collection(name);
+            this.storageManager = storageManager;
+            this.name = name;
+            this.pageSize = pageSize;
+            if (initialise) {
+                void this.initialise();
+            }
+        }
+    }
+
+    function cartesian(arrays) {
+        if (arrays.length === 0)
+            return [[]];
+        for (const a of arrays)
+            if (a.length === 0)
+                return [];
+        let acc = [[]];
+        for (const items of arrays) {
+            const next = [];
+            for (const prefix of acc)
+                for (const item of items)
+                    next.push([...prefix, item]);
+            acc = next;
+        }
+        return acc;
+    }
+    function hasEq(value) {
+        return typeof value === "object" && value !== null && "$eq" in value;
+    }
+    function hasRef(value) {
+        return (typeof value === "object" &&
+            value !== null &&
+            "$ref" in value &&
+            typeof value.$ref === "object" &&
+            value.$ref !== null &&
+            "controller" in value.$ref &&
+            "field" in value.$ref);
+    }
+    function isJoinRefObject(value) {
+        return (typeof value === "object" &&
+            value !== null &&
+            "controller" in value &&
+            "field" in value);
+    }
+    function buildPrefilterObject(where) {
+        // Only include conditions that Collection can evaluate locally:
+        // - literal values
+        // - {$eq: literal}
+        // Excludes cross-controller comparisons ($ref, $eq with JoinRef).
+        const out = {};
+        for (const [k, v] of Object.entries(where)) {
+            if (hasRef(v))
+                continue;
+            if (hasEq(v)) {
+                const rhs = v.$eq;
+                if (isJoinRefObject(rhs))
+                    continue;
+                out[k] = rhs;
+                continue;
+            }
+            out[k] = v;
+        }
+        return out;
+    }
+    function getByName(comboByName, controller, field) {
+        var _a;
+        return (_a = comboByName[controller]) === null || _a === void 0 ? void 0 : _a[field];
+    }
+    function applyAliasesToModel(model, rawWhere, comboByName) {
+        for (const [field, cond] of Object.entries(rawWhere)) {
+            const as = cond === null || cond === void 0 ? void 0 : cond.$as;
+            if (!as)
+                continue;
+            // Prefer the local value; if missing, try resolving from ref/eq(rhs ref).
+            let value = model[field];
+            if (value === undefined) {
+                if (hasRef(cond)) {
+                    value = getByName(comboByName, cond.$ref.controller, cond.$ref.field);
+                }
+                else if (hasEq(cond) && isJoinRefObject(cond.$eq)) {
+                    const rhs = cond.$eq;
+                    value = getByName(comboByName, rhs.controller, rhs.field);
+                }
+            }
+            model[as] = value;
+        }
+    }
+    function join(from, where = {}, select) {
+        var _a;
+        const andWhere = ((_a = where.$and) !== null && _a !== void 0 ? _a : {});
+        const controllerNames = from.map((c) => c.name);
+        const perControllerMatches = from.map((c) => {
+            var _a;
+            const rawWhere = ((_a = andWhere[c.name]) !== null && _a !== void 0 ? _a : {});
+            const prefilter = buildPrefilterObject(rawWhere);
+            return c.collection.find(prefilter).map((d) => d.toModel());
+        });
+        const combos = cartesian(perControllerMatches);
+        const filtered = combos.filter((models) => {
+            var _a, _b, _c;
+            const byName = {};
+            for (let i = 0; i < controllerNames.length; i++)
+                byName[controllerNames[i]] = (_a = models[i]) !== null && _a !== void 0 ? _a : {};
+            for (const c of from) {
+                const rawWhere = ((_b = andWhere[c.name]) !== null && _b !== void 0 ? _b : {});
+                const model = (_c = byName[c.name]) !== null && _c !== void 0 ? _c : {};
+                for (const [field, cond] of Object.entries(rawWhere)) {
+                    if (hasRef(cond)) {
+                        const lhs = model[field];
+                        const rhs = getByName(byName, cond.$ref.controller, cond.$ref.field);
+                        if (lhs !== rhs)
+                            return false;
+                        continue;
+                    }
+                    if (hasEq(cond)) {
+                        const lhs = model[field];
+                        const rhs = cond.$eq;
+                        if (isJoinRefObject(rhs)) {
+                            const rhsVal = getByName(byName, rhs.controller, rhs.field);
+                            if (lhs !== rhsVal)
+                                return false;
+                        }
+                        else {
+                            if (lhs !== rhs)
+                                return false;
+                        }
+                    }
+                }
+            }
+            return true;
+        });
+        if (!select) {
+            return filtered.map((ms) => Object.assign({}, ...ms));
+        }
+        return filtered.map((ms) => {
+            var _a, _b, _c;
+            // Rebuild per-controller view to apply $as aliases deterministically.
+            const byName = {};
+            for (let i = 0; i < controllerNames.length; i++)
+                byName[controllerNames[i]] = Object.assign({}, ((_a = ms[i]) !== null && _a !== void 0 ? _a : {}));
+            for (const c of from) {
+                const rawWhere = ((_b = andWhere[c.name]) !== null && _b !== void 0 ? _b : {});
+                applyAliasesToModel((_c = byName[c.name]) !== null && _c !== void 0 ? _c : {}, rawWhere, byName);
+            }
+            // Now project.
+            const out = {};
+            const getQualified = (qualified) => {
+                var _a;
+                const dot = qualified.indexOf(".");
+                if (dot <= 0)
+                    return undefined;
+                const controller = qualified.slice(0, dot);
+                const field = qualified.slice(dot + 1);
+                const model = (_a = byName[controller]) !== null && _a !== void 0 ? _a : {};
+                return model[field];
+            };
+            if (Array.isArray(select)) {
+                for (const item of select) {
+                    if (typeof item === "string") {
+                        out[item] = getQualified(item);
+                        continue;
+                    }
+                    if (typeof item === "object" && item !== null) {
+                        for (const [key, as] of Object.entries(item)) {
+                            if (typeof as !== "string" || as.length === 0)
+                                continue;
+                            out[as] = getQualified(key);
+                        }
+                    }
+                }
+            }
+            else {
+                for (const [key, as] of Object.entries(select)) {
+                    if (typeof as !== "string" || as.length === 0)
+                        continue;
+                    out[as] = getQualified(key);
+                }
+            }
+            return out;
+        });
+    }
+
+    /**
+     * Registry for controllers, keyed by `controller.name`.
+     *
+     * Used by React helpers (`ContextProvider`, `useController`, `useRegister`), but
+     * can be used in any framework.
+     *
+     * @example
+     * ```ts
+     * const store = createObjectStore();
+     * store.register(new UsersController("users"));
+     * const users = store.get("users");
+     * ```
+     */
+    class ObjectStore {
+        constructor() {
+            this.store = new Map();
+        }
+        /**
+         * Register a controller instance in this store.
+         */
+        register(controller) {
+            this.store.set(controller.name, controller);
+        }
+        /**
+         * Get a controller by name.
+         *
+         * Throws if not found. Register controllers up front via `register()`.
+         */
+        get(name) {
+            const controller = this.store.get(name);
+            if (!controller) {
+                throw Error(`Controller with name ${name} is not registered`);
+            }
+            return controller;
+        }
+        /**
+         * Remove a controller from the store.
+         */
+        remove(name) {
+            this.store.delete(name);
+        }
+        /**
+         * Initialise all registered controllers.
+         *
+         * This is equivalent to calling `controller.initialise()` for each controller.
+         */
+        initialise() {
+            this.store.forEach((controller) => {
+                controller.initialise();
+            });
+        }
+    }
+    const _objectStore = new ObjectStore();
+    /**
+     * Returns a singleton store instance.
+     *
+     * `ContextProvider` uses this by default.
+     */
+    function getDefaultObjectStore() {
+        return _objectStore;
+    }
+    /**
+     * Create a new store instance (non-singleton).
+     */
+    function createObjectStore() {
+        return new ObjectStore();
+    }
+
+    /**
+     * IndexedDB-backed StorageManager.
+     *
+     * This is fully async (no in-memory cache needed).
+     *
+     * Stores snapshots as array-of-models under `${prefix}${name}`.
+     */
+    class IndexDbStorageManager extends StorageManager {
+        constructor(options = {}) {
+            var _a, _b, _c;
+            super();
+            this.dbPromise = null;
+            this.dbName = (_a = options.dbName) !== null && _a !== void 0 ? _a : "live-cache";
+            this.storeName = (_b = options.storeName) !== null && _b !== void 0 ? _b : "collections";
+            this.prefix = (_c = options.prefix) !== null && _c !== void 0 ? _c : "live-cache:";
+        }
+        key(name) {
+            return `${this.prefix}${name}`;
+        }
+        openDb() {
+            if (this.dbPromise)
+                return this.dbPromise;
+            this.dbPromise = new Promise((resolve, reject) => {
+                if (typeof indexedDB === "undefined") {
+                    reject(new Error("indexedDB is not available in this environment"));
+                    return;
+                }
+                const request = indexedDB.open(this.dbName, 1);
+                request.onupgradeneeded = () => {
+                    const db = request.result;
+                    if (!db.objectStoreNames.contains(this.storeName)) {
+                        db.createObjectStore(this.storeName);
+                    }
+                };
+                request.onsuccess = () => resolve(request.result);
+                request.onerror = () => { var _a; return reject((_a = request.error) !== null && _a !== void 0 ? _a : new Error("Failed to open IndexedDB")); };
+            });
+            return this.dbPromise;
+        }
+        idbGet(key) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const db = yield this.openDb();
+                return yield new Promise((resolve, reject) => {
+                    const tx = db.transaction(this.storeName, "readonly");
+                    const store = tx.objectStore(this.storeName);
+                    const req = store.get(key);
+                    req.onsuccess = () => {
+                        const value = req.result;
+                        if (!value)
+                            return resolve(null);
+                        resolve(Array.isArray(value) ? value : null);
+                    };
+                    req.onerror = () => { var _a; return reject((_a = req.error) !== null && _a !== void 0 ? _a : new Error("IndexedDB get failed")); };
+                });
+            });
+        }
+        idbSet(key, value) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const db = yield this.openDb();
+                yield new Promise((resolve, reject) => {
+                    const tx = db.transaction(this.storeName, "readwrite");
+                    const store = tx.objectStore(this.storeName);
+                    store.put(value, key);
+                    tx.oncomplete = () => resolve();
+                    tx.onerror = () => { var _a; return reject((_a = tx.error) !== null && _a !== void 0 ? _a : new Error("IndexedDB set failed")); };
+                    tx.onabort = () => { var _a; return reject((_a = tx.error) !== null && _a !== void 0 ? _a : new Error("IndexedDB set aborted")); };
+                });
+            });
+        }
+        idbDelete(key) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const db = yield this.openDb();
+                yield new Promise((resolve, reject) => {
+                    const tx = db.transaction(this.storeName, "readwrite");
+                    const store = tx.objectStore(this.storeName);
+                    store.delete(key);
+                    tx.oncomplete = () => resolve();
+                    tx.onerror = () => { var _a; return reject((_a = tx.error) !== null && _a !== void 0 ? _a : new Error("IndexedDB delete failed")); };
+                    tx.onabort = () => { var _a; return reject((_a = tx.error) !== null && _a !== void 0 ? _a : new Error("IndexedDB delete aborted")); };
+                });
+            });
+        }
+        get(name) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const k = this.key(name);
+                try {
+                    const value = yield this.idbGet(k);
+                    return (value !== null && value !== void 0 ? value : []);
+                }
+                catch (_a) {
+                    return [];
+                }
+            });
+        }
+        set(name, models) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const k = this.key(name);
+                const value = Array.isArray(models) ? models : [];
+                try {
+                    yield this.idbSet(k, value);
+                }
+                catch (_a) {
+                    // ignore write errors
+                }
+            });
+        }
+        delete(name) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const k = this.key(name);
+                try {
+                    yield this.idbDelete(k);
+                }
+                catch (_a) {
+                    // ignore delete errors
+                }
+            });
+        }
+    }
+
+    /**
+     * `localStorage`-backed `StorageManager`.
+     *
+     * Stores snapshots as JSON under `${prefix}${name}`.
+     * Reads return `[]` on failure (private mode, JSON parse issues, etc).
+     */
+    class LocalStorageStorageManager extends StorageManager {
+        constructor(prefix = "live-cache:") {
+            super();
+            this.prefix = prefix;
+        }
+        key(name) {
+            return `${this.prefix}${name}`;
+        }
+        get(name) {
+            return __awaiter(this, void 0, void 0, function* () {
+                try {
+                    const raw = localStorage.getItem(this.key(name));
+                    if (!raw)
+                        return [];
+                    const parsed = JSON.parse(raw);
+                    return Array.isArray(parsed) ? parsed : [];
+                }
+                catch (_a) {
+                    return [];
+                }
+            });
+        }
+        set(name, models) {
+            return __awaiter(this, void 0, void 0, function* () {
+                try {
+                    localStorage.setItem(this.key(name), JSON.stringify(models));
+                }
+                catch (_a) {
+                    // ignore quota / private mode issues
+                }
+            });
+        }
+        delete(name) {
+            return __awaiter(this, void 0, void 0, function* () {
+                try {
+                    localStorage.removeItem(this.key(name));
+                }
+                catch (_a) {
+                    // ignore
+                }
+            });
+        }
+    }
+
+    const context = React.createContext(null);
+    /**
+     * React context provider for an `ObjectStore`.
+     *
+     * `useController()` reads the store from this context by default.
+     *
+     * @example
+     * ```tsx
+     * <ContextProvider>
+     *   <App />
+     * </ContextProvider>
+     * ```
+     */
+    function ContextProvider({ children, store = getDefaultObjectStore(), }) {
+        return React.createElement(context.Provider, { value: store }, children);
+    }
+    /**
+     * Register controllers in a store (defaults to the singleton store).
+     *
+     * This is usually called at component mount time.
+     *
+     * @example
+     * ```tsx
+     * useRegister([usersController, postsController]);
+     * ```
+     */
+    function useRegister(controller, store = getDefaultObjectStore()) {
+        const stored = React.useMemo(() => {
+            controller.forEach((c) => {
+                store.register(c);
+            });
+            return store;
+        }, [store, controller]);
+        return stored;
+    }
+
+    /**
+     * React hook to subscribe to a registered controller.
+     *
+     * - Looks up the controller by name from the `ObjectStore` (context by default)
+     * - Subscribes to `controller.publish()`
+     * - Exposes `data`, `loading`, `error`, and the `controller` instance
+     *
+     * @param name - controller name
+     * @param where - optional `Collection.find()` filter (string `_id` or partial)
+     * @param options - store selection, initialise behavior, abort-on-unmount, and invalidation wiring
+     *
+     * When `options.withInvalidation` is true, this hook calls `controller.invalidate()` once on mount
+     * and calls the returned cleanup function on unmount.
+     *
+     * @example
+     * ```tsx
+     * const { data, controller } = useController<User, "users">("users");
+     * return (
+     *   <button onClick={() => void controller.invalidate()}>Refresh</button>
+     * );
+     * ```
+     */
+    function useController(name, where, options) {
+        var _a, _b, _c, _d;
+        const initialise = (_a = options === null || options === void 0 ? void 0 : options.initialise) !== null && _a !== void 0 ? _a : true;
+        const optionalStore = options === null || options === void 0 ? void 0 : options.store;
+        const abortOnUnmount = (_b = options === null || options === void 0 ? void 0 : options.abortOnUnmount) !== null && _b !== void 0 ? _b : true;
+        const withInvalidation = (_c = options === null || options === void 0 ? void 0 : options.withInvalidation) !== null && _c !== void 0 ? _c : true;
+        const [data, setData] = React.useState([]);
+        const [loading, setLoading] = React.useState(false);
+        const [error, setError] = React.useState(null);
+        const defaultStore = React.useContext(context);
+        const store = (_d = optionalStore !== null && optionalStore !== void 0 ? optionalStore : defaultStore) !== null && _d !== void 0 ? _d : null;
+        if (!store) {
+            throw Error("Store is not defined");
+        }
+        const controller = React.useMemo(() => store.get(name), [store, name]);
+        React.useEffect(() => {
+            if (initialise) {
+                controller.initialise();
+            }
+            const callback = () => {
+                var _a;
+                setLoading(controller.loading);
+                setError((_a = controller.error) !== null && _a !== void 0 ? _a : null);
+                setData(controller.collection.find(where).map((item) => item.toModel()));
+            };
+            // Prime state immediately.
+            callback();
+            const cleanup = controller.publish(callback);
+            let cleanupInvalidation = () => { };
+            if (withInvalidation) {
+                cleanupInvalidation = controller.invalidate();
+            }
+            return () => {
+                if (abortOnUnmount) {
+                    controller.abort();
+                }
+                cleanup();
+                cleanupInvalidation();
+            };
+        }, [controller, where, initialise, abortOnUnmount, withInvalidation]);
+        return { controller, data, loading, error };
+    }
+
+    /**
+     * React hook that recomputes a `join()` projection whenever any of the `from` controllers commit.
+     *
+     * @example
+     * ```tsx
+     * const rows = useJoinController({
+     *   from: [usersController, postsController] as const,
+     *   where: { $and: { posts: { userId: { $ref: { controller: "users", field: "id" } } } } } as const,
+     *   select: ["users.name", "posts.title"] as const,
+     * });
+     * ```
+     */
+    function useJoinController({ from, where, select }) {
+        const [data, setData] = React.useState([]);
+        React.useEffect(() => {
+            const callback = () => {
+                setData(join(from, where, select));
+            };
+            callback();
+            const cleanup = from.map((c) => c.publish(callback));
+            return () => {
+                cleanup.forEach((c) => c());
+            };
+        }, [from, where, select]);
+        return data;
+    }
+
+    // Main library exports
+    // Default export for UMD/browser usage
+    var index = {
+        Collection,
+        Controller,
+        Document,
+        join,
+        ObjectStore,
+        createObjectStore,
+        getDefaultObjectStore,
+        StorageManager,
+        DefaultStorageManager,
+        IndexDbStorageManager,
+        LocalStorageStorageManager,
+        ContextProvider,
+        useRegister,
+        useController,
+        useJoinController,
+    };
+
+    exports.Collection = Collection;
+    exports.ContextProvider = ContextProvider;
+    exports.Controller = Controller;
+    exports.DefaultStorageManager = DefaultStorageManager;
+    exports.Document = Document;
+    exports.IndexDbStorageManager = IndexDbStorageManager;
+    exports.LocalStorageStorageManager = LocalStorageStorageManager;
+    exports.ObjectStore = ObjectStore;
+    exports.StorageManager = StorageManager;
+    exports.createObjectStore = createObjectStore;
+    exports.default = index;
+    exports.getDefaultObjectStore = getDefaultObjectStore;
+    exports.join = join;
+    exports.useController = useController;
+    exports.useJoinController = useJoinController;
+    exports.useRegister = useRegister;
+
+    Object.defineProperty(exports, '__esModule', { value: true });
+
+}));
+//# sourceMappingURL=index.umd.js.map