@chidchanun/bcp 0.1.18 → 0.1.20

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.

package/docs/releases/0.1.19.md

@@ -0,0 +1,106 @@
+# BCP Framework 0.1.19
+
+BCP Framework 0.1.19 adds the first built-in Validation System.
+
+## Highlights
+
+- new `bcp/validation` public entrypoint
+- universal validation API for server and client code
+- `v.object`, `v.string`, `v.number`, `v.boolean`, `v.literal`, `v.enum`, `v.array` and `v.union`
+- `.optional()`, `.nullable()` and `.refine()` composition
+- `safeParse()` and throwing `parse()` modes
+- typed validation output through `InferValidator`
+- `validateFormData()` for BCP form actions
+- repeated FormData keys become arrays
+- string/number/boolean coercion options for HTML forms
+- field errors flattened into dot paths
+- serializable validation failure objects
+- unknown object fields are stripped by default
+- no new external runtime dependency
+
+## Form action example
+
+```ts
+import {
+    validateFormData,
+    v,
+} from "bcp/validation";
+
+const schema =
+    v.object({
+        email:
+            v.string({
+                trim: true,
+                email: true,
+            }),
+        age:
+            v.number({
+                coerce: true,
+                min: 18,
+            }),
+    });
+
+export async function saveUser(
+    formData: FormData
+) {
+    const result =
+        validateFormData(
+            schema,
+            formData
+        );
+
+    if (!result.success) {
+        return result;
+    }
+
+    return {
+        success: true,
+        user: result.data,
+    };
+}
+```
+
+## API example
+
+```ts
+const result =
+    schema.safeParse(
+        await request.json()
+    );
+
+if (!result.success) {
+    return Response.json(
+        result,
+        {
+            status: 422,
+        }
+    );
+}
+```
+
+## Error shape
+
+Validation failures use the same shape in form actions, API routes and direct validation calls:
+
+```ts
+{
+    success: false,
+    issues: [
+        {
+            path: ["email"],
+            message:
+                "Must be a valid email address.",
+            code:
+                "invalid_email",
+        },
+    ],
+    fieldErrors: {
+        email: [
+            "Must be a valid email address.",
+        ],
+    },
+    formErrors: [],
+}
+```
+
+See `docs/validation.md` for the full API.

package/docs/releases/0.1.20.md

@@ -0,0 +1,124 @@
+# BCP Framework 0.1.20
+
+BCP 0.1.20 introduces the Error Handling System: structured HTTP errors and consistent JSON error responses for APIs, form actions, guards, loaders and shared service code. It also hardens development hydration on Windows by normalizing source line endings before the React Refresh/Babel transform.
+
+## Highlights
+
+- Added the public `bcp/error` entrypoint.
+- Added `HttpError`, `createHttpError()`, `throwHttpError()` and `isHttpError()`.
+- Added `errorResponse()` and `toErrorResponse()`.
+- Added convenience response helpers for common statuses:
+  - `badRequest()` — 400
+  - `unauthorized()` — 401
+  - `forbidden()` — 403
+  - `notFoundResponse()` — 404
+  - `conflict()` — 409
+  - `unprocessableEntity()` — 422
+  - `tooManyRequests()` — 429
+  - `internalServerError()` — 500
+  - `serviceUnavailable()` — 503
+- Standardized the HTTP error payload around `status`, `code`, `message` and optional `details`.
+- Error responses default to `Cache-Control: no-store`.
+- `tooManyRequests()` can emit `Retry-After`.
+- Unknown exceptions passed to `toErrorResponse()` become a safe generic 500 response without exposing the original exception message.
+- Re-exported the HTTP error helpers through the server-only `bcp/server` entrypoint.
+- Kept `notFound()` and `notFoundResponse()` intentionally separate: page 404 UI versus JSON HTTP 404 response.
+- Fixed development hydration mismatches on Windows when CRLF source files contain multiline JSX/template-literal attributes such as multiline `className` values.
+- Development application source now normalizes `CRLF` and standalone `CR` to `LF` before the React Refresh Babel transform, matching SSR source semantics.
+- Added a CRLF development bundle regression fixture so the line-ending mismatch cannot silently return.
+- Added unit and publish-surface regression coverage.
+- Added the Error Handling and Hydration guides and updated the `bcp-docs` source map.
+
+## API example
+
+```ts
+import {
+    unauthorized,
+} from "bcp/error";
+
+export async function GET() {
+    const user = null;
+
+    if (!user) {
+        return unauthorized();
+    }
+
+    return Response.json({
+        user,
+    });
+}
+```
+
+## Validation example
+
+```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,
+            }
+        );
+    }
+
+    return Response.json(
+        result.data
+    );
+}
+```
+
+## Windows hydration fix
+
+The following pattern is valid BCP/React code and no longer requires a one-line workaround on CRLF checkouts:
+
+```tsx
+export default function Page() {
+    return (
+        <main
+            className={`
+                min-h-screen
+                bg-white
+                text-slate-950
+            `}
+        >
+            Hello
+        </main>
+    );
+}
+```
+
+Before the fix, the development Babel/React Refresh path could preserve carriage-return characters differently from the SSR transform. React then saw different attribute strings during hydration even though the Tailwind class list looked identical. BCP now normalizes the development source before Babel.
+
+This does not suppress genuine hydration errors from `Date.now()`, `Math.random()`, browser-only initial branches, locale differences, changing external data or invalid HTML.
+
+See `docs/hydration.md` for details and troubleshooting.
+
+## Compatibility
+
+0.1.20 is additive. Existing `Response`, `Response.json()`, `bcp/server` helpers, `notFound()`, route guards and form actions continue to work.
+
+Applications do not need to migrate existing error handling immediately. New code can adopt `bcp/error` incrementally.

package/docs/validation.md

@@ -0,0 +1,342 @@
+# Validation
+
+BCP Framework 0.1.19 adds a built-in validation system through `bcp/validation`.
+
+The module is universal and can be used in server actions, API routes, loaders and client-side code.
+
+## Basic schema
+
+```ts
+import {
+    v,
+} from "bcp/validation";
+
+const userSchema =
+    v.object({
+        name:
+            v.string({
+                trim: true,
+                minLength: 2,
+            }),
+        email:
+            v.string({
+                trim: true,
+                email: true,
+            }),
+        age:
+            v.number({
+                coerce: true,
+                integer: true,
+                min: 18,
+            }),
+        role:
+            v.enum([
+                "admin",
+                "user",
+            ]),
+    });
+```
+
+## Safe parsing
+
+```ts
+const result =
+    userSchema.safeParse(input);
+
+if (!result.success) {
+    console.log(
+        result.fieldErrors
+    );
+    return;
+}
+
+console.log(result.data);
+```
+
+Successful results have:
+
+```ts
+{
+    success: true,
+    data: value,
+}
+```
+
+Failures have:
+
+```ts
+{
+    success: false,
+    issues: [...],
+    fieldErrors: {
+        email: [
+            "Must be a valid email address.",
+        ],
+    },
+    formErrors: [],
+}
+```
+
+Nested field paths are flattened with dot notation, for example `profile.email` and `items.0.name`.
+
+## Form actions
+
+`validateFormData()` converts repeated FormData keys into arrays and validates the resulting object.
+
+```ts
+import {
+    validateFormData,
+    v,
+} from "bcp/validation";
+
+const schema =
+    v.object({
+        email:
+            v.string({
+                trim: true,
+                email: true,
+            }),
+        age:
+            v.number({
+                coerce: true,
+                min: 18,
+            }),
+    });
+
+export async function saveUser(
+    formData: FormData
+) {
+    const result =
+        validateFormData(
+            schema,
+            formData
+        );
+
+    if (!result.success) {
+        return result;
+    }
+
+    // result.data is typed and validated.
+    // await db.execute(...)
+
+    return {
+        success: true,
+        user: result.data,
+    };
+}
+```
+
+The failure object is serializable and can be returned from a BCP form action directly.
+
+## API routes
+
+```ts
+import {
+    v,
+} from "bcp/validation";
+
+const schema =
+    v.object({
+        email:
+            v.string({
+                email: true,
+            }),
+    });
+
+export async function POST(
+    request: Request
+) {
+    const input =
+        await request.json();
+    const result =
+        schema.safeParse(
+            input
+        );
+
+    if (!result.success) {
+        return Response.json(
+            result,
+            {
+                status: 422,
+            }
+        );
+    }
+
+    return Response.json({
+        user: result.data,
+    });
+}
+```
+
+## Throwing parse
+
+Use `parse()` when invalid input should throw a `ValidationError`.
+
+```ts
+import {
+    ValidationError,
+    parse,
+} from "bcp/validation";
+
+try {
+    const user =
+        parse(
+            userSchema,
+            input
+        );
+} catch (error) {
+    if (
+        error instanceof
+        ValidationError
+    ) {
+        console.log(
+            error.fieldErrors
+        );
+    }
+}
+```
+
+## Available validators
+
+```ts
+v.string()
+v.number()
+v.boolean()
+v.literal("active")
+v.enum(["admin", "user"])
+v.array(v.string())
+v.object({ ... })
+v.union([ ... ])
+```
+
+Optional and nullable values:
+
+```ts
+v.string().optional()
+v.string().nullable()
+
+v.optional(v.string())
+v.nullable(v.string())
+```
+
+## String validation
+
+```ts
+v.string({
+    trim: true,
+    minLength: 2,
+    maxLength: 100,
+    email: true,
+    pattern: /^[A-Z]/,
+})
+```
+
+## Number validation
+
+```ts
+v.number({
+    coerce: true,
+    integer: true,
+    min: 1,
+    max: 100,
+})
+```
+
+`coerce: true` is useful for HTML forms because FormData values are strings.
+
+## Boolean validation
+
+```ts
+v.boolean({
+    coerce: true,
+})
+```
+
+Boolean coercion recognizes common form values including `true`, `false`, `1`, `0`, `on`, `off`, `yes` and `no`.
+
+## Custom rules
+
+Use `refine()` for application-specific rules.
+
+```ts
+const password =
+    v.string({
+        minLength: 8,
+    }).refine(
+        (value) =>
+            /\d/.test(value),
+        "Password must contain a number.",
+        "password_number"
+    );
+```
+
+## Unknown object fields
+
+Object validation strips fields that are not declared in the schema by default.
+
+This is useful for API and form input because untrusted extra fields do not automatically pass into database writes.
+
+To preserve unknown fields explicitly:
+
+```ts
+v.object(
+    {
+        name: v.string(),
+    },
+    {
+        allowUnknown: true,
+    }
+)
+```
+
+## Validation paths and errors
+
+Each issue contains:
+
+```ts
+{
+    path: [
+        "profile",
+        "email",
+    ],
+    message:
+        "Must be a valid email address.",
+    code:
+        "invalid_email",
+}
+```
+
+Use `getFieldError()` when only the first message for a field is needed.
+
+```ts
+import {
+    getFieldError,
+} from "bcp/validation";
+
+const emailError =
+    getFieldError(
+        result,
+        "email"
+    );
+```
+
+## Type inference
+
+Use `InferValidator` when application code needs the TypeScript output type of a schema.
+
+```ts
+import type {
+    InferValidator,
+} from "bcp/validation";
+
+type UserInput =
+    InferValidator<
+        typeof userSchema
+    >;
+```
+
+## External schema libraries
+
+BCP 0.1.19 does not require Zod, Valibot or another validation dependency. The built-in API keeps framework validation dependency-free.
+
+Adapters for external schema libraries can be added in future releases without changing the validation result model used by actions and API routes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chidchanun/bcp",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "description": "BCP Framework - a React full-stack framework with file-based routing, SSR, APIs, middleware, islands, caching and standalone production builds.",
   "type": "module",
   "license": "MIT",
@@ -43,6 +43,14 @@
       "types": "./packages/client/src/config.ts",
       "default": "./packages/client/src/config.ts"
     },
+    "./validation": {
+      "types": "./packages/client/src/validation.ts",
+      "default": "./packages/client/src/validation.ts"
+    },
+    "./error": {
+      "types": "./packages/client/src/http-error.ts",
+      "default": "./packages/client/src/http-error.ts"
+    },
     "./database": {
       "types": "./packages/client/src/database.ts",
       "browser": "./packages/client/src/server-only.browser.mjs",