@abloatai/ablo 0.35.0 → 0.37.0

package/dist/ModelRegistry.js

@@ -1,537 +0,0 @@
-/**
- * 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 './transaction/types/index.js';
-import { getContext } from './context.js';
-import { AbloValidationError } from './transaction/errors.js';
-/**
- * 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;
-    registeredModels = new Set();
-    pendingHashUpdate = false;
-    constructor(config = {}) {
-        this.config = {
-            validateOnRegister: config.validateOnRegister ?? true,
-            allowLateReferences: config.allowLateReferences ?? true,
-        };
-    }
-    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') {
-                getContext().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 });
-        getContext().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);
-                getContext().logger.debug('Reference resolved', `${ref.modelName}.${ref.propertyName}`, {
-                    targetModel: targetModelName,
-                });
-            }
-            catch (error) {
-                getContext().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)) {
-            getContext().logger.debug('Model already registered, skipping', name);
-            return;
-        }
-        getContext().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;
-        getContext().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
-                getContext().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;
-        getContext().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.
-        getContext().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);
-        getContext().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) {
-            getContext().logger.info('All model references are valid');
-        }
-        else {
-            getContext().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;
-        getContext().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/NetworkMonitor.d.ts

@@ -1,26 +0,0 @@
-/**
- * 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';
-export declare class NetworkMonitor extends EventEmitter {
-    private isOnline;
-    private lastOnlineCheck;
-    constructor();
-    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/NetworkMonitor.js

@@ -1,77 +0,0 @@
-/**
- * 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 { getContext } from './context.js';
-export class NetworkMonitor extends EventEmitter {
-    // 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() {
-        super();
-        this.setupListeners();
-    }
-    handleOnline = () => {
-        const wasOffline = !this.isOnline;
-        this.isOnline = true;
-        this.lastOnlineCheck = new Date();
-        if (wasOffline) {
-            getContext().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.
-            getContext().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) {
-            getContext().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();
-    }
-}

package/dist/RuntimeContext.d.ts

@@ -1,52 +0,0 @@
-/**
- * RuntimeContext — Runtime dependency container
- *
- * All SDK classes receive this context at construction time.
- * It bundles every injectable dependency so constructors stay clean.
- */
-import type { Logger, ObservabilityProvider, Analytics, SessionErrorDetector, OnlineStatusProvider, ModelDebugLoggerContract, MutationExecutor, RuntimeConfig } from './interfaces/index.js';
-import type { ModelMetadata } from './transaction/types/index.js';
-export interface RuntimeContext {
-    /** Structured logger */
-    logger: Logger;
-    /** Error tracking & performance monitoring */
-    observability: ObservabilityProvider;
-    /** Product analytics (optional) */
-    analytics?: Analytics;
-    /** Session error detection for auth redirect decisions */
-    sessionErrorDetector: SessionErrorDetector;
-    /** Network connectivity detection */
-    onlineStatus: OnlineStatusProvider;
-    /** Model operation debug logging (optional, dev-only) */
-    modelDebugLogger?: ModelDebugLoggerContract;
-    /** Backend mutation transport (GraphQL, REST, etc.) */
-    mutationExecutor: MutationExecutor;
-    /** Application-specific sync configuration */
-    config: RuntimeConfig;
-    /**
-     * Model metadata lookup. Injected by the client (it wires this from its
-     * `ModelRegistry`) so the settlement core can resolve a model's metadata
-     * without importing the registry — the dependency inversion that keeps the
-     * core free of the client's `Model` layer (ADR 0013).
-     */
-    getModelMetadata: (name: string) => ModelMetadata | undefined;
-}
-export { noopLogger } from './transaction/logger.js';
-/** No-op observability — silently discards all observability calls */
-export declare const noopObservability: ObservabilityProvider;
-/** No-op analytics — silently discards all analytics calls */
-export declare const noopAnalytics: Analytics;
-/** Browser-native online status provider */
-export declare const browserOnlineStatus: OnlineStatusProvider;
-/** Session error detector — delegates to AbloSessionError so detection is
- *  code-aware (only genuine session/JWT expiry counts), not a blunt 401/403. */
-export declare const defaultSessionErrorDetector: SessionErrorDetector;
-/**
- * Fallback config used when the context is read before
- * `createSyncEngine(...)` has initialized it (tests, early-boot code
- * paths). An empty `modelCreatePriority` means every model falls through
- * to `defaultCreatePriority`, so ordering is flat — fine for tests that
- * never exercise FK ordering; consumers who do rely on it should finish
- * wiring the engine before the first `create()` fires.
- */
-export declare const emptyConfig: RuntimeConfig;