@zipbul/baker 3.4.1 → 4.0.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @zipbul/baker
 
+## 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,14 +1,28 @@
 # @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
 
@@ -23,143 +37,154 @@ class UserDto {
   @Field(isString, isEmail()) email!: string;
 }
 
-// Call once at app startup, after all DTOs are loaded.
+// Call once at app startup, after every DTO has been imported.
 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
+
+| Concept | What it does |
+| ------------------- | ------------------------------------------------------------------------------ |
+| `@Recipe`           | Marks a class as a DTO and registers it with baker.                            |
+| `@Field(...rules)`  | Declares a validated field. Only `@Field` properties are part of the contract. |
+| `seal()`            | Compiles every registered DTO into executor functions. Call once, at startup.  |
+| `deserialize` / `validate` / `serialize` | Run the sealed executors: parse+validate, validate-only, or emit a plain object. |
 
-Baker generates optimized JavaScript functions once on first seal, then executes them on every call.
+## Why baker?
 
-| 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        |
+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
+@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 +215,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,6 +243,8 @@ 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';
@@ -235,47 +262,11 @@ 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
-
-`minLength(n)`, `maxLength(n)`, `length(min, max)`, `contains(seed)`, `notContains(seed)`, `matches(regex)`
-
-### Formats
-
-`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
+> **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).
 
-`isMobilePhone(locale)`, `isPostalCode(locale)`, `isIdentityCard(locale)`, `isPassportNumber(locale)`
+## Composing DTOs
 
-## Nested DTOs
+### Nested DTOs
 
 ```typescript
 @Recipe
@@ -290,7 +281,7 @@ class UserDto {
 }
 ```
 
-## Collections
+### Collections
 
 ```typescript
 @Recipe
@@ -302,7 +293,7 @@ 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
@@ -321,7 +312,7 @@ class PetOwner {
 }
 ```
 
-## Inheritance
+### Inheritance
 
 ```typescript
 @Recipe
@@ -336,6 +327,99 @@ class UserDto extends BaseDto {
 }
 ```
 
+## Runtime API
+
+### `seal()`
+
+**Required.** Call once at app startup, after every DTO module has been imported. Takes no arguments — seals every class registered via `@Recipe` so far, plus any nested DTOs they reach. Idempotent: a second call is a no-op.
+
+`deserialize` / `serialize` / `validate` throw `BakerError` if the DTO is not sealed.
+
+### `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.
+
+### `configure(config)`
+
+Global configuration. Must be called **before** `seal()`. After seal, `configure(...)` throws `BakerError`.
+
+```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
+});
+```
+
+### `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
+const isEven = createRule({
+  name: 'isEven',
+  validate: v => typeof v === 'number' && v % 2 === 0,
+  requiresType: '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 `seal()`, passing a raw rule function, calling `configure()` after seal, 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,7 +440,9 @@ 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 `seal()` once at app startup walks every registered DTO, analyzes field metadata, generates optimized JavaScript executor functions, and caches them. Subsequent `deserialize` / `serialize` / `validate` calls run the pre-compiled functions directly. There is no auto-seal — forgetting to call `seal()` raises `BakerError` on first use.
+
+> 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
 
@@ -364,15 +450,17 @@ Calling `seal()` once at app startup walks every registered DTO, analyzes field
 import {
   seal,
   deserialize, deserializeSync, deserializeAsync,
-  validate,    validateSync,    validateAsync,
-  serialize,   serializeSync,   serializeAsync,
-  configure, createRule, Field, arrayOf, isBakerIssueSet, BakerError,
+  validate, validateSync, validateAsync,
+  serialize, serializeSync, serializeAsync,
+  configure, createRule, Field, Recipe, arrayOf, isBakerIssueSet, BakerError,
 } 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 } 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

@@ -6,6 +6,9 @@ export { createRule } from './src/create-rule';
 export { seal } from './src/seal/seal';
 export { Field, arrayOf, Recipe } from './src/decorators/index';
 export type { FieldOptions, ArrayOfMarker } from './src/decorators/index';
+export { createBaker } from './src/baker';
+export type { 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{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{createBaker}from"./src/baker.js";export{ExcludeMode,RequiredType}from"./src/enums.js";export{isBakerIssueSet,BakerError}from"./src/errors.js";

package/dist/src/baker.d.ts

@@ -0,0 +1,26 @@
+import type { BakerConfig } from './configure';
+/**
+ * A baker scope — an isolated registration + seal boundary. Each `createBaker()` owns its own
+ * registry and config; classes sealed through it are attributed to it, so separate scopes never
+ * mix. `@Field`, rules, transformers, and `deserialize/serialize/validate` stay global (they read
+ * the metadata/executor stored on the class), so only the class-collecting `Recipe` and `seal` are
+ * scoped.
+ */
+export interface Baker {
+    /** Class decorator — registers the class as a root of THIS scope. Use as `@app.Recipe`. */
+    readonly Recipe: (value: Function, context: ClassDecoratorContext) => void;
+    /** Seal every root registered to this scope (and its nested DTOs) with this scope's config. */
+    readonly seal: () => void;
+}
+/**
+ * Create an isolated baker scope. Use for libraries and multi-app processes where each app must
+ * not mix with another. Single-app code can keep using the global `@Recipe` / `seal()` / `configure()`.
+ *
+ * ```ts
+ * const app = createBaker({ autoConvert: true });
+ * @app.Recipe class UserDto { @Field(isString) name!: string }
+ * app.seal();
+ * deserialize(UserDto, input); // global — reads UserDto's sealed executor
+ * ```
+ */
+export declare function createBaker(config?: BakerConfig): Baker;

package/dist/src/baker.js

@@ -0,0 +1 @@
+import{normalizeConfig as H}from"./configure.js";import{sealRegistry as I}from"./seal/seal.js";export function createBaker(j){const q=new Set,E=j===void 0?Object.freeze({}):H(j);let A=!1;return{Recipe(G){q.add(G)},seal(){if(A)return;I(q,E);A=!0}}}

package/dist/src/configure.d.ts

@@ -16,9 +16,15 @@ interface BakerConfig {
  * If not called, defaults are applied.
  */
 declare function configure(config: BakerConfig): void;
+/**
+ * Validate a BakerConfig and map it to the internal SealOptions. Shared by `configure()`
+ * (default instance) and `createBaker()` (per-scope instances). Does NOT check seal state —
+ * that gate is specific to the global `configure()`.
+ */
+declare function normalizeConfig(config: BakerConfig): SealOptions;
 /** @internal — used by seal. Returns the frozen global options; the only way to change them is configure(). */
 declare function getGlobalOptions(): SealOptions;
 /** @internal — reset to defaults on unseal */
 declare function resetConfigForTesting(): void;
-export { configure, getGlobalOptions, resetConfigForTesting };
+export { configure, getGlobalOptions, resetConfigForTesting, normalizeConfig };
 export type { BakerConfig };

package/dist/src/configure.js

@@ -1 +1 @@
-import{BakerError as j}from"./errors.js";import{isSealed as w}from"./seal/seal-state.js";const v=new Set(["autoConvert","allowClassDefaults","stopAtFirstError","forbidUnknown","debug"]);let m=Object.freeze({});function configure(h){if(w())throw new j("[baker] configure() called after seal(). Already-sealed classes are not affected. Call configure() before seal().");if(h===null||typeof h!=="object"||Array.isArray(h))throw new j(`[baker] configure() requires a plain object. Received: ${h===null?"null":Array.isArray(h)?"array":typeof h}.`);for(const q of Object.keys(h))if(!v.has(q))throw new j(`[baker] configure(): unknown key '${q}'. Valid keys: ${[...v].join(", ")}.`);m=Object.freeze({enableImplicitConversion:h.autoConvert??!1,exposeDefaultValues:h.allowClassDefaults??!1,stopAtFirstError:h.stopAtFirstError??!1,whitelist:h.forbidUnknown??!1,debug:h.debug??!1})}function getGlobalOptions(){return m}function resetConfigForTesting(){m=Object.freeze({})}export{configure,getGlobalOptions,resetConfigForTesting};
+import{BakerError as j}from"./errors.js";import{isSealed as x}from"./seal/seal-state.js";const w=new Set(["autoConvert","allowClassDefaults","stopAtFirstError","forbidUnknown","debug"]);let q=Object.freeze({});function configure(h){if(x())throw new j("[baker] configure() called after seal(). Already-sealed classes are not affected. Call configure() before seal().");q=normalizeConfig(h)}function normalizeConfig(h){if(h===null||typeof h!=="object"||Array.isArray(h))throw new j(`[baker] config requires a plain object. Received: ${h===null?"null":Array.isArray(h)?"array":typeof h}.`);for(const v of Object.keys(h))if(!w.has(v))throw new j(`[baker] unknown key '${v}'. Valid keys: ${[...w].join(", ")}.`);return Object.freeze({enableImplicitConversion:h.autoConvert??!1,exposeDefaultValues:h.allowClassDefaults??!1,stopAtFirstError:h.stopAtFirstError??!1,whitelist:h.forbidUnknown??!1,debug:h.debug??!1})}function getGlobalOptions(){return q}function resetConfigForTesting(){q=Object.freeze({})}export{configure,getGlobalOptions,resetConfigForTesting,normalizeConfig};