live-cache 0.1.0

package/dist/index.mjs

@@ -0,0 +1,1251 @@
+import React, { createContext, useMemo, useState, useContext, useEffect } from 'react';
+
+/******************************************************************************
+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 = 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 = 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] = useState([]);
+    const [loading, setLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const defaultStore = 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 = useMemo(() => store.get(name), [store, name]);
+    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] = useState([]);
+    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,
+};
+
+export { Collection, ContextProvider, Controller, DefaultStorageManager, Document, IndexDbStorageManager, LocalStorageStorageManager, ObjectStore, StorageManager, createObjectStore, index as default, getDefaultObjectStore, join, useController, useJoinController, useRegister };
+//# sourceMappingURL=index.mjs.map