@warlock.js/seal 5.30.0 → 5.32.0

package/CHANGELOG.md

@@ -4,33 +4,71 @@ 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.32.0 - 2026-10-18
+
+### Changed
+
+- Replace the unused classic TypeScript import-organizer development dependency with `@ianvs/prettier-plugin-sort-imports`, compatible with TypeScript 7.
+- Pin the package development compiler to TypeScript 7.0.2 and use explicit Node types and source roots with supported module resolution.
+- Rebaseline the type benchmark on TS7 with `--checkers 1` so type/instantiation counts remain deterministic; resolve the compiler through its exported package manifest.
+
+## 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 +150,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

@@ -20,15 +20,15 @@ var __copyProps = (to, from, except, desc) => {
 	}
 	return to;
 };
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule || !__hasOwnProp.call(mod, "default") ? __defProp(target, "default", {
 	value: mod,
 	enumerable: true
 }) : 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-BJlnLnwa.cjs");
+const require_object = require("./object-BoVGJ68E.cjs");
+const require_string = require("./string-CM8x0u2w.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;
@@ -661,18 +661,18 @@ var ArrayValidator = class extends require_required_methods.BaseValidator {
 				parent: mutatedData,
 				value,
 				key: index.toString(),
-				path: require_required_methods.setKeyPath(context.path, index.toString())
+				path: require_object.setKeyPath(context.path, index.toString())
 			};
 			const childResult = await this.validator.validate(value, childContext);
 			mutatedData[index] = childResult.data;
 			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();
@@ -1987,15 +1987,19 @@ var NumberValidator = class extends require_string.PrimitiveValidator {
 			if (typeof betweenOpts.max === "number") schema.maximum = betweenOpts.max;
 		}
 		const gtOpts = require_required_methods.getRuleOptions(this.rules, "greaterThan");
-		if (gtOpts?.value !== void 0 && typeof gtOpts.value === "number") if (target === "draft-07") {
-			schema.minimum = gtOpts.value;
-			schema.exclusiveMinimum = true;
-		} else schema.exclusiveMinimum = gtOpts.value;
+		if (gtOpts?.value !== void 0 && typeof gtOpts.value === "number") {
+			if (target === "draft-07") {
+				schema.minimum = gtOpts.value;
+				schema.exclusiveMinimum = true;
+			} else schema.exclusiveMinimum = gtOpts.value;
+		}
 		const ltOpts = require_required_methods.getRuleOptions(this.rules, "lessThan");
-		if (ltOpts?.value !== void 0 && typeof ltOpts.value === "number") if (target === "draft-07") {
-			schema.maximum = ltOpts.value;
-			schema.exclusiveMaximum = true;
-		} else schema.exclusiveMaximum = ltOpts.value;
+		if (ltOpts?.value !== void 0 && typeof ltOpts.value === "number") {
+			if (target === "draft-07") {
+				schema.maximum = ltOpts.value;
+				schema.exclusiveMaximum = true;
+			} else schema.exclusiveMaximum = ltOpts.value;
+		}
 		const moduloOpts = require_required_methods.getRuleOptions(this.rules, "modulo");
 		if (moduloOpts?.value !== void 0 && typeof moduloOpts.value === "number") schema.multipleOf = moduloOpts.value;
 		const inOpts = require_required_methods.getRuleOptions(this.rules, "in");
@@ -2157,7 +2161,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 +2292,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;
@@ -2299,18 +2303,18 @@ var RecordValidator = class extends require_required_methods.BaseValidator {
 				parent: mutatedData,
 				value: mutatedData[key],
 				key,
-				path: require_required_methods.setKeyPath(context.path, key)
+				path: require_object.setKeyPath(context.path, key)
 			};
 			const childResult = await this.valueValidator.validate(mutatedData[key], childContext);
 			mutatedData[key] = childResult.data;
 			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 +2549,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;
@@ -2568,18 +2572,18 @@ var TupleValidator = class extends require_required_methods.BaseValidator {
 				parent: mutatedData,
 				value: mutatedData[index],
 				key: index.toString(),
-				path: require_required_methods.setKeyPath(context.path, index.toString())
+				path: require_object.setKeyPath(context.path, index.toString())
 			};
 			const childResult = await validator.validate(mutatedData[index], childContext);
 			mutatedData[index] = childResult.data;
 			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 +2632,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 +2702,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),
@@ -3073,7 +3085,7 @@ exports.rtrimMutator = require_string.rtrimMutator;
 exports.safeHtmlMutator = require_string.safeHtmlMutator;
 exports.sameAsFieldDateRule = require_required_methods.sameAsFieldDateRule;
 exports.scalarRule = require_required_methods.scalarRule;
-exports.setKeyPath = require_required_methods.setKeyPath;
+exports.setKeyPath = require_object.setKeyPath;
 exports.slugMutator = require_string.slugMutator;
 exports.snakeCaseMutator = require_string.snakeCaseMutator;
 exports.sortArrayMutator = sortArrayMutator;