@affectively/dash 5.0.0 → 5.1.0

package/dist/src/sync/aeon/schema-adapter.js

@@ -0,0 +1,163 @@
+/**
+ * Schema Adapter for Dash
+ *
+ * Bridges Aeon's SchemaVersionManager with Dash's LensEngine.
+ * Provides migration tracking, version compatibility checks, and audit trails.
+ */
+import { SchemaVersionManager, MigrationEngine, MigrationTracker, } from '@affectively/aeon';
+/**
+ * Adapter that bridges Aeon versioning with Dash's Lens system
+ */
+export class DashSchemaAdapter {
+    versionManager;
+    migrationEngine;
+    migrationTracker;
+    lensEngine;
+    constructor(lensEngine) {
+        this.versionManager = new SchemaVersionManager();
+        this.migrationEngine = new MigrationEngine();
+        this.migrationTracker = new MigrationTracker();
+        this.lensEngine = lensEngine;
+    }
+    /**
+     * Register a schema version with associated Lens operations
+     */
+    registerVersion(version, description, lensOps, breaking = false) {
+        const [major, minor, patch] = version.split('.').map(Number);
+        // Register with Aeon
+        this.versionManager.registerVersion({
+            major,
+            minor,
+            patch,
+            timestamp: new Date().toISOString(),
+            description,
+            breaking,
+        });
+        // Register Lens if provided
+        if (lensOps && major > 1) {
+            this.lensEngine.registerLens(major - 1, major, lensOps);
+        }
+    }
+    /**
+     * Register a migration for a version upgrade
+     */
+    registerMigration(id, fromVersion, toVersion, migrate, rollback) {
+        const migration = {
+            id,
+            name: `${fromVersion} -> ${toVersion}`,
+            version: toVersion,
+            description: `Migrate from ${fromVersion} to ${toVersion}`,
+            timestamp: new Date().toISOString(),
+            up: migrate,
+            down: rollback,
+        };
+        this.migrationEngine.registerMigration(migration);
+    }
+    /**
+     * Execute a migration on data
+     */
+    async executeMigration(migrationId, data) {
+        const result = await this.migrationEngine.executeMigration(migrationId, data);
+        // Track the migration
+        const record = {
+            id: `record-${Date.now()}`,
+            migrationId,
+            timestamp: new Date().toISOString(),
+            version: result.migrationId,
+            direction: 'up',
+            status: result.success ? 'applied' : 'failed',
+            duration: result.duration,
+            itemsAffected: result.itemsAffected,
+            errorMessage: result.errors.length > 0 ? result.errors.join(', ') : undefined,
+            appliedBy: 'dash-schema-adapter',
+        };
+        this.migrationTracker.recordMigration(record);
+        return result;
+    }
+    /**
+     * Rollback a migration
+     */
+    async rollbackMigration(migrationId, data) {
+        const result = await this.migrationEngine.rollbackMigration(migrationId, data);
+        // Track the rollback
+        const record = {
+            id: `record-${Date.now()}`,
+            migrationId,
+            timestamp: new Date().toISOString(),
+            version: result.migrationId,
+            direction: 'down',
+            status: result.success ? 'rolled-back' : 'failed',
+            duration: result.duration,
+            itemsAffected: result.itemsAffected,
+            errorMessage: result.errors.length > 0 ? result.errors.join(', ') : undefined,
+            appliedBy: 'dash-schema-adapter',
+        };
+        this.migrationTracker.recordMigration(record);
+        return result;
+    }
+    /**
+     * Migrate data using Lens transformations
+     */
+    migrateWithLens(data, fromVersion, toVersion) {
+        return this.lensEngine.migrate(data, fromVersion, toVersion);
+    }
+    /**
+     * Get current version
+     */
+    getCurrentVersion() {
+        return this.versionManager.getCurrentVersion();
+    }
+    /**
+     * Get a specific version by string
+     */
+    getVersion(version) {
+        return this.versionManager.getVersion(version);
+    }
+    /**
+     * Get migration by ID
+     */
+    getMigration(id) {
+        return this.migrationEngine.getMigration(id);
+    }
+    /**
+     * Check if migration is needed
+     */
+    needsMigration(fromVersion, toVersion) {
+        return this.versionManager.canMigrate(fromVersion, toVersion);
+    }
+    /**
+     * Get migration path between versions
+     */
+    getMigrationPath(fromVersion, toVersion) {
+        const from = this.versionManager.parseVersion(fromVersion);
+        const to = this.versionManager.parseVersion(toVersion);
+        return this.versionManager.getMigrationPath(from, to);
+    }
+    /**
+     * Get pending migrations
+     */
+    getPendingMigrations() {
+        return this.migrationEngine.getPendingMigrations();
+    }
+    /**
+     * Get migration statistics
+     */
+    getStatistics() {
+        return {
+            engine: this.migrationEngine.getStatistics(),
+            tracker: this.migrationTracker.getStatistics(),
+        };
+    }
+    /**
+     * Format version for display
+     */
+    formatVersion(version) {
+        return `${version.major}.${version.minor}.${version.patch}`;
+    }
+}
+/**
+ * Create a schema adapter from an existing LensEngine
+ */
+export function createSchemaAdapter(lensEngine) {
+    return new DashSchemaAdapter(lensEngine);
+}

package/dist/src/sync/hybrid-provider.d.ts

@@ -1,6 +1,10 @@
 import * as Y from 'yjs';
 import { Observable } from 'lib0/observable';
 import * as awarenessProtocol from 'y-protocols/awareness';
+import { type AeonConfig } from './aeon/config.js';
+import { DashDeltaAdapter } from './aeon/delta-adapter.js';
+import { DashPresenceAdapter } from './aeon/presence-adapter.js';
+import { DashOfflineAdapter } from './aeon/offline-adapter.js';
 export declare class HybridProvider extends Observable<string> {
     private doc;
     private ws;
@@ -11,8 +15,13 @@ export declare class HybridProvider extends Observable<string> {
     awareness: awarenessProtocol.Awareness;
     private writer;
     private highFrequencyMode;
-    constructor(url: string, roomName: string, doc: Y.Doc, { awareness }?: {
-        awareness?: awarenessProtocol.Awareness | undefined;
+    private aeonConfig;
+    private deltaAdapter;
+    private presenceAdapter;
+    private offlineAdapter;
+    constructor(url: string, roomName: string, doc: Y.Doc, { awareness, aeonConfig, }?: {
+        awareness?: awarenessProtocol.Awareness;
+        aeonConfig?: AeonConfig;
     });
     private connect;
     private connectWebSocket;
@@ -25,4 +34,139 @@ export declare class HybridProvider extends Observable<string> {
     private onDocUpdate;
     private onAwarenessUpdate;
     destroy(): void;
+    /**
+     * Get the delta adapter for compression stats
+     */
+    getDeltaAdapter(): DashDeltaAdapter | null;
+    /**
+     * Get the presence adapter for rich presence features
+     */
+    getPresenceAdapter(): DashPresenceAdapter | null;
+    /**
+     * Get the offline adapter for queue management
+     */
+    getOfflineAdapter(): DashOfflineAdapter | null;
+    /**
+     * Get Aeon configuration
+     */
+    getAeonConfig(): AeonConfig;
+    /**
+     * Process offline queue when back online
+     */
+    processOfflineQueue(): Promise<{
+        synced: number;
+        failed: number;
+    }>;
+    /**
+     * Get comprehensive connection status
+     */
+    getConnectionStatus(): ConnectionStatus;
+    /**
+     * Get all awareness states from connected peers
+     */
+    getAwarenessStates(): AwarenessState[];
+    /**
+     * Get the local client ID
+     */
+    getLocalClientId(): number;
+    /**
+     * Get connected peer count (excluding local)
+     */
+    getPeerCount(): number;
+    /**
+     * Get document state information
+     */
+    getDocumentState(): DocumentState;
+    /**
+     * Get a snapshot of the Yjs document for inspection
+     */
+    getDocumentSnapshot(): DocumentSnapshot;
+    /**
+     * Set local awareness state for introspection (admin view)
+     */
+    setLocalAwareness(state: Record<string, unknown>): void;
+    /**
+     * Get full provider status for debugging
+     */
+    getProviderStatus(): ProviderStatus;
+    /**
+     * Get Aeon-specific status
+     */
+    getAeonStatus(): AeonStatus;
+}
+export interface ConnectionStatus {
+    connected: boolean;
+    roomName: string;
+    url: string;
+    websocket: {
+        state: 'connecting' | 'open' | 'closing' | 'closed';
+        connected: boolean;
+    };
+    webTransport: {
+        connected: boolean;
+        highFrequencyMode: boolean;
+    };
+    transport: 'WebSocket' | 'WebTransport';
+}
+export interface AwarenessState {
+    clientId: number;
+    state: Record<string, unknown>;
+    isLocal: boolean;
+}
+export interface SharedTypeInfo {
+    name: string;
+    type: 'YMap' | 'YArray' | 'YText' | 'YXmlFragment' | 'unknown';
+    size: number;
+}
+export interface DocumentState {
+    clientId: number;
+    guid: string;
+    stateVectorSize: number;
+    updateSize: number;
+    sharedTypes: SharedTypeInfo[];
+    transactionCount: number;
+    gcEnabled: boolean;
+}
+export interface DocumentSnapshot {
+    timestamp: string;
+    roomName: string;
+    content: Record<string, unknown>;
+}
+export interface ProviderStatus {
+    connection: ConnectionStatus;
+    awareness: {
+        localClientId: number;
+        peerCount: number;
+        states: AwarenessState[];
+    };
+    document: DocumentState;
+    aeon: AeonStatus;
+}
+export interface AeonStatus {
+    enabled: {
+        deltaSync: boolean;
+        richPresence: boolean;
+        offlineQueue: boolean;
+    };
+    delta: {
+        totalOperations: number;
+        totalFull: number;
+        totalDelta: number;
+        totalOriginalSize: number;
+        totalDeltaSize: number;
+        averageReductionPercent: number;
+    } | null;
+    offline: {
+        pending: number;
+        syncing: number;
+        failed: number;
+        synced: number;
+        totalOperations: number;
+    } | null;
+    presence: {
+        total: number;
+        online: number;
+        away: number;
+        offline: number;
+    } | null;
 }

package/dist/src/sync/hybrid-provider.js

@@ -1,3 +1,4 @@
+import * as Y from 'yjs';
 import { Observable } from 'lib0/observable';
 import * as encoding from 'lib0/encoding';
 import * as decoding from 'lib0/decoding';
@@ -5,6 +6,17 @@ import * as decoding from 'lib0/decoding';
 import * as syncProtocol from 'y-protocols/sync';
 // @ts-ignore
 import * as awarenessProtocol from 'y-protocols/awareness';
+// Aeon integration
+import { defaultAeonConfig } from './aeon/config.js';
+import { DashDeltaAdapter } from './aeon/delta-adapter.js';
+import { DashPresenceAdapter } from './aeon/presence-adapter.js';
+import { DashOfflineAdapter } from './aeon/offline-adapter.js';
+// Message types
+const MessageType = {
+    Sync: 0,
+    Awareness: 1,
+    Delta: 2, // New: Aeon delta-compressed sync
+};
 export class HybridProvider extends Observable {
     doc;
     ws = null;
@@ -16,12 +28,28 @@ export class HybridProvider extends Observable {
     writer = null;
     // "High Frequency" mode uses WebTransport for ephemeral data
     highFrequencyMode = false;
-    constructor(url, roomName, doc, { awareness = new awarenessProtocol.Awareness(doc) } = {}) {
+    // Aeon integration
+    aeonConfig;
+    deltaAdapter = null;
+    presenceAdapter = null;
+    offlineAdapter = null;
+    constructor(url, roomName, doc, { awareness = new awarenessProtocol.Awareness(doc), aeonConfig = defaultAeonConfig, } = {}) {
         super();
         this.url = url;
         this.roomName = roomName;
         this.doc = doc;
         this.awareness = awareness;
+        this.aeonConfig = aeonConfig;
+        // Initialize Aeon adapters
+        if (aeonConfig.enableDeltaSync) {
+            this.deltaAdapter = new DashDeltaAdapter(roomName, aeonConfig.deltaThreshold);
+        }
+        if (aeonConfig.enableRichPresence) {
+            this.presenceAdapter = new DashPresenceAdapter(roomName, awareness);
+        }
+        if (aeonConfig.enableOfflineQueue) {
+            this.offlineAdapter = new DashOfflineAdapter(doc, roomName, aeonConfig.maxOfflineQueueSize, aeonConfig.maxOfflineRetries);
+        }
         this.doc.on('update', this.onDocUpdate.bind(this));
         this.awareness.on('update', this.onAwarenessUpdate.bind(this));
         this.connect();
@@ -139,19 +167,28 @@ export class HybridProvider extends Observable {
         }
     }
     handleMessage(buf) {
-        // Simple protocol: First byte is message type (0=Sync, 1=Awareness)
+        // Simple protocol: First byte is message type (0=Sync, 1=Awareness, 2=Delta)
         // In strict binary mode, we might need a more robust header.
         // For now assuming Y-protocol encoding.
         // Note: The Relay DO sends raw messages back.
         const decoder = decoding.createDecoder(buf);
         const messageType = decoding.readVarUint(decoder);
         switch (messageType) {
-            case 0: // Sync
+            case MessageType.Sync:
                 syncProtocol.readSyncMessage(decoder, encoding.createEncoder(), this.doc, this);
                 break;
-            case 1: // Awareness
+            case MessageType.Awareness:
                 awarenessProtocol.applyAwarenessUpdate(this.awareness, decoding.readVarUint8Array(decoder), this);
                 break;
+            case MessageType.Delta:
+                // Handle Aeon delta-compressed sync
+                if (this.deltaAdapter) {
+                    const deltaPayloadBytes = decoding.readVarUint8Array(decoder);
+                    const deltaPayload = this.deltaAdapter.decodePayload(deltaPayloadBytes);
+                    const update = this.deltaAdapter.unwrapDelta(deltaPayload);
+                    Y.applyUpdate(this.doc, update, this);
+                }
+                break;
         }
     }
     async send(message) {
@@ -169,10 +206,26 @@ export class HybridProvider extends Observable {
     onDocUpdate(update, origin) {
         if (origin === this)
             return;
-        const encoder = encoding.createEncoder();
-        encoding.writeVarUint(encoder, 0); // MessageType.Sync
-        syncProtocol.writeUpdate(encoder, update);
-        this.send(encoding.toUint8Array(encoder));
+        // Check if we should queue (offline)
+        if (this.offlineAdapter?.shouldQueue()) {
+            this.offlineAdapter.queueUpdate(update);
+            return;
+        }
+        // Use delta compression if enabled
+        if (this.deltaAdapter) {
+            const deltaPayload = this.deltaAdapter.wrapUpdate(update, origin);
+            const encoder = encoding.createEncoder();
+            encoding.writeVarUint(encoder, MessageType.Delta);
+            encoding.writeVarUint8Array(encoder, this.deltaAdapter.encodePayload(deltaPayload));
+            this.send(encoding.toUint8Array(encoder));
+        }
+        else {
+            // Standard Yjs sync
+            const encoder = encoding.createEncoder();
+            encoding.writeVarUint(encoder, MessageType.Sync);
+            syncProtocol.writeUpdate(encoder, update);
+            this.send(encoding.toUint8Array(encoder));
+        }
     }
     onAwarenessUpdate({ added, updated, removed }, origin) {
         if (origin === this)
@@ -188,7 +241,237 @@ export class HybridProvider extends Observable {
         this.awareness.off('update', this.onAwarenessUpdate);
         this.ws?.close();
         this.wt?.close();
+        // Cleanup Aeon adapters
+        this.presenceAdapter?.destroy();
+        this.offlineAdapter?.destroy();
         this.connected = false;
         super.destroy();
     }
+    // ============================================
+    // AEON ADAPTER ACCESSORS
+    // ============================================
+    /**
+     * Get the delta adapter for compression stats
+     */
+    getDeltaAdapter() {
+        return this.deltaAdapter;
+    }
+    /**
+     * Get the presence adapter for rich presence features
+     */
+    getPresenceAdapter() {
+        return this.presenceAdapter;
+    }
+    /**
+     * Get the offline adapter for queue management
+     */
+    getOfflineAdapter() {
+        return this.offlineAdapter;
+    }
+    /**
+     * Get Aeon configuration
+     */
+    getAeonConfig() {
+        return this.aeonConfig;
+    }
+    /**
+     * Process offline queue when back online
+     */
+    async processOfflineQueue() {
+        if (!this.offlineAdapter) {
+            return { synced: 0, failed: 0 };
+        }
+        return this.offlineAdapter.processQueue(async (update) => {
+            const encoder = encoding.createEncoder();
+            if (this.deltaAdapter) {
+                const deltaPayload = this.deltaAdapter.wrapUpdate(update);
+                encoding.writeVarUint(encoder, MessageType.Delta);
+                encoding.writeVarUint8Array(encoder, this.deltaAdapter.encodePayload(deltaPayload));
+            }
+            else {
+                encoding.writeVarUint(encoder, MessageType.Sync);
+                syncProtocol.writeUpdate(encoder, update);
+            }
+            await this.send(encoding.toUint8Array(encoder));
+        });
+    }
+    // ============================================
+    // INTROSPECTION METHODS FOR DASH-STUDIO
+    // ============================================
+    /**
+     * Get comprehensive connection status
+     */
+    getConnectionStatus() {
+        let wsState = 'closed';
+        if (this.ws) {
+            switch (this.ws.readyState) {
+                case WebSocket.CONNECTING:
+                    wsState = 'connecting';
+                    break;
+                case WebSocket.OPEN:
+                    wsState = 'open';
+                    break;
+                case WebSocket.CLOSING:
+                    wsState = 'closing';
+                    break;
+                case WebSocket.CLOSED:
+                    wsState = 'closed';
+                    break;
+            }
+        }
+        return {
+            connected: this.connected,
+            roomName: this.roomName,
+            url: this.url,
+            websocket: {
+                state: wsState,
+                connected: this.ws !== null && this.ws.readyState === WebSocket.OPEN
+            },
+            webTransport: {
+                connected: this.wt !== null,
+                highFrequencyMode: this.highFrequencyMode
+            },
+            transport: this.highFrequencyMode ? 'WebTransport' : 'WebSocket'
+        };
+    }
+    /**
+     * Get all awareness states from connected peers
+     */
+    getAwarenessStates() {
+        const states = [];
+        const awarenessStates = this.awareness.getStates();
+        awarenessStates.forEach((state, clientId) => {
+            states.push({
+                clientId,
+                state,
+                isLocal: clientId === this.awareness.clientID
+            });
+        });
+        return states;
+    }
+    /**
+     * Get the local client ID
+     */
+    getLocalClientId() {
+        return this.awareness.clientID;
+    }
+    /**
+     * Get connected peer count (excluding local)
+     */
+    getPeerCount() {
+        const states = this.awareness.getStates();
+        return Math.max(0, states.size - 1); // Exclude self
+    }
+    /**
+     * Get document state information
+     */
+    getDocumentState() {
+        const stateVector = Y.encodeStateVector(this.doc);
+        const update = Y.encodeStateAsUpdate(this.doc);
+        // Get shared types info
+        const sharedTypes = [];
+        this.doc.share.forEach((type, name) => {
+            let typeKind = 'unknown';
+            let size = 0;
+            if (type instanceof Y.Map) {
+                typeKind = 'YMap';
+                size = type.size;
+            }
+            else if (type instanceof Y.Array) {
+                typeKind = 'YArray';
+                size = type.length;
+            }
+            else if (type instanceof Y.Text) {
+                typeKind = 'YText';
+                size = type.length;
+            }
+            else if (type instanceof Y.XmlFragment) {
+                typeKind = 'YXmlFragment';
+                size = type.length;
+            }
+            sharedTypes.push({
+                name,
+                type: typeKind,
+                size
+            });
+        });
+        return {
+            clientId: this.doc.clientID,
+            guid: this.doc.guid,
+            stateVectorSize: stateVector.byteLength,
+            updateSize: update.byteLength,
+            sharedTypes,
+            transactionCount: 0, // Yjs doesn't expose this directly
+            gcEnabled: this.doc.gc
+        };
+    }
+    /**
+     * Get a snapshot of the Yjs document for inspection
+     */
+    getDocumentSnapshot() {
+        const content = {};
+        this.doc.share.forEach((type, name) => {
+            try {
+                if (type instanceof Y.Map) {
+                    content[name] = type.toJSON();
+                }
+                else if (type instanceof Y.Array) {
+                    content[name] = type.toJSON();
+                }
+                else if (type instanceof Y.Text) {
+                    content[name] = type.toString();
+                }
+                else if (type instanceof Y.XmlFragment) {
+                    content[name] = type.toString();
+                }
+                else {
+                    content[name] = '[unsupported type]';
+                }
+            }
+            catch (e) {
+                content[name] = '[error reading content]';
+            }
+        });
+        return {
+            timestamp: new Date().toISOString(),
+            roomName: this.roomName,
+            content
+        };
+    }
+    /**
+     * Set local awareness state for introspection (admin view)
+     */
+    setLocalAwareness(state) {
+        this.awareness.setLocalState(state);
+    }
+    /**
+     * Get full provider status for debugging
+     */
+    getProviderStatus() {
+        return {
+            connection: this.getConnectionStatus(),
+            awareness: {
+                localClientId: this.awareness.clientID,
+                peerCount: this.getPeerCount(),
+                states: this.getAwarenessStates()
+            },
+            document: this.getDocumentState(),
+            aeon: this.getAeonStatus()
+        };
+    }
+    /**
+     * Get Aeon-specific status
+     */
+    getAeonStatus() {
+        return {
+            enabled: {
+                deltaSync: this.aeonConfig.enableDeltaSync,
+                richPresence: this.aeonConfig.enableRichPresence,
+                offlineQueue: this.aeonConfig.enableOfflineQueue,
+            },
+            delta: this.deltaAdapter?.getStats() ?? null,
+            offline: this.offlineAdapter?.getStats() ?? null,
+            presence: this.presenceAdapter?.getStats() ?? null,
+        };
+    }
 }