@zipbul/baker 2.0.0 → 2.1.0

package/README.md

@@ -1,18 +1,14 @@
 # @zipbul/baker
 
-Decorator-based validation + transformation with inline code generation. Zero `reflect-metadata`.
+The fastest decorator-based DTO validation library for TypeScript. Generates optimized validation code at class definition time (AOT), delivering **42ns per validation** — up to 163x faster than class-validator, 16x faster than Zod.
 
 ```bash
 bun add @zipbul/baker
 ```
 
-Requires `"experimentalDecorators": true` in `tsconfig.json`.
+Zero `reflect-metadata`. Zero runtime overhead. 1,890 tests. 99%+ line coverage.
 
-## API
-
-### `deserialize<T>(Class, input, options?): T | BakerErrors | Promise<T | BakerErrors>`
-
-Validates input and creates a class instance. Sync DTOs return directly. Async DTOs (async transform/rules) return Promise. Always safe to `await`.
+## Quick Start
 
 ```typescript
 import { deserialize, isBakerError, Field } from '@zipbul/baker';
@@ -24,92 +20,82 @@ class UserDto {
   @Field(isString, isEmail()) email!: string;
 }
 
-const result = await deserialize(UserDto, { name: 'Alice', age: 30, email: 'alice@test.com' });
+const result = await deserialize(UserDto, {
+  name: 'Alice', age: 30, email: 'alice@test.com',
+});
 
 if (isBakerError(result)) {
-  console.log(result.errors); // { path: string, code: string }[]
+  console.log(result.errors); // [{ path: 'email', code: 'isEmail' }]
 } else {
-  console.log(result.name);  // 'Alice'
+  console.log(result.name);   // 'Alice' — typed as UserDto
 }
 ```
 
-Never throws on validation failure. Throws `SealError` only for programming errors (no `@Field` decorators, banned field names).
+## Why Baker?
 
-### `validate(Class, input, options?): true | BakerErrors | Promise<true | BakerErrors>`
+Baker generates optimized JavaScript validation functions **once** at class definition time, then executes them on every call — no interpretation, no schema traversal, no runtime compilation cost after the first seal.
 
-Same validation as `deserialize` without instance creation.
+| Feature | baker | class-validator | Zod |
+|---|---|---|---|
+| Valid path (5 fields) | **42ns** | 6,852ns | 675ns |
+| Invalid path (5 fields) | **93ns** | 10,109ns | 7,948ns |
+| Approach | AOT code generation | Runtime interpretation | Schema method chain |
+| Decorators | `@Field` (unified) | 30+ individual | N/A |
+| `reflect-metadata` | Not needed | Required | N/A |
+| Sync DTO return | Direct value | Promise | Direct value |
 
-```typescript
-import { validate, isBakerError } from '@zipbul/baker';
+## Performance
 
-const result = await validate(UserDto, input);
-if (isBakerError(result)) { /* errors */ }
-```
+Benchmarked against 6 libraries on a simple 5-field DTO (valid + invalid input):
 
-### `validate(input, ...rules): true | BakerErrors | Promise<true | BakerErrors>`
+| Library | Valid | Invalid | vs baker (valid) | vs baker (invalid) |
+|---|---|---|---|---|
+| **baker** | **42ns** | **93ns** | — | — |
+| TypeBox | 123ns | 112ns | 2.9x slower | 1.2x slower |
+| AJV | 142ns | 201ns | 3.4x slower | 2.2x slower |
+| ArkType | 145ns | 8,591ns | 3.4x slower | 92x slower |
+| Valibot | 281ns | 1,070ns | 6.7x slower | 12x slower |
+| Zod | 675ns | 7,948ns | 16x slower | 85x slower |
+| class-validator | 6,852ns | 10,109ns | 163x slower | 109x slower |
 
-Ad-hoc single value validation. No DTO needed.
+## API
 
-```typescript
-const result = await validate('hello@test.com', isString, isEmail());
-// result === true
-```
+### `deserialize<T>(Class, input, options?)`
 
-### `serialize<T>(instance, options?): Record<string, unknown> | Promise<Record<string, unknown>>`
+Returns `T | BakerErrors | Promise<T | BakerErrors>`. Sync DTOs return directly — no Promise wrapping. Never throws on validation failure.
 
-Converts a class instance to a plain object. No validation. Sync DTOs return directly.
+### `serialize<T>(instance, options?)`
 
-```typescript
-import { serialize } from '@zipbul/baker';
+Returns `Record<string, unknown> | Promise<Record<string, unknown>>`. No validation. Sync DTOs return directly.
 
-const plain = await serialize(userInstance);
-```
+### `validate(Class, input, options?)` / `validate(input, ...rules)`
 
-### `isBakerError(value): value is BakerErrors`
+DTO-level or ad-hoc single-value validation. Returns `true | BakerErrors`.
 
-Type guard. Narrows `deserialize`/`validate` result to error type.
+### `isBakerError(value)`
 
-```typescript
-interface BakerError {
-  readonly path: string;     // 'name', 'address.city', 'items[0].value'
-  readonly code: string;     // 'isString', 'minLength', 'invalidInput'
-  readonly message?: string; // custom message if set
-  readonly context?: unknown; // custom context if set
-}
-```
+Type guard. Narrows result to `BakerErrors` containing `{ path, code, message?, context? }[]`.
 
-### `configure(config): ConfigureResult`
+### `configure(config)`
 
-Global configuration. Call before first `deserialize`/`serialize`/`validate`.
+Global configuration. Call before first deserialize/serialize/validate.
 
 ```typescript
-import { configure } from '@zipbul/baker';
-
 configure({
-  autoConvert: true,        // "123" → 123. Default: false
-  allowClassDefaults: true, // use class field initializers for missing keys. Default: false
-  stopAtFirstError: true,   // return on first validation failure. Default: false
-  forbidUnknown: true,      // reject undeclared fields. Default: false
+  autoConvert: true,        // coerce "123" → 123
+  allowClassDefaults: true, // use class field initializers for missing keys
+  stopAtFirstError: true,   // return on first validation failure
+  forbidUnknown: true,      // reject undeclared fields
 });
 ```
 
-### `createRule(name, validate): EmittableRule`
+### `createRule(name, validate)`
 
-Creates a custom validation rule.
-
-```typescript
-import { createRule } from '@zipbul/baker';
+Custom validation rule with optional AOT `emit()` for maximum performance.
 
-const isEven = createRule('isEven', (v) => typeof v === 'number' && v % 2 === 0);
-
-const isUnique = createRule({
-  name: 'isUnique',
-  validate: async (v) => await db.checkUnique(v),
-  constraints: { table: 'users' },
-});
-```
+## @Field Decorator
 
-## `@Field` Decorator
+One decorator for everything — replaces 30+ individual decorators from class-validator.
 
 ```typescript
 @Field(...rules)
@@ -119,43 +105,103 @@ const isUnique = createRule({
 
 ### Options
 
+| Option | Type | Description |
+|---|---|---|
+| `type` | `() => Dto \| [Dto]` | Nested DTO. `[Dto]` for arrays |
+| `discriminator` | `{ property, subTypes }` | Polymorphic dispatch |
+| `optional` | `boolean` | Allow undefined |
+| `nullable` | `boolean` | Allow null |
+| `name` | `string` | Bidirectional key mapping |
+| `deserializeName` | `string` | Input key mapping |
+| `serializeName` | `string` | Output key mapping |
+| `exclude` | `boolean \| 'deserializeOnly' \| 'serializeOnly'` | Field exclusion |
+| `groups` | `string[]` | Conditional visibility |
+| `when` | `(obj) => boolean` | Conditional validation |
+| `transform` | `Transformer \| Transformer[]` | Value transformer |
+| `message` | `string \| (args) => string` | Error message override |
+| `context` | `unknown` | Error context |
+| `mapValue` | `() => Dto` | Map value DTO |
+| `setValue` | `() => Dto` | Set element DTO |
+
+## Transformers
+
+Bidirectional value transformers with separate `deserialize` and `serialize` methods.
+
+```typescript
+import type { Transformer } from '@zipbul/baker';
+
+const centsTransformer: Transformer = {
+  deserialize: ({ value }) => typeof value === 'number' ? value * 100 : value,
+  serialize: ({ value }) => typeof value === 'number' ? value / 100 : value,
+};
+```
+
+### Built-in Transformers
+
 ```typescript
-interface FieldOptions {
-  type?: () => DtoClass | [DtoClass];        // nested DTO. [Dto] for arrays
-  discriminator?: {                           // polymorphic dispatch
-    property: string;
-    subTypes: { value: Function; name: string }[];
-  };
-  keepDiscriminatorProperty?: boolean;        // preserve discriminator in result. Default: false
-  rules?: EmittableRule[];                    // rules as array (alternative to variadic)
-  optional?: boolean;                         // allow undefined. Default: false
-  nullable?: boolean;                         // allow null. Default: false
-  name?: string;                              // bidirectional key mapping
-  deserializeName?: string;                   // input key mapping
-  serializeName?: string;                     // output key mapping
-  exclude?: boolean | 'deserializeOnly' | 'serializeOnly';  // field exclusion
-  groups?: string[];                          // conditional visibility
-  when?: (obj: any) => boolean;               // conditional validation
-  transform?: (params: FieldTransformParams) => unknown;     // value transform
-  transformDirection?: 'deserializeOnly' | 'serializeOnly';  // transform direction
-  message?: string | ((args) => string);      // error message override
-  context?: unknown;                          // error context
-  mapValue?: () => DtoClass;                  // Map value DTO
-  setValue?: () => DtoClass;                  // Set element DTO
+import {
+  trimTransformer, toLowerCaseTransformer, toUpperCaseTransformer,
+  roundTransformer, unixSecondsTransformer, unixMillisTransformer,
+  isoStringTransformer, csvTransformer, jsonTransformer,
+} from '@zipbul/baker/transformers';
+```
+
+| Transformer | deserialize | serialize |
+|---|---|---|
+| `trimTransformer` | trim string | trim string |
+| `toLowerCaseTransformer` | lowercase | lowercase |
+| `toUpperCaseTransformer` | uppercase | uppercase |
+| `roundTransformer(n?)` | round to n decimals | round to n decimals |
+| `unixSecondsTransformer` | unix seconds &rarr; Date | Date &rarr; unix seconds |
+| `unixMillisTransformer` | unix ms &rarr; Date | Date &rarr; unix ms |
+| `isoStringTransformer` | ISO string &rarr; Date | Date &rarr; ISO string |
+| `csvTransformer(sep?)` | `"a,b"` &rarr; `["a","b"]` | `["a","b"]` &rarr; `"a,b"` |
+| `jsonTransformer` | JSON string &rarr; object | object &rarr; JSON string |
+
+### Transform Array Order
+
+Multiple transformers apply as a codec stack:
+- **Deserialize**: left to right — `[A, B, C]` applies A, then B, then C
+- **Serialize**: right to left — `[A, B, C]` applies C, then B, then A
+
+```typescript
+@Field(isString, { transform: [trimTransformer, toLowerCaseTransformer] })
+email!: string;
+// deserialize "  HELLO  " → trim → toLowerCase → "hello"
+// serialize   "hello"     → toLowerCase → trim → "hello"
+```
+
+### Optional Peer Transformers
+
+```typescript
+// bun add luxon
+import { luxonTransformer } from '@zipbul/baker/transformers';
+const luxon = await luxonTransformer({ zone: 'Asia/Seoul' });
+
+class EventDto {
+  @Field({ transform: luxon }) startAt!: DateTime;
 }
 ```
 
+```typescript
+// bun add moment
+import { momentTransformer } from '@zipbul/baker/transformers';
+const mt = await momentTransformer({ format: 'YYYY-MM-DD' });
+```
+
 ## Rules
 
+104 built-in validation rules.
+
 ### Type Checkers
 
-`isString`, `isInt`, `isBoolean`, `isDate`, `isArray`, `isObject` — constants, no `()`.
+`isString`, `isInt`, `isBoolean`, `isDate`, `isArray`, `isObject` — constants, no `()` needed.
 
-`isNumber(options?)`, `isEnum(entity)` — factories, need `()`.
+`isNumber(options?)`, `isEnum(entity)` — factories, require `()`.
 
 ### Numbers
 
-`min(n)`, `max(n)`, `min(n, { exclusive: true })`, `isPositive`, `isNegative`, `isDivisibleBy(n)`
+`min(n)`, `max(n)`, `isPositive`, `isNegative`, `isDivisibleBy(n)`
 
 ### Strings
 
@@ -163,7 +209,7 @@ interface FieldOptions {
 
 ### Formats
 
-`isEmail()`, `isURL()`, `isUUID(version?)`, `isIP(version?)`, `isISO8601()`, `isJSON`, `isJWT`, `isCreditCard`, `isIBAN()`, `isFQDN()`, `isMACAddress()`, `isBase64()`, `isHexColor`, `isSemVer`, `isMongoId`, `isPhoneNumber`, `isStrongPassword()`
+`isEmail()`, `isURL()`, `isUUID(version?)`, `isIP(version?)`, `isISO8601()`, `isJSON`, `isJWT`, `isCreditCard`, `isIBAN()`, `isFQDN()`, `isMACAddress()`, `isBase64()`, `isHexColor`, `isSemVer`, `isMongoId`, `isPhoneNumber()`, `isStrongPassword()`, `isULID()`, `isCUID2()`
 
 ### Arrays
 
@@ -199,7 +245,7 @@ class UserDto {
 ```typescript
 class UserDto {
   @Field({ type: () => Set as any, setValue: () => TagDto }) tags!: Set<TagDto>;
-  @Field({ type: () => Map as any, mapValue: () => TagDto }) tagMap!: Map<string, TagDto>;
+  @Field({ type: () => Map as any, mapValue: () => PriceDto }) prices!: Map<string, PriceDto>;
 }
 ```
 
@@ -233,34 +279,36 @@ class UserDto extends BaseDto {
 }
 ```
 
-## Exports
+## FAQ
 
-```typescript
-// Functions
-import { deserialize, validate, serialize, configure, createRule } from '@zipbul/baker';
+### When should I use baker instead of class-validator?
 
-// Decorators
-import { Field, arrayOf } from '@zipbul/baker';
+When performance matters. baker is 163x faster on valid input and 109x faster on invalid input, while providing the same decorator-based DX. baker also eliminates the `reflect-metadata` dependency.
 
-// Error handling
-import { isBakerError, SealError } from '@zipbul/baker';
+### How does baker compare to Zod?
 
-// Types
-import type {
-  BakerError, BakerErrors, FieldOptions, FieldTransformParams,
-  ArrayOfMarker, EmittableRule, BakerConfig, ConfigureResult, RuntimeOptions,
-} from '@zipbul/baker';
+Zod uses schema method chains (`z.string().email()`), baker uses decorators (`@Field(isString, isEmail())`). baker is 16x faster on valid input because it generates optimized code at definition time instead of interpreting schemas at runtime. Choose Zod if you need schema-first design; choose baker if you need class-based DTOs with maximum performance.
 
-// Rules (subpath)
-import { isString, isNumber, ... } from '@zipbul/baker/rules';
-```
+### Does baker support async validation?
+
+Yes. If any rule or transformer is async, baker automatically detects it at seal time and generates an async executor. Sync DTOs return values directly without Promise wrapping.
+
+### Can I use baker with NestJS?
 
-## What Baker Does Not Do
+Yes. baker's `@Field` decorator works alongside NestJS pipes. Use `deserialize()` in a custom validation pipe.
 
-- JSON Schema / OpenAPI generation
-- GraphQL schema generation
-- Runtime type inference from schemas
-- `reflect-metadata` dependency
+### How does the AOT code generation work?
+
+On the first call to `deserialize`/`serialize`/`validate`, baker seals all registered DTOs: it analyzes field metadata, generates optimized JavaScript validation functions via `new Function()`, and caches them. Subsequent calls execute the pre-compiled functions directly.
+
+## Exports
+
+```typescript
+import { deserialize, validate, serialize, configure, createRule, Field, arrayOf, isBakerError, SealError } from '@zipbul/baker';
+import type { Transformer, TransformParams, BakerError, BakerErrors, FieldOptions, EmittableRule, RuntimeOptions } from '@zipbul/baker';
+import { isString, isEmail, isULID, isCUID2, ... } from '@zipbul/baker/rules';
+import { trimTransformer, jsonTransformer, ... } from '@zipbul/baker/transformers';
+```
 
 ## License
 

package/dist/index-fnv35wrf.js

@@ -0,0 +1,3 @@
+// @bun
+var f=Symbol.for("baker:raw"),g=Symbol.for("baker:sealed");
+export{f as d,g as e};

package/dist/index-k3d659ad.js

@@ -0,0 +1,3 @@
+// @bun
+import{d as v}from"./index-fnv35wrf.js";var z=new Set;function B(h,w){if(!Object.prototype.hasOwnProperty.call(h,v))h[v]=Object.create(null),z.add(h);let G=h[v];return G[w]??={validation:[],transform:[],expose:[],exclude:null,type:null,flags:{}}}var H=Symbol.for("baker:arrayOf");function T(...h){let w={rules:h};return w[H]=!0,w}function J(h){return typeof h==="object"&&h!==null&&h[H]===!0}var U=new Set(["type","discriminator","keepDiscriminatorProperty","rules","optional","nullable","name","deserializeName","serializeName","exclude","groups","when","transform","message","context","mapValue","setValue"]);function C(h){if(typeof h==="function")return!1;if(typeof h!=="object"||h===null)return!1;if(J(h))return!1;let w=Object.keys(h);if(w.length===0)return!0;return w.some((G)=>U.has(G))}function X(h){if(h.length===0)return{rules:[],options:{}};if(h.length===1&&C(h[0])){let G=h[0];return{rules:G.rules??[],options:G}}let w=h[h.length-1];if(C(w)){let G=w,j=h.slice(0,-1);if(G.rules)j=[...j,...G.rules];return{rules:j,options:G}}return{rules:h,options:{}}}function Z(h,w,G){for(let j of w)if(J(j))for(let q of j.rules){let b={rule:q,each:!0,groups:G.groups};if(G.message!==void 0)b.message=G.message;if(G.context!==void 0)b.context=G.context;h.validation.push(b)}else{let q={rule:j,groups:G.groups};if(G.message!==void 0)q.message=G.message;if(G.context!==void 0)q.context=G.context;h.validation.push(q)}}function $(h,w){if(w.name)h.expose.push({name:w.name,groups:w.groups});else if(w.deserializeName||w.serializeName){if(w.deserializeName)h.expose.push({name:w.deserializeName,deserializeOnly:!0,groups:w.groups});if(w.serializeName)h.expose.push({name:w.serializeName,serializeOnly:!0,groups:w.groups})}else if(w.groups)h.expose.push({groups:w.groups});else h.expose.push({})}function K(h,w){if(!w.transform)return;let G=Array.isArray(w.transform)?w.transform:[w.transform];for(let j of G)h.transform.push({fn:j.deserialize,options:{deserializeOnly:!0}},{fn:j.serialize,options:{serializeOnly:!0}})}function E(...h){return(w,G)=>{let j=w.constructor,b=B(j,G),{rules:Q,options:S}=X(h);if(Z(b,Q,S),S.optional)b.flags.isOptional=!0;if(S.nullable)b.flags.isNullable=!0;if(S.when)b.flags.validateIf=S.when;if(S.type)b.type={fn:S.type,discriminator:S.discriminator,keepDiscriminatorProperty:S.keepDiscriminatorProperty,collectionValue:S.mapValue??S.setValue};if($(b,S),S.exclude){if(S.exclude===!0)b.exclude={};else if(S.exclude==="deserializeOnly")b.exclude={deserializeOnly:!0};else if(S.exclude==="serializeOnly")b.exclude={serializeOnly:!0}}K(b,S)}}
+export{z as a,T as b,E as c};

package/dist/index-s0n74vx1.js

@@ -0,0 +1,3 @@
+// @bun
+var a=import.meta.require;
+export{a as f};

package/dist/index-xdn55cz3.js

@@ -1,4 +1 @@
 // @bun
-
-//# debugId=029AE51BD364B21F64756E2164756E21
-//# sourceMappingURL=index-xdn55cz3.js.map

package/dist/index.d.ts

@@ -4,9 +4,9 @@ export { serialize } from './src/functions/serialize';
 export { configure } from './src/configure';
 export { createRule } from './src/create-rule';
 export { Field, arrayOf } from './src/decorators/index';
-export type { FieldOptions, FieldTransformParams, ArrayOfMarker } from './src/decorators/index';
+export type { FieldOptions, ArrayOfMarker } from './src/decorators/index';
 export type { BakerError, BakerErrors } from './src/errors';
 export { isBakerError, SealError } from './src/errors';
-export type { EmittableRule } from './src/types';
+export type { EmittableRule, Transformer, TransformParams } from './src/types';
 export type { BakerConfig, ConfigureResult } from './src/configure';
 export type { RuntimeOptions } from './src/interfaces';