@zipbul/baker 3.4.1 → 5.0.0

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # @zipbul/baker
 
+## 5.0.0
+
+### Major Changes
+
+- 8ea7162: Remove the global registration API in favor of the `Baker` class. `new Baker(config?)`
+  is now the only way to register and seal DTOs: use `@app.Recipe` to register a class and
+  `app.seal()` to seal it. The global `@Recipe`, `seal()`, `configure()`, and the `createBaker()`
+  factory have been removed — each `Baker` instance owns its own isolated registry and config, so
+  multiple apps in one process never mix. `@Field`, the rule/transformer factories, and
+  `deserialize`/`validate`/`serialize` are unchanged.
+
+  Migration: replace `configure(opts)` + global `@Recipe`/`seal()` with
+  `const app = new Baker(opts); @app.Recipe class Dto {}; app.seal();`.
+
+## 4.0.0
+
+### Major Changes
+
+- 98c9a0a: **Breaking:** rule type hints and field exclusion are now enums instead of string literals.
+  `createRule({ requiresType: 'number' })` becomes `requiresType: RequiredType.Number`, and
+  `@Field({ exclude: 'serializeOnly' })` becomes `exclude: ExcludeMode.SerializeOnly`. Runtime
+  behaviour is unchanged — the enums are string-valued, so generated code and validation results are
+  identical; only the public type surface changed. `RequiredType` and `ExcludeMode` are now exported.
+
+### Minor Changes
+
+- 98c9a0a: Add `createBaker()` for multi-app isolation. Each scope owns its own registration and config, so
+  multiple apps in one process — or a bundler-duplicated copy of baker — no longer fragment `seal()`
+  (the previous "`<Class> is not sealed`" failure). Use:
+
+  ```ts
+  const app = createBaker({ autoConvert: true });
+  @app.Recipe
+  class UserDto {
+    @Field(isString) name!: string;
+  }
+  app.seal();
+  deserialize(UserDto, input);
+  ```
+
+  `@Field`, rules, and `deserialize/serialize/validate` stay global. Distinct classes are fully
+  isolated (each sealed with its scope's config); a class shared across scopes is reused as one sealed
+  form. Single-app code is unchanged — global `@Recipe` / `seal()` / `configure()` still work. Exports
+  `createBaker` and the `Baker` type.
+
 ## 3.4.1
 
 ### Patch Changes

package/README.md

@@ -1,165 +1,195 @@
 # @zipbul/baker
 
-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.
+The fastest decorator-based DTO validation library for TypeScript. baker generates optimized validation and serialization code once at seal time, then reuses the sealed executors on every call.
 
 ```bash
 bun add @zipbul/baker
 ```
 
-Zero `reflect-metadata`. Sealed codegen. 99%+ line coverage.
+Zero `reflect-metadata`. Sealed codegen.
 
-> **Requires Bun ≥ 1.3.13.** baker relies on TC39 decorator metadata (`Symbol.metadata`), which Node does not populate — it is Bun-only.
+## Requirements
+
+- **Bun ≥ 1.3.13.** baker relies on TC39 decorator metadata (`Symbol.metadata`), which Node does not populate — it is Bun-only.
+- **ESM only.** baker ships no CommonJS build.
+- **TypeScript ≥ 5.2** with native (TC39, Stage 3) decorators. Bun runs TypeScript directly, so your DTOs need no separate build step.
+
+```jsonc
+// tsconfig.json
+{
+  "compilerOptions": {
+    "target": "ESNext", // must include Symbol.metadata (ES2022+/ESNext)
+    "experimentalDecorators": false // use native TC39 decorators — this is the default; do NOT enable it
+  }
+}
+```
 
 ## Quick Start
 
 ```typescript
-import { deserialize, isBakerIssueSet, Field, Recipe, seal } from '@zipbul/baker';
+import { Baker, Field, deserialize, isBakerIssueSet } from '@zipbul/baker';
 import { isString, isNumber, isEmail, min, minLength } from '@zipbul/baker/rules';
 
-@Recipe
+const baker = new Baker();
+
+@baker.Recipe
 class UserDto {
   @Field(isString, minLength(2)) name!: string;
   @Field(isNumber(), min(0)) age!: number;
   @Field(isString, isEmail()) email!: string;
 }
 
-// Call once at app startup, after all DTOs are loaded.
-seal();
+// Call once at startup, after this baker's DTOs are defined.
+baker.seal();
 
-const result = await deserialize(UserDto, {
+// All rules here are sync, so deserialize returns the value directly (no await).
+const result = deserialize(UserDto, {
   name: 'Alice',
   age: 30,
   email: 'alice@test.com',
 });
 
 if (isBakerIssueSet(result)) {
-  console.log(result.errors); // [{ path: 'email', code: 'isEmail' }]
+  // Reached only for invalid input, e.g. [{ path: 'email', code: 'isEmail' }]
+  console.log(result.errors);
 } else {
   console.log(result.name); // 'Alice' — typed as UserDto
 }
 ```
 
-## Why Baker?
+`deserialize` returns either your typed instance or a `BakerIssueSet`; narrow between them with `isBakerIssueSet`. If any rule or transformer on the DTO is async, `deserialize` returns a `Promise` instead — `await` it (see [Runtime API](#runtime-api)).
+
+## Core Concepts
 
-Baker generates optimized JavaScript functions once on first seal, then executes them on every call.
+| Concept | What it does |
+| ------------------- | ------------------------------------------------------------------------------ |
+| `new Baker(config?)` | An isolated registration + seal scope. Multiple bakers never mix. Use `@app.Recipe` and `app.seal()`. |
+| `@app.Recipe`       | Marks a class as a DTO of that baker. Only `@Field` properties are part of the contract. |
+| `@Field(...rules)`  | Declares a validated field. Global — works with any baker.                     |
+| `app.seal()`        | Compiles that baker's DTOs into executor functions. Call once, at startup.     |
+| `deserialize` / `validate` / `serialize` | Global — run the sealed executors stored on the class: parse+validate, validate-only, or emit a plain object. |
 
-| 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        |
+> Examples below assume a `const baker = new Baker()` in scope and a single `baker.seal()` after the DTOs are defined.
+
+## Why baker?
+
+baker generates optimized JavaScript functions once on first seal, then executes them on every call — no per-call rule interpretation.
+
+| Feature            | baker                | class-validator        | Zod                 |
+| ------------------ | -------------------- | ---------------------- | ------------------- |
+| 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        |
 
 ## Performance
 
-Benchmarked against multiple libraries on simple, nested, array, and error-collection scenarios. Exact numbers vary by machine and runtime.
+Benchmarked against multiple libraries on simple, nested, array, and error-collection scenarios. Exact numbers vary by machine and runtime — see [`bench/`](./bench) for the suite and to measure on your machine.
 
-See [`bench/`](./bench) for the current benchmark suite and exact scenarios.
+## @Field Decorator
 
-## API
+One decorator for everything — replaces 30+ individual decorators from class-validator.
 
-### `seal(...classes?)`
+Only fields decorated with `@Field` participate in validation, deserialization, and serialization. Undecorated fields are silently absent from results — they are not part of the DTO contract.
 
-**Required.** Call once at app startup, after every DTO module has been imported. With no arguments, seals every class registered via `@Field` so far. With class arguments, seals only those (and any nested DTOs they reach). Idempotent.
+```typescript
+@Field(...rules)
+@Field(...rules, options)
+@Field(options)
+@Field() // marker-only (no rules)
+```
 
-`deserialize` / `serialize` / `validate` throw `BakerError` if the DTO is not sealed. Tests that need to mutate decorator metadata should call `seal()` after each `configure(...)` reconfiguration.
+Each rule must be an emittable rule object created via `createRule()` or one of the built-in rule factories. Passing a raw function (e.g. `@Field(isNumber)` instead of `@Field(isNumber())`) throws `BakerError` at decorator-evaluation time.
 
-### `deserialize<T>(Class, input, options?)`
+### Options
 
-Returns `T | BakerIssueSet` for sync DTOs, `Promise<T | BakerIssueSet>` for async DTOs. Never throws on validation failure.
+Most fields need only rules. The options below cover nested, conditional, collection, and key-mapping cases — reach for them as needed.
+
+| Option                      | Type                                              | Description                              |
+| --------------------------- | ------------------------------------------------- | ---------------------------------------- |
+| `type`                      | `() => Dto \| [Dto] \| Set \| Map`                | Nested DTO. `[Dto]` for arrays; `Set`/`Map` for collections |
+| `discriminator`             | `{ property, subTypes }`                          | Polymorphic dispatch (requires `type`)   |
+| `keepDiscriminatorProperty` | `boolean`                                         | Keep the discriminator key in the result |
+| `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                          |
+
+### Conditional fields & custom messages
 
-If the DTO has any async rule or transformer, `deserialize` returns a `Promise`. Otherwise it returns the value directly. For full type safety pick a strict variant (see below).
+```typescript
+@baker.Recipe
+class UserDto {
+  @Field(isString) name!: string;
 
-### `deserializeSync<T>` / `deserializeAsync<T>`
+  // Validated & exposed only when a matching group is requested at runtime.
+  @Field(isString, { groups: ['admin'] }) ssn!: string;
 
-Strict variants. `deserializeSync` throws `BakerError` if the DTO is async on the deserialize side. `deserializeAsync` always returns `Promise` (sync DTOs are wrapped via `Promise.resolve`).
+  // Rules apply only when the predicate returns true for the input object.
+  @Field(isString, isEmail(), { when: obj => obj.contactable === true })
+  email!: string;
 
-### `serialize<T>(instance, options?)`
+  // Override the default error message for this field's failures.
+  @Field(isString, minLength(2), { message: 'Name must be at least 2 characters' })
+  displayName!: string;
+}
 
-Returns `Record<string, unknown>` for sync DTOs, `Promise<Record<string, unknown>>` for async DTOs. No validation. Async asymmetry: `_isSerializeAsync` is independent of `_isAsync` — a DTO can be async on deserialize but sync on serialize, and vice versa.
+deserialize(UserDto, input); // `ssn` is skipped
+deserialize(UserDto, input, { groups: ['admin'] }); // `ssn` is included
+```
 
-### `serializeSync<T>` / `serializeAsync<T>`
+A field with no `groups` is always included; a field tagged with `groups` participates only when a matching group is passed via [runtime options](#runtime-options). See [`RuntimeOptions`](#runtime-options) for the call-site shape.
 
-Strict variants. `serializeSync` throws `BakerError` if the DTO is async on the serialize side.
+## Rules
 
-### `validate(Class, input, options?)`
+114 built-in validation rules.
 
-Validates `input` against a decorated class's schema. Returns `true | BakerIssueSet` for sync paths, `Promise<true | BakerIssueSet>` for async paths. To validate a single primitive without a DTO, call the rule directly (e.g. `isEmail()(value)`).
+> **Constants vs factories:** rules listed without `()` are pre-built constants — use them bare (`@Field(isString)`). Rules shown with `()` are factories you must call (`@Field(isNumber())`). Passing a factory without calling it throws `BakerError`.
 
-### `validateSync` / `validateAsync`
+### Type Checkers
 
-Strict variants. `validateSync` throws `BakerError` if the DTO is async; `validateAsync` always returns `Promise`.
+`isString`, `isInt`, `isBoolean`, `isDate`, `isArray`, `isObject` — constants, no `()` needed.
 
-### `isBakerIssueSet(value)`
+`isNumber(options?)`, `isEnum(entity)` — factories, require `()`.
 
-Type guard. Narrows result to `BakerIssueSet` containing `{ path, code, message?, context? }[]`.
+### Numbers
 
-### `configure(config)`
+`min(n)`, `max(n)`, `isPositive`, `isNegative`, `isDivisibleBy(n)`
 
-Global configuration. Must be called **before** `seal()`. After seal, `configure(...)` throws `BakerError`; reconfiguring requires `unseal()` (test-only helper) + `configure(...)` + `seal()` again.
+### Strings
 
-```typescript
-configure({
-  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
-});
-```
+`minLength(n)`, `maxLength(n)`, `length(min, max)`, `contains(seed)`, `notContains(seed)`, `matches(regex)`
 
-### `createRule(name, validate)` / `createRule(options)`
+### Formats
 
-Custom validation rule. Two forms — a `(name, validate)` shorthand or an options object:
+`isEmail()`, `isURL()`, `isUUID(version?)`, `isIP(version?)`, `isISO8601()`, `isJSON`, `isJWT`, `isCreditCard`, `isIBAN()`, `isFQDN()`, `isMACAddress()`, `isBase64()`, `isHexColor`, `isSemVer`, `isMongoId`, `isPhoneNumber`, `isStrongPassword()`, `isULID()`, `isCUID2()`, `isHttpToken`
 
-```typescript
-const koreanPhone = createRule('koreanPhone', v => /^01[016789]/.test(v as string));
-```
+### Arrays
 
-```typescript
-const isEven = createRule({
-  name: 'isEven',
-  validate: v => typeof v === 'number' && v % 2 === 0,
-  requiresType: 'number',
-});
-```
+`arrayMinSize(n)`, `arrayMaxSize(n)`, `arrayUnique()`, `arrayNotEmpty`, `arrayContains(values)`, `arrayNotContains(values)`
 
-## @Field Decorator
+> `arrayOf(...rules)` validates each element of an array against the given rules. It is imported from the main entry (`@zipbul/baker`), not `@zipbul/baker/rules`.
 
-One decorator for everything — replaces 30+ individual decorators from class-validator.
+### Common
 
-Only fields decorated with `@Field` participate in validation, deserialization, and serialization. Undecorated fields are silently absent from results — they are not part of the DTO contract.
+`equals(val)`, `notEquals(val)`, `isIn(values)`, `isNotIn(values)`, `isEmpty`, `isNotEmpty`
 
-```typescript
-@Field(...rules)
-@Field(...rules, options)
-@Field(options)
-@Field()                    // marker-only (no rules)
-```
+### Date
 
-Each rule must be an emittable rule object created via `createRule()` or one of the built-in rule factories. Passing a raw function (e.g. `@Field(isNumber)` instead of `@Field(isNumber())`) throws `BakerError` at decorator-evaluation time.
+`minDate(date)`, `maxDate(date)`
 
-### Options
+### Locale
 
-| Option            | Type                                              | Description                    |
-| ----------------- | ------------------------------------------------- | ------------------------------ |
-| `type`            | `() => Dto \| [Dto]`                              | Nested DTO. `[Dto]` for arrays |
-| `discriminator`   | `{ property, subTypes }`                          | Polymorphic dispatch           |
-| `keepDiscriminatorProperty` | `boolean`                               | Keep the discriminator key in the result |
-| `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                |
+`isMobilePhone(locale)`, `isPostalCode(locale)`, `isIdentityCard(locale)`, `isPassportNumber(locale)`
 
 ## Transformers
 
@@ -190,17 +220,17 @@ import {
 } 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  |
+| 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 → Date     | Date → unix seconds     |
+| `unixMillisTransformer`  | unix ms → Date          | Date → unix ms          |
+| `isoStringTransformer`   | ISO string → Date       | Date → ISO string       |
+| `csvTransformer(sep?)`   | `"a,b"` → `["a","b"]`   | `["a","b"]` → `"a,b"`   |
+| `jsonTransformer`        | JSON string → object    | object → JSON string    |
 
 ### Transform Array Order
 
@@ -218,12 +248,14 @@ email!: string;
 
 ### Optional Peer Transformers
 
+`luxonTransformer` and `momentTransformer` require their respective libraries as optional peer dependencies — install whichever you use.
+
 ```typescript
 // bun add luxon
 import { luxonTransformer } from '@zipbul/baker/transformers';
 const luxon = await luxonTransformer({ zone: 'Asia/Seoul' });
 
-@Recipe
+@baker.Recipe
 class EventDto {
   @Field({ transform: luxon }) startAt!: DateTime;
 }
@@ -235,65 +267,29 @@ import { momentTransformer } from '@zipbul/baker/transformers';
 const mt = await momentTransformer({ format: 'YYYY-MM-DD' });
 ```
 
-> **Note on `format`**: The `format` option in `luxonTransformer` / `momentTransformer` controls the **serialize-side output only**. On deserialize, both transformers parse the input with the library's default parser (ISO-first for Luxon, lenient parser for Moment). Using a lossy format like `'YYYY-MM-DD'` makes the transformer one-way — `serialize → deserialize` will not recover the original time of day. If you need a lossless roundtrip, omit `format` (defaults to ISO 8601).
-
-## Rules
-
-105 built-in validation rules.
-
-### Type Checkers
-
-`isString`, `isInt`, `isBoolean`, `isDate`, `isArray`, `isObject` — constants, no `()` needed.
-
-`isNumber(options?)`, `isEnum(entity)` — factories, require `()`.
-
-### Numbers
-
-`min(n)`, `max(n)`, `isPositive`, `isNegative`, `isDivisibleBy(n)`
-
-### Strings
+> **Note on `format`:** The `format` option in `luxonTransformer` / `momentTransformer` controls the **serialize-side output only**. On deserialize, both transformers parse the input with the library's default parser (ISO-first for Luxon, lenient parser for Moment). Using a lossy format like `'YYYY-MM-DD'` makes the transformer one-way — `serialize → deserialize` will not recover the original time of day. If you need a lossless roundtrip, omit `format` (defaults to ISO 8601).
 
-`minLength(n)`, `maxLength(n)`, `length(min, max)`, `contains(seed)`, `notContains(seed)`, `matches(regex)`
-
-### Formats
+## Composing DTOs
 
-`isEmail()`, `isURL()`, `isUUID(version?)`, `isIP(version?)`, `isISO8601()`, `isJSON`, `isJWT`, `isCreditCard`, `isIBAN()`, `isFQDN()`, `isMACAddress()`, `isBase64()`, `isHexColor`, `isSemVer`, `isMongoId`, `isPhoneNumber()`, `isStrongPassword()`, `isULID()`, `isCUID2()`, `isHttpToken`
-
-### Arrays
-
-`arrayMinSize(n)`, `arrayMaxSize(n)`, `arrayUnique()`, `arrayNotEmpty`, `arrayContains(values)`, `arrayOf(...rules)`
-
-### Common
-
-`equals(val)`, `notEquals(val)`, `isIn(values)`, `isNotIn(values)`, `isEmpty`, `isNotEmpty`
-
-### Date
-
-`minDate(date)`, `maxDate(date)`
-
-### Locale
-
-`isMobilePhone(locale)`, `isPostalCode(locale)`, `isIdentityCard(locale)`, `isPassportNumber(locale)`
-
-## Nested DTOs
+### Nested DTOs
 
 ```typescript
-@Recipe
+@baker.Recipe
 class AddressDto {
   @Field(isString) city!: string;
 }
 
-@Recipe
+@baker.Recipe
 class UserDto {
   @Field({ type: () => AddressDto }) address!: AddressDto;
   @Field({ type: () => [AddressDto] }) addresses!: AddressDto[];
 }
 ```
 
-## Collections
+### Collections
 
 ```typescript
-@Recipe
+@baker.Recipe
 class UserDto {
   @Field({ type: () => Set, setValue: () => TagDto }) tags!: Set<TagDto>;
   @Field({ type: () => Map, mapValue: () => PriceDto }) prices!: Map<string, PriceDto>;
@@ -302,10 +298,10 @@ class UserDto {
 
 > Deserialize input shape: a `Set` field accepts a JSON **array**, a `Map` field accepts a plain **object** keyed by string. Serialize emits the same shapes.
 
-## Discriminator
+### Discriminator
 
 ```typescript
-@Recipe
+@baker.Recipe
 class PetOwner {
   @Field({
     type: () => CatDto,
@@ -321,21 +317,118 @@ class PetOwner {
 }
 ```
 
-## Inheritance
+### Inheritance
 
 ```typescript
-@Recipe
+@baker.Recipe
 class BaseDto {
   @Field(isString) id!: string;
 }
 
-@Recipe
+@baker.Recipe
 class UserDto extends BaseDto {
   @Field(isString) name!: string;
   // inherits 'id' field with isString rule
 }
 ```
 
+## Runtime API
+
+### `new Baker(config?)`
+
+A `Baker` is an isolated registration + seal scope. Construct one per app/library; multiple bakers in one process never mix.
+
+- `@app.Recipe` — class decorator; registers the class as one of this baker's DTOs.
+- `app.seal()` — **required.** Compiles the baker's DTOs (and any nested DTOs they reach) into executor functions. Call once at startup, after the baker's DTOs are defined. Idempotent.
+- Config is passed to the constructor:
+
+```typescript
+const app = new Baker({
+  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
+});
+```
+
+`deserialize` / `serialize` / `validate` are global — they read the sealed executor off the class — and throw `BakerError` if the class is not sealed.
+
+**Isolation:** distinct classes are fully isolated (each sealed with its baker's config). A class shared across bakers is sealed once (first seal wins) — use separate classes if you need different config.
+
+### `deserialize` / `serialize` / `validate`
+
+Three entry points share the same sync/async shape. If the DTO has any async rule or transformer on the relevant side, the call returns a `Promise`; otherwise it returns the value directly.
+
+| Function    | Signature                          | Returns (sync)          | Notes                                  |
+| ----------- | ---------------------------------- | ----------------------- | -------------------------------------- |
+| `deserialize` | `(Class, input, options?)`       | `T \| BakerIssueSet`    | Parse + validate. Never throws on validation failure. |
+| `validate`    | `(Class, input, options?)`       | `true \| BakerIssueSet` | Validate only. |
+| `serialize`   | `(instance, options?)`           | `Record<string, unknown>` | Emit a plain object. No validation. |
+
+Async returns are wrapped: `Promise<T \| BakerIssueSet>`, `Promise<true \| BakerIssueSet>`, and `Promise<Record<string, unknown>>` respectively. The deserialize and serialize sides are independent — a DTO can be async on deserialize but sync on serialize, and vice versa.
+
+To validate a single primitive without a DTO, call the rule directly: `isEmail()(value)`.
+
+#### Strict variants
+
+Each function has `*Sync` and `*Async` variants for unambiguous types:
+
+- `deserializeSync` / `serializeSync` / `validateSync` — throw `BakerError` if the DTO is async on that side.
+- `deserializeAsync` / `serializeAsync` / `validateAsync` — always return a `Promise` (sync DTOs are wrapped via `Promise.resolve`).
+
+### Runtime options
+
+`deserialize`, `serialize`, and `validate` accept an optional trailing `options` argument:
+
+```typescript
+interface RuntimeOptions {
+  groups?: string[]; // per-request group selection — see @Field `groups`
+}
+```
+
+Groups are passed at call time (not on `@Field`) because the active set typically varies per request.
+
+### `createRule(name, validate)` / `createRule(options)`
+
+Custom validation rule. Two forms — a `(name, validate)` shorthand or an options object:
+
+```typescript
+const koreanPhone = createRule('koreanPhone', v => /^01[016789]/.test(v as string));
+```
+
+```typescript
+import { RequiredType } from '@zipbul/baker';
+
+const isEven = createRule({
+  name: 'isEven',
+  validate: v => typeof v === 'number' && v % 2 === 0,
+  requiresType: RequiredType.Number,
+});
+```
+
+### `isBakerIssueSet(value)`
+
+Type guard. Narrows a result to `BakerIssueSet`, whose `errors` array holds `{ path, code, message?, context? }` issues.
+
+## Error Handling
+
+baker separates two failure modes:
+
+- **`BakerError` (thrown)** — a programming mistake: using a DTO before `app.seal()`, passing a raw rule function, an unknown config key, or calling a strict `*Sync` variant on an async DTO. Fix the code; don't catch it in request handlers.
+- **`BakerIssueSet` (returned)** — a validation failure. `deserialize` and `validate` return it instead of throwing. Guard with `isBakerIssueSet` and read `.errors`.
+
+```typescript
+const result = deserialize(UserDto, input);
+
+if (isBakerIssueSet(result)) {
+  for (const issue of result.errors) {
+    console.log(`${issue.path}: ${issue.code}`); // e.g. "email: isEmail"
+  }
+} else {
+  // result is a typed UserDto
+}
+```
+
 ## FAQ
 
 ### When should I use baker instead of class-validator?
@@ -356,23 +449,27 @@ Yes. baker's `@Field` decorator works alongside NestJS pipes. Use `deserialize()
 
 ### How does the AOT code generation work?
 
-Calling `seal()` once at app startup walks every registered DTO, analyzes field metadata, generates optimized JavaScript validation functions via `new Function()`, and caches them. Subsequent `deserialize`/`serialize`/`validate` calls execute the pre-compiled functions directly. There is no auto-seal — forgetting to call `seal()` raises `BakerError` on first use.
+Calling `app.seal()` once at startup walks the baker's DTOs (and their nested DTOs), analyzes field metadata, generates optimized JavaScript executor functions, and stores them on each class. Subsequent `deserialize` / `serialize` / `validate` calls run the pre-compiled functions directly. There is no auto-seal — using a DTO before `app.seal()` raises `BakerError`.
+
+> baker builds its executors with `new Function()`. Under a strict Content-Security-Policy this requires `'unsafe-eval'`; baker will not run in environments that forbid runtime code generation.
 
 ## Exports
 
 ```typescript
 import {
-  seal,
+  Baker,
   deserialize, deserializeSync, deserializeAsync,
-  validate,    validateSync,    validateAsync,
-  serialize,   serializeSync,   serializeAsync,
-  configure, createRule, Field, arrayOf, isBakerIssueSet, BakerError,
+  validate, validateSync, validateAsync,
+  serialize, serializeSync, serializeAsync,
+  createRule, Field, arrayOf, isBakerIssueSet, BakerError, RequiredType, ExcludeMode,
 } from '@zipbul/baker';
-import type { Transformer, TransformParams, BakerError, BakerIssueSet, FieldOptions, EmittableRule, RuntimeOptions } from '@zipbul/baker';
-import { isString, isEmail, isULID, isCUID2, ... } from '@zipbul/baker/rules';
-import { trimTransformer, jsonTransformer, ... } from '@zipbul/baker/transformers';
+import type { Transformer, TransformParams, BakerIssue, BakerIssueSet, FieldOptions, EmittableRule, RuntimeOptions, BakerConfig } from '@zipbul/baker';
+import { isString, isEmail, isULID, isCUID2 /* …114 rules */ } from '@zipbul/baker/rules';
+import { trimTransformer, jsonTransformer /* …and more */ } from '@zipbul/baker/transformers';
 ```
 
+Decorators are also available from the `@zipbul/baker/decorators` subpath.
+
 ## License
 
 MIT

package/dist/index.d.ts

@@ -1,11 +1,11 @@
 export { deserialize, deserializeSync, deserializeAsync } from './src/functions/deserialize';
 export { validate, validateSync, validateAsync } from './src/functions/validate';
 export { serialize, serializeSync, serializeAsync } from './src/functions/serialize';
-export { configure } from './src/configure';
 export { createRule } from './src/create-rule';
-export { seal } from './src/seal/seal';
-export { Field, arrayOf, Recipe } from './src/decorators/index';
+export { Field, arrayOf } from './src/decorators/index';
 export type { FieldOptions, ArrayOfMarker } from './src/decorators/index';
+export { Baker } from './src/baker';
+export { ExcludeMode, RequiredType } from './src/enums';
 export type { BakerIssue, BakerIssueSet } from './src/errors';
 export { isBakerIssueSet, BakerError } from './src/errors';
 export type { EmittableRule, Transformer, TransformParams } from './src/types';

package/dist/index.js

@@ -1 +1 @@
-export{deserialize,deserializeSync,deserializeAsync}from"./src/functions/deserialize.js";export{validate,validateSync,validateAsync}from"./src/functions/validate.js";export{serialize,serializeSync,serializeAsync}from"./src/functions/serialize.js";export{configure}from"./src/configure.js";export{createRule}from"./src/create-rule.js";export{seal}from"./src/seal/seal.js";export{Field,arrayOf,Recipe}from"./src/decorators/index.js";export{isBakerIssueSet,BakerError}from"./src/errors.js";
+export{deserialize,deserializeSync,deserializeAsync}from"./src/functions/deserialize.js";export{validate,validateSync,validateAsync}from"./src/functions/validate.js";export{serialize,serializeSync,serializeAsync}from"./src/functions/serialize.js";export{createRule}from"./src/create-rule.js";export{Field,arrayOf}from"./src/decorators/index.js";export{Baker}from"./src/baker.js";export{ExcludeMode,RequiredType}from"./src/enums.js";export{isBakerIssueSet,BakerError}from"./src/errors.js";