ts-prorm-orm 1.1.0 → 1.2.0

package/dist/migrations/prormmigration.d.ts

@@ -0,0 +1,131 @@
+/**
+ * PrormMigration class - Integration layer between migrations and Prorm
+ * Handles running migrations with the Prorm instance
+ */
+import { Migration, MigrationMeta } from './migration';
+import { QueryInterface } from './query-interface';
+import { Prorm } from '../prorm';
+/**
+ * PrormMigration options
+ */
+export interface PrormMigrationOptions {
+    /**
+     * Prorm instance to use
+     */
+    prorm: Prorm;
+    /**
+     * Table name for storing migration history
+     */
+    tableName?: string;
+    /**
+     * Schema for the migrations table
+     */
+    schema?: string;
+}
+/**
+ * PrormMigration - Integrates with Prorm to manage migrations
+ */
+export declare class PrormMigration {
+    private prorm;
+    private queryInterface;
+    private tableName;
+    private schema?;
+    private migrationMeta;
+    /**
+     * Create a new PrormMigration instance
+     * @param options - Configuration options
+     */
+    constructor(options: PrormMigrationOptions);
+    /**
+     * Create a QueryInterface from the Prorm instance
+     */
+    private createQueryInterface;
+    /**
+     * Get the QueryInterface
+     */
+    getQueryInterface(): QueryInterface;
+    /**
+     * Get the Prorm instance
+     */
+    getProrm(): Prorm;
+    /**
+     * Get the migrations table name
+     */
+    getTableName(): string;
+    /**
+     * Ensure the migrations table exists
+     */
+    ensureMigrationsTable(): Promise<void>;
+    /**
+     * Load migration metadata from the database
+     */
+    loadMigrationMeta(): Promise<void>;
+    /**
+     * Record a migration as executed in the database
+     * @param migration - The migration to record
+     * @param batch - The batch number
+     */
+    recordMigration(migration: Migration, batch: number): Promise<void>;
+    /**
+     * Remove a migration record from the database
+     * @param migrationName - Name of the migration to remove
+     */
+    removeMigration(migrationName: string): Promise<void>;
+    /**
+     * Get all executed migrations
+     */
+    getExecutedMigrations(): Promise<MigrationMeta[]>;
+    /**
+     * Check if a migration has been executed
+     * @param migrationName - Name of the migration
+     */
+    isMigrationExecuted(migrationName: string): Promise<boolean>;
+    /**
+     * Compute the next batch number from the currently loaded migration meta.
+     * Callers are expected to have called `loadMigrationMeta()` beforehand.
+     */
+    private computeNextBatch;
+    /**
+     * Run a migration
+     * @param migration - The migration to run
+     * @param batch - Optional batch number to record this migration under. When
+     *   omitted, a fresh batch number is computed for this single migration.
+     *   `runMigrations()` passes an explicit shared batch so that all migrations
+     *   applied in one run land in the same batch.
+     */
+    runMigration(migration: Migration, batch?: number): Promise<void>;
+    /**
+     * Revert a migration
+     * @param migration - The migration to revert
+     */
+    revertMigration(migration: Migration): Promise<void>;
+    /**
+     * Execute all pending migrations
+     * @param migrations - Array of migrations to run
+     */
+    runMigrations(migrations: Migration[]): Promise<void>;
+    /**
+     * Revert migrations to a specific batch
+     *
+     * For each executed migration with a batch number greater than
+     * `targetBatch`, this loads its `down()` function (via the supplied
+     * `migrations` lookup) and actually executes it before removing its
+     * tracking row. If `down()` throws, the error is logged and re-thrown, and
+     * the tracking row for that migration (and any migrations after it) is
+     * left in place so the revert can be retried.
+     *
+     * @param targetBatch - Target batch number to revert down to
+     * @param migrations - The loaded Migration definitions (with `down()`
+     *   functions attached), keyed by migration name. Typically
+     *   `Migrator.getMigrations()` / the Migrator's internal migrations map.
+     */
+    revertToBatch(targetBatch: number, migrations: Map<string, Migration> | Migration[]): Promise<void>;
+    /**
+     * Get the current database version
+     */
+    getDatabaseVersion(): Promise<string>;
+    /**
+     * Sync the migrations table
+     */
+    syncMigrationsTable(): Promise<void>;
+}

package/dist/migrations/query-interface.d.ts

@@ -0,0 +1,335 @@
+/**
+ * QueryInterface for migrations
+ * Provides methods for schema modifications during migrations
+ */
+import { Dialect, ColumnDefinition, TableOptions, IndexOptions } from '../dialects/dialect';
+import { Transaction, WhereOptions } from '../types';
+/**
+ * Table descriptor for querying table info
+ */
+export interface TableDescriptor {
+    tableName: string;
+    schema?: string;
+}
+/**
+ * Column description from describeTable
+ */
+export interface ColumnDescription {
+    type: string;
+    allowNull: boolean;
+    defaultValue: any;
+    primaryKey: boolean;
+    autoIncrement: boolean;
+}
+/**
+ * Index description
+ */
+export interface IndexDescription {
+    name: string;
+    unique: boolean;
+    fields: Array<{
+        attribute: string;
+        order: string;
+    }>;
+    type?: string;
+}
+/**
+ * Foreign key description
+ */
+export interface ForeignKeyDescription {
+    name: string;
+    field: string;
+    references: {
+        table: string;
+        field: string;
+    };
+    onDelete?: string;
+    onUpdate?: string;
+}
+/**
+ * Constraint description
+ */
+export interface ConstraintDescription {
+    name: string;
+    type: 'PRIMARY KEY' | 'UNIQUE' | 'FOREIGN KEY' | 'CHECK' | 'DEFAULT';
+    fields?: string[];
+    reference?: {
+        table: string;
+        fields: string[];
+    };
+}
+/**
+ * QueryInterface class for migrations
+ * Provides a unified API for schema modifications across dialects
+ */
+export declare class QueryInterface {
+    private dialect;
+    private transaction;
+    /**
+     * Create a new QueryInterface instance
+     * @param dialect - The database dialect to use
+     */
+    constructor(dialect: Dialect);
+    /**
+     * Set the current transaction
+     */
+    setTransaction(transaction: Transaction | null): void;
+    /**
+     * Get the current transaction
+     */
+    getTransaction(): Transaction | null;
+    /**
+     * Get the underlying dialect
+     */
+    getDialect(): Dialect;
+    /**
+     * Create a new table
+     * @param tableName - Name of the table to create
+     * @param columns - Column definitions
+     * @param options - Table options
+     */
+    createTable(tableName: string, columns: Record<string, ColumnDefinition>, options?: TableOptions): Promise<void>;
+    /**
+     * Drop a table
+     * @param tableName - Name of the table to drop
+     * @param options - Drop options
+     */
+    dropTable(tableName: string, options?: {
+        cascade?: boolean;
+        ifExists?: boolean;
+    }): Promise<void>;
+    /**
+     * Drop all tables (dialect-specific)
+     */
+    dropAllTables(_options?: {
+        skip?: string[];
+    }): Promise<void>;
+    /**
+     * Rename a table
+     * @param oldName - Current table name
+     * @param newName - New table name
+     */
+    renameTable(oldName: string, newName: string): Promise<void>;
+    /**
+     * Show all tables in the database
+     */
+    showTables(): Promise<string[]>;
+    /**
+     * Describe a table (get column information)
+     * @param tableName - Name of the table to describe
+     */
+    describeTable(tableName: string): Promise<Record<string, ColumnDescription>>;
+    /**
+     * Add a column to a table
+     * @param tableName - Name of the table
+     * @param columnName - Name of the new column
+     * @param definition - Column definition
+     */
+    addColumn(tableName: string, columnName: string, definition: ColumnDefinition): Promise<void>;
+    /**
+     * Remove a column from a table
+     * @param tableName - Name of the table
+     * @param columnName - Name of the column to remove
+     */
+    removeColumn(tableName: string, columnName: string): Promise<void>;
+    /**
+     * Change a column definition
+     * @param tableName - Name of the table
+     * @param columnName - Name of the column to change
+     * @param definition - New column definition
+     */
+    changeColumn(tableName: string, columnName: string, definition: ColumnDefinition): Promise<void>;
+    /**
+     * Rename a column
+     * @param tableName - Name of the table
+     * @param oldColumnName - Current column name
+     * @param newColumnName - New column name
+     */
+    renameColumn(tableName: string, oldColumnName: string, newColumnName: string): Promise<void>;
+    /**
+     * Add an index to a table
+     * @param tableName - Name of the table
+     * @param indexName - Name of the index
+     * @param fields - Fields to index
+     * @param options - Index options
+     */
+    addIndex(tableName: string, indexName: string, fields: string[], options?: IndexOptions): Promise<void>;
+    /**
+     * Remove an index from a table
+     * @param tableName - Name of the table
+     * @param indexName - Name of the index
+     */
+    removeIndex(tableName: string, indexName: string): Promise<void>;
+    /**
+     * Show indexes for a table
+     * @param tableName - Name of the table
+     */
+    showIndexes(tableName: string): Promise<IndexDescription[]>;
+    /**
+     * Add a constraint to a table
+     * @param tableName - Name of the table
+     * @param constraintName - Name of the constraint
+     * @param constraintDefinition - Constraint definition
+     */
+    addConstraint(tableName: string, constraintName: string, constraintDefinition: {
+        type: 'unique' | 'primaryKey' | 'foreignKey' | 'check';
+        fields?: string[];
+        references?: {
+            table: string;
+            fields: string[];
+        };
+        onDelete?: string;
+        onUpdate?: string;
+    }): Promise<void>;
+    /**
+     * Remove a constraint from a table
+     * @param tableName - Name of the table
+     * @param constraintName - Name of the constraint
+     * @param constraintType - Type of constraint
+     */
+    removeConstraint(tableName: string, constraintName: string, constraintType: 'unique' | 'primaryKey' | 'foreignKey' | 'check'): Promise<void>;
+    /**
+     * Bulk insert records into a table
+     * @param tableName - Name of the table
+     * @param records - Array of records to insert
+     */
+    bulkInsert(tableName: string, records: Record<string, any>[]): Promise<number>;
+    /**
+     * Bulk update records in a table
+     * @param tableName - Name of the table
+     * @param values - Values to update
+     * @param where - Where conditions
+     */
+    bulkUpdate(tableName: string, values: Record<string, any>, where: WhereOptions): Promise<number>;
+    /**
+     * Bulk delete records from a table
+     * @param tableName - Name of the table
+     * @param where - Where conditions
+     */
+    bulkDelete(tableName: string, where: WhereOptions): Promise<number>;
+    /**
+     * Check if a table exists
+     * @param tableName - Name of the table
+     */
+    tableExists(tableName: string): Promise<boolean>;
+    /**
+     * Check if a column exists
+     * @param tableName - Name of the table
+     * @param columnName - Name of the column
+     */
+    columnExists(tableName: string, columnName: string): Promise<boolean>;
+    /**
+     * Check if an index exists
+     * @param tableName - Name of the table
+     * @param indexName - Name of the index
+     */
+    indexExists(tableName: string, indexName: string): Promise<boolean>;
+    /**
+     * Get all foreign keys for a table
+     * @param tableName - Name of the table
+     */
+    getForeignKeysForTable(tableName: string): Promise<ForeignKeyDescription[]>;
+    /**
+     * Remove foreign key
+     * @param tableName - Name of the table
+     * @param foreignKeyName - Name of the foreign key
+     */
+    removeForeignKey(tableName: string, foreignKeyName: string): Promise<void>;
+    /**
+     * Add foreign key
+     * @param tableName - Name of the table
+     * @param columnName - Name of the column
+     * @param references - Reference definition
+     */
+    addForeignKey(tableName: string, columnName: string, references: {
+        table: string;
+        field: string;
+    }, onDelete?: string, onUpdate?: string): Promise<void>;
+    /**
+     * Create a partitioned table (PostgreSQL 10+)
+     * @param tableName - Name of the table to create
+     * @param columns - Column definitions
+     * @param options - Table options including partition configuration
+     */
+    createPartitionedTable(tableName: string, columns: Record<string, ColumnDefinition>, options?: TableOptions & {
+        partitionBy: {
+            type: 'range' | 'list' | 'hash';
+            column: string | string[];
+        };
+        partitions?: {
+            name: string;
+            bound?: {
+                from: string | number | Date;
+                to?: string | number | Date;
+                values?: (string | number)[];
+                modulus?: number;
+                remainder?: number;
+            };
+            tablespace?: string;
+            storageParameters?: Record<string, string | number>;
+        }[];
+    }): Promise<void>;
+    /**
+     * Create a partition for an existing partitioned table (PostgreSQL 10+)
+     * @param options - Partition creation options
+     */
+    createPartition(options: {
+        parentTable: string;
+        name: string;
+        bound?: {
+            from: string | number | Date;
+            to?: string | number | Date;
+            values?: (string | number)[];
+            modulus?: number;
+            remainder?: number;
+        };
+        tablespace?: string;
+        storageParameters?: Record<string, string | number>;
+    }): Promise<void>;
+    /**
+     * Attach a partition to a partitioned table (PostgreSQL 11+)
+     * @param options - Partition attachment options
+     */
+    attachPartition(options: {
+        parentTable: string;
+        partitionName: string;
+    }): Promise<void>;
+    /**
+     * Detach a partition from a partitioned table (PostgreSQL 11+)
+     * @param options - Partition detachment options
+     */
+    detachPartition(options: {
+        partitionName: string;
+        validate?: boolean;
+    }): Promise<void>;
+    /**
+     * Drop a partition (PostgreSQL 10+)
+     * @param partitionName - Name of the partition to drop
+     * @param options - Drop options
+     */
+    dropPartition(partitionName: string, options?: {
+        ifExists?: boolean;
+        cascade?: boolean;
+    }): Promise<void>;
+    /**
+     * Execute a raw SQL query
+     * @param sql - SQL query
+     * @param options - Query options
+     */
+    prormQuery(sql: string, options?: {
+        raw?: boolean;
+        replacements?: Record<string, any>;
+    }): Promise<any>;
+    /**
+     * Get the database version
+     */
+    getDatabaseVersion(): Promise<string>;
+    /**
+     * Build a WHERE clause from WhereOptions
+     */
+    private buildWhereClause;
+}
+/**
+ * Create a QueryInterface from a dialect
+ */
+export declare function createQueryInterface(dialect: Dialect): QueryInterface;

package/dist/migrations/seeder.d.ts

@@ -0,0 +1,167 @@
+/**
+ * Seeder System - Manages database seed data
+ * Provides a way to populate a database with initial or test data
+ */
+import { EventEmitter } from 'events';
+/**
+ * Definition of a seeder - up populates data, down removes it
+ */
+export interface SeederDefinition {
+    up(queryInterface: any, prorm: any): Promise<void>;
+    down(queryInterface: any, prorm: any): Promise<void>;
+    /**
+     * Optional environment scoping. When set, the seeder is only eligible to
+     * run when the environment passed to runSeeders() (or NODE_ENV) matches
+     * one of these values. Seeders without this field always run, regardless
+     * of environment - this keeps plain reference-data seeders "production
+     * safe" by default while letting dev-only fixtures opt in to scoping.
+     */
+    env?: string | string[];
+}
+/**
+ * Options accepted by SeederRunner#runSeeders
+ */
+export interface RunSeedersOptions {
+    /**
+     * When set, only the seeder with this name (basename without extension)
+     * is considered, instead of every pending seeder. Still respects the
+     * "already executed" idempotency check unless `force` is set.
+     */
+    only?: string;
+    /**
+     * When set, seeders whose `env` field is defined and does not include
+     * this value are skipped (left pending, not recorded as executed).
+     * Seeders with no `env` field always run.
+     */
+    env?: string;
+    /**
+     * Re-run a seeder even if it's already recorded as executed. Only takes
+     * effect together with `only`, to avoid accidentally re-seeding
+     * everything.
+     */
+    force?: boolean;
+}
+/**
+ * Options for the SeederRunner
+ */
+export interface SeederOptions {
+    /**
+     * Path to seeder files directory
+     */
+    seedersPath?: string;
+    /**
+     * Table name to track executed seeders (default: 'PrormData')
+     */
+    seedsTableName?: string;
+    /**
+     * File pattern to match seeder files
+     */
+    pattern?: RegExp;
+    /**
+     * The current environment used to scope env-specific seeders. When not
+     * provided, it falls back to `process.env.NODE_ENV`. A seeder that declares
+     * an `env` only runs when it equals this value; if neither is resolvable,
+     * env-scoped seeders are skipped entirely.
+     */
+    env?: string;
+}
+/**
+ * Status record for a single seeder
+ */
+export interface SeedStatus {
+    name: string;
+    status: 'pending' | 'executed';
+    executedAt?: Date;
+}
+/**
+ * Helper to create a seeder with full type safety
+ */
+export declare function createSeeder(definition: SeederDefinition): SeederDefinition;
+/**
+ * SeederRunner manages the lifecycle of database seeders
+ */
+export declare class SeederRunner extends EventEmitter {
+    private prorm;
+    private options;
+    private tableName;
+    private seedersPath;
+    private pattern;
+    constructor(prorm: any, options?: SeederOptions);
+    /**
+     * Get the dialect instance from the prorm object.
+     * Supports both the custom ORM (getDialectInstance) and a plain query wrapper.
+     */
+    private getDialect;
+    /**
+     * Execute a raw SQL query via the prorm/dialect instance
+     */
+    private rawQuery;
+    /**
+     * Escape an identifier using the dialect, or fall back to simple quoting
+     */
+    private escapeId;
+    /**
+     * Escape a literal value using the dialect so it can be inlined directly into
+     * SQL. Inlining avoids relying on a specific bind-placeholder style (`?`,
+     * `$1`, `:name`), which differs between dialects — Postgres-family dialects,
+     * for example, do not understand `?` — and keeps the tracking/seeder SQL
+     * portable across every dialect.
+     */
+    private escapeVal;
+    /**
+     * Resolve the current environment used for env-scoped seeders.
+     * Prefers the explicit option, then NODE_ENV; otherwise undefined.
+     */
+    private resolveEnv;
+    /**
+     * Ensure the PrormData tracking table exists
+     */
+    ensureSeedsTable(): Promise<void>;
+    /**
+     * Check whether the tracking table exists
+     */
+    private tableExists;
+    /**
+     * Return names of all seeders that have already been executed
+     */
+    getExecutedSeeds(): Promise<string[]>;
+    /**
+     * Discover all seeder files in the seeders path, sorted by name
+     */
+    private discoverSeederFiles;
+    /**
+     * Load a seeder module from disk
+     */
+    private loadSeeder;
+    /**
+     * Build the query interface object passed to seeder functions.
+     * This mirrors the shape that seeder authors expect.
+     */
+    private buildQueryInterface;
+    /**
+     * Run all pending seeders (or a single one, via `options.only`). Returns
+     * the names of seeders that were executed.
+     *
+     * Seeders are discovered in sorted filename order (see
+     * discoverSeederFiles) and run strictly one after another. If a seeder's
+     * up() throws, the error propagates immediately: seeders already recorded
+     * in this call remain recorded (their tracking rows were only inserted
+     * after up() resolved successfully), the failing seeder is NOT recorded
+     * as executed, and no further seeders in the batch are attempted. Re-running
+     * runSeeders() afterwards will retry the failed seeder and any that never
+     * got a chance to run.
+     */
+    runSeeders(seedersPath?: string, options?: RunSeedersOptions): Promise<string[]>;
+    /**
+     * Undo a specific seeder, or the most recently executed one if no name given
+     */
+    undoSeeder(seederName?: string): Promise<void>;
+    /**
+     * Undo all executed seeders in reverse order
+     */
+    undoAllSeeders(): Promise<void>;
+    /**
+     * Return the status of all seed files (both pending and executed)
+     */
+    getSeedStatus(): Promise<SeedStatus[]>;
+}