@noego/proper 0.1.0 → 0.2.0

package/bin/index.d.mts

@@ -6,6 +6,14 @@ interface MigrationConfig {
     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;
@@ -202,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;
 }
@@ -219,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[]>;
@@ -237,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[]>;
@@ -278,4 +352,108 @@ type SeedFactory = {
 };
 declare function createSeedFactory(options: SeedFactoryOptions): SeedFactory;
 
-export { type ISQLRunner, type MigrationConfig, MySQLMigrationRunner as MigrationRunner, MigrationRunnerFactory, type PgQueryable, PgRunner, SQLRunner, SQLiteRunner, 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 };

package/bin/index.d.ts

@@ -6,6 +6,14 @@ interface MigrationConfig {
     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;
@@ -202,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;
 }
@@ -219,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[]>;
@@ -237,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[]>;
@@ -278,4 +352,108 @@ type SeedFactory = {
 };
 declare function createSeedFactory(options: SeedFactoryOptions): SeedFactory;
 
-export { type ISQLRunner, type MigrationConfig, MySQLMigrationRunner as MigrationRunner, MigrationRunnerFactory, type PgQueryable, PgRunner, SQLRunner, SQLiteRunner, 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 };