zerodrift 1.0.0

package/dist/react/index.js

@@ -0,0 +1,373 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+/**
+ * React integration for the Sync Engine.
+ *
+ * Hooks subscribe to ObjectPool change notifications via useSyncExternalStore,
+ * so a delta packet that adds, updates, or removes a model automatically
+ * re-renders any component reading it through `useRecord` / `useRecords` /
+ * `useRecordsByIndex` (or a relation via `useRelation`).
+ */
+import { createContext, useContext, useState, useEffect, useCallback, useMemo, useRef, useSyncExternalStore, useLayoutEffect, } from "react";
+import { StoreManager } from "../core/StoreManager";
+import { BootstrapPhase } from "../core/types";
+import { BackRef } from "../core/LazyCollection";
+import { readFk } from "../core/ObjectPool";
+// `<any>` keeps the hooks free of TContext — none of them touch it.
+const SyncContext = createContext(null);
+// ---------------------------------------------------------------------------
+// Provider
+// ---------------------------------------------------------------------------
+export function SyncProvider({ config, context, children, fallback, }) {
+    const [status, setStatus] = useState({
+        phase: BootstrapPhase.Idle,
+    });
+    const smRef = useRef(null);
+    const cfgRef = useRef(config);
+    cfgRef.current = config;
+    // Detect bfcache restores. When a tab is duplicated (or the user navigates
+    // back/forward) the browser may restore the page from its back/forward cache
+    // (bfcache). In that case the JS heap is frozen and thawed — React effects do
+    // NOT re-run, so the StoreManager never bootstraps and the fallback stays
+    // visible forever. Reloading on persisted pageshow breaks out of that state.
+    useEffect(() => {
+        const handlePageShow = (e) => {
+            if (e.persisted) {
+                window.location.reload();
+            }
+        };
+        window.addEventListener("pageshow", handlePageShow);
+        return () => window.removeEventListener("pageshow", handlePageShow);
+    }, []);
+    // Latest context, sampled at render time. Captured into a ref so the
+    // construction effect can seed the StoreManager without re-running when
+    // the context changes (the dedicated effect below pushes updates).
+    const contextRef = useRef(context);
+    contextRef.current = context;
+    useEffect(() => {
+        let active = true;
+        const sm = new StoreManager({
+            ...cfgRef.current,
+            hooks: {
+                ...cfgRef.current.hooks,
+                onPhaseChange: (phase, detail) => {
+                    cfgRef.current.hooks?.onPhaseChange?.(phase, detail);
+                    if (active) {
+                        setStatus({ phase, detail });
+                    }
+                },
+            },
+        });
+        if (contextRef.current !== undefined) {
+            sm.setContext(contextRef.current);
+        }
+        smRef.current = sm;
+        sm.bootstrap().catch((err) => {
+            if (active) {
+                setStatus({ phase: BootstrapPhase.Error, error: String(err) });
+            }
+        });
+        return () => {
+            active = false;
+            sm.teardown();
+            smRef.current = null;
+        };
+    }, [cfgRef.current.workspaceId]);
+    // Push context updates synchronously so an event handler dispatched in the
+    // same commit as a context change sees the fresh value when minting ids.
+    useLayoutEffect(() => {
+        if (smRef.current != null && context !== undefined) {
+            smRef.current.setContext(context);
+        }
+    }, [context]);
+    if (smRef.current == null) {
+        return fallback != null ? _jsx(_Fragment, { children: fallback }) : null;
+    }
+    if (status.phase !== BootstrapPhase.Ready &&
+        status.phase !== BootstrapPhase.Error &&
+        fallback != null) {
+        return _jsx(_Fragment, { children: fallback });
+    }
+    return (_jsx(SyncContext.Provider, { value: { sm: smRef.current, status }, children: children }));
+}
+// ---------------------------------------------------------------------------
+// Core hook
+// ---------------------------------------------------------------------------
+export function useSyncEngine() {
+    const ctx = useContext(SyncContext);
+    if (ctx == null) {
+        throw new Error("useSyncEngine() must be inside <SyncProvider>");
+    }
+    return ctx;
+}
+export function useBootstrapStatus() {
+    return useSyncEngine().status;
+}
+/** Subscribe to a model type's pool changes and read a snapshot synchronously.
+ *
+ * `getSnapshot` is intentionally NOT stabilized — useSyncExternalStore calls
+ * it during render and compares the returned value, not the function identity.
+ * Stabilizing via useStableCallback would defer ref-updates to useLayoutEffect
+ * and silently return stale values on the render where its inputs change. */
+function usePoolSnapshot(modelName, getSnapshot) {
+    const { sm } = useSyncEngine();
+    const subscribe = useCallback((onStoreChange) => sm.objectPool.subscribe(modelName, onStoreChange), [sm, modelName]);
+    return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
+// ---------------------------------------------------------------------------
+// useLoader — internal helper carrying the loading/error/reload + race-guard
+// shape shared by every pool-aware hook below. Auto-fires on mount and on
+// `triggerKey` change when `shouldAutoFire` returns true; `reload()` always
+// fires regardless of the gate.
+// ---------------------------------------------------------------------------
+function useLoader(load, enabled, triggerKey, shouldAutoFire) {
+    const [isLoading, setIsLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const gen = useRef(0);
+    const stableLoad = useStableCallback(load);
+    const stableShouldAutoFire = useStableCallback(shouldAutoFire);
+    const reload = useCallback(async () => {
+        if (!enabled) {
+            return;
+        }
+        const g = ++gen.current;
+        setIsLoading(true);
+        setError(null);
+        try {
+            await stableLoad();
+            if (g === gen.current) {
+                setIsLoading(false);
+            }
+        }
+        catch (e) {
+            if (g === gen.current) {
+                setError(e);
+                setIsLoading(false);
+            }
+        }
+    }, [enabled, triggerKey, stableLoad]);
+    useEffect(() => {
+        if (enabled && stableShouldAutoFire()) {
+            void reload();
+        }
+    }, [reload, enabled, triggerKey, stableShouldAutoFire]);
+    return { isLoading, error, reload };
+}
+/** `isLoaded` for the pool-keyed hooks: ready, not loading, no error — true
+ * from frame zero on a pool hit (the loader's auto-fire is gated). */
+const settled = (ready, isLoading, error) => ready && !isLoading && error == null;
+// Model-name-keyed implementations. The public hooks resolve a handle
+// (schema namespace or model class) to a registry name and delegate here,
+// so the pool-subscription / loader machinery lives in exactly one place.
+/** Reactive single model by id. Pool-first sync read; async backfill on miss. */
+function useRecordByName(modelName, id) {
+    const { sm, status } = useSyncEngine();
+    const pool = sm.objectPool;
+    const ready = status.phase === BootstrapPhase.Ready;
+    const item = usePoolSnapshot(modelName, () => id != null ? (pool.getById(modelName, id) ?? null) : null);
+    const { isLoading, error, reload } = useLoader(() => sm.getOrLoadById(modelName, id), ready && id != null, `${modelName}:${id ?? ""}`, 
+    // Skip the load when the pool already has the entry — eager models
+    // render with isLoading: false from frame zero.
+    () => id != null && pool.getById(modelName, id) == null);
+    return {
+        data: ready ? item : null,
+        isLoading,
+        isLoaded: settled(ready, isLoading, error),
+        error,
+        reload,
+    };
+}
+/** Reactive list of models of a type, optionally filtered to a specific id
+ * set. Without `ids`: every instance in the pool. With `ids`: just those, in
+ * the order given, with async backfill for any missing from the pool. The
+ * ids array is compared by content so inline literals don't cause re-fetches. */
+function useRecordsByName(modelName, ids) {
+    const { sm, status } = useSyncEngine();
+    const pool = sm.objectPool;
+    const ready = status.phase === BootstrapPhase.Ready;
+    const idsKey = ids?.join(",") ?? "";
+    const all = usePoolSnapshot(modelName, () => pool.getAll(modelName));
+    const items = useMemo(() => {
+        if (ids == null) {
+            return all;
+        }
+        const byId = new Map(all.map((m) => [m.id, m]));
+        return ids
+            .map((id) => byId.get(id))
+            .filter((m) => m != null);
+    }, [all, idsKey]);
+    const { isLoading, error, reload } = useLoader(() => sm.getOrLoadByIds(modelName, ids ?? []), ready && ids != null && ids.length > 0, `${modelName}:${idsKey}`, () => ids != null && ids.some((id) => pool.getById(modelName, id) == null));
+    return {
+        data: ready ? items : [],
+        isLoading,
+        isLoaded: settled(ready, isLoading, error),
+        error,
+        reload,
+    };
+}
+/** Reactive list of models matching one OR many values on a foreign-key
+ * index. A single string and a `string[]` take the same path (the single
+ * value is a one-element set), so semantics are identical. Coverage is
+ * tracked per `(name, indexKey, value)` so re-renders don't re-fetch
+ * already-covered buckets; values are compared by content so inline literals
+ * don't trigger re-fetches.
+ *
+ * For one-round-trip multi-value fetches, configure
+ * `onDemandIndexBatchFetcher` + `serverSupportsCompoundIndexKeys: true` —
+ * see `agent-docs/04-lazy-loading.md`. */
+function useRecordsByIndexName(modelName, indexKey, value) {
+    const { sm, status } = useSyncEngine();
+    const ready = status.phase === BootstrapPhase.Ready;
+    const values = value == null
+        ? []
+        : (Array.isArray(value) ? value : [value]).filter((v) => v != null && v !== "");
+    const valuesKey = values.join(",");
+    const hasValues = values.length > 0;
+    const all = usePoolSnapshot(modelName, () => sm.objectPool.getAll(modelName));
+    const items = useMemo(() => {
+        if (!hasValues) {
+            return [];
+        }
+        const set = new Set(values);
+        return all.filter((m) => {
+            const v = readFk(m, indexKey);
+            return v != null && set.has(v);
+        });
+        // valuesKey: content equality; array identity is unstable for inline literals.
+    }, [all, indexKey, valuesKey, hasValues]);
+    const { isLoading, error, reload } = useLoader(async () => {
+        await Promise.all(values.map((v) => sm.getOrLoadCollection(modelName, indexKey, v)));
+    }, ready && hasValues, `${modelName}:${indexKey}:${valuesKey}`, () => hasValues &&
+        values.some((v) => !sm.isCollectionLoaded(modelName, indexKey, v)));
+    return {
+        data: ready ? items : [],
+        isLoading,
+        isLoaded: settled(ready, isLoading, error),
+        error,
+        reload,
+    };
+}
+// ---------------------------------------------------------------------------
+// Batch and undo/redo
+// ---------------------------------------------------------------------------
+/** Returns `store.batch` — the sync overload yields the `batchId` string,
+ * the async overload a `Promise<string>`. */
+export function useBatch() {
+    const { sm } = useSyncEngine();
+    return useCallback(((fn) => sm.batch(fn)), [sm]);
+}
+export function useUndoRedo() {
+    const { sm } = useSyncEngine();
+    const snapshotRef = useRef({ undoDepth: 0, redoDepth: 0 });
+    const subscribe = useCallback((onStoreChange) => sm.transactionQueue.subscribe(onStoreChange), [sm]);
+    const getSnapshot = useCallback(() => {
+        const undoDepth = sm.transactionQueue.undoDepth;
+        const redoDepth = sm.transactionQueue.redoDepth;
+        if (snapshotRef.current.undoDepth !== undoDepth ||
+            snapshotRef.current.redoDepth !== redoDepth) {
+            snapshotRef.current = { undoDepth, redoDepth };
+        }
+        return snapshotRef.current;
+    }, [sm]);
+    const { undoDepth, redoDepth } = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+    return {
+        undo: useCallback(() => sm.undo(), [sm]),
+        redo: useCallback(() => sm.redo(), [sm]),
+        canUndo: undoDepth > 0,
+        canRedo: redoDepth > 0,
+    };
+}
+export function useRelation(relation) {
+    const [tick, forceRender] = useState(0);
+    const isBackRef = relation instanceof BackRef;
+    // Collections expose watch() for invalidation; BackRef does not.
+    useEffect(() => {
+        if (relation == null || isBackRef) {
+            return;
+        }
+        return relation.watch(() => forceRender((n) => n + 1));
+    }, [relation, isBackRef]);
+    useEffect(() => {
+        if (relation != null && !relation.isLoaded && !relation.isLoading) {
+            relation.load().then(() => forceRender((n) => n + 1));
+        }
+    }, [relation, tick]);
+    if (relation == null) {
+        // Can't tell collection from back-ref at null; `[]` is the map-safe
+        // default. A null back-ref reads `[]` rather than `null` — harmless
+        // (consumers use `data?.x`), and the relation object is non-null
+        // whenever its holding record exists.
+        return {
+            data: [],
+            isLoading: false,
+            isLoaded: false,
+            error: null,
+            reload: async () => { },
+        };
+    }
+    return {
+        data: isBackRef
+            ? (relation.value ?? null)
+            : (relation.items ?? []),
+        isLoading: relation.isLoading ?? false,
+        isLoaded: relation.isLoaded ?? false,
+        error: relation.error ?? null,
+        reload: async () => {
+            await (isBackRef
+                ? relation.load()
+                : relation.reload());
+        },
+    };
+}
+function useStableCallback(callback) {
+    const computedRef = useRef(callback);
+    const stableRef = useRef((...args) => {
+        return computedRef.current(...args);
+    });
+    useLayoutEffect(function updateStableCallbackRef() {
+        computedRef.current = callback;
+    }, [callback]);
+    return stableRef.current;
+}
+// ---------------------------------------------------------------------------
+// Public read hooks — keyed by a "handle"
+//
+// A handle is either a schema namespace (`store.issue`) or a decorator
+// model class (`Issue`). Both resolve to a registry name; the record type
+// is inferred from whichever form was passed, so the same four hooks serve
+// both authoring paths with one vocabulary:
+//
+//   useRecord(handle, id)               → AsyncResource<T | null>
+//   useRecords(handle, ids?)            → AsyncResource<T[]>
+//   useRecordsByIndex(handle, key, v|v[]) → AsyncResource<T[]>
+//   useRelation(record.relation)        → AsyncResource<T[] | T | null>
+//
+// For namespace handles the index key is constrained to the schema's
+// `.indexed()` fields; for class handles it's `string`.
+// ---------------------------------------------------------------------------
+import { entityNamespaceRegistryName, } from "../schema/createStore";
+function handleRegistryName(handle) {
+    if (typeof handle === "function") {
+        // Set by @ClientModel (explicit { name } or ctor.name fallback).
+        return (handle._modelName ??
+            handle.name);
+    }
+    return entityNamespaceRegistryName(handle);
+}
+// `as unknown as` bridges `BaseModel` (what the internal name-keyed hooks
+// return) and `RecordOf<H>` (the typed view of the same pooled instance).
+// Same object at runtime; neither type is assignable to the other (BaseModel
+// has `__mobx`/`store`; RecordOf has schema fields + extensions). One cast
+// per wrapper, contained.
+/** Reactive single record by id. Pool-first sync read; async backfill on miss. */
+export function useRecord(handle, id) {
+    return useRecordByName(handleRegistryName(handle), id);
+}
+/** Reactive list of records, optionally filtered to (and ordered by) `ids`. */
+export function useRecords(handle, ids) {
+    return useRecordsByName(handleRegistryName(handle), ids);
+}
+/** Reactive list of records matching one value, or any of several, on a
+ * foreign-key index. */
+export function useRecordsByIndex(handle, indexKey, value) {
+    return useRecordsByIndexName(handleRegistryName(handle), indexKey, value);
+}

package/dist/schema/builders.d.ts

@@ -0,0 +1,29 @@
+import type { AnyFieldBuilder, AnyLinkDef, EntityDef, FieldBuilder, FieldMeta, LinkDef, SchemaDef } from "./types";
+export declare function rebuildFieldBuilder<T, M extends FieldMeta>(meta: M): FieldBuilder<T, M>;
+export declare const fields: {
+    id: () => FieldBuilder<string, FieldMeta & {
+        kind: "id";
+    }>;
+    string: () => FieldBuilder<string, FieldMeta & {
+        kind: "string";
+    }>;
+    number: () => FieldBuilder<number, FieldMeta & {
+        kind: "number";
+    }>;
+    boolean: () => FieldBuilder<boolean, FieldMeta & {
+        kind: "boolean";
+    }>;
+    date: () => FieldBuilder<Date, FieldMeta & {
+        kind: "date";
+    }>;
+    json: <T = unknown>() => FieldBuilder<T, FieldMeta & {
+        kind: "json";
+    }>;
+    refId: <Target extends string>(target: Target) => FieldBuilder<string, FieldMeta & {
+        kind: "refId";
+        refTarget: Target;
+    }>;
+};
+export declare function entity<const F extends Record<string, AnyFieldBuilder>>(def: EntityDef<F>): EntityDef<F>;
+export declare function link<const FromEntity extends string, const FromField extends string, const As extends string, const ToEntity extends string, const Many extends string>(def: LinkDef<FromEntity, FromField, As, ToEntity, Many>): LinkDef<FromEntity, FromField, As, ToEntity, Many>;
+export declare function defineSchema<const E extends Record<string, EntityDef>, const L extends Record<string, AnyLinkDef>>(schema: SchemaDef<E, L>): SchemaDef<E, L>;

package/dist/schema/builders.js

@@ -0,0 +1,81 @@
+import { dateDeserializer, dateSerializer } from "../core/serializers";
+function makeBuilder(meta) {
+    return {
+        meta,
+        nullable() {
+            return makeBuilder({ ...meta, nullable: true });
+        },
+        indexed() {
+            return makeBuilder({
+                ...meta,
+                indexed: true,
+            });
+        },
+        default(value) {
+            return makeBuilder({
+                ...meta,
+                default: value,
+            });
+        },
+        ephemeral() {
+            return makeBuilder({ ...meta, ephemeral: true });
+        },
+        serialize(fn) {
+            return makeBuilder({
+                ...meta,
+                serializer: fn,
+            });
+        },
+        deserialize(fn) {
+            return makeBuilder({ ...meta, deserializer: fn });
+        },
+    };
+}
+export function rebuildFieldBuilder(meta) {
+    return makeBuilder(meta);
+}
+const baseFlags = {
+    nullable: false,
+    optional: false,
+    indexed: false,
+    ephemeral: false,
+};
+function field(kind, extras) {
+    return makeBuilder({
+        kind,
+        ...baseFlags,
+        ...extras,
+    });
+}
+const id = () => field("id");
+const stringField = () => field("string");
+const numberField = () => field("number");
+const booleanField = () => field("boolean");
+const date = () => field("date", {
+    serializer: dateSerializer,
+    deserializer: dateDeserializer,
+});
+const json = () => field("json");
+const refId = (target) => makeBuilder({
+    kind: "refId",
+    refTarget: target,
+    ...baseFlags,
+});
+export const fields = {
+    id,
+    string: stringField,
+    number: numberField,
+    boolean: booleanField,
+    date,
+    json,
+    refId,
+};
+export function entity(def) {
+    return def;
+}
+export function link(def) {
+    return def;
+}
+export function defineSchema(schema) {
+    return schema;
+}

package/dist/schema/compile.d.ts

@@ -0,0 +1,28 @@
+import type { SchemaDef } from "./types";
+export interface CompiledSchema {
+    /** Registry names of every entity that was compiled. */
+    modelNames: readonly string[];
+    /** Map from schema-entity key to registry name. */
+    nameByKey: ReadonlyMap<string, string>;
+    /** Snapshot of the global registry hash after compilation. */
+    schemaHash: string;
+}
+/**
+ * Compile a `SchemaDef` produced by `defineSchema(...)` into the existing
+ * `ModelRegistry`. Each schema entity becomes a synthetic `BaseModel`
+ * subclass, registered under its PascalCased key (or `entity({ name })`
+ * override). After this returns, `ModelRegistry`, `StoreManager`, and the
+ * sync runtime see schema-defined models exactly the way they see
+ * decorator-defined ones.
+ *
+ * The function is pure with respect to the input `schema` object, but
+ * registers globally as a side effect — same contract as `@ClientModel`.
+ * Validation runs before any registry mutation; on failure the registry
+ * is untouched.
+ *
+ * The four passes below have an ordering dependency: ctors must be created
+ * before their fields can carry resolved `referenceTo` registry names; fields
+ * must exist before `registerLink` can `updateProperty` the FK; and the
+ * per-entity hash must run last so it captures every link side-effect.
+ */
+export declare function compileSchema(schema: SchemaDef): CompiledSchema;