zerodrift 1.0.0

package/dist/core/LazyCollection.d.ts

@@ -0,0 +1,168 @@
+/**
+ * RefCollection and BackRef
+ *
+ * Runtime objects backing the collection / back-reference decorators. When a
+ * model is hydrated, each @ReferenceCollection / @LazyReferenceCollection
+ * property becomes a `RefCollection` instance, and each @BackReference becomes
+ * a `BackRef`. The runtime shape is identical regardless of whether the
+ * decorator is eager or lazy — eager just auto-fires `.load()` during
+ * makeModelObservable().
+ *
+ * Key behaviors:
+ *
+ *   RefCollection:
+ *     - Stores partial index values (e.g. "all Issues where teamId = team.id")
+ *     - On first access, queries ObjectPool for already-loaded matches
+ *     - If not fully loaded, queries IDB by index
+ *     - Tracks loading state (idle → loading → loaded)
+ *     - After a delta packet adds/removes items, can be invalidated and re-queried
+ *
+ *   BackRef:
+ *     - Resolves a single inverse model (e.g. Issue.favorite → Favorite)
+ *     - Supports cascade delete: when the owning model is deleted,
+ *       the back-referenced model is also removed from the pool
+ *
+ * Usage from React:
+ *   const { data: team } = useRecord(Team, teamId);
+ *   const { items, isLoading, load } = team.issues;  // RefCollection
+ *   // or via hook:
+ *   const { data, isLoading } = useRelation(team?.issues);
+ */
+import type { BaseModel } from "./BaseModel";
+import type { CoveringPath } from "./types";
+export declare enum CollectionState {
+    /** Never accessed — hydrate() computed the index values but no load yet. */
+    Idle = "idle",
+    /** Async load from IDB/server is in progress. */
+    Loading = "loading",
+    /** Load completed. Items are available. */
+    Loaded = "loaded",
+    /** Load failed. */
+    Error = "error"
+}
+export declare abstract class LazyCollectionBase<T extends BaseModel = BaseModel> {
+    items: T[];
+    state: CollectionState;
+    error: Error | null;
+    readonly referencedModelName: string;
+    private listeners;
+    private inFlight;
+    private onErrorHandler;
+    constructor(referencedModelName: string);
+    /** Wire a side-channel error reporter. Called by the loader's catch block in
+     * subclasses, in addition to setting `state = Error` and `.error`. Used by
+     * StoreManager to route into `config.onError` for telemetry. */
+    setOnError(handler: (err: Error) => void): void;
+    protected reportError(err: Error): void;
+    /** Subclass implementation. `load()` wraps this with concurrent-call dedup. */
+    protected abstract runLoad(): Promise<T[]>;
+    load(): Promise<T[]>;
+    invalidate(): void;
+    reload(): Promise<T[]>;
+    /**
+     * Splice an instance into items reactively. Idempotent — duplicates by id are
+     * skipped. Called by the ObjectPool when a child enters the pool with a
+     * matching foreign key, or moves into this parent.
+     */
+    attach(item: T): void;
+    /**
+     * Remove an instance from items reactively. No-op if missing. Called by the
+     * ObjectPool when a child is removed from the pool, or moves to a different
+     * parent.
+     */
+    detach(itemId: string): void;
+    /**
+     * Replace items wholesale. Used by the ObjectPool to backfill when a parent
+     * enters the pool after children were already present.
+     */
+    setItems(items: T[]): void;
+    get isLoaded(): boolean;
+    get isLoading(): boolean;
+    get length(): number;
+    /** Observe set-membership changes (items added / removed / replaced).
+     * Payload-less — re-read `items` inside the listener. Returns an
+     * unsubscribe function. The single subscription verb across the public
+     * surface (`record.watch`, `store.<entity>.watchAll`). */
+    watch(listener: () => void): () => void;
+    protected notifyListeners(): void;
+}
+export declare class RefCollection<T extends BaseModel = BaseModel> extends LazyCollectionBase<T> {
+    /** The foreign key on the child model (e.g. "teamId"). */
+    readonly inverseKey: string;
+    /** Additional FK axes on the parent that the loader should also query. */
+    readonly coveringIndexes: string[];
+    /** Auto-derived covering paths from the registry FK walk. Each path is
+     * resolved at hydrate time — depth 1 paths read directly from the parent;
+     * deeper paths walk the pool. Manual `coveringIndexes` and these paths
+     * are union'd into `partialIndexValues`, deduped by (axis, value). */
+    readonly derivedCoveringPaths: CoveringPath[];
+    /** The ID of the parent model (e.g. team.id). Set during hydrate(). */
+    parentId: string;
+    /**
+     * Cached covering values. Built in `hydrate()` from the parent's id +
+     * `coveringIndexes` axes; `runLoad` passes this to the loader, which
+     * turns each entry into a `getOrLoadCollection` call and unions the results.
+     */
+    private partialIndexValues;
+    private loader;
+    constructor(referencedModelName: string, inverseKey: string, coveringIndexes?: string[], derivedCoveringPaths?: CoveringPath[]);
+    /**
+     * Called by Model.hydrate() after the parent model is populated.
+     * Computes the covering partial-index values used for future loads.
+     */
+    hydrate(parent: BaseModel): void;
+    /**
+     * The set of (key, value) queries this collection's loader will run. One
+     * entry for the FK match; one per covering axis whose value is non-empty
+     * on the parent.
+     */
+    getCoveringPartialIndexValues(): ReadonlyArray<{
+        key: string;
+        value: string;
+    }>;
+    /** Wire the loader function. Called by StoreManager. */
+    setLoader(loader: (modelName: string, queries: Array<{
+        key: string;
+        value: string;
+    }>) => Promise<T[]>): void;
+    /**
+     * Resolve items already in the ObjectPool synchronously.
+     * Used for eager-load models where everything is in memory after bootstrap.
+     */
+    resolveFromPool(pool: {
+        getAll(name: string): BaseModel[];
+    }): T[];
+    protected runLoad(): Promise<T[]>;
+}
+export declare class BackRef<T extends BaseModel = BaseModel> {
+    value: T | null;
+    state: CollectionState;
+    error: Error | null;
+    readonly referencedModelName: string;
+    readonly inverseOf: string;
+    parentId: string;
+    private loader;
+    private onErrorHandler;
+    constructor(referencedModelName: string, inverseOf: string);
+    hydrate(parentId: string): void;
+    setLoader(loader: (modelName: string, key: string, value: string) => Promise<T | null>): void;
+    setOnError(handler: (err: Error) => void): void;
+    /** Resolve from pool synchronously. */
+    resolveFromPool(pool: {
+        getAll(name: string): BaseModel[];
+    }): T | null;
+    load(): Promise<T | null>;
+    invalidate(): void;
+    /**
+     * Set the resolved value reactively. Used by the ObjectPool when a model
+     * matching this back-reference enters the pool. Idempotent on identity.
+     */
+    attach(item: T): void;
+    /**
+     * Clear the resolved value reactively. Used by the ObjectPool when the
+     * referenced model leaves the pool or its inverse key changes.
+     */
+    detach(itemId: string): void;
+    get isLoaded(): boolean;
+    get isLoading(): boolean;
+}

package/dist/core/LazyCollection.js

@@ -0,0 +1,403 @@
+/**
+ * RefCollection and BackRef
+ *
+ * Runtime objects backing the collection / back-reference decorators. When a
+ * model is hydrated, each @ReferenceCollection / @LazyReferenceCollection
+ * property becomes a `RefCollection` instance, and each @BackReference becomes
+ * a `BackRef`. The runtime shape is identical regardless of whether the
+ * decorator is eager or lazy — eager just auto-fires `.load()` during
+ * makeModelObservable().
+ *
+ * Key behaviors:
+ *
+ *   RefCollection:
+ *     - Stores partial index values (e.g. "all Issues where teamId = team.id")
+ *     - On first access, queries ObjectPool for already-loaded matches
+ *     - If not fully loaded, queries IDB by index
+ *     - Tracks loading state (idle → loading → loaded)
+ *     - After a delta packet adds/removes items, can be invalidated and re-queried
+ *
+ *   BackRef:
+ *     - Resolves a single inverse model (e.g. Issue.favorite → Favorite)
+ *     - Supports cascade delete: when the owning model is deleted,
+ *       the back-referenced model is also removed from the pool
+ *
+ * Usage from React:
+ *   const { data: team } = useRecord(Team, teamId);
+ *   const { items, isLoading, load } = team.issues;  // RefCollection
+ *   // or via hook:
+ *   const { data, isLoading } = useRelation(team?.issues);
+ */
+import { observable, runInAction, makeObservable } from "mobx";
+import { readFk } from "./ObjectPool";
+/** Walk a `CoveringPath` from `parent` through the pool, returning the
+ * leaf FK value or null if any link is missing. Depth-1 paths are a single
+ * `readFk(parent, hops[0].fk)`. Deeper paths use intermediate
+ * `pool.getById(throughModel, id)` lookups; if the intermediate isn't in
+ * the pool, the path is silently skipped (its covering query will be
+ * issued only when the chain becomes resolvable on a later access). */
+function resolveCoveringPath(parent, path) {
+    // Depth-1 fast path — no pool walk needed; just read the FK off `parent`.
+    if (path.hops.length === 1) {
+        return readFk(parent, path.hops[0].fk);
+    }
+    let current = parent;
+    // Deeper paths walk through `pool.getById`; bail silently if any link
+    // is missing (the covering query is just skipped for now).
+    for (let i = 0; i < path.hops.length - 1; i++) {
+        const id = readFk(current, path.hops[i].fk);
+        if (id == null) {
+            return null;
+        }
+        const pool = current.store;
+        if (pool == null) {
+            return null;
+        }
+        const next = pool.getById(path.hops[i].throughModel, id);
+        if (next == null) {
+            return null;
+        }
+        current = next;
+    }
+    return readFk(current, path.hops[path.hops.length - 1].fk);
+}
+// ---------------------------------------------------------------------------
+// Loading state
+// ---------------------------------------------------------------------------
+export var CollectionState;
+(function (CollectionState) {
+    /** Never accessed — hydrate() computed the index values but no load yet. */
+    CollectionState["Idle"] = "idle";
+    /** Async load from IDB/server is in progress. */
+    CollectionState["Loading"] = "loading";
+    /** Load completed. Items are available. */
+    CollectionState["Loaded"] = "loaded";
+    /** Load failed. */
+    CollectionState["Error"] = "error";
+})(CollectionState || (CollectionState = {}));
+// ---------------------------------------------------------------------------
+// LazyCollectionBase — shared foundation for all lazy collection types
+// ---------------------------------------------------------------------------
+export class LazyCollectionBase {
+    constructor(referencedModelName) {
+        this.items = [];
+        this.state = CollectionState.Idle;
+        this.error = null;
+        this.listeners = new Set();
+        this.inFlight = null;
+        this.onErrorHandler = null;
+        this.referencedModelName = referencedModelName;
+        makeObservable(this, {
+            items: observable.shallow,
+            state: observable,
+            error: observable,
+        });
+    }
+    /** Wire a side-channel error reporter. Called by the loader's catch block in
+     * subclasses, in addition to setting `state = Error` and `.error`. Used by
+     * StoreManager to route into `config.onError` for telemetry. */
+    setOnError(handler) {
+        this.onErrorHandler = handler;
+    }
+    reportError(err) {
+        this.onErrorHandler?.(err);
+    }
+    load() {
+        if (this.inFlight != null) {
+            return this.inFlight;
+        }
+        this.inFlight = this.runLoad().finally(() => {
+            this.inFlight = null;
+        });
+        return this.inFlight;
+    }
+    invalidate() {
+        if (this.state === CollectionState.Loaded) {
+            runInAction(() => {
+                this.state = CollectionState.Idle;
+            });
+            this.notifyListeners();
+        }
+    }
+    async reload() {
+        runInAction(() => {
+            this.state = CollectionState.Idle;
+        });
+        return this.load();
+    }
+    /**
+     * Splice an instance into items reactively. Idempotent — duplicates by id are
+     * skipped. Called by the ObjectPool when a child enters the pool with a
+     * matching foreign key, or moves into this parent.
+     */
+    attach(item) {
+        if (this.items.some((existing) => existing.id === item.id)) {
+            return;
+        }
+        runInAction(() => {
+            this.items = [...this.items, item];
+        });
+        this.notifyListeners();
+    }
+    /**
+     * Remove an instance from items reactively. No-op if missing. Called by the
+     * ObjectPool when a child is removed from the pool, or moves to a different
+     * parent.
+     */
+    detach(itemId) {
+        if (!this.items.some((existing) => existing.id === itemId)) {
+            return;
+        }
+        runInAction(() => {
+            this.items = this.items.filter((existing) => existing.id !== itemId);
+        });
+        this.notifyListeners();
+    }
+    /**
+     * Replace items wholesale. Used by the ObjectPool to backfill when a parent
+     * enters the pool after children were already present.
+     */
+    setItems(items) {
+        runInAction(() => {
+            this.items = items;
+        });
+        this.notifyListeners();
+    }
+    get isLoaded() {
+        return this.state === CollectionState.Loaded;
+    }
+    get isLoading() {
+        return this.state === CollectionState.Loading;
+    }
+    get length() {
+        return this.items.length;
+    }
+    /** Observe set-membership changes (items added / removed / replaced).
+     * Payload-less — re-read `items` inside the listener. Returns an
+     * unsubscribe function. The single subscription verb across the public
+     * surface (`record.watch`, `store.<entity>.watchAll`). */
+    watch(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    notifyListeners() {
+        this.listeners.forEach((fn) => fn());
+    }
+}
+// ---------------------------------------------------------------------------
+// RefCollection — one-to-many queried by foreign key index. The runtime shape
+// is identical for eager and lazy decorators; the decorator only chooses
+// whether `.load()` fires automatically during makeModelObservable().
+// ---------------------------------------------------------------------------
+export class RefCollection extends LazyCollectionBase {
+    constructor(referencedModelName, inverseKey, coveringIndexes = [], derivedCoveringPaths = []) {
+        super(referencedModelName);
+        /** The ID of the parent model (e.g. team.id). Set during hydrate(). */
+        this.parentId = "";
+        /**
+         * Cached covering values. Built in `hydrate()` from the parent's id +
+         * `coveringIndexes` axes; `runLoad` passes this to the loader, which
+         * turns each entry into a `getOrLoadCollection` call and unions the results.
+         */
+        this.partialIndexValues = [];
+        this.loader = null;
+        this.inverseKey = inverseKey;
+        this.coveringIndexes = coveringIndexes;
+        this.derivedCoveringPaths = derivedCoveringPaths;
+    }
+    /**
+     * Called by Model.hydrate() after the parent model is populated.
+     * Computes the covering partial-index values used for future loads.
+     */
+    hydrate(parent) {
+        this.parentId = parent.id;
+        const values = [
+            { key: this.inverseKey, value: parent.id },
+        ];
+        // Note: Set's constructor takes an *iterable*. A bare string would
+        // iterate as characters, so seed with a one-element array.
+        const seen = new Set([`${this.inverseKey}=${parent.id}`]);
+        const push = (key, value) => {
+            const sig = `${key}=${value}`;
+            if (seen.has(sig)) {
+                return;
+            }
+            seen.add(sig);
+            values.push({ key, value });
+        };
+        for (const axis of this.coveringIndexes) {
+            const v = readFk(parent, axis);
+            if (v != null) {
+                push(axis, v);
+            }
+        }
+        for (const path of this.derivedCoveringPaths) {
+            const v = resolveCoveringPath(parent, path);
+            if (v != null) {
+                push(path.axis, v);
+            }
+        }
+        this.partialIndexValues = values;
+    }
+    /**
+     * The set of (key, value) queries this collection's loader will run. One
+     * entry for the FK match; one per covering axis whose value is non-empty
+     * on the parent.
+     */
+    getCoveringPartialIndexValues() {
+        return this.partialIndexValues;
+    }
+    /** Wire the loader function. Called by StoreManager. */
+    setLoader(loader) {
+        this.loader = loader;
+    }
+    /**
+     * Resolve items already in the ObjectPool synchronously.
+     * Used for eager-load models where everything is in memory after bootstrap.
+     */
+    resolveFromPool(pool) {
+        if (pool == null || this.parentId === "") {
+            return [];
+        }
+        const all = pool.getAll(this.referencedModelName);
+        return all.filter((m) => m[this.inverseKey] === this.parentId);
+    }
+    async runLoad() {
+        runInAction(() => {
+            this.state = CollectionState.Loading;
+            this.error = null;
+        });
+        try {
+            // The loader hydrates records into the ObjectPool, which synchronously
+            // dispatches attach() back into this collection. By the time the loader
+            // resolves, items already reflects every record the loader produced (plus
+            // anything else in the pool with a matching foreign key).
+            if (this.loader != null) {
+                await this.loader(this.referencedModelName, this.partialIndexValues);
+            }
+            runInAction(() => {
+                this.state = CollectionState.Loaded;
+            });
+            this.notifyListeners();
+            return [...this.items];
+        }
+        catch (err) {
+            runInAction(() => {
+                this.error = err;
+                this.state = CollectionState.Error;
+            });
+            this.notifyListeners();
+            this.reportError(err);
+            return [];
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// BackRef — single inverse reference.
+//
+// When the owning model is deleted, the back-referenced model is cascade-removed.
+//
+// Example: Issue has @BackReference("Favorite", "issueId")
+// → issue.favorite is a BackRef that resolves the Favorite where
+//   issueId === issue.id
+// ---------------------------------------------------------------------------
+export class BackRef {
+    constructor(referencedModelName, inverseOf) {
+        this.value = null;
+        this.state = CollectionState.Idle;
+        this.error = null;
+        this.parentId = "";
+        this.loader = null;
+        this.onErrorHandler = null;
+        this.referencedModelName = referencedModelName;
+        this.inverseOf = inverseOf;
+        makeObservable(this, {
+            value: observable.ref,
+            state: observable,
+            error: observable,
+        });
+    }
+    hydrate(parentId) {
+        this.parentId = parentId;
+    }
+    setLoader(loader) {
+        this.loader = loader;
+    }
+    setOnError(handler) {
+        this.onErrorHandler = handler;
+    }
+    /** Resolve from pool synchronously. */
+    resolveFromPool(pool) {
+        if (pool == null || this.parentId === "") {
+            return null;
+        }
+        const all = pool.getAll(this.referencedModelName);
+        return (all.find((m) => m[this.inverseOf] === this.parentId) ?? null);
+    }
+    async load() {
+        if (this.state === CollectionState.Loading) {
+            return this.value;
+        }
+        runInAction(() => {
+            this.state = CollectionState.Loading;
+            this.error = null;
+        });
+        try {
+            const result = this.loader != null
+                ? await this.loader(this.referencedModelName, this.inverseOf, this.parentId)
+                : null;
+            runInAction(() => {
+                this.value = result;
+                this.state = CollectionState.Loaded;
+            });
+            return result;
+        }
+        catch (err) {
+            runInAction(() => {
+                this.error = err;
+                this.state = CollectionState.Error;
+            });
+            this.onErrorHandler?.(err);
+            return null;
+        }
+    }
+    invalidate() {
+        if (this.state === CollectionState.Loaded) {
+            runInAction(() => {
+                this.state = CollectionState.Idle;
+            });
+        }
+    }
+    /**
+     * Set the resolved value reactively. Used by the ObjectPool when a model
+     * matching this back-reference enters the pool. Idempotent on identity.
+     */
+    attach(item) {
+        if (this.value === item) {
+            return;
+        }
+        runInAction(() => {
+            this.value = item;
+        });
+    }
+    /**
+     * Clear the resolved value reactively. Used by the ObjectPool when the
+     * referenced model leaves the pool or its inverse key changes.
+     */
+    detach(itemId) {
+        if (this.value == null || this.value.id !== itemId) {
+            return;
+        }
+        runInAction(() => {
+            this.value = null;
+        });
+    }
+    get isLoaded() {
+        return this.state === CollectionState.Loaded;
+    }
+    get isLoading() {
+        return this.state === CollectionState.Loading;
+    }
+}

package/dist/core/LazyOwnedCollection.d.ts

@@ -0,0 +1,35 @@
+/**
+ * OwnedRefs — many-to-many where the parent owns the list of IDs.
+ *
+ * Contrast with RefCollection, where the *child* holds the foreign key (e.g.
+ * Issue has teamId). Here the parent holds the array.
+ *
+ * Resolution:
+ *   - resolveFromPool: looks up each ID via pool.getById — synchronous
+ *   - load: fetches missing IDs from IDB via the wired loader — async
+ *
+ * Usage:
+ *   @Property()
+ *   public issueIds: string[] = [];
+ *
+ *   @OwnedCollection("Issue", { idsField: "issueIds" })
+ *   public issues: OwnedRefs<Issue>;
+ */
+import type { BaseModel } from "./BaseModel";
+import { LazyCollectionBase } from "./LazyCollection";
+export declare class OwnedRefs<T extends BaseModel = BaseModel> extends LazyCollectionBase<T> {
+    /** Live getter — reads the current IDs array from the parent model each call. */
+    private idsGetter;
+    private loader;
+    constructor(referencedModelName: string, idsGetter: () => string[]);
+    /** Wire the loader. Called by StoreManager during makeModelObservable(). */
+    setLoader(loader: (modelName: string, ids: string[]) => Promise<T[]>): void;
+    /**
+     * Resolve items already in the ObjectPool synchronously.
+     * Looks up each ID directly — no index query needed.
+     */
+    resolveFromPool(pool: {
+        getById(name: string, id: string): BaseModel | undefined;
+    }): T[];
+    protected runLoad(): Promise<T[]>;
+}

package/dist/core/LazyOwnedCollection.js

@@ -0,0 +1,66 @@
+/**
+ * OwnedRefs — many-to-many where the parent owns the list of IDs.
+ *
+ * Contrast with RefCollection, where the *child* holds the foreign key (e.g.
+ * Issue has teamId). Here the parent holds the array.
+ *
+ * Resolution:
+ *   - resolveFromPool: looks up each ID via pool.getById — synchronous
+ *   - load: fetches missing IDs from IDB via the wired loader — async
+ *
+ * Usage:
+ *   @Property()
+ *   public issueIds: string[] = [];
+ *
+ *   @OwnedCollection("Issue", { idsField: "issueIds" })
+ *   public issues: OwnedRefs<Issue>;
+ */
+import { runInAction } from "mobx";
+import { LazyCollectionBase, CollectionState } from "./LazyCollection";
+export class OwnedRefs extends LazyCollectionBase {
+    constructor(referencedModelName, idsGetter) {
+        super(referencedModelName);
+        this.loader = null;
+        this.idsGetter = idsGetter;
+    }
+    /** Wire the loader. Called by StoreManager during makeModelObservable(). */
+    setLoader(loader) {
+        this.loader = loader;
+    }
+    /**
+     * Resolve items already in the ObjectPool synchronously.
+     * Looks up each ID directly — no index query needed.
+     */
+    resolveFromPool(pool) {
+        return this.idsGetter()
+            .map((id) => pool.getById(this.referencedModelName, id))
+            .filter((m) => m != null);
+    }
+    async runLoad() {
+        runInAction(() => {
+            this.state = CollectionState.Loading;
+            this.error = null;
+        });
+        try {
+            const ids = this.idsGetter();
+            const results = ids.length > 0 && this.loader != null
+                ? await this.loader(this.referencedModelName, ids)
+                : [];
+            runInAction(() => {
+                this.items = results;
+                this.state = CollectionState.Loaded;
+            });
+            this.notifyListeners();
+            return results;
+        }
+        catch (err) {
+            runInAction(() => {
+                this.error = err;
+                this.state = CollectionState.Error;
+            });
+            this.notifyListeners();
+            this.reportError(err);
+            return [];
+        }
+    }
+}