@abloatai/ablo 0.35.0 → 0.37.0

package/dist/LazyReferenceCollection.d.ts

@@ -1,177 +0,0 @@
-/**
- * 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/LazyReferenceCollection.js

@@ -1,461 +0,0 @@
-/**
- * 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 './transaction/errors.js';
-/**
- * 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';