@zipbul/baker 2.0.0 → 2.2.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 and serialization code on first seal, then reuses the sealed executors on every call.
 
 ```bash
 bun add @zipbul/baker
 ```
 
-Requires `"experimentalDecorators": true` in `tsconfig.json`.
+Zero `reflect-metadata`. Sealed codegen. 1,975 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 functions once on first seal, then executes them on every call.
 
-Same validation as `deserialize` without instance creation.
+| Feature | baker | class-validator | Zod |
+|---|---|---|---|
+| Valid path (5 fields) | **fast sealed path** | slower | slower |
+| Invalid path (5 fields) | **fast sealed path** | slower | slower |
+| 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 multiple libraries on simple, nested, array, and error-collection scenarios. Exact numbers vary by machine and runtime.
 
-### `validate(input, ...rules): true | BakerErrors | Promise<true | BakerErrors>`
+See [`bench/`](./bench) for the current benchmark suite and exact scenarios.
 
-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` for sync DTOs, `Promise<T | BakerErrors>` for async DTOs. 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>` for sync DTOs, `Promise<Record<string, unknown>>` for async DTOs. No validation.
 
-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` for sync paths, `Promise<true | BakerErrors>` for async paths.
 
-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. Calling it after auto-seal throws `SealError`.
 
 ```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.
+Custom validation rule.
 
 ```typescript
-import { createRule } from '@zipbul/baker';
-
-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' },
+const isEven = createRule({
+  name: 'isEven',
+  validate: (v) => typeof v === 'number' && v % 2 === 0,
+  requiresType: 'number',
 });
 ```
 
-## `@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
+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
-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
+@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-03cysbck.js

@@ -0,0 +1,3 @@
+// @bun
+import{o as C}from"./index-jp2yjd6g.js";var H=new Set;function J(h,G){if(!Object.prototype.hasOwnProperty.call(h,C))h[C]=Object.create(null),H.add(h);let S=h[C];return S[G]??={validation:[],transform:[],expose:[],exclude:null,type:null,flags:{}}}function Q(h){return h[Symbol.toStringTag]==="AsyncFunction"}function U(h){return(typeof h==="object"||typeof h==="function")&&h!==null&&typeof h.then==="function"}var $=Symbol.for("baker:arrayOf");function M(...h){let G={rules:h};return G[$]=!0,G}function N(h){return typeof h==="object"&&h!==null&&h[$]===!0}var V=new Set(["type","discriminator","keepDiscriminatorProperty","rules","optional","nullable","name","deserializeName","serializeName","exclude","groups","when","transform","message","context","mapValue","setValue"]);function X(h){if(typeof h==="function")return!1;if(typeof h!=="object"||h===null)return!1;if(N(h))return!1;let G=Object.keys(h);if(G.length===0)return!0;return G.some((S)=>V.has(S))}function I(h){if(h.length===0)return{rules:[],options:{}};if(h.length===1&&X(h[0])){let S=h[0];return{rules:S.rules??[],options:S}}let G=h[h.length-1];if(X(G)){let S=G,q=h.slice(0,-1);if(S.rules)q=[...q,...S.rules];return{rules:q,options:S}}return{rules:h,options:{}}}function L(h,G,S){for(let q of G)if(N(q))for(let w of q.rules){let b={rule:w,each:!0,groups:S.groups};if(S.message!==void 0)b.message=S.message;if(S.context!==void 0)b.context=S.context;h.validation.push(b)}else{let w={rule:q,groups:S.groups};if(S.message!==void 0)w.message=S.message;if(S.context!==void 0)w.context=S.context;h.validation.push(w)}}function E(h,G){if(G.name)h.expose.push({name:G.name,groups:G.groups});else if(G.deserializeName||G.serializeName){if(G.deserializeName)h.expose.push({name:G.deserializeName,deserializeOnly:!0,groups:G.groups});if(G.serializeName)h.expose.push({name:G.serializeName,serializeOnly:!0,groups:G.groups})}else if(G.groups)h.expose.push({groups:G.groups});else h.expose.push({})}function Z(h,G,S){let q=Q(S);return{fn:(b)=>{let B=S(b);if(!q&&U(B))throw Error(`@Field(${h}) ${G} transform returned Promise. Declare the transform with async if it is asynchronous.`);return B},isAsync:q}}function P(h,G,S){if(!S.transform)return;let q=Array.isArray(S.transform)?S.transform:[S.transform];for(let w of q){let b=Z(G,"deserialize",w.deserialize),B=Z(G,"serialize",w.serialize);h.transform.push({fn:b.fn,isAsync:b.isAsync,options:{deserializeOnly:!0}},{fn:B.fn,isAsync:B.isAsync,options:{serializeOnly:!0}})}}function v(...h){return(G,S)=>{let q=G.constructor,w=S,b=J(q,w),{rules:B,options:j}=I(h);if(L(b,B,j),j.optional)b.flags.isOptional=!0;if(j.nullable)b.flags.isNullable=!0;if(j.when)b.flags.validateIf=j.when;if(j.type)b.type={fn:j.type,discriminator:j.discriminator,keepDiscriminatorProperty:j.keepDiscriminatorProperty,collectionValue:j.mapValue??j.setValue};if(E(b,j),j.exclude){if(j.exclude===!0)b.exclude={};else if(j.exclude==="deserializeOnly")b.exclude={deserializeOnly:!0};else if(j.exclude==="serializeOnly")b.exclude={serializeOnly:!0}}P(b,w,j)}}
+export{H as j,Q as k,U as l,M as m,v as n};

package/dist/index-dcbd798a.js

@@ -0,0 +1,3 @@
+// @bun
+var I=()=>({kind:"value"}),Y=(w=I())=>({kind:"member",object:w,property:"length"}),Z=(w=I())=>({kind:"call0",object:w,method:"getTime"}),O=(w)=>({kind:"literal",value:w}),_=(w,z,A)=>({kind:"compare",left:w,op:z,right:typeof A==="number"?O(A):A});var $=(...w)=>({kind:"or",checks:w});function L(w){return Q({name:w.name,requiresType:w.requiresType,constraints:w.constraints,plan:w.plan,validate:w.validate,emit:(z,A)=>U(z,A,w.name,w.plan)})}function Q(w){let z=(A)=>w.validate(A);if(z.emit=w.emit,z.ruleName=w.name,w.requiresType!==void 0)z.requiresType=w.requiresType;if(z.constraints=w.constraints??{},w.isAsync)z.isAsync=!0;if(w.plan)z.plan=w.plan;return z}function U(w,z,A,B,F,K){let M=K?W(B.failure):B.failure;return`if (${J(M,w,F)}) ${z.fail(A)};`}function W(w){if(w.kind==="compare")return w;let z=w.checks.filter((A)=>!X(A));if(z.length===0)return w;if(z.length===1)return z[0];return{kind:w.kind,checks:z}}function X(w){if(w.kind!=="compare"||w.op!=="!==")return!1;return H(w.left,w.right)}function H(w,z){if(w.kind!==z.kind)return!1;if(w.kind==="value")return!0;if(w.kind==="literal")return w.value===z.value;if(w.kind==="member")return H(w.object,z.object);if(w.kind==="call0")return w.method===z.method&&H(w.object,z.object);return!1}function J(w,z,A){if(w.kind==="compare")return`${D(w.left,z,A)} ${w.op} ${D(w.right,z,A)}`;let B=w.kind==="and"?" && ":" || ";return`(${w.checks.map((F)=>J(F,z,A)).join(B)})`}function D(w,z,A){switch(w.kind){case"value":return z;case"literal":return String(w.value);case"member":return A?.length??`${D(w.object,z,A)}.length`;case"call0":return A?.time??`${D(w.object,z,A)}.getTime()`}}
+export{I as a,Y as b,Z as c,O as d,_ as e,$ as f,L as g,Q as h,U as i};

package/dist/index-jp2yjd6g.js

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

package/dist/index-mw7met6r.js

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

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 { BakerConfig, ConfigureResult } from './src/configure';
+export type { EmittableRule, Transformer, TransformParams } from './src/types';
+export type { BakerConfig } from './src/configure';
 export type { RuntimeOptions } from './src/interfaces';