@chidchanun/bcp 0.1.13 → 0.1.14

package/docs/database.md

@@ -0,0 +1,127 @@
+# Database
+
+BCP `0.1.14` adds the first framework-native database API through the server-only `bcp/database` entrypoint.
+
+The initial adapter targets MySQL. Additional adapters can be added in later releases without changing the page, loader, guard or action APIs that consume the database layer.
+
+## Create an app with MySQL
+
+```bash
+npx create-bcp-app my-app
+```
+
+Choose **MySQL** during interactive setup. The generated project installs `mysql2`, writes the database environment variables and creates `lib/database.ts` as a thin wrapper around `bcp/database`.
+
+## Environment
+
+```env
+DB_DRIVER=mysql
+DB_HOST=localhost
+DB_PORT=3306
+DB_USER=root
+DB_PASSWORD=
+DB_NAME=bcp_app
+DB_CONNECTION_LIMIT=10
+DB_WAIT_FOR_CONNECTIONS=1
+DB_QUEUE_LIMIT=0
+DB_CHARSET=utf8mb4
+```
+
+Only `DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD` and `DB_NAME` are required for the standard generated preset. The remaining values have safe framework defaults.
+
+## Query
+
+```ts
+import {
+    db,
+} from "bcp/database";
+
+interface UserRow {
+    id: number;
+    email: string;
+}
+
+const users =
+    await db.query<UserRow[]>(
+        "SELECT id, email FROM users WHERE active = ?",
+        [
+            1,
+        ]
+    );
+```
+
+## Execute
+
+```ts
+const result =
+    await db.execute(
+        "INSERT INTO users (email) VALUES (?)",
+        [
+            "user@example.com",
+        ]
+    );
+```
+
+Use placeholders and parameter arrays instead of concatenating untrusted values into SQL strings.
+
+## Transaction
+
+```ts
+await db.transaction(
+    async (transaction) => {
+        await transaction.execute(
+            "UPDATE accounts SET balance = balance - ? WHERE id = ?",
+            [
+                100,
+                1,
+            ]
+        );
+
+        await transaction.execute(
+            "UPDATE accounts SET balance = balance + ? WHERE id = ?",
+            [
+                100,
+                2,
+            ]
+        );
+    }
+);
+```
+
+BCP commits the transaction when the callback resolves and rolls it back when the callback throws.
+
+## Custom database instance
+
+```ts
+import {
+    createDatabase,
+} from "bcp/database";
+
+export const reportingDb =
+    createDatabase({
+        host:
+            "reporting-db.internal",
+        database:
+            "analytics",
+        connectionLimit:
+            5,
+    });
+```
+
+Explicit options override environment values for that database instance.
+
+## Lifecycle
+
+Connections are lazy. Importing `bcp/database` does not open a MySQL connection. The pool is created on the first `query`, `execute` or `transaction` call.
+
+For custom shutdown handling, close the pool with:
+
+```ts
+await db.close();
+```
+
+## Server-only boundary
+
+`bcp/database` is a server-only package export. Importing it into a browser bundle is blocked by the framework's browser export boundary.
+
+The MySQL adapter loads `mysql2/promise` only when a connection is first needed. Projects that do not use MySQL do not need to install the driver.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chidchanun/bcp",
-  "version": "0.1.13",
+  "version": "0.1.14",
   "description": "BCP Framework - a React full-stack framework with file-based routing, SSR, APIs, middleware, islands, caching and standalone production builds.",
   "type": "module",
   "license": "MIT",
@@ -43,6 +43,11 @@
       "types": "./packages/client/src/config.ts",
       "default": "./packages/client/src/config.ts"
     },
+    "./database": {
+      "types": "./packages/client/src/database.ts",
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/database.ts"
+    },
     "./server": {
       "types": "./packages/client/src/server.ts",
       "browser": "./packages/client/src/server-only.browser.mjs",

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."
+        );
+    }
+}