@warlock.js/seal 5.30.0 → 5.31.0

package/CHANGELOG.md

@@ -4,33 +4,63 @@ All notable changes to `@warlock.js/seal` are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). `@warlock.js/*` packages are released in lockstep — every package shares the same version number, so a version below may list only the changes that affected this package.
 
+## 5.31.0 - 2026-10-18
+
+### Upgrading
+
+- **BREAKING:** a failed `v.union(...)` reports the closest member's errors at their own paths (`actor.id` instead of `actor`), still typed `union`; with `firstErrorOnly: false` it reports each of that member's errors separately instead of one `;`-joined message from every member. A custom union message, or a value no member can hold by type, still gives one error at the union's path. Update code that reads union errors by path or splits the joined message.
+- **BREAKING:** `.refine()` now runs against successful output after child validation and transformers, and skips absent/null or invalid values. Callbacks are typed from the validator's output instead of `any`. Move checks that need input before child validation to `.addRule()`. `warlock upgrade --from 5.30 --to 5.31.0` lists every `.refine()` to review (codemod `seal-refine-output`).
+- **BREAKING:** `.catch()` is a no-op on container validators, including failures in the container's own rules. Inputs previously accepted by an array/object catch after a length or unknown-key error now fail. Apply catches to child validators or handle a failed container result explicitly. `warlock upgrade --from 5.30 --to 5.31.0` lists `.catch()` calls on containers (codemod `seal-container-catch`).
+- **BREAKING:** `v.union()` now returns its matched branch's validated output. Trimming and date parsing change values; object defaults/computed fields are retained, stripped unknown keys disappear, and an explicit `undefined` output drops the containing object field. Persisted, compared or serialized output can differ. Read and keep the raw input before validation when you need it. `warlock upgrade --from 5.30 --to 5.31.0` lists every `v.union()` to review (codemod `seal-union-output`).
+- Refinements now also check successful empty defaults such as `.default("")`; callbacks that reject those defaults now reject validation.
+
+### Changed
+
+- Object factories return their already typed class directly, avoiding a duplicate Standard Schema intersection and reducing compiler work for composed schemas. CI now checks the Seal inference benchmark against its updated baseline.
+
+### Fixed
+
+- `v.union(...)` tries every member whose type matches before failing, so a union of several object schemas accepts a value that matches a later member; `firstErrorOnly` limits the errors reported, not the members tried. A failing union reports its closest member: fewest mismatched literals, then fewest errors, then the deepest error path, then declaration order.
+- A failing union no longer stores its last member error on the shared rule, so a later validation with no type-matching member reports the default message instead of a stale one.
+- The custom-error locale example is strict JSON, with its filename outside the code fence.
+- Standalone string replacement mutators accept an omitted context or options and preserve the stringified input instead of throwing.
+- Object `.merge()` retains refinements from both schemas, in their original order; cloning, extending and selecting fields preserve the original schema's refinements.
+- Union and record Standard Schema types now distinguish child input from validated output; `Infer.Output` reads the Standard Schema output parameter. Defaults and catches remain guaranteed in output.
+- Object, array, tuple and lazy Standard Schema output declarations preserve child defaults and catches independently of their input types.
+- `v.tuple([...])` infers one type per position: `v.tuple([v.string(), v.int()])` is typed `[string, number]` for input and output instead of `(string | number)[]`, so a value with swapped positions no longer type-checks. A `BaseValidator[]` variable is still accepted.
+
+### Added
+
+- A failed rule result may carry `errors: [{ error, path }]` to report several errors, each at its own path, under the rule's type.
+- Successful custom rules may return a `data` property to replace the current validated value, including explicit `undefined`; omitting the property preserves the value.
+
 ## 5.30.0 - 2026-10-16
 
 ### Upgrading
 
-- **BREAKING (types only):** `validate()` now returns a result narrowed on `isValid`. On success `data` is `Infer.Output<typeof schema>`, on failure it is `undefined`. Code that read `result.data` without checking `isValid`, or assigned it to an unrelated type, may need a check or a cast. A schema typed as bare `BaseValidator`/`ObjectValidator` keeps `data: any`.
+- **BREAKING (types only):** `validate()` now returns a result narrowed on `isValid`. On success `data` is `Infer.Output<typeof schema>`, on failure it is `undefined`. Code that read `result.data` without checking `isValid`, or assigned it to an unrelated type, may need a check or a cast. A schema typed as bare `BaseValidator`/`ObjectValidator` keeps `data: any`. `warlock upgrade --from 5.29 --to 5.31.0` lists `validate()` results read without an `isValid` check (codemod `seal-validate-result`).
 
 ### Added
 
 - `TypedValidationResult<T>` and `ValidatedOutput<T>` types.
-- `pnpm bench:types` measures inference compile cost on a generated composed-schema project (16 entities, 8 services) and fails when instantiations or types grow more than 5% over `bench/types-baseline.json` (WR-001). It also fails when it cannot read a metric or is given a malformed option, warns when the TypeScript version differs from the baseline's (`--strict` makes that a failure), and removes its temporary project on Ctrl+C.
+- `pnpm bench:types` measures inference compile cost on a generated composed-schema project (16 entities, 8 services) and fails when instantiations or types grow more than 5% over `bench/types-baseline.json`. It also fails when it cannot read a metric or is given a malformed option, warns when the TypeScript version differs from the baseline's (`--strict` makes that a failure), and removes its temporary project on Ctrl+C.
 
 ### Changed
 
 - `validate()` takes `data: unknown` instead of `any`.
 - `Infer.Input`/`Infer.Output` of an object is one flat object type instead of an intersection of its optional and required halves; the shape is unchanged and compile cost moves by 0.1%.
 - `pnpm typecheck` now also checks the `expectTypeOf` assertions in `tests/unit/types/` (`tsconfig.typecheck.json`); they were never enforced before.
-- `.refine()` callbacks stay `value: any` on purpose: custom rules run before an object or array validates its children, so the value is not the schema output (WR-020).
+- `.refine()` callbacks stay `value: any` on purpose: custom rules run before an object or array validates its children, so the value is not the schema output.
 - **Behaviour change:** `v.union([...])` now checks a present empty value (`""`) against its members instead of accepting it unchecked; a missing key is still the required/`.optional()` question. `v.union([v.literal("x"), v.int()]).present()` now rejects `""`.
 - `validate()` keeps the typed output of `v.record(...)` (`Record<string, …>`); only an index signature over `any`/`unknown` (the wide `Schema`) stays `any`.
 
 ### Fixed
 
-- `v.literal("")` accepts a present `""` again (regressed in 5.25): its default (implicit) required state and `.present()` keep it, `.optional()` and `.nullable()` no longer drop it. An explicit `.required()` or `requiredIf(...)` still rejects `""`. A literal set without a blank value still reads `""` as missing (WR-008).
-- A field with an empty default (`v.string().max(n).default("")`) no longer fails "is required" when the input omits it, sends `null`, or sends a blank string (an untouched HTML input); the output is the default (WR-008).
+- `v.literal("")` accepts a present `""` again (regressed in 5.25): its default (implicit) required state and `.present()` keep it, `.optional()` and `.nullable()` no longer drop it. An explicit `.required()` or `requiredIf(...)` still rejects `""`. A literal set without a blank value still reads `""` as missing.
+- A field with an empty default (`v.string().max(n).default("")`) no longer fails "is required" when the input omits it, sends `null`, or sends a blank string (an untouched HTML input); the output is the default.
 - A `null` default no longer satisfies "required" on a field that is not `.nullable()`, and an empty default of the wrong type (`v.int().default("")`) now fails the type rule instead of being returned unchecked.
-- `v.discriminatedUnion(...).optional()` accepts an absent, `undefined` or `null` field, as every other validator does; `.default(...)` replaces `null` too and is validated through its branch. A required union reports a missing or `null` field with the `required` error; `.nullable()` keeps `null` (WR-007).
-- `schema["~standard"].validate(...)` on a discriminated union resolves to the branch output union instead of `unknown` (WR-020).
+- `v.discriminatedUnion(...).optional()` accepts an absent, `undefined` or `null` field, as every other validator does; `.default(...)` replaces `null` too and is validated through its branch. A required union reports a missing or `null` field with the `required` error; `.nullable()` keeps `null`.
+- `schema["~standard"].validate(...)` on a discriminated union resolves to the branch output union instead of `unknown`.
 
 ## 5.29.0 - 2026-10-01
 
@@ -112,6 +142,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 ### Changed
 
 - Lockstep release maintenance and dependency refresh.
+
 ## 5.20.0 - 2026-09-24
 
 ### Changed

package/README.md

@@ -181,18 +181,56 @@ const schema = v.object({
 });
 ```
 
+### Union and record output types
+
+`v.union(...)` and `v.record(...)` expose separate Standard Schema input and output
+types. `Infer.Output` and `~standard.validate()` describe validated child output:
+defaults and catches guarantee fields even when callers may omit them. A union
+returns its matching branch's validated data, including computed fields and child
+transformers, before running its own transformers and refinements.
+
+```ts
+const entry = v.object({ count: v.int().optional().default(1) });
+const union = v.union([entry, v.string()]);
+const record = v.record(entry);
+// Infer.Input<typeof union>: { count?: number } | string
+// Infer.Output<typeof union>: { count: number } | string
+// Infer.Output<typeof record>: Record<string, { count: number }>
+```
+
+**Upgrading:** union output now includes member trimming, date parsing, defaults,
+computed fields and unknown-key stripping. A member that outputs `undefined`
+causes the containing object field to be omitted. This can change stored,
+compared or serialized values. Keep any raw input you need before validation.
+
 ### ✅ Custom Validation
 
 Add your own validation logic:
 
 ```typescript
-v.string().refine(async value => {
+v.string().refine(async (value) => {
   const exists = await checkUsername(value);
   if (exists) return "Username already taken";
 });
 ```
 
-The callback's `value` is typed `any` on purpose: custom rules run before an object or array validates its children, so the value is the (mutated) input, not the schema output. Check the shape you rely on.
+The callback's `value` is typed from the validator's output. Refinements run after value rules, child validation (including defaults and computed fields), and output transformers succeed. They skip absent/null values and failed validation, even with `firstErrorOnly: false`. Multiple refinements run in declaration order and respect `firstErrorOnly`. Use `.addRule()` for checks that need the input before child validation.
+
+Refinements also run on successful empty defaults such as `.default("")`. Object
+`.merge()` appends refinements from the merged schema; `.extend()` imports only
+its fields and retains the receiver's refinements. Other clone/field-selection
+operations keep the receiver's refinements, so callbacks must tolerate any fields
+you remove from the shape.
+
+Output transformer types are not fully tracked yet: for example,
+`v.date().toISOString()` returns a string at runtime while its declared output
+remains `Date`. Use a Date input rule or convert the Date after validation when
+a refinement needs Date methods. Chaining `.refine()` before `.toISOString()`
+does not change execution order.
+
+A successful `.addRule()` callback may return `{ isValid: true, data: replacement }`
+to replace the value for later rules, transformers and refinements. Omitting `data`
+keeps the current value; including `data: undefined` explicitly clears it.
 
 ### ✅ Mutators & Transformers
 
@@ -304,19 +342,14 @@ const bookingSchema = v.object({
 ### Array Validation
 
 ```typescript
-const tagsSchema = v
-  .array(v.string())
-  .required()
-  .minLength(1)
-  .maxLength(10)
-  .unique();
+const tagsSchema = v.array(v.string()).required().minLength(1).maxLength(10).unique();
 
 const usersSchema = v
   .array(
     v.object({
       name: v.string().required(),
       email: v.string().email(),
-    })
+    }),
   )
   .minLength(1);
 ```
@@ -382,6 +415,21 @@ The documentation includes:
 
 ---
 
+## Type inference compiler budget
+
+From `packages/seal`, run `pnpm bench:types --check` to compile a deterministic
+fixture of 16 composed entities and 8 services. CI runs the same check when Seal
+is selected. It rejects compiler errors and growth above 5% in instantiations or
+types; memory and elapsed time are recorded for context. Object factories use the
+class's existing input/output generics directly, avoiding a duplicate Standard
+Schema intersection on every nested object.
+
+After reviewing a deliberate change, refresh the baseline with
+`node scripts/bench-types.mjs --update`. Keep fixture sizes and TypeScript versions
+the same when comparing counts.
+
+---
+
 ## 📄 License
 
 MIT

package/cjs/index.cjs

@@ -26,9 +26,9 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 }) : target, mod));
 
 //#endregion
-const require_required_methods = require('./required-methods-DYsRO9aZ.cjs');
-const require_object = require('./object--LXRt5RF.cjs');
-const require_string = require('./string-DsqnKoSB.cjs');
+const require_required_methods = require('./required-methods-chT0TXQS.cjs');
+const require_object = require('./object-VTtA-k1a.cjs');
+const require_string = require('./string-edcPIpcU.cjs');
 let _mongez_reinforcements = require("@mongez/reinforcements");
 let _mongez_supportive_is = require("@mongez/supportive-is");
 let dayjs = require("dayjs");
@@ -650,7 +650,7 @@ var ArrayValidator = class extends require_required_methods.BaseValidator {
 	async validate(data, context) {
 		const valueForRules = data ?? this.getDefaultValue();
 		const mutatedData = await this.mutate(valueForRules, context);
-		const result = await super.validate(data, context);
+		const result = await this.validateRules(data, context);
 		if (result.isValid === false) return result;
 		if (mutatedData === void 0 || mutatedData === null) return result;
 		if (!Array.isArray(mutatedData)) return result;
@@ -668,11 +668,11 @@ var ArrayValidator = class extends require_required_methods.BaseValidator {
 			if (childResult.isValid === false) errors.push(...childResult.errors);
 		});
 		await Promise.all(validationPromises);
-		return {
+		return this.refineResult({
 			isValid: errors.length === 0,
 			errors,
 			data: await this.startTransformationPipeline(mutatedData, context)
-		};
+		}, context);
 	}
 	/**
 	* @inheritdoc
@@ -1657,7 +1657,7 @@ var DiscriminatedUnionValidator = class DiscriminatedUnionValidator extends requ
 				data: void 0
 			};
 		}
-		return branch.validate(data, context);
+		return this.refineResult(await branch.validate(data, context), context);
 	}
 	clone() {
 		const cloned = super.clone();
@@ -2157,7 +2157,7 @@ var LazyValidator = class extends require_required_methods.BaseValidator {
 		return this.resolvedValidator;
 	}
 	async validate(data, context) {
-		return this.resolve().validate(data, context);
+		return this.refineResult(await this.resolve().validate(data, context), context);
 	}
 	matchesType(value) {
 		return this.resolve().matchesType(value);
@@ -2288,7 +2288,7 @@ var RecordValidator = class extends require_required_methods.BaseValidator {
 	async validate(data, context) {
 		const valueForRules = data ?? this.getDefaultValue();
 		const mutatedData = await this.mutate(valueForRules, context);
-		const result = await super.validate(data, context);
+		const result = await this.validateRules(data, context);
 		if (result.isValid === false) return result;
 		if (mutatedData === void 0 || mutatedData === null) return result;
 		if (!(0, _mongez_supportive_is.isPlainObject)(mutatedData)) return result;
@@ -2306,11 +2306,11 @@ var RecordValidator = class extends require_required_methods.BaseValidator {
 			if (childResult.isValid === false) errors.push(...childResult.errors);
 		});
 		await Promise.all(validationPromises);
-		return {
+		return this.refineResult({
 			isValid: errors.length === 0,
 			errors,
 			data: await this.startTransformationPipeline(mutatedData, context)
-		};
+		}, context);
 	}
 	/**
 	* @inheritdoc
@@ -2545,7 +2545,7 @@ var TupleValidator = class extends require_required_methods.BaseValidator {
 	async validate(data, context) {
 		const valueForRules = data ?? this.getDefaultValue();
 		const mutatedData = await this.mutate(valueForRules, context);
-		const result = await super.validate(data, context);
+		const result = await this.validateRules(data, context);
 		if (result.isValid === false) return result;
 		if (mutatedData === void 0 || mutatedData === null) return result;
 		if (!Array.isArray(mutatedData)) return result;
@@ -2575,11 +2575,11 @@ var TupleValidator = class extends require_required_methods.BaseValidator {
 			if (childResult.isValid === false) errors.push(...childResult.errors);
 		});
 		await Promise.all(validationPromises);
-		return {
+		return this.refineResult({
 			isValid: errors.length === 0,
 			errors,
 			data: await this.startTransformationPipeline(mutatedData, context)
-		};
+		}, context);
 	}
 	/**
 	* @inheritdoc
@@ -2628,7 +2628,9 @@ var TupleValidator = class extends require_required_methods.BaseValidator {
 *
 * Tries each validator in order until one passes. If a validator's matchesType()
 * returns false, it's skipped for optimization. First validator that both matches
-* the type and passes validation wins.
+* the type and passes validation wins; every type-matching validator is tried,
+* whatever `firstErrorOnly` says. When none passes, the closest one's errors are
+* reported (fewest mismatched literals, then fewest errors, then deepest path).
 *
 * @example
 * ```ts
@@ -2696,7 +2698,13 @@ const v = {
 	array: (validator, errorMessage) => new ArrayValidator(validator, errorMessage),
 	/** Create a record validator - object with dynamic keys and consistent value types */
 	record: (validator, errorMessage) => new RecordValidator(validator || v.any(), errorMessage),
-	/** Create a tuple validator - fixed-length array with position-specific types */
+	/**
+	* Create a tuple validator - fixed-length array with position-specific types.
+	*
+	* The `| []` in the constraint makes TypeScript infer a literal list as a tuple, so
+	* `v.tuple([v.string(), v.int()])` is typed `[string, number]` rather than
+	* `(string | number)[]`; a `BaseValidator[]` variable is still accepted.
+	*/
 	tuple: (validators, errorMessage) => new TupleValidator(validators, errorMessage),
 	/** Create a date validator */
 	date: (errorMessage) => new DateValidator(errorMessage),