@digilogiclabs/platform-core 1.0.0

package/dist/index-C_2W7Byw.d.mts

@@ -0,0 +1,379 @@
+/**
+ * Database Migration Interface
+ *
+ * Provides a vendor-agnostic way to manage database schema migrations.
+ * Supports:
+ * - Forward and rollback migrations
+ * - Migration versioning and tracking
+ * - Transaction-safe migrations
+ * - Dry-run mode for testing
+ * - Migration locking to prevent concurrent runs
+ */
+interface Migration {
+    /** Unique migration version (e.g., '20240101120000' or '001') */
+    version: string;
+    /** Human-readable name */
+    name: string;
+    /** SQL or function to apply the migration */
+    up: string | ((db: IMigrationDatabase) => Promise<void>);
+    /** SQL or function to rollback the migration */
+    down: string | ((db: IMigrationDatabase) => Promise<void>);
+    /** Optional: run in a transaction (default: true) */
+    transactional?: boolean;
+    /** Optional: checksum for detecting modified migrations */
+    checksum?: string;
+}
+interface MigrationRecord {
+    /** Migration version */
+    version: string;
+    /** Migration name */
+    name: string;
+    /** When the migration was applied */
+    appliedAt: Date;
+    /** How long the migration took (ms) */
+    executionTime: number;
+    /** Migration checksum at time of application */
+    checksum?: string;
+}
+interface MigrationResult {
+    /** The migration that was run */
+    migration: Migration;
+    /** Whether it succeeded */
+    success: boolean;
+    /** Execution time in milliseconds */
+    executionTime: number;
+    /** Error if failed */
+    error?: Error;
+    /** Whether this was a dry run */
+    dryRun: boolean;
+}
+interface MigrationStatus {
+    /** Currently applied migrations */
+    applied: MigrationRecord[];
+    /** Pending migrations (not yet applied) */
+    pending: Migration[];
+    /** Current schema version (last applied migration) */
+    currentVersion: string | null;
+    /** Latest available version */
+    latestVersion: string | null;
+}
+interface MigratorConfig {
+    /** Table name for tracking migrations (default: '_migrations') */
+    tableName?: string;
+    /** Schema for migration table (default: 'public') */
+    schema?: string;
+    /** Lock timeout in seconds (default: 60) */
+    lockTimeout?: number;
+    /** Whether to validate checksums (default: true) */
+    validateChecksums?: boolean;
+    /** Directory containing migration files (for file-based loading) */
+    migrationsDir?: string;
+}
+/**
+ * Simplified database interface for migrations
+ * Migrations only need raw SQL execution capability
+ */
+interface IMigrationDatabase {
+    /**
+     * Execute raw SQL
+     */
+    raw<T = unknown>(sql: string, params?: unknown[]): Promise<{
+        data: T[];
+        error?: Error;
+    }>;
+    /**
+     * Execute within a transaction
+     */
+    transaction<T>(fn: (db: IMigrationDatabase) => Promise<T>): Promise<T>;
+}
+interface IMigrator {
+    /**
+     * Get current migration status
+     */
+    status(): Promise<MigrationStatus>;
+    /**
+     * Run all pending migrations
+     */
+    up(options?: {
+        dryRun?: boolean;
+        to?: string;
+    }): Promise<MigrationResult[]>;
+    /**
+     * Rollback the last migration
+     */
+    down(options?: {
+        dryRun?: boolean;
+        steps?: number;
+    }): Promise<MigrationResult[]>;
+    /**
+     * Rollback all migrations and re-run them
+     */
+    reset(options?: {
+        dryRun?: boolean;
+    }): Promise<MigrationResult[]>;
+    /**
+     * Migrate to a specific version (up or down as needed)
+     */
+    goto(version: string, options?: {
+        dryRun?: boolean;
+    }): Promise<MigrationResult[]>;
+    /**
+     * Add migrations to the migrator
+     */
+    addMigrations(migrations: Migration[]): void;
+    /**
+     * Load migrations from directory
+     */
+    loadMigrations(dir: string): Promise<void>;
+    /**
+     * Create a new migration file
+     */
+    create(name: string): Promise<string>;
+    /**
+     * Validate migration integrity
+     */
+    validate(): Promise<{
+        valid: boolean;
+        errors: string[];
+    }>;
+    /**
+     * Acquire migration lock (for concurrent safety)
+     */
+    lock(): Promise<boolean>;
+    /**
+     * Release migration lock
+     */
+    unlock(): Promise<void>;
+}
+
+/**
+ * Database Migrator
+ *
+ * Enterprise-grade database migration system supporting:
+ * - PostgreSQL (primary)
+ * - Memory database (for testing)
+ * - Transaction-safe migrations
+ * - Concurrent execution locking
+ * - Checksum validation
+ * - Dry-run mode
+ */
+
+declare class Migrator implements IMigrator {
+    private db;
+    private config;
+    private migrations;
+    private initialized;
+    private locked;
+    constructor(db: IMigrationDatabase, config?: MigratorConfig);
+    /**
+     * Get the fully qualified migration table name
+     */
+    private get tableName();
+    /**
+     * Get the lock table name
+     */
+    private get lockTableName();
+    /**
+     * Initialize migration tracking tables
+     */
+    private initialize;
+    /**
+     * Acquire migration lock
+     */
+    lock(): Promise<boolean>;
+    /**
+     * Release migration lock
+     */
+    unlock(): Promise<void>;
+    /**
+     * Add migrations to the migrator
+     */
+    addMigrations(migrations: Migration[]): void;
+    /**
+     * Load migrations from directory
+     * Expects files named: {version}_{name}.ts or {version}_{name}.sql
+     */
+    loadMigrations(dir: string): Promise<void>;
+    /**
+     * Parse SQL migration file with -- UP and -- DOWN sections
+     */
+    private parseSqlMigration;
+    /**
+     * Get current migration status
+     */
+    status(): Promise<MigrationStatus>;
+    /**
+     * Run all pending migrations (or up to a specific version)
+     */
+    up(options?: {
+        dryRun?: boolean;
+        to?: string;
+    }): Promise<MigrationResult[]>;
+    /**
+     * Rollback migrations
+     */
+    down(options?: {
+        dryRun?: boolean;
+        steps?: number;
+    }): Promise<MigrationResult[]>;
+    /**
+     * Rollback all migrations and re-run them
+     */
+    reset(options?: {
+        dryRun?: boolean;
+    }): Promise<MigrationResult[]>;
+    /**
+     * Migrate to a specific version
+     */
+    goto(version: string, options?: {
+        dryRun?: boolean;
+    }): Promise<MigrationResult[]>;
+    /**
+     * Run a single migration
+     */
+    private runMigration;
+    /**
+     * Create a new migration file
+     */
+    create(name: string): Promise<string>;
+    /**
+     * Validate migration integrity
+     */
+    validate(): Promise<{
+        valid: boolean;
+        errors: string[];
+    }>;
+}
+
+/**
+ * Migration Helper Functions
+ *
+ * Utilities for creating migrations in a type-safe and convenient way.
+ */
+
+/**
+ * Create a SQL-based migration
+ *
+ * @example
+ * ```typescript
+ * export default sqlMigration({
+ *   version: '20240101000000',
+ *   name: 'create_users',
+ *   up: `
+ *     CREATE TABLE users (
+ *       id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+ *       email VARCHAR(255) UNIQUE NOT NULL,
+ *       created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
+ *     )
+ *   `,
+ *   down: `DROP TABLE users`
+ * });
+ * ```
+ */
+declare function sqlMigration(migration: {
+    version: string;
+    name: string;
+    up: string;
+    down: string;
+    transactional?: boolean;
+}): Migration;
+/**
+ * Create a function-based migration for complex logic
+ *
+ * @example
+ * ```typescript
+ * export default createMigration({
+ *   version: '20240102000000',
+ *   name: 'seed_initial_data',
+ *   up: async (db) => {
+ *     await db.raw(`INSERT INTO users (email) VALUES ('admin@example.com')`);
+ *     await db.raw(`INSERT INTO settings (key, value) VALUES ('version', '1.0.0')`);
+ *   },
+ *   down: async (db) => {
+ *     await db.raw(`DELETE FROM settings WHERE key = 'version'`);
+ *     await db.raw(`DELETE FROM users WHERE email = 'admin@example.com'`);
+ *   }
+ * });
+ * ```
+ */
+declare function createMigration(migration: {
+    version: string;
+    name: string;
+    up: (db: IMigrationDatabase) => Promise<void>;
+    down: (db: IMigrationDatabase) => Promise<void>;
+    transactional?: boolean;
+}): Migration;
+/**
+ * Type-safe migration definition with inference
+ * Useful for defining migrations in separate files
+ *
+ * @example
+ * ```typescript
+ * // migrations/20240101000000_create_users.ts
+ * export const migration = defineMigration({
+ *   version: '20240101000000',
+ *   name: 'create_users',
+ *   up: 'CREATE TABLE users (...)',
+ *   down: 'DROP TABLE users'
+ * });
+ *
+ * // Or with functions
+ * export const migration = defineMigration({
+ *   version: '20240102000000',
+ *   name: 'complex_migration',
+ *   up: async (db) => { ... },
+ *   down: async (db) => { ... }
+ * });
+ * ```
+ */
+declare function defineMigration<T extends {
+    version: string;
+    name: string;
+    up: string | ((db: IMigrationDatabase) => Promise<void>);
+    down: string | ((db: IMigrationDatabase) => Promise<void>);
+    transactional?: boolean;
+}>(migration: T): Migration;
+/**
+ * Generate a version timestamp for new migrations
+ *
+ * @example
+ * ```typescript
+ * const version = generateVersion(); // '20240315143052'
+ * ```
+ */
+declare function generateVersion(): string;
+/**
+ * Common SQL snippets for migrations
+ */
+declare const SQL: {
+    /**
+     * Create updated_at trigger function (PostgreSQL)
+     */
+    createUpdatedAtFunction: string;
+    /**
+     * Create an updated_at trigger for a table
+     */
+    createUpdatedAtTrigger: (tableName: string) => string;
+    /**
+     * Drop an updated_at trigger
+     */
+    dropUpdatedAtTrigger: (tableName: string) => string;
+    /**
+     * Standard timestamp columns
+     */
+    timestampColumns: string;
+    /**
+     * UUID primary key with default
+     */
+    uuidPrimaryKey: string;
+    /**
+     * Enable UUID extension
+     */
+    enableUuidExtension: string;
+    /**
+     * Enable pgcrypto for gen_random_uuid()
+     */
+    enablePgCrypto: string;
+};
+
+export { type IMigrator as I, Migrator as M, SQL as S, type Migration as a, type MigrationRecord as b, createMigration as c, defineMigration as d, type MigrationResult as e, type MigrationStatus as f, generateVersion as g, type MigratorConfig as h, type IMigrationDatabase as i, sqlMigration as s };