@zipbul/baker 3.0.0 → 3.0.1

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @zipbul/baker
 
+## 3.0.1
+
+### Patch Changes
+
+- ea40a75: Docs/metadata accuracy: every README example now includes the required `@Recipe` decorator
+  (without it `seal()` does not register the class and `deserialize` throws), drop the
+  unnecessary `() => Set as any` / `Map as any`, state the Bun-only requirement (Bun ≥ 1.3.13),
+  and replace unsubstantiated speed multipliers with honest qualitative claims. Refresh the
+  package description and remove the now-redundant MIGRATION-3.0.md (its content lives in the
+  CHANGELOG 3.0.0 entry).
+
 ## 3.0.0
 
 ### Major Changes
@@ -21,35 +32,31 @@
   mode was removed — call a rule directly instead). `configure()` rejects unknown keys and
   post-`seal()` calls, and seal-time options can no longer be passed per-call.
 
-  See `MIGRATION-3.0.md` for the full upgrade guide.
-
 ### Minor Changes
 
 - 421fd54: Add the `isHttpToken` rule — validates the RFC 9110 §5.6.2 HTTP `token` production
   (`1*tchar`), used for HTTP method names and header field-names. Usable as a predicate
   (`isHttpToken(value)`) or as `@Field(isHttpToken)`, and exported from `@zipbul/baker/rules`.
 
-## 3.0.0
-
 ### DX reform — breaking changes
 
-- **Auto-seal removed.** Call `seal()` once at app startup, after every DTO module is loaded. Without it, the first `deserialize` / `serialize` / `validate` call throws `SealError`.
+- **Auto-seal removed.** Call `seal()` once at app startup, after every DTO module is loaded. Without it, the first `deserialize` / `serialize` / `validate` call throws `BakerError`.
   - Migration: import `seal` and call `seal()` once before any deserialize/serialize/validate call. For tests, call `seal()` after each `unseal()` / `configure(...)` reconfiguration.
-- **Per-call options are validated.** Only `groups` is a valid per-call option. Passing any other key (`stopAtFirstError`, `autoConvert`, `allowClassDefaults`, `forbidUnknown`, `debug`, …) throws `SealError`. Move those keys into `configure({...})` before `seal()`.
-- **`@Field` argument validation.** Passing a non-rule value (e.g. `@Field(isNumber)` instead of `@Field(isNumber())`) now throws `SealError` immediately with the four valid forms listed in the message.
-- **Map non-string keys.** Serializing a `Map<K, V>` whose key is not a `string` throws `TypeError` — previously the key was silently coerced via `[object Object]` and collided.
+- **Per-call options are validated.** Only `groups` is a valid per-call option. Passing any other key (`stopAtFirstError`, `autoConvert`, `allowClassDefaults`, `forbidUnknown`, `debug`, …) throws `BakerError`. Move those keys into `configure({...})` before `seal()`.
+- **`@Field` argument validation.** Passing a non-rule value (e.g. `@Field(isNumber)` instead of `@Field(isNumber())`) now throws `BakerError` immediately with the four valid forms listed in the message.
+- **Map non-string keys.** Serializing a `Map<K, V>` whose key is not a `string` throws `BakerError` — previously the key was silently coerced via `[object Object]` and collided.
 
 ### API additions
 
 - `seal(...classes?)` — explicit AOT seal trigger.
-- `deserializeSync<T>` / `deserializeAsync<T>` / `serializeSync<T>` / `serializeAsync<T>` / `validateSync` / `validateAsync` — strict variants. `*Sync` throws `SealError` when the DTO is async on the relevant direction; `*Async` always returns `Promise`.
+- `deserializeSync<T>` / `deserializeAsync<T>` / `serializeSync<T>` / `serializeAsync<T>` / `validateSync` / `validateAsync` — strict variants. `*Sync` throws `BakerError` when the DTO is async on the relevant direction; `*Async` always returns `Promise`.
 
 ### Defect fixes
 
 - **F-1** `circular-analyzer.walk()` now walks `meta.type.collectionValue` — Set/Map nested DTO cycles are caught at seal time, no more `stack overflow` at runtime.
-- **F-2** Discriminator / Set·Map / inheritance invariants now run before codegen via the new `validate-meta` pass — invalid metadata throws `SealError` with a precise message instead of producing invalid generated JS.
+- **F-2** Discriminator / Set·Map / inheritance invariants now run before codegen via the new `validate-meta` pass — invalid metadata throws `BakerError` with a precise message instead of producing invalid generated JS.
 - **F-3** Discriminator default branch now reports `context: { received, validSubTypes: [...] }` so callers can show the user the allowed values.
-- **F-4** Per-call options other than `groups` are rejected with `SealError` instead of being silently dropped.
+- **F-4** Per-call options other than `groups` are rejected with `BakerError` instead of being silently dropped.
 - **F-8** FR passport regex now anchors both ends (`/^[A-Z0-9]{9}$/i`).
 - **F-9** `MAGNET_URI_RE` is anchored on the trailing end.
 - **N-3** Circular-detection `WeakSet` is now allocated per call via `Symbol.for('baker:circular-seen')` threaded through `_opts` — concurrent async calls no longer false-circular on shared input objects.

package/README.md

@@ -8,12 +8,15 @@ bun add @zipbul/baker
 
 Zero `reflect-metadata`. Sealed codegen. 99%+ line coverage.
 
+> **Requires Bun ≥ 1.3.13.** baker relies on TC39 decorator metadata (`Symbol.metadata`), which Node does not populate — it is Bun-only.
+
 ## Quick Start
 
 ```typescript
-import { deserialize, isBakerIssueSet, Field, seal } from '@zipbul/baker';
+import { deserialize, isBakerIssueSet, Field, Recipe, seal } from '@zipbul/baker';
 import { isString, isNumber, isEmail, min, minLength } from '@zipbul/baker/rules';
 
+@Recipe
 class UserDto {
   @Field(isString, minLength(2)) name!: string;
   @Field(isNumber(), min(0)) age!: number;
@@ -106,9 +109,13 @@ configure({
 });
 ```
 
-### `createRule(name, validate)`
+### `createRule(name, validate)` / `createRule(options)`
 
-Custom validation rule.
+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({
@@ -139,6 +146,7 @@ Each rule must be an emittable rule object created via `createRule()` or one of
 | ----------------- | ------------------------------------------------- | ------------------------------ |
 | `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      |
@@ -215,6 +223,7 @@ email!: string;
 import { luxonTransformer } from '@zipbul/baker/transformers';
 const luxon = await luxonTransformer({ zone: 'Asia/Seoul' });
 
+@Recipe
 class EventDto {
   @Field({ transform: luxon }) startAt!: DateTime;
 }
@@ -269,10 +278,12 @@ const mt = await momentTransformer({ format: 'YYYY-MM-DD' });
 ## Nested DTOs
 
 ```typescript
+@Recipe
 class AddressDto {
   @Field(isString) city!: string;
 }
 
+@Recipe
 class UserDto {
   @Field({ type: () => AddressDto }) address!: AddressDto;
   @Field({ type: () => [AddressDto] }) addresses!: AddressDto[];
@@ -282,15 +293,19 @@ class UserDto {
 ## Collections
 
 ```typescript
+@Recipe
 class UserDto {
-  @Field({ type: () => Set as any, setValue: () => TagDto }) tags!: Set<TagDto>;
-  @Field({ type: () => Map as any, mapValue: () => PriceDto }) prices!: Map<string, PriceDto>;
+  @Field({ type: () => Set, setValue: () => TagDto }) tags!: Set<TagDto>;
+  @Field({ type: () => Map, mapValue: () => PriceDto }) prices!: Map<string, PriceDto>;
 }
 ```
 
+> 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
 
 ```typescript
+@Recipe
 class PetOwner {
   @Field({
     type: () => CatDto,
@@ -309,10 +324,12 @@ class PetOwner {
 ## Inheritance
 
 ```typescript
+@Recipe
 class BaseDto {
   @Field(isString) id!: string;
 }
 
+@Recipe
 class UserDto extends BaseDto {
   @Field(isString) name!: string;
   // inherits 'id' field with isString rule
@@ -323,11 +340,11 @@ class UserDto extends BaseDto {
 
 ### When should I use baker instead of class-validator?
 
-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.
+When performance matters. baker generates optimized validation/serialization code at seal time instead of interpreting rules on every call, so it is substantially faster than class-validator on both valid and invalid input while providing the same decorator-based DX. baker also eliminates the `reflect-metadata` dependency. Run [`bench/`](./bench) to measure the exact difference on your machine.
 
 ### How does baker compare to Zod?
 
-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.
+Zod uses schema method chains (`z.string().email()`), baker uses decorators (`@Field(isString, isEmail())`). baker generates optimized code at definition time instead of interpreting schemas at runtime. Choose Zod if you need schema-first design or Node support; choose baker if you need class-based DTOs on Bun with maximum performance.
 
 ### Does baker support async validation?
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zipbul/baker",
-  "version": "3.0.0",
-  "description": "Fastest decorator-based DTO validation for TypeScript. AOT code generation, 42ns per validation, 163x faster than class-validator. Zero reflect-metadata.",
+  "version": "3.0.1",
+  "description": "Bun-only AOT decorator-based DTO validation & serialization. class-validator DX, sealed code generation, zero reflect-metadata.",
   "keywords": [
     "aot",
     "bun",
@@ -37,7 +37,6 @@
     "dist/**/*.d.ts",
     "README.md",
     "CHANGELOG.md",
-    "MIGRATION-3.0.md",
     "LICENSE"
   ],
   "type": "module",

package/MIGRATION-3.0.md

@@ -1,104 +0,0 @@
-# Baker 2.x → 3.x Migration
-
-This release replaces the implicit "auto-seal on first call" model with explicit, user-triggered `seal()`. It also tightens per-call options validation and adds strict sync/async variants.
-
-## Required changes
-
-### 1. Call `seal()` once at app startup
-
-**Before**
-
-```ts
-// Module load registers DTOs; first deserialize implicitly seals everything.
-const r = await deserialize(UserDto, payload);
-```
-
-**After**
-
-```ts
-import { seal, deserialize } from '@zipbul/baker';
-// Call after every DTO module has been imported (before HTTP server / job runner starts).
-seal();
-const r = await deserialize(UserDto, payload);
-```
-
-`deserialize` / `serialize` / `validate` throw `BakerError` if the DTO is not sealed.
-
-### 2. Move per-call options into `configure(...)`
-
-Only `groups` survives as a per-call option.
-
-**Before**
-
-```ts
-await deserialize(UserDto, payload, { stopAtFirstError: true });
-```
-
-**After**
-
-```ts
-import { configure, seal } from '@zipbul/baker';
-configure({ stopAtFirstError: true });
-seal();
-await deserialize(UserDto, payload);
-```
-
-All other keys (`stopAtFirstError`, `autoConvert`, `allowClassDefaults`, `forbidUnknown`, `debug`) and their legacy `SealOptions` aliases (`enableImplicitConversion`, `exposeDefaultValues`, `whitelist`) now throw `BakerError` when passed per-call.
-
-### 3. `configure()` must run before `seal()`
-
-After `seal()`, `configure(...)` throws `BakerError`. Tests that need to reconfigure must call the test-only `unseal()` helper, change config, then `seal()` again.
-
-### 4. `@Field` argument validation is strict
-
-Passing a non-rule value (factory not invoked, primitive, plain function without `.emit` / `.ruleName`) throws `BakerError` at decorator-evaluation time with the four valid forms listed.
-
-```ts
-@Field(isNumber)       // ✗ factory not invoked → BakerError
-@Field(isNumber())     // ✓
-@Field(isString)       // ✓ constant rule
-@Field()               // ✓ marker only
-@Field(isString, { optional: true })       // ✓
-@Field({ type: () => NestedDto })          // ✓
-```
-
-### 5. `Map<K, V>` requires string keys at serialize
-
-Serializing a `Map` with non-string keys throws `TypeError`. Previously the key was silently coerced via `String(key)`, producing collisions like `'[object Object]'`.
-
-### 6. New strict sync/async variants
-
-Six new entry points enforce the call-direction asymmetry at the type level:
-
-| Integrated    | Strict sync       | Strict async       |
-| ------------- | ----------------- | ------------------ |
-| `deserialize` | `deserializeSync` | `deserializeAsync` |
-| `serialize`   | `serializeSync`   | `serializeAsync`   |
-| `validate`    | `validateSync`    | `validateAsync`    |
-
-`*Sync` throws `BakerError` if the DTO is async on that direction (e.g. async transform on deserialize side for `deserializeSync`). `*Async` always returns `Promise` (sync DTOs are wrapped via `Promise.resolve`). The integrated `deserialize` / `serialize` / `validate` remain available for ergonomic use.
-
-## Defect fixes (no migration needed)
-
-The following bugs in 2.x are silently fixed in 3.x:
-
-- **Set/Map nested DTO cycles** no longer cause stack overflow (`circular-analyzer` now walks `collectionValue`).
-- **Set/Map value DTOs marked async** now correctly propagate `_isAsync` / `_isSerializeAsync` to the parent.
-- **Discriminator with empty `subTypes`** throws `BakerError` at seal time instead of producing invalid generated JS.
-- **Concurrent async deserialize on the same input** no longer reports a false `circular` error (per-call `WeakSet` via `Symbol.for('baker:circular-seen')`).
-- **`Object.hasOwn` checks** prevent prototype-chain values from leaking into DTO results.
-- **Discriminator default branch** error now reports `context: { received, validSubTypes: [...] }`.
-- **FR passport regex** now anchors both ends.
-- **MAGNET URI regex** now anchors the trailing end.
-- **Inheritance dedup** now compares by `ruleName` — a child re-declaring the same rule replaces the parent's rule.
-- **`seal(Class)` failure** is now transactional: a failed seal removes the placeholder so retry can succeed.
-- **`collectionValue` thunk** errors are wrapped in `BakerError` with the field name.
-
-## Removed APIs
-
-- `_runSealed` (was internal, but some test code depended on it). Use the public functions instead.
-
-## Notes
-
-- The decorator-side registry (`globalRegistry`) is still used internally as an index of decorated classes so `seal()` (no args) can seal everything. This is not auto-seal — `seal()` must be called explicitly.
-- `unseal()` is exported by `test/integration/helpers/unseal.ts` for testing only. It is not part of the public API.