@noego/proper 0.0.9 → 0.2.0

package/bin/index.d.mts

@@ -1,10 +1,19 @@
 import mysql from 'mysql2/promise';
+import * as sqlite from 'sqlite';
 
 interface MigrationConfig {
     config_file?: string;
     migration_table: string;
     migration_folder: string;
     database: string;
+    /**
+     * Folder containing one-shot ledger patch files. Defaults to a `patches`
+     * sibling of `migration_folder` (e.g. `migrations` -> `patches`,
+     * `database/migrations` -> `database/patches`).
+     */
+    patch_folder?: string;
+    /** Table recording applied patches. Defaults to `proper_patches`. */
+    patch_table?: string;
     sql?: {
         host: string;
         user: string;
@@ -15,6 +24,20 @@ interface MigrationConfig {
     sqlite?: {
         database: string;
     };
+    /**
+     * PostgreSQL. Either a single `connectionString` (also readable from
+     * `process.env.DATABASE_URL` when omitted) or discrete fields.
+     * `password` falls back to `process.env.PG_PASSWORD`.
+     */
+    pg?: {
+        connectionString?: string;
+        host?: string;
+        user?: string;
+        database?: string;
+        password?: string;
+        port?: number;
+        ssl?: boolean | Record<string, unknown>;
+    };
     seeds?: {
         migrationsDir?: string;
         dataDir?: string;
@@ -31,6 +54,92 @@ interface ISQLRunner {
     execute(sql: string, params?: any[]): Promise<any>;
     end(): Promise<void>;
 }
+/**
+ * Base class that implements the common contract and helper utilities that are
+ * shared between the different dialect runners. The concrete subclasses only
+ * need to implement the three primitive methods `_query`, `_execute` and
+ * `_end` that perform the actual driver-specific interaction.  Everything else
+ * – such as ensuring a uniform return shape – is handled here once.
+ */
+declare abstract class BaseSQLRunner implements ISQLRunner {
+    abstract _query(sql: string, params?: any[]): Promise<any>;
+    abstract _execute(sql: string, params?: any[]): Promise<any>;
+    abstract _end(): Promise<void>;
+    /**
+     * Ensures that both MySQL and SQLite return the same tuple shape that callers
+     * expect: `[rowsOrResult, extra]`.  For SQLite there is no `extra` metadata
+     * comparable to MySQL's `FieldPacket[]`, so we just use `undefined`.
+     */
+    query(sql: string, params?: any[]): Promise<any>;
+    execute(sql: string, params?: any[]): Promise<any>;
+    end(): Promise<void>;
+}
+declare class SQLRunner extends BaseSQLRunner {
+    private connection;
+    constructor(connection: mysql.Connection);
+    _query(sql: string, params?: any[]): Promise<[mysql.OkPacket | mysql.RowDataPacket[] | mysql.ResultSetHeader[] | mysql.RowDataPacket[][] | mysql.OkPacket[] | mysql.ProcedureCallPacket, mysql.FieldPacket[]]>;
+    _execute(sql: string, params?: any[]): Promise<[mysql.OkPacket | mysql.RowDataPacket[] | mysql.ResultSetHeader[] | mysql.RowDataPacket[][] | mysql.OkPacket[] | mysql.ProcedureCallPacket, mysql.FieldPacket[]]>;
+    _end(): Promise<void>;
+}
+declare class SQLiteRunner extends BaseSQLRunner {
+    private connection;
+    constructor(connection: sqlite.Database | any);
+    private prepareStatement;
+    private finalizeStatement;
+    private statementAll;
+    private statementRun;
+    _query(sql: string, params?: any[]): Promise<any>;
+    _execute(sql: string, params?: any[]): Promise<any>;
+    /**
+     * Checks if SQL is empty or contains only comments/whitespace.
+     * Returns true if there is no actual SQL to execute.
+     */
+    private isEmptySQL;
+    private isMultiStatement;
+    private executeMultiStatement;
+    private removeComments;
+    _end(): Promise<void>;
+}
+/**
+ * Minimal structural type for a `pg` Client or Pool (or anything shaped like
+ * one, e.g. a Hyperdrive/Neon client). We only rely on `query()` and `end()`.
+ */
+interface PgQueryable {
+    query(text: string, values?: any[]): Promise<{
+        rows: any[];
+        rowCount: number | null;
+    }>;
+    end?(): Promise<void>;
+}
+/**
+ * PostgreSQL runner.
+ *
+ * Proper's internal bookkeeping statements use MySQL-style `?` placeholders;
+ * Postgres wants `$1..$n`, so parameterised statements are rewritten here.
+ * Migration files themselves are executed verbatim with no parameters — a
+ * parameter-less `query()` goes through the simple protocol, which allows
+ * multiple `;`-separated statements in one call, so no client-side splitting
+ * (as SQLite needs) is required.
+ */
+declare class PgRunner extends BaseSQLRunner {
+    private connection;
+    constructor(connection: PgQueryable);
+    /** `?` -> `$1`, `$2`, ... outside of string literals / comments. */
+    static toPositional(sql: string): string;
+    private run;
+    _query(sql: string, params?: any[]): Promise<(any[] | {
+        rows: any[];
+        rowCount: number | null;
+    })[]>;
+    _execute(sql: string, params?: any[]): Promise<({
+        rows: any[];
+        rowCount: number | null;
+    } | {
+        changes: number;
+        lastID: undefined;
+    })[]>;
+    _end(): Promise<void>;
+}
 
 declare abstract class MigrationNode {
     name: string;
@@ -76,10 +185,11 @@ declare class MigrationDirectoryReader {
     private read_strategy;
     private sqlrunner;
     private dialect;
-    constructor(directory: string, read_strategy: any, sqlrunner: ISQLRunner, dialect?: 'sql' | 'sqlite');
+    constructor(directory: string, read_strategy: any, sqlrunner: ISQLRunner, dialect?: 'sql' | 'sqlite' | 'pg');
     /**
      * Resolves the appropriate file for a migration based on dialect.
      * Priority: dialect-specific file > generic file
+     * File extensions: `.mysql.up.sql`, `.sqlite.up.sql`, `.pg.up.sql`.
      */
     private resolveFile;
     /**
@@ -100,13 +210,57 @@ declare class MigrationSetup {
     teardown(): Promise<void>;
 }
 
+type PatchOperation = {
+    verb: 'rename_migration';
+    from: string;
+    to: string;
+} | {
+    verb: 'mark_applied';
+    key: string;
+} | {
+    verb: 'unmark_applied';
+    key: string;
+};
+/** A parsed and schema-validated patch file. */
+interface PatchDocument {
+    /** Filename without `.yaml`. */
+    patchKey: string;
+    /** Basename including `.yaml`. */
+    fileName: string;
+    /** Absolute or config-relative resolved path. */
+    filePath: string;
+    /** SHA-256 hex over the exact UTF-8 file bytes. */
+    checksum: string;
+    version: number;
+    description: string;
+    operations: PatchOperation[];
+}
+interface PatchOperationResult {
+    verb: PatchOperation['verb'];
+    /** True when the operation mutated the ledger; false for a conditional no-op. */
+    changed: boolean;
+}
+interface PatchApplyResult {
+    patchKey: string;
+    fileName: string;
+    /**
+     * applied           - this process committed the patch
+     * already_applied   - a matching patch-history row already existed
+     */
+    status: 'applied' | 'already_applied';
+    operations: PatchOperationResult[];
+}
+/** Resolved patch settings with defaults applied. */
+declare function resolvePatchFolder(config: MigrationConfig): string;
+declare function resolvePatchTable(config: MigrationConfig): string;
+
 declare function loadMigrationConfig(configFile: string): MigrationConfig;
 declare class MigrationRunnerFactory {
     private static isSQLRunner;
     static create(configFile: string, conn?: any): Promise<MySQLMigrationRunner>;
     static createConnection(config: MigrationConfig): Promise<any>;
     static createEmpty(configFile: string): Promise<MySQLMigrationRunner>;
-    create(config: MigrationConfig, conn: any): Promise<MySQLMigrationRunner>;
+    create(config: MigrationConfig, conn: any, factoryOwnsConnection?: boolean): Promise<MySQLMigrationRunner>;
     createEmpty(config: MigrationConfig): Promise<MySQLMigrationRunner>;
     private getReadStategy;
 }
@@ -117,6 +271,8 @@ interface MigrationHistory {
 }
 interface IMigrationRunner {
     setup(): Promise<void>;
+    applyPendingPatches(): Promise<PatchApplyResult[]>;
+    createPatch(name: string): string;
     terminate(): Promise<void>;
     getMigrationsHistory(): Promise<MigrationHistory[]>;
     getMigrations(): Promise<MigrationNode[]>;
@@ -135,8 +291,28 @@ declare class MySQLMigrationRunner implements IMigrationRunner {
     private setupRunner;
     private sqlrunner;
     private connection;
-    constructor(config: MigrationConfig, directory: MigrationDirectoryReader, setupRunner: MigrationSetup, sqlrunner: ISQLRunner, connection: mysql.Connection);
+    private preflightEnabled;
+    /**
+     * Memoized in-flight preflight promise. Simultaneous or repeated calls
+     * to setup() on one runner execute the preflight (migration table setup
+     * + patch application) exactly once. Cleared after rejection so a caller
+     * may retry after fixing the cause.
+     */
+    private preflightPromise;
+    private lastPatchResults;
+    constructor(config: MigrationConfig, directory: MigrationDirectoryReader, setupRunner: MigrationSetup, sqlrunner: ISQLRunner, connection: mysql.Connection, preflightEnabled?: boolean);
     setup(): Promise<void>;
+    private runPreflight;
+    /**
+     * Delegates to the same idempotent preflight; returns the results of the
+     * patch pass that ran (or is running) for this runner.
+     */
+    applyPendingPatches(): Promise<PatchApplyResult[]>;
+    /**
+     * Scaffolds a new ledger patch file and returns the created path.
+     * Never connects to a database.
+     */
+    createPatch(name: string): string;
     terminate(): Promise<void>;
     getMigrationsHistory(): Promise<MigrationHistory[]>;
     getMigrations(): Promise<MigrationNode[]>;
@@ -176,4 +352,108 @@ type SeedFactory = {
 };
 declare function createSeedFactory(options: SeedFactoryOptions): SeedFactory;
 
-export { type MigrationConfig, MySQLMigrationRunner as MigrationRunner, MigrationRunnerFactory, type SeedContext, type SeedFactory, type SeedFactoryOptions, createSeedFactory, loadMigrationConfig, runSeedsWithRunner };
+/**
+ * Scaffolds a new patch file. Never connects to a database.
+ */
+declare class PatchCreator {
+    private patchFolder;
+    constructor(patchFolder: string);
+    /**
+     * Normalizes a patch name: trim, whitespace runs -> `_`, lowercase.
+     * Rejects empty results, path separators, `..`, control characters,
+     * characters outside [a-z0-9_-], and names longer than 120 characters.
+     */
+    static normalizeName(name: string): string;
+    /**
+     * Creates `<patch_folder>/<stamp>_<normalized_name>.yaml` with exclusive
+     * file creation. On a millisecond-stamp collision, mints a later stamp
+     * and retries. Returns the created path.
+     */
+    create(name: string): string;
+}
+
+/**
+ * Applies pending ledger patches. Uses ISQLRunner directly (never the public
+ * runner methods) so it can run inside the runner's preflight without
+ * recursion.
+ *
+ * Precondition: the provided connection must not already be inside an
+ * application-managed transaction when preflight begins; Proper will issue
+ * its own BEGIN/COMMIT/ROLLBACK per patch and must not commit or roll back a
+ * caller's outer transaction.
+ */
+declare class PatchRunner {
+    private sqlrunner;
+    private config;
+    private patchTable;
+    private migrationTable;
+    private dialect;
+    constructor(sqlrunner: ISQLRunner, config: MigrationConfig);
+    /**
+     * Discovers, validates, and applies every unapplied patch in order.
+     * Each unapplied patch is its own transaction; earlier committed patches
+     * remain committed if a later patch fails.
+     */
+    applyPending(): Promise<PatchApplyResult[]>;
+    private loadHistory;
+    private beginSql;
+    private begin;
+    private rollbackQuietly;
+    private applyOne;
+    private findCommittedRow;
+    private countRows;
+    private conflict;
+    private applyOperation;
+}
+
+/**
+ * Base class for all migration-related errors
+ */
+declare class MigrationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Base class for all patch-related errors.
+ */
+declare class PatchError extends MigrationError {
+    readonly patchFile?: string | undefined;
+    readonly patchKey?: string | undefined;
+    constructor(message: string, patchFile?: string | undefined, patchKey?: string | undefined);
+}
+/**
+ * A patch file failed YAML parsing or schema/plan validation.
+ */
+declare class PatchValidationError extends PatchError {
+    constructor(message: string, patchFile?: string, patchKey?: string);
+}
+/**
+ * An applied patch's file is missing or its content no longer matches the
+ * checksum recorded at application time.
+ */
+declare class PatchIntegrityError extends PatchError {
+    readonly expectedChecksum?: string | undefined;
+    readonly actualChecksum?: string | undefined;
+    constructor(message: string, patchFile?: string, patchKey?: string, expectedChecksum?: string | undefined, actualChecksum?: string | undefined);
+}
+/**
+ * An operation precondition failed: ledger conflict or corruption
+ * (unexpected row counts) at the operation's turn.
+ */
+declare class PatchConflictError extends PatchError {
+    readonly operationIndex?: number | undefined;
+    readonly operationVerb?: string | undefined;
+    readonly migrationKeys?: string[] | undefined;
+    readonly observedRowCounts?: Record<string, number> | undefined;
+    constructor(message: string, patchFile?: string, patchKey?: string, operationIndex?: number | undefined, operationVerb?: string | undefined, migrationKeys?: string[] | undefined, observedRowCounts?: Record<string, number> | undefined);
+}
+/**
+ * A database/transaction failure while applying a patch.
+ */
+declare class PatchExecutionError extends PatchError {
+    readonly operationIndex?: number | undefined;
+    readonly operationVerb?: string | undefined;
+    readonly originalError?: Error | undefined;
+    constructor(message: string, patchFile?: string, patchKey?: string, operationIndex?: number | undefined, operationVerb?: string | undefined, originalError?: Error | undefined);
+}
+
+export { type ISQLRunner, type MigrationConfig, MigrationError, MySQLMigrationRunner as MigrationRunner, MigrationRunnerFactory, type PatchApplyResult, PatchConflictError, PatchCreator, type PatchDocument, PatchError, PatchExecutionError, PatchIntegrityError, type PatchOperation, type PatchOperationResult, PatchRunner, PatchValidationError, type PgQueryable, PgRunner, SQLRunner, SQLiteRunner, type SeedContext, type SeedFactory, type SeedFactoryOptions, createSeedFactory, loadMigrationConfig, resolvePatchFolder, resolvePatchTable, runSeedsWithRunner };