@abloatai/ablo 0.3.0

package/dist/Model.js

@@ -0,0 +1,715 @@
+/**
+ * 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
+ */
+import { runInAction, isComputedProp } from 'mobx';
+import { v4 as uuid } from 'uuid';
+import { M1 } from './utils/mobx-setup.js';
+import { getActiveRegistry, hasActiveRegistry } from './ModelRegistry.js';
+import { getContext } from './context.js';
+import { AbloValidationError } from './errors.js';
+/**
+ * Validation error for model validation failures
+ */
+export class ValidationError extends Error {
+    errors;
+    constructor(errors) {
+        super(`Validation failed: ${errors.join(', ')}`);
+        this.errors = errors;
+        this.name = 'ValidationError';
+    }
+}
+/**
+ * Abstract Model - Base class for all domain models
+ *
+ * Pure domain object with no external dependencies
+ */
+export class Model {
+    /** Static reference to active SyncedStore for reactive queries */
+    static store = null;
+    /** Unique identifier - always permanent UUID */
+    id;
+    /** Client ID - always equals id, kept for compatibility */
+    clientId;
+    /** MobX observable properties storage */
+    _mobxProperties = {};
+    /** Referenced models cache */
+    _referencedModels = {};
+    /** Track property changes */
+    modifiedProperties = new Map();
+    /** Track if this is a new model */
+    _isNew = true;
+    /** Original data snapshot */
+    _originalData;
+    /** Sync status */
+    syncStatus = 'pending';
+    /** Timestamps */
+    createdAt;
+    updatedAt;
+    archivedAt;
+    /** Validation rules */
+    validationRules = {};
+    /** Lifecycle state */
+    isDisposed = false;
+    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
+     */
+    _observedCollections = new Set();
+    constructor(data = {}) {
+        // Always generate permanent UUID on client
+        this.id = data.id || Model.generateId();
+        this.clientId = this.id; // No more temp IDs!
+        // Ensure dates are Date objects, not strings
+        this.createdAt = data.createdAt
+            ? data.createdAt instanceof Date
+                ? data.createdAt
+                : new Date(data.createdAt)
+            : new Date();
+        this.updatedAt = data.updatedAt
+            ? data.updatedAt instanceof Date
+                ? data.updatedAt
+                : new Date(data.updatedAt)
+            : new Date();
+        this.syncStatus = data.syncStatus || 'pending';
+    }
+    /**
+     * Generate unique ID
+     */
+    static generateId() {
+        return uuid();
+    }
+    /**
+     * Set the active SyncedStore reference for reactive queries.
+     * Called once at engine initialization.
+     */
+    static setStore(store) {
+        Model.store = store;
+    }
+    /**
+     * 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() {
+        return Model.store;
+    }
+    /**
+     * Initialize MobX observability
+     */
+    makeObservable() {
+        const modelName = this.getModelName();
+        // Get metadata from static ModelRegistry
+        const propertyMetadata = getActiveRegistry().getProperties(modelName);
+        const referenceMetadata = getActiveRegistry().getReferences(modelName);
+        // Use M1 for observability setup
+        M1(this, propertyMetadata, referenceMetadata);
+    }
+    /**
+     * Track property changes
+     */
+    propertyChanged(propertyName, oldValue, newValue) {
+        if (oldValue === newValue)
+            return;
+        runInAction(() => {
+            // Preserve the earliest captured `old` for this field until the entry
+            // is cleared (by `clearChanges` on sync-ack or by a mutator consuming
+            // it). Consecutive in-place mutations between mutator invocations —
+            // e.g. a drag loop writing `layer.position = ...` on every frame —
+            // would otherwise overwrite `.old` with each frame's predecessor,
+            // destroying the pre-session baseline that `RecordingTransaction`
+            // relies on to record a correct undo inverse. `.new` always reflects
+            // the latest value so the transaction queue's `getChanges()` keeps
+            // sending the right payload to the server.
+            const existing = this.modifiedProperties.get(propertyName);
+            this.modifiedProperties.set(propertyName, {
+                old: existing ? existing.old : oldValue,
+                new: newValue,
+            });
+            this.updatedAt = new Date();
+        });
+    }
+    /**
+     * Get changes as object
+     */
+    getChanges() {
+        const changes = {};
+        for (const [propertyName, change] of this.modifiedProperties) {
+            changes[propertyName] = change.new;
+        }
+        return changes;
+    }
+    /**
+     * Check if model has changes
+     */
+    get hasChanges() {
+        return this.modifiedProperties.size > 0;
+    }
+    /**
+     * Mark model as persisted (not new)
+     */
+    markAsPersisted() {
+        this._isNew = false;
+        this._originalData = this.captureSnapshot();
+    }
+    /**
+     * Check if this is a new model
+     */
+    isNew() {
+        return this._isNew;
+    }
+    /**
+     * 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() {
+        return this._originalData;
+    }
+    /**
+     * Clear tracked changes
+     */
+    clearChanges() {
+        runInAction(() => {
+            this.modifiedProperties.clear();
+            this._originalData = this.captureSnapshot();
+        });
+    }
+    /**
+     * Validate model
+     */
+    validate() {
+        if (this.isDisposed) {
+            throw new AbloValidationError('Cannot validate disposed model', {
+                code: 'model_disposed',
+            });
+        }
+        const errors = [];
+        const modelName = this.getModelName();
+        const properties = getActiveRegistry().getProperties(modelName);
+        if (properties) {
+            const json = this.toJSON();
+            for (const [propName, metadata] of properties) {
+                // Check required fields
+                if (!metadata.nullable && !metadata.optional) {
+                    const value = json[propName];
+                    if (value == null || value === '') {
+                        errors.push(`${propName} is required`);
+                    }
+                }
+                // Run custom validation rules
+                const rules = this.validationRules[propName];
+                if (rules) {
+                    const value = json[propName];
+                    for (const rule of rules) {
+                        const error = rule(value);
+                        if (error)
+                            errors.push(error);
+                    }
+                }
+            }
+        }
+        // Run model-specific validation
+        const customErrors = this.customValidate();
+        errors.push(...customErrors);
+        return errors;
+    }
+    /**
+     * Override for custom validation
+     */
+    customValidate() {
+        return [];
+    }
+    /**
+     * Add validation rule
+     */
+    addValidationRule(propName, rule) {
+        if (!this.validationRules[propName]) {
+            this.validationRules[propName] = [];
+        }
+        this.validationRules[propName].push(rule);
+    }
+    /**
+     * Prepare save operation
+     * Returns the changes to be saved without side effects
+     */
+    prepareSave() {
+        if (this.isDisposed) {
+            throw new AbloValidationError('Cannot prepare save for disposed model', {
+                code: 'model_disposed',
+            });
+        }
+        // Validate first
+        const errors = this.validate();
+        if (errors.length > 0) {
+            throw new ValidationError(errors);
+        }
+        if (this._isNew) {
+            // New model - return create operation
+            return {
+                type: 'create',
+                modelName: this.getModelName(), // Use Prisma model name
+                modelId: this.id,
+                timestamp: new Date(),
+            };
+        }
+        else if (this.hasChanges) {
+            // Existing model with changes - return update operation
+            return {
+                type: 'update',
+                modelName: this.getModelName(), // Use Prisma model name
+                modelId: this.id,
+                changes: new Map(this.modifiedProperties),
+                timestamp: new Date(),
+            };
+        }
+        // No changes
+        return null;
+    }
+    /**
+     * Prepare delete operation
+     */
+    prepareDelete() {
+        if (this.isDisposed) {
+            throw new AbloValidationError('Cannot prepare delete for disposed model', {
+                code: 'model_disposed',
+            });
+        }
+        this.willDelete();
+        return {
+            type: 'delete',
+            modelName: this.getModelName(), // Use Prisma model name
+            modelId: this.id,
+            timestamp: new Date(),
+        };
+    }
+    /**
+     * Prepare archive operation
+     */
+    prepareArchive() {
+        if (this.isDisposed) {
+            throw new AbloValidationError('Cannot prepare archive for disposed model', {
+                code: 'model_disposed',
+            });
+        }
+        this.archivedAt = new Date();
+        return {
+            type: 'archive',
+            modelName: this.getModelName(), // Use Prisma model name
+            modelId: this.id,
+            timestamp: new Date(),
+        };
+    }
+    /**
+     * Prepare unarchive operation
+     */
+    prepareUnarchive() {
+        if (this.isDisposed) {
+            throw new AbloValidationError('Cannot prepare unarchive for disposed model', {
+                code: 'model_disposed',
+            });
+        }
+        this.archivedAt = null;
+        return {
+            type: 'unarchive',
+            modelName: this.getModelName(), // Use Prisma model name
+            modelId: this.id,
+            timestamp: new Date(),
+        };
+    }
+    /**
+     * Update from raw data (hydration)
+     */
+    updateFromData(data) {
+        if (this.isDisposed) {
+            throw new AbloValidationError('Cannot update disposed model', {
+                code: 'model_disposed',
+            });
+        }
+        runInAction(() => {
+            // Temporarily disable change tracking
+            const originalTracking = this.modifiedProperties;
+            this.modifiedProperties = new Map();
+            // Update properties with safety checks for read-only/computed accessors
+            for (const [key, raw] of Object.entries(data)) {
+                if (key === 'id')
+                    continue;
+                // Only attempt to set if the property exists on instance or prototype
+                if (!(this.hasOwnProperty(key) || key in this))
+                    continue;
+                // Never assign to MobX computed properties (they may expose a setter that throws)
+                try {
+                    if (isComputedProp(this, key)) {
+                        continue;
+                    }
+                }
+                catch {
+                    // If MobX internals are unavailable for some reason, fall back to descriptor checks below
+                }
+                // Resolve property descriptor from own or prototype chain
+                const ownDesc = Object.getOwnPropertyDescriptor(this, key);
+                let desc = ownDesc;
+                if (!desc) {
+                    let proto = Object.getPrototypeOf(this);
+                    while (proto && proto !== Object.prototype && !desc) {
+                        desc = Object.getOwnPropertyDescriptor(proto, key);
+                        proto = Object.getPrototypeOf(proto);
+                    }
+                }
+                // Determine writability: allow if data descriptor writable, or accessor with setter
+                const writable = desc
+                    ? ('writable' in desc && !!desc.writable) ||
+                        ('set' in desc && typeof desc.set === 'function')
+                    : true;
+                if (!writable) {
+                    // Skip read-only accessor properties (getter-only)
+                    continue;
+                }
+                // Handle date conversions
+                const value = (key === 'createdAt' || key === 'updatedAt' || key === 'archivedAt') && raw
+                    ? new Date(raw)
+                    : raw;
+                // Dynamic property assignment for hydration - use indexed access
+                this[key] = value;
+            }
+            // Restore change tracking
+            this.modifiedProperties = originalTracking;
+        });
+        // Mark as persisted if updating existing model
+        if (!this._isNew) {
+            this._originalData = this.captureSnapshot();
+        }
+        this.didUpdate();
+    }
+    /**
+     * 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
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    toJSON() {
+        const modelName = this.getModelName();
+        const properties = getActiveRegistry().getProperties(modelName);
+        const result = {
+            __class: this.getModelName(), // Use Prisma model name for consistency
+            __typename: this.getModelName(), // Also add __typename for GraphQL compatibility
+            id: this.id,
+            createdAt: this.createdAt?.toISOString(),
+            updatedAt: this.updatedAt?.toISOString(),
+            clientId: this.clientId,
+            syncStatus: this.syncStatus,
+        };
+        if (this.archivedAt !== undefined) {
+            result.archivedAt = this.archivedAt?.toISOString() || null;
+        }
+        if (properties) {
+            const self = this;
+            for (const [propName, metadata] of properties) {
+                // Skip certain types
+                if (metadata.type === 'ephemeralProperty')
+                    continue;
+                if (metadata.type === 'referenceModel')
+                    continue;
+                if (metadata.type === 'referenceCollection')
+                    continue;
+                const value = self[propName];
+                if (value !== undefined) {
+                    result[propName] = value;
+                }
+            }
+        }
+        return result;
+    }
+    /**
+     * Clone this model
+     */
+    clone() {
+        const Constructor = this.constructor;
+        const clone = new Constructor();
+        const data = this.toJSON();
+        delete data.id; // New ID for clone
+        delete data.createdAt;
+        delete data.updatedAt;
+        clone.updateFromData(data);
+        return clone;
+    }
+    getModelName() {
+        const registeredName = getActiveRegistry().getModelNameFromConstructor(this.constructor);
+        if (registeredName) {
+            return registeredName;
+        }
+        const className = this.constructor.name;
+        // Use consumer-provided fallback map from config (replaces hardcoded Prisma name map)
+        const fallbackMap = getContext().config.classNameFallbackMap;
+        return fallbackMap[className] || className.replace(/Model$/, '');
+    }
+    /**
+     * 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) {
+        return Reflect.get(this, name);
+    }
+    /**
+     * Check equality
+     */
+    equals(other) {
+        return this.id === other.id && this.constructor === other.constructor;
+    }
+    /**
+     * String representation
+     */
+    toString() {
+        return `${this.constructor.name}[${this.id}]`;
+    }
+    // ==========================================
+    // MobX Observation Tracking (for GC prevention)
+    // ==========================================
+    /**
+     * Register a LazyReferenceCollection as being observed
+     * Called by LazyReferenceCollection when onBecomeObserved fires
+     */
+    _registerObservedCollection(collection) {
+        this._observedCollections.add(collection);
+    }
+    /**
+     * Unregister a LazyReferenceCollection that's no longer observed
+     * Called by LazyReferenceCollection when onBecomeUnobserved fires
+     */
+    _unregisterObservedCollection(collection) {
+        this._observedCollections.delete(collection);
+    }
+    /**
+     * 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() {
+        return this._observedCollections.size > 0;
+    }
+    /**
+     * Get count of observed collections (for debugging)
+     */
+    get observedCollectionCount() {
+        return this._observedCollections.size;
+    }
+    /**
+     * Dispose model
+     */
+    dispose() {
+        if (this.isDisposed)
+            return;
+        // Clean up
+        for (const disposer of this.disposers) {
+            disposer();
+        }
+        this.disposers = [];
+        this._referencedModels = {};
+        this.modifiedProperties.clear();
+        this._observedCollections.clear();
+        // Dispose collections. Gracefully skip when no active registry
+        // exists — `dispose()` is a cleanup path and must not crash when a
+        // test (or a teardown during engine shutdown) calls it after the
+        // registry is gone. Production flows always have one set, so the
+        // collection-disposal branch still runs there.
+        if (hasActiveRegistry()) {
+            const modelName = this.getModelName();
+            const properties = getActiveRegistry().getProperties(modelName);
+            if (properties) {
+                const self = this;
+                for (const [propName, metadata] of properties) {
+                    if (metadata.type === 'referenceCollection') {
+                        const collection = self[propName];
+                        if (collection?.dispose) {
+                            collection.dispose();
+                        }
+                    }
+                }
+            }
+        }
+        this.isDisposed = true;
+    }
+    /**
+     * Check if disposed
+     */
+    get disposed() {
+        return this.isDisposed;
+    }
+    /**
+     * Lifecycle hooks - override in subclasses
+     */
+    didUpdate() { }
+    willDelete() { }
+    /**
+     * Capture snapshot for change detection
+     */
+    captureSnapshot() {
+        const snapshot = {};
+        const modelName = this.getModelName();
+        const properties = getActiveRegistry().getProperties(modelName);
+        if (properties) {
+            const json = this.toJSON();
+            for (const [propName] of properties) {
+                snapshot[propName] = json[propName];
+            }
+        }
+        return snapshot;
+    }
+    /**
+     * Get field changes for activity tracking
+     */
+    getFieldChanges() {
+        const changes = [];
+        for (const [field, change] of this.modifiedProperties) {
+            changes.push({
+                field,
+                oldValue: change.old,
+                newValue: change.new,
+                fieldType: this.getFieldType(change.new),
+            });
+        }
+        return changes;
+    }
+    getFieldType(value) {
+        if (value === null || value === undefined)
+            return 'string';
+        if (typeof value === 'number')
+            return 'number';
+        if (value instanceof Date)
+            return 'date';
+        if (Array.isArray(value))
+            return 'array';
+        if (typeof value === 'string' && /^[a-fA-F0-9-]{36}$/.test(value))
+            return 'reference';
+        return 'string';
+    }
+    /**
+     * Create model from JSON
+     */
+    static fromJSON(data) {
+        // Support both __class and __typename, and handle both old and new naming
+        const modelIdentifier = data.__typename || data.__class || data.modelName;
+        if (!modelIdentifier) {
+            throw new AbloValidationError('Model identifier (__typename, __class, or modelName) not found in data', { code: 'model_identifier_missing' });
+        }
+        // Try to get model class by identifier
+        let ModelClass = getActiveRegistry().getModelByName(modelIdentifier);
+        // If not found with Prisma name, try mapping to class name
+        if (!ModelClass) {
+            const classNameMap = {
+                Task: 'TaskModel',
+                Project: 'Project',
+                Comment: 'CommentModel',
+                User: 'UserModel',
+                Organization: 'OrganizationModel',
+                StatusGroup: 'StatusGroupModel',
+                Team: 'TeamModel',
+                Member: 'MemberModel',
+                Role: 'RoleModel',
+            };
+            const className = classNameMap[modelIdentifier];
+            if (className) {
+                ModelClass = getActiveRegistry().getModelByName(className);
+            }
+        }
+        if (!ModelClass) {
+            throw new AbloValidationError(`Model class not found for: ${modelIdentifier}`, { code: 'model_class_not_registered' });
+        }
+        const instance = new ModelClass(data);
+        instance.markAsPersisted();
+        return instance;
+    }
+    /**
+     * Get sync status
+     */
+    getSyncStatus() {
+        return this.syncStatus;
+    }
+    /**
+     * Mark model as synced
+     */
+    markAsSynced() {
+        this.syncStatus = 'synced';
+    }
+    /**
+     * Mark model as pending sync
+     */
+    markAsPending() {
+        this.syncStatus = 'pending';
+    }
+}
+/**
+ * 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 function modelAsRow(model) {
+    return model;
+}
+/**
+ * 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 function rowAsModel(entity) {
+    return entity;
+}