@affectively/aeon 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Affectively AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,332 @@
+# Aeon
+
+> Distributed synchronization, schema versioning, and conflict resolution for real-time collaborative applications.
+
+[![npm version](https://badge.fury.io/js/@affectively%2Faeon.svg)](https://www.npmjs.com/package/@affectively/aeon)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.6+-blue.svg)](https://www.typescriptlang.org/)
+
+## Philosophy
+
+In Gnosticism, **Aeons** are not just time periods; they are divine beings or powers that emanate from the "One" (the Pleroma). They function as links or "levels" between the pure divine source and the material world, often existing in pairs (syzygies) to maintain balance.
+
+In the Affectively framework, if "halos" are the users, then **Aeons are the collaborative structures** - the channels that allow users to communicate with the higher-level logic of the platform. They bridge the gap between individual user state and the distributed system, maintaining harmony across the network.
+
+## Overview
+
+**Aeon** is a comprehensive TypeScript library for building distributed, collaborative applications. It provides the primitives needed for:
+
+- **Distributed Synchronization** - Coordinate sync sessions across multiple nodes
+- **Schema Versioning** - Manage schema evolution with migrations and rollbacks
+- **Data Replication** - Configure consistency levels and replication policies
+- **Conflict Resolution** - Multiple strategies for resolving divergent state
+- **Real-time Presence** - Track node health and status in real-time
+
+## Installation
+
+```bash
+npm install @affectively/aeon
+# or
+yarn add @affectively/aeon
+# or
+pnpm add @affectively/aeon
+# or
+bun add @affectively/aeon
+```
+
+## Quick Start
+
+### Distributed Synchronization
+
+```typescript
+import { SyncCoordinator } from '@affectively/aeon';
+
+// Create a sync coordinator
+const coordinator = new SyncCoordinator();
+
+// Register nodes
+coordinator.registerNode({
+  id: 'node-1',
+  address: 'localhost',
+  port: 3000,
+  status: 'online',
+  lastHeartbeat: new Date().toISOString(),
+  version: '1.0.0',
+  capabilities: ['sync', 'replicate'],
+});
+
+// Create a sync session
+const session = coordinator.createSyncSession('node-1', ['node-2', 'node-3']);
+
+// Listen for sync events
+coordinator.on('sync-completed', (session) => {
+  console.log(`Session ${session.id} completed:`, session.itemsSynced, 'items synced');
+});
+
+// Start heartbeat monitoring
+coordinator.startHeartbeatMonitoring(5000);
+```
+
+### Schema Versioning & Migrations
+
+```typescript
+import { SchemaVersionManager, MigrationEngine, MigrationTracker } from '@affectively/aeon';
+
+// Initialize version manager
+const versionManager = new SchemaVersionManager();
+
+// Register schema versions
+versionManager.registerVersion({
+  major: 1,
+  minor: 0,
+  patch: 0,
+  timestamp: new Date().toISOString(),
+  description: 'Initial schema',
+  breaking: false,
+});
+
+versionManager.registerVersion({
+  major: 2,
+  minor: 0,
+  patch: 0,
+  timestamp: new Date().toISOString(),
+  description: 'Added user status field',
+  breaking: true,
+});
+
+// Create migration engine
+const migrationEngine = new MigrationEngine();
+
+// Register a migration
+migrationEngine.registerMigration({
+  id: 'add-status-field',
+  version: '2.0.0',
+  name: 'Add user status field',
+  up: (data) => ({ ...data, status: 'active' }),
+  down: (data) => {
+    const { status, ...rest } = data;
+    return rest;
+  },
+  timestamp: new Date().toISOString(),
+  description: 'Adds status field to all user records',
+});
+
+// Execute migration
+const result = await migrationEngine.executeMigration('add-status-field', userData);
+console.log(`Migration completed: ${result.itemsAffected} items affected`);
+```
+
+### Data Replication
+
+```typescript
+import { ReplicationManager } from '@affectively/aeon';
+
+const replicationManager = new ReplicationManager();
+
+// Create a replication policy
+const policy = replicationManager.createPolicy(
+  'user-data-policy',
+  3,                    // replication factor
+  'read-after-write',   // consistency level
+  1000,                 // sync interval (ms)
+  10000                 // max replication lag (ms)
+);
+
+// Register replicas
+replicationManager.registerReplica({
+  id: 'replica-1',
+  nodeId: 'node-1',
+  status: 'primary',
+  lastSyncTime: new Date().toISOString(),
+  lagBytes: 0,
+  lagMillis: 0,
+});
+
+// Check replication health
+const health = replicationManager.checkReplicationHealth(policy.id);
+console.log('Replication healthy:', health.healthy);
+```
+
+### Conflict Resolution
+
+```typescript
+import { StateReconciler } from '@affectively/aeon';
+
+const reconciler = new StateReconciler();
+
+// Record state versions from different nodes
+reconciler.recordStateVersion('user:123', '1.0', '2024-01-01T00:00:00Z', 'node-1', 'hash-a', { name: 'Alice' });
+reconciler.recordStateVersion('user:123', '1.0', '2024-01-01T00:00:01Z', 'node-2', 'hash-b', { name: 'Bob' });
+
+// Detect conflicts
+if (reconciler.detectConflicts('user:123')) {
+  // Reconcile using last-write-wins strategy
+  const versions = reconciler.getStateVersions('user:123');
+  const result = reconciler.reconcileLastWriteWins(versions);
+
+  console.log('Resolved state:', result.mergedState);
+  console.log('Conflicts resolved:', result.conflictsResolved);
+}
+```
+
+## Modules
+
+### Core (`@affectively/aeon/core`)
+
+Shared types and utilities used across all modules.
+
+```typescript
+import type { Operation, VectorClock, PresenceInfo } from '@affectively/aeon/core';
+```
+
+### Offline (`@affectively/aeon/offline`)
+
+Offline-first operation management.
+
+- `OfflineOperationQueue` - Priority-based offline operation queue with retry logic
+
+### Compression (`@affectively/aeon/compression`)
+
+Data compression and delta sync optimization.
+
+- `CompressionEngine` - Native compression using CompressionStream API
+- `DeltaSyncOptimizer` - Field-level change detection (70-90% payload reduction)
+
+### Optimization (`@affectively/aeon/optimization`)
+
+Network and performance optimization.
+
+- `PrefetchingEngine` - Predictive pre-compression based on operation patterns
+- `BatchTimingOptimizer` - Intelligent batch scheduling based on network conditions
+- `AdaptiveCompressionOptimizer` - Auto-adjusting compression level (1-9)
+
+### Presence (`@affectively/aeon/presence`)
+
+Real-time agent presence tracking.
+
+- `AgentPresenceManager` - Track agent status, cursors, and activity
+
+### Versioning (`@affectively/aeon/versioning`)
+
+Schema versioning and migration system.
+
+- `SchemaVersionManager` - Version tracking and compatibility
+- `MigrationEngine` - Migration execution and rollback
+- `DataTransformer` - Data transformation during migrations
+- `MigrationTracker` - Migration history and audit trails
+
+### Distributed (`@affectively/aeon/distributed`)
+
+Distributed synchronization primitives.
+
+- `SyncCoordinator` - Sync session management
+- `ReplicationManager` - Replica management and policies
+- `SyncProtocol` - Protocol messages and handshaking
+- `StateReconciler` - Conflict detection and resolution
+
+### Utils (`@affectively/aeon/utils`)
+
+Shared utilities including pluggable logging.
+
+```typescript
+import { setLogger, disableLogging } from '@affectively/aeon/utils';
+
+// Use custom logger
+setLogger({
+  debug: (...args) => myLogger.debug(...args),
+  info: (...args) => myLogger.info(...args),
+  warn: (...args) => myLogger.warn(...args),
+  error: (...args) => myLogger.error(...args),
+});
+
+// Or disable logging entirely
+disableLogging();
+```
+
+## API Reference
+
+### SyncCoordinator
+
+| Method | Description |
+|--------|-------------|
+| `registerNode(node)` | Register a node in the cluster |
+| `deregisterNode(nodeId)` | Remove a node from the cluster |
+| `createSyncSession(initiatorId, participantIds)` | Create a new sync session |
+| `updateSyncSession(sessionId, updates)` | Update sync session status |
+| `recordConflict(sessionId, nodeId, data)` | Record a conflict |
+| `getStatistics()` | Get sync statistics |
+| `startHeartbeatMonitoring(interval)` | Start health monitoring |
+
+### SchemaVersionManager
+
+| Method | Description |
+|--------|-------------|
+| `registerVersion(version)` | Register a schema version |
+| `getCurrentVersion()` | Get current active version |
+| `setCurrentVersion(version)` | Set the current version |
+| `canMigrate(from, to)` | Check if migration path exists |
+| `getMigrationPath(from, to)` | Get migration steps |
+| `compareVersions(v1, v2)` | Compare two versions |
+
+### MigrationEngine
+
+| Method | Description |
+|--------|-------------|
+| `registerMigration(migration)` | Register a migration |
+| `executeMigration(id, data)` | Execute a migration |
+| `rollbackMigration(id, data)` | Rollback a migration |
+| `getState()` | Get current migration state |
+| `getPendingMigrations()` | Get pending migrations |
+| `getStatistics()` | Get migration statistics |
+
+### ReplicationManager
+
+| Method | Description |
+|--------|-------------|
+| `registerReplica(replica)` | Register a replica |
+| `removeReplica(replicaId)` | Remove a replica |
+| `createPolicy(...)` | Create replication policy |
+| `updateReplicaStatus(...)` | Update replica status |
+| `checkReplicationHealth(policyId)` | Check replication health |
+| `getStatistics()` | Get replication statistics |
+
+### StateReconciler
+
+| Method | Description |
+|--------|-------------|
+| `recordStateVersion(...)` | Record a state version |
+| `detectConflicts(key)` | Detect state conflicts |
+| `compareStates(s1, s2)` | Generate state diff |
+| `reconcileLastWriteWins(versions)` | LWW reconciliation |
+| `reconcileVectorClock(versions)` | Vector clock reconciliation |
+| `reconcileMajorityVote(versions)` | Majority vote reconciliation |
+
+## Comparison with Similar Libraries
+
+| Feature | Aeon | Yjs | Automerge |
+|---------|------|-----|-----------|
+| Schema Versioning | ✅ | ❌ | ❌ |
+| Migrations | ✅ | ❌ | ❌ |
+| Replication Policies | ✅ | ❌ | ❌ |
+| Multiple Merge Strategies | ✅ | ⚠️ | ⚠️ |
+| TypeScript-first | ✅ | ⚠️ | ⚠️ |
+| Zero Dependencies* | ✅ | ❌ | ❌ |
+
+*Only `eventemitter3` for event handling
+
+## Requirements
+
+- Node.js >= 18.0.0
+- TypeScript >= 5.0.0 (for types)
+
+## Contributing
+
+Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details.
+
+## License
+
+MIT - see [LICENSE](LICENSE) for details.
+
+## Credits
+
+Built with care by [Affectively AI](https://github.com/affectively-ai).

package/dist/core/index.cjs

@@ -0,0 +1,4 @@
+'use strict';
+
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/core/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.cjs"}

package/dist/core/index.d.cts

@@ -0,0 +1,146 @@
+/**
+ * Aeon Core Types
+ *
+ * Shared type definitions for the Aeon synchronization and versioning system.
+ */
+/**
+ * Operation type - what action is being performed
+ */
+type OperationType = 'create' | 'update' | 'delete' | 'sync' | 'batch';
+/**
+ * Operation priority for sync ordering
+ */
+type OperationPriority = 'high' | 'normal' | 'low';
+/**
+ * Operation sync status
+ */
+type OperationStatus = 'pending' | 'syncing' | 'synced' | 'failed';
+/**
+ * Queued operation for offline-first synchronization
+ */
+interface Operation {
+    id: string;
+    type: OperationType;
+    sessionId: string;
+    status: OperationStatus;
+    data: Record<string, unknown>;
+    priority?: OperationPriority;
+    createdAt?: number;
+    syncedAt?: number;
+    retryCount?: number;
+    maxRetries?: number;
+}
+/**
+ * Conflict detection result
+ */
+interface ConflictDetectionResult {
+    hasConflict: boolean;
+    type?: 'update_update' | 'delete_update' | 'update_delete' | 'concurrent';
+    severity?: 'low' | 'medium' | 'high';
+    similarity?: number;
+}
+/**
+ * Conflict resolution strategy
+ */
+type ResolutionStrategy = 'local_wins' | 'remote_wins' | 'last_modified' | 'merge' | 'manual';
+/**
+ * Sync batch for uploading multiple operations
+ */
+interface SyncBatch {
+    batchId: string;
+    operations: Operation[];
+    totalSize: number;
+    createdAt: number;
+    priority: OperationPriority;
+}
+/**
+ * Sync result from server
+ */
+interface SyncResult {
+    success: boolean;
+    synced: string[];
+    failed: Array<{
+        operationId: string;
+        error: string;
+    }>;
+    conflicts: Array<{
+        operationId: string;
+        remoteVersion: Record<string, unknown>;
+        strategy: ResolutionStrategy;
+    }>;
+}
+/**
+ * Network state for adaptive sync
+ */
+type NetworkState = 'online' | 'offline' | 'poor' | 'unknown';
+/**
+ * Bandwidth profile for sync adaptation
+ */
+interface BandwidthProfile {
+    bandwidth: number;
+    latency: number;
+    timestamp: number;
+    reliability: number;
+}
+/**
+ * Sync coordinator configuration
+ */
+interface SyncCoordinatorConfig {
+    maxBatchSize: number;
+    maxBatchBytes: number;
+    maxRetries: number;
+    retryDelayMs: number;
+    enableCompression: boolean;
+    enableDeltaSync: boolean;
+    adaptateBatchSize: boolean;
+}
+/**
+ * Vector clock for causality tracking
+ */
+interface VectorClock {
+    [nodeId: string]: number;
+}
+/**
+ * CRDT operation for conflict-free updates
+ */
+interface CRDTOperation {
+    id: string;
+    type: 'insert' | 'delete' | 'update';
+    path: string[];
+    value?: unknown;
+    timestamp: number;
+    nodeId: string;
+    vectorClock: VectorClock;
+}
+/**
+ * Presence information for real-time collaboration
+ */
+interface PresenceInfo {
+    userId: string;
+    nodeId: string;
+    cursor?: {
+        x: number;
+        y: number;
+    };
+    selection?: {
+        start: number;
+        end: number;
+    };
+    metadata?: Record<string, unknown>;
+    lastActivity: number;
+}
+/**
+ * Event emitter types
+ */
+type EventCallback<T = unknown> = (data: T) => void;
+type EventUnsubscribe = () => void;
+/**
+ * Generic event emitter interface
+ */
+interface IEventEmitter {
+    on<T = unknown>(event: string, callback: EventCallback<T>): EventUnsubscribe;
+    off(event: string, callback: EventCallback): void;
+    emit<T = unknown>(event: string, data?: T): void;
+}
+
+export type { BandwidthProfile, CRDTOperation, ConflictDetectionResult, EventCallback, EventUnsubscribe, IEventEmitter, NetworkState, Operation, OperationPriority, OperationStatus, OperationType, PresenceInfo, ResolutionStrategy, SyncBatch, SyncCoordinatorConfig, SyncResult, VectorClock };

package/dist/core/index.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Aeon Core Types
+ *
+ * Shared type definitions for the Aeon synchronization and versioning system.
+ */
+/**
+ * Operation type - what action is being performed
+ */
+type OperationType = 'create' | 'update' | 'delete' | 'sync' | 'batch';
+/**
+ * Operation priority for sync ordering
+ */
+type OperationPriority = 'high' | 'normal' | 'low';
+/**
+ * Operation sync status
+ */
+type OperationStatus = 'pending' | 'syncing' | 'synced' | 'failed';
+/**
+ * Queued operation for offline-first synchronization
+ */
+interface Operation {
+    id: string;
+    type: OperationType;
+    sessionId: string;
+    status: OperationStatus;
+    data: Record<string, unknown>;
+    priority?: OperationPriority;
+    createdAt?: number;
+    syncedAt?: number;
+    retryCount?: number;
+    maxRetries?: number;
+}
+/**
+ * Conflict detection result
+ */
+interface ConflictDetectionResult {
+    hasConflict: boolean;
+    type?: 'update_update' | 'delete_update' | 'update_delete' | 'concurrent';
+    severity?: 'low' | 'medium' | 'high';
+    similarity?: number;
+}
+/**
+ * Conflict resolution strategy
+ */
+type ResolutionStrategy = 'local_wins' | 'remote_wins' | 'last_modified' | 'merge' | 'manual';
+/**
+ * Sync batch for uploading multiple operations
+ */
+interface SyncBatch {
+    batchId: string;
+    operations: Operation[];
+    totalSize: number;
+    createdAt: number;
+    priority: OperationPriority;
+}
+/**
+ * Sync result from server
+ */
+interface SyncResult {
+    success: boolean;
+    synced: string[];
+    failed: Array<{
+        operationId: string;
+        error: string;
+    }>;
+    conflicts: Array<{
+        operationId: string;
+        remoteVersion: Record<string, unknown>;
+        strategy: ResolutionStrategy;
+    }>;
+}
+/**
+ * Network state for adaptive sync
+ */
+type NetworkState = 'online' | 'offline' | 'poor' | 'unknown';
+/**
+ * Bandwidth profile for sync adaptation
+ */
+interface BandwidthProfile {
+    bandwidth: number;
+    latency: number;
+    timestamp: number;
+    reliability: number;
+}
+/**
+ * Sync coordinator configuration
+ */
+interface SyncCoordinatorConfig {
+    maxBatchSize: number;
+    maxBatchBytes: number;
+    maxRetries: number;
+    retryDelayMs: number;
+    enableCompression: boolean;
+    enableDeltaSync: boolean;
+    adaptateBatchSize: boolean;
+}
+/**
+ * Vector clock for causality tracking
+ */
+interface VectorClock {
+    [nodeId: string]: number;
+}
+/**
+ * CRDT operation for conflict-free updates
+ */
+interface CRDTOperation {
+    id: string;
+    type: 'insert' | 'delete' | 'update';
+    path: string[];
+    value?: unknown;
+    timestamp: number;
+    nodeId: string;
+    vectorClock: VectorClock;
+}
+/**
+ * Presence information for real-time collaboration
+ */
+interface PresenceInfo {
+    userId: string;
+    nodeId: string;
+    cursor?: {
+        x: number;
+        y: number;
+    };
+    selection?: {
+        start: number;
+        end: number;
+    };
+    metadata?: Record<string, unknown>;
+    lastActivity: number;
+}
+/**
+ * Event emitter types
+ */
+type EventCallback<T = unknown> = (data: T) => void;
+type EventUnsubscribe = () => void;
+/**
+ * Generic event emitter interface
+ */
+interface IEventEmitter {
+    on<T = unknown>(event: string, callback: EventCallback<T>): EventUnsubscribe;
+    off(event: string, callback: EventCallback): void;
+    emit<T = unknown>(event: string, data?: T): void;
+}
+
+export type { BandwidthProfile, CRDTOperation, ConflictDetectionResult, EventCallback, EventUnsubscribe, IEventEmitter, NetworkState, Operation, OperationPriority, OperationStatus, OperationType, PresenceInfo, ResolutionStrategy, SyncBatch, SyncCoordinatorConfig, SyncResult, VectorClock };

package/dist/core/index.js

@@ -0,0 +1,3 @@
+
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}