@a0n/aeon 5.0.1

package/dist/versioning/index.d.cts

@@ -0,0 +1,537 @@
+import { S as StorageAdapter, b as PersistenceSerializer, a as PersistenceDeserializer } from '../types-CMxO7QF0.cjs';
+
+/**
+ * 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>;
+    previousHash?: string;
+    integrityHash?: string;
+}
+interface RollbackPath {
+    path: string[];
+    canRollback: boolean;
+    affectedVersions: string[];
+    estimatedDuration: number;
+}
+interface MigrationIntegrityEntry {
+    recordId: string;
+    previousHash: string;
+    hash: string;
+}
+interface MigrationTrackerPersistenceData {
+    migrations: MigrationRecord[];
+    snapshots: Array<{
+        recordId: string;
+        beforeHash: string;
+        afterHash: string;
+        itemCount: number;
+    }>;
+    integrity: {
+        algorithm: 'sha256-chain-v1';
+        entries: MigrationIntegrityEntry[];
+        rootHash: string;
+    };
+}
+interface MigrationTrackerPersistenceConfig {
+    adapter: StorageAdapter;
+    key?: string;
+    autoPersist?: boolean;
+    autoLoad?: boolean;
+    persistDebounceMs?: number;
+    serializer?: PersistenceSerializer<MigrationTrackerPersistenceData>;
+    deserializer?: PersistenceDeserializer<MigrationTrackerPersistenceData>;
+}
+interface MigrationTrackerOptions {
+    persistence?: MigrationTrackerPersistenceConfig;
+}
+/**
+ * Migration Tracker
+ * Tracks and manages migration history with rollback support
+ */
+declare class MigrationTracker {
+    private static readonly DEFAULT_PERSIST_KEY;
+    private static readonly INTEGRITY_ROOT;
+    private migrations;
+    private snapshots;
+    private persistence;
+    private persistTimer;
+    private persistInFlight;
+    private persistPending;
+    constructor(options?: MigrationTrackerOptions);
+    /**
+     * 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;
+    /**
+     * Persist tracker state with integrity chain verification metadata.
+     */
+    saveToPersistence(): Promise<void>;
+    /**
+     * Load tracker state and verify integrity chain.
+     */
+    loadFromPersistence(): Promise<{
+        migrations: number;
+        snapshots: number;
+    }>;
+    /**
+     * Remove persisted migration tracker state.
+     */
+    clearPersistence(): Promise<void>;
+    /**
+     * Clear history (for testing)
+     */
+    clear(): void;
+    /**
+     * Get total migrations tracked
+     */
+    getTotalMigrations(): number;
+    /**
+     * Find migrations by time range
+     */
+    getMigrationsByTimeRange(startTime: string, endTime: string): MigrationRecord[];
+    private schedulePersist;
+    private persistSafely;
+    private isValidMigrationRecord;
+    private stableStringify;
+    private computeDigestHex;
+    private toHex;
+    private fallbackDigestHex;
+}
+
+export { type CompatibilityRule, DataTransformer, type FieldTransformer, type Migration, MigrationEngine, type MigrationIntegrityEntry, type MigrationRecord, type MigrationResult, type MigrationState, MigrationTracker, type MigrationTrackerOptions, type MigrationTrackerPersistenceConfig, type MigrationTrackerPersistenceData, type RollbackPath, type SchemaVersion, SchemaVersionManager, type TransformationResult, type TransformationRule, type VersionMetadata };