@abloatai/ablo 0.36.0 → 0.37.0

package/dist/Model.d.ts

@@ -1,454 +0,0 @@
-/**
- * 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>;
-}
-/** 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;
-    /**
-     * 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;
-    /**
-     * 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 {};