zerodrift 1.0.0

package/dist/core/types.d.ts

@@ -0,0 +1,320 @@
+import type { BaseModel } from "./BaseModel";
+/** How a model is loaded into the client. Choose by *when* you need its rows. */
+export declare enum LoadStrategy {
+    /** Loaded during bootstrap, fully resident, kept current by SSE. The
+     * default — pick this unless a model is large or rarely needed. */
+    Eager = "eager",
+    /** Not in bootstrap. The whole table is fetched the first time any of it
+     * is requested, then kept current by SSE. For rarely-opened tables. */
+    Lazy = "lazy",
+    /** Not in bootstrap. Only the subset reached via an index/relation is
+     * fetched on demand and tracked by partial-index coverage. For large
+     * tables you only ever view a slice of (e.g. comments per issue). */
+    Partial = "partial",
+    /** Persisted to IDB but never synced — local-only state (drafts, settings)
+     * that must survive reload but never leaves the device. */
+    LocalOnly = "localOnly",
+    /** Pool-only — never persisted to IDB. Fed purely by SSE / ModelStream.
+     * For transient data like live metrics or computed results. */
+    Ephemeral = "ephemeral"
+}
+/** The kind of data a property holds. Determines how it's stored and observed. */
+export declare enum PropertyType {
+    /** A regular persisted property owned by the model (e.g. Issue.title). */
+    Property = "property",
+    /** Like Property but NOT saved to IndexedDB (e.g. User.lastInteraction). */
+    EphemeralProperty = "ephemeralProperty",
+    /** A foreign key ID pointing to another model (e.g. Issue.teamId). Persisted and indexed. */
+    Reference = "reference",
+    /** A virtual getter/setter that resolves a Reference ID to the actual model instance. Not persisted. */
+    ReferenceModel = "referenceModel",
+    /** A one-to-many relationship from the parent side (e.g. Team.templates). */
+    ReferenceCollection = "referenceCollection",
+    /** Inverse of a Reference. Deleted when the referenced model is deleted. */
+    BackReference = "backReference",
+    /** A many-to-many relationship stored as an array of IDs (e.g. Project.memberIds). */
+    ReferenceArray = "referenceArray",
+    /** A collection where the parent owns an array of IDs (e.g. Team.issueIds → issues). */
+    OwnedCollection = "ownedCollection"
+}
+/** Progress phases during the bootstrap pipeline. Used for loading indicators. */
+export declare enum BootstrapPhase {
+    Idle = "idle",
+    CreatingStores = "creatingStores",
+    ConnectingDatabase = "connectingDatabase",
+    DeterminingBootstrapType = "determiningBootstrapType",
+    Fetching = "fetching",
+    WritingToDatabase = "writingToDatabase",
+    Hydrating = "hydrating",
+    ConnectingSync = "connectingSync",
+    Ready = "ready",
+    Error = "error"
+}
+/** Transaction lifecycle states. */
+export declare enum TransactionState {
+    /** Created but not yet sent to the server. */
+    Pending = "pending",
+    /** Sent to the server, waiting for response. */
+    Executing = "executing",
+    /** Server acknowledged, but the matching delta packet hasn't arrived yet. */
+    CompletedButUnsynced = "completedButUnsynced",
+    /** Delta packet received. Fully done. */
+    Completed = "completed",
+    /** Server rejected the transaction. */
+    Failed = "failed"
+}
+/**
+ * Default `transientIndexDepth` — how deep `RefCollection`s walk the parent's
+ * outgoing FK chain to auto-derive covering axes when no explicit value is
+ * passed via `StoreManagerConfig.transientIndexDepth`. See that field for
+ * the trade-offs. Lives in types.ts so both the StoreManager getter and the
+ * BaseModel fallback can reference the same constant without a cycle.
+ */
+export declare const DEFAULT_TRANSIENT_INDEX_DEPTH = 3;
+/**
+ * One auto-derived covering axis for a `RefCollection`. Each path encodes
+ * how to reach a value on the parent (or a deeper ancestor) that matches an
+ * indexed FK on the child. Resolved at `RefCollection.hydrate()`:
+ *
+ *   walk the `hops` chain through the pool; the last hop's `fk` value is
+ *   used as the covering query — `Comment[axis = resolvedValue]`.
+ *
+ * For depth 1 (`hops.length === 1`), resolution is `readFk(parent, hops[0].fk)`.
+ * For depth 2+, intermediate hops resolve through `pool.getById(throughModel, id)`.
+ */
+export interface CoveringPath {
+    /** The FK name on the child model — also `hops[hops.length - 1].fk`. */
+    axis: string;
+    /** Chain of FK lookups starting from the parent. The last hop is the
+     * leaf; preceding hops are pool look-ups that resolve to the next model. */
+    hops: {
+        fk: string;
+        throughModel: string;
+    }[];
+}
+/** Metadata about a single property, stored in the ModelRegistry. */
+export interface PropertyMeta {
+    name: string;
+    type: PropertyType;
+    lazy?: boolean;
+    nullable?: boolean;
+    indexed?: boolean;
+    serializer?: (value: unknown) => unknown;
+    deserializer?: (value: unknown) => unknown;
+    referenceTo?: string;
+    inverseOf?: string;
+    idField?: string;
+    idsField?: string;
+    onDelete?: OnDelete;
+    /**
+     * Additional FK axes a `@*ReferenceCollection` covers beyond `inverseOf`.
+     * Each entry names a property on the *parent* model whose value is also a
+     * partial-index key on the child. At hydrate time the collection reads
+     * `parent[axis]` and emits an extra query, so the load fetches the union of
+     * (inverseOf == parent.id) plus each covering axis. Used for sync-group
+     * scoping and similar multi-axis lazy queries.
+     */
+    coveringIndexes?: string[];
+}
+/** Metadata about a model class, stored in the ModelRegistry. */
+export interface ModelMeta {
+    name: string;
+    loadStrategy: LoadStrategy;
+    usedForPartialIndexes: boolean;
+    properties: Map<string, PropertyMeta>;
+    actions: Set<string>;
+    computedProps: Set<string>;
+    ctor: new () => BaseModel;
+    schemaVersion: number;
+}
+/**
+ * Transforms a value at the moment it's assigned via the property setter.
+ * Receives the model instance so it can read sibling fields, plus the live
+ * `StoreManager` context for tenant/user-scoped rewrites. Output replaces
+ * the original assignment value before the MobX box is updated.
+ */
+export type FieldTransform<TContext = unknown> = (value: unknown, instance: BaseModel, ctx: TContext | undefined) => unknown;
+/** Tracks what changed on a property: old value and new value. */
+export interface PropertyChange {
+    oldValue: unknown;
+    newValue: unknown;
+}
+/**
+ * User-initiated commit intent passed to `StoreManagerConfig.routeCommit`.
+ * Discriminates on `kind` so adopters can route different ops.
+ */
+export type CommitIntent = {
+    kind: "create";
+    model: BaseModel;
+    modelName: string;
+} | {
+    kind: "update";
+    model: BaseModel;
+    modelName: string;
+    changes: Record<string, PropertyChange>;
+    /**
+     * The model's serialized state *before* this edit's setters ran (the
+     * live instance is already mutated by the time `routeCommit` fires).
+     * Lazy — serialization only happens if you call it. Memoized per
+     * intent, so repeated calls are free. Use it to seed a redirect
+     * target with the pre-edit baseline.
+     */
+    previousData: () => Record<string, unknown>;
+};
+/**
+ * Return value from `routeCommit`. Returning nothing (`void`) lets the engine
+ * commit the original intent. `"skip"` suppresses it. A `redirect` object asks
+ * the engine to apply/enqueue the intent against a different model id.
+ */
+export type CommitRouteResult = "skip" | {
+    action: "redirect";
+    modelName?: string;
+    modelId: string;
+    restoreOriginal?: boolean;
+};
+export type CommitRouteHandler = (intent: CommitIntent) => CommitRouteResult | void;
+/**
+ * Fired the instant a clean model becomes dirty — its first pending change
+ * since the last save/discard. Runs synchronously inside the property setter,
+ * before any `save()`. Use it for eager side-effects that should not wait for
+ * a commit (e.g. materializing a draft-layer scaffold so the UI can switch
+ * immediately). The actual write is still routed at `save()` via
+ * `routeCommit`. NOT fired during the engine's own redirect replay.
+ */
+export type OnModelTouchedHandler = (model: BaseModel, modelName: string) => void;
+/** Behavior when the parent of a `Reference` / `BackReference` is deleted. */
+export type OnDelete = "cascade" | "nullify" | "restrict";
+/** Object pool interface as seen from BaseModel. Avoids importing ObjectPool directly. */
+export interface IObjectPool {
+    getById<T extends BaseModel = BaseModel>(modelName: string, id: string): T | undefined;
+    put(modelName: string, instance: BaseModel): void;
+    /**
+     * Notify the pool that a child's foreign-key property changed so it can
+     * detach from the old parent's RefCollection / BackRef and attach to the
+     * new one. Called by BaseModel from `propertyChanged` and from `hydrate`
+     * when an in-pool model receives a delta-driven box update.
+     */
+    notifyReferenceChange(child: BaseModel, childModelName: string, fkName: string, oldId: string | null, newId: string | null): void;
+    /**
+     * Register a tracked MobX dependency on the pool entry for `(modelName, id)`.
+     * The pool fires the corresponding atom on insert / removal / identity swap,
+     * so observers reading the entry through `@Reference` re-evaluate even when
+     * the holder's foreign key didn't change.
+     */
+    trackModel(modelName: string, id: string): void;
+}
+/** Store manager interface as seen from BaseModel. Avoids importing StoreManager directly. */
+export interface IStoreManager {
+    readonly objectPool: IObjectPool;
+    /** How deep `RefCollection` walks the parent FK graph to auto-derive
+     * covering axes. Configurable via `StoreManagerConfig.transientIndexDepth`
+     * (default 3). Capped at the registry-walk implementation's max depth. */
+    readonly transientIndexDepth: number;
+    commitCreate(model: BaseModel): void;
+    commitUpdate(modelId: string, modelName: string, changes: Record<string, PropertyChange>): void;
+    getOrLoadCollection(modelName: string, key: string, value: string): Promise<BaseModel[]>;
+    getOrLoadByIds(modelName: string, ids: string[]): Promise<BaseModel[]>;
+    getOrLoadById(modelName: string, id: string): Promise<BaseModel | null>;
+    emitError(err: unknown, context: EngineErrorContext): void;
+    /** Mint a fresh id for a newly-constructed client-side model. Honors
+     * `StoreManagerConfig.identifierFn` if configured; otherwise falls back
+     * to `crypto.randomUUID()`. */
+    mintId(instance: BaseModel): string;
+    /** True iff `applyFieldTransforms` registered at least one transform.
+     * Setters check this before calling `applyTransform` so the no-config
+     * path stays a single boolean read on the assignment hot path. */
+    readonly hasFieldTransforms: boolean;
+    /** Run any registered field transform for `(instance, propName)` against
+     * `value` and return the result (or the value unchanged when no rule
+     * applies). The StoreManager owns the cache key shape and the context
+     * read so setters don't need to. */
+    applyTransform(instance: BaseModel, propName: string, value: unknown): unknown;
+    /** @internal Notify the StoreManager that `model` was mutated. Inside
+     * an open `atomic()` scope this records the model so the scope can
+     * call `save()` on commit or `discardUnsavedChanges()` on rollback.
+     * No-op when no atomic scope is active. Called from
+     * `BaseModel.propertyChanged`; not part of the public adopter surface. */
+    registerAtomicTouch(model: BaseModel): void;
+    /** True iff `StoreManagerConfig.onModelTouched` is configured.
+     * `BaseModel.propertyChanged` checks this before calling
+     * `fireModelTouched` so the no-config path stays a single boolean read
+     * on the clean→dirty transition. */
+    readonly hasModelTouchedHandler: boolean;
+    /** @internal Notify the StoreManager that `model` went from clean to
+     * dirty (its first pending change since the last save/discard). Fires
+     * `onModelTouched`; suppressed during the engine's own redirect replay.
+     * Called from `BaseModel.propertyChanged`. */
+    fireModelTouched(model: BaseModel, modelName: string): void;
+}
+/**
+ * Tagged union describing where in the engine an error originated. Passed to
+ * `StoreManagerConfig.onError` so adopters can route into Sentry/Datadog/console
+ * with the right metadata. Each tag carries fields specific to its failure site.
+ */
+export type EngineErrorContext = {
+    kind: "eagerReferenceLoad";
+    modelName: string;
+    id: string;
+} | {
+    kind: "eagerCollectionLoad";
+    modelName: string;
+    parentModelName: string;
+    parentId: string;
+} | {
+    kind: "lazyCollectionLoad";
+    modelName: string;
+    parentModelName: string;
+    parentId: string;
+} | {
+    kind: "lazyOwnedCollectionLoad";
+    modelName: string;
+} | {
+    kind: "lazyBackRefLoad";
+    modelName: string;
+    parentId: string;
+} | {
+    kind: "deferredBootstrap";
+    modelNames: string[];
+} | {
+    kind: "newModelsBootstrap";
+    modelNames: string[];
+} | {
+    kind: "transactionDiscarded";
+    modelName: string;
+    modelId: string;
+    action: string;
+    reason: "target-deleted";
+} | {
+    kind: "syncGroupFetch";
+    groups: string[];
+} | {
+    kind: "ssePacketParse";
+    url: string;
+    raw: string;
+} | {
+    kind: "sseConstruction";
+    url: string;
+} | {
+    kind: "transactionSend";
+    batchSize: number;
+} | {
+    kind: "onSyncGroupDelete";
+    groupId: string;
+} | {
+    kind: "undoableAction";
+    phase: "undo" | "redo";
+    changeLogId: string;
+    actionType?: string;
+} | {
+    kind: "beforeCommit";
+    opKind: "create" | "update";
+    modelName: string;
+    modelId: string;
+} | {
+    kind: "onModelTouched";
+    modelName: string;
+    modelId: string;
+};
+export type EngineErrorHandler = (err: Error, context: EngineErrorContext) => void;
+/** Coerce an `unknown` from a `catch` clause into a real `Error` instance. */
+export declare const toError: (err: unknown) => Error;

package/dist/core/types.js

@@ -0,0 +1,84 @@
+// ---------------------------------------------------------------------------
+// Enums
+// ---------------------------------------------------------------------------
+/** How a model is loaded into the client. Choose by *when* you need its rows. */
+export var LoadStrategy;
+(function (LoadStrategy) {
+    /** Loaded during bootstrap, fully resident, kept current by SSE. The
+     * default — pick this unless a model is large or rarely needed. */
+    LoadStrategy["Eager"] = "eager";
+    /** Not in bootstrap. The whole table is fetched the first time any of it
+     * is requested, then kept current by SSE. For rarely-opened tables. */
+    LoadStrategy["Lazy"] = "lazy";
+    /** Not in bootstrap. Only the subset reached via an index/relation is
+     * fetched on demand and tracked by partial-index coverage. For large
+     * tables you only ever view a slice of (e.g. comments per issue). */
+    LoadStrategy["Partial"] = "partial";
+    /** Persisted to IDB but never synced — local-only state (drafts, settings)
+     * that must survive reload but never leaves the device. */
+    LoadStrategy["LocalOnly"] = "localOnly";
+    /** Pool-only — never persisted to IDB. Fed purely by SSE / ModelStream.
+     * For transient data like live metrics or computed results. */
+    LoadStrategy["Ephemeral"] = "ephemeral";
+})(LoadStrategy || (LoadStrategy = {}));
+/** The kind of data a property holds. Determines how it's stored and observed. */
+export var PropertyType;
+(function (PropertyType) {
+    /** A regular persisted property owned by the model (e.g. Issue.title). */
+    PropertyType["Property"] = "property";
+    /** Like Property but NOT saved to IndexedDB (e.g. User.lastInteraction). */
+    PropertyType["EphemeralProperty"] = "ephemeralProperty";
+    /** A foreign key ID pointing to another model (e.g. Issue.teamId). Persisted and indexed. */
+    PropertyType["Reference"] = "reference";
+    /** A virtual getter/setter that resolves a Reference ID to the actual model instance. Not persisted. */
+    PropertyType["ReferenceModel"] = "referenceModel";
+    /** A one-to-many relationship from the parent side (e.g. Team.templates). */
+    PropertyType["ReferenceCollection"] = "referenceCollection";
+    /** Inverse of a Reference. Deleted when the referenced model is deleted. */
+    PropertyType["BackReference"] = "backReference";
+    /** A many-to-many relationship stored as an array of IDs (e.g. Project.memberIds). */
+    PropertyType["ReferenceArray"] = "referenceArray";
+    /** A collection where the parent owns an array of IDs (e.g. Team.issueIds → issues). */
+    PropertyType["OwnedCollection"] = "ownedCollection";
+})(PropertyType || (PropertyType = {}));
+/** Progress phases during the bootstrap pipeline. Used for loading indicators. */
+export var BootstrapPhase;
+(function (BootstrapPhase) {
+    BootstrapPhase["Idle"] = "idle";
+    BootstrapPhase["CreatingStores"] = "creatingStores";
+    BootstrapPhase["ConnectingDatabase"] = "connectingDatabase";
+    BootstrapPhase["DeterminingBootstrapType"] = "determiningBootstrapType";
+    BootstrapPhase["Fetching"] = "fetching";
+    BootstrapPhase["WritingToDatabase"] = "writingToDatabase";
+    BootstrapPhase["Hydrating"] = "hydrating";
+    BootstrapPhase["ConnectingSync"] = "connectingSync";
+    BootstrapPhase["Ready"] = "ready";
+    BootstrapPhase["Error"] = "error";
+})(BootstrapPhase || (BootstrapPhase = {}));
+/** Transaction lifecycle states. */
+export var TransactionState;
+(function (TransactionState) {
+    /** Created but not yet sent to the server. */
+    TransactionState["Pending"] = "pending";
+    /** Sent to the server, waiting for response. */
+    TransactionState["Executing"] = "executing";
+    /** Server acknowledged, but the matching delta packet hasn't arrived yet. */
+    TransactionState["CompletedButUnsynced"] = "completedButUnsynced";
+    /** Delta packet received. Fully done. */
+    TransactionState["Completed"] = "completed";
+    /** Server rejected the transaction. */
+    TransactionState["Failed"] = "failed";
+})(TransactionState || (TransactionState = {}));
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/**
+ * Default `transientIndexDepth` — how deep `RefCollection`s walk the parent's
+ * outgoing FK chain to auto-derive covering axes when no explicit value is
+ * passed via `StoreManagerConfig.transientIndexDepth`. See that field for
+ * the trade-offs. Lives in types.ts so both the StoreManager getter and the
+ * BaseModel fallback can reference the same constant without a cycle.
+ */
+export const DEFAULT_TRANSIENT_INDEX_DEPTH = 3;
+/** Coerce an `unknown` from a `catch` clause into a real `Error` instance. */
+export const toError = (err) => err instanceof Error ? err : new Error(String(err));

package/dist/react/index.d.ts

@@ -0,0 +1,82 @@
+/**
+ * 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 React from "react";
+import { StoreManager, type StoreManagerConfig } from "../core/StoreManager";
+import { BootstrapPhase } from "../core/types";
+import { LazyCollectionBase, BackRef } from "../core/LazyCollection";
+import type { BaseModel } from "../core/BaseModel";
+export interface SyncStatus {
+    phase: BootstrapPhase;
+    detail?: string;
+    error?: string;
+}
+export declare function SyncProvider<TContext = unknown>({ config, context, children, fallback, }: {
+    config: StoreManagerConfig<TContext>;
+    /** Live context forwarded to `StoreManager.setContext` — consumed by
+     * `identifierFn` when minting ids for client-side models. Pushed
+     * synchronously so handlers fired in the same commit see the update. */
+    context?: TContext;
+    children: React.ReactNode;
+    /** Shown while bootstrap is in progress. */
+    fallback?: React.ReactNode;
+}): import("react/jsx-runtime").JSX.Element | null;
+export declare function useSyncEngine(): {
+    sm: StoreManager<any>;
+    status: SyncStatus;
+};
+export declare function useBootstrapStatus(): SyncStatus;
+/**
+ * Uniform async-resource shape for every load-aware hook (`useRecord`,
+ * `useRecords`, `useRecordsByIndex`, `useRelation`). `data` is the payload
+ * (`T | null` for a single record, `T[]` for a list); the rest is the
+ * lifecycle bag. `isLoaded` is true once the first resolve settled without
+ * error (a pool hit counts as resolved from frame zero).
+ */
+export interface AsyncResource<T> {
+    data: T;
+    isLoading: boolean;
+    isLoaded: boolean;
+    error: Error | null;
+    reload: () => Promise<void>;
+}
+/** Returns `store.batch` — the sync overload yields the `batchId` string,
+ * the async overload a `Promise<string>`. */
+export declare function useBatch(): StoreManager["batch"];
+export declare function useUndoRedo(): {
+    undo: () => Promise<import("../core").UndoResult | null>;
+    redo: () => Promise<import("../core").UndoResult | null>;
+    canUndo: boolean;
+    canRedo: boolean;
+};
+export declare function useRelation<T extends BaseModel = BaseModel>(relation: LazyCollectionBase<T> | null | undefined): AsyncResource<T[]>;
+export declare function useRelation<T extends BaseModel = BaseModel>(relation: BackRef<T> | null | undefined): AsyncResource<T | null>;
+import { type EntityNamespace, type RecordWithExtensions } from "../schema/createStore";
+import type { ExtensionDescriptor } from "../schema/extend";
+import type { EntityKey, IndexedFieldKeys } from "../schema/infer";
+import type { SchemaDef } from "../schema/types";
+type AnyNamespace = EntityNamespace<any, any, any>;
+type ModelCtor<T extends BaseModel = BaseModel> = abstract new (...args: any[]) => T;
+type Handle = AnyNamespace | ModelCtor;
+type RecordOfNamespace<NS> = NS extends EntityNamespace<infer S, infer K, infer Exts> ? S extends SchemaDef ? K extends EntityKey<S> ? Exts extends readonly ExtensionDescriptor<S>[] ? RecordWithExtensions<S, K, Exts> : never : never : never : never;
+type IndexKeyOfNamespace<NS> = NS extends EntityNamespace<infer S, infer K, infer _Exts> ? S extends SchemaDef ? K extends EntityKey<S> ? IndexedFieldKeys<S, K> : never : never : never;
+/** Record type for a handle: the class instance type, or the schema's typed
+ * projection for a namespace. Ctor is checked first — a namespace is a plain
+ * object and never matches `ModelCtor`. */
+type RecordOf<H> = H extends ModelCtor<infer T> ? T : RecordOfNamespace<H>;
+/** Index-key constraint for a handle: schema `.indexed()` fields for a
+ * namespace, unconstrained `string` for a decorator class. */
+type IndexKeyOf<H> = H extends ModelCtor ? string : IndexKeyOfNamespace<H>;
+/** Reactive single record by id. Pool-first sync read; async backfill on miss. */
+export declare function useRecord<H extends Handle>(handle: H, id: string | null | undefined): AsyncResource<RecordOf<H> | null>;
+/** Reactive list of records, optionally filtered to (and ordered by) `ids`. */
+export declare function useRecords<H extends Handle>(handle: H, ids?: string[] | null): AsyncResource<RecordOf<H>[]>;
+/** Reactive list of records matching one value, or any of several, on a
+ * foreign-key index. */
+export declare function useRecordsByIndex<H extends Handle>(handle: H, indexKey: IndexKeyOf<H>, value: string | readonly string[] | null | undefined): AsyncResource<RecordOf<H>[]>;
+export {};