@chidchanun/bcp 0.1.18 → 0.1.19

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.19`
 
 ## Purpose
 
@@ -40,6 +40,7 @@ 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 |
 
 ### Authentication
 
@@ -72,9 +73,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
 ```
 
 The newest release should also be available from `/releases`.
@@ -102,6 +103,9 @@ Recommended feature groups:
 - Form actions
 - Request-scoped server APIs
 - Cookies and redirects
+- `bcp/validation`
+- Typed form/API validation
+- Field and form error output
 
 ### Database
 
@@ -153,7 +157,7 @@ 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, middleware and production tooling.
 ```
 
 Primary actions:
@@ -183,6 +187,7 @@ Core
   Server Data Loaders
   Route Guards
   Form Actions
+  Validation
 
 Authentication
   Authentication Core
@@ -203,9 +208,9 @@ Production
   Development Logging
 
 Releases
+  0.1.19
   0.1.18
   0.1.17
-  0.1.16
 ```
 
 ## Suggested documentation page layout
@@ -249,6 +254,11 @@ import {
     db,
 } from "bcp/database";
 
+import {
+    v,
+    validateFormData,
+} from "bcp/validation";
+
 import {
     type MiddlewarePipelineHandler,
 } from "bcp/middleware";
@@ -297,7 +307,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 +320,21 @@ 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 introduces 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.
+
 ## Release workflow for documentation
 
 Before publishing a new BCP release:

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/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.19",
   "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,10 @@
       "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"
+    },
     "./database": {
       "types": "./packages/client/src/database.ts",
       "browser": "./packages/client/src/server-only.browser.mjs",