@abloatai/ablo 0.36.0 → 0.37.0

package/dist/InstanceCache.d.ts

@@ -1,237 +0,0 @@
-/**
- * InstanceCache is the in-memory cache of live model instances, keyed by id and
- * deduplicated so each entity has a single instance. It maintains type and
- * foreign-key indexes for fast lookups, evicts entries under a size cap, and
- * notifies subscribers and query views as models are added, updated, or
- * removed. It holds a {@link ModelRegistry} to map between model names and
- * constructor classes, but performs no persistence of its own.
- */
-import { Model } from './Model.js';
-import { ModelRegistry } from './ModelRegistry.js';
-import type { RuntimeContext } from './RuntimeContext.js';
-import { ModelScope } from './transaction/types/index.js';
-import { ViewRegistry } from './views/ViewRegistry.js';
-import { QueryView, type QueryViewOptions } from './views/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;
-    /** The owning client's runtime. Defaults to the module-global bridge. */
-    runtime?: RuntimeContext;
-}
-interface DeltaInfo {
-    action?: string;
-    syncId?: number;
-}
-/**
- * The in-memory cache of model instances, keyed by id and deduplicated so each
- * entity resolves to a single instance.
- */
-export declare class InstanceCache {
-    private entries;
-    private typeIndex;
-    private accessTimes;
-    private recentAdditions;
-    private deltaHistory;
-    private foreignKeyIndexes;
-    private foreignKeyConfig;
-    private metrics;
-    private config;
-    private readonly runtime;
-    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);
-    private resolveModel;
-    get<T extends Model = Model>(id: string): T | undefined;
-    /**
-     * Look a row up **within one model**.
-     *
-     * The pool is a single id space: `get(id)` returns whatever row carries that
-     * id, whatever model it belongs to. That is the correct storage shape — ids
-     * are globally unique, the same premise as Relay's Global Object
-     * Identification — but it means an *untyped* lookup cannot stand in for a
-     * typed one. Apollo and EmberData avoid the question by keying their identity
-     * maps on `Type:id`; with unique ids the equivalent guarantee comes from
-     * stating the expected model at the lookup instead.
-     *
-     * Returns `undefined` for a row belonging to another model: from the asking
-     * model's perspective that id is simply absent. Callers that must tell "not
-     * here" apart from "here, but another model's" should compare against
-     * {@link get}.
-     *
-     * Prefer this over `get()` anywhere the caller knows which model it wants —
-     * `get()` returning another model's row has caused three product bugs, most
-     * recently a resize gesture that reverted after every commit.
-     */
-    getOfType<T extends Model = Model>(id: string, modelName: 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('Section', { id, reportId, ... })`.
-     * 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, opts?: {
-        /**
-         * Throw (instead of warn + return null) when the wire names a model
-         * this client never registered. Passed by the developer-await read
-         * path (`OnDemandLoader`'s network leg) so a schema collision
-         * — the org's pushed schema names `Document` but this client only
-         * registered `documents` — surfaces AT the row that failed, with the
-         * known-model list and `ablo status` pointer, instead of bubbling up
-         * three layers later as a misleading `entity_not_found`. Left off
-         * (default) for the continuous delta loop and IDB-cache hydration,
-         * where a single unknown typename must not wedge the whole batch.
-         */
-        strict?: boolean;
-    }): 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('Block', 'sectionId')
-     * This enables getByForeignKey('Block', 'sectionId', someSectionId) → 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;
-}