@abloatai/humans 0.37.0

package/dist/local/Model.d.ts

@@ -0,0 +1,475 @@
+/**
+ * Model is the base class for the sync engine's domain models. A model is a
+ * plain domain object: it holds data and business logic, tracks its own
+ * property changes, and validates itself, and it returns the changes to apply
+ * rather than applying them. It does not reach into stores or singletons and
+ * does not perform side effects such as saving or sending notifications;
+ * persistence and sync are driven by the store that owns the model.
+ */
+/** Store interface — methods that Model subclasses can call on the store */
+interface SyncStoreRef {
+    getByForeignKey<T extends Model>(modelName: string, foreignKey: string, id: string): T[];
+    retrieve<T extends Model>(modelClass: abstract new (...args: never[]) => T, id: string): T | undefined;
+    /** Lookup a model by ID alone. Returns the pool entry regardless of type. */
+    getById(id: string): Model | undefined;
+    /** Persist a model (upsert). */
+    save(model: Model): Promise<void>;
+    /** Delete a model. */
+    delete(model: Model): Promise<void>;
+    /** Archive a model (soft delete). */
+    archive(model: Model): Promise<void>;
+    /** Unarchive a previously archived model. */
+    unarchive(model: Model): Promise<void>;
+}
+/**
+ * Internal wire-hydration hint. Symbol-keyed and non-enumerable at the call
+ * site, so it can never enter persistence, JSON, a mutation payload, or a
+ * consumer's model fields.
+ */
+export declare const DEFER_MODEL_OBSERVABILITY: unique symbol;
+/** Model data type - allows any object with string keys.
+ *  Mirrors `ModelData` exported from BaseSyncedStore — kept local to
+ *  break the import cycle between Model and BaseSyncedStore. */
+type ModelData = Record<string, unknown>;
+/** Represents a property value change with old and new values */
+export interface PropertyChange {
+    old: unknown;
+    new: unknown;
+}
+/** Validation rule function that returns error string or null if valid */
+type ValidationRule = (value: unknown) => string | null;
+/** Interface for objects that can be disposed */
+interface Disposable {
+    dispose(): void;
+}
+/** Field change information for activity tracking */
+interface FieldChange {
+    field: string;
+    oldValue: unknown;
+    newValue: unknown;
+    fieldType: string;
+}
+/**
+ * Validation error for model validation failures
+ */
+export declare class ValidationError extends Error {
+    errors: string[];
+    constructor(errors: string[]);
+}
+/**
+ * Model changes for external processing
+ */
+export interface ModelChanges {
+    type: 'create' | 'update' | 'delete' | 'archive' | 'unarchive';
+    modelName: string;
+    modelId: string;
+    changes?: Map<string, PropertyChange>;
+    timestamp: Date;
+}
+/**
+ * The abstract base class every domain model extends. It holds the model's id
+ * and timestamps, tracks in-place property changes for change detection and
+ * undo, and serializes itself, while leaving persistence and sync to the store
+ * that owns it.
+ */
+export declare abstract class Model {
+    /** Static reference to active SyncedStore for reactive queries */
+    private static store;
+    /** Unique identifier - always permanent UUID */
+    id: string;
+    /** Client ID - always equals id, kept for compatibility */
+    clientId: string;
+    /** MobX observable properties storage */
+    _mobxProperties: ModelData;
+    /** Referenced models cache */
+    _referencedModels: Record<string, Model | null>;
+    /** Track property changes */
+    modifiedProperties: Map<string, PropertyChange>;
+    /** Track if this is a new model */
+    private _isNew;
+    /** Original data snapshot */
+    private _originalData?;
+    /** Sync status */
+    syncStatus: 'pending' | 'syncing' | 'synced';
+    /** Timestamps */
+    createdAt?: Date;
+    updatedAt?: Date;
+    archivedAt?: Date | null;
+    /** Validation rules */
+    protected validationRules: Record<string, ValidationRule[]>;
+    /** Lifecycle state */
+    private isDisposed;
+    private disposers;
+    /**
+     * Whether MobX field instrumentation has been installed. Wire hydration can
+     * deliberately defer this work until the cache hands the model to a
+     * consumer; optimistic/local models still install it in their constructor.
+     */
+    private _observabilityReady;
+    private _observabilityDeferred;
+    /**
+     * Track observed LazyReferenceCollections for GC prevention
+     * When any collection is being observed by React, the model should not be GC'd
+     * Following MobX best practice: https://mobx.js.org/lazy-observables.html
+     */
+    private _observedCollections;
+    constructor(data?: Partial<Model>);
+    /**
+     * Generate unique ID
+     */
+    static generateId(): string;
+    /**
+     * Set the active SyncedStore reference for reactive queries.
+     * Called once at engine initialization.
+     */
+    static setStore(store: SyncStoreRef): void;
+    /**
+     * Get the active SyncedStore reference for reactive queries.
+     *
+     * Returns `null` if no store has been registered yet (e.g. during
+     * bootstrap before the engine is ready). Subclasses should use this
+     * instead of reaching into the private static field via bracket
+     * notation — the generic parameter lets app-side Model subclasses
+     * narrow the return to their concrete store type.
+     *
+     * @example
+     *   // In a Section model getter
+     *   const store = Section.getStore();
+     *   if (!store) return [];
+     *   return store.getByForeignKey<Block>('Block', 'sectionId', this.id);
+     */
+    static getStore<T extends SyncStoreRef = SyncStoreRef>(): T | null;
+    /**
+     * Initialize MobX observability
+     */
+    makeObservable(): void;
+    /** Mark a schema model as intentionally cold until cache exposure. */
+    protected deferObservability(): void;
+    /**
+     * Activate a cold wire-hydrated model before it crosses a consumer-visible
+     * cache boundary. Idempotent, so ordinary eagerly observable models pay only
+     * the boolean check.
+     */
+    ensureObservable(): void;
+    /**
+     * Track property changes
+     */
+    propertyChanged(propertyName: string, oldValue: unknown, newValue: unknown): void;
+    /**
+     * Get changes as object
+     */
+    getChanges(): ModelData;
+    /**
+     * Check if model has changes
+     */
+    get hasChanges(): boolean;
+    /**
+     * Mark model as persisted (not new)
+     */
+    markAsPersisted(): void;
+    /**
+     * Check if this is a new model
+     */
+    isNew(): boolean;
+    /**
+     * Return a read-only view of the snapshot taken at {@link markAsPersisted}
+     * or at load time. The undo machinery uses it to recover a field's pre-edit
+     * value when the field was written without first being tracked in
+     * `modifiedProperties`. The returned object is the live snapshot, so callers
+     * must not mutate it.
+     *
+     * This per-instance baseline is needed because application code can edit a
+     * model in two ways that coexist: a direct property write
+     * (`section.title = 'foo'`) and a recorded mutation. A design in which every
+     * write went through a single recorded path would not need it, since the
+     * last acknowledged state would already be the authoritative baseline.
+     */
+    getOriginalSnapshot(): Readonly<ModelData> | undefined;
+    /**
+     * Clear tracked changes
+     */
+    clearChanges(): void;
+    /**
+     * Capture a before-image for `keys` — the single source of truth for the
+     * "previous value" that undo inverses are built from. Both undo paths call
+     * this so they can never drift: the stream path
+     * (`MutationQueue.extractPreviousData`) and the manual-record path
+     * (`RecordingMutation.snapshotFields`).
+     *
+     * Resolution order per key:
+     *   1. `modifiedProperties.get(key).old` — first-old-wins pre-session
+     *      baseline, set whenever the field was mutated in place before commit.
+     *   2. `getOriginalSnapshot()[key]` — the last loaded/acked row, the correct
+     *      before-image for a key written without a prior in-place mutation
+     *      (e.g. a `precomputedChanges` write).
+     *   3. `fallbackToLive` only — the current live value. The manual-record path
+     *      wants this last resort; the stream path deliberately omits unresolved
+     *      keys so `buildUndoOps` drops an un-revertible inverse rather than
+     *      inventing one. The flag is the one intentional difference between the
+     *      two callers — do not collapse it.
+     *
+     * `id` is always skipped. Values are read out per-key, so the
+     * `getOriginalSnapshot()` "callers must not mutate" contract is preserved.
+     *
+     * Invariant this relies on: a given undo scope is either stream-recorded
+     * (`recordFromStream: true`) or manual (`useMutators({ undoScope })`), never
+     * both — otherwise a write would be captured twice. No surface sets both.
+     */
+    capturePreviousValues(keys: Iterable<string>, opts?: {
+        fallbackToLive?: boolean;
+    }): ModelData;
+    /**
+     * Drop the `modifiedProperties` entries for `keys` — re-baselines a field
+     * after its `.old` has been frozen into a committed transaction, so the next
+     * write to the same field starts from this commit's result rather than the
+     * stale pre-session `.old` that {@link propertyChanged}'s first-old-wins
+     * policy preserves. Safe because the committed transaction owns its own
+     * frozen `data`/`previousData`; neither re-reads `modifiedProperties`. `id`
+     * is never consumed. With no `keys`, consumes every tracked field.
+     */
+    consumeModifiedFields(keys?: Iterable<string>): void;
+    /**
+     * Validate model
+     */
+    validate(): string[];
+    /**
+     * Override for custom validation
+     */
+    protected customValidate(): string[];
+    /**
+     * Add validation rule
+     */
+    protected addValidationRule(propName: string, rule: ValidationRule): void;
+    /**
+     * Prepare save operation
+     * Returns the changes to be saved without side effects
+     */
+    prepareSave(): ModelChanges | null;
+    /**
+     * Prepare delete operation
+     */
+    prepareDelete(): ModelChanges;
+    /**
+     * Prepare archive operation
+     */
+    prepareArchive(): ModelChanges;
+    /**
+     * Prepare unarchive operation
+     */
+    prepareUnarchive(): ModelChanges;
+    /**
+     * Safely assign each field of `data` onto this instance, skipping `id`,
+     * unknown keys, MobX computed accessors, and getter-only (read-only)
+     * properties, and coercing date fields. Shared by `updateFromData`
+     * (hydration) and `applyChanges` (local user update).
+     *
+     * Change tracking is explicit: for every field actually
+     * written, `onWrite(key, oldValue, newValue)` is invoked with the value
+     * captured immediately before assignment. `applyChanges` passes a hook
+     * that records the change in `modifiedProperties`; `updateFromData`
+     * passes none (hydration must not generate outbound mutations).
+     *
+     * This is not the ONLY tracking path. `mobxSetup`'s `observe()` bridge is
+     * live and forwards a DIRECT assignment (`layer.position = next`) to
+     * `propertyChanged` as well — product code writes model fields directly in
+     * plenty of places (keyboard nudge, formatting, AI tools), and those writes
+     * have to reach the server and the undo stream too. The two paths compose:
+     * a direct write establishes the first-old-wins baseline, and a later
+     * `applyChanges` carrying the value the model already holds is a no-op that
+     * leaves that baseline intact.
+     */
+    private assignFieldsFromData;
+    /**
+     * Update from raw data (hydration)
+     *
+     * Used for inbound server deltas and pool upserts. Change tracking is
+     * deliberately suppressed: hydration writes must not land in
+     * `modifiedProperties`, otherwise applying a server delta would queue a
+     * brand-new outbound mutation and the record would echo forever. For a
+     * local user edit, use `applyChanges` instead.
+     *
+     * Suppression takes two forms and BOTH are load-bearing: we pass no
+     * `onWrite` hook, and we clear/restore `modifiedProperties` around the
+     * assignment. The second is what catches `mobxSetup`'s `observe()` bridge,
+     * which fires on the assignment itself and would otherwise record an
+     * inbound delta as a local edit — queueing an outbound mutation that echoes
+     * forever, and putting a collaborator's change on your undo stack. Do not
+     * remove it while that bridge exists (`mobxSetup.M1`).
+     */
+    updateFromData(data: ModelData): void;
+    /**
+     * Apply a local, user-initiated update from a data object — the write
+     * path for `proxy.update({ id, data })`, which is the one and only way
+     * application code mutates synced fields.
+     *
+     * Unlike `updateFromData` (hydration, untracked), this records every
+     * written field in `modifiedProperties` via `propertyChanged`, so
+     * `getChanges()` and the transaction queue send the edited fields to the
+     * server and the undo system gets a correct pre-write baseline. Recording
+     * is explicit here, through the `onWrite` hook, and does not rely on any
+     * MobX `observe()` side channel.
+     *
+     * `_originalData` is intentionally not reset here: it stays as the
+     * last-persisted baseline until `clearChanges()` runs on sync-ack.
+     */
+    applyChanges(data: ModelData): void;
+    /**
+     * Serialize to JSON
+     * This method should not trigger MobX reactions since it's used for serialization
+     * Returns Record<string, any> to allow subclass specialization with more specific return types
+     */
+    toJSON(): Record<string, any>;
+    /**
+     * Clone this model
+     */
+    clone(): this;
+    getModelName(): string;
+    /**
+     * Read a field value by name. Runtime-safe dynamic field access —
+     * schema-generated models store all declared fields as instance properties.
+     * Use this for generic code (sort comparators, filter predicates that work
+     * across model types) that reads fields by name string.
+     */
+    getField(name: string): unknown;
+    /**
+     * Check equality
+     */
+    equals(other: Model): boolean;
+    /**
+     * String representation
+     */
+    toString(): string;
+    /**
+     * Register a LazyReferenceCollection as being observed
+     * Called by LazyReferenceCollection when onBecomeObserved fires
+     */
+    _registerObservedCollection(collection: Disposable): void;
+    /**
+     * Unregister a LazyReferenceCollection that's no longer observed
+     * Called by LazyReferenceCollection when onBecomeUnobserved fires
+     */
+    _unregisterObservedCollection(collection: Disposable): void;
+    /**
+     * Check if any collection on this model is currently being observed by React
+     * Used by InstanceCache GC to prevent disposing models in active use
+     */
+    hasObservedCollections(): boolean;
+    /**
+     * Get count of observed collections (for debugging)
+     */
+    get observedCollectionCount(): number;
+    /**
+     * Dispose model
+     */
+    dispose(): void;
+    /**
+     * Check if disposed
+     */
+    get disposed(): boolean;
+    /**
+     * Lifecycle hooks - override in subclasses
+     */
+    protected didUpdate(): void;
+    protected willDelete(): void;
+    /**
+     * Capture snapshot for change detection
+     */
+    protected captureSnapshot(): ModelData;
+    /**
+     * A fresh, plain row snapshot that READS every declared field through its
+     * MobX observable getter. This is the reactive read surface for
+     * `useReactive`/`useAblo`, and it relies on two MobX facts:
+     *
+     *  1. MobX tracks property *access*, not values — so reading each field here,
+     *     inside the caller's tracked function, SUBSCRIBES the reaction to that
+     *     field. A bare `return model` (the previous `modelAsRow`) dereferences
+     *     nothing, so an in-place delta update fires no reaction and the UI never
+     *     re-renders. (https://mobx.js.org/understanding-reactivity.html)
+     *  2. The returned object is a NEW identity each call, so the hook's equality
+     *     check detects the change — the same mutated instance would compare equal
+     *     and suppress the re-render even after tracking fired.
+     *
+     * Unlike `toJSON()`, values keep their runtime types (a `Date` stays a `Date`,
+     * a json field stays its parsed object) and wire-noise keys
+     * (`__class`/`clientId`/`syncStatus`) are omitted — this is exactly the row
+     * the schema's `T` describes. Computed relations (`referenceModel`/
+     * `referenceCollection`) and ephemeral fields are skipped, matching `toJSON`'s
+     * row projection; they're lazy/recursive and not part of the row's data.
+     *
+     * Schema-derived getters (`computed:` entries and `${field}Json` getters) ARE
+     * materialized, as non-enumerable own values. The schema's inferred row type
+     * includes them, so omitting them would make every snapshot read of a computed
+     * silently `undefined` — a type-level lie. They're evaluated here, inside the
+     * caller's tracked function, so the reaction subscribes to whatever fields the
+     * getter reads. Non-enumerable keeps write-path parity with model instances:
+     * an instance's getters sit on the prototype and never enter `{...model}`
+     * spreads or `JSON.stringify`, and materialized values must not either — a
+     * spread-into-update would otherwise send computed keys to the server.
+     */
+    toReactiveSnapshot<T = ModelData>(): T;
+    /**
+     * Names of schema-derived getters — `computed:` entries and `${field}Json`
+     * getters — that {@link toReactiveSnapshot} materializes onto snapshots.
+     * The dynamic model class built by `registerModelsFromSchema` overrides this;
+     * hand-written Model subclasses default to none.
+     */
+    getDerivedGetterNames(): readonly string[];
+    /**
+     * Get field changes for activity tracking
+     */
+    getFieldChanges(): FieldChange[];
+    private getFieldType;
+    /**
+     * Create model from JSON
+     */
+    static fromJSON(data: ModelData & {
+        __typename?: string;
+        __class?: string;
+        modelName?: string;
+    }): Model;
+    /**
+     * Get sync status
+     */
+    getSyncStatus(): 'pending' | 'syncing' | 'synced';
+    /**
+     * Mark model as synced
+     */
+    markAsSynced(): void;
+    /**
+     * Mark model as pending sync
+     */
+    markAsPending(): void;
+}
+/**
+ * Project a dynamic-class `Model` instance to the schema row shape `T`.
+ *
+ * The runtime invariant: `createDynamicModelClass(...)` attaches every
+ * field of `T` directly onto the Model prototype/instance via
+ * `Object.defineProperty` and the M1 observable bridge, so a Model
+ * instance structurally satisfies `T` at runtime. The static type
+ * system can't see this because `T` is a free generic — there's no
+ * common ancestor between `Model` (base class) and the schema row
+ * interface produced by `defineSchema`.
+ *
+ * This is a typed boundary, not a bypass: every call site is the
+ * dynamic-class duality where Model-with-extras-and-T-fields is being
+ * returned to a consumer that only sees `T`. Concentrating the cast
+ * here means there's one place to look when the boundary changes.
+ */
+export declare function modelAsRow<T>(model: Model): T;
+/**
+ * Inverse of `modelAsRow`: accept a row-shaped value (schema-derived
+ * `T` with at minimum an `id`) and surface it as a `Model`. Used by
+ * `BaseSyncedStore.save / delete / archive / unarchive` so consumers
+ * can pass either a typed schema row or a Model instance and the
+ * SDK's persistence path sees a uniform Model surface.
+ *
+ * Same runtime invariant as `modelAsRow`: dynamic-class instances
+ * carry both the row fields and the Model methods on the same object
+ * — one structural identity, two static views. The helper does no
+ * runtime conversion (no allocation, no copy) — it's a pure type cast.
+ */
+export declare function rowAsModel<T extends {
+    id: string;
+}>(entity: T): Model;
+export {};