@chidchanun/bcp 0.1.25 → 0.1.26

package/README.md

@@ -1,19 +1,19 @@
 # BCP Framework
 
-BCP Framework is a React full-stack framework focused on file-based routing, server rendering, server-side data loading, guarded application flows, API routes, authentication, database access, validation, logging, file uploads, storage adapters and standalone production deployment.
+BCP Framework is a React full-stack framework focused on file-based routing, SSR, server data loading, guarded application flows, API routes, authentication, database access, validation, logging, uploads, storage adapters and standalone production deployment.
 
-> **Development target:** `0.1.25`
+> **Release candidate target:** `0.1.26`
 >
-> BCP is still pre-1.0. Features documented for the current development target should not be presented as published npm behavior until the release candidate has passed and the matching version has been published.
+> BCP is pre-1.0. The `0.1.26` source is complete for RC validation, but it must not be presented as a published npm release until the full release checks pass and the matching packages are published.
 
 ## Overview
 
-BCP provides a single application model for React pages and server code:
+BCP keeps React pages and their server behavior close to the route that owns them:
 
 ```text
 Browser
   ↓
-BCP middleware / security
+BCP security / middleware / cache
   ↓
 Route guard
   ↓
@@ -24,7 +24,7 @@ React SSR
 Hydration / SPA navigation
 ```
 
-The framework is designed so application code can stay close to the route that owns it:
+A typical route can colocate its page, loader, guard and actions:
 
 ```text
 app/
@@ -57,8 +57,8 @@ app/
 | Error handling | HTTP error helpers and consistent error responses |
 | Database | MySQL pool/query helpers, transactions and migrations |
 | Logging | Structured logger, request logger and request IDs |
-| Uploads | Multipart parsing, file validation and safe local persistence |
-| Storage | `StorageAdapter`, local storage adapter and file delivery |
+| Uploads | Buffered multipart helpers and production multipart streaming |
+| Storage | Local + S3-compatible adapters, streaming I/O and ranged delivery |
 | Caching | Response cache and revalidation primitives |
 | Developer tools | `doctor`, `inspect`, updater and route inspection |
 | Production | Standalone server build with production middleware pipeline |
@@ -73,8 +73,6 @@ Database features currently target MySQL.
 
 ## Quick start
 
-Create a new application:
-
 ```bash
 npx create-bcp-app@latest my-app
 cd my-app
@@ -87,7 +85,7 @@ Default development URL:
 http://localhost:3000
 ```
 
-A generated project normally exposes scripts such as:
+Generated projects normally include:
 
 ```json
 {
@@ -96,7 +94,8 @@ A generated project normally exposes scripts such as:
     "build": "bcp build",
     "start": "bcp start",
     "routes": "bcp routes",
-    "update": "bcp update"
+    "update": "bcp update",
+    "typecheck": "tsc --noEmit"
   }
 }
 ```
@@ -109,13 +108,7 @@ The public framework package is published as:
 @chidchanun/bcp
 ```
 
-Applications normally consume it through the dependency key:
-
-```text
-bcp
-```
-
-This keeps imports concise:
+Applications normally consume it through the dependency key `bcp`, keeping imports concise:
 
 ```ts
 import {
@@ -125,7 +118,7 @@ import {
 } from "bcp";
 ```
 
-Server-only APIs use dedicated entrypoints such as:
+Server-only APIs use dedicated entrypoints:
 
 ```ts
 import {
@@ -137,8 +130,6 @@ import {
 
 ## Project structure
 
-A typical application can grow into this layout:
-
 ```text
 app/
 ├─ layout.tsx
@@ -168,11 +159,9 @@ package.json
 tsconfig.json
 ```
 
-BCP keeps page rendering, route authorization, server data and route mutations close together without requiring one large application router configuration file.
-
 ## Routing
 
-Page routes are discovered from `app/**/page.tsx`.
+Page routes are discovered from `app/**/page.tsx`:
 
 ```text
 app/page.tsx                     /
@@ -196,15 +185,13 @@ Read more: [Routing](docs/routing.md)
 
 ## Layouts and metadata
 
-Routes can inherit layouts from parent directories. The framework resolves the layout chain while rendering both development and standalone production requests.
-
-Document metadata is route-aware and can be generated alongside the page tree.
+Routes inherit layouts from parent directories. BCP resolves the layout chain in development and standalone production. Document metadata is route-aware and can be generated alongside the page tree.
 
 Read more: [Routing](docs/routing.md)
 
 ## Server data loaders
 
-Place `loader.ts` next to a page when the route needs server-side data.
+Place `loader.ts` next to a page when the route needs server-side data:
 
 ```ts
 // app/users/[id]/loader.ts
@@ -218,7 +205,7 @@ export async function loader({
 }
 ```
 
-Consume the serializable result in a client page:
+Consume serializable loader data from a client page:
 
 ```tsx
 "use client";
@@ -233,11 +220,7 @@ export default function UserPage() {
             id: string;
         }>();
 
-    return (
-        <main>
-            User {data.id}
-        </main>
-    );
+    return <main>User {data.id}</main>;
 }
 ```
 
@@ -245,9 +228,7 @@ Read more: [Server Data Loaders](docs/server-data-loaders.md)
 
 ## Route guards
 
-A route tree can define `guard.ts` to authorize access before the protected route is rendered.
-
-Authentication-aware guards are available through `bcp/auth`:
+A route tree can define `guard.ts` to authorize access before rendering:
 
 ```ts
 import {
@@ -267,16 +248,12 @@ Read more:
 
 ## Form actions
 
-Route-owned mutations live in `actions.ts` and can be invoked through the public `<Form>` API.
-
-This supports both progressive form submission and SPA action transport while keeping mutation logic server-only.
+Route-owned mutations live in `actions.ts` and can be invoked through the public `<Form>` API. BCP supports progressive form submission and SPA action transport while keeping mutation code server-only.
 
 Read more: [Form Actions](docs/form-actions.md)
 
 ## Server request APIs
 
-Request-scoped APIs are exposed through `bcp/server`:
-
 ```ts
 import {
     bearerToken,
@@ -289,13 +266,13 @@ import {
 } from "bcp/server";
 ```
 
-`requestId()` uses a valid incoming `X-Request-Id` when available or generates a stable UUID for the active request.
+`requestId()` accepts a valid incoming `X-Request-Id` or generates a stable UUID for the active request.
 
 Read more: [Server Request APIs](docs/server-request-apis.md)
 
 ## Authentication and sessions
 
-High-level authentication helpers are available through:
+High-level authentication helpers:
 
 ```ts
 import {
@@ -305,7 +282,7 @@ import {
 } from "bcp/auth";
 ```
 
-Lower-level JWT cookie session primitives are available through `bcp/server`:
+Lower-level JWT cookie session primitives:
 
 ```ts
 import {
@@ -317,7 +294,7 @@ import {
 } from "bcp/server";
 ```
 
-Authentication is intentionally separated from application-specific credential lookup so projects can connect their own user table or identity provider.
+Authentication is separated from application-specific credential lookup so projects can connect their own user table or identity provider.
 
 Read more:
 
@@ -346,16 +323,12 @@ export async function middleware(
 }
 ```
 
-This allows middleware to run logic both before and after downstream route execution.
-
 Existing middleware v1 behavior remains supported for compatibility.
 
 Read more: [Middleware](docs/middleware.md)
 
 ## Validation
 
-BCP includes typed validation primitives:
-
 ```ts
 import {
     v,
@@ -363,14 +336,10 @@ import {
 } from "bcp/validation";
 ```
 
-Validation can be shared by API routes and form actions without coupling application schemas to the rendering layer.
-
 Read more: [Validation](docs/validation.md)
 
 ## Error handling
 
-Structured HTTP error helpers are exposed through `bcp/error`:
-
 ```ts
 import {
     badRequest,
@@ -397,23 +366,13 @@ Read more: [Error Handling](docs/error-handling.md)
 
 ## Database
 
-Database helpers are exposed through:
-
 ```ts
 import {
     db,
 } from "bcp/database";
 ```
 
-The database layer provides:
-
-- lazy MySQL pool creation,
-- prepared execution,
-- query helpers,
-- transactions,
-- migration status and rollback support.
-
-Migration commands:
+The database layer provides a lazy MySQL pool, prepared execution, query helpers, transactions and migrations.
 
 ```bash
 bcp db create create_users
@@ -429,8 +388,6 @@ Read more:
 
 ## Logging and observability
 
-Structured server logging is available through `bcp/server`:
-
 ```ts
 import {
     logger,
@@ -446,26 +403,6 @@ logger.info(
 );
 ```
 
-Request-scoped logging can automatically include request identity:
-
-```ts
-export async function loader() {
-    const log =
-        await requestLogger({
-            feature:
-                "categories",
-        });
-
-    log.info(
-        "Loading categories"
-    );
-
-    return {
-        items: [],
-    };
-}
-```
-
 Environment controls:
 
 ```env
@@ -473,28 +410,13 @@ BCP_LOG_LEVEL=debug
 BCP_LOG_FORMAT=json
 ```
 
-Supported levels:
-
-```text
-debug
-info
-warn
-error
-silent
-```
-
-Supported formats:
-
-```text
-pretty
-json
-```
+Supported levels are `debug`, `info`, `warn`, `error` and `silent`. Formats are `pretty` and `json`.
 
 Read more: [Logging and Observability](docs/development-logging.md)
 
-## File upload
+## File uploads
 
-BCP `0.1.24` introduced multipart parsing and file validation:
+BCP keeps the buffered multipart API for small forms:
 
 ```ts
 import {
@@ -503,90 +425,78 @@ import {
     saveUploadedFile,
 } from "bcp/server";
 
-export async function POST(
-    request: Request
-) {
-    const formData =
-        await parseMultipartFormData(
-            request,
-            {
-                maxBytes:
-                    8 * 1024 * 1024,
-            }
-        );
-
-    const file =
-        requireUploadedFile(
-            formData,
-            "file",
-            {
+const formData =
+    await parseMultipartFormData(
+        request,
+        {
+            maxBytes:
+                8 * 1024 * 1024,
+        }
+    );
+
+const file =
+    requireUploadedFile(
+        formData,
+        "file",
+        {
+            maxBytes:
+                5 * 1024 * 1024,
+            allowedTypes: [
+                "image/png",
+                "image/jpeg",
+                "image/webp",
+            ],
+        }
+    );
+```
+
+BCP `0.1.26` adds direct multipart-to-storage streaming for larger production uploads:
+
+```ts
+import {
+    storeMultipartFile,
+} from "bcp/server";
+
+const stored =
+    await storeMultipartFile(
+        request,
+        {
+            storage,
+            fieldName:
+                "file",
+            key:
+                "documents/report.pdf",
+            maxBytes:
+                100 * 1024 * 1024,
+            constraints: {
                 maxBytes:
-                    5 * 1024 * 1024,
+                    80 * 1024 * 1024,
                 allowedTypes: [
-                    "image/png",
-                    "image/jpeg",
-                    "image/webp",
+                    "application/pdf",
                 ],
                 allowedExtensions: [
-                    ".png",
-                    ".jpg",
-                    ".jpeg",
-                    ".webp",
+                    ".pdf",
                 ],
-            }
-        );
-
-    return Response.json(
-        await saveUploadedFile(
-            file,
-            {
-                directory:
-                    "./uploads",
-            }
-        )
+            },
+        }
     );
-}
 ```
 
-Upload helpers provide:
-
-- multipart validation,
-- total request and per-file size limits,
-- MIME and extension allowlists,
-- required/optional file fields,
-- safe UUID-based storage names,
-- filename sanitization,
-- path traversal protection,
-- no-overwrite-by-default persistence,
-- SHA-256 checksum metadata.
-
-The security gateway applies `server.bodyLimit` / `BCP_BODY_LIMIT` before application upload parsing. Applications accepting larger files must raise that outer limit explicitly.
-
-```ts
-import {
-    defineConfig,
-} from "bcp/config";
+`storeMultipartFile()` parses `Request.body` incrementally and streams the selected file directly into the configured `StorageAdapter`. It does not call `request.formData()` for the target file.
 
-export default defineConfig({
-    server: {
-        bodyLimit:
-            10 * 1024 * 1024,
-    },
-});
-```
+The security gateway still applies `server.bodyLimit` / `BCP_BODY_LIMIT` as the outer request limit. Streaming controls memory use; it does not bypass proxy/platform/body limits.
 
-MIME type and extension validation are metadata checks, not content-signature verification. Security-sensitive applications should additionally verify content and use malware scanning where appropriate.
+MIME type and extension validation are metadata checks, not content-signature verification.
 
 Read more: [File Upload](docs/file-upload.md)
 
 ## Storage adapters
 
-BCP `0.1.25` adds the first application-facing storage abstraction.
+### Local filesystem
 
 ```ts
 import {
     createLocalStorage,
-    storeUploadedFile,
 } from "bcp/server";
 
 const storage =
@@ -594,46 +504,76 @@ const storage =
         directory:
             "./uploads",
     });
+```
 
-const stored =
-    await storeUploadedFile(
-        file,
-        {
-            storage,
-            key:
-                "avatars/user-101.webp",
-        }
-    );
+### S3-compatible storage
+
+BCP `0.1.26` adds an S3-compatible backend:
+
+```ts
+import {
+    createS3Storage,
+} from "bcp/server";
+
+const storage =
+    createS3Storage({
+        bucket:
+            process.env.S3_BUCKET!,
+        region:
+            process.env.S3_REGION!,
+        endpoint:
+            process.env.S3_ENDPOINT,
+        accessKeyId:
+            process.env.S3_ACCESS_KEY_ID,
+        secretAccessKey:
+            process.env.S3_SECRET_ACCESS_KEY,
+    });
 ```
 
-The `StorageAdapter` contract contains:
+Custom endpoints and `forcePathStyle` allow use with S3-compatible services such as MinIO. Explicit credentials are optional; when omitted, the AWS SDK can use its normal server-side credential provider chain.
+
+Keep cloud credentials server-only. Never expose them through `BCP_PUBLIC_*` variables.
+
+Read more: [S3-Compatible Storage](docs/s3-storage.md)
+
+### Streaming storage
+
+The `StorageAdapter` contract keeps its original buffered methods and adds optional streaming capabilities:
 
 ```text
 put
+putStream?     ← 0.1.26
 stat
 read
+readStream?    ← 0.1.26
 exists
 delete
 ```
 
-Application code can depend on this contract instead of depending directly on filesystem paths.
+Use generic helpers so legacy and native-streaming adapters can share application code:
 
-The built-in adapter in `0.1.25` is local filesystem storage. Cloud/object-storage adapters are planned for a later milestone.
+```ts
+import {
+    getStorageCapabilities,
+    putStorageStream,
+    readStorageStream,
+} from "bcp/server";
+```
+
+Both built-in `0.1.26` adapters support native streaming reads, streaming writes and byte ranges.
 
-Storage keys are logical relative paths. Absolute paths and traversal segments are rejected.
+Streaming writes support `maxBytes` and `AbortSignal`. Local incomplete objects are removed on failure; S3 multipart uploads are configured to clean up parts on failed completion.
 
 Read more: [Storage and File Delivery](docs/storage.md)
 
 ## Production file delivery
 
-Storage objects can be returned through a hardened HTTP response helper:
-
 ```ts
 import {
     createStorageResponse,
 } from "bcp/server";
 
-export async function GET(
+export function GET(
     request: Request
 ) {
     return createStorageResponse(
@@ -650,41 +590,36 @@ export async function GET(
 }
 ```
 
-`createStorageResponse()` supports:
+`createStorageResponse()` uses storage streaming and supports:
 
-- `GET`,
-- `HEAD`,
-- `ETag`,
-- `Last-Modified`,
-- `If-None-Match`,
-- `If-Modified-Since`,
+- `GET` / `HEAD`,
+- ETag / Last-Modified validators,
 - `If-Range`,
 - single byte ranges with `206 Partial Content`,
 - `304 Not Modified`,
 - `416 Range Not Satisfiable`,
-- safe `Content-Disposition` filenames.
+- safe `Content-Disposition` filenames,
+- configurable cache control.
 
-The default cache policy is intentionally conservative:
+The default cache policy remains:
 
 ```text
 private, max-age=0, must-revalidate
 ```
 
-Public immutable caching must be opted into explicitly.
-
-Multiple byte ranges are intentionally not supported in `0.1.25`.
+Multiple byte ranges remain intentionally unsupported in `0.1.26`.
 
 Read more: [Storage and File Delivery](docs/storage.md)
 
 ## Caching
 
-BCP includes server response caching and revalidation primitives used by development and standalone production runtimes.
+BCP includes response caching and revalidation primitives used by development and standalone production runtimes.
 
 Read more: [Caching](docs/caching.md)
 
 ## Security
 
-The framework security layer includes request body limits and production request handling defaults. Application authorization is still the responsibility of route guards and application logic.
+The framework security layer includes request body limits and production request handling defaults. Application authorization remains the responsibility of route guards and application logic.
 
 Storage keys, filenames and MIME metadata must not be treated as authorization decisions.
 
@@ -698,60 +633,48 @@ Application configuration lives in:
 bcp.config.ts
 ```
 
-Public environment variables use the prefix:
+Public environment variables use:
 
 ```text
 BCP_PUBLIC_
 ```
 
-Server-only environment values remain server-side and are not emitted into browser bundles.
+Server-only values remain server-side and are not emitted into browser bundles.
 
 Read more: [Configuration](docs/configuration.md)
 
 ## Developer tools
 
-BCP includes project diagnostics:
-
 ```bash
 bcp doctor
 bcp inspect
 ```
 
-`bcp doctor` checks areas such as:
+`bcp doctor` checks project structure, BCP/React installation parity, duplicate framework copies, environment/config loading, route conflicts and client/server boundaries.
 
-- project structure,
-- BCP installation,
-- React / ReactDOM compatibility,
-- duplicate framework copies,
-- environment/config loading,
-- route conflicts,
-- client/server boundaries.
-
-`bcp inspect` reports resolved configuration, environment sources, dependencies and discovered routes.
+`bcp inspect` reports resolved configuration, environment sources, dependency versions and discovered routes.
 
 Read more: [Developer Tools](docs/developer-tools.md)
 
 ## Windows CLI
 
-Microsoft SQL Server also installs an executable named `bcp.exe` on Windows.
-
-BCP therefore publishes the collision-free alias:
-
-```text
-bcp-framework
-```
+Microsoft SQL Server can install another executable named `bcp.exe`. BCP therefore publishes the collision-free alias `bcp-framework`.
 
-Inside project npm scripts, `bcp` remains safe because npm puts `node_modules/.bin` at the front of `PATH`.
+Inside npm scripts, `bcp` is safe because npm prepends the project's `node_modules/.bin` to `PATH`.
 
-For direct PowerShell usage, prefer:
+For direct PowerShell usage, use the project-local CLI:
 
 ```powershell
+npm exec -- bcp-framework --version
 npm exec -- bcp-framework doctor
 npm exec -- bcp-framework inspect
+npm exec -- bcp-framework routes
 npm exec -- bcp-framework dev
 npm exec -- bcp-framework build
 ```
 
+This keeps the CLI version aligned with the framework installed by the application.
+
 ## CLI reference
 
 ```bash
@@ -774,9 +697,7 @@ bcp db rollback
 
 ## Development behavior
 
-BCP includes Fast Refresh and deterministic development hydration behavior.
-
-Recent stabilization work also covers:
+BCP includes Fast Refresh and deterministic development hydration behavior. Recent stabilization work covers:
 
 - Windows line-ending parity,
 - multiline JSX hydration parity,
@@ -784,25 +705,16 @@ Recent stabilization work also covers:
 - automatic page-route/client-bundle graph resynchronization,
 - standalone authentication guard request-context parity.
 
-A development topology change should no longer require manually deleting `.bcp-framework` to recover a missing client route bundle.
-
 Read more: [Hydration](docs/hydration.md)
 
 ## Production build
 
-Build an application:
-
 ```bash
 npm run build
-```
-
-Start the generated standalone runtime:
-
-```bash
 npm run start
 ```
 
-Production output is written under:
+Production output:
 
 ```text
 .bcp-framework/build/
@@ -814,7 +726,7 @@ Production output is written under:
 
 The standalone runtime composes production middleware, security, cache, actions, guards, loaders and page rendering into the final HTTP pipeline.
 
-Runtime hostname/port overrides can be supplied to `bcp start` without rebuilding the application.
+Runtime hostname/port overrides can be supplied to `bcp start` without rebuilding.
 
 Read more: [Deployment](docs/deployment.md)
 
@@ -824,11 +736,11 @@ Read more: [Deployment](docs/deployment.md)
 bcp update
 bcp update --check
 bcp update --dry-run
-bcp update 0.1.25
+bcp update 0.1.26
 bcp update next
 ```
 
-Projects created before the updater was introduced can bootstrap it once using the public package:
+Projects created before the updater was introduced can bootstrap it once with:
 
 ```bash
 npx @chidchanun/bcp@latest update
@@ -836,14 +748,15 @@ npx @chidchanun/bcp@latest update
 
 Read more: [Updating](docs/updating.md)
 
-## Framework development
+## Framework development and release validation
 
-When working inside the BCP Framework repository itself:
+Inside the BCP Framework repository:
 
 ```bash
 npm install
 npm run typecheck
 npm run test:unit
+npm run test:integration
 npm run test:e2e
 npm run test:package
 ```
@@ -854,13 +767,13 @@ Full release-candidate validation:
 npm run rc:check
 ```
 
-A version must not be tagged or published until its release candidate and packed-package verification pass.
+A version must not be tagged or published until RC and packed-package verification pass.
 
 Read more: [Releasing](docs/releasing.md)
 
 ## Documentation source
 
-The `docs/` directory is the source content intended to feed the future **`bcp-docs-web`** documentation website.
+The `docs/` directory is the source content for the future **`bcp-docs-web`** documentation website.
 
 Start with:
 
@@ -877,6 +790,7 @@ Start with:
 - [Error Handling](docs/error-handling.md)
 - [File Upload](docs/file-upload.md)
 - [Storage and File Delivery](docs/storage.md)
+- [S3-Compatible Storage](docs/s3-storage.md)
 - [Authentication](docs/authentication.md)
 - [Auth Route Guards](docs/auth-route-guards.md)
 - [JWT Sessions](docs/session-auth.md)
@@ -892,9 +806,7 @@ Start with:
 - [Updating](docs/updating.md)
 - [Releasing](docs/releasing.md)
 
-## Documentation website model
-
-When `bcp-docs-web` is built, the recommended top-level information architecture is:
+Recommended `bcp-docs-web` top-level navigation:
 
 ```text
 Getting Started
@@ -902,21 +814,14 @@ Routing & Data
 Authentication
 Database
 Runtime & Infrastructure
+Storage & Uploads
 API Reference
 Releases
 ```
 
-`docs/README.md` contains the proposed route-to-source mapping for that website.
-
 ## Release history
 
-Release notes are stored under:
-
-```text
-docs/releases/
-```
-
-Recent milestones:
+Release notes live under `docs/releases/`.
 
 | Version | Milestone |
 | --- | --- |
@@ -926,17 +831,18 @@ Recent milestones:
 | `0.1.23` | Logging and observability |
 | `0.1.24` | File Upload Foundation |
 | `0.1.25` | Storage Adapters and File Delivery |
+| `0.1.26` | S3-Compatible Storage and Production Streaming |
 
-## Roadmap
+## Next direction
 
-Current planned direction after `0.1.25`:
+After `0.1.26`, the recommended direction is:
 
-1. S3-compatible / cloud storage adapter integration.
-2. Production upload streaming.
-3. Broader storage adapter ecosystem.
-4. Additional production hardening as new workloads expose edge cases.
+1. signed storage URLs where needed,
+2. object listing/copy/move capabilities,
+3. broader production hardening and graceful shutdown,
+4. stronger storage/provider diagnostics.
 
-Roadmap items are plans, not published API guarantees.
+These are roadmap items, not `0.1.26` API guarantees.
 
 ## License