zerodrift 1.0.0

package/dist/core/ObjectPool.d.ts

@@ -0,0 +1,113 @@
+/**
+ * ObjectPool — the in-memory cache of all hydrated model instances.
+ *
+ * Structure: Map<modelName, Map<uuid, modelInstance>>
+ *
+ * This is what @Reference getters resolve against when you access
+ * `issue.assignee` — it looks up the User by ID in this pool.
+ *
+ * Subscription system:
+ *   React hooks subscribe to specific model types. When a delta packet
+ *   adds, updates, or removes an instance of that type, all subscribers
+ *   are notified and their components re-render.
+ */
+import type { BaseModel } from "./BaseModel";
+import { type ModelMeta } from "./types";
+type Listener = () => void;
+/**
+ * Read a dynamic property off a model instance. The single bridge between
+ * the typed `BaseModel` shape and the index-string access we need for
+ * runtime field reflection (covering paths, predicate filters, etc.).
+ */
+export declare function prop(model: BaseModel, key: string): unknown;
+/** Read a dynamic FK property off a model instance, or null if missing/empty. */
+export declare function readFk(instance: BaseModel, key: string): string | null;
+export declare class ObjectPool {
+    private pool;
+    private snapshotCache;
+    /**
+     * Subscribers per model type. When the pool changes for a given type,
+     * all listeners for that type are called, triggering React re-renders.
+     */
+    private listeners;
+    /**
+     * Per-`(modelName, id)` MobX atoms. Each atom is bumped when the entry
+     * is added, removed, or replaced — bridging pool identity changes into
+     * the MobX dependency graph. The `@Reference` getter calls `trackModel`
+     * to register a tracked read, so observers wake when the underlying
+     * pool entry transitions even if the holder's foreign key didn't change.
+     * Atoms are created lazily on first observation and dropped automatically
+     * when no observer remains.
+     */
+    private modelAtoms;
+    /**
+     * Register a tracked MobX dependency on the pool entry for `(modelName, id)`.
+     * Bumped from `put` (when the entry is new) and `remove`, so observers
+     * reading the entry through `@Reference` re-run on identity changes — not
+     * just on FK changes.
+     */
+    trackModel(modelName: string, id: string): void;
+    /** Bump the atom for `(modelName, id)` if any observer is currently tracking it. */
+    private notifyModelChanged;
+    /**
+     * Subscribe to changes for a model type. The optional `predicate` runs
+     * against the affected record on `put` / `remove` and the listener only
+     * fires when it returns true; `clear` always fires every listener since
+     * the affected record is gone by definition.
+     *
+     * Predicate filtering covers **set-membership changes** (a record was
+     * added or removed). It does NOT see field-level reassignments — a child
+     * moving between FK buckets via `child.teamId = "..."` goes through MobX
+     * boxes, not `notify`. Pair with `record.watch` if you need to react to
+     * field changes that cross a filter boundary.
+     *
+     * Returns an unsubscribe function.
+     */
+    subscribe(modelName: string, listener: Listener): () => void;
+    subscribe(modelName: string, predicate: (model: BaseModel) => boolean, listener: Listener): () => void;
+    private notify;
+    getById<T extends BaseModel = BaseModel>(modelName: string, id: string): T | undefined;
+    /** Store a model instance. Notifies subscribers. */
+    put(modelName: string, instance: BaseModel): void;
+    /** Remove a model. Notifies subscribers. */
+    remove(modelName: string, id: string): void;
+    getAll<T extends BaseModel = BaseModel>(modelName: string): T[];
+    get size(): number;
+    counts(): Record<string, number>;
+    /**
+     * Create an instance from raw data, hydrate it, make it observable,
+     * and add it to the pool. Used everywhere a new model arrives from
+     * the server or IDB.
+     */
+    hydrateAndPut(modelName: string, meta: ModelMeta, data: Record<string, unknown>): BaseModel;
+    clear(): void;
+    /**
+     * Memoized parent-side declarations targeting a given child model. The
+     * registry is decorator-load-time only, so the cache lives for the pool's
+     * lifetime.
+     */
+    private inverseDeclCache;
+    /** Set of FK property names that are an `inverseOf` on some parent's decl.
+     * Lets `notifyReferenceChange` skip the work for plain property writes
+     * (`title`, `done`, ...) without iterating decls. */
+    private inverseFkCache;
+    private inverseDeclarations;
+    private inverseFkNames;
+    /** Resolve the parent's runtime collection / back-ref for an inverse decl. */
+    private inverseTarget;
+    private attachInverseLinks;
+    private detachInverseLinks;
+    /**
+     * When a parent enters the pool after its children, seed each declared
+     * collection / back-ref from children already in the pool. Counterpart
+     * to `attachInverseLinks` on the parent side.
+     */
+    private populateOwnedCollectionsFromPool;
+    /**
+     * Called by BaseModel when a child's foreign-key property changes — either
+     * via the prototype setter or via `box.set` in hydrate. Detaches from the
+     * old parent and attaches to the new one in a single batched action.
+     */
+    notifyReferenceChange(child: BaseModel, childModelName: string, fkName: string, oldId: string | null, newId: string | null): void;
+}
+export {};

package/dist/core/ObjectPool.js

@@ -0,0 +1,339 @@
+/**
+ * ObjectPool — the in-memory cache of all hydrated model instances.
+ *
+ * Structure: Map<modelName, Map<uuid, modelInstance>>
+ *
+ * This is what @Reference getters resolve against when you access
+ * `issue.assignee` — it looks up the User by ID in this pool.
+ *
+ * Subscription system:
+ *   React hooks subscribe to specific model types. When a delta packet
+ *   adds, updates, or removes an instance of that type, all subscribers
+ *   are notified and their components re-render.
+ */
+import { createAtom, runInAction } from "mobx";
+import { ModelRegistry } from "./ModelRegistry";
+import { PropertyType } from "./types";
+/**
+ * Read a dynamic property off a model instance. The single bridge between
+ * the typed `BaseModel` shape and the index-string access we need for
+ * runtime field reflection (covering paths, predicate filters, etc.).
+ */
+export function prop(model, key) {
+    return model[key];
+}
+/** Read a dynamic FK property off a model instance, or null if missing/empty. */
+export function readFk(instance, key) {
+    const v = prop(instance, key);
+    return typeof v === "string" && v !== "" ? v : null;
+}
+export class ObjectPool {
+    constructor() {
+        this.pool = new Map();
+        this.snapshotCache = new Map();
+        /**
+         * Subscribers per model type. When the pool changes for a given type,
+         * all listeners for that type are called, triggering React re-renders.
+         */
+        this.listeners = new Map();
+        /**
+         * Per-`(modelName, id)` MobX atoms. Each atom is bumped when the entry
+         * is added, removed, or replaced — bridging pool identity changes into
+         * the MobX dependency graph. The `@Reference` getter calls `trackModel`
+         * to register a tracked read, so observers wake when the underlying
+         * pool entry transitions even if the holder's foreign key didn't change.
+         * Atoms are created lazily on first observation and dropped automatically
+         * when no observer remains.
+         */
+        this.modelAtoms = new Map();
+        // ── Inverse link maintenance ──────────────────────────────────────────────
+        //
+        // Children push themselves into their parents' RefCollection / BackRef as
+        // they enter and leave the pool — no manual invalidation, no re-query.
+        // Walked from the parent side so plain @Property foreign keys work the
+        // same as @Reference-typed ones. Mirrors how Linear's framework does
+        // inverse attachment from the child's setter path.
+        /**
+         * Memoized parent-side declarations targeting a given child model. The
+         * registry is decorator-load-time only, so the cache lives for the pool's
+         * lifetime.
+         */
+        this.inverseDeclCache = new Map();
+        /** Set of FK property names that are an `inverseOf` on some parent's decl.
+         * Lets `notifyReferenceChange` skip the work for plain property writes
+         * (`title`, `done`, ...) without iterating decls. */
+        this.inverseFkCache = new Map();
+    }
+    /**
+     * Register a tracked MobX dependency on the pool entry for `(modelName, id)`.
+     * Bumped from `put` (when the entry is new) and `remove`, so observers
+     * reading the entry through `@Reference` re-run on identity changes — not
+     * just on FK changes.
+     */
+    trackModel(modelName, id) {
+        const key = `${modelName}:${id}`;
+        let atom = this.modelAtoms.get(key);
+        const wasJustCreated = atom == null;
+        if (atom == null) {
+            atom = createAtom(key, undefined, () => this.modelAtoms.delete(key));
+            this.modelAtoms.set(key, atom);
+        }
+        // reportObserved returns true iff a derivation is currently tracking. If
+        // we created the atom for a non-reactive read (event handler, JSON walk,
+        // etc.) the onUnobserved callback won't fire later, so drop the entry now
+        // to keep modelAtoms bounded.
+        if (!atom.reportObserved() && wasJustCreated) {
+            this.modelAtoms.delete(key);
+        }
+    }
+    /** Bump the atom for `(modelName, id)` if any observer is currently tracking it. */
+    notifyModelChanged(modelName, id) {
+        this.modelAtoms.get(`${modelName}:${id}`)?.reportChanged();
+    }
+    subscribe(modelName, a, b) {
+        const sub = b != null
+            ? { predicate: a, listener: b }
+            : { listener: a };
+        if (!this.listeners.has(modelName)) {
+            this.listeners.set(modelName, new Set());
+        }
+        this.listeners.get(modelName).add(sub);
+        return () => {
+            this.listeners.get(modelName)?.delete(sub);
+        };
+    }
+    notify(modelName, affected) {
+        const subs = this.listeners.get(modelName);
+        if (subs == null) {
+            return;
+        }
+        for (const sub of subs) {
+            if (sub.predicate != null && affected != null && !sub.predicate(affected)) {
+                continue;
+            }
+            sub.listener();
+        }
+    }
+    // ── Core operations (notify on mutation) ──────────────────────────────────
+    getById(modelName, id) {
+        return this.pool.get(modelName)?.get(id);
+    }
+    /** Store a model instance. Notifies subscribers. */
+    put(modelName, instance) {
+        if (!this.pool.has(modelName)) {
+            this.pool.set(modelName, new Map());
+        }
+        const bucket = this.pool.get(modelName);
+        const wasNew = !bucket.has(instance.id);
+        bucket.set(instance.id, instance);
+        instance.store = this;
+        this.snapshotCache.delete(modelName);
+        // First-time entry: wire inverse links and bump the per-id atom. Re-puts
+        // for an in-place hydrate skip this — the model's own MobX boxes already
+        // report their property changes, so observers don't need a duplicate poke.
+        if (wasNew) {
+            runInAction(() => {
+                this.attachInverseLinks(modelName, instance);
+                this.populateOwnedCollectionsFromPool(modelName, instance);
+                this.notifyModelChanged(modelName, instance.id);
+            });
+        }
+        this.notify(modelName, instance);
+    }
+    /** Remove a model. Notifies subscribers. */
+    remove(modelName, id) {
+        const instance = this.pool.get(modelName)?.get(id);
+        runInAction(() => {
+            if (instance != null) {
+                this.detachInverseLinks(modelName, instance);
+            }
+            this.pool.get(modelName)?.delete(id);
+            this.snapshotCache.delete(modelName);
+            this.notifyModelChanged(modelName, id);
+        });
+        this.notify(modelName, instance);
+    }
+    getAll(modelName) {
+        let snapshot = this.snapshotCache.get(modelName);
+        if (snapshot === undefined) {
+            const bucket = this.pool.get(modelName);
+            snapshot = bucket != null ? [...bucket.values()] : [];
+            this.snapshotCache.set(modelName, snapshot);
+        }
+        return snapshot;
+    }
+    get size() {
+        let total = 0;
+        for (const bucket of this.pool.values()) {
+            total += bucket.size;
+        }
+        return total;
+    }
+    counts() {
+        const out = {};
+        for (const [name, bucket] of this.pool) {
+            out[name] = bucket.size;
+        }
+        return out;
+    }
+    /**
+     * Create an instance from raw data, hydrate it, make it observable,
+     * and add it to the pool. Used everywhere a new model arrives from
+     * the server or IDB.
+     */
+    hydrateAndPut(modelName, meta, data) {
+        const id = data.id;
+        if (id != null) {
+            const existing = this.getById(modelName, id);
+            if (existing != null) {
+                existing.hydrate(data);
+                return existing;
+            }
+        }
+        const inst = new meta.ctor();
+        inst.hydrate(data);
+        inst.makeModelObservable();
+        this.put(modelName, inst);
+        return inst;
+    }
+    clear() {
+        const names = [...this.pool.keys()];
+        // Snapshot atoms before iterating: reportChanged can disturb the map via
+        // onUnobserved as observers detach.
+        const atoms = [...this.modelAtoms.values()];
+        this.pool.clear();
+        this.snapshotCache.clear();
+        for (const atom of atoms) {
+            atom.reportChanged();
+        }
+        names.forEach((n) => this.notify(n));
+    }
+    inverseDeclarations(childModelName) {
+        let cached = this.inverseDeclCache.get(childModelName);
+        if (cached != null) {
+            return cached;
+        }
+        cached = [];
+        for (const parentMeta of ModelRegistry.allModels()) {
+            for (const [propName, propMeta] of parentMeta.properties) {
+                if (propMeta.referenceTo !== childModelName) {
+                    continue;
+                }
+                if (propMeta.inverseOf == null) {
+                    continue;
+                }
+                if (propMeta.type !== PropertyType.ReferenceCollection &&
+                    propMeta.type !== PropertyType.BackReference) {
+                    continue;
+                }
+                cached.push({
+                    parentModelName: parentMeta.name,
+                    parentPropName: propName,
+                    fkName: propMeta.inverseOf,
+                    kind: propMeta.type,
+                });
+            }
+        }
+        this.inverseDeclCache.set(childModelName, cached);
+        return cached;
+    }
+    inverseFkNames(childModelName) {
+        let cached = this.inverseFkCache.get(childModelName);
+        if (cached != null) {
+            return cached;
+        }
+        cached = new Set(this.inverseDeclarations(childModelName).map((d) => d.fkName));
+        this.inverseFkCache.set(childModelName, cached);
+        return cached;
+    }
+    /** Resolve the parent's runtime collection / back-ref for an inverse decl. */
+    inverseTarget(decl, parentId) {
+        const parent = this.getById(decl.parentModelName, parentId);
+        if (parent == null) {
+            return undefined;
+        }
+        if (decl.kind === PropertyType.ReferenceCollection) {
+            return parent.__collections[decl.parentPropName];
+        }
+        return parent.__backRefs[decl.parentPropName];
+    }
+    attachInverseLinks(modelName, instance) {
+        for (const decl of this.inverseDeclarations(modelName)) {
+            const fk = readFk(instance, decl.fkName);
+            if (fk != null) {
+                this.inverseTarget(decl, fk)?.attach(instance);
+            }
+        }
+    }
+    detachInverseLinks(modelName, instance) {
+        for (const decl of this.inverseDeclarations(modelName)) {
+            const fk = readFk(instance, decl.fkName);
+            if (fk != null) {
+                this.inverseTarget(decl, fk)?.detach(instance.id);
+            }
+        }
+    }
+    /**
+     * When a parent enters the pool after its children, seed each declared
+     * collection / back-ref from children already in the pool. Counterpart
+     * to `attachInverseLinks` on the parent side.
+     */
+    populateOwnedCollectionsFromPool(modelName, instance) {
+        const meta = ModelRegistry.getModelMeta(modelName);
+        if (meta == null) {
+            return;
+        }
+        for (const [propName, propMeta] of meta.properties) {
+            if (propMeta.type === PropertyType.ReferenceCollection) {
+                const collection = instance.__collections[propName];
+                if (collection == null) {
+                    continue;
+                }
+                const matches = collection.resolveFromPool(this);
+                if (matches.length > 0) {
+                    collection.setItems(matches);
+                }
+            }
+            else if (propMeta.type === PropertyType.BackReference) {
+                const backRef = instance.__backRefs[propName];
+                if (backRef == null) {
+                    continue;
+                }
+                const match = backRef.resolveFromPool(this);
+                if (match != null) {
+                    backRef.attach(match);
+                }
+            }
+        }
+    }
+    /**
+     * Called by BaseModel when a child's foreign-key property changes — either
+     * via the prototype setter or via `box.set` in hydrate. Detaches from the
+     * old parent and attaches to the new one in a single batched action.
+     */
+    notifyReferenceChange(child, childModelName, fkName, oldId, newId) {
+        if (oldId === newId) {
+            return;
+        }
+        // Hot-path gate: skip the runInAction frame and the loop entirely when the
+        // changed property isn't an `inverseOf` for any parent. propertyChanged
+        // calls this for every tracked write (title, done, updatedAt, ...) — most
+        // of which aren't FKs.
+        if (!this.inverseFkNames(childModelName).has(fkName)) {
+            return;
+        }
+        runInAction(() => {
+            for (const decl of this.inverseDeclarations(childModelName)) {
+                if (decl.fkName !== fkName) {
+                    continue;
+                }
+                if (oldId != null) {
+                    this.inverseTarget(decl, oldId)?.detach(child.id);
+                }
+                if (newId != null) {
+                    this.inverseTarget(decl, newId)?.attach(child);
+                }
+            }
+        });
+    }
+}

package/dist/core/Store.d.ts

@@ -0,0 +1,40 @@
+/**
+ * FullStore and PartialStore — per-model stores that sync memory ↔ IndexedDB.
+ *
+ * StoreManager creates one of these for each registered model:
+ *   - FullStore for eager/lazy/localOnly models (all instances at once)
+ *   - PartialStore for partial models (on demand)
+ *   - EphemeralStore for ephemeral models (pool-only, never persisted)
+ */
+import type { BaseModel } from "./BaseModel";
+import type { StorageAdapter } from "./Database";
+import { ObjectPool } from "./ObjectPool";
+import { type ModelMeta } from "./types";
+export declare abstract class ModelStore {
+    protected meta: ModelMeta;
+    protected database: StorageAdapter;
+    protected pool: ObjectPool;
+    constructor(meta: ModelMeta, database: StorageAdapter, pool: ObjectPool);
+    get modelName(): string;
+    protected hydrateRecord(record: Record<string, unknown>): BaseModel;
+    abstract loadFromDatabase(): Promise<void>;
+    abstract loadFromServer(records: Record<string, unknown>[]): Promise<void>;
+}
+/** FullStore — loads ALL instances of a model at once. */
+export declare class FullStore extends ModelStore {
+    loadFromDatabase(): Promise<void>;
+    loadFromServer(records: Record<string, unknown>[]): Promise<void>;
+}
+/** EphemeralStore — pool-only, no IDB reads or writes. */
+export declare class EphemeralStore extends ModelStore {
+    loadFromDatabase(): Promise<void>;
+    loadFromServer(): Promise<void>;
+}
+/** PartialStore — loads a subset of instances on demand. */
+export declare class PartialStore extends ModelStore {
+    private loadedIds;
+    loadFromDatabase(): Promise<void>;
+    loadFromServer(records: Record<string, unknown>[]): Promise<void>;
+    /** Load a single instance by ID from IDB. Returns null if not found. */
+    loadById(id: string): Promise<BaseModel | null>;
+}

package/dist/core/Store.js

@@ -0,0 +1,73 @@
+/**
+ * FullStore and PartialStore — per-model stores that sync memory ↔ IndexedDB.
+ *
+ * StoreManager creates one of these for each registered model:
+ *   - FullStore for eager/lazy/localOnly models (all instances at once)
+ *   - PartialStore for partial models (on demand)
+ *   - EphemeralStore for ephemeral models (pool-only, never persisted)
+ */
+import { LoadStrategy } from "./types";
+export class ModelStore {
+    constructor(meta, database, pool) {
+        this.meta = meta;
+        this.database = database;
+        this.pool = pool;
+    }
+    get modelName() {
+        return this.meta.name;
+    }
+    hydrateRecord(record) {
+        return this.pool.hydrateAndPut(this.modelName, this.meta, record);
+    }
+}
+/** FullStore — loads ALL instances of a model at once. */
+export class FullStore extends ModelStore {
+    async loadFromDatabase() {
+        const records = await this.database.readAllModels(this.modelName);
+        for (const record of records) {
+            this.hydrateRecord(record);
+        }
+    }
+    async loadFromServer(records) {
+        await this.database.clearModelStore(this.modelName);
+        await this.database.writeModels(this.modelName, records);
+        // Only hydrate into memory if this model loads at bootstrap time
+        if (this.meta.loadStrategy === LoadStrategy.Eager) {
+            for (const record of records) {
+                this.hydrateRecord(record);
+            }
+        }
+    }
+}
+/** EphemeralStore — pool-only, no IDB reads or writes. */
+export class EphemeralStore extends ModelStore {
+    async loadFromDatabase() { }
+    async loadFromServer() { }
+}
+/** PartialStore — loads a subset of instances on demand. */
+export class PartialStore extends ModelStore {
+    constructor() {
+        super(...arguments);
+        this.loadedIds = new Set();
+    }
+    async loadFromDatabase() {
+        /* no-op — partial models load on demand */
+    }
+    async loadFromServer(records) {
+        await this.database.clearModelStore(this.modelName);
+        await this.database.writeModels(this.modelName, records);
+        // NOT hydrated — will be loaded individually when requested
+    }
+    /** Load a single instance by ID from IDB. Returns null if not found. */
+    async loadById(id) {
+        if (this.loadedIds.has(id)) {
+            return this.pool.getById(this.modelName, id) ?? null;
+        }
+        const record = await this.database.readModel(this.modelName, id);
+        if (record == null) {
+            return null;
+        }
+        this.loadedIds.add(id);
+        return this.hydrateRecord(record);
+    }
+}