@chidchanun/bcp 0.2.1 → 0.2.3

package/packages/cli/src/database-migrations.ts

@@ -4,8 +4,10 @@ import {
     pathToFileURL,
 } from "node:url";
 
-import type {
-    TransactionDatabase,
+import {
+    resolveDatabaseOptions,
+    type DatabaseDriver,
+    type TransactionDatabase,
 } from "../../client/src/database.js";
 
 export type DatabaseMigrationAction =
@@ -35,6 +37,7 @@ export interface DatabaseMigrationCommandOptions {
     action: DatabaseMigrationAction;
     name?: string;
     database?: MigrationDatabase;
+    driver?: DatabaseDriver;
     now?: Date;
 }
 
@@ -65,6 +68,12 @@ interface MigrationModule {
     ) => Promise<void> | void;
 }
 
+interface MigrationDialect {
+    createTableSql: string;
+    insertMigrationSql: string;
+    deleteMigrationSql: string;
+}
+
 const MIGRATION_DIRECTORY =
     "migrations";
 const MIGRATION_TABLE =
@@ -105,8 +114,15 @@ export async function runDatabaseMigrationCommand(
         );
     }
 
+    const dialect =
+        getMigrationDialect(
+            options.driver ??
+            resolveDatabaseOptions().driver
+        );
+
     await ensureMigrationTable(
-        database
+        database,
+        dialect
     );
 
     if (
@@ -129,14 +145,16 @@ export async function runDatabaseMigrationCommand(
     ) {
         await migratePending(
             rootDirectory,
-            database
+            database,
+            dialect
         );
         return;
     }
 
     await rollbackLatestBatch(
         rootDirectory,
-        database
+        database,
+        dialect
     );
 }
 
@@ -197,13 +215,13 @@ export function createMigrationFile(
         `export async function up(\n` +
         `    db: TransactionDatabase\n` +
         `): Promise<void> {\n` +
-        `    // Write the forward migration here.\n` +
+        `    // Write provider-compatible forward SQL here.\n` +
         `    void db;\n` +
         `}\n\n` +
         `export async function down(\n` +
         `    db: TransactionDatabase\n` +
         `): Promise<void> {\n` +
-        `    // Write the rollback migration here.\n` +
+        `    // Write provider-compatible rollback SQL here.\n` +
         `    void db;\n` +
         `}\n`;
 
@@ -363,7 +381,8 @@ export async function getMigrationStatus(
 
 async function migratePending(
     rootDirectory: string,
-    database: MigrationDatabase
+    database: MigrationDatabase,
+    dialect: MigrationDialect
 ): Promise<void> {
     const files =
         listMigrationFiles(
@@ -421,11 +440,11 @@ async function migratePending(
 
         await database.transaction(
             async (transaction) => {
-                await module.up?.(
+                await module.up(
                     transaction
                 );
                 await transaction.execute(
-                    `INSERT INTO ${MIGRATION_TABLE} (name, batch) VALUES (?, ?)`,
+                    dialect.insertMigrationSql,
                     [
                         migration.name,
                         batch,
@@ -442,7 +461,8 @@ async function migratePending(
 
 async function rollbackLatestBatch(
     rootDirectory: string,
-    database: MigrationDatabase
+    database: MigrationDatabase,
+    dialect: MigrationDialect
 ): Promise<void> {
     const applied =
         await readAppliedMigrations(
@@ -520,11 +540,11 @@ async function rollbackLatestBatch(
 
         await database.transaction(
             async (transaction) => {
-                await module.down?.(
+                await module.down(
                     transaction
                 );
                 await transaction.execute(
-                    `DELETE FROM ${MIGRATION_TABLE} WHERE name = ?`,
+                    dialect.deleteMigrationSql,
                     [
                         record.name,
                     ]
@@ -539,15 +559,11 @@ async function rollbackLatestBatch(
 }
 
 async function ensureMigrationTable(
-    database: MigrationDatabase
+    database: MigrationDatabase,
+    dialect: MigrationDialect
 ): Promise<void> {
     await database.execute(
-        `CREATE TABLE IF NOT EXISTS ${MIGRATION_TABLE} (` +
-        `id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY, ` +
-        `name VARCHAR(255) NOT NULL UNIQUE, ` +
-        `batch INT UNSIGNED NOT NULL, ` +
-        `applied_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP` +
-        `) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4`
+        dialect.createTableSql
     );
 }
 
@@ -561,6 +577,60 @@ async function readAppliedMigrations(
     );
 }
 
+function getMigrationDialect(
+    driver: DatabaseDriver
+): MigrationDialect {
+    if (
+        driver === "postgresql"
+    ) {
+        return {
+            createTableSql:
+                `CREATE TABLE IF NOT EXISTS ${MIGRATION_TABLE} (` +
+                `id BIGSERIAL PRIMARY KEY, ` +
+                `name VARCHAR(255) NOT NULL UNIQUE, ` +
+                `batch INTEGER NOT NULL, ` +
+                `applied_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP` +
+                `)`,
+            insertMigrationSql:
+                `INSERT INTO ${MIGRATION_TABLE} (name, batch) VALUES ($1, $2)`,
+            deleteMigrationSql:
+                `DELETE FROM ${MIGRATION_TABLE} WHERE name = $1`,
+        };
+    }
+
+    if (
+        driver === "sqlite"
+    ) {
+        return {
+            createTableSql:
+                `CREATE TABLE IF NOT EXISTS ${MIGRATION_TABLE} (` +
+                `id INTEGER PRIMARY KEY AUTOINCREMENT, ` +
+                `name TEXT NOT NULL UNIQUE, ` +
+                `batch INTEGER NOT NULL, ` +
+                `applied_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP` +
+                `)`,
+            insertMigrationSql:
+                `INSERT INTO ${MIGRATION_TABLE} (name, batch) VALUES (?, ?)`,
+            deleteMigrationSql:
+                `DELETE FROM ${MIGRATION_TABLE} WHERE name = ?`,
+        };
+    }
+
+    return {
+        createTableSql:
+            `CREATE TABLE IF NOT EXISTS ${MIGRATION_TABLE} (` +
+            `id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY, ` +
+            `name VARCHAR(255) NOT NULL UNIQUE, ` +
+            `batch INT UNSIGNED NOT NULL, ` +
+            `applied_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP` +
+            `) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4`,
+        insertMigrationSql:
+            `INSERT INTO ${MIGRATION_TABLE} (name, batch) VALUES (?, ?)`,
+        deleteMigrationSql:
+            `DELETE FROM ${MIGRATION_TABLE} WHERE name = ?`,
+    };
+}
+
 async function loadMigrationModule(
     migration: LoadedMigration
 ): Promise<Required<MigrationModule>> {
@@ -595,7 +665,7 @@ async function loadMigrationModule(
             module.up,
         down:
             module.down,
-    };
+    } as Required<MigrationModule>;
 }
 
 function normalizeMigrationName(

package/packages/cli/src/index.ts

@@ -76,6 +76,11 @@ switch (cliOptions.command) {
     break;
   }
 
+  case "config": {
+    await runConfigCommand();
+    break;
+  }
+
   case "doctor": {
     await runDeveloperCommand(
       "doctor"
@@ -112,6 +117,24 @@ async function runDev() {
       cliOptions.rootDirectory
     );
 
+  const {
+    runStartupConfigurationDiagnostics,
+  } =
+    await import(
+      "./configuration.js"
+    );
+
+  await runStartupConfigurationDiagnostics(
+    rootDirectory,
+    "development",
+    {
+      port:
+        cliOptions.port,
+      hostname:
+        cliOptions.hostname,
+    }
+  );
+
   installApplicationModuleAlias(
     rootDirectory
   );
@@ -185,6 +208,24 @@ async function runBuild() {
       cliOptions.rootDirectory
     );
 
+  const {
+    runStartupConfigurationDiagnostics,
+  } =
+    await import(
+      "./configuration.js"
+    );
+
+  await runStartupConfigurationDiagnostics(
+    rootDirectory,
+    "production",
+    {
+      port:
+        cliOptions.port,
+      hostname:
+        cliOptions.hostname,
+    }
+  );
+
   const appDirectory =
     path.join(
       rootDirectory,
@@ -518,6 +559,36 @@ async function runGenerateCommand(): Promise<void> {
   });
 }
 
+async function runConfigCommand(): Promise<void> {
+  const action =
+    cliOptions.configAction;
+
+  if (
+    action === undefined ||
+    action === "help"
+  ) {
+    printConfigHelp();
+    return;
+  }
+
+  const rootDirectory =
+    resolveProjectRoot(
+      cliOptions.rootDirectory
+    );
+  const {
+    runConfigurationCheck,
+  } =
+    await import(
+      "./configuration.js"
+    );
+
+  await runConfigurationCheck({
+    rootDirectory,
+    json:
+      cliOptions.json,
+  });
+}
+
 async function runDeveloperCommand(
   command:
     "doctor" |
@@ -759,6 +830,32 @@ Examples:
 `);
 }
 
+function printConfigHelp() {
+  console.log(`
+BCP Configuration & Environment
+
+Usage:
+  bcp config <command> [options]
+
+Commands:
+  check               Validate bcp.config.*, bcp.environment.* and loaded environment values
+  help                Show configuration command help
+
+Options:
+  --root <path>        Project root directory
+  --json               Emit the configuration diagnostics report as JSON
+
+Environment mode:
+  NODE_ENV=production bcp config check
+  NODE_ENV=test bcp config check
+  bcp config check     (development by default)
+
+Examples:
+  bcp config check
+  bcp config check --json
+`);
+}
+
 function printHelp() {
   console.log(`
 BCP Framework v${FRAMEWORK_VERSION}
@@ -774,6 +871,7 @@ Commands:
   update [target]    Update BCP Framework (default target: latest)
   db <command>       Manage database migrations
   generate <kind>    Generate pages, API routes, middleware or migrations
+  config <command>   Validate project configuration and environment schema
   doctor             Run project/runtime health diagnostics
   inspect            Print resolved env, config, dependencies and routes
   help               Show this help message
@@ -786,7 +884,7 @@ Options:
   --host <host>         Alias for --hostname
   --check               Check for a BCP update without changing files
   --dry-run             Preview a BCP update without changing files
-  --json                JSON output for doctor/inspect
+  --json                JSON output for doctor/inspect/config
   --force               Replace existing generated scaffold files
   -h, --help            Show help
   -v, --version         Show version
@@ -803,6 +901,8 @@ Examples:
   bcp generate page dashboard/users
   bcp generate api users
   bcp generate middleware
+  bcp config check
+  bcp config check --json
   bcp doctor
   bcp doctor --json
   bcp inspect

package/packages/client/src/config.ts

@@ -16,3 +16,29 @@ export {
     type ResolveBcpConfigOverrides,
     type ResolvedBcpConfig,
 } from "../../config/src/index.js";
+
+export {
+    applyEnvironmentDefaults,
+    defineEnvironment,
+    validateEnvironment,
+    type BcpEnvironmentSchema,
+    type BcpEnvironmentValidationIssue,
+    type BcpEnvironmentValidationResult,
+    type BcpEnvironmentValueType,
+    type BcpEnvironmentVariableRule,
+} from "../../config/src/environment-schema.js";
+
+export {
+    getEnvironmentSchemaFileNames,
+    loadBcpEnvironmentSchema,
+    type LoadedBcpEnvironmentSchema,
+} from "../../config/src/environment-loader.js";
+
+export {
+    assertConfigurationDiagnostics,
+    diagnoseBcpConfiguration,
+    type BcpConfigurationDiagnostic,
+    type BcpConfigurationDiagnosticSeverity,
+    type BcpConfigurationDiagnosticsReport,
+    type DiagnoseBcpConfigurationOptions,
+} from "../../config/src/diagnostics.js";

package/packages/client/src/database-mysql.ts

@@ -0,0 +1,291 @@
+import type {
+    DatabaseAdapter,
+    DatabaseParameters,
+    ResolvedDatabaseOptions,
+    TransactionDatabase,
+} from "./database.js";
+
+interface MysqlExecutor {
+    query(
+        sql: string,
+        parameters?: DatabaseParameters
+    ): Promise<[unknown, unknown]>;
+    execute(
+        sql: string,
+        parameters?: DatabaseParameters
+    ): Promise<[unknown, unknown]>;
+}
+
+interface MysqlConnection extends MysqlExecutor {
+    beginTransaction(): Promise<void>;
+    commit(): Promise<void>;
+    rollback(): Promise<void>;
+    release(): void;
+}
+
+interface MysqlPool extends MysqlExecutor {
+    getConnection(): Promise<MysqlConnection>;
+    end(): Promise<void>;
+}
+
+interface MysqlModule {
+    createPool(
+        options: Record<string, unknown>
+    ): MysqlPool;
+}
+
+const MYSQL_MODULE_SPECIFIER =
+    "mysql2/promise";
+
+export function createMysqlDatabaseAdapter(
+    options: ResolvedDatabaseOptions
+): DatabaseAdapter {
+    return new MysqlDatabaseAdapter(
+        options
+    );
+}
+
+class MysqlDatabaseAdapter
+implements DatabaseAdapter {
+    readonly driver = "mysql";
+
+    private readonly options:
+        ResolvedDatabaseOptions;
+
+    private poolPromise:
+        Promise<MysqlPool> | null =
+        null;
+
+    constructor(
+        options: ResolvedDatabaseOptions
+    ) {
+        this.options =
+            options;
+    }
+
+    async connect(): Promise<void> {
+        if (!this.poolPromise) {
+            this.poolPromise =
+                createMysqlPool(
+                    this.options
+                );
+        }
+
+        await this.poolPromise;
+    }
+
+    async query<T = unknown>(
+        sql: string,
+        parameters?: DatabaseParameters
+    ): Promise<T> {
+        assertSql(
+            sql
+        );
+
+        const pool =
+            await this.getPool();
+        const [rows] =
+            await pool.query(
+                sql,
+                parameters
+            );
+
+        return rows as T;
+    }
+
+    async execute<T = unknown>(
+        sql: string,
+        parameters?: DatabaseParameters
+    ): Promise<T> {
+        assertSql(
+            sql
+        );
+
+        const pool =
+            await this.getPool();
+        const [result] =
+            await pool.execute(
+                sql,
+                parameters
+            );
+
+        return result as T;
+    }
+
+    async transaction<T>(
+        callback: (
+            database: TransactionDatabase
+        ) => Promise<T>
+    ): Promise<T> {
+        assertTransactionCallback(
+            callback
+        );
+
+        const pool =
+            await this.getPool();
+        const connection =
+            await pool.getConnection();
+
+        await connection.beginTransaction();
+
+        const transactionDatabase:
+            TransactionDatabase = {
+            query: async <R = unknown>(
+                sql: string,
+                parameters?: DatabaseParameters
+            ): Promise<R> => {
+                assertSql(
+                    sql
+                );
+
+                const [rows] =
+                    await connection.query(
+                        sql,
+                        parameters
+                    );
+
+                return rows as R;
+            },
+            execute: async <R = unknown>(
+                sql: string,
+                parameters?: DatabaseParameters
+            ): Promise<R> => {
+                assertSql(
+                    sql
+                );
+
+                const [result] =
+                    await connection.execute(
+                        sql,
+                        parameters
+                    );
+
+                return result as R;
+            },
+        };
+
+        try {
+            const result =
+                await callback(
+                    transactionDatabase
+                );
+
+            await connection.commit();
+
+            return result;
+        } catch (error) {
+            try {
+                await connection.rollback();
+            } catch {
+                // Preserve the original transaction error.
+            }
+
+            throw error;
+        } finally {
+            connection.release();
+        }
+    }
+
+    async disconnect(): Promise<void> {
+        const pendingPool =
+            this.poolPromise;
+
+        this.poolPromise =
+            null;
+
+        if (!pendingPool) {
+            return;
+        }
+
+        let pool:
+            MysqlPool;
+
+        try {
+            pool =
+                await pendingPool;
+        } catch {
+            return;
+        }
+
+        await pool.end();
+    }
+
+    private async getPool():
+        Promise<MysqlPool> {
+        await this.connect();
+
+        return this.poolPromise as
+            Promise<MysqlPool>;
+    }
+}
+
+async function createMysqlPool(
+    options: ResolvedDatabaseOptions
+): Promise<MysqlPool> {
+    let mysqlModule:
+        MysqlModule;
+
+    try {
+        mysqlModule =
+            await import(
+                MYSQL_MODULE_SPECIFIER
+            ) as unknown as MysqlModule;
+    } catch (error) {
+        throw new Error(
+            "BCP Database: MySQL requires the optional dependency mysql2. Install it with `npm install mysql2` or create the app with the MySQL preset.",
+            {
+                cause:
+                    error,
+            }
+        );
+    }
+
+    return mysqlModule.createPool({
+        host:
+            options.host,
+        port:
+            options.port,
+        user:
+            options.user,
+        password:
+            options.password,
+        database:
+            options.database,
+        waitForConnections:
+            options.waitForConnections,
+        connectionLimit:
+            options.connectionLimit,
+        queueLimit:
+            options.queueLimit,
+        charset:
+            options.charset,
+    });
+}
+
+function assertSql(
+    sql: string
+): void {
+    if (
+        typeof sql !== "string" ||
+        sql.trim() === ""
+    ) {
+        throw new TypeError(
+            "BCP Database: SQL must be a non-empty string."
+        );
+    }
+}
+
+function assertTransactionCallback(
+    callback: unknown
+): asserts callback is (
+    database: TransactionDatabase
+) => Promise<unknown> {
+    if (
+        typeof callback !==
+        "function"
+    ) {
+        throw new TypeError(
+            "BCP Database: transaction callback must be a function."
+        );
+    }
+}