live-cache 0.1.0 → 0.2.0

package/dist/index.cjs

@@ -449,6 +449,34 @@ class Collection {
     }
 }
 
+class Invalidator {
+    constructor() {
+        this.invalidator = (...data) => {
+            throw Error("The invalidator needs to be binded from the controller");
+        };
+    }
+    bind(invalidator) {
+        this.invalidator = invalidator;
+    }
+    registerInvalidation() {
+        throw Error("Method not implemented");
+    }
+    unregisterInvalidation() {
+        throw Error("Method not implemented");
+    }
+}
+class DefaultInvalidator extends Invalidator {
+    bind(invalidator) {
+        super.bind(invalidator);
+    }
+    registerInvalidation() {
+        // No-op
+    }
+    unregisterInvalidation() {
+        return () => { };
+    }
+}
+
 /**
  * Storage adapter used by `Controller` to persist and hydrate snapshots.
  *
@@ -456,19 +484,25 @@ class Collection {
  * Implementations should be resilient: reads should return `[]` on failure.
  */
 class StorageManager {
+    constructor(prefix) {
+        this.prefix = prefix;
+    }
 }
 /**
  * No-op storage manager.
  *
  * Useful in environments where you don’t want persistence (tests, ephemeral caches, etc).
  */
-class DefaultStorageManager {
-    get(_name) {
+class DefaultStorageManager extends StorageManager {
+    constructor(prefix) {
+        super(prefix);
+    }
+    get(name) {
         return __awaiter(this, void 0, void 0, function* () {
-            return Promise.resolve([]);
+            return Promise.resolve(null);
         });
     }
-    set(_name, _models) {
+    set(name, models) {
         return __awaiter(this, void 0, void 0, function* () {
             return Promise.resolve();
         });
@@ -478,48 +512,13 @@ class DefaultStorageManager {
             return Promise.resolve();
         });
     }
+    getParams() {
+        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).
@@ -562,12 +561,16 @@ class Controller {
      */
     initialise() {
         return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            if (this.loading)
+                return;
             // If the collection is not empty, return.
             let data = this.collection.find().map((doc) => doc.toData());
-            if (data.length !== 0)
+            if (data.length !== 0) {
                 return;
+            }
             // If the collection is empty, check the storage manager.
-            data = yield this.storageManager.get(this.name);
+            data = (_a = (yield this.storageManager.get(this.name))) !== null && _a !== void 0 ? _a : [];
             if (data.length !== 0) {
                 this.updateTotal(this.collection.find().length);
                 this.collection.insertMany(data);
@@ -580,6 +583,7 @@ class Controller {
                 const [_data, total] = yield this.fetchAll();
                 this.collection.insertMany(_data);
                 this.updateTotal(total);
+                yield this.commit();
             }
             catch (error) {
                 this.error = error;
@@ -587,7 +591,6 @@ class Controller {
             finally {
                 this.loading = false;
             }
-            yield this.commit();
         });
     }
     /**
@@ -673,23 +676,24 @@ class Controller {
      * 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) {
+    constructor(name, { storageManager = new DefaultStorageManager("live-cache:"), pageSize = -1, invalidator = new DefaultInvalidator(), initialiseOnMount = true, }) {
         this.subscribers = new Set();
         this.loading = false;
         this.error = null;
         this.total = -1;
         this.pageSize = -1;
         this.abortController = null;
+        this.name = name;
         this.collection = new Collection(name);
         this.storageManager = storageManager;
-        this.name = name;
         this.pageSize = pageSize;
-        if (initialise) {
-            void this.initialise();
+        this.invalidator = invalidator;
+        this.invalidator.bind(this.invalidate.bind(this));
+        if (initialiseOnMount) {
+            this.initialise();
         }
     }
 }
@@ -865,6 +869,28 @@ function join(from, where = {}, select) {
         return out;
     });
 }
+// // Type-check-only example (kept unreachable to avoid runtime side effects).
+// if (false) {
+//     join(
+//         [
+//             new Controller<{ name: string; age: number; city: string }, "users">("users"),
+//             new Controller<{ name: string; title: string; body: string; creator: string }, "posts">("posts"),
+//         ],
+//         {
+//             $and: {
+//                 users: {
+//                     name: {
+//                         $ref: {
+//                             controller: "posts",
+//                             field: "creator",
+//                         },
+//                     },
+//                 },
+//             },
+//         } as const,
+//         ["posts._id"]
+//     )[0];
+// }
 
 /**
  * Registry for controllers, keyed by `controller.name`.
@@ -882,6 +908,7 @@ function join(from, where = {}, select) {
 class ObjectStore {
     constructor() {
         this.store = new Map();
+        this.initialisePromises = new WeakMap();
     }
     /**
      * Register a controller instance in this store.
@@ -917,6 +944,22 @@ class ObjectStore {
             controller.initialise();
         });
     }
+    /**
+     * Initialise a controller once per store, even if multiple callers request it.
+     */
+    initialiseOnce(name) {
+        const controller = this.get(name);
+        const existing = this.initialisePromises.get(controller);
+        if (existing)
+            return existing;
+        const promise = controller.initialise().finally(() => {
+            if (this.initialisePromises.get(controller) === promise) {
+                this.initialisePromises.delete(controller);
+            }
+        });
+        this.initialisePromises.set(controller, promise);
+        return promise;
+    }
 }
 const _objectStore = new ObjectStore();
 /**
@@ -934,6 +977,84 @@ function createObjectStore() {
     return new ObjectStore();
 }
 
+class TransactionsInstance {
+    constructor(storageManager) {
+        this.storageManager = storageManager;
+    }
+    add(collection) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const transaction_name = `transaction::${collection.name}::${Date.now()}`;
+            yield this.storageManager.set(transaction_name, collection.serialize());
+            return transaction_name;
+        });
+    }
+    rollback(transaction_name, name) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const collection = yield this.get(transaction_name, name);
+            yield this.storageManager.delete(transaction_name);
+            return collection;
+        });
+    }
+    finish(name) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const params = yield this.storageManager.getParams();
+            const _txn_name = `transaction::${name}::`;
+            for (const param of params) {
+                if (param.startsWith(_txn_name)) {
+                    yield this.storageManager.delete(param);
+                }
+            }
+        });
+    }
+    get(transaction_name, name) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const serialized = yield this.storageManager.get(transaction_name);
+            if (!serialized) {
+                throw new Error("Transaction not found");
+            }
+            return Collection.deserialize(name, serialized);
+        });
+    }
+}
+class Transactions {
+    static createInstance(storageManager) {
+        if (Transactions.instance) {
+            throw new Error("Transactions instance already initialized");
+        }
+        Transactions.instance = new TransactionsInstance(storageManager);
+    }
+    static getInstance() {
+        if (!Transactions.instance) {
+            throw new Error("Transactions instance not initialized");
+        }
+        return Transactions.instance;
+    }
+    static add(collection) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const instance = Transactions.getInstance();
+            return instance.add(collection);
+        });
+    }
+    static rollback(transaction_name, name) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const instance = Transactions.getInstance();
+            return instance.rollback(transaction_name, name);
+        });
+    }
+    static finish(name) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const instance = Transactions.getInstance();
+            return instance.finish(name);
+        });
+    }
+    static get(transaction_name, name) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const instance = Transactions.getInstance();
+            return instance.get(transaction_name, name);
+        });
+    }
+}
+
 /**
  * IndexedDB-backed StorageManager.
  *
@@ -943,12 +1064,12 @@ function createObjectStore() {
  */
 class IndexDbStorageManager extends StorageManager {
     constructor(options = {}) {
-        var _a, _b, _c;
-        super();
+        var _a, _b, _c, _d;
+        super((_a = options.prefix) !== null && _a !== void 0 ? _a : "live-cache:");
         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:";
+        this.dbName = (_b = options.dbName) !== null && _b !== void 0 ? _b : "live-cache";
+        this.storeName = (_c = options.storeName) !== null && _c !== void 0 ? _c : "collections";
+        this.prefix = (_d = options.prefix) !== null && _d !== void 0 ? _d : "live-cache:";
     }
     key(name) {
         return `${this.prefix}${name}`;
@@ -1051,6 +1172,17 @@ class IndexDbStorageManager extends StorageManager {
             }
         });
     }
+    getParams() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const db = yield this.openDb();
+            return new Promise((resolve, reject) => {
+                const req = db.transaction(this.storeName, "readonly").objectStore(this.storeName).getAllKeys();
+                const keys = req.result.map(x => x.toString().replace(this.prefix, ""));
+                req.onsuccess = () => resolve(keys);
+                req.onerror = () => { var _a; return reject((_a = req.error) !== null && _a !== void 0 ? _a : new Error("IndexedDB get params failed")); };
+            });
+        });
+    }
 }
 
 /**
@@ -1061,8 +1193,7 @@ class IndexDbStorageManager extends StorageManager {
  */
 class LocalStorageStorageManager extends StorageManager {
     constructor(prefix = "live-cache:") {
-        super();
-        this.prefix = prefix;
+        super(prefix);
     }
     key(name) {
         return `${this.prefix}${name}`;
@@ -1101,6 +1232,11 @@ class LocalStorageStorageManager extends StorageManager {
             }
         });
     }
+    getParams() {
+        return __awaiter(this, void 0, void 0, function* () {
+            return Object.keys(localStorage).filter(key => key.startsWith(this.prefix)).map(key => key.replace(this.prefix, ""));
+        });
+    }
 }
 
 const context = React.createContext(null);
@@ -1150,12 +1286,15 @@ function useRegister(controller, store = getDefaultObjectStore()) {
  * @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.
+ * When `options.withInvalidation` is true, this hook calls
+ * `controller.invalidator.registerInvalidation()` on mount and
+ * `controller.invalidator.unregisterInvalidation()` on unmount.
  *
  * @example
  * ```tsx
- * const { data, controller } = useController<User, "users">("users");
+ * const { data, controller } = useController<User, "users">("users", undefined, {
+ *   withInvalidation: true,
+ * });
  * return (
  *   <button onClick={() => void controller.invalidate()}>Refresh</button>
  * );
@@ -1177,9 +1316,6 @@ function useController(name, where, options) {
     }
     const controller = React.useMemo(() => store.get(name), [store, name]);
     React.useEffect(() => {
-        if (initialise) {
-            controller.initialise();
-        }
         const callback = () => {
             var _a;
             setLoading(controller.loading);
@@ -1189,16 +1325,18 @@ function useController(name, where, options) {
         // Prime state immediately.
         callback();
         const cleanup = controller.publish(callback);
-        let cleanupInvalidation = () => { };
         if (withInvalidation) {
-            cleanupInvalidation = controller.invalidate();
+            controller.invalidator.registerInvalidation();
+        }
+        if (initialise) {
+            void store.initialiseOnce(name);
         }
         return () => {
             if (abortOnUnmount) {
                 controller.abort();
             }
             cleanup();
-            cleanupInvalidation();
+            controller.invalidator.unregisterInvalidation();
         };
     }, [controller, where, initialise, abortOnUnmount, withInvalidation]);
     return { controller, data, loading, error };
@@ -1231,6 +1369,34 @@ function useJoinController({ from, where, select }) {
     return data;
 }
 
+class TimeoutInvalidator extends Invalidator {
+    constructor(timeoutMs = 0, options = {}) {
+        var _a;
+        super();
+        this.intervalId = null;
+        this.timeoutMs = timeoutMs;
+        this.immediate = (_a = options.immediate) !== null && _a !== void 0 ? _a : true;
+    }
+    registerInvalidation() {
+        if (this.intervalId)
+            return;
+        if (this.immediate) {
+            this.invalidator();
+        }
+        if (this.timeoutMs > 0) {
+            this.intervalId = setInterval(() => {
+                this.invalidator();
+            }, this.timeoutMs);
+        }
+    }
+    unregisterInvalidation() {
+        if (!this.intervalId)
+            return;
+        clearInterval(this.intervalId);
+        this.intervalId = null;
+    }
+}
+
 // Main library exports
 // Default export for UMD/browser usage
 var index = {
@@ -1241,6 +1407,7 @@ var index = {
     ObjectStore,
     createObjectStore,
     getDefaultObjectStore,
+    Transactions,
     StorageManager,
     DefaultStorageManager,
     IndexDbStorageManager,
@@ -1249,17 +1416,24 @@ var index = {
     useRegister,
     useController,
     useJoinController,
+    DefaultInvalidator,
+    Invalidator,
+    TimeoutInvalidator,
 };
 
 exports.Collection = Collection;
 exports.ContextProvider = ContextProvider;
 exports.Controller = Controller;
+exports.DefaultInvalidator = DefaultInvalidator;
 exports.DefaultStorageManager = DefaultStorageManager;
 exports.Document = Document;
 exports.IndexDbStorageManager = IndexDbStorageManager;
+exports.Invalidator = Invalidator;
 exports.LocalStorageStorageManager = LocalStorageStorageManager;
 exports.ObjectStore = ObjectStore;
 exports.StorageManager = StorageManager;
+exports.TimeoutInvalidator = TimeoutInvalidator;
+exports.Transactions = Transactions;
 exports.createObjectStore = createObjectStore;
 exports.default = index;
 exports.getDefaultObjectStore = getDefaultObjectStore;