@affectively/aeon 1.0.0

package/dist/versioning/index.d.ts

@@ -0,0 +1,472 @@
+/**
+ * Schema Version Manager
+ *
+ * Manages schema versioning across the application.
+ * Tracks version history, compatibility, and migration paths.
+ *
+ * Features:
+ * - Version tracking and comparison
+ * - Compatibility matrix management
+ * - Migration path calculation
+ * - Version validation
+ */
+interface SchemaVersion {
+    major: number;
+    minor: number;
+    patch: number;
+    timestamp: string;
+    description: string;
+    breaking: boolean;
+}
+interface VersionMetadata {
+    version: SchemaVersion;
+    previousVersion?: SchemaVersion;
+    changes: string[];
+    migrationsRequired: string[];
+    rollbackPossible: boolean;
+}
+interface CompatibilityRule {
+    from: string;
+    to: string;
+    compatible: boolean;
+    requiresMigration: boolean;
+    migrationSteps: number;
+}
+/**
+ * Schema Version Manager
+ * Tracks and manages schema versions across the application
+ */
+declare class SchemaVersionManager {
+    private versions;
+    private versionHistory;
+    private compatibilityMatrix;
+    private currentVersion;
+    constructor();
+    /**
+     * Initialize default versions
+     */
+    private initializeDefaultVersions;
+    /**
+     * Register a new schema version
+     */
+    registerVersion(version: SchemaVersion): void;
+    /**
+     * Get current version
+     */
+    getCurrentVersion(): SchemaVersion;
+    /**
+     * Set current version
+     */
+    setCurrentVersion(version: SchemaVersion): void;
+    /**
+     * Get version history
+     */
+    getVersionHistory(): SchemaVersion[];
+    /**
+     * Check if version exists
+     */
+    hasVersion(version: SchemaVersion): boolean;
+    /**
+     * Get version by string (e.g., "1.2.3")
+     */
+    getVersion(versionString: string): SchemaVersion | undefined;
+    /**
+     * Register compatibility rule
+     */
+    registerCompatibility(rule: CompatibilityRule): void;
+    /**
+     * Check if migration path exists
+     */
+    canMigrate(fromVersion: SchemaVersion | string, toVersion: SchemaVersion | string): boolean;
+    /**
+     * Get migration path
+     */
+    getMigrationPath(fromVersion: SchemaVersion, toVersion: SchemaVersion): SchemaVersion[];
+    /**
+     * Compare two versions
+     * Returns: -1 if v1 < v2, 0 if equal, 1 if v1 > v2
+     */
+    compareVersions(v1: SchemaVersion | string, v2: SchemaVersion | string): number;
+    /**
+     * Parse version string to SchemaVersion
+     */
+    parseVersion(versionString: string): SchemaVersion;
+    /**
+     * Create new version
+     */
+    createVersion(major: number, minor: number, patch: number, description: string, breaking?: boolean): SchemaVersion;
+    /**
+     * Convert version to string
+     */
+    versionToString(version: SchemaVersion): string;
+    /**
+     * Get version metadata
+     */
+    getVersionMetadata(version: SchemaVersion): VersionMetadata;
+    /**
+     * Get all registered versions
+     */
+    getAllVersions(): SchemaVersion[];
+    /**
+     * Clear all versions (for testing)
+     */
+    clear(): void;
+}
+
+/**
+ * Migration Engine
+ *
+ * Executes schema migrations with rollback support.
+ * Manages migration execution, error handling, and state management.
+ *
+ * Features:
+ * - Migration execution and tracking
+ * - Rollback support
+ * - Error handling and recovery
+ * - Migration state management
+ */
+interface Migration {
+    id: string;
+    version: string;
+    name: string;
+    up: (data: unknown) => unknown;
+    down?: (data: unknown) => unknown;
+    timestamp: string;
+    description: string;
+}
+interface MigrationResult {
+    migrationId: string;
+    success: boolean;
+    timestamp: string;
+    duration: number;
+    itemsAffected: number;
+    errors: string[];
+}
+interface MigrationState {
+    currentVersion: string;
+    appliedMigrations: string[];
+    failedMigrations: string[];
+    lastMigrationTime: string;
+    totalMigrationsRun: number;
+}
+/**
+ * Migration Engine
+ * Executes and manages schema migrations
+ */
+declare class MigrationEngine {
+    private migrations;
+    private executedMigrations;
+    private state;
+    /**
+     * Register a migration
+     */
+    registerMigration(migration: Migration): void;
+    /**
+     * Execute a migration
+     */
+    executeMigration(migrationId: string, data: unknown): Promise<MigrationResult>;
+    /**
+     * Rollback a migration
+     */
+    rollbackMigration(migrationId: string, data: unknown): Promise<MigrationResult>;
+    /**
+     * Get migration state
+     */
+    getState(): MigrationState;
+    /**
+     * Get migration execution history
+     */
+    getExecutionHistory(): MigrationResult[];
+    /**
+     * Get migration by ID
+     */
+    getMigration(migrationId: string): Migration | undefined;
+    /**
+     * Get all registered migrations
+     */
+    getAllMigrations(): Migration[];
+    /**
+     * Get applied migrations
+     */
+    getAppliedMigrations(): string[];
+    /**
+     * Get failed migrations
+     */
+    getFailedMigrations(): string[];
+    /**
+     * Get pending migrations
+     */
+    getPendingMigrations(): Migration[];
+    /**
+     * Get migration statistics
+     */
+    getStatistics(): {
+        totalExecuted: number;
+        successful: number;
+        failed: number;
+        successRate: number;
+        totalDurationMs: number;
+        averageDurationMs: number;
+        totalAffected: number;
+    };
+    /**
+     * Clear history (for testing)
+     */
+    clear(): void;
+}
+
+/**
+ * Data Transformer
+ *
+ * Transforms data structures during schema migrations.
+ * Handles field transformation, type casting, and validation.
+ *
+ * Features:
+ * - Field-level transformation
+ * - Type conversion and casting
+ * - Validation during transformation
+ * - Error handling and reporting
+ * - Batch transformation support
+ */
+interface FieldTransformer {
+    (value: unknown): unknown;
+}
+interface TransformationRule {
+    field: string;
+    transformer: FieldTransformer;
+    required?: boolean;
+    defaultValue?: unknown;
+}
+interface TransformationResult {
+    success: boolean;
+    itemsTransformed: number;
+    itemsFailed: number;
+    errors: Array<{
+        item: unknown;
+        error: string;
+    }>;
+    warnings: string[];
+    duration: number;
+}
+/**
+ * Data Transformer
+ * Transforms data structures during schema migrations
+ */
+declare class DataTransformer {
+    private rules;
+    private transformationHistory;
+    /**
+     * Register a transformation rule
+     */
+    registerRule(rule: TransformationRule): void;
+    /**
+     * Transform a single field value
+     */
+    transformField(field: string, value: unknown): unknown;
+    /**
+     * Transform a single object
+     */
+    transformObject(data: Record<string, unknown>): Record<string, unknown>;
+    /**
+     * Transform a collection of items
+     */
+    transformCollection(items: unknown[]): TransformationResult;
+    /**
+     * Validate transformed data
+     */
+    validateTransformation(original: unknown[], transformed: unknown[]): {
+        valid: boolean;
+        issues: string[];
+    };
+    /**
+     * Validate a single item transformation
+     */
+    private validateItem;
+    /**
+     * Get transformation history
+     */
+    getTransformationHistory(): TransformationResult[];
+    /**
+     * Get transformation statistics
+     */
+    getStatistics(): {
+        totalBatches: number;
+        totalTransformed: number;
+        totalFailed: number;
+        successRate: number;
+        totalDurationMs: number;
+        averageBatchDurationMs: number;
+    };
+    /**
+     * Get registered rules
+     */
+    getRules(): TransformationRule[];
+    /**
+     * Get rule for field
+     */
+    getRule(field: string): TransformationRule | undefined;
+    /**
+     * Clear all rules (for testing)
+     */
+    clearRules(): void;
+    /**
+     * Clear history (for testing)
+     */
+    clearHistory(): void;
+    /**
+     * Clear all state (for testing)
+     */
+    clear(): void;
+}
+
+/**
+ * Migration Tracker
+ *
+ * Tracks migration history and enables rollback.
+ * Maintains detailed audit trail of all schema changes.
+ *
+ * Features:
+ * - Migration history tracking
+ * - Rollback path calculation
+ * - Data snapshots for recovery
+ * - Audit trail with timestamps
+ * - Migration dependency tracking
+ */
+interface MigrationRecord {
+    id: string;
+    migrationId: string;
+    timestamp: string;
+    version: string;
+    direction: 'up' | 'down';
+    status: 'pending' | 'applied' | 'failed' | 'rolled-back';
+    duration: number;
+    itemsAffected: number;
+    dataSnapshot?: {
+        beforeHash: string;
+        afterHash: string;
+        itemCount: number;
+    };
+    errorMessage?: string;
+    appliedBy: string;
+    metadata?: Record<string, unknown>;
+}
+interface RollbackPath {
+    path: string[];
+    canRollback: boolean;
+    affectedVersions: string[];
+    estimatedDuration: number;
+}
+/**
+ * Migration Tracker
+ * Tracks and manages migration history with rollback support
+ */
+declare class MigrationTracker {
+    private migrations;
+    private snapshots;
+    /**
+     * Track a new migration
+     */
+    recordMigration(record: MigrationRecord): void;
+    /**
+     * Track migration with snapshot
+     */
+    trackMigration(migrationId: string, version: string, beforeHash: string, afterHash: string, itemCount: number, duration: number, itemsAffected: number, appliedBy?: string): void;
+    /**
+     * Get all migration records
+     */
+    getMigrations(): MigrationRecord[];
+    /**
+     * Get migrations for a specific version
+     */
+    getMigrationsForVersion(version: string): MigrationRecord[];
+    /**
+     * Get migration by ID
+     */
+    getMigration(id: string): MigrationRecord | undefined;
+    /**
+     * Check if can rollback
+     */
+    canRollback(fromVersion: string, toVersion: string): boolean;
+    /**
+     * Get rollback path
+     */
+    getRollbackPath(fromVersion: string, toVersion: string): RollbackPath;
+    /**
+     * Get applied migrations
+     */
+    getAppliedMigrations(): MigrationRecord[];
+    /**
+     * Get failed migrations
+     */
+    getFailedMigrations(): MigrationRecord[];
+    /**
+     * Get pending migrations
+     */
+    getPendingMigrations(): MigrationRecord[];
+    /**
+     * Get latest migration
+     */
+    getLatestMigration(): MigrationRecord | undefined;
+    /**
+     * Get migration timeline
+     */
+    getTimeline(): Array<{
+        timestamp: string;
+        version: string;
+        status: string;
+    }>;
+    /**
+     * Get migration statistics
+     */
+    getStatistics(): {
+        total: number;
+        applied: number;
+        failed: number;
+        pending: number;
+        rolledBack: number;
+        successRate: number;
+        totalDurationMs: number;
+        averageDurationMs: number;
+        totalItemsAffected: number;
+    };
+    /**
+     * Get audit trail
+     */
+    getAuditTrail(migrationId?: string): {
+        id: string;
+        timestamp: string;
+        migrationId: string;
+        version: string;
+        status: "pending" | "failed" | "applied" | "rolled-back";
+        appliedBy: string;
+        duration: number;
+        itemsAffected: number;
+        error: string | undefined;
+    }[];
+    /**
+     * Get data snapshot for recovery
+     */
+    getSnapshot(recordId: string): {
+        beforeHash: string;
+        afterHash: string;
+        itemCount: number;
+    } | undefined;
+    /**
+     * Update migration status
+     */
+    updateMigrationStatus(recordId: string, status: MigrationRecord['status'], error?: string): void;
+    /**
+     * Clear history (for testing)
+     */
+    clear(): void;
+    /**
+     * Get total migrations tracked
+     */
+    getTotalMigrations(): number;
+    /**
+     * Find migrations by time range
+     */
+    getMigrationsByTimeRange(startTime: string, endTime: string): MigrationRecord[];
+}
+
+export { type CompatibilityRule, DataTransformer, type FieldTransformer, type Migration, MigrationEngine, type MigrationRecord, type MigrationResult, type MigrationState, MigrationTracker, type RollbackPath, type SchemaVersion, SchemaVersionManager, type TransformationResult, type TransformationRule, type VersionMetadata };