@abloatai/humans 0.37.0

package/dist/local/ModelRegistry.d.ts

@@ -0,0 +1,225 @@
+/**
+ * ModelRegistry is the source of truth for model metadata: which model classes
+ * exist, the properties and references declared on each, the back-references
+ * used for cascade handling, and a stable hash of the whole schema.
+ * {@link Model} instances resolve their metadata through the active registry,
+ * and {@link InstanceCache} uses it to map between model names and constructor
+ * classes. References resolve lazily, so a model may declare a reference to
+ * another model that is registered later.
+ */
+import { type ModelMetadata, type PropertyMetadata, type ReferenceMetadata, LoadStrategy } from '@abloatai/transaction/types';
+import type { RuntimeContext } from './RuntimeContext.js';
+import type { Model } from './Model.js';
+import type { ConcreteModelConstructor } from './BaseSyncedStore.js';
+/**
+ * What callers may hand to {@link ModelRegistry.registerModel}: any concrete
+ * `Model` subclass constructor. `never[]` params make every subclass
+ * constructor assignable (construct-signature params are contravariant).
+ */
+export type ModelClassInput = new (...args: never[]) => Model;
+/**
+ * What the registry hands BACK: a registered model class — concretely
+ * constructible with an optional data row (`ConcreteModelConstructor`, the
+ * SDK's existing Model-vs-row construction seam) and carrying `Model`'s
+ * statics (`fromJSON`, …). `Omit<typeof Model, never>` keeps the statics
+ * while stripping the ABSTRACT construct signature (mapped types drop
+ * construct signatures), so `new registry.getModelByName(n)!(...)` is legal.
+ * The one cast from {@link ModelClassInput} lives at the validated
+ * registration boundary below.
+ */
+export type RegisteredModelClass = Omit<typeof Model, never> & ConcreteModelConstructor<Model>;
+/**
+ * {@link ReferenceMetadata} extended with cascade behavior: what happens to a
+ * referencing model when the referenced model is deleted or archived.
+ */
+export interface ExtendedReferenceMetadata extends ReferenceMetadata {
+    onDelete?: 'cascade' | 'nullify' | 'restrict';
+    onArchive?: 'cascade' | 'nullify';
+}
+/**
+ * Reference metadata in its serialized form — `referencedModel` is
+ * resolved to the model NAME (string), not the lazy constructor
+ * thunk. Produced by `exportRegistryData()` and other debug-side
+ * paths. A class function would be unserializable JSON; the name is
+ * what consumers (devtools, schema-hash inputs) actually want.
+ */
+export interface SerializedReferenceMetadata extends Omit<ExtendedReferenceMetadata, 'referencedModel'> {
+    referencedModel: string;
+}
+/**
+ * Metadata that records a child model's foreign key to a parent model, used
+ * for cascade-aware transaction handling: when the parent is deleted, the
+ * child's pending transactions can be cancelled.
+ */
+export interface BackReferenceMetadata {
+    /** The parent model name (e.g., 'Report') */
+    parentModel: string;
+    /** The foreign key property on this model (e.g., 'reportId') */
+    foreignKey: string;
+    /** Whether to cascade-cancel transactions when parent is deleted */
+    cascadeDelete: boolean;
+}
+interface RegistryConfig {
+    validateOnRegister?: boolean;
+    allowLateReferences?: boolean;
+    /** The owning client's runtime. Defaults to the module-global bridge. */
+    runtime?: RuntimeContext;
+}
+/** Set the active ModelRegistry instance (called by createSyncEngine) */
+export declare function setActiveRegistry(registry: ModelRegistry): void;
+/** Get the active ModelRegistry. Throws if none set. */
+export declare function getActiveRegistry(): ModelRegistry;
+/** Whether an active ModelRegistry has been set. */
+export declare function hasActiveRegistry(): boolean;
+/** Clear the active ModelRegistry (tests only). */
+export declare function clearActiveRegistry(): void;
+export declare class ModelRegistry {
+    private models;
+    private modelMetadata;
+    private properties;
+    private references;
+    private pendingReferences;
+    private constructorToModelName;
+    private backReferences;
+    private schemaHash?;
+    private config;
+    private readonly runtime;
+    private registeredModels;
+    private pendingHashUpdate;
+    constructor(config?: RegistryConfig);
+    private validateModelConstructor;
+    private arePropertiesCompatible;
+    private addPendingReference;
+    private resolvePendingReferences;
+    private completeReferenceRegistration;
+    /**
+     * Register a model with validation
+     */
+    registerModel(name: string, constructor: ModelClassInput, metadata?: ModelMetadata): void;
+    /**
+     * Register property with validation
+     */
+    registerProperty(modelName: string, propertyName: string, metadata: PropertyMetadata): void;
+    /**
+     * Register reference with lazy resolution
+     */
+    registerReference(modelName: string, propertyName: string, metadata: ExtendedReferenceMetadata): void;
+    /**
+     * Register a back-reference for cascade-aware transaction handling.
+     *
+     * When a parent model is deleted, the transaction queue cancels pending
+     * transactions for every child model that declares a back-reference to that
+     * parent.
+     *
+     * @param childModelName - The model that holds a foreign key to the parent (e.g., 'Section')
+     * @param metadata - The back-reference configuration
+     */
+    registerBackReference(childModelName: string, metadata: BackReferenceMetadata): void;
+    /** Get all models with specific load strategy. */
+    getModelsByLoadStrategy(strategy: LoadStrategy): string[];
+    /** Get model name from constructor (production-safe). */
+    getModelNameFromConstructor(constructor: unknown): string | undefined;
+    /** Get properties for a model. */
+    getPropertiesForModel(modelName: string): Map<string, PropertyMetadata>;
+    /**
+     * Get all registered model names for this instance
+     */
+    getRegisteredModelNames(): string[];
+    /** Get model constructor by name */
+    getModelByName(name: string): RegisteredModelClass | undefined;
+    /** Check if model is registered */
+    hasModel(name: string): boolean;
+    /** Get model metadata by name */
+    getMetadata(name: string): ModelMetadata | undefined;
+    /** Get properties for a model */
+    getProperties(name: string): Map<string, PropertyMetadata>;
+    /** Get references for a model */
+    getReferences(name: string): Map<string, ExtendedReferenceMetadata>;
+    /** Get indexed properties for a model */
+    getIndexedProperties(modelName: string): string[];
+    /** Get back-references for a child model */
+    getBackReferences(childModelName: string): BackReferenceMetadata[];
+    /** Get child models for a parent */
+    getChildModels(parentModelName: string): {
+        childModel: string;
+        foreignKey: string;
+    }[];
+    /**
+     * Compute a stable hash of the registered schema — model names, property
+     * types, and their indexed and optional flags. Memoized until the schema
+     * changes.
+     */
+    getSchemaHash(): string;
+    /**
+     * Browser-compatible hash function
+     */
+    private simpleHash;
+    /**
+     * Static wrapper for backward compatibility
+     */
+    /**
+     * Validate all references
+     */
+    validateReferences(): {
+        valid: boolean;
+        errors: string[];
+    };
+    /**
+     * Static wrapper for backward compatibility
+     */
+    /**
+     * Start batch registration mode to optimize performance
+     */
+    startBatch(): void;
+    /**
+     * Static wrapper for backward compatibility
+     */
+    /**
+     * End batch registration mode and update schema hash if needed
+     */
+    endBatch(): void;
+    /**
+     * Static wrapper for backward compatibility
+     */
+    /**
+     * Clear registry
+     */
+    clear(): void;
+    /**
+     * Static wrapper for backward compatibility
+     */
+    /**
+     * Export for debugging
+     */
+    export(): {
+        models: string[];
+        metadata: {
+            [k: string]: ModelMetadata;
+        };
+        properties: {
+            [k: string]: {
+                [k: string]: PropertyMetadata;
+            };
+        };
+        references: {
+            [k: string]: {
+                [k: string]: ExtendedReferenceMetadata;
+            };
+        };
+        pending: {
+            [k: string]: string[];
+        };
+        schemaHash: string;
+    };
+    /**
+     * Export registry data for debugging (backward compatibility)
+     */
+    exportRegistryData(): {
+        models: Record<string, string>;
+        properties: Record<string, Record<string, PropertyMetadata>>;
+        references: Record<string, Record<string, SerializedReferenceMetadata>>;
+        metadata: Record<string, ModelMetadata>;
+        schemaHash: string;
+    };
+}
+export {};