@chidchanun/bcp 0.1.19 → 0.1.21

package/README.md

@@ -1,8 +1,8 @@
 # BCP Framework
 
-BCP Framework is a React full-stack framework with file-based routing, SSR, client navigation, API routes, middleware, metadata, client islands, cache/revalidation, security defaults and standalone production builds.
+BCP Framework is a React full-stack framework with file-based routing, SSR, client navigation, API routes, middleware, metadata, client islands, cache/revalidation, validation, structured errors, authentication, database primitives, security defaults and standalone production builds.
 
-> Current release target: `0.1.11`. BCP is still pre-1.0 and validates each release candidate before the manual npm publish step.
+> Current release target: `0.1.21`. BCP is still pre-1.0 and validates each release candidate before the manual npm publish step.
 
 ## Quick start
 
@@ -86,6 +86,30 @@ See [Application Modules](docs/application-modules.md) for the complete boundary
 
 Generated Tailwind projects compile to `public/bcp.css`. BCP 0.1.6 inlines that stylesheet into SSR HTML when it is 8 KiB or smaller, removing the stylesheet request from the initial render-critical path. Larger stylesheets remain external so the browser can cache them normally. If the application's Content Security Policy does not allow inline styles, BCP automatically keeps the external stylesheet link.
 
+## Development hydration parity
+
+BCP 0.1.21 fixes a development-only hydration mismatch where the SSR transform and the React Refresh client transform could assign different semantic values to the same multiline JSX attribute.
+
+For example, this is supported application code:
+
+```tsx
+<div
+    className="
+        min-h-screen
+        bg-white
+        text-slate-950
+    "
+/>
+```
+
+BCP 0.1.20 already normalized Windows `CRLF` and standalone `CR` source line endings to `LF`, but Babel's JSX transform could still collapse the multiline quoted attribute to a single-space-separated string while SSR preserved the original line breaks and indentation.
+
+In 0.1.21, Babel remains responsible for TypeScript stripping and React Refresh registration, but JSX is preserved until esbuild compiles it with the development JSX runtime. This keeps static JSX attribute semantics aligned between SSR and the development client bundle.
+
+Applications should not need to rewrite multiline classes to one line or use `suppressHydrationWarning` to work around framework transform differences. Genuine runtime mismatches caused by values such as `Date.now()`, `Math.random()`, browser-only initial state, locale differences or changing external data still need to be fixed in application code.
+
+See [Hydration and deterministic rendering](docs/hydration.md) for the transform pipeline and troubleshooting guidance.
+
 ## Commands
 
 ```bash
@@ -117,7 +141,7 @@ bcp update --dry-run
 Or select a published version/dist-tag explicitly:
 
 ```bash
-bcp update 0.1.11
+bcp update 0.1.21
 bcp update next
 ```
 
@@ -777,12 +801,19 @@ No real npm publish command is run automatically by the repository.
 - [Server Data Loaders](docs/server-data-loaders.md)
 - [Protected Route Guards](docs/route-guards.md)
 - [Form Actions and Server Mutations](docs/form-actions.md)
+- [Validation](docs/validation.md)
+- [Error Handling](docs/error-handling.md)
+- [Authentication](docs/authentication.md)
+- [Auth Route Guards](docs/auth-route-guards.md)
 - [JWT Cookie Sessions](docs/session-auth.md)
+- [Database](docs/database.md)
+- [Database Migrations](docs/database-migrations.md)
+- [Middleware](docs/middleware.md)
+- [Hydration and deterministic rendering](docs/hydration.md)
 - [Updating BCP Framework](docs/updating.md)
 - [Routing](docs/routing.md)
 - [Configuration](docs/configuration.md)
 - [Caching](docs/caching.md)
-- [Middleware](docs/middleware.md)
 - [Security](docs/security.md)
 - [Deployment](docs/deployment.md)
 - [Releasing](docs/releasing.md)

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.21`
 
 ## 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 transform parity, deterministic rendering and Windows line endings |
 | `/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
+/releases/0.1.21
 ```
 
 The newest release should also be available from `/releases`.
@@ -95,6 +97,8 @@ Recommended feature groups:
 - Loading and error UI
 - API routes
 - Client islands / partial hydration
+- Deterministic development hydration across server/client transform pipelines
+- LF/CRLF-safe development source handling
 
 ### Server data and mutations
 
@@ -106,6 +110,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 +164,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 +196,7 @@ Core
   Route Guards
   Form Actions
   Validation
+  Error Handling
 
 Authentication
   Authentication Core
@@ -200,6 +209,7 @@ Database
 
 Runtime
   Middleware
+  Hydration
   Caching
   Security
 
@@ -208,9 +218,9 @@ Production
   Development Logging
 
 Releases
+  0.1.21
+  0.1.20
   0.1.19
-  0.1.18
-  0.1.17
 ```
 
 ## Suggested documentation page layout
@@ -259,6 +269,11 @@ import {
     validateFormData,
 } from "bcp/validation";
 
+import {
+    badRequest,
+    unauthorized,
+} from "bcp/error";
+
 import {
     type MiddlewarePipelineHandler,
 } from "bcp/middleware";
@@ -322,7 +337,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 +350,54 @@ Important concepts to surface:
 
 See `validation.md` for the complete API and examples.
 
+## Error Handling documentation priority
+
+BCP 0.1.20 introduced 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 added line-ending normalization for the development React Refresh path. That removed the Windows `CRLF` versus `LF` mismatch, but a second issue remained when Babel compiled multiline quoted JSX attributes and collapsed their whitespace differently from SSR.
+
+BCP 0.1.21 completes this fix by keeping Babel responsible for TypeScript removal and React Refresh instrumentation while leaving JSX untransformed. esbuild then performs the development JSX transform with the development JSX runtime enabled.
+
+The docs website should make these points clear:
+
+- multiline quoted JSX attributes are supported,
+- multiline template-literal JSX expressions are supported,
+- developers should not need to rewrite multiline `className` values as one-line strings to avoid framework hydration warnings,
+- `CRLF` and standalone `CR` source line endings are normalized to `LF` before development instrumentation,
+- React Refresh instrumentation must not change the semantic value of JSX attributes,
+- 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, transform pipeline and troubleshooting steps.
+
+## Release roadmap adjustment
+
+`0.1.21` is reserved for the hydration parity hotfix because `0.1.20` was already published before the remaining Babel JSX whitespace mismatch was isolated.
+
+The previously planned Developer Tools release moves to `0.1.22`, and later roadmap items should shift forward accordingly unless they are regrouped into a larger milestone.
+
 ## 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.