@zipbul/baker 2.1.0 → 3.0.0

package/CHANGELOG.md

@@ -0,0 +1,256 @@
+# @zipbul/baker
+
+## 3.0.0
+
+### Major Changes
+
+- 421fd54: 3.0 — error system redesign and API hardening (breaking).
+
+  **Error channel.** A single `BakerError` class is now thrown for every developer/config/schema
+  misuse (it carries `cause`). The validation-result types are renamed for clarity:
+
+  - `SealError` → `BakerError` (the thrown class)
+  - the field-error interface `BakerError` → `BakerIssue`
+  - `BakerErrors` → `BakerIssueSet`
+  - `isBakerError` → `isBakerIssueSet`
+
+  The split is now explicit: **throw `BakerError`** for misuse discoverable without input;
+  **return `BakerIssueSet`** for external-input validation failures from `deserialize`/`validate`.
+
+  **API hardening.** `validate(Class, input)` is DTO-only (the ad-hoc `validate(value, ...rules)`
+  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`.
+  - 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.
+
+### 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`.
+
+### 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-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-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.
+- **N-4** `extractCode` checks `Object.hasOwn(input, key)` before reading — prototype-chain values no longer leak into DTO results.
+- **N-6** `mergeInheritance` validation dedup now compares by `ruleName`, so a child redeclaring the same rule (e.g. `minLength(5)`) replaces the parent's rule instead of producing duplicate errors.
+
+### Dead code
+
+- `src/functions/_run-sealed.ts` removed. The corresponding internal-only tests in `test/e2e/change-coverage.test.ts` were dropped — their coverage is now provided by public-API tests.
+
+## 2.2.0
+
+### Minor Changes
+
+- 78d701a: feat: validate-only executor with inline nested code generation
+
+  - Add `_validate` sealed executor — validates input without Object.create or property assignment
+  - validate() now uses dedicated `_validate` executor instead of routing through `_deserialize`
+  - Inline nested DTO validation: nested DTO fields are expanded directly into the parent function body, eliminating per-item function call overhead
+  - Recursive inline for all nesting patterns: nested objects, arrays of nested, discriminator, collections (Set/Map), transforms, groups
+  - Only circular references fall back to function call (physically impossible to inline)
+  - 14 refs-based validators converted to inline emit (isISBN, isISIN, isIBAN, isFQDN, etc.)
+  - Type gate dead code removal: 11 redundant checks eliminated in gated paths
+  - Rule Plan IR `stripSelfComparison` for AST-level optimization inside type gates
+  - Shared codegen utilities extracted to `codegen-utils.ts`
+  - GEN constants centralized in serialize-builder to prevent typo-related bugs
+  - `makeRule`/`makePlannedRule` factory functions for cleaner rule creation
+  - Sync/async contract enforcement for declared-sync rules
+
+  Performance:
+
+  - validate() nested 3-level: 8.79ns (typebox: 11.56ns) — 1.3x faster than typebox
+  - validate() array 1000 items: 2.35µs (typebox: 2.37µs) — equivalent to typebox
+  - validate() vs deserialize(): 2-5x faster across all benchmarks
+  - Zero memory leaks verified under 10M sustained operations
+  - 26.6M ops/sec throughput (validate valid, flat DTO)
+
+## 2.1.0
+
+### Minor Changes
+
+- 5696199: feat: Transformer interface, built-in transformers, isULID, isCUID2
+
+  ### Breaking Changes
+
+  - `FieldOptions.transform` now accepts `Transformer | Transformer[]` instead of function
+  - `FieldTransformParams`, `FieldTransformFn` types removed — use `Transformer` interface
+  - `transformDirection` option removed — use passthrough in the unused direction method
+  - Serialize direction applies transforms in reverse order (codec stack)
+
+  ### New Features
+
+  - `Transformer` interface with separate `deserialize`/`serialize` methods
+  - `transform` option accepts arrays — serialize applies in reverse order
+  - `type` + `transform` combination support in serialize (nested serialize → transform)
+  - 9 built-in core transformers: trim, toLowerCase, toUpperCase, round, unixSeconds, unixMillis, isoString, csv, json
+  - 2 optional peer transformers: luxon, moment (async factory, `await import()`)
+  - `isULID()` validator
+  - `isCUID2()` validator
+  - `@zipbul/baker/transformers` subpath export
+
+  ### Improvements
+
+  - `when` callback typed as `(obj: Record<string, any>)` instead of `any`
+  - Sourcemap removed from build output
+  - README rewritten with GEO optimization (FAQ, benchmarks, comparison tables)
+  - package.json description and keywords optimized
+
+## 2.0.0
+
+### Major Changes
+
+- 5d01955: feat!: v2 API overhaul — isBakerError, validate, performance optimization
+
+  ### Breaking Changes
+
+  - `deserialize()` no longer throws on validation failure — returns `T | BakerErrors | Promise<T | BakerErrors>`
+  - `serialize()` returns directly for sync DTOs — `Record<string, unknown> | Promise<Record<string, unknown>>`
+  - `BakerValidationError` class removed — use `isBakerError()` type guard
+  - `toJsonSchema()` removed
+  - `@Schema` decorator and `schema` field option removed
+  - `JsonSchemaOverride`, `ToJsonSchemaOptions` types removed
+  - `BAKER_ERROR` symbol no longer exported (internal only)
+  - `README.ko.md` removed
+
+  ### New Features
+
+  - `validate(Class, input, options?)` — DTO-level validation without instantiation
+  - `validate(input, ...rules)` — ad-hoc single value validation
+  - `isBakerError()` — type guard for narrowing validation results
+  - Sync DTOs return directly (no Promise wrapper) across all APIs
+  - Memory leak detection CI step
+
+  ### Performance
+
+  - Valid path: 188ns → 38ns (5x improvement)
+  - Invalid path: 6.08µs → 76ns (80x improvement)
+
+  ### Bug Fixes
+
+  - WeakSet circular detection false positive on same-object reuse
+  - serialize-builder async discriminator array syntax error
+  - 13 rules missing constraints in metadata
+
+## 1.1.0
+
+### Minor Changes
+
+- b27cdf6: ## New Features
+
+  - **Sync API optimization** — `deserialize()` and `serialize()` are no longer `async function`. Sync DTOs (no async transforms/rules) skip `Promise` allocation via `Promise.resolve()`. Async DTOs use the executor's native `Promise`. Return type remains `Promise<T>` for backward compatibility.
+
+  - **Map/Set auto-conversion** — New `type: () => Map` and `type: () => Set` support in `@Field()`:
+
+    - `Set<T>`: JSON array ↔ `Set`, with optional `setValue: () => DtoClass` for nested DTOs
+    - `Map<string, T>`: JSON object ↔ `Map`, with optional `mapValue: () => DtoClass` for nested DTOs
+    - JSON Schema: Set → `{ type: 'array', uniqueItems: true }`, Map → `{ type: 'object', additionalProperties }`
+
+  - **Per-field error messages** — `message` and `context` options on `@Field()` apply to all rules on the field. Supports static strings, dynamic functions with `{ property, value, constraints }`, and arbitrary context values including falsy ones (`0`, `false`, `''`).
+
+  ## Chores
+
+  - Translate all Korean comments and documentation to English (82 files)
+  - Delete REVIEW.md (all 42 items completed)
+  - 1808 tests, 2639 assertions
+
+## 1.0.0
+
+### Major Changes
+
+- b7ea675: ## Breaking Changes
+
+  - **`@Field()` unified decorator** — Replaces 30+ individual decorators with a single `@Field()` that accepts rules as arguments and options as an object.
+  - **Auto-seal** — `seal()` removed. DTOs auto-seal on first `deserialize()`/`serialize()` call.
+  - **`configure()` replaces `seal()` options** — `configure({ autoConvert, stopAtFirstError, forbidUnknown, ... })`.
+  - **`configure()` returns `{ warnings: string[] }`** instead of `void`.
+  - **`enableCircularCheck` removed** — Circular detection always runs automatically.
+  - **`stripUnknown` renamed to `forbidUnknown`** — `stripUnknown` kept as deprecated alias.
+
+  ## Bug Fixes
+
+  - C-1: Fix analyzeAsync discriminator visited Set sharing (infinite recursion risk)
+  - C-2: Fix Set/Map stopAtFirstError error path missing element index
+  - C-3: Fix discriminator JSON Schema $ref+properties sibling (allOf wrapper)
+  - C-5: Throw on isDivisibleBy(0)
+  - C-6: Fix isURL accepting ports 65536-99999
+  - C-7: Fix isNumber maxDecimalPlaces scientific notation bypass
+  - C-8: Implement serialize discriminator with instanceof dispatch
+  - C-9: Fix nullable $ref invalid JSON Schema (oneOf wrapper)
+  - C-11: Null guard for nested array serialize
+  - C-12: Throw on min(NaN)/max(Infinity)
+  - C-13~C-17, B-1~B-11: 11 additional safety guards and silent failure fixes
+
+  ## New Features
+
+  - Debug mode: `configure({ debug: true })`
+  - `onUnmappedRule` callback for `toJsonSchema()`
+  - `forbidUnknown` option (renamed from `stripUnknown`)
+
+  ## Refactoring
+
+  - Decompose buildRulesCode (250 lines → 5 functions) and Field() (125 lines → 4 helpers)
+  - Deduplicate Array/Set/Map each codegen, extract GEN constants, strategy pattern for nullable/optional
+  - 1730 tests, 2509 assertions, 99.94% Funcs / 99.83% Lines
+
+## 0.1.2
+
+### Patch Changes
+
+- 76657db: fix: pin CI Bun version to 1.3.9 to avoid 1.3.10 bundler regression, optimize isIn/isNotIn with Set, improve npm packaging and test coverage
+
+## 0.1.1
+
+### Patch Changes
+
+- 95ce993: Add coverage badge gist configuration
+
+## 0.1.0
+
+### Minor Changes
+
+- 214f664: ### Breaking Changes
+
+  - Remove `src/aot/` module and `@zipbul/baker/aot` subpath export. The zipbul CLI now reads baker decorators directly via AST.
+  - `MessageArgs.constraints` type changed from `unknown[]` to `Record<string, unknown>`.
+  - Default behavior for fields without `@IsOptional`/`@IsNullable`: `undefined`/`null` input now emits `isDefined` error code instead of falling through to type gate errors (e.g., `isString`).
+
+  ### Features
+
+  - **`@Nested(fn, opts?)`** — Single-decorator shorthand for `@ValidateNested()` + `@Type(fn)` with discriminator support.
+  - **`@IsNullable()`** — Allow `null` (skip validation), reject `undefined`. Complements `@IsOptional()` for OAS 3.0 `nullable: true` semantics.
+  - **`@Schema(schema)`** — Attach JSON Schema Draft 2020-12 metadata at class or property level. Supports object and function forms.
+  - **`toJsonSchema(Class, opts?)`** — Generate JSON Schema Draft 2020-12 from DTO decorators. Supports `direction`, `groups`, circular references, discriminator `oneOf`, and `@Schema()` overrides.
+  - **`seal({ whitelist: true })`** — Reject undeclared fields with `whitelistViolation` error code.
+  - **`@Min(n, { exclusive: true })` / `@Max(n, { exclusive: true })`** — Exclusive minimum/maximum support.
+  - **`enableImplicitConversion`** — Automatic type conversion (string/number/boolean/date) based on `requiresType` and `@Type()` hints.
+  - **`EmittableRule.constraints`** — All built-in rules now expose their parameters via `constraints` for JSON Schema mapping and `message` callback access.
+  - **`requiresType` expansion** — Added `'boolean'` and `'date'` variants. Fixed silent rule loss for non-string/non-number `requiresType` values.
+
+  ### Internal
+
+  - Upgrade `@zipbul/result` from `^0.0.3` to `^0.1.4` and adopt `Result<T, E>` / `ResultAsync<T, E>` type aliases.
+  - Fix seal placeholder to throw `SealError` instead of bare `Error`.
+  - Remove dead branch in deserialize input type guard.

package/MIGRATION-3.0.md

@@ -0,0 +1,104 @@
+# 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.