@chidchanun/bcp 0.1.13 → 0.1.15

package/packages/cli/src/index.ts

@@ -66,6 +66,11 @@ switch (cliOptions.command) {
     break;
   }
 
+  case "db": {
+    await runDatabaseCommand();
+    break;
+  }
+
   case "help": {
     printHelp();
     break;
@@ -381,6 +386,86 @@ async function runUpdate() {
   });
 }
 
+async function runDatabaseCommand() {
+  const action =
+    cliOptions.dbAction;
+
+  if (
+    action === undefined ||
+    action === "help"
+  ) {
+    printDatabaseHelp();
+    return;
+  }
+
+  const rootDirectory =
+    resolveProjectRoot(
+      cliOptions.rootDirectory
+    );
+
+  process.env.NODE_ENV =
+    process.env.NODE_ENV ??
+    "development";
+
+  const {
+    loadEnvironment,
+  } =
+    await import(
+      "../../env/src/index.js"
+    );
+
+  const environment =
+    loadEnvironment(
+      rootDirectory,
+      "development"
+    );
+
+  if (
+    environment.files.length > 0
+  ) {
+    console.log(
+      `[BCP Env] development: ${environment.files.join(", ")}`
+    );
+  }
+
+  const {
+    runDatabaseMigrationCommand,
+  } =
+    await import(
+      "./database-migrations.js"
+    );
+
+  if (
+    action === "create"
+  ) {
+    await runDatabaseMigrationCommand({
+      rootDirectory,
+      action,
+      name:
+        cliOptions.dbMigrationName,
+    });
+    return;
+  }
+
+  const {
+    db,
+  } =
+    await import(
+      "../../client/src/database.js"
+    );
+
+  try {
+    await runDatabaseMigrationCommand({
+      rootDirectory,
+      action,
+      database:
+        db,
+    });
+  } finally {
+    await db.close();
+  }
+}
+
 function installShutdownHandlers(
   server: {
     stop(): Promise<void>;
@@ -521,6 +606,28 @@ function formatBytes(
   ).toFixed(2)} MiB`;
 }
 
+function printDatabaseHelp() {
+  console.log(`
+BCP Database Migrations
+
+Usage:
+  bcp db <command> [arguments]
+
+Commands:
+  create <name>       Create a timestamped migration in migrations/
+  migrate             Run all pending migrations
+  status              Show applied and pending migrations
+  rollback            Roll back the latest migration batch
+  help                Show database command help
+
+Examples:
+  bcp db create create_users
+  bcp db migrate
+  bcp db status
+  bcp db rollback
+`);
+}
+
 function printHelp() {
   console.log(`
 BCP Framework v${FRAMEWORK_VERSION}
@@ -534,6 +641,7 @@ Commands:
   start              Start the standalone production build
   routes             Print discovered page and API routes
   update [target]    Update BCP Framework (default target: latest)
+  db <command>       Manage database migrations
   help               Show this help message
   version            Show framework version
 
@@ -558,6 +666,9 @@ Examples:
   bcp routes
   bcp update
   bcp update --check
-  bcp update 0.1.10
+  bcp db create create_users
+  bcp db migrate
+  bcp db status
+  bcp db rollback
 `);
 }

package/packages/client/src/database.ts

@@ -0,0 +1,492 @@
+export type DatabaseDriver = "mysql";
+
+export interface DatabaseOptions {
+    driver?: DatabaseDriver;
+    host?: string;
+    port?: number;
+    user?: string;
+    password?: string;
+    database?: string;
+    connectionLimit?: number;
+    waitForConnections?: boolean;
+    queueLimit?: number;
+    charset?: string;
+}
+
+export type DatabaseParameters =
+    | readonly unknown[]
+    | Record<string, unknown>;
+
+export interface TransactionDatabase {
+    query<T = unknown>(
+        sql: string,
+        parameters?: DatabaseParameters
+    ): Promise<T>;
+    execute<T = unknown>(
+        sql: string,
+        parameters?: DatabaseParameters
+    ): Promise<T>;
+}
+
+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 class BcpDatabase {
+    private readonly options:
+        DatabaseOptions;
+
+    private poolPromise:
+        Promise<MysqlPool> | null =
+        null;
+
+    constructor(
+        options: DatabaseOptions = {}
+    ) {
+        this.options = {
+            ...options,
+        };
+    }
+
+    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> {
+        if (
+            typeof callback !==
+            "function"
+        ) {
+            throw new TypeError(
+                "BCP Database: transaction callback must be a function."
+            );
+        }
+
+        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 close(): Promise<void> {
+        const pendingPool =
+            this.poolPromise;
+
+        this.poolPromise =
+            null;
+
+        if (!pendingPool) {
+            return;
+        }
+
+        const pool =
+            await pendingPool;
+
+        await pool.end();
+    }
+
+    private getPool(): Promise<MysqlPool> {
+        if (!this.poolPromise) {
+            this.poolPromise =
+                createMysqlPool(
+                    resolveDatabaseOptions(
+                        this.options
+                    )
+                );
+        }
+
+        return this.poolPromise;
+    }
+}
+
+export function createDatabase(
+    options: DatabaseOptions = {}
+): BcpDatabase {
+    return new BcpDatabase(
+        options
+    );
+}
+
+export function resolveDatabaseOptions(
+    options: DatabaseOptions = {},
+    environment: NodeJS.ProcessEnv =
+        process.env
+): Required<DatabaseOptions> {
+    const driver =
+        options.driver ??
+        normalizeDriver(
+            environment.DB_DRIVER ??
+            "mysql"
+        );
+
+    if (
+        driver !== "mysql"
+    ) {
+        throw new Error(
+            `BCP Database: unsupported database driver "${driver}".`
+        );
+    }
+
+    return {
+        driver,
+        host:
+            nonEmpty(
+                options.host ??
+                environment.DB_HOST
+            ) ??
+            "localhost",
+        port:
+            resolvePositiveInteger(
+                options.port ??
+                environment.DB_PORT,
+                3306,
+                "DB_PORT"
+            ),
+        user:
+            nonEmpty(
+                options.user ??
+                environment.DB_USER
+            ) ??
+            "root",
+        password:
+            String(
+                options.password ??
+                environment.DB_PASSWORD ??
+                ""
+            ),
+        database:
+            nonEmpty(
+                options.database ??
+                environment.DB_NAME
+            ) ??
+            "bcp_app",
+        connectionLimit:
+            resolvePositiveInteger(
+                options.connectionLimit ??
+                environment.DB_CONNECTION_LIMIT,
+                10,
+                "DB_CONNECTION_LIMIT"
+            ),
+        waitForConnections:
+            options.waitForConnections ??
+            resolveBoolean(
+                environment.DB_WAIT_FOR_CONNECTIONS,
+                true,
+                "DB_WAIT_FOR_CONNECTIONS"
+            ),
+        queueLimit:
+            resolveNonNegativeInteger(
+                options.queueLimit ??
+                environment.DB_QUEUE_LIMIT,
+                0,
+                "DB_QUEUE_LIMIT"
+            ),
+        charset:
+            nonEmpty(
+                options.charset ??
+                environment.DB_CHARSET
+            ) ??
+            "utf8mb4",
+    };
+}
+
+export const db =
+    createDatabase();
+
+async function createMysqlPool(
+    options: Required<DatabaseOptions>
+): 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 normalizeDriver(
+    value: string
+): DatabaseDriver {
+    const normalized =
+        value
+            .trim()
+            .toLowerCase();
+
+    if (
+        normalized === "mysql"
+    ) {
+        return "mysql";
+    }
+
+    throw new Error(
+        `BCP Database: unsupported database driver "${value}".`
+    );
+}
+
+function nonEmpty(
+    value: unknown
+): string | null {
+    if (
+        typeof value !== "string"
+    ) {
+        return null;
+    }
+
+    const normalized =
+        value.trim();
+
+    return normalized ||
+        null;
+}
+
+function resolvePositiveInteger(
+    value: unknown,
+    fallback: number,
+    label: string
+): number {
+    if (
+        value === undefined ||
+        value === null ||
+        value === ""
+    ) {
+        return fallback;
+    }
+
+    const parsed =
+        Number(value);
+
+    if (
+        !Number.isInteger(parsed) ||
+        parsed <= 0
+    ) {
+        throw new Error(
+            `BCP Database: ${label} must be a positive integer.`
+        );
+    }
+
+    return parsed;
+}
+
+function resolveNonNegativeInteger(
+    value: unknown,
+    fallback: number,
+    label: string
+): number {
+    if (
+        value === undefined ||
+        value === null ||
+        value === ""
+    ) {
+        return fallback;
+    }
+
+    const parsed =
+        Number(value);
+
+    if (
+        !Number.isInteger(parsed) ||
+        parsed < 0
+    ) {
+        throw new Error(
+            `BCP Database: ${label} must be a non-negative integer.`
+        );
+    }
+
+    return parsed;
+}
+
+function resolveBoolean(
+    value: unknown,
+    fallback: boolean,
+    label: string
+): boolean {
+    if (
+        value === undefined ||
+        value === null ||
+        value === ""
+    ) {
+        return fallback;
+    }
+
+    if (
+        value === true ||
+        value === "1" ||
+        value === "true"
+    ) {
+        return true;
+    }
+
+    if (
+        value === false ||
+        value === "0" ||
+        value === "false"
+    ) {
+        return false;
+    }
+
+    throw new Error(
+        `BCP Database: ${label} must be true/false or 1/0.`
+    );
+}
+
+function assertSql(
+    sql: string
+): void {
+    if (
+        typeof sql !== "string" ||
+        sql.trim() === ""
+    ) {
+        throw new TypeError(
+            "BCP Database: SQL must be a non-empty string."
+        );
+    }
+}