@chidchanun/bcp 0.1.19 → 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.19`
+> Documentation target: BCP Framework `0.1.20`
 
 ## Purpose
 
@@ -41,6 +41,7 @@ The website should not invent API behavior that is not documented or tested in t
 | `/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
 
@@ -62,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 |
@@ -73,9 +75,9 @@ Use the files under `docs/releases/` for release pages.
 Recommended route format:
 
 ```text
-/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`.
@@ -95,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
 
@@ -106,6 +109,9 @@ Recommended feature groups:
 - `bcp/validation`
 - Typed form/API validation
 - Field and form error output
+- `bcp/error`
+- Structured HTTP error responses
+- Safe unknown-error fallback responses
 
 ### Database
 
@@ -157,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, validation, middleware and production tooling.
+data loading, server mutations, authentication, databases, validation, structured errors,
+middleware and production tooling.
 ```
 
 Primary actions:
@@ -188,6 +195,7 @@ Core
   Route Guards
   Form Actions
   Validation
+  Error Handling
 
 Authentication
   Authentication Core
@@ -200,6 +208,7 @@ Database
 
 Runtime
   Middleware
+  Hydration
   Caching
   Security
 
@@ -208,9 +217,9 @@ Production
   Development Logging
 
 Releases
+  0.1.20
   0.1.19
   0.1.18
-  0.1.17
 ```
 
 ## Suggested documentation page layout
@@ -259,6 +268,11 @@ import {
     validateFormData,
 } from "bcp/validation";
 
+import {
+    badRequest,
+    unauthorized,
+} from "bcp/error";
+
 import {
     type MiddlewarePipelineHandler,
 } from "bcp/middleware";
@@ -322,7 +336,7 @@ See `middleware.md` for the full API and examples.
 
 ## Validation documentation priority
 
-BCP 0.1.19 introduces the public `bcp/validation` entrypoint. The docs website should show validation in both form-action and API-route examples.
+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:
 
@@ -335,6 +349,44 @@ Important concepts to surface:
 
 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.

package/docs/hydration.md

@@ -0,0 +1,112 @@
+# Hydration and deterministic rendering
+
+BCP uses server-side rendering for the initial HTML and React hydration in the browser. The server-rendered tree and the first client-rendered tree must produce the same element attributes and text.
+
+## Windows CRLF support
+
+BCP Framework 0.1.20 normalizes application source line endings before the development React Refresh/Babel transform.
+
+This fixes a Windows-specific hydration warning that could appear when a JSX attribute used a multiline template literal, for example:
+
+```tsx
+export default function Page() {
+    return (
+        <main
+            className={`
+                min-h-screen
+                bg-white
+                text-slate-950
+            `}
+        >
+            Hello
+        </main>
+    );
+}
+```
+
+On a CRLF checkout, the development client transform could previously preserve carriage-return characters differently from the SSR transform. React then compared two visually equivalent class lists whose underlying strings were different and reported a hydration mismatch.
+
+BCP now normalizes both `CRLF` (`\r\n`) and standalone `CR` (`\r`) source line endings to `LF` (`\n`) before Babel processes development application modules. Developers do not need to rewrite multiline `className` values as one line to work around this framework issue.
+
+## What BCP fixes automatically
+
+The line-ending fix addresses deterministic source transformation. It does not hide genuine hydration differences caused by application behavior.
+
+BCP applications should still avoid producing different initial values on the server and client from code such as:
+
+```tsx
+const value = Date.now();
+```
+
+```tsx
+const value = Math.random();
+```
+
+or:
+
+```tsx
+const browserOnly =
+    typeof window !== "undefined";
+```
+
+when those values directly change the initial rendered markup.
+
+Other common application-level causes include:
+
+- locale-dependent formatting that differs between server and browser,
+- data that changes between SSR and hydration without a serialized snapshot,
+- invalid HTML nesting,
+- browser extensions that modify the DOM before React hydrates it.
+
+## Recommended pattern for browser-only state
+
+If a value genuinely depends on the browser, initialize the server/client render deterministically and update it after mount.
+
+```tsx
+"use client";
+
+import {
+    useEffect,
+    useState,
+} from "react";
+
+export default function BrowserValue() {
+    const [ready, setReady] =
+        useState(false);
+
+    useEffect(
+        () => {
+            setReady(true);
+        },
+        []
+    );
+
+    return (
+        <span>
+            {ready
+                ? "Browser ready"
+                : "Loading"}
+        </span>
+    );
+}
+```
+
+## Development and production
+
+The Windows CRLF issue was specific to the development React Refresh/Babel path. Production client compilation uses the production esbuild pipeline. The 0.1.20 fix makes development source handling deterministic before Babel so development hydration matches the SSR semantics.
+
+## Troubleshooting
+
+If React still reports a hydration mismatch after upgrading to a BCP release containing this fix:
+
+1. stop the BCP dev server,
+2. remove `.bcp-framework/`,
+3. start `bcp dev` again,
+4. inspect the first differing server/client value in the React hydration warning,
+5. check for request-time, random, locale, browser-only or externally changing values.
+
+Do not use `suppressHydrationWarning` as a general fix. It should only be used when a difference is intentional and understood.
+
+## Regression coverage
+
+The framework test suite contains a Windows-style CRLF fixture with a multiline JSX `className`. The development client bundle is required to normalize source line endings before the React Refresh Babel transform.