@abloatai/ablo 0.3.0

package/dist/ObjectPool.d.ts

@@ -0,0 +1,202 @@
+/**
+ * ObjectPool - In-memory model cache with deduplication
+ *
+ * Pure memory management without database or registry dependencies.
+ * Uses static ModelRegistry for model class lookup only.
+ */
+import { Model } from './Model.js';
+import { ModelRegistry } from './ModelRegistry.js';
+import { ModelScope } from './types/index.js';
+import { ViewRegistry } from './core/ViewRegistry.js';
+import { QueryView, type QueryViewOptions } from './core/QueryView.js';
+/** Constructor type for Model subclasses - uses abstract to handle variance */
+type ModelConstructor<T extends Model> = abstract new (...args: never[]) => T;
+export { ModelScope };
+interface PoolConfig {
+    maxSize?: number;
+    maxAge?: number;
+    gcInterval?: number;
+    useWeakRefs?: boolean;
+}
+interface DeltaInfo {
+    action?: string;
+    syncId?: number;
+}
+/**
+ * ObjectPool - Pure in-memory model cache with deduplication
+ */
+export declare class ObjectPool {
+    private entries;
+    private typeIndex;
+    private accessTimes;
+    private recentAdditions;
+    private deltaHistory;
+    private foreignKeyIndexes;
+    private foreignKeyConfig;
+    private metrics;
+    private config;
+    private gcTimer?;
+    readonly registry: ModelRegistry;
+    readonly viewRegistry: ViewRegistry;
+    private subscriptions;
+    /**
+     * Subscribe to updates for a specific model type.
+     */
+    subscribe<T extends Model>(modelClass: ModelConstructor<T>, callback: (model: T) => void): () => void;
+    private notifySubscribers;
+    constructor(config?: PoolConfig, modelRegistry?: ModelRegistry);
+    /**
+     * 🔧 PRODUCTION FIX: Initialize type indexes for all registered models
+     * This prevents the "No type index found" error in production where constructor
+     * references are lost due to minification.
+     */
+    private initializeTypeIndexes;
+    private resolveModel;
+    get<T extends Model = Model>(id: string): T | undefined;
+    /**
+     * Add model with deduplication support
+     */
+    add(model: Model, scope?: ModelScope, deltaInfo?: DeltaInfo): void;
+    /**
+     * Upsert a model - INSERT if new, UPDATE if exists
+     */
+    upsert(model: Model, scope?: ModelScope): void;
+    /**
+     * Batch add models - optimized for hydration
+     * All models are added in a single MobX action to minimize reactivity overhead
+     */
+    addBatch(models: Model[], scope?: ModelScope): number;
+    /**
+     * Batch upsert models - optimized for delta processing.
+     * All upserts happen in a single MobX action to minimize reactivity overhead.
+     */
+    upsertBatch(models: Model[], scope?: ModelScope): void;
+    /**
+     * Batch remove models by ID - optimized for delta processing.
+     * All removals happen in a single MobX action to minimize reactivity overhead.
+     * Returns the number of models actually removed.
+     */
+    removeBatch(ids: string[]): number;
+    /**
+     * Read-only accessor for entity IDs by model type.
+     * Used by applyBootstrapToPool() and rehydrateFromDatabase() for ghost detection.
+     */
+    getIdsByModelType(modelType: string): ReadonlySet<string> | undefined;
+    addToArchive(model: Model): void;
+    remove(id: string): boolean;
+    removeFromArchive(id: string): boolean;
+    getByType(modelClass: ModelConstructor<Model>, scope?: ModelScope): Model[];
+    /**
+     * Get all models of a given type by string name.
+     * Used for custom entity types where multiple entity type names share
+     * the same CustomEntityModel constructor (getByType can't disambiguate).
+     * Reads from the same typeIndex as getByType — MobX tracks the dependency.
+     */
+    getByTypeName(modelName: string, scope?: ModelScope): Model[];
+    iterateByType(modelClass: ModelConstructor<Model>, scope?: ModelScope): Generator<Model, void, unknown>;
+    updateScope(id: string, scope: ModelScope): void;
+    /**
+     * Create (or update) a model instance locally, given a typename and raw
+     * data. Cleaner than `createFromData({ __typename, ...data })` — the
+     * typename lives in the arg list, not hidden inside the data object.
+     *
+     * Used for optimistic local writes: `pool.create('Slide', { id, deckId, ... })`.
+     * For hydration from server deltas (where `__typename` already rides on
+     * the payload), use `createFromData(data)` directly — that path is kept
+     * because the wire format attaches the discriminator to the data itself.
+     */
+    create(typename: string, data: Record<string, unknown>): Model | null;
+    createFromData(data: Record<string, unknown> & {
+        __typename?: string;
+        __class?: string;
+        modelName?: string;
+        id?: string;
+    }, ModelClass?: new (data: Record<string, unknown>) => Model): Model | null;
+    /**
+     * Clear the object pool
+     * @param options.preserveObserved - If true, keep models that are being observed by React
+     *                                   This prevents React components from holding stale references
+     *                                   after bootstrap/rehydration
+     */
+    clear(options?: {
+        preserveObserved?: boolean;
+    }): void;
+    has(id: string): boolean;
+    /**
+     * Touch a model to update its access time (prevents premature GC)
+     * Used by LazyReferenceCollection to keep parent models alive during active usage
+     */
+    touch(id: string): boolean;
+    getAllIds(): string[];
+    getAllModels(): Model[];
+    get size(): number;
+    get hitRate(): number;
+    getStats(): {
+        size: number;
+        hitRate: number;
+        metrics: {
+            hits: number;
+            misses: number;
+            evictions: number;
+            additions: number;
+            duplicatesSkipped: number;
+        };
+        scopeCounts: {
+            live: number;
+            archived: number;
+        };
+        typeCounts: {
+            [k: string]: number;
+        };
+        deltaHistorySize: number;
+        recentAdditionsSize: number;
+        config: {
+            maxSize: number;
+            maxAge: number;
+            gcInterval: number;
+            useWeakRefs: boolean;
+        };
+    };
+    clearDeltaHistory(olderThanMs?: number): void;
+    private cleanupTracking;
+    private gc;
+    private startGC;
+    stopGC(): void;
+    private evictOldest;
+    private isLargeModel;
+    /**
+     * Register a foreign key field for indexing on a model type.
+     * Call once during app initialization (e.g., after model registration).
+     *
+     * Example: registerForeignKey('SlideLayer', 'slideId')
+     * This enables getByForeignKey('SlideLayer', 'slideId', someSlideId) → O(1) lookup
+     */
+    registerForeignKey(modelName: string, fieldName: string): void;
+    /**
+     * Check whether a foreign key index exists for a given typename + field.
+     * Used by QueryView to decide whether to use FK-index for initial scan.
+     */
+    hasForeignKeyIndex(typename: string, fieldName: string): boolean;
+    /**
+     * Create a QueryView — an incrementally maintained materialized view.
+     * The view registers itself with the ViewRegistry and receives
+     * incremental updates when models of the given typename change.
+     */
+    createView<T extends Record<string, unknown>>(typename: string, options?: QueryViewOptions<T>): QueryView<T>;
+    /**
+     * O(1) lookup of models by foreign key value.
+     * Returns model instances, filtered to live scope by default.
+     */
+    getByForeignKey(modelName: string, fieldName: string, fieldValue: string): Model[];
+    /**
+     * Add a model to foreign key indexes (called from addToTypeIndex path)
+     */
+    private addToForeignKeyIndex;
+    /**
+     * Remove a model from foreign key indexes (called from removeFromTypeIndex path)
+     */
+    private removeFromForeignKeyIndex;
+    private addToTypeIndex;
+    private removeFromTypeIndex;
+    private matchesScope;
+}