@gravito/mass 3.0.1 → 3.0.2

package/dist/errors.d.ts

@@ -0,0 +1,169 @@
+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[]>;
+};
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAA;AAC1D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAE/C;;;;GAIG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;CAavB,CAAA;AAEV;;;;GAIG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;CAapB,CAAA;AAEV;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,KAAK,EAAE,UAAU,KAAK;IAClD,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB,CAAA;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;aAQ1B,MAAM,EAAE,gBAAgB;aACxB,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IARlE;;;;;OAKG;gBAEe,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAMlE;;;;OAIG;IACH,MAAM;;;;kBAXkC,MAAM;qBAAW,MAAM;;;CAkBhE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,UAAU,EACjB,MAAM,GAAE,OAAO,GAAG,IAAc,GAC/B;IACD,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB,CAsDA;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK;IAChC,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB,GACA,cAAc,CAUhB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG;IAC9E,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;CACjC,CAYA"}

package/dist/formats.d.ts

@@ -0,0 +1,98 @@
+/**
+ * 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;
+//# sourceMappingURL=formats.d.ts.map

package/dist/formats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formats.d.ts","sourceRoot":"","sources":["../src/formats.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,iGAUrB,CAAA;AAEV,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAA;AAmFlE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,GAAG,IAAI,CAExF;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAIzC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAExD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,GAAG,SAAS,CAEzF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAEnD"}

package/dist/index.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @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 { tbValidator as validator } from '@hono/typebox-validator';
+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';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqEG;AAGH,OAAO,EAAE,WAAW,IAAI,SAAS,EAAE,MAAM,yBAAyB,CAAA;AAGlE,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAA;AAExD,OAAO,KAAK,MAAM,MAAM,mBAAmB,CAAA;AAE3C,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,aAAa,EACb,UAAU,EACV,UAAU,EACV,aAAa,EACb,YAAY,EACZ,oBAAoB,GACrB,MAAM,YAAY,CAAA;AAEnB,OAAO,EACL,oBAAoB,EACpB,iBAAiB,EACjB,oBAAoB,EACpB,KAAK,cAAc,EACnB,YAAY,EACZ,YAAY,EACZ,mBAAmB,GACpB,MAAM,UAAU,CAAA;AAEjB,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,KAAK,gBAAgB,EACrB,kBAAkB,EAClB,cAAc,EACd,gBAAgB,GACjB,MAAM,WAAW,CAAA;AAElB,OAAO,EACL,KAAK,cAAc,EACnB,oBAAoB,EACpB,mBAAmB,EACnB,KAAK,aAAa,EAClB,gBAAgB,GACjB,MAAM,WAAW,CAAA;AAElB,YAAY,EACV,eAAe,EACf,cAAc,EACd,gBAAgB,GACjB,MAAM,SAAS,CAAA;AAEhB,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AAEjC,OAAO,EAAE,KAAK,gBAAgB,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA"}