@chidchanun/bcp 0.1.18 → 0.1.20

package/docs/README.md

@@ -4,7 +4,7 @@ This directory is the documentation source of truth for the BCP Framework docume
 
 The recommended documentation website project name is `bcp-docs`.
 
-> Documentation target: BCP Framework `0.1.18`
+> Documentation target: BCP Framework `0.1.20`
 
 ## Purpose
 
@@ -40,6 +40,8 @@ The website should not invent API behavior that is not documented or tested in t
 | `/docs/route-guards` | `route-guards.md` | Scoped page authorization |
 | `/docs/form-actions` | `form-actions.md` | Server mutations and forms |
 | `/docs/server-request-apis` | `server-request-apis.md` | Request, cookie, redirect and response APIs |
+| `/docs/validation` | `validation.md` | Typed form/API validation and field errors |
+| `/docs/error-handling` | `error-handling.md` | Structured HTTP errors and standard error responses |
 
 ### Authentication
 
@@ -61,6 +63,7 @@ The website should not invent API behavior that is not documented or tested in t
 | Website route | Source file | Description |
 | --- | --- | --- |
 | `/docs/middleware` | `middleware.md` | Middleware System v2 and v1 compatibility |
+| `/docs/hydration` | `hydration.md` | SSR/client hydration, deterministic rendering and Windows CRLF behavior |
 | `/docs/caching` | `caching.md` | Cache and revalidation |
 | `/docs/security` | `security.md` | Framework security defaults |
 | `/docs/development-logging` | `development-logging.md` | Development request logging |
@@ -72,9 +75,9 @@ Use the files under `docs/releases/` for release pages.
 Recommended route format:
 
 ```text
-/releases/0.1.16
-/releases/0.1.17
 /releases/0.1.18
+/releases/0.1.19
+/releases/0.1.20
 ```
 
 The newest release should also be available from `/releases`.
@@ -94,6 +97,7 @@ Recommended feature groups:
 - Loading and error UI
 - API routes
 - Client islands / partial hydration
+- Deterministic development hydration across LF/CRLF source checkouts
 
 ### Server data and mutations
 
@@ -102,6 +106,12 @@ Recommended feature groups:
 - Form actions
 - Request-scoped server APIs
 - Cookies and redirects
+- `bcp/validation`
+- Typed form/API validation
+- Field and form error output
+- `bcp/error`
+- Structured HTTP error responses
+- Safe unknown-error fallback responses
 
 ### Database
 
@@ -153,7 +163,8 @@ Suggested content, not a required exact copy:
 ```text
 BCP Framework
 A React full-stack framework for building server-rendered applications with routing,
-data loading, server mutations, authentication, databases, middleware and production tooling.
+data loading, server mutations, authentication, databases, validation, structured errors,
+middleware and production tooling.
 ```
 
 Primary actions:
@@ -183,6 +194,8 @@ Core
   Server Data Loaders
   Route Guards
   Form Actions
+  Validation
+  Error Handling
 
 Authentication
   Authentication Core
@@ -195,6 +208,7 @@ Database
 
 Runtime
   Middleware
+  Hydration
   Caching
   Security
 
@@ -203,9 +217,9 @@ Production
   Development Logging
 
 Releases
+  0.1.20
+  0.1.19
   0.1.18
-  0.1.17
-  0.1.16
 ```
 
 ## Suggested documentation page layout
@@ -249,6 +263,16 @@ import {
     db,
 } from "bcp/database";
 
+import {
+    v,
+    validateFormData,
+} from "bcp/validation";
+
+import {
+    badRequest,
+    unauthorized,
+} from "bcp/error";
+
 import {
     type MiddlewarePipelineHandler,
 } from "bcp/middleware";
@@ -297,7 +321,7 @@ npx create-bcp-app@latest my-app
 
 ## Middleware v2 documentation priority
 
-BCP 0.1.18 introduces a meaningful middleware architecture change, so the `bcp-docs` website should make the distinction between v1 and v2 clear.
+BCP 0.1.18 introduced a meaningful middleware architecture change, so the `bcp-docs` website should make the distinction between v1 and v2 clear.
 
 The middleware page should prominently explain:
 
@@ -310,6 +334,59 @@ Existing v1 code remains supported, so migration documentation should describe v
 
 See `middleware.md` for the full API and examples.
 
+## Validation documentation priority
+
+BCP 0.1.19 introduced the public `bcp/validation` entrypoint. The docs website should show validation in both form-action and API-route examples.
+
+Important concepts to surface:
+
+- `v.object`, `v.string`, `v.number`, `v.boolean`, `v.array`
+- FormData coercion with `validateFormData()`
+- `success/data` versus `issues/fieldErrors/formErrors`
+- object fields are stripped unless `allowUnknown: true`
+- `refine()` for custom application rules
+- no external validation dependency is required
+
+See `validation.md` for the complete API and examples.
+
+## Error Handling documentation priority
+
+BCP 0.1.20 introduces the public `bcp/error` entrypoint and a standard HTTP error envelope.
+
+The docs website should clearly distinguish:
+
+```text
+notFound()          = activate page 404 UI behavior
+notFoundResponse()  = return a JSON 404 HTTP response
+```
+
+Important concepts to surface:
+
+- `HttpError` and `createHttpError()`
+- `errorResponse()` for any 4xx/5xx status
+- `toErrorResponse()` for safe catch boundaries
+- `badRequest()`, `unauthorized()`, `forbidden()`, `conflict()` and other convenience helpers
+- standard `{ error: { status, code, message, details? } }` payload
+- error responses default to `Cache-Control: no-store`
+- unknown exceptions become a generic 500 response without exposing the original exception message
+- normal field validation still belongs to `bcp/validation`
+
+See `error-handling.md` for the complete API and examples.
+
+## Hydration documentation priority
+
+BCP 0.1.20 also fixes a Windows development hydration mismatch caused by CRLF source line endings passing through the React Refresh/Babel transform differently from SSR.
+
+The docs website should make these points clear:
+
+- multiline JSX attributes such as template-literal `className` values are supported,
+- developers should not need to rewrite them as one-line strings to avoid framework hydration warnings,
+- BCP normalizes `CRLF` and standalone `CR` source line endings to `LF` before the development Babel transform,
+- the framework fix does not suppress genuine hydration mismatches caused by random values, locale differences, browser-only initial branches, changing external data or invalid HTML,
+- `suppressHydrationWarning` is not a general-purpose solution.
+
+See `hydration.md` for the full explanation and troubleshooting steps.
+
 ## Release workflow for documentation
 
 Before publishing a new BCP release:

package/docs/error-handling.md

@@ -0,0 +1,457 @@
+# Error Handling
+
+BCP 0.1.20 adds a structured HTTP error API for API routes, form actions, route guards, server data loaders and shared service code.
+
+Import the public helpers from `bcp/error`:
+
+```ts
+import {
+    badRequest,
+    conflict,
+    createHttpError,
+    forbidden,
+    isHttpError,
+    notFoundResponse,
+    throwHttpError,
+    tooManyRequests,
+    toErrorResponse,
+    unauthorized,
+    unprocessableEntity,
+} from "bcp/error";
+```
+
+The same helpers are also re-exported by the server-only `bcp/server` entrypoint.
+
+## Standard error envelope
+
+BCP error responses use one JSON shape:
+
+```json
+{
+  "error": {
+    "status": 422,
+    "code": "invalid_input",
+    "message": "Input is invalid",
+    "details": {
+      "email": [
+        "Email is required"
+      ]
+    }
+  }
+}
+```
+
+`details` is optional.
+
+HTTP error responses default to:
+
+```http
+Cache-Control: no-store
+Content-Type: application/json
+```
+
+The no-store default prevents authentication and validation failures from being cached accidentally. A custom `Cache-Control` header can override the default when an application intentionally needs another policy.
+
+## API routes
+
+Return an error helper exactly like a normal Web `Response`:
+
+```ts
+import {
+    unauthorized,
+} from "bcp/error";
+
+export async function GET() {
+    const user = null;
+
+    if (!user) {
+        return unauthorized();
+    }
+
+    return Response.json({
+        user,
+    });
+}
+```
+
+Custom messages and details are supported:
+
+```ts
+import {
+    unprocessableEntity,
+} from "bcp/error";
+
+export async function POST() {
+    return unprocessableEntity(
+        "Input is invalid",
+        {
+            email: [
+                "Email is required",
+            ],
+        }
+    );
+}
+```
+
+## Form actions
+
+BCP actions already accept a Web `Response`, so error helpers work without a separate transport convention:
+
+```ts
+import {
+    conflict,
+} from "bcp/error";
+
+export async function createUser(
+    formData: FormData
+) {
+    const email =
+        String(
+            formData.get("email") ?? ""
+        );
+
+    const exists =
+        email ===
+        "existing@example.com";
+
+    if (exists) {
+        return conflict(
+            "Email is already in use",
+            {
+                field:
+                    "email",
+            }
+        );
+    }
+
+    return {
+        ok: true,
+    };
+}
+```
+
+For normal form-field validation, prefer `bcp/validation`. Use HTTP error responses for request-level failures such as authorization, conflicts, invalid application state or service failures.
+
+## Route guards
+
+Route guards may stop navigation with a response:
+
+```ts
+import {
+    forbidden,
+} from "bcp/error";
+
+export async function guard() {
+    const role =
+        "member";
+
+    if (
+        role !== "admin"
+    ) {
+        return forbidden(
+            "Admin access required"
+        );
+    }
+
+    return {
+        role,
+    };
+}
+```
+
+For standard authenticated route protection, `requireAuth()` and `requireRole()` from `bcp/auth` remain the preferred high-level APIs.
+
+## Server data loaders
+
+Loaders may return error responses before rendering a page:
+
+```ts
+import {
+    serviceUnavailable,
+} from "bcp/error";
+
+export async function loader() {
+    const databaseAvailable =
+        false;
+
+    if (!databaseAvailable) {
+        return serviceUnavailable();
+    }
+
+    return {
+        users: [],
+    };
+}
+```
+
+## `notFound()` versus `notFoundResponse()`
+
+BCP has two intentionally different 404 APIs.
+
+Use `notFound()` from `bcp` when page rendering should activate the BCP `not-found.tsx` route UI:
+
+```ts
+import {
+    notFound,
+} from "bcp";
+
+export default function UserPage() {
+    const user = null;
+
+    if (!user) {
+        notFound();
+    }
+
+    return <main>User</main>;
+}
+```
+
+Use `notFoundResponse()` from `bcp/error` when the caller needs a JSON HTTP response:
+
+```ts
+import {
+    notFoundResponse,
+} from "bcp/error";
+
+export function GET() {
+    return notFoundResponse(
+        "User not found"
+    );
+}
+```
+
+This separation keeps page UI semantics distinct from API response semantics.
+
+## Structured `HttpError`
+
+Shared service code may need to report a typed error without returning a Web `Response` directly.
+
+Create one with:
+
+```ts
+import {
+    createHttpError,
+} from "bcp/error";
+
+export async function loadAccount(
+    id: string
+) {
+    if (!id) {
+        throw createHttpError(
+            400,
+            {
+                code:
+                    "missing_account_id",
+                message:
+                    "Account id is required",
+            }
+        );
+    }
+}
+```
+
+The equivalent shorthand is:
+
+```ts
+import {
+    throwHttpError,
+} from "bcp/error";
+
+throwHttpError(
+    403,
+    {
+        code:
+            "billing_access_denied",
+        message:
+            "Billing access denied",
+    }
+);
+```
+
+`HttpError` contains:
+
+```ts
+{
+    status: number;
+    code: string;
+    message: string;
+    details: unknown;
+    headers: Headers;
+}
+```
+
+HTTP error statuses must be integers from `400` through `599`.
+
+## Converting caught errors
+
+Use `isHttpError()` when application code needs to branch on the error type:
+
+```ts
+import {
+    isHttpError,
+    toErrorResponse,
+} from "bcp/error";
+
+export async function GET() {
+    try {
+        await loadAccount("123");
+
+        return Response.json({
+            ok: true,
+        });
+    } catch (error) {
+        if (
+            isHttpError(error)
+        ) {
+            console.warn(
+                error.code,
+                error.status
+            );
+        }
+
+        return toErrorResponse(
+            error
+        );
+    }
+}
+```
+
+Known `HttpError` values preserve their status, code, message, details and headers.
+
+Unknown exceptions are intentionally converted to:
+
+```json
+{
+  "error": {
+    "status": 500,
+    "code": "internal_server_error",
+    "message": "Internal Server Error"
+  }
+}
+```
+
+BCP does not expose the original unknown exception message in that fallback response. Log internal errors on the server instead of returning stack traces, database errors, credentials or other implementation details to clients.
+
+## Rate limiting
+
+`tooManyRequests()` supports `Retry-After`:
+
+```ts
+import {
+    tooManyRequests,
+} from "bcp/error";
+
+return tooManyRequests(
+    "Try again later",
+    {
+        retryAfter:
+            60,
+    }
+);
+```
+
+Response:
+
+```http
+HTTP/1.1 429 Too Many Requests
+Retry-After: 60
+Cache-Control: no-store
+```
+
+## Generic status responses
+
+Use `errorResponse()` when no convenience helper exists:
+
+```ts
+import {
+    errorResponse,
+} from "bcp/error";
+
+return errorResponse(
+    405,
+    {
+        code:
+            "method_not_allowed",
+        message:
+            "Only POST is allowed",
+        headers: {
+            Allow:
+                "POST",
+        },
+    }
+);
+```
+
+Common built-in helpers in 0.1.20 are:
+
+```text
+badRequest()            400
+unauthorized()          401
+forbidden()             403
+notFoundResponse()      404
+conflict()              409
+unprocessableEntity()   422
+tooManyRequests()       429
+internalServerError()   500
+serviceUnavailable()    503
+```
+
+Use `errorResponse(status, options)` for other `4xx` and `5xx` statuses.
+
+## Validation integration
+
+A practical API pattern combines `bcp/validation` with `bcp/error`:
+
+```ts
+import {
+    unprocessableEntity,
+} from "bcp/error";
+import {
+    v,
+} from "bcp/validation";
+
+const schema =
+    v.object({
+        email:
+            v.string({
+                email: true,
+            }),
+    });
+
+export async function POST(
+    request: Request
+) {
+    const result =
+        schema.safeParse(
+            await request.json()
+        );
+
+    if (!result.success) {
+        return unprocessableEntity(
+            "Validation failed",
+            {
+                fieldErrors:
+                    result.fieldErrors,
+                formErrors:
+                    result.formErrors,
+            }
+        );
+    }
+
+    return Response.json(
+        result.data
+    );
+}
+```
+
+## Error handling responsibilities
+
+BCP separates three concerns:
+
+```text
+notFound()             -> page 404 UI convention
+bcp/validation         -> typed input validation
+bcp/error              -> HTTP/application error responses
+```
+
+Unexpected framework or programming exceptions remain server errors and should be logged. Do not convert every exception to a successful action data object; use the correct HTTP status when the failure represents an HTTP request outcome.