@gravito/mass 3.0.1 → 3.0.3

package/dist/errors.d.ts

@@ -0,0 +1,168 @@
+import type { ValueError } from '@sinclair/typebox/errors';
+import type { ValidationSource } from './types';
+/**
+ * Error Messages - Traditional Chinese
+ *
+ * Provides common validation error messages in Traditional Chinese.
+ */
+export declare const ERROR_MESSAGES_ZH_TW: {
+    readonly REQUIRED: "此欄位為必填";
+    readonly INVALID_TYPE: "資料型別不正確";
+    readonly INVALID_EMAIL: "電子郵件格式不正確";
+    readonly INVALID_URL: "網址格式不正確";
+    readonly INVALID_UUID: "UUID 格式不正確";
+    readonly INVALID_DATE: "日期格式不正確";
+    readonly TOO_SHORT: "長度過短";
+    readonly TOO_LONG: "長度過長";
+    readonly TOO_SMALL: "數值過小";
+    readonly TOO_LARGE: "數值過大";
+    readonly INVALID_PATTERN: "格式不符合規則";
+    readonly INVALID_FORMAT: "格式不正確";
+};
+/**
+ * Error Messages - English
+ *
+ * Provides common validation error messages in English.
+ */
+export declare const ERROR_MESSAGES_EN: {
+    readonly REQUIRED: "This field is required";
+    readonly INVALID_TYPE: "Invalid data type";
+    readonly INVALID_EMAIL: "Invalid email format";
+    readonly INVALID_URL: "Invalid URL format";
+    readonly INVALID_UUID: "Invalid UUID format";
+    readonly INVALID_DATE: "Invalid date format";
+    readonly TOO_SHORT: "Too short";
+    readonly TOO_LONG: "Too long";
+    readonly TOO_SMALL: "Value too small";
+    readonly TOO_LARGE: "Value too large";
+    readonly INVALID_PATTERN: "Does not match required pattern";
+    readonly INVALID_FORMAT: "Invalid format";
+};
+/**
+ * Error Formatter Function Type
+ *
+ * Function type for converting TypeBox errors into a custom format.
+ */
+export type ErrorFormatter = (error: ValueError) => {
+    path: string;
+    message: string;
+    expected?: string;
+    received?: string;
+};
+/**
+ * Custom error class thrown or returned when validation fails.
+ *
+ * This class encapsulates the validation error details and the source of the data
+ * (e.g., 'json', 'query') that failed validation. It is suitable for use in
+ * exception filters or global error handlers.
+ *
+ * @example
+ * ```typescript
+ * throw new MassValidationError('json', [
+ *   { path: '/email', message: 'Invalid email format' }
+ * ])
+ * ```
+ */
+export declare class MassValidationError extends Error {
+    readonly source: ValidationSource;
+    readonly errors: Array<{
+        path: string;
+        message: string;
+    }>;
+    /**
+     * Creates a new MassValidationError instance.
+     *
+     * @param source - The source of the invalid data
+     * @param errors - The list of validation errors
+     */
+    constructor(source: ValidationSource, errors: Array<{
+        path: string;
+        message: string;
+    }>);
+    /**
+     * Serializes the error to a JSON-compatible object.
+     *
+     * @returns A structured error object suitable for API responses
+     */
+    toJSON(): {
+        error: string;
+        source: ValidationSource;
+        details: {
+            path: string;
+            message: string;
+        }[];
+    };
+}
+/**
+ * Enhances TypeBox Validation Errors.
+ *
+ * Converts raw TypeBox errors into structured error objects with more context,
+ * suitable for returning directly to clients or logging.
+ *
+ * @param error - The raw TypeBox validation error
+ * @param locale - Locale ('zh-TW' or 'en'), defaults to 'zh-TW'
+ * @returns Enhanced error object
+ *
+ * @example
+ * ```typescript
+ * import { Value } from '@sinclair/typebox/value'
+ *
+ * const errors = [...Value.Errors(schema, data)]
+ * const enhanced = errors.map(err => enhanceError(err, 'zh-TW'))
+ * // [{ path: '/email', message: '電子郵件格式不正確', expected: 'string<email>', received: 'string' }]
+ * ```
+ */
+export declare function enhanceError(error: ValueError, locale?: 'zh-TW' | 'en'): {
+    path: string;
+    message: string;
+    expected?: string;
+    received?: string;
+};
+/**
+ * Creates Custom Error Formatter.
+ *
+ * High-order function that allows creating custom error formatting logic for TypeBox validation errors.
+ * Useful for standardizing error formats or supporting multiple languages.
+ *
+ * @param formatter - Custom formatter function
+ * @returns Error formatter function
+ *
+ * @example
+ * ```typescript
+ * const myFormatter = createErrorFormatter((error) => ({
+ *   path: error.path,
+ *   message: `Custom Message: ${error.message}`,
+ *   code: 'VALIDATION_ERROR'
+ * }))
+ *
+ * const errors = [...Value.Errors(schema, data)]
+ * const formatted = errors.map(myFormatter)
+ * ```
+ */
+export declare function createErrorFormatter(formatter: (error: ValueError) => {
+    path: string;
+    message: string;
+    [key: string]: unknown;
+}): ErrorFormatter;
+/**
+ * Formats a flat list of validation errors into a field-grouped structure.
+ *
+ * This helper transforms TypeBox's error format into a more frontend-friendly
+ * format where errors are grouped by field name.
+ *
+ * @param errors - The raw validation errors
+ * @returns An object where keys are field names and values are arrays of error messages
+ *
+ * @example
+ * ```typescript
+ * const errors = [{ path: '/user/name', message: 'Required' }]
+ * const formatted = formatErrors(errors)
+ * // Result: { fields: { 'user.name': ['Required'] } }
+ * ```
+ */
+export declare function formatErrors(errors: Array<{
+    path: string;
+    message: string;
+}>): {
+    fields: Record<string, string[]>;
+};

package/dist/formats.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Pre-registered Format Names.
+ *
+ * Provides common data format validators including email, url, uuid, date-time, etc.
+ */
+export declare const REGISTERED_FORMATS: readonly ["email", "uri", "uri-reference", "uuid", "date-time", "date", "time", "ipv4", "ipv6"];
+export type RegisteredFormat = (typeof REGISTERED_FORMATS)[number];
+/**
+ * Registers Custom Format Validator.
+ *
+ * Allows registering custom format validation logic to TypeBox's FormatRegistry.
+ * Once registered, can be used in Schema.String() via the format option.
+ *
+ * @param name - Format name (e.g., 'phone-number', 'credit-card')
+ * @param validator - Validation function, returns true if valid
+ *
+ * @example Register Taiwan Phone Number Format
+ * ```typescript
+ * registerFormat('tw-phone', (value) => /^09\d{8}$/.test(value))
+ *
+ * const schema = Schema.String({ format: 'tw-phone' })
+ * const valid = Value.Check(schema, '0912345678') // true
+ * ```
+ *
+ * @example Register Credit Card Format (Simplified)
+ * ```typescript
+ * registerFormat('credit-card', (value) => {
+ *   const cleaned = value.replace(/\s/g, '')
+ *   return /^\d{13,19}$/.test(cleaned)
+ * })
+ * ```
+ */
+export declare function registerFormat(name: string, validator: (value: string) => boolean): void;
+/**
+ * Registers All Predefined Format Validators.
+ *
+ * Registers all common formats (email, url, uuid, etc.) to TypeBox's FormatRegistry.
+ * Typically called once at application startup.
+ *
+ * @example Register at Application Entry Point
+ * ```typescript
+ * import { registerAllFormats } from '@gravito/mass'
+ *
+ * // Register all predefined formats
+ * registerAllFormats()
+ *
+ * // Now you can use these formats in schemas
+ * const userSchema = Schema.Object({
+ *   email: Schema.String({ format: 'email' }),
+ *   website: Schema.String({ format: 'uri' }),
+ *   id: Schema.String({ format: 'uuid' })
+ * })
+ * ```
+ */
+export declare function registerAllFormats(): void;
+/**
+ * Checks if a Specific Format is Registered.
+ *
+ * @param name - Format name
+ * @returns True if the format is registered
+ *
+ * @example
+ * ```typescript
+ * registerFormat('custom-format', (value) => true)
+ * isFormatRegistered('custom-format') // true
+ * isFormatRegistered('unknown-format') // false
+ * ```
+ */
+export declare function isFormatRegistered(name: string): boolean;
+/**
+ * Gets Registered Format Validator.
+ *
+ * @param name - Format name
+ * @returns Validation function, or undefined if not registered
+ *
+ * @example
+ * ```typescript
+ * const emailValidator = getFormatValidator('email')
+ * if (emailValidator) {
+ *   const isValid = emailValidator('test@example.com') // true
+ * }
+ * ```
+ */
+export declare function getFormatValidator(name: string): ((value: string) => boolean) | undefined;
+/**
+ * Removes Registered Format Validator.
+ *
+ * @param name - Format name
+ *
+ * @example
+ * ```typescript
+ * registerFormat('temp-format', (value) => true)
+ * unregisterFormat('temp-format')
+ * isFormatRegistered('temp-format') // false
+ * ```
+ */
+export declare function unregisterFormat(name: string): void;

package/dist/index.d.ts

@@ -0,0 +1,79 @@
+/**
+ * @gravito/mass - TypeBox-based validation for Gravito Galaxy Architecture.
+ *
+ * Mass provides high-performance schema validation with full TypeScript support,
+ * seamlessly integrating with Photon middleware system. Named after the concept
+ * of "mass" in physics, this package provides the "weight" of data integrity
+ * to your API endpoints.
+ *
+ * ## Key Features
+ *
+ * - **Zero-overhead TypeBox validation** - Generates validators at build-time for faster runtime performance
+ * - **Full TypeScript inference** - Validated data is fully typed without manual typings
+ * - **Multiple validation sources** - Validate JSON, query, params, and form data
+ * - **Custom error handling hooks** - Override default error responses
+ * - **Seamless Photon/Hono integration** - Works out of the box with Gravito's HTTP layer
+ *
+ * @example Basic JSON validation
+ * ```typescript
+ * import { Photon } from '@gravito/photon'
+ * import { Schema, validate } from '@gravito/mass'
+ *
+ * const app = new Photon()
+ *
+ * const loginSchema = Schema.Object({
+ *   username: Schema.String({ minLength: 3, maxLength: 50 }),
+ *   password: Schema.String({ minLength: 8 })
+ * })
+ *
+ * app.post('/login', validate('json', loginSchema), (c) => {
+ *   const { username } = c.req.valid('json')
+ *   // username is fully typed as string
+ *   return c.json({ success: true, user: username })
+ * })
+ * ```
+ *
+ * @example Custom error handling
+ * ```typescript
+ * app.post('/register',
+ *   validate('json', registerSchema, (result, c) => {
+ *     if (!result.success) {
+ *       return c.json({
+ *         error: 'Validation failed',
+ *         details: result.errors
+ *       }, 400)
+ *     }
+ *   }),
+ *   handler
+ * )
+ * ```
+ *
+ * @example Query parameter validation
+ * ```typescript
+ * const searchSchema = Schema.Object({
+ *   q: Schema.String(),
+ *   page: Schema.Optional(Schema.Number({ minimum: 1, default: 1 })),
+ *   limit: Schema.Optional(Schema.Number({ minimum: 1, maximum: 100, default: 20 }))
+ * })
+ *
+ * app.get('/search', validate('query', searchSchema), (c) => {
+ *   const { q, page, limit } = c.req.valid('query')
+ *   return c.json({ query: q, page, limit })
+ * })
+ * ```
+ *
+ * @see {@link validate} - Main validation middleware
+ * @see {@link Schema} - TypeBox schema builders
+ * @see {@link https://github.com/sinclairzx81/typebox | TypeBox Documentation}
+ *
+ * @packageDocumentation
+ */
+export type { Static, TSchema } from '@sinclair/typebox';
+export * as Schema from '@sinclair/typebox';
+export { CoercibleBoolean, CoercibleInteger, CoercibleNumber, coerceBoolean, coerceData, coerceDate, coerceInteger, coerceNumber, validateWithCoercion, } from './coercion';
+export { createErrorFormatter, ERROR_MESSAGES_EN, ERROR_MESSAGES_ZH_TW, type ErrorFormatter, enhanceError, formatErrors, MassValidationError, } from './errors';
+export { getFormatValidator, isFormatRegistered, REGISTERED_FORMATS, type RegisteredFormat, registerAllFormats, registerFormat, unregisterFormat, } from './formats';
+export { type AstralResource, createAstralResource, createCrudResources, type OpenApiSchema, typeboxToOpenApi, } from './openapi';
+export type { ValidationError, ValidationHook, ValidationResult, } from './types';
+export { partial } from './utils';
+export { type ValidationSource, validate } from './validator';

package/dist/index.js

@@ -1,15 +1,30 @@
 // @bun
-// src/index.ts
-import { tbValidator as tbValidator2 } from "@hono/typebox-validator";
-import * as Schema from "@sinclair/typebox";
-
-// src/validator.ts
-import { tbValidator } from "@hono/typebox-validator";
-function validate(source, schema, hook) {
-  return tbValidator(source, schema, hook);
-}
 export {
-  tbValidator2 as validator,
+  validateWithCoercion,
   validate,
-  Schema
+  unregisterFormat,
+  typeboxToOpenApi,
+  registerFormat,
+  registerAllFormats,
+  partial,
+  isFormatRegistered,
+  getFormatValidator,
+  formatErrors,
+  enhanceError,
+  createErrorFormatter,
+  createCrudResources,
+  createAstralResource,
+  coerceNumber,
+  coerceInteger,
+  coerceDate,
+  coerceData,
+  coerceBoolean,
+  Schema,
+  REGISTERED_FORMATS,
+  MassValidationError,
+  ERROR_MESSAGES_ZH_TW,
+  ERROR_MESSAGES_EN,
+  CoercibleNumber,
+  CoercibleInteger,
+  CoercibleBoolean
 };

package/dist/openapi.d.ts

@@ -0,0 +1,214 @@
+import type { TSchema } from '@sinclair/typebox';
+/**
+ * OpenAPI Schema Object Type
+ *
+ * Represents a Schema Object in the OpenAPI 3.0 specification.
+ */
+export interface OpenApiSchema {
+    type?: string;
+    format?: string;
+    description?: string;
+    enum?: unknown[];
+    items?: OpenApiSchema;
+    properties?: Record<string, OpenApiSchema>;
+    required?: string[];
+    additionalProperties?: boolean | OpenApiSchema;
+    minLength?: number;
+    maxLength?: number;
+    minimum?: number;
+    maximum?: number;
+    pattern?: string;
+    default?: unknown;
+    example?: unknown;
+    nullable?: boolean;
+    readOnly?: boolean;
+    writeOnly?: boolean;
+    deprecated?: boolean;
+    [key: string]: unknown;
+}
+/**
+ * Astral Resource Definition Type
+ *
+ * Represents the resource definition for Gravito Astral automatic API documentation.
+ */
+export interface AstralResource {
+    path: string;
+    method: string;
+    summary?: string;
+    description?: string;
+    tags?: string[];
+    requestBody?: {
+        description?: string;
+        required?: boolean;
+        content: {
+            'application/json': {
+                schema: OpenApiSchema;
+            };
+        };
+    };
+    responses: {
+        [statusCode: string]: {
+            description: string;
+            content?: {
+                'application/json': {
+                    schema: OpenApiSchema;
+                };
+            };
+        };
+    };
+}
+/**
+ * Converts a TypeBox Schema to an OpenAPI Schema.
+ *
+ * This function transforms TypeBox schema definitions into OpenAPI 3.0 compliant schema objects,
+ * suitable for automatic API documentation generation or integration with third-party tools.
+ *
+ * @param schema - The TypeBox schema object
+ * @returns An OpenAPI Schema object
+ *
+ * @example Basic Type Conversion
+ * ```typescript
+ * import { Type } from '@sinclair/typebox'
+ *
+ * const schema = Type.String({ minLength: 3, maxLength: 50 })
+ * const openapi = typeboxToOpenApi(schema)
+ * // {
+ * //   type: 'string',
+ * //   minLength: 3,
+ * //   maxLength: 50
+ * // }
+ * ```
+ *
+ * @example Object Type Conversion
+ * ```typescript
+ * const userSchema = Type.Object({
+ *   name: Type.String(),
+ *   email: Type.String({ format: 'email' }),
+ *   age: Type.Optional(Type.Number({ minimum: 0 }))
+ * })
+ *
+ * const openapi = typeboxToOpenApi(userSchema)
+ * // {
+ * //   type: 'object',
+ * //   properties: {
+ * //     name: { type: 'string' },
+ * //     email: { type: 'string', format: 'email' },
+ * //     age: { type: 'number', minimum: 0 }
+ * //   },
+ * //   required: ['name', 'email']
+ * // }
+ * ```
+ */
+export declare function typeboxToOpenApi(schema: TSchema): OpenApiSchema;
+/**
+ * Creates an Astral Resource Definition.
+ *
+ * This function builds resource definitions for the Gravito Astral automatic API documentation system,
+ * combining TypeBox schemas with HTTP route information to generate complete API endpoint documentation.
+ *
+ * @param options - Resource definition options
+ * @returns Astral Resource Definition object
+ *
+ * @example Create POST endpoint resource
+ * ```typescript
+ * const createUserResource = createAstralResource({
+ *   path: '/users',
+ *   method: 'POST',
+ *   summary: 'Create New User',
+ *   description: 'Creates a new user account with the provided data',
+ *   tags: ['users'],
+ *   requestSchema: Type.Object({
+ *     name: Type.String({ minLength: 1 }),
+ *     email: Type.String({ format: 'email' }),
+ *     password: Type.String({ minLength: 8 })
+ *   }),
+ *   responseSchema: Type.Object({
+ *     id: Type.String({ format: 'uuid' }),
+ *     name: Type.String(),
+ *     email: Type.String(),
+ *     createdAt: Type.String({ format: 'date-time' })
+ *   }),
+ *   responseStatusCode: 201
+ * })
+ * ```
+ *
+ * @example Create GET endpoint resource (no request body)
+ * ```typescript
+ * const getUsersResource = createAstralResource({
+ *   path: '/users',
+ *   method: 'GET',
+ *   summary: 'Get User List',
+ *   tags: ['users'],
+ *   responseSchema: Type.Array(
+ *     Type.Object({
+ *       id: Type.String(),
+ *       name: Type.String()
+ *     })
+ *   )
+ * })
+ * ```
+ */
+export declare function createAstralResource(options: {
+    path: string;
+    method: string;
+    summary?: string;
+    description?: string;
+    tags?: string[];
+    requestSchema?: TSchema;
+    requestDescription?: string;
+    requestRequired?: boolean;
+    responseSchema: TSchema;
+    responseDescription?: string;
+    responseStatusCode?: number;
+}): AstralResource;
+/**
+ * Batch creates CRUD Resource Definitions.
+ *
+ * Automatically generates all relevant Astral resource definitions for standard CRUD operations.
+ *
+ * @param options - CRUD resource options
+ * @returns CRUD Resource Definition object
+ *
+ * @example Create full User CRUD resources
+ * ```typescript
+ * const userCrudResources = createCrudResources({
+ *   resourceName: 'user',
+ *   basePath: '/users',
+ *   tags: ['users'],
+ *   schemas: {
+ *     item: Type.Object({
+ *       id: Type.String({ format: 'uuid' }),
+ *       name: Type.String(),
+ *       email: Type.String({ format: 'email' })
+ *     }),
+ *     create: Type.Object({
+ *       name: Type.String(),
+ *       email: Type.String({ format: 'email' })
+ *     }),
+ *     update: Type.Partial(Type.Object({
+ *       name: Type.String(),
+ *       email: Type.String({ format: 'email' })
+ *     }))
+ *   }
+ * })
+ *
+ * // Returns: { list, get, create, update, delete }
+ * ```
+ */
+export declare function createCrudResources(options: {
+    resourceName: string;
+    basePath: string;
+    tags?: string[];
+    schemas: {
+        item: TSchema;
+        list?: TSchema;
+        create: TSchema;
+        update: TSchema;
+    };
+}): {
+    list: AstralResource;
+    get: AstralResource;
+    create: AstralResource;
+    update: AstralResource;
+    delete: AstralResource;
+};

package/dist/types.d.ts

@@ -0,0 +1,50 @@
+import type { GravitoContext } from '@gravito/photon';
+import type { Static, TSchema } from '@sinclair/typebox';
+/**
+ * Supported data sources for validation.
+ *
+ * Determines which part of the HTTP request should be validated against the schema.
+ */
+export type ValidationSource = 'json' | 'query' | 'param' | 'form';
+/**
+ * Details of a validation error.
+ *
+ * Provides structured information about why a specific field failed validation.
+ */
+export interface ValidationError {
+    /** The path to the invalid field (e.g., "/user/name") */
+    path: string;
+    /** A human-readable description of the error */
+    message: string;
+    /** The value or type that was expected */
+    expected?: string;
+    /** The value or type that was actually received */
+    received?: string;
+}
+/**
+ * The outcome of a validation attempt.
+ *
+ * Passed to validation hooks to allow custom handling of success or failure states.
+ *
+ * @template T - The TypeBox schema type used for validation
+ */
+export interface ValidationResult<T extends TSchema> {
+    /** Indicates whether the data satisfied the schema */
+    success: boolean;
+    /** The validated and typed data (only present if success is true) */
+    data?: Static<T>;
+    /** A list of validation errors (only present if success is false) */
+    errors?: ValidationError[];
+}
+/**
+ * A callback function for intercepting validation results.
+ *
+ * Use this hook to customize error responses, log failures, or transform data
+ * after validation but before the main route handler.
+ *
+ * @template T - The TypeBox schema type
+ * @param result - The outcome of the validation
+ * @param context - The Photon request context
+ * @returns A Response object to short-circuit the request, or undefined to proceed
+ */
+export type ValidationHook<T extends TSchema> = (result: ValidationResult<T>, context: GravitoContext) => Response | Promise<Response> | undefined;

package/dist/utils.d.ts

@@ -0,0 +1,22 @@
+import type { TObject, TPartial } from '@sinclair/typebox';
+/**
+ * Creates a new schema with all properties of the original schema set to optional.
+ *
+ * This utility is useful for creating "update" schemas (e.g., for PATCH requests)
+ * where clients can send a subset of fields to update.
+ *
+ * @param schema - The original TypeBox object schema
+ * @returns A new schema with all properties marked as optional
+ *
+ * @example
+ * ```typescript
+ * const userSchema = Schema.Object({
+ *   name: Schema.String(),
+ *   email: Schema.String()
+ * })
+ *
+ * // All fields in updateSchema are optional
+ * const updateSchema = partial(userSchema)
+ * ```
+ */
+export declare function partial<T extends TObject>(schema: T): TPartial<T>;