zon-format/dist/core/migration.d.ts

ZON: The most token-efficient serialization format for LLMs - beats CSV, TOON, JSON, and all competitors

/**
 * ZON Data Migration Manager
 *
 * Manages schema migrations for evolving ZON data structures.
 * Supports versioned migration functions with automatic path finding.
 */
export type MigrationFunction = (data: any, fromVersion: string, toVersion: string) => any;
export interface Migration {
    from: string;
    to: string;
    migrate: MigrationFunction;
    description?: string;
}
/**
 * Manager for ZON schema migrations.
 * Allows registering migration functions and automatically finding migration paths.
 */
export declare class ZonMigrationManager {
    private migrations;
    /**
     * Registers a migration from one version to another.
     *
     * @param from - Source version
     * @param to - Target version
     * @param migrate - Migration function
     * @param description - Optional description of the migration
     *
     * @example
     * ```typescript
     * manager.registerMigration("1.0.0", "2.0.0", (data) => {
  
     *   if (data.users) {
     *     data.users = data.users.map(u => ({ ...u, email: `${u.name}@example.com` }));
     *   }
     *   return data;
     * }, "Added email field to users");
     * ```
     */
    registerMigration(from: string, to: string, migrate: MigrationFunction, description?: string): void;
    /**
     * Migrates data from one version to another.
     * Automatically finds the migration path if direct migration not available.
     *
     * @param data - Data to migrate
     * @param fromVersion - Current version
     * @param toVersion - Target version
     * @returns Migrated data
     *
     * @throws Error if no migration path exists
     */
    migrate(data: any, fromVersion: string, toVersion: string): any;
    /**
     * Finds a migration path between two versions using BFS.
     *
     * @param from - Source version
     * @param to - Target version
     * @returns Array of migrations to apply, or null if no path exists
     */
    private findMigrationPath;
    /**
     * Checks if migration is possible between two versions.
     *
     * @param from - Source version
     * @param to - Target version
     * @returns True if migration path exists
     */
    canMigrate(from: string, to: string): boolean;
    /**
     * Gets all registered migrations.
     *
     * @returns Array of all migrations
     */
    getMigrations(): Migration[];
    /**
     * Gets migrations available from a specific version.
     *
     * @param version - Source version
     * @returns Array of migrations starting from this version
     */
    getMigrationsFrom(version: string): Migration[];
    /**
     * Clears all registered migrations.
     */
    clear(): void;
}
/**
 * Global migration manager instance.
 * Can be used to register and manage migrations across the application.
 */
export declare const globalMigrationManager: ZonMigrationManager;
/**
 * Helper function to create a migration that adds a default value for a new field.
 *
 * @param path - Path to the field (e.g., "users.email")
 * @param defaultValue - Default value for the field
 * @returns Migration function
 */
export declare function createAddFieldMigration(path: string, defaultValue: any): MigrationFunction;
/**
 * Helper function to create a migration that removes a field.
 *
 * @param path - Path to the field to remove
 * @returns Migration function
 */
export declare function createRemoveFieldMigration(path: string): MigrationFunction;
/**
 * Helper function to create a migration that renames a field.
 *
 * @param oldPath - Current field path
 * @param newPath - New field path
 * @returns Migration function
 */
export declare function createRenameFieldMigration(oldPath: string, newPath: string): MigrationFunction;