live-cache 0.1.0

package/dist/core/Controller.d.ts

@@ -0,0 +1,141 @@
+import Collection from "./Collection";
+import { ModelType } from "./Document";
+import { DefaultStorageManager, StorageManager } from "./StorageManager";
+/**
+ * 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();
+ *   }
+ * }
+ * ```
+ */
+export default class Controller<TVariable, TName extends string> {
+    name: TName;
+    collection: Collection<TVariable, TName>;
+    protected subscribers: Set<(model: ModelType<TVariable>[]) => void>;
+    protected storageManager: StorageManager<TVariable>;
+    loading: boolean;
+    error: unknown;
+    total: number;
+    pageSize: number;
+    abortController: AbortController | null;
+    /**
+     * 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(): void;
+    protected updateTotal(total: number): void;
+    protected updatePageSize(pageSize: number): void;
+    /**
+     * 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(): Promise<[TVariable[], number]>;
+    /**
+     * 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(): Promise<void>;
+    /**
+     * 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: (data: ModelType<TVariable>[]) => void): () => boolean;
+    /**
+     * Persist the latest snapshot and notify all subscribers.
+     *
+     * This is intentionally private: consumers should use `commit()` which computes the snapshot.
+     */
+    private subscribe;
+    /**
+     * 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(): Promise<void>;
+    /**
+     * Refetch data using the controller's initialise flow.
+     *
+     * Subclasses typically use this inside `invalidate()`.
+     */
+    protected refetch(): Promise<void>;
+    /**
+     * 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: TVariable[]): () => void;
+    /**
+     * Clear in-memory cache and delete persisted snapshot.
+     * Publishes an empty snapshot to subscribers.
+     */
+    reset(): void;
+    /**
+     * 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: TName, initialise?: boolean, storageManager?: DefaultStorageManager<TVariable>, pageSize?: number);
+}

package/dist/core/Document.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 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`
+ */
+export default class Document<TVariable> {
+    _id: string;
+    private data;
+    updatedAt: number;
+    private static processId;
+    constructor(data: TVariable, counter?: number);
+    updateData(data: Partial<TVariable>): void;
+    /**
+     * Convert to a plain model including `_id`.
+     */
+    toModel(): {
+        _id: string;
+    } & TVariable;
+    /**
+     * Convert to raw data (without `_id`).
+     */
+    toData(): TVariable;
+    /**
+     * Generate a MongoDB-style ObjectId (24 hex characters).
+     *
+     * Format: timestamp (4 bytes) + random process id (5 bytes) + counter (3 bytes)
+     */
+    static generateId(_counter: number): string;
+}
+/**
+ * Convenience type: the return type of `Document<T>["toModel"]`.
+ */
+export type ModelType<K> = ReturnType<Document<K>["toModel"]>;

package/dist/core/ObjectStore.d.ts

@@ -0,0 +1,47 @@
+import Controller from "./Controller";
+/**
+ * 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");
+ * ```
+ */
+export default class ObjectStore {
+    store: Map<string, Controller<any, any>>;
+    /**
+     * Register a controller instance in this store.
+     */
+    register<TVariable, TName extends string>(controller: Controller<TVariable, TName>): void;
+    /**
+     * Get a controller by name.
+     *
+     * Throws if not found. Register controllers up front via `register()`.
+     */
+    get<TVariable, TName extends string>(name: TName): Controller<TVariable, TName>;
+    /**
+     * Remove a controller from the store.
+     */
+    remove<TVariable, TName extends string>(name: TName): void;
+    /**
+     * Initialise all registered controllers.
+     *
+     * This is equivalent to calling `controller.initialise()` for each controller.
+     */
+    initialise(): void;
+}
+/**
+ * Returns a singleton store instance.
+ *
+ * `ContextProvider` uses this by default.
+ */
+export declare function getDefaultObjectStore(): ObjectStore;
+/**
+ * Create a new store instance (non-singleton).
+ */
+export declare function createObjectStore(): ObjectStore;

package/dist/core/StorageManager.d.ts

@@ -0,0 +1,35 @@
+import { ModelType } from "./Document";
+/**
+ * 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.
+ */
+export declare abstract class StorageManager<TVariable> {
+    /**
+     * Get a previously persisted snapshot for a controller name.
+     *
+     * @returns Array of models (each model includes `_id`)
+     */
+    abstract get<T>(name: string): Promise<ModelType<T>[]>;
+    /**
+     * Persist a snapshot for a controller name.
+     *
+     * Controllers call this from `commit()`.
+     */
+    abstract set<T>(name: string, models: ModelType<T>[]): Promise<void>;
+    /**
+     * Delete the persisted snapshot for a controller name.
+     */
+    abstract delete(name: string): Promise<void>;
+}
+/**
+ * No-op storage manager.
+ *
+ * Useful in environments where you don’t want persistence (tests, ephemeral caches, etc).
+ */
+export declare class DefaultStorageManager<TVariable> implements StorageManager<TVariable> {
+    get<T>(_name: string): Promise<ModelType<T>[]>;
+    set<T>(_name: string, _models: ModelType<T>[]): Promise<void>;
+    delete(_name: string): Promise<void>;
+}

package/dist/core/join.d.ts

@@ -0,0 +1,106 @@
+import Controller from "./Controller";
+import { ModelType } from "./Document";
+/**
+ * Join data across multiple controllers by applying cross-controller equality constraints.
+ *
+ * `where.$and[controllerName]` can include:
+ * - literal: `{ id: 1 }`
+ * - join ref: `{ userId: { $ref: { controller: "users", field: "id" } } }`
+ * - eq: `{ status: { $eq: "active" } }`
+ *
+ * `select` supports:
+ * - array of qualified keys: `["users.id", "posts.title"]`
+ * - select-map for aliasing: `{ "users.id": "userId", "posts.title": "title" }`
+ * - mixed array: `["users.id", { "posts.title": "title" }]`
+ *
+ * @example
+ * ```ts
+ * const rows = join(
+ *   [usersController, postsController] as const,
+ *   {
+ *     $and: {
+ *       posts: { userId: { $ref: { controller: "users", field: "id" } } },
+ *     },
+ *   } as const,
+ *   ["users.name", "posts.title"] as const,
+ * );
+ * ```
+ */
+type ControllerName<C> = C extends Controller<any, infer N> ? N : never;
+type ControllerVar<C> = C extends Controller<infer V, any> ? V : never;
+type Tuple2Plus = readonly [
+    Controller<any, any>,
+    Controller<any, any>,
+    ...Controller<any, any>[]
+];
+type Names<Cs extends readonly Controller<any, any>[]> = ControllerName<Cs[number]>;
+type ControllerOfName<Cs extends readonly Controller<any, any>[], N extends string> = Extract<Cs[number], Controller<any, N>>;
+type ModelOfName<Cs extends readonly Controller<any, any>[], N extends string> = ModelType<ControllerVar<ControllerOfName<Cs, N>>>;
+export type JoinRef<Cs extends readonly Controller<any, any>[]> = {
+    [N in Names<Cs>]: {
+        controller: N;
+        field: keyof ModelOfName<Cs, N>;
+    };
+}[Names<Cs>];
+type JoinEq<Cs extends readonly Controller<any, any>[], N extends Names<Cs>, K extends keyof ModelOfName<Cs, N>> = {
+    $eq: ModelOfName<Cs, N>[K] | JoinRef<Cs>;
+    $as?: string;
+};
+type JoinRefCond<Cs extends readonly Controller<any, any>[]> = {
+    $ref: JoinRef<Cs>;
+    $as?: string;
+};
+export type FieldCondition<Cs extends readonly Controller<any, any>[], N extends Names<Cs>, K extends keyof ModelOfName<Cs, N>> = ModelOfName<Cs, N>[K] | JoinEq<Cs, N, K> | JoinRefCond<Cs>;
+type PerControllerWhere<Cs extends readonly Controller<any, any>[], N extends Names<Cs>> = Partial<{
+    [K in keyof ModelOfName<Cs, N>]: FieldCondition<Cs, N, K>;
+}>;
+type AndWhere<Cs extends readonly Controller<any, any>[]> = Partial<{
+    [N in Names<Cs>]: PerControllerWhere<Cs, N>;
+}>;
+export type JoinWhere<Cs extends readonly Controller<any, any>[]> = {
+    $and?: AndWhere<Cs>;
+};
+type ExtractAs<T> = T extends {
+    $as?: infer S;
+} ? (S extends string ? S : never) : never;
+type AsInPerControllerWhere<T> = T extends object ? ExtractAs<T[keyof T]> : never;
+type AsInAndWhere<T> = T extends object ? AsInPerControllerWhere<T[keyof T]> : never;
+type AsInJoinWhere<W> = W extends {
+    $and?: infer A;
+} ? AsInAndWhere<A> : never;
+type QualifiedModelKey<Cs extends readonly Controller<any, any>[]> = {
+    [N in Names<Cs>]: `${N}.${Extract<keyof ModelOfName<Cs, N>, string>}`;
+}[Names<Cs>];
+type QualifiedAsKey<Cs extends readonly Controller<any, any>[], W> = AsInJoinWhere<W> extends infer A ? A extends string ? `${Names<Cs>}.${A}` : never : never;
+type SelectKey<Cs extends readonly Controller<any, any>[], W> = QualifiedModelKey<Cs> | QualifiedAsKey<Cs, W>;
+type ValueForKey<Cs extends readonly Controller<any, any>[], K extends PropertyKey> = K extends `${infer N}.${infer F}` ? N extends Names<Cs> ? F extends keyof ModelOfName<Cs, N> ? ModelOfName<Cs, N>[F] : unknown : unknown : unknown;
+type ProjectionFromSelect<Cs extends readonly Controller<any, any>[], S extends readonly PropertyKey[]> = {
+    [K in S[number]]: ValueForKey<Cs, K>;
+};
+type SelectMap<Cs extends readonly Controller<any, any>[], W> = Partial<Record<SelectKey<Cs, W>, string>>;
+type ProjectionFromSelectMap<Cs extends readonly Controller<any, any>[], M extends Partial<Record<PropertyKey, string>>> = {
+    [K in keyof M as M[K] extends string ? M[K] : never]: ValueForKey<Cs, K>;
+};
+type ProjectionFromSelectMapSafe<Cs extends readonly Controller<any, any>[], M> = M extends Partial<Record<PropertyKey, string>> ? ProjectionFromSelectMap<Cs, M> : {};
+type UnionToIntersection<U> = [
+    U
+] extends [never] ? {} : (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : {};
+type MixedSelect<Cs extends readonly Controller<any, any>[], W> = readonly (SelectKey<Cs, W> | SelectMap<Cs, W>)[];
+type KeysFromMixedSelect<SA extends readonly unknown[]> = Extract<SA[number], PropertyKey>;
+type MapsFromMixedSelect<SA extends readonly unknown[]> = Extract<SA[number], Partial<Record<PropertyKey, string>>>;
+type ProjectionFromMixedSelect<Cs extends readonly Controller<any, any>[], SA extends readonly unknown[]> = ProjectionFromSelect<Cs, readonly KeysFromMixedSelect<SA>[]> & ProjectionFromSelectMapSafe<Cs, UnionToIntersection<MapsFromMixedSelect<SA>>>;
+/**
+ * Joins data across controllers.
+ *
+ * `where.$and[controllerName]` can include:
+ * - literal: `{ id: 1 }`
+ * - join: `{ userId: { $ref: { controller: \"users\", field: \"id\" }, $as?: \"userId\" } }`
+ * - eq: `{ status: { $eq: \"active\", $as?: \"state\" } }`
+ *
+ * `$as` aliases the value into the output object (legacy).
+ * Prefer passing `select` as an object: `{ fieldName: "alias" }`.
+ */
+export default function join<const Cs extends Tuple2Plus, const W extends JoinWhere<Cs>, const S extends readonly SelectKey<Cs, W>[]>(from: Cs, where: W, select: S): Array<ProjectionFromSelect<Cs, S>>;
+export default function join<const Cs extends Tuple2Plus, const W extends JoinWhere<Cs>, const SM extends SelectMap<Cs, W>>(from: Cs, where: W, select: SM & SelectMap<Cs, W>): Array<ProjectionFromSelectMap<Cs, SM>>;
+export default function join<const Cs extends Tuple2Plus, const W extends JoinWhere<Cs>, const SA extends MixedSelect<Cs, W>>(from: Cs, where: W, select: SA): Array<ProjectionFromMixedSelect<Cs, SA>>;
+export {};