@abloatai/humans 0.37.0

package/dist/local/InstanceCache.d.ts

@@ -0,0 +1,255 @@
+/**
+ * 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 '@abloatai/transaction/types';
+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;
+        /**
+         * Build a cold model for continuous wire ingestion. InstanceCache
+         * activates it before get/query/subscriber/view delivery, avoiding eager
+         * per-field MobX setup for rows no consumer has observed.
+         */
+        deferObservability?: 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;
+    /**
+     * Free capacity for a whole incoming frame in one scan.
+     *
+     * Calling evictOldest once per model made a full 10k-entry cache scan
+     * `incomingCount` times. A 400-row delta frame therefore performed four
+     * million entry visits before constructing models. Keep only the `count`
+     * oldest candidates in a bounded max-heap: a full sort paid
+     * O(cache log cache) for every sustained publication frame even though it
+     * consumed only the first few hundred entries. The heap preserves the same
+     * LRU/observed-model contract at O(cache log count) time and O(count) space.
+     */
+    private evictOldestBatch;
+    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;
+}