@abloatai/ablo 0.3.0

package/dist/ModelRegistry.d.ts

@@ -0,0 +1,200 @@
+/**
+ * ModelRegistry - Type-safe model metadata management
+ *
+ * Key improvements:
+ * - Instance-based for better testing
+ * - Validation at registration
+ * - Lazy reference resolution
+ * - Crypto-based schema hashing
+ * - Comprehensive error reporting
+ * - Best practices from Linear Sync Engine
+ */
+import { ModelMetadata, PropertyMetadata, ReferenceMetadata, LoadStrategy } from './types/index.js';
+/**
+ * Extended ReferenceMetadata with additional Linear-style options
+ */
+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;
+}
+/**
+ * BackReference metadata for cascade-aware transaction handling
+ * Linear pattern: When parent is deleted, cancel pending transactions for children
+ */
+export interface BackReferenceMetadata {
+    /** The parent model name (e.g., 'SlideDeck') */
+    parentModel: string;
+    /** The foreign key property on this model (e.g., 'deckId') */
+    foreignKey: string;
+    /** Whether to cascade-cancel transactions when parent is deleted */
+    cascadeDelete: boolean;
+}
+interface RegistryConfig {
+    validateOnRegister?: boolean;
+    allowLateReferences?: boolean;
+}
+/** 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 registeredModels;
+    private batchMode;
+    private pendingHashUpdate;
+    constructor(config?: RegistryConfig);
+    private validateModelConstructor;
+    private arePropertiesCompatible;
+    private addPendingReference;
+    private resolvePendingReferences;
+    private completeReferenceRegistration;
+    /**
+     * Register a model with validation
+     */
+    registerModel(name: string, constructor: any, 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;
+    /**
+     * LINEAR PATTERN: Register a back-reference for cascade-aware transaction handling
+     *
+     * When a parent model is deleted, the TransactionQueue will cancel pending
+     * transactions for all child models that have a backReference to that parent.
+     *
+     * @param childModelName - The model that has a FK to the parent (e.g., 'Slide')
+     * @param metadata - BackReference 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: any): 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): any;
+    /** 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): Array<{
+        childModel: string;
+        foreignKey: string;
+    }>;
+    /**
+     * Calculate schema hash using crypto
+     */
+    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 {};