@abloatai/ablo 0.3.0

package/dist/Model.d.ts

@@ -0,0 +1,339 @@
+/**
+ * Model - Clean base class for domain models
+ *
+ * Models are pure domain objects that:
+ * - Hold data and business logic
+ * - Track their own changes
+ * - Validate themselves
+ * - Return updates/changes (not perform them)
+ *
+ * Models do NOT:
+ * - Access stores or singletons
+ * - Perform side effects (saving, notifications)
+ * - Know about sync infrastructure
+ */
+/** 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;
+}
+/**
+ * Abstract Model - Base class for all domain models
+ *
+ * Pure domain object with no external dependencies
+ */
+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 Slide model getter
+     *   const store = Slide.getStore();
+     *   if (!store) return [];
+     *   return store.getByForeignKey<SlideLayer>('SlideLayer', 'slideId', 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;
+    /**
+     * Read-only view of the snapshot taken at `markAsPersisted()` /
+     * load. Used by recording-transaction undo to derive a pre-session
+     * baseline for fields that weren't yet pre-mutated (so
+     * `modifiedProperties` has no entry for them). Returns the same
+     * underlying object — callers must not mutate it.
+     *
+     * Architectural note: this method exists because we allow direct
+     * property writes (`slide.title = 'foo'`) AND mutator-recorded
+     * writes to coexist. Zero / Replicache structurally avoids this:
+     * every mutation MUST go through a registered mutator function,
+     * mutator args are serialized, and on server pull all unacked
+     * mutations are dropped and the mutator functions are replayed on
+     * the new basis (rebase). That makes per-instance baselines
+     * unnecessary because the b-tree at the new basis IS the
+     * authoritative pre-session state.
+     *
+     * If we ever migrate to "mutators are the only write path," this
+     * snapshot field, `_originalData`, and most of
+     * `RecordingTransaction.snapshotFields` become dead code. See
+     * `packages/replicache/src/db/rebase.ts` (rocicorp/mono) for the
+     * pattern.
+     */
+    getOriginalSnapshot(): Readonly<ModelData> | undefined;
+    /**
+     * Clear tracked changes
+     */
+    clearChanges(): 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;
+    /**
+     * Update from raw data (hydration)
+     */
+    updateFromData(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 ObjectPool 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;
+    /**
+     * 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 {};