@abloatai/humans 0.37.0

package/dist/local/LazyReferenceCollection.d.ts

@@ -0,0 +1,177 @@
+/**
+ * LazyReferenceCollection implements a lazy-loaded one-to-many relationship.
+ * It loads related rows on demand, caches them, and batches lookups so that
+ * reading a parent's children does not trigger a query per parent.
+ */
+import type { Model } from './Model.js';
+import { Database } from './Database.js';
+import { InstanceCache } from './InstanceCache.js';
+/**
+ * Options for LazyReferenceCollection behavior
+ */
+export interface LazyCollectionOptions {
+    /** Skip network hydration if local data exists */
+    canSkipNetworkHydration?: () => boolean;
+    /** Custom filter for loaded items */
+    filter?: (item: any) => boolean;
+    /** Custom sort function */
+    sort?: (a: any, b: any) => number;
+    /** Maximum items to load */
+    limit?: number;
+    /** Enable automatic refresh on parent changes */
+    autoRefresh?: boolean;
+}
+/**
+ * A lazy-loaded one-to-many relationship between a parent {@link Model} and
+ * its children. It reads from the local store first and falls back to the
+ * network, batches lookups to avoid one query per parent, and is observable so
+ * a React component re-renders when the set of children changes. Loaded items
+ * can be filtered, sorted, and limited through {@link LazyCollectionOptions}.
+ */
+export declare class LazyReferenceCollection<T extends Model> {
+    private modelName;
+    private parent;
+    private foreignKey;
+    private customQuery?;
+    private options;
+    /** Static dependencies - shared across all instances */
+    private static _database;
+    private static _objectPool;
+    /**
+     * Set global dependencies for all LazyReferenceCollection instances
+     * Called once during SyncedStore initialization
+     */
+    static setDependencies(database: Database, objectPool: InstanceCache): void;
+    /**
+     * Clear dependencies (e.g., on logout/store disposal)
+     */
+    static clearDependencies(): void;
+    /** Loaded items (null = not loaded, [] = loaded but empty) */
+    items: T[] | null;
+    /** Loading state */
+    isLoading: boolean;
+    /** Error state */
+    loadError: Error | null;
+    /**
+     * MobX observation tracking - prevents GC while React is observing this collection
+     * Following MobX best practice: https://mobx.js.org/lazy-observables.html
+     */
+    _isBeingObserved: boolean;
+    /** Promise for ongoing hydration */
+    private hydrationPromise;
+    /** Disposer for observation lifecycle hooks */
+    private observationDisposer;
+    /** Get database from static dependencies */
+    private get database();
+    /** Get objectPool from static dependencies */
+    private get objectPool();
+    constructor(modelName: string, parent: Model, foreignKey: string, customQuery?: any | undefined, options?: LazyCollectionOptions);
+    /**
+     * Set up MobX observation lifecycle hooks
+     * When React components observe this collection, we prevent GC of the parent model
+     */
+    private _setupObservationTracking;
+    /**
+     * Check if this collection is currently being observed by React/MobX
+     */
+    get isBeingObserved(): boolean;
+    /**
+     * Get the collection value (triggers hydration if needed).
+     *
+     * Filters out items whose id is no longer in the InstanceCache. The
+     * local `items` array isn't auto-synced with `pool.remove()` — a
+     * deleted entity would linger here until hydrate() re-runs on
+     * reload. Reading `pool.has(item.id)` inside this computed getter
+     * makes MobX track both `this.items` AND the pool's entries map,
+     * so any pool.remove invalidates the computed and re-renders the
+     * consumer with the deleted item gone.
+     *
+     * Without this, deleting a block would pool.remove() cleanly
+     * but the view — which reads `section.blocks.value` — would keep
+     * showing the deleted block until a full reload rebuilt the
+     * collection.
+     */
+    get value(): T[];
+    /**
+     * Check if collection has been loaded
+     */
+    get loaded(): boolean;
+    /**
+     * Check if collection is empty (only meaningful after loading)
+     */
+    get empty(): boolean;
+    /**
+     * Check if currently loading
+     */
+    get loading(): boolean;
+    /**
+     * Get load error if any
+     */
+    get error(): Error | null;
+    /**
+     * Get collection size
+     */
+    get size(): number;
+    /**
+     * Hydrate the collection from local storage and/or network
+     */
+    hydrate(): Promise<void>;
+    /**
+     * Internal hydration implementation
+     */
+    private _performHydration;
+    /**
+     * Load items from IndexedDB
+     */
+    private _loadFromLocal;
+    /**
+     * Refresh the collection (reload from network)
+     */
+    refresh(): Promise<void>;
+    /**
+     * Add an item to the collection
+     */
+    add(item: T): void;
+    /**
+     * Remove an item from the collection
+     */
+    remove(itemOrId: T | string): boolean;
+    /**
+     * Find an item in the collection
+     */
+    find(predicate: (item: T) => boolean): T | undefined;
+    /**
+     * Filter items in the collection
+     */
+    filter(predicate: (item: T) => boolean): T[];
+    /**
+     * Check if collection contains an item
+     */
+    contains(itemOrId: T | string): boolean;
+    /**
+     * Convert to array (triggers hydration)
+     */
+    toArray(): T[];
+    /**
+     * Set items directly (internal use)
+     */
+    private _setItems;
+    /**
+     * Set loading state (internal use)
+     */
+    private _setLoading;
+    /**
+     * Set error state (internal use)
+     */
+    private _setError;
+    /**
+     * Clear the collection
+     */
+    clear(): void;
+    /**
+     * Dispose of the collection (cleanup)
+     * Following MobX best practice: always clean up observation hooks
+     * See: https://github.com/mobxjs/mobx/issues/2047
+     */
+    dispose(): void;
+}

package/dist/local/LazyReferenceCollection.js

@@ -0,0 +1,461 @@
+/**
+ * LazyReferenceCollection implements a lazy-loaded one-to-many relationship.
+ * It loads related rows on demand, caches them, and batches lookups so that
+ * reading a parent's children does not trigger a query per parent.
+ */
+import { makeObservable, observable, action, computed, onBecomeObserved, onBecomeUnobserved, } from 'mobx';
+import { Database } from './Database.js';
+import { InstanceCache } from './InstanceCache.js';
+import { getActiveRegistry } from './ModelRegistry.js';
+import { AbloValidationError } from '@abloatai/transaction/errors';
+/**
+ * A lazy-loaded one-to-many relationship between a parent {@link Model} and
+ * its children. It reads from the local store first and falls back to the
+ * network, batches lookups to avoid one query per parent, and is observable so
+ * a React component re-renders when the set of children changes. Loaded items
+ * can be filtered, sorted, and limited through {@link LazyCollectionOptions}.
+ */
+export class LazyReferenceCollection {
+    modelName;
+    parent;
+    foreignKey;
+    customQuery;
+    options;
+    /** Static dependencies - shared across all instances */
+    static _database = null;
+    static _objectPool = null;
+    /**
+     * Set global dependencies for all LazyReferenceCollection instances
+     * Called once during SyncedStore initialization
+     */
+    static setDependencies(database, objectPool) {
+        LazyReferenceCollection._database = database;
+        LazyReferenceCollection._objectPool = objectPool;
+        getContext().logger.debug('LazyReferenceCollection dependencies set');
+    }
+    /**
+     * Clear dependencies (e.g., on logout/store disposal)
+     */
+    static clearDependencies() {
+        LazyReferenceCollection._database = null;
+        LazyReferenceCollection._objectPool = null;
+    }
+    /** Loaded items (null = not loaded, [] = loaded but empty) */
+    items = null;
+    /** Loading state */
+    isLoading = false;
+    /** Error state */
+    loadError = null;
+    /**
+     * MobX observation tracking - prevents GC while React is observing this collection
+     * Following MobX best practice: https://mobx.js.org/lazy-observables.html
+     */
+    _isBeingObserved = false;
+    /** Promise for ongoing hydration */
+    hydrationPromise = null;
+    /** Disposer for observation lifecycle hooks */
+    observationDisposer = null;
+    /** Get database from static dependencies */
+    get database() {
+        return LazyReferenceCollection._database;
+    }
+    /** Get objectPool from static dependencies */
+    get objectPool() {
+        return LazyReferenceCollection._objectPool;
+    }
+    constructor(modelName, parent, foreignKey, customQuery, options = {}) {
+        this.modelName = modelName;
+        this.parent = parent;
+        this.foreignKey = foreignKey;
+        this.customQuery = customQuery;
+        this.options = options;
+        makeObservable(this, {
+            items: observable,
+            isLoading: observable,
+            loadError: observable,
+            _isBeingObserved: observable,
+            hydrate: action,
+            refresh: action,
+            value: computed,
+            loaded: computed,
+            empty: computed,
+            loading: computed,
+            error: computed,
+            isBeingObserved: computed,
+        });
+        // Set up MobX observation lifecycle hooks
+        // This follows the official MobX pattern for lazy observables
+        // See: https://mobx.js.org/lazy-observables.html
+        this._setupObservationTracking();
+    }
+    /**
+     * Set up MobX observation lifecycle hooks
+     * When React components observe this collection, we prevent GC of the parent model
+     */
+    _setupObservationTracking() {
+        // Track when 'items' becomes observed (React component is rendering)
+        const disposeOnObserved = onBecomeObserved(this, 'items', () => {
+            this._isBeingObserved = true;
+            // Touch parent model to prevent GC while we're being observed
+            if (this.objectPool && this.parent?.id) {
+                this.objectPool.touch(this.parent.id);
+            }
+            // Register this collection with parent for observation tracking
+            if (this.parent) {
+                this.parent._registerObservedCollection(this);
+            }
+        });
+        // Track when 'items' stops being observed (component unmounted)
+        const disposeOnUnobserved = onBecomeUnobserved(this, 'items', () => {
+            this._isBeingObserved = false;
+            // Unregister from parent
+            if (this.parent) {
+                this.parent._unregisterObservedCollection(this);
+            }
+        });
+        // Store combined disposer for cleanup
+        this.observationDisposer = () => {
+            disposeOnObserved();
+            disposeOnUnobserved();
+        };
+    }
+    /**
+     * Check if this collection is currently being observed by React/MobX
+     */
+    get isBeingObserved() {
+        return this._isBeingObserved;
+    }
+    /**
+     * Get the collection value (triggers hydration if needed).
+     *
+     * Filters out items whose id is no longer in the InstanceCache. The
+     * local `items` array isn't auto-synced with `pool.remove()` — a
+     * deleted entity would linger here until hydrate() re-runs on
+     * reload. Reading `pool.has(item.id)` inside this computed getter
+     * makes MobX track both `this.items` AND the pool's entries map,
+     * so any pool.remove invalidates the computed and re-renders the
+     * consumer with the deleted item gone.
+     *
+     * Without this, deleting a block would pool.remove() cleanly
+     * but the view — which reads `section.blocks.value` — would keep
+     * showing the deleted block until a full reload rebuilt the
+     * collection.
+     */
+    get value() {
+        // Touch parent model to prevent GC during active collection usage
+        if (this.objectPool && this.parent?.id) {
+            this.objectPool.touch(this.parent.id);
+        }
+        if (this.items === null && !this.isLoading) {
+            // Auto-hydrate on first access
+            this.hydrate().catch((error) => {
+                getContext().observability.breadcrumb('Auto-hydration failed', 'sync.database', 'warning', {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            });
+            return []; // Return empty array while loading
+        }
+        const raw = this.items || [];
+        const pool = this.objectPool;
+        if (!pool || raw.length === 0)
+            return raw;
+        // Filter items still present in the pool. `pool.has(id)` reads the
+        // observable `entries` map — MobX tracks the dependency, so a
+        // subsequent `pool.remove(id)` re-runs this computed.
+        return raw.filter((item) => pool.has(item.id));
+    }
+    /**
+     * Check if collection has been loaded
+     */
+    get loaded() {
+        return this.items !== null;
+    }
+    /**
+     * Check if collection is empty (only meaningful after loading)
+     */
+    get empty() {
+        return this.loaded && this.items.length === 0;
+    }
+    /**
+     * Check if currently loading
+     */
+    get loading() {
+        return this.isLoading;
+    }
+    /**
+     * Get load error if any
+     */
+    get error() {
+        return this.loadError;
+    }
+    /**
+     * Get collection size
+     */
+    get size() {
+        // Touch parent model when accessing collection size
+        if (this.objectPool && this.parent?.id) {
+            this.objectPool.touch(this.parent.id);
+        }
+        return this.items?.length || 0;
+    }
+    /**
+     * Hydrate the collection from local storage and/or network
+     */
+    async hydrate() {
+        // Return existing hydration promise if already in progress
+        if (this.hydrationPromise) {
+            return this.hydrationPromise;
+        }
+        // Skip if already loaded
+        if (this.items !== null) {
+            return;
+        }
+        this.hydrationPromise = this._performHydration();
+        try {
+            await this.hydrationPromise;
+        }
+        finally {
+            this.hydrationPromise = null;
+        }
+    }
+    /**
+     * Internal hydration implementation
+     */
+    async _performHydration() {
+        this._setLoading(true);
+        this._setError(null);
+        try {
+            // Step 1: Try loading from IndexedDB
+            const localData = await this._loadFromLocal();
+            if (localData.length > 0) {
+                this._setItems(localData);
+                // Check if we can skip network hydration
+                if (this.options.canSkipNetworkHydration?.()) {
+                    this._setLoading(false);
+                    return;
+                }
+            }
+        }
+        catch (error) {
+            this._setError(error);
+            getContext().observability.breadcrumb('Failed to hydrate collection', 'sync.database', 'warning', {
+                parent: this.parent.getModelName(),
+                parentId: this.parent.id,
+                foreignKey: this.foreignKey,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+        finally {
+            this._setLoading(false);
+        }
+    }
+    /**
+     * Load items from IndexedDB
+     */
+    async _loadFromLocal() {
+        try {
+            if (!this.database) {
+                throw new AbloValidationError(`Database dependency not provided to LazyReferenceCollection for ${this.modelName}`, { code: 'lazy_ref_db_missing' });
+            }
+            if (!this.objectPool) {
+                throw new AbloValidationError(`InstanceCache dependency not provided to LazyReferenceCollection for ${this.modelName}`, { code: 'lazy_ref_pool_missing' });
+            }
+            const store = this.database.getStore(this.modelName);
+            const rawData = store ? await store.getAllFromIndex(this.foreignKey, this.parent.id) : [];
+            // Get model class from registry
+            const ModelClass = getActiveRegistry().getModelByName(this.modelName);
+            if (!ModelClass) {
+                getContext().observability.breadcrumb(`Model '${this.modelName}' not found in registry`, 'sync.database', 'error');
+                return [];
+            }
+            // Convert raw data to model instances
+            const models = [];
+            for (const data of rawData) {
+                const id = data.id;
+                // Skip malformed rows. Records from IDB are typed as
+                // `Record<string, unknown>` (the centralized
+                // `ObjectStoreContract` shape) so the `id` field is
+                // narrow-checked here rather than assumed.
+                if (typeof id !== 'string')
+                    continue;
+                // Check if already in InstanceCache
+                let model = this.objectPool.get(id);
+                if (!model) {
+                    // Create new model instance
+                    model = new ModelClass();
+                    model.updateFromData(data);
+                    this.objectPool.add(model);
+                }
+                if (model) {
+                    // The by-name registry lookup types instances as the base
+                    // `Model`; this collection's `modelName` IS `T`'s registered
+                    // name (fixed at construction), so the instance is a `T`.
+                    models.push(model);
+                }
+            }
+            // Apply filtering if specified
+            let filteredModels = models;
+            if (this.options.filter) {
+                filteredModels = models.filter(this.options.filter);
+            }
+            // Apply sorting if specified
+            if (this.options.sort) {
+                filteredModels.sort(this.options.sort);
+            }
+            // Apply limit if specified
+            if (this.options.limit) {
+                filteredModels = filteredModels.slice(0, this.options.limit);
+            }
+            getContext().logger.debug('Loaded local items for collection', {
+                count: filteredModels.length,
+                parent: this.parent.getModelName(),
+                id: this.parent.id,
+                fk: this.foreignKey,
+            });
+            return filteredModels;
+        }
+        catch (error) {
+            getContext().observability.breadcrumb('Failed to load from local', 'sync.database', 'warning', {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return [];
+        }
+    }
+    /**
+     * Refresh the collection (reload from network)
+     */
+    async refresh() {
+        this.items = null;
+        this.hydrationPromise = null;
+        await this.hydrate();
+        getContext().logger.debug('Refreshed collection', {
+            parent: this.parent.getModelName(),
+            id: this.parent.id,
+            fk: this.foreignKey,
+        });
+    }
+    /**
+     * Add an item to the collection
+     */
+    add(item) {
+        if (this.items === null) {
+            this.items = [];
+        }
+        // Check if item already exists
+        const existingIndex = this.items.findIndex((existing) => existing.id === item.id);
+        if (existingIndex >= 0) {
+            // Replace existing item
+            this.items[existingIndex] = item;
+        }
+        else {
+            // Add new item
+            this.items.push(item);
+            // Apply sorting if specified
+            if (this.options.sort) {
+                this.items.sort(this.options.sort);
+            }
+        }
+        getContext().logger.debug('Added item to collection', { model: item.getModelName(), id: item.id });
+    }
+    /**
+     * Remove an item from the collection
+     */
+    remove(itemOrId) {
+        if (this.items === null)
+            return false;
+        const id = typeof itemOrId === 'string' ? itemOrId : itemOrId.id;
+        const index = this.items.findIndex((item) => item.id === id);
+        if (index >= 0) {
+            this.items.splice(index, 1);
+            getContext().logger.debug('Removed item from collection', { id });
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Find an item in the collection
+     */
+    find(predicate) {
+        // Touch parent model when searching collection
+        if (this.objectPool && this.parent?.id) {
+            this.objectPool.touch(this.parent.id);
+        }
+        if (this.items === null)
+            return undefined;
+        return this.items.find(predicate);
+    }
+    /**
+     * Filter items in the collection
+     */
+    filter(predicate) {
+        // Touch parent model when filtering collection
+        if (this.objectPool && this.parent?.id) {
+            this.objectPool.touch(this.parent.id);
+        }
+        if (this.items === null)
+            return [];
+        return this.items.filter(predicate);
+    }
+    /**
+     * Check if collection contains an item
+     */
+    contains(itemOrId) {
+        if (this.items === null)
+            return false;
+        const id = typeof itemOrId === 'string' ? itemOrId : itemOrId.id;
+        return this.items.some((item) => item.id === id);
+    }
+    /**
+     * Convert to array (triggers hydration)
+     */
+    toArray() {
+        return this.value;
+    }
+    /**
+     * Set items directly (internal use)
+     */
+    _setItems(items) {
+        this.items = items;
+    }
+    /**
+     * Set loading state (internal use)
+     */
+    _setLoading(loading) {
+        this.isLoading = loading;
+    }
+    /**
+     * Set error state (internal use)
+     */
+    _setError(error) {
+        this.loadError = error;
+    }
+    /**
+     * Clear the collection
+     */
+    clear() {
+        this.items = [];
+        this.loadError = null;
+    }
+    /**
+     * Dispose of the collection (cleanup)
+     * Following MobX best practice: always clean up observation hooks
+     * See: https://github.com/mobxjs/mobx/issues/2047
+     */
+    dispose() {
+        // Clean up MobX observation hooks first
+        if (this.observationDisposer) {
+            this.observationDisposer();
+            this.observationDisposer = null;
+        }
+        // Unregister from parent if still registered
+        if (this._isBeingObserved && this.parent) {
+            this.parent._unregisterObservedCollection(this);
+        }
+        this._isBeingObserved = false;
+        this.items = null;
+        this.hydrationPromise = null;
+        this.loadError = null;
+        this.isLoading = false;
+    }
+}
+import { getContext } from './context.js';