@gravito/mass 3.0.1 → 3.0.3

package/README.md

@@ -1,23 +1,46 @@
-# @gravito/mass
+# @gravito/mass ⚖️
 
-TypeBox-based validation for Gravito. High-performance schema validation with full TypeScript support.
+> High-performance, TypeBox-powered schema validation for Gravito Galaxy Architecture.
 
-## Features
+`@gravito/mass` provides the "weight" of data integrity to your Gravito applications. Built on top of **TypeBox**, it offers ultra-fast runtime validation with full TypeScript type inference, designed to work seamlessly with the **Photon** HTTP engine.
 
-- **Fast validation**: TypeBox-powered validators with strong runtime performance
-- **Full TypeScript support**: Type inference without manual typings
-- **Photon integration**: Works seamlessly with Photon validation middleware
-- **Multiple sources**: Validate JSON, query, params, and form data
+## ✨ Key Features
 
-## Installation
+- 🚀 **Performance-First**: Built on TypeBox, it generates ultra-fast validators that outperform standard libraries like Zod.
+- 🌌 **Galaxy-Ready**: The "Data Quality Layer" ensuring integrity across all Gravito Satellites and Orbits.
+- 🛡️ **Full Type Safety**: Zero-config type inference—your schemas are your TypeScript types.
+- 📡 **Beam Integration**: Share schemas between backend and frontend for end-to-end type-safe RPC.
+- 🔌 **Photon Integration**: Native middleware for `@gravito/photon` to validate JSON, query, params, and form data.
+- 📦 **Binary (CBOR) Support**: Optimized validation for binary protocols in high-performance microservices.
+
+## 🌌 Role in Galaxy Architecture
+
+In the **Gravito Galaxy Architecture**, Mass serves as the **Data Quality Layer (Immune System)**.
+
+- **Sensing Filter**: Acts as the first line of defense in the `Photon` Sensing Layer, filtering out malformed or malicious data before it reaches your business logic.
+- **Contract Definition**: Provides the shared language (Schemas) used by `Beam` to ensure that Satellites and clients communicate with perfect understanding.
+- **Type Propagation**: Injects strong types from the edge of the network into the deepest parts of your IoC container.
+
+```mermaid
+graph LR
+    Request([Request]) --> Mass{Mass Filter}
+    Mass -- "Valid" --> Satellite[Satellite Business Logic]
+    Mass -- "Invalid" --> Error[400 Bad Request]
+    Satellite -- "Beam RPC" --> Client([Typed Client])
+    Mass -.->|Schema| Client
+```
+
+## 📦 Installation
 
 ```bash
 bun add @gravito/mass
 ```
 
-## Quick Start
+## 🚀 Quick Start
 
-### JSON validation
+### Basic JSON Validation
+
+Define a schema using `Schema` and apply it to your routes using the `validate` middleware.
 
 ```typescript
 import { Photon } from '@gravito/photon'
@@ -25,40 +48,39 @@ import { Schema, validate } from '@gravito/mass'
 
 const app = new Photon()
 
-app.post('/login',
-  validate('json', Schema.Object({
-    username: Schema.String(),
-    password: Schema.String()
-  })),
+const CreateUserSchema = Schema.Object({
+  username: Schema.String({ minLength: 3 }),
+  email: Schema.String({ format: 'email' }),
+  age: Schema.Number({ minimum: 18 })
+})
+
+app.post('/users', 
+  validate('json', CreateUserSchema), 
   (c) => {
-    const { username } = c.req.valid('json')
-    return c.json({ success: true, message: `Welcome ${username}` })
+    // Data is fully typed as { username: string; email: string; age: number }
+    const user = c.req.valid('json')
+    return c.json({ success: true, data: user })
   }
 )
 ```
 
-### Query validation
+### Validating Different Sources
+
+Mass can validate data from various parts of the HTTP request:
 
 ```typescript
-app.get('/search',
-  validate('query', Schema.Object({
-    q: Schema.String(),
-    page: Schema.Optional(Schema.Number())
-  })),
+// Query Parameters
+app.get('/search', 
+  validate('query', Schema.Object({ q: Schema.String() })),
   (c) => {
-    const { q, page } = c.req.valid('query')
-    return c.json({ query: q, page: page ?? 1 })
+    const { q } = c.req.valid('query')
+    return c.text(`Searching for: ${q}`)
   }
 )
-```
-
-### Route param validation
 
-```typescript
+// URL Parameters
 app.get('/users/:id',
-  validate('param', Schema.Object({
-    id: Schema.String({ pattern: '^[0-9]+$' })
-  })),
+  validate('param', Schema.Object({ id: Schema.Number() })),
   (c) => {
     const { id } = c.req.valid('param')
     return c.json({ userId: id })
@@ -66,65 +88,77 @@ app.get('/users/:id',
 )
 ```
 
-## Schema Builder
+## ⏳ Advanced Patterns
+
+### Partial Updates (PATCH)
 
-`Schema` exposes TypeBox constructors:
+Use the `partial()` utility to make all properties of a schema optional, perfect for update endpoints.
 
 ```typescript
-import { Schema } from '@gravito/mass'
+import { partial } from '@gravito/mass'
 
-Schema.String()
-Schema.Number()
-Schema.Boolean()
-Schema.Array(Schema.String())
+const UpdateUserSchema = partial(CreateUserSchema)
 
-Schema.Object({
-  name: Schema.String(),
-  age: Schema.Number()
-})
-
-Schema.Optional(Schema.String())
-Schema.String({ default: 'hello' })
-Schema.String({ minLength: 2, maxLength: 100 })
-Schema.Number({ minimum: 0, maximum: 100 })
-Schema.String({ format: 'email' })
+app.patch('/users/:id', 
+  validate('json', UpdateUserSchema), 
+  (c) => {
+    const updates = c.req.valid('json')
+    return c.json({ updated: updates })
+  }
+)
 ```
 
-## Beam Client Integration
+### Custom Error Handling
 
-When you compose routes with `app.route()`, you get full type inference for the client:
+Override the default 400 response with your own error format using the validation hook.
 
 ```typescript
-// app.ts
-import { Photon } from '@gravito/photon'
-import { userRoute } from './routes/user'
+app.post('/strict-endpoint',
+  validate('json', schema, (result, c) => {
+    if (!result.success) {
+      return c.json({
+        code: 'VAL_ERR',
+        errors: result.errors.map(e => ({ field: e.path, msg: e.message }))
+      }, 422)
+    }
+  }),
+  (c) => c.text('Success')
+)
+```
 
-const app = new Photon()
-const routes = app.route('/api/users', userRoute)
+## 🧩 API Reference
 
-export default app
-export type AppRoutes = typeof routes
-```
+### `validate(source, schema, hook?)`
+Main middleware for schema enforcement.
+- `source`: `'json' | 'query' | 'param' | 'form'`
+- `schema`: A TypeBox schema instance.
+- `hook`: `(result, context) => Response | undefined`
 
-```typescript
-// client.ts
-import { createBeam } from '@gravito/beam'
-import type { AppRoutes } from './types'
+### `Schema`
+The central builder for defining data structures. Re-exports all TypeBox builders.
+- `Schema.String()`
+- `Schema.Number()`
+- `Schema.Boolean()`
+- `Schema.Object({ ... })`
+- `Schema.Array(...)`
+- `Schema.Optional(...)`
 
-export const createClient = (baseUrl: string) => {
-  return createBeam<AppRoutes>(baseUrl)
-}
+### `partial(schema)`
+Recursively makes all properties in an object schema optional.
 
-const client = createClient('http://localhost:3000')
-const result = await client.api.users.login.$post({
-  json: { username: 'user', password: 'pass' }
-})
-```
+## 📚 Documentation
+
+Detailed guides and references for the Galaxy Architecture:
+
+- [🏗️ **Architecture Overview**](./README.md) — Data integrity and schema validation.
+- [📐 **Schema Design**](./doc/SCHEMA_DESIGN.md) — **NEW**: Best practices for domain-specific schemas and composition.
+- [🛡️ **Validation Strategy**](./doc/VALIDATION_STRATEGY.md) — **NEW**: Multi-source validation, hooks, and performance tuning.
+- [🔌 **Photon Integration**](#-photon-integration) — Native middleware for request validation.
 
-## Performance Notes
+## 🤝 Contributing
 
-TypeBox generates validators at build-time for faster runtime performance, smaller bundles, and strong TypeScript inference.
+We welcome contributions! Please see our [Contributing Guide](../../CONTRIBUTING.md) for details.
 
-## License
+## 📄 License
 
-MIT
+MIT © Carl Lee

package/README.zh-TW.md

@@ -1,14 +1,29 @@
-# @gravito/mass
+# @gravito/mass ⚖️
 
-> Gravito 的 TypeBox 驗證模組，提供高效能且完整的 TypeScript 支援。
+> 基於 TypeBox 的高效能 Schema 驗證工具，專為 Gravito Galaxy 架構設計。
 
-## 安裝
+`@gravito/mass` 為您的 Gravito 應用程式提供數據完整性的「重量」。基於 **TypeBox** 構建，它提供了極快的執行期驗證速度與完整的 TypeScript 類型推導，並與 **Photon** HTTP 引擎無縫整合。
+
+## 🌟 核心特性
+
+- **🚀 效能優先**：利用 TypeBox 的編譯期驗證器生成技術，實現近乎零負擔的執行期效能。
+- **🛡️ 完整類型安全**：自動進行 TypeScript 類型推導 —— 無需分別維護 Interface 與 Schema。
+- **🔌 Photon 深度整合**：提供原生中間件，支援驗證 JSON、Query、URL 參數及表單數據。
+- **🛠️ Schema 實用工具**：提供如 `partial()` 等進階輔助函式，輕鬆建立 PATCH 接口所需的 Schema。
+- **🪝 靈活的 Hook 機制**：可攔截驗證結果，自定義錯誤回應格式或紀錄日誌。
+- **📦 Galaxy 架構相容**：遵循 Gravito 的模組化哲學，保持依賴精簡且高效。
+
+## 📦 安裝
 
 ```bash
 bun add @gravito/mass
 ```
 
-## 快速開始
+## 🚀 快速上手
+
+### 基礎 JSON 驗證
+
+使用 `Schema` 定義數據結構，並透過 `validate` 中間件應用於路由。
 
 ```typescript
 import { Photon } from '@gravito/photon'
@@ -16,14 +31,108 @@ import { Schema, validate } from '@gravito/mass'
 
 const app = new Photon()
 
-app.post('/login',
-  validate('json', Schema.Object({
-    username: Schema.String(),
-    password: Schema.String()
-  })),
+const CreateUserSchema = Schema.Object({
+  username: Schema.String({ minLength: 3 }),
+  email: Schema.String({ format: 'email' }),
+  age: Schema.Number({ minimum: 18 })
+})
+
+app.post('/users', 
+  validate('json', CreateUserSchema), 
+  (c) => {
+    // 數據已自動推導類型為 { username: string; email: string; age: number }
+    const user = c.req.valid('json')
+    return c.json({ success: true, data: user })
+  }
+)
+```
+
+### 驗證不同數據源
+
+Mass 可以驗證 HTTP 請求中不同位置的數據：
+
+```typescript
+// 驗證 Query 參數
+app.get('/search', 
+  validate('query', Schema.Object({ q: Schema.String() })),
   (c) => {
-    const { username } = c.req.valid('json')
-    return c.json({ success: true, message: `Welcome ${username}` })
+    const { q } = c.req.valid('query')
+    return c.text(`正在搜尋：${q}`)
+  }
+)
+
+// 驗證 URL 參數
+app.get('/users/:id',
+  validate('param', Schema.Object({ id: Schema.Number() })),
+  (c) => {
+    const { id } = c.req.valid('param')
+    return c.json({ userId: id })
   }
 )
 ```
+
+## ⏳ 進階模式
+
+### 部分更新 (PATCH)
+
+使用 `partial()` 工具將 Schema 中的所有屬性轉為可選，非常適合用於更新接口。
+
+```typescript
+import { partial } from '@gravito/mass'
+
+const UpdateUserSchema = partial(CreateUserSchema)
+
+app.patch('/users/:id', 
+  validate('json', UpdateUserSchema), 
+  (c) => {
+    const updates = c.req.valid('json')
+    return c.json({ updated: updates })
+  }
+)
+```
+
+### 自定義錯誤處理
+
+透過驗證 Hook 覆蓋預設的 400 回應，提供符合您需求的錯誤格式。
+
+```typescript
+app.post('/strict-endpoint',
+  validate('json', schema, (result, c) => {
+    if (!result.success) {
+      return c.json({
+        code: 'VAL_ERR',
+        errors: result.errors.map(e => ({ field: e.path, msg: e.message }))
+      }, 422)
+    }
+  }),
+  (c) => c.text('成功')
+)
+```
+
+## 🧩 API 參考
+
+### `validate(source, schema, hook?)`
+強制執行 Schema 驗證的主要中間件。
+- `source`: `'json' | 'query' | 'param' | 'form'`
+- `schema`: TypeBox Schema 實例。
+- `hook`: `(result, context) => Response | undefined`
+
+### `Schema`
+定義數據結構的核心工具，重新導出了所有 TypeBox 的建構子。
+- `Schema.String()`
+- `Schema.Number()`
+- `Schema.Boolean()`
+- `Schema.Object({ ... })`
+- `Schema.Array(...)`
+- `Schema.Optional(...)`
+
+### `partial(schema)`
+遞迴地將物件 Schema 中的所有屬性設為可選。
+
+## 🤝 參與貢獻
+
+我們歡迎任何形式的貢獻！詳細資訊請參閱 [貢獻指南](../../CONTRIBUTING.md)。
+
+## 📄 開源授權
+
+MIT © Carl Lee

package/dist/coercion.d.ts

@@ -0,0 +1,222 @@
+import type { GravitoContext, GravitoMiddleware } from '@gravito/core';
+import type { TBoolean, TInteger, TNumber, TSchema } from '@sinclair/typebox';
+/**
+ * String to Number Coercion Helper.
+ *
+ * Converts a string value from query or params to a JavaScript Number.
+ *
+ * @param value - The string value to coerce
+ * @returns The converted number, or NaN if conversion fails
+ *
+ * @example
+ * ```typescript
+ * coerceNumber('123') // 123
+ * coerceNumber('12.34') // 12.34
+ * coerceNumber('abc') // NaN
+ * ```
+ */
+export declare function coerceNumber(value: string): number;
+/**
+ * String to Integer Coercion Helper.
+ *
+ * Converts a string value from query or params to a JavaScript Number (Integer).
+ *
+ * @param value - The string value to coerce
+ * @returns The converted integer, or NaN if conversion fails
+ *
+ * @example
+ * ```typescript
+ * coerceInteger('123') // 123
+ * coerceInteger('12.99') // 12
+ * coerceInteger('abc') // NaN
+ * ```
+ */
+export declare function coerceInteger(value: string): number;
+/**
+ * String to Boolean Coercion Helper.
+ *
+ * Converts a string value from query or params to a JavaScript Boolean.
+ * Supports multiple common boolean string representations.
+ *
+ * @param value - The string value to coerce
+ * @returns The converted boolean value
+ *
+ * @example
+ * ```typescript
+ * coerceBoolean('true') // true
+ * coerceBoolean('1') // true
+ * coerceBoolean('yes') // true
+ * coerceBoolean('false') // false
+ * coerceBoolean('0') // false
+ * coerceBoolean('no') // false
+ * coerceBoolean('') // false
+ * ```
+ */
+export declare function coerceBoolean(value: string): boolean;
+/**
+ * String to Date Coercion Helper.
+ *
+ * Converts a string date (ISO 8601) from query or params to a JavaScript Date object.
+ *
+ * @param value - The string value (ISO 8601 format)
+ * @returns The converted Date object, or Invalid Date if conversion fails
+ *
+ * @example
+ * ```typescript
+ * coerceDate('2024-01-15') // Date object
+ * coerceDate('2024-01-15T10:30:00Z') // Date object
+ * coerceDate('invalid') // Invalid Date
+ * ```
+ */
+export declare function coerceDate(value: string): Date;
+/**
+ * Creates a Number Schema with Automatic Coercion.
+ *
+ * Builds a TypeBox Number schema that automatically converts string input to number before validation.
+ * Suitable for query and param validation where data sources are string-based.
+ *
+ * @param options - TypeBox Number schema options
+ * @returns TypeBox Number schema (with automatic coercion)
+ *
+ * @example Query Parameter Coercion
+ * ```typescript
+ * const searchSchema = Schema.Object({
+ *   page: CoercibleNumber({ minimum: 1, default: 1 }),
+ *   limit: CoercibleNumber({ minimum: 1, maximum: 100, default: 20 })
+ * })
+ *
+ * app.get('/search', validate('query', searchSchema), (c) => {
+ *   const { page, limit } = c.req.valid('query')
+ *   // page and limit are typed as number
+ *   return c.json({ page, limit })
+ * })
+ * ```
+ */
+export declare function CoercibleNumber(options?: Partial<TNumber['properties']> & {
+    default?: number;
+}): TNumber;
+/**
+ * Creates an Integer Schema with Automatic Coercion.
+ *
+ * Builds a TypeBox Integer schema that automatically converts string input to integer before validation.
+ *
+ * @param options - TypeBox Integer schema options
+ * @returns TypeBox Integer schema (with automatic coercion)
+ *
+ * @example
+ * ```typescript
+ * const schema = Schema.Object({
+ *   userId: CoercibleInteger({ minimum: 1 })
+ * })
+ * ```
+ */
+export declare function CoercibleInteger(options?: Partial<TInteger['properties']> & {
+    default?: number;
+}): TInteger;
+/**
+ * Creates a Boolean Schema with Automatic Coercion.
+ *
+ * Builds a TypeBox Boolean schema that automatically converts string input to boolean before validation.
+ *
+ * @param options - TypeBox Boolean schema options
+ * @returns TypeBox Boolean schema (with automatic coercion)
+ *
+ * @example
+ * ```typescript
+ * const schema = Schema.Object({
+ *   active: CoercibleBoolean({ default: false }),
+ *   published: CoercibleBoolean()
+ * })
+ * ```
+ */
+export declare function CoercibleBoolean(options?: Partial<TBoolean['properties']> & {
+    default?: boolean;
+}): TBoolean;
+/**
+ * Performs Automatic Data Coercion.
+ *
+ * Traverses the object and automatically converts string data to corresponding types
+ * based on the schema definition. Primarily used for pre-processing query and param data.
+ *
+ * @param data - The raw data object
+ * @param schema - The TypeBox schema definition
+ * @returns The coerced data object
+ *
+ * @example
+ * ```typescript
+ * const schema = Type.Object({
+ *   page: Type.Number(),
+ *   limit: Type.Number(),
+ *   active: Type.Boolean()
+ * })
+ *
+ * const raw = { page: '1', limit: '20', active: 'true' }
+ * const coerced = coerceData(raw, schema)
+ * // { page: 1, limit: 20, active: true }
+ * ```
+ */
+export declare function coerceData<T extends TSchema>(data: unknown, schema: T): unknown;
+/**
+ * Creates Validation Middleware with Automatic Coercion.
+ *
+ * Extends the standard validate middleware to automatically convert string data to appropriate
+ * types before validation. Especially useful for query and param validation where data sources
+ * are string-based.
+ *
+ * @template T - TypeBox schema type
+ *
+ * @param source - Validation source (recommend using 'query' or 'param')
+ * @param schema - TypeBox schema definition
+ * @param hook - Optional validation result hook
+ * @returns Gravito middleware handler
+ *
+ * @example Query Parameter Coercion
+ * ```typescript
+ * const searchSchema = Type.Object({
+ *   page: Type.Number({ minimum: 1 }),
+ *   limit: Type.Number({ minimum: 1, maximum: 100 }),
+ *   active: Type.Optional(Type.Boolean())
+ * })
+ *
+ * app.get('/search',
+ *   validateWithCoercion('query', searchSchema),
+ *   (c) => {
+ *     const { page, limit, active } = c.req.valid('query')
+ *     // All values are automatically coerced to correct types
+ *     return c.json({ page, limit, active })
+ *   }
+ * )
+ * ```
+ *
+ * @example Route Parameter Coercion
+ * ```typescript
+ * const paramSchema = Type.Object({
+ *   id: Type.Number({ minimum: 1 })
+ * })
+ *
+ * app.get('/users/:id',
+ *   validateWithCoercion('param', paramSchema),
+ *   (c) => {
+ *     const { id } = c.req.valid('param')
+ *     // id converted from string to number
+ *     return c.json({ userId: id })
+ *   }
+ * )
+ * ```
+ *
+ * @example With Custom Error Handling
+ * ```typescript
+ * app.get('/items',
+ *   validateWithCoercion('query', querySchema, (result, c) => {
+ *     if (!result.success) {
+ *       return c.json({
+ *         error: 'Invalid query parameters',
+ *         details: result.errors
+ *       }, 400)
+ *     }
+ *   }),
+ *   handler
+ * )
+ * ```
+ */
+export declare function validateWithCoercion<T extends TSchema>(source: 'json' | 'query' | 'param' | 'form', schema: T, hook?: (result: unknown, c: GravitoContext) => Response | Promise<Response> | undefined): GravitoMiddleware;