@abloatai/humans 0.37.0

package/dist/local/ModelRegistry.js

@@ -0,0 +1,539 @@
+/**
+ * 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.
+ */
+// Removed Node.js crypto import for browser compatibility
+import { PropertyType, LoadStrategy, } from '@abloatai/transaction/types';
+import { globalRuntime } from './context.js';
+import { AbloValidationError } from '@abloatai/transaction/errors';
+/**
+ * Module-level active registry. Set by createSyncEngine so that Model instances
+ * (which don't receive DI) can look up metadata without static maps.
+ */
+let _activeRegistry = null;
+/** Set the active ModelRegistry instance (called by createSyncEngine) */
+export function setActiveRegistry(registry) {
+    _activeRegistry = registry;
+}
+/** Get the active ModelRegistry. Throws if none set. */
+export function getActiveRegistry() {
+    if (!_activeRegistry) {
+        throw new AbloValidationError('No active ModelRegistry — call createSyncEngine() first', { code: 'registry_not_initialized' });
+    }
+    return _activeRegistry;
+}
+/** Whether an active ModelRegistry has been set. */
+export function hasActiveRegistry() {
+    return _activeRegistry !== null;
+}
+/** Clear the active ModelRegistry (tests only). */
+export function clearActiveRegistry() {
+    _activeRegistry = null;
+}
+export class ModelRegistry {
+    models = new Map();
+    modelMetadata = new Map();
+    properties = new Map();
+    references = new Map();
+    pendingReferences = new Map();
+    // Maps a constructor back to its model name. Keyed as `unknown` on purpose:
+    // lookups arrive both as `this.constructor` (a Function) and as typed model
+    // classes, and both are accepted without a cast.
+    constructorToModelName = new Map();
+    // Back-references for cascade-aware transaction handling. Maps a child model
+    // name to the parent models it references. The inverse direction (parent to
+    // children) is derived on demand by `getChildModels`; it is populated here.
+    backReferences = new Map();
+    schemaHash;
+    config;
+    runtime;
+    registeredModels = new Set();
+    pendingHashUpdate = false;
+    constructor(config = {}) {
+        this.config = {
+            validateOnRegister: config.validateOnRegister ?? true,
+            allowLateReferences: config.allowLateReferences ?? true,
+        };
+        this.runtime = config.runtime ?? globalRuntime;
+    }
+    validateModelConstructor(name, constructor) {
+        if (typeof constructor !== 'function') {
+            throw new AbloValidationError(`Model ${name} constructor must be a function`, { code: 'registry_invalid_constructor' });
+        }
+        const prototype = constructor.prototype;
+        if (!prototype || typeof prototype !== 'object') {
+            throw new AbloValidationError(`Model ${name} constructor must have a prototype`, { code: 'registry_invalid_constructor' });
+        }
+        // Check for required methods
+        const required = ['updateFromData', 'toJSON', 'getModelName'];
+        for (const method of required) {
+            if (typeof prototype[method] !== 'function') {
+                this.runtime.logger.debug('Model missing required method', name, { method });
+            }
+        }
+    }
+    arePropertiesCompatible(existing, incoming) {
+        // For reference-generated ID properties, be more lenient
+        // Only check core compatibility, not all metadata fields
+        return (existing.type === incoming.type &&
+            // For indexed, treat undefined as false for comparison
+            (existing.indexed ?? false) === (incoming.indexed ?? false) &&
+            // For optional, treat undefined as false for comparison
+            (existing.optional ?? false) === (incoming.optional ?? false));
+    }
+    addPendingReference(modelName, propertyName, metadata) {
+        // Get target model name
+        let targetName;
+        try {
+            targetName = metadata.referencedModel()?.name || 'Unknown';
+        }
+        catch {
+            targetName = 'Unknown';
+        }
+        let pending = this.pendingReferences.get(targetName);
+        if (!pending) {
+            pending = [];
+            this.pendingReferences.set(targetName, pending);
+        }
+        pending.push({ modelName, propertyName, metadata });
+        this.runtime.logger.debug('Reference deferred', `${modelName}.${propertyName}`, { targetModel: targetName });
+    }
+    resolvePendingReferences(targetModelName) {
+        const pending = this.pendingReferences.get(targetModelName);
+        if (!pending)
+            return;
+        for (const ref of pending) {
+            try {
+                this.completeReferenceRegistration(ref.modelName, ref.propertyName, ref.metadata);
+                this.runtime.logger.debug('Reference resolved', `${ref.modelName}.${ref.propertyName}`, {
+                    targetModel: targetModelName,
+                });
+            }
+            catch (error) {
+                this.runtime.observability.breadcrumb(`Failed to resolve reference ${ref.modelName}.${ref.propertyName}`, 'sync.database', 'error', {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+        this.pendingReferences.delete(targetModelName);
+    }
+    completeReferenceRegistration(modelName, propertyName, metadata) {
+        // Store reference
+        let refs = this.references.get(modelName);
+        if (!refs) {
+            refs = new Map();
+            this.references.set(modelName, refs);
+        }
+        refs.set(propertyName, metadata);
+        // Register ID property (skip organizationId as it's handled by models themselves)
+        const idPropName = propertyName.endsWith('Id') ? propertyName : `${propertyName}Id`;
+        if (idPropName !== 'organizationId') {
+            this.registerProperty(modelName, idPropName, {
+                type: PropertyType.reference,
+                indexed: metadata.indexed || false,
+                optional: metadata.nullable || false,
+            });
+        }
+        // Register model property
+        this.registerProperty(modelName, propertyName, {
+            type: PropertyType.referenceModel,
+            optional: metadata.nullable || false,
+        });
+        this.schemaHash = undefined;
+    }
+    /**
+     * Register a model with validation
+     */
+    registerModel(name, constructor, metadata = { loadStrategy: LoadStrategy.instant }) {
+        // Validate
+        if (this.config.validateOnRegister) {
+            this.validateModelConstructor(name, constructor);
+        }
+        // Check for duplicate
+        if (this.models.has(name)) {
+            this.runtime.logger.debug('Model already registered, skipping', name);
+            return;
+        }
+        this.runtime.logger.debug('Registering model', name);
+        // Register. The one cast in this file: input is any Model-subclass
+        // constructor (validated above); registered classes are concrete
+        // subclasses constructible with `data?` and carrying Model's statics —
+        // the shape `RegisteredModelClass` names for every read site.
+        const modelClass = constructor;
+        this.models.set(name, modelClass);
+        this.modelMetadata.set(name, metadata);
+        // Record the reverse mapping from constructor to model name
+        this.constructorToModelName.set(constructor, name);
+        // Initialize property maps
+        if (!this.properties.has(name)) {
+            this.properties.set(name, new Map());
+        }
+        if (!this.references.has(name)) {
+            this.references.set(name, new Map());
+        }
+        // Mark as registered
+        this.registeredModels.add(name);
+        // Resolve pending references to this model
+        this.resolvePendingReferences(name);
+        // Invalidate schema hash
+        this.schemaHash = undefined;
+        this.runtime.logger.debug('Model registered', name, metadata);
+    }
+    /**
+     * Register property with validation
+     */
+    registerProperty(modelName, propertyName, metadata) {
+        // Validate model exists
+        if (!this.models.has(modelName) && this.config.validateOnRegister) {
+            throw new AbloValidationError(`Cannot register property for unknown model: ${modelName}`, { code: 'registry_unknown_model' });
+        }
+        // Get or create property map
+        let props = this.properties.get(modelName);
+        if (!props) {
+            props = new Map();
+            this.properties.set(modelName, props);
+        }
+        // Check for conflicts
+        const existing = props.get(propertyName);
+        if (existing) {
+            if (this.arePropertiesCompatible(existing, metadata)) {
+                // Properties are compatible, skip re-registration
+                this.runtime.logger.debug('Property already registered (compatible)', `${modelName}.${propertyName}`);
+                return;
+            }
+            else {
+                throw new AbloValidationError(`Property ${modelName}.${propertyName} already registered with incompatible metadata`, { code: 'registry_property_conflict' });
+            }
+        }
+        props.set(propertyName, metadata);
+        this.schemaHash = undefined;
+        this.runtime.logger.debug('Property registered', `${modelName}.${propertyName}`, metadata);
+    }
+    /**
+     * Register reference with lazy resolution
+     */
+    registerReference(modelName, propertyName, metadata) {
+        // Try to resolve target model
+        let targetModelName;
+        try {
+            const targetModel = metadata.referencedModel();
+            targetModelName = targetModel?.name;
+        }
+        catch {
+            // Defer resolution
+            if (this.config.allowLateReferences) {
+                this.addPendingReference(modelName, propertyName, metadata);
+                return;
+            }
+            throw new AbloValidationError(`Cannot resolve reference ${modelName}.${propertyName}`, { code: 'registry_reference_unresolved' });
+        }
+        // Validate target exists or defer
+        if (!this.models.has(targetModelName)) {
+            if (this.config.allowLateReferences) {
+                this.addPendingReference(modelName, propertyName, metadata);
+                return;
+            }
+            throw new AbloValidationError(`Reference ${modelName}.${propertyName} points to unknown model ${targetModelName}`, { code: 'registry_reference_unknown_target' });
+        }
+        // Complete registration
+        this.completeReferenceRegistration(modelName, propertyName, metadata);
+    }
+    /**
+     * 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, metadata) {
+        // Add to instance map
+        let refs = this.backReferences.get(childModelName);
+        if (!refs) {
+            refs = [];
+            this.backReferences.set(childModelName, refs);
+        }
+        // Avoid duplicates
+        const exists = refs.some((r) => r.parentModel === metadata.parentModel && r.foreignKey === metadata.foreignKey);
+        if (!exists) {
+            refs.push(metadata);
+        }
+        // Reverse lookup (parent → children) is derived on demand by
+        // `getChildModels`, which scans this map.
+        this.runtime.logger.debug('BackReference registered', `${childModelName} -> ${metadata.parentModel}`, {
+            foreignKey: metadata.foreignKey,
+            cascadeDelete: metadata.cascadeDelete,
+        });
+    }
+    /** Get all models with specific load strategy. */
+    getModelsByLoadStrategy(strategy) {
+        const models = [];
+        for (const [modelName, metadata] of this.modelMetadata) {
+            if (metadata.loadStrategy === strategy) {
+                models.push(modelName);
+            }
+        }
+        return models;
+    }
+    /** Get model name from constructor (production-safe). */
+    getModelNameFromConstructor(constructor) {
+        return this.constructorToModelName.get(constructor);
+    }
+    /** Get properties for a model. */
+    getPropertiesForModel(modelName) {
+        return this.properties.get(modelName) || new Map();
+    }
+    /**
+     * Get all registered model names for this instance
+     */
+    getRegisteredModelNames() {
+        return Array.from(this.models.keys());
+    }
+    /** Get model constructor by name */
+    getModelByName(name) {
+        return this.models.get(name);
+    }
+    /** Check if model is registered */
+    hasModel(name) {
+        return this.models.has(name);
+    }
+    /** Get model metadata by name */
+    getMetadata(name) {
+        return this.modelMetadata.get(name);
+    }
+    /** Get properties for a model */
+    getProperties(name) {
+        return this.properties.get(name) || new Map();
+    }
+    /** Get references for a model */
+    getReferences(name) {
+        return this.references.get(name) || new Map();
+    }
+    /** Get indexed properties for a model */
+    getIndexedProperties(modelName) {
+        const properties = this.getProperties(modelName);
+        const indexed = [];
+        for (const [propName, metadata] of properties) {
+            if (metadata.indexed)
+                indexed.push(propName);
+        }
+        return indexed;
+    }
+    /** Get back-references for a child model */
+    getBackReferences(childModelName) {
+        return this.backReferences.get(childModelName) || [];
+    }
+    /** Get child models for a parent */
+    getChildModels(parentModelName) {
+        // Derive from backReferences
+        const children = [];
+        for (const [childModel, refs] of this.backReferences) {
+            for (const ref of refs) {
+                if (ref.parentModel === parentModelName) {
+                    children.push({ childModel, foreignKey: ref.foreignKey });
+                }
+            }
+        }
+        return children;
+    }
+    /**
+     * Compute a stable hash of the registered schema — model names, property
+     * types, and their indexed and optional flags. Memoized until the schema
+     * changes.
+     */
+    getSchemaHash() {
+        if (this.schemaHash)
+            return this.schemaHash;
+        const schema = {};
+        // Build schema object
+        for (const [modelName, props] of this.properties) {
+            schema[modelName] = {};
+            for (const [propName, meta] of props) {
+                schema[modelName][propName] = {
+                    type: meta.type,
+                    indexed: meta.indexed || false,
+                    optional: meta.optional || false,
+                };
+            }
+        }
+        // Sort and stringify
+        const sorted = JSON.stringify(schema, Object.keys(schema).sort());
+        // Create hash - browser-compatible simple hash
+        this.schemaHash = this.simpleHash(sorted);
+        this.runtime.logger.debug('Schema hash updated', this.schemaHash);
+        return this.schemaHash;
+    }
+    /**
+     * Browser-compatible hash function
+     */
+    simpleHash(str) {
+        let hash = 0;
+        for (let i = 0; i < str.length; i++) {
+            const char = str.charCodeAt(i);
+            hash = (hash << 5) - hash + char;
+            hash = hash & hash; // Convert to 32bit integer
+        }
+        return Math.abs(hash).toString(16).padStart(8, '0');
+    }
+    /**
+     * Static wrapper for backward compatibility
+     */
+    /**
+     * Validate all references
+     */
+    validateReferences() {
+        const errors = [];
+        // Check pending references
+        for (const [target, pending] of this.pendingReferences) {
+            for (const ref of pending) {
+                errors.push(`Unresolved reference: ${ref.modelName}.${ref.propertyName} -> ${target}`);
+            }
+        }
+        // Check resolved references
+        for (const [modelName, refs] of this.references) {
+            for (const [propName, meta] of refs) {
+                try {
+                    const target = meta.referencedModel();
+                    if (!this.models.has(target.name)) {
+                        errors.push(`Invalid reference: ${modelName}.${propName} -> ${target.name}`);
+                    }
+                }
+                catch (error) {
+                    errors.push(`Cannot resolve reference: ${modelName}.${propName}`);
+                }
+            }
+        }
+        const isValid = errors.length === 0;
+        if (isValid) {
+            this.runtime.logger.info('All model references are valid');
+        }
+        else {
+            this.runtime.observability.breadcrumb('Reference validation failed', 'sync.database', 'error');
+        }
+        return {
+            valid: isValid,
+            errors,
+        };
+    }
+    /**
+     * Static wrapper for backward compatibility
+     */
+    /**
+     * Start batch registration mode to optimize performance
+     */
+    startBatch() {
+        this.pendingHashUpdate = false;
+    }
+    /**
+     * Static wrapper for backward compatibility
+     */
+    /**
+     * End batch registration mode and update schema hash if needed
+     */
+    endBatch() {
+        if (this.pendingHashUpdate) {
+            this.getSchemaHash(); // This will recalculate if needed
+            this.pendingHashUpdate = false;
+        }
+    }
+    /**
+     * Static wrapper for backward compatibility
+     */
+    /**
+     * Clear registry
+     */
+    clear() {
+        this.models.clear();
+        this.modelMetadata.clear();
+        this.properties.clear();
+        this.references.clear();
+        this.pendingReferences.clear();
+        this.registeredModels.clear();
+        this.backReferences.clear();
+        this.constructorToModelName.clear();
+        this.schemaHash = undefined;
+        this.pendingHashUpdate = false;
+        this.runtime.logger.info('ModelRegistry cleared');
+    }
+    /**
+     * Static wrapper for backward compatibility
+     */
+    /**
+     * Export for debugging
+     */
+    export() {
+        return {
+            models: Array.from(this.models.keys()),
+            metadata: Object.fromEntries(this.modelMetadata),
+            properties: Object.fromEntries(Array.from(this.properties.entries()).map(([name, props]) => [
+                name,
+                Object.fromEntries(props),
+            ])),
+            references: Object.fromEntries(Array.from(this.references.entries()).map(([name, refs]) => [
+                name,
+                Object.fromEntries(refs),
+            ])),
+            pending: Object.fromEntries(Array.from(this.pendingReferences.entries()).map(([name, refs]) => [
+                name,
+                refs.map((r) => `${r.modelName}.${r.propertyName}`),
+            ])),
+            schemaHash: this.getSchemaHash(),
+        };
+    }
+    /**
+     * Export registry data for debugging (backward compatibility)
+     */
+    exportRegistryData() {
+        const models = {};
+        const properties = {};
+        const references = {};
+        const metadata = {};
+        // Export models
+        for (const [name, constructor] of this.models) {
+            models[name] = constructor.name;
+        }
+        // Export properties
+        for (const [modelName, propertyMap] of this.properties) {
+            properties[modelName] = {};
+            for (const [propName, propMetadata] of propertyMap) {
+                properties[modelName][propName] = propMetadata;
+            }
+        }
+        // Export references
+        for (const [modelName, referenceMap] of this.references) {
+            references[modelName] = {};
+            for (const [refName, refMetadata] of referenceMap) {
+                try {
+                    references[modelName][refName] = {
+                        ...refMetadata,
+                        referencedModel: refMetadata.referencedModel().name,
+                    };
+                }
+                catch {
+                    references[modelName][refName] = {
+                        ...refMetadata,
+                        referencedModel: 'Unresolved',
+                    };
+                }
+            }
+        }
+        // Export metadata
+        for (const [modelName, modelMetadata] of this.modelMetadata) {
+            metadata[modelName] = modelMetadata;
+        }
+        return {
+            models,
+            properties,
+            references,
+            metadata,
+            schemaHash: this.getSchemaHash(),
+        };
+    }
+}

package/dist/local/NetworkMonitor.d.ts

@@ -0,0 +1,28 @@
+/**
+ * NetworkMonitor tracks network connectivity and reports it through events.
+ * It listens to the browser's online and offline events, and it also watches
+ * for a tab becoming visible again: after a laptop sleep/wake or a long spell
+ * in the background, the WebSocket can die silently without an offline event
+ * firing, so returning to the tab emits a recovery signal the store can act on.
+ */
+import { EventEmitter } from 'events';
+import type { RuntimeContext } from './RuntimeContext.js';
+export declare class NetworkMonitor extends EventEmitter {
+    private readonly runtime;
+    private isOnline;
+    private lastOnlineCheck;
+    constructor(runtime?: RuntimeContext);
+    private handleOnline;
+    private handleOffline;
+    /**
+     * When the tab becomes visible, the WebSocket may have silently died
+     * (e.g., laptop sleep/wake, long background). Browser online/offline events
+     * don't fire in this case because the network itself didn't change.
+     * Emit 'visibility_online' so SyncedStore can check and recover.
+     */
+    private handleVisibilityChange;
+    private setupListeners;
+    getStatus(): boolean;
+    getLastOnlineTime(): Date;
+    dispose(): void;
+}

package/dist/local/NetworkMonitor.js

@@ -0,0 +1,79 @@
+/**
+ * NetworkMonitor tracks network connectivity and reports it through events.
+ * It listens to the browser's online and offline events, and it also watches
+ * for a tab becoming visible again: after a laptop sleep/wake or a long spell
+ * in the background, the WebSocket can die silently without an offline event
+ * firing, so returning to the tab emits a recovery signal the store can act on.
+ */
+import { EventEmitter } from 'events';
+import { globalRuntime } from './context.js';
+export class NetworkMonitor extends EventEmitter {
+    runtime;
+    // Only `navigator.onLine === false` means offline. Node 18+ exposes a global
+    // `navigator` with `onLine === undefined`, so the naive `navigator.onLine`
+    // would seed `false` (offline) on every server client — start optimistic.
+    isOnline = !(typeof navigator !== 'undefined' && navigator.onLine === false);
+    lastOnlineCheck = new Date();
+    constructor(runtime = globalRuntime) {
+        super();
+        this.runtime = runtime;
+        this.setupListeners();
+    }
+    handleOnline = () => {
+        const wasOffline = !this.isOnline;
+        this.isOnline = true;
+        this.lastOnlineCheck = new Date();
+        if (wasOffline) {
+            this.runtime.logger.info('Network connection restored');
+            this.emit('online');
+        }
+    };
+    handleOffline = () => {
+        const wasOnline = this.isOnline;
+        this.isOnline = false;
+        if (wasOnline) {
+            // Symmetric with 'Network connection restored' (info) — expected,
+            // transient connectivity state, not an actionable warning.
+            this.runtime.logger.info('Network connection lost');
+            this.emit('offline');
+        }
+    };
+    /**
+     * When the tab becomes visible, the WebSocket may have silently died
+     * (e.g., laptop sleep/wake, long background). Browser online/offline events
+     * don't fire in this case because the network itself didn't change.
+     * Emit 'visibility_online' so SyncedStore can check and recover.
+     */
+    handleVisibilityChange = () => {
+        if (document.visibilityState !== 'visible')
+            return;
+        // Update navigator.onLine state — it may have changed while hidden
+        this.isOnline = navigator.onLine;
+        this.lastOnlineCheck = new Date();
+        if (this.isOnline) {
+            this.runtime.logger.info('Tab became visible with network available — emitting visibility_online');
+            this.emit('visibility_online');
+        }
+    };
+    setupListeners() {
+        if (typeof window === 'undefined')
+            return;
+        window.addEventListener('online', this.handleOnline);
+        window.addEventListener('offline', this.handleOffline);
+        document.addEventListener('visibilitychange', this.handleVisibilityChange);
+    }
+    getStatus() {
+        return this.isOnline;
+    }
+    getLastOnlineTime() {
+        return this.lastOnlineCheck;
+    }
+    dispose() {
+        if (typeof window !== 'undefined') {
+            window.removeEventListener('online', this.handleOnline);
+            window.removeEventListener('offline', this.handleOffline);
+            document.removeEventListener('visibilitychange', this.handleVisibilityChange);
+        }
+        this.removeAllListeners();
+    }
+}