@chidchanun/bcp 0.1.17 → 0.1.19

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.17",
+  "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",