@chidchanun/bcp 0.2.1 → 0.2.3

package/docs/database.md

@@ -1,18 +1,24 @@
 # Database
 
-BCP `0.1.14` adds the first framework-native database API through the server-only `bcp/database` entrypoint.
+BCP `0.2.3` completes Database Platform v2 behind 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.
+The public database facade is provider-neutral and currently includes built-in adapters for:
 
-## Create an app with MySQL
+- MySQL,
+- PostgreSQL,
+- SQLite.
+
+Applications can keep the same `db.query()`, `db.execute()`, `db.transaction()` and lifecycle API while selecting the provider through environment or explicit options.
+
+## MySQL
+
+Install the optional driver:
 
 ```bash
-npx create-bcp-app my-app
+npm install mysql2
 ```
 
-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
+Environment:
 
 ```env
 DB_DRIVER=mysql
@@ -22,20 +28,105 @@ 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.
+MySQL remains the default when no provider can be inferred.
 
-## Query
+Parameterized query:
 
 ```ts
 import {
     db,
 } from "bcp/database";
 
+const users =
+    await db.query(
+        "SELECT id, email FROM users WHERE active = ?",
+        [
+            1,
+        ]
+    );
+```
+
+## PostgreSQL
+
+Install the optional driver:
+
+```bash
+npm install pg
+```
+
+BCP can infer PostgreSQL from a connection URL:
+
+```env
+DATABASE_URL=postgresql://postgres:password@localhost:5432/bcp_app
+```
+
+or use explicit fields:
+
+```env
+DB_DRIVER=postgresql
+DB_HOST=localhost
+DB_PORT=5432
+DB_USER=postgres
+DB_PASSWORD=password
+DB_NAME=bcp_app
+```
+
+PostgreSQL parameters use `$1`, `$2`, and later placeholders:
+
+```ts
+const users =
+    await db.query(
+        "SELECT id, email FROM users WHERE active = $1",
+        [
+            true,
+        ]
+    );
+```
+
+`postgres` and `pg` are accepted as environment aliases for the PostgreSQL driver and are normalized to `postgresql`.
+
+## SQLite
+
+Install the optional driver:
+
+```bash
+npm install better-sqlite3
+```
+
+Recommended environment:
+
+```env
+DB_DRIVER=sqlite
+DATABASE_URL=./data/bcp.sqlite
+```
+
+BCP also recognizes `:memory:`, `sqlite:` / `file:` URLs and common `.sqlite`, `.sqlite3`, and `.db` file names.
+
+Example:
+
+```ts
+import {
+    createDatabase,
+} from "bcp/database";
+
+const database =
+    createDatabase({
+        driver:
+            "sqlite",
+        database:
+            "./data/app.sqlite",
+    });
+```
+
+SQLite operations are serialized by the built-in adapter so async transaction callbacks cannot interleave unrelated queries on the same native connection.
+
+## Query and execute
+
+`query<T>()` is intended for row-returning statements:
+
+```ts
 interface UserRow {
     id: number;
     email: string;
@@ -43,28 +134,27 @@ interface UserRow {
 
 const users =
     await db.query<UserRow[]>(
-        "SELECT id, email FROM users WHERE active = ?",
-        [
-            1,
-        ]
+        "SELECT id, email FROM users"
     );
 ```
 
-## Execute
+`execute<T>()` is intended for mutations and DDL:
 
 ```ts
 const result =
     await db.execute(
-        "INSERT INTO users (email) VALUES (?)",
+        "DELETE FROM sessions WHERE expired_at < ?",
         [
-            "user@example.com",
+            new Date(),
         ]
     );
 ```
 
-Use placeholders and parameter arrays instead of concatenating untrusted values into SQL strings.
+Use the placeholder syntax of the active database provider. BCP does not rewrite application SQL between dialects.
 
-## Transaction
+## Transactions
+
+The transaction callback receives a provider-scoped `TransactionDatabase`:
 
 ```ts
 await db.transaction(
@@ -88,7 +178,33 @@ await db.transaction(
 );
 ```
 
-BCP commits the transaction when the callback resolves and rolls it back when the callback throws.
+The example above uses MySQL/SQLite placeholders. PostgreSQL migrations and application statements should use `$1`, `$2`, and so on.
+
+BCP commits when the callback resolves and rolls back when it throws.
+
+## Connection lifecycle
+
+Database instances remain lazy by default. Importing `bcp/database` does not connect to a provider.
+
+BCP `0.2.3` adds explicit lifecycle methods:
+
+```ts
+await db.connect();
+
+// application work
+
+await db.disconnect();
+```
+
+`close()` remains available as the backward-compatible shutdown method and is equivalent to `disconnect()`:
+
+```ts
+await db.close();
+```
+
+After disconnecting, the next operation or `connect()` call creates a fresh adapter connection/pool.
+
+If adapter initialization fails, BCP resets the pending lifecycle state so a later attempt can retry cleanly. Calling `close()` after a failed initialization is safe.
 
 ## Custom database instance
 
@@ -99,6 +215,8 @@ import {
 
 export const reportingDb =
     createDatabase({
+        driver:
+            "postgresql",
         host:
             "reporting-db.internal",
         database:
@@ -110,18 +228,69 @@ export const reportingDb =
 
 Explicit options override environment values for that database instance.
 
-## Lifecycle
+## Database adapter contract
 
-Connections are lazy. Importing `bcp/database` does not open a MySQL connection. The pool is created on the first `query`, `execute` or `transaction` call.
+Provider implementations use the shared adapter contract:
+
+```ts
+import type {
+    DatabaseAdapter,
+    TransactionDatabase,
+} from "bcp/database";
 
-For custom shutdown handling, close the pool with:
+const adapter: DatabaseAdapter = {
+    driver: "custom",
+
+    async connect() {},
+
+    async query<T>(sql, parameters) {
+        throw new Error("Not implemented");
+    },
+
+    async execute<T>(sql, parameters) {
+        throw new Error("Not implemented");
+    },
+
+    async transaction<T>(
+        callback: (
+            database: TransactionDatabase
+        ) => Promise<T>
+    ) {
+        throw new Error("Not implemented");
+    },
+
+    async disconnect() {},
+};
+```
+
+Inject an adapter directly or through a lazy factory:
 
 ```ts
-await db.close();
+export const customDb =
+    createDatabase({
+        adapter: () => adapter,
+    });
+```
+
+The contract lets future providers integrate without changing application-facing database calls.
+
+## Migrations
+
+Framework migration bookkeeping supports MySQL, PostgreSQL and SQLite in `0.2.3`.
+
+```bash
+bcp db create create_users
+bcp db migrate
+bcp db status
+bcp db rollback
 ```
 
+BCP selects the internal migration-table dialect from the same active database environment. Migration files themselves remain normal provider SQL and are not automatically translated between SQL dialects.
+
+Read more: [Database Migrations](database-migrations.md)
+
 ## 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.
+`bcp/database` is a server-only package export. Importing it into a browser bundle is blocked by the framework 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.
+Provider drivers are optional and loaded lazily. Projects only need to install the driver they actually use.

package/docs/docs-web-manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "versionTarget": "0.2.1",
+  "versionTarget": "0.2.3",
   "releaseState": "unreleased",
   "sections": [
     {
@@ -11,6 +11,7 @@
       "pages": [
         { "route": "/docs/getting-started", "source": "getting-started.md", "title": "Getting Started" },
         { "route": "/docs/configuration", "source": "configuration.md", "title": "Configuration" },
+        { "route": "/docs/environment-validation", "source": "environment-validation.md", "title": "Environment Validation" },
         { "route": "/docs/application-modules", "source": "application-modules.md", "title": "Application Modules" },
         { "route": "/docs/project-metadata", "source": "project-metadata.md", "title": "Project Metadata" },
         { "route": "/docs/deployment", "source": "deployment.md", "title": "Deployment" },
@@ -44,7 +45,7 @@
     {
       "id": "database",
       "title": "Database",
-      "description": "Database primitives, transactions and migration workflows.",
+      "description": "Provider-neutral MySQL, PostgreSQL and SQLite primitives, lifecycle and migrations.",
       "pages": [
         { "route": "/docs/database", "source": "database.md", "title": "Database" },
         { "route": "/docs/database-migrations", "source": "database-migrations.md", "title": "Database Migrations" }
@@ -103,7 +104,9 @@
     }
   ],
   "releases": [
-    { "route": "/releases/0.2.1", "source": "releases/0.2.1.md", "version": "0.2.1", "state": "unreleased" },
+    { "route": "/releases/0.2.3", "source": "releases/0.2.3.md", "version": "0.2.3", "state": "unreleased" },
+    { "route": "/releases/0.2.2", "source": "releases/0.2.2.md", "version": "0.2.2" },
+    { "route": "/releases/0.2.1", "source": "releases/0.2.1.md", "version": "0.2.1" },
     { "route": "/releases/0.2.0", "source": "releases/0.2.0.md", "version": "0.2.0" },
     { "route": "/releases/0.1.29", "source": "releases/0.1.29.md", "version": "0.1.29" },
     { "route": "/releases/0.1.28", "source": "releases/0.1.28.md", "version": "0.1.28" },

package/docs/environment-validation.md

@@ -0,0 +1,224 @@
+# Environment Validation
+
+BCP Framework `0.2.2` adds an optional typed environment schema for application-specific environment variables.
+
+The schema is separate from `bcp.config.*` and uses the project convention:
+
+```text
+bcp.environment.ts
+bcp.environment.mts
+bcp.environment.js
+bcp.environment.mjs
+```
+
+Keep only one environment schema file in an application.
+
+## Define a schema
+
+```ts
+import {
+    defineEnvironment,
+} from "bcp/config";
+
+export default defineEnvironment({
+    DB_HOST: {
+        type: "string",
+        required: true,
+    },
+
+    DB_PORT: {
+        type: "number",
+        default: 3306,
+        min: 1,
+        max: 65535,
+    },
+
+    SESSION_SECRET: {
+        type: "string",
+        required: true,
+        secret: true,
+        minLength: 32,
+    },
+
+    FEATURE_ENABLED: {
+        type: "boolean",
+        default: false,
+    },
+
+    BCP_PUBLIC_API_URL: {
+        type: "url",
+        required: true,
+    },
+});
+```
+
+Supported types:
+
+```text
+string
+number
+boolean
+url
+```
+
+Supported rule fields:
+
+```text
+type
+required
+secret
+minLength
+maxLength
+min
+max
+default
+description
+```
+
+`minLength` / `maxLength` are intended for string and URL values. `min` / `max` are intended for numbers.
+
+## Validate from the CLI
+
+```bash
+bcp config check
+```
+
+On Windows where another `bcp.exe` may exist:
+
+```powershell
+npm exec -- bcp-framework config check
+```
+
+JSON output:
+
+```powershell
+npm exec -- bcp-framework config check --json
+```
+
+The command validates:
+
+- `bcp.config.*`,
+- `bcp.environment.*`,
+- loaded `.env` files,
+- configured BCP runtime values,
+- application environment-schema values,
+- selected production safety diagnostics.
+
+Development is the default mode.
+
+To inspect production diagnostics from a shell where `NODE_ENV` can be set:
+
+```bash
+NODE_ENV=production bcp config check
+```
+
+PowerShell example:
+
+```powershell
+$env:NODE_ENV = "production"
+npm exec -- bcp-framework config check
+Remove-Item Env:NODE_ENV
+```
+
+## Startup validation
+
+When a project contains `bcp.environment.*`, `bcp dev` and `bcp build` validate the schema before the application starts or a production build is produced.
+
+A missing or invalid required environment variable stops startup/build with a configuration error.
+
+Example:
+
+```text
+BCP Configuration Error:
+- SESSION_SECRET must contain at least 32 character(s).
+```
+
+Changing `bcp.environment.*` while the development supervisor is running automatically restarts the dev worker, the same way changes to `.env*` or `bcp.config.*` do.
+
+## Public variables and secrets
+
+Variables beginning with:
+
+```text
+BCP_PUBLIC_
+```
+
+can be embedded into browser bundles.
+
+Do not use that prefix for credentials, session secrets, access keys or private service tokens.
+
+BCP treats this as an error:
+
+```ts
+export default defineEnvironment({
+    BCP_PUBLIC_TOKEN: {
+        type: "string",
+        required: true,
+        secret: true,
+    },
+});
+```
+
+The `secret: true` flag is metadata used by validation/tooling. It does not encrypt the environment value. Secrets must still be stored in an appropriate environment/secret manager and kept out of public client variables.
+
+## Programmatic validation
+
+The same primitives are public through `bcp/config`:
+
+```ts
+import {
+    defineEnvironment,
+    validateEnvironment,
+} from "bcp/config";
+
+const schema = defineEnvironment({
+    API_URL: {
+        type: "url",
+        required: true,
+    },
+});
+
+const result = validateEnvironment(
+    schema,
+    process.env
+);
+
+if (!result.ok) {
+    console.error(
+        result.issues
+    );
+}
+```
+
+The parsed `result.values` contains only keys declared by the schema. BCP configuration diagnostics do not print raw secret values.
+
+## Production diagnostics
+
+Production configuration checks can emit warnings for potentially risky choices such as:
+
+- production source maps enabled,
+- `security.poweredByHeader` enabled,
+- Content-Security-Policy disabled,
+- trusted proxy mode enabled.
+
+Warnings do not block a build. Environment-schema errors do.
+
+Trusted proxy warnings are informational safety reminders. Enable `BCP_TRUST_PROXY` only when untrusted clients cannot bypass the trusted reverse proxy/load balancer.
+
+## Existing applications
+
+Environment schemas are optional.
+
+Projects without `bcp.environment.*` continue to use the existing `.env` loading and BCP configuration behavior. The `0.2.2` schema system is additive and does not change the established configuration precedence:
+
+```text
+CLI override
+    ↓
+BCP_* environment
+    ↓
+bcp.config.*
+    ↓
+framework defaults
+```
+
+Application-specific variables are validated against `bcp.environment.*` after environment files are loaded.

package/docs/platform-manifest.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "releaseState": "unreleased",
-  "baseline": "framework-platform",
+  "baseline": "database-platform-v2",
   "runtime": {
     "node": ">=24.11.0",
     "react": "19",
@@ -30,6 +30,7 @@
     "update",
     "db",
     "generate",
+    "config",
     "doctor",
     "inspect",
     "help",
@@ -45,6 +46,11 @@
     "middlewareV2": true,
     "jwtCookieSessions": true,
     "databaseMigrations": true,
+    "databaseAdapterContract": true,
+    "databasePostgresql": true,
+    "databaseSqlite": true,
+    "databaseLifecycleV2": true,
+    "databaseMigrationProviderConsistency": true,
     "validation": true,
     "structuredErrors": true,
     "logging": true,
@@ -55,8 +61,16 @@
     "projectGenerators": true,
     "projectDiagnostics": true,
     "documentationPlatform": true,
-    "apiManifest": true
+    "apiManifest": true,
+    "typedEnvironmentSchema": true,
+    "configurationDiagnostics": true,
+    "configCheckCli": true
   },
+  "databaseProviders": [
+    "mysql",
+    "postgresql",
+    "sqlite"
+  ],
   "storageProviders": [
     "local",
     "amazon-s3",
@@ -64,7 +78,7 @@
     "s3-compatible"
   ],
   "compatibility": {
-    "previousBaseline": "0.2.0",
+    "previousBaseline": "0.2.2",
     "intentionalBreakingChangesFromPreviousBaseline": false,
     "migrationGuide": "migration-0.2.md"
   },
@@ -75,7 +89,8 @@
     "platformContract": "platform-contract.md",
     "documentationPlatform": "documentation-platform.md",
     "apiReference": "api-reference.md",
+    "environmentValidation": "environment-validation.md",
     "migrationGuide": "migration-0.2.md",
-    "releaseNotes": "releases/0.2.1.md"
+    "releaseNotes": "releases/0.2.3.md"
   }
 }