@webergency-utils/typechecker 0.1.10 → 0.2.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019-2026 Webergency s.r.o.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,8 +1,17 @@
 # @webergency-utils/typechecker
 
-[![npm version](https://img.shields.io/npm/v/%40webergency-utils%2Ftypechecker)](https://www.npmjs.com/package/@webergency-utils/typechecker) [![Maintenance](https://img.shields.io/badge/maintenance-active-brightgreen.svg)](#maintenance) [![npm downloads](https://img.shields.io/npm/dm/%40webergency-utils%2Ftypechecker)](https://www.npmjs.com/package/@webergency-utils/typechecker) [![License](https://img.shields.io/npm/l/%40webergency-utils%2Ftypechecker)](https://www.npmjs.com/package/@webergency-utils/typechecker)
-
-An ahead-of-time (AOT) type validation engine and TypeScript compiler plugin that compiles TypeScript types directly into optimized runtime validation functions. It intercepts type definitions at build time to enforce value constraints, formatting, and defaults with zero runtime reflection and no third-party schema dependencies.
+An ahead-of-time (AOT) TypeScript validation engine that compiles types into optimized runtime validators via a compiler transformer—no runtime reflection and no third-party schema library.
+
+[![npm version](https://img.shields.io/npm/v/%40webergency-utils%2Ftypechecker)](https://www.npmjs.com/package/@webergency-utils/typechecker)
+[![License](https://img.shields.io/npm/l/%40webergency-utils%2Ftypechecker)](https://www.npmjs.com/package/@webergency-utils/typechecker)
+[![Maintenance](https://img.shields.io/badge/maintenance-active-brightgreen.svg)](#maintenance)
+[![dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg)](https://www.npmjs.com/package/@webergency-utils/typechecker?activeTab=dependencies)
+[![npm downloads](https://img.shields.io/npm/dm/%40webergency-utils%2Ftypechecker)](https://www.npmjs.com/package/@webergency-utils/typechecker)
+<br>
+[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/webergency-utils/typechecker/badge)](https://securityscorecards.dev/viewer/?uri=github.com/webergency-utils/typechecker)
+[![codecov](https://codecov.io/gh/webergency-utils/typechecker/branch/main/graph/badge.svg)](https://codecov.io/gh/webergency-utils/typechecker)
+[![tests](https://github.com/webergency-utils/typechecker/actions/workflows/ci.yml/badge.svg)](https://github.com/webergency-utils/typechecker/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/webergency-utils/typechecker/actions/workflows/codeql.yml/badge.svg)](https://github.com/webergency-utils/typechecker/actions/workflows/codeql.yml)
 
 ## TL;DR
 
@@ -34,7 +43,11 @@ if (result.success) {
 
 ## Installation & Setup
 
-Since this package is a TypeScript compiler plugin (transformer), you must compile your project using a compiler patcher like `ts-patch` to hook into TS compilation.
+This package is a TypeScript compiler plugin (transformer). You must compile with a compiler patcher such as `ts-patch` so the transformer can hook into `tsc`.
+
+**Peer dependency:** `typescript` `>=5.0.0` (required; provides the compiler API the transformer and language service plugin use).
+
+There are **no runtime `dependencies`**—only the peer `typescript` and your build tooling.
 
 ### 1. Install Dependencies
 
@@ -58,7 +71,7 @@ npx ts-patch install
 
 ### 3. Configure tsconfig.json
 
-Register the typechecker transform plugin under the `plugins` array of `compilerOptions` in your `tsconfig.json`:
+Register the typechecker **transformer** (and optionally the language service plugin) under `compilerOptions.plugins` in `tsconfig.json`:
 
 ```json
 {
@@ -67,12 +80,14 @@ Register the typechecker transform plugin under the `plugins` array of `compiler
     "module": "NodeNext",
     "moduleResolution": "NodeNext",
     "plugins": [
-      { "transform": "@webergency-utils/typechecker" }
+      { "transform": "@webergency-utils/typechecker/transformer" },
+      { "name": "@webergency-utils/typechecker/plugin" }
     ]
   }
 }
 ```
 
+The `transform` entry is required for AOT validation. The `name` entry enables IDE constraint diagnostics via the language service plugin.
 ---
 
 ## Architecture & Internals
@@ -92,11 +107,17 @@ graph TD
     G --> H[Emit optimized JavaScript files]
 ```
 
-1. **Build-Time Transformation**: The compiler transformer intercepts calls to validation helper functions (`validate`, `is`, `assert`, `assertGuard`, `jsonSchema`) containing generic arguments.
+1. **Build-Time Transformation**: The compiler transformer intercepts calls to validation helper functions (`validate`, `is`, `assert`, `assertGuard`, `jsonSchema`, `validateSchema`, `isSchema`, `assertSchema`, `assertGuardSchema`).
 2. **Type Extraction & Analysis**: It parses the target TS type structure, extracting intersection constraints, formats, transforms, and defaults recursively.
 3. **Hoisted Registry**: The transformer generates highly optimized, direct JavaScript validator functions for each resolved type shape, generates a unique hash, and registers them in a global `MetadataStore`.
 4. **Call Replacement**: The transformer replaces the original compile-time call expressions with direct, zero-reflection references to the runtime `MetadataStore`.
 
+### External dependencies
+
+- **Required peer:** `typescript` (`>=5.0.0`) — compiler API for the transformer and optional language service plugin.
+- **Required build tooling:** `ts-patch` (or equivalent) — patches `tsc` so `compilerOptions.plugins` `transform` entries run.
+- **Runtime dependencies:** none.
+
 ### Static Constraint Diagnostics
 
 The package includes an IDE / Language Service plugin that statically checks literal values against type constraints during editing or compilation:
@@ -113,16 +134,19 @@ const age: number & constraint.Minimum<18> = 5;
 
 ## Glossary
 
-- [validate](file:///Users/tomaskorenko/Projects/Github/webergency-utils/typechecker/src/index.ts#L22): Validates a value against a type, returning a structured result containing the validation status and a detailed list of errors.
-- [is](file:///Users/tomaskorenko/Projects/Github/webergency-utils/typechecker/src/index.ts#L19): A type guard function that returns `true` if a value is valid, narrowing its type for TypeScript.
-- [assert](file:///Users/tomaskorenko/Projects/Github/webergency-utils/typechecker/src/index.ts#L20): Validates a value and returns it, throwing a validation error on failure.
-- [assertGuard](file:///Users/tomaskorenko/Projects/Github/webergency-utils/typechecker/src/index.ts#L21): A type assertion function that throws if a value does not match the target type, narrowing the type in the outer scope.
-- [jsonSchema](file:///Users/tomaskorenko/Projects/Github/webergency-utils/typechecker/src/index.ts#L23): Generates and returns a raw JSON Schema draft-07 representation matching a TypeScript type at compile time.
-- [WithModifiers](file:///Users/tomaskorenko/Projects/Github/webergency-utils/typechecker/src/runtime/tags.ts#L79): A utility type that applies constraint, format, or transformation tags to properties of deeply nested or external types using dot-separated path mappings.
-- [ResolveDefaults](file:///Users/tomaskorenko/Projects/Github/webergency-utils/typechecker/src/runtime/tags.ts#L87): A helper type that removes the optional flag (`?`) from properties that have defined default values.
-- [convertPropertyCasing](file:///Users/tomaskorenko/Projects/Github/webergency-utils/typechecker/src/runtime/casing.ts#L190): A runtime utility to recursively change the casing of object keys.
-- [toZodIssues](file:///Users/tomaskorenko/Projects/Github/webergency-utils/typechecker/src/runtime/validators.ts#L991): Utility to transform internal typechecker validation errors into Zod-compatible issue structures.
-- [ZodLikeError](file:///Users/tomaskorenko/Projects/Github/webergency-utils/typechecker/src/runtime/validators.ts#L1017): Error class wrapping validation errors in a structure compatible with libraries expecting Zod errors.
+- [`validate`](src/index.ts): Validates a value against a type, returning a structured result containing the validation status and a detailed list of errors.
+- [`is`](src/index.ts): A type guard for `T`. Always mutates in place; `from` may coerce nested fields. Root replacement fails the guard.
+- [`assert`](src/index.ts): Validates a value and returns it, throwing a validation error on failure (supports `from` coercion).
+- [`assertGuard`](src/index.ts): Asserts a value is `T`. Always mutates in place; `from` may coerce nested fields. Root replacement throws.
+- [`jsonSchema`](src/index.ts): Generates and returns a JSON Schema representation matching a TypeScript type at compile time (draft-07 shaped, with `x-typescript-type` for Date/RegExp/Set/Map/bigint/etc.).
+- [`validateSchema`](src/index.ts) / [`isSchema`](src/index.ts) / [`assertSchema`](src/index.ts) / [`assertGuardSchema`](src/index.ts): Same entrypoints against a runtime JSON Schema value instead of a TypeScript generic.
+- [`WithModifiers`](src/runtime/tags.ts): A utility type that applies constraint, format, or transformation tags to properties of deeply nested or external types using dot-separated path mappings.
+- [`ResolveDefaults`](src/runtime/tags.ts): A helper type that removes the optional flag (`?`) from properties that have defined default values.
+- [`convertPropertyCasing`](src/runtime/casing.ts): A runtime utility to recursively change the casing of object keys.
+- [`toZodIssues`](src/runtime/validators.ts) / [`groupErrorsByPath`](src/runtime/validators.ts): Transform or group validation errors (including nested union `issues`).
+- [`ZodLikeError`](src/runtime/validators.ts): Error class wrapping validation errors in a structure compatible with libraries expecting Zod errors.
+- [`@webergency-utils/typechecker/transformer`](src/transformer.ts): Required `ts-patch` transform entry for AOT rewrite.
+- [`@webergency-utils/typechecker/plugin`](src/plugin.ts): Optional language-service plugin for IDE static constraint diagnostics.
 
 ---
 
@@ -143,13 +167,13 @@ Validates input data against type `T` and returns a structured validation result
   const result = validate<User>(data, 'strip');
   ```
 
-#### `is<T>(input: unknown, options?: ValidationMode | ValidationOptions): input is ResolveDefaults<T>`
+#### `is<T>(input: unknown, options?: ValidationMode | GuardOptions): input is ResolveDefaults<T>`
 
-A type guard function checking if the input matches type `T`.
+A type guard for type `T`. Always mutates in place (no `mutate` option). `from` may coerce nested fields onto the same object; if validation would replace the root value (e.g. primitive `"42"` → `42`), returns `false`.
 
 - **Parameters**:
   - `input`: The value to check.
-  - `options` (optional): Either a `ValidationMode` string or a `ValidationOptions` object.
+  - `options` (optional): Either a `ValidationMode` string or a `GuardOptions` object.
 - **Returns**: `boolean` (`true` if valid, `false` otherwise). Narrows type of `input` to `ResolveDefaults<T>` on success.
 - **Example**:
   ```typescript
@@ -158,13 +182,13 @@ A type guard function checking if the input matches type `T`.
   }
   ```
 
-#### `assert<T>(input: unknown, options?: ValidationMode | ValidationOptions): ResolveDefaults<T>`
+#### `assert<T>(input: unknown, options?: ValidationMode | AssertOptions): ResolveDefaults<T>`
 
 Validates input data and returns it, throwing a validation error on failure.
 
 - **Parameters**:
   - `input`: The value to validate.
-  - `options` (optional): Either a `ValidationMode` string or a `ValidationOptions` object.
+  - `options` (optional): Either a `ValidationMode` string or an `AssertOptions` object.
 - **Returns**: `ResolveDefaults<T>` (the validated value with defaults resolved).
 - **Throws**: `Error` containing a list of path and constraint failures, or a custom error via `options.errorFactory`.
 - **Example**:
@@ -172,15 +196,15 @@ Validates input data and returns it, throwing a validation error on failure.
   const user = assert<User>(data);
   ```
 
-#### `assertGuard<T>(input: unknown, options?: ValidationMode | ValidationOptions): asserts input is ResolveDefaults<T>`
+#### `assertGuard<T>(input: unknown, options?: ValidationMode | AssertGuardOptions): asserts input is ResolveDefaults<T>`
 
-An assertion guard that throws a validation error if the input does not match type `T`.
+An assertion guard for type `T`. Always mutates in place (no `mutate` option). `from` may coerce nested fields; root replacement fails with a normal type error (re-checked without `from`).
 
 - **Parameters**:
   - `input`: The value to check.
-  - `options` (optional): Either a `ValidationMode` string or a `ValidationOptions` object.
+  - `options` (optional): Either a `ValidationMode` string or an `AssertGuardOptions` object.
 - **Returns**: `void`. Narrows the type of `input` in the enclosing scope on success.
-- **Throws**: `Error` if validation fails.
+- **Throws**: `Error` if validation fails (or a custom error via `options.errorFactory`).
 - **Example**:
   ```typescript
   assertGuard<User>(data);
@@ -196,6 +220,31 @@ Generates a raw JSON Schema draft-07 object matching type `T` at compile time.
   const userSchema = jsonSchema<User>();
   ```
 
+#### `validateSchema<T = any>(schema: any, input: unknown, options?: ValidationMode | ValidationOptions): IValidation<T>`
+
+Validates `input` against a **runtime JSON Schema** value (not a TypeScript generic).
+
+- **Parameters**:
+  - `schema`: JSON Schema object.
+  - `input`: The value to validate.
+  - `options` (optional): Same as `validate`.
+- **Example**:
+  ```typescript
+  const result = validateSchema({ type: 'string', minLength: 2 }, name);
+  ```
+
+#### `isSchema(schema: any, input: unknown, options?: ValidationMode | GuardOptions): boolean`
+
+Schema type-predicate. Always mutates in place; root replacement fails the guard.
+
+#### `assertSchema<T = any>(schema: any, input: unknown, options?: ValidationMode | AssertOptions): T`
+
+Like `assert`, but against a JSON Schema value.
+
+#### `assertGuardSchema(schema: any, input: unknown, options?: ValidationMode | AssertGuardOptions): void`
+
+Like `assertGuard`, but against a JSON Schema value. Root replacement throws.
+
 ---
 
 ### Utility Functions and Classes
@@ -216,12 +265,24 @@ Recursively converts all property keys of an object to the specified casing form
 
 #### `toZodIssues(errors: IValidationError[]): any[]`
 
-Converts internal validation errors into Zod-compatible issues.
+Converts internal validation errors into Zod-compatible issues. Flattens nested union `issues` into a flat list.
 
 - **Parameters**:
   - `errors`: Array of `IValidationError`.
 - **Returns**: An array of Zod-like issues.
 
+#### `groupErrorsByPath(errors: IValidationError[]): Record<string, { value: any, errors: string[] }>`
+
+Groups validation errors by path, including nested `issues` from failed unions.
+
+- **Parameters**:
+  - `errors`: Array of `IValidationError`.
+- **Returns**: A map of path → `{ value, errors }`.
+
+#### `coerceQueryNumber(v: any): any` / `coerceQueryBoolean(v: any): any` / `coerceQueryDate(v: any): any` / `coerceJsonDate(v: any): any`
+
+Shared coercion helpers used by `from: 'query'` / `from: 'json'` and by `transform.ToNumber` / `ToBoolean` / `ToDate`.
+
 #### `class ZodLikeError extends Error`
 
 An error class wrapper that transforms internal validation errors into a Zod-like error structure.
@@ -235,17 +296,64 @@ An error class wrapper that transforms internal validation errors into a Zod-lik
 
 ### Interfaces and Types
 
+#### `type ValidationMode`
+
+Controls **unknown object keys only**. It does **not** coerce or revive values — that is exclusively `from`.
+
+| Value | Behavior |
+| :--- | :--- |
+| `'strict'` (default) | Reject properties not declared on the type/schema. |
+| `'relaxed'` | Allow unknown properties and keep them on the result. No type conversion. |
+| `'strip'` | Drop unknown properties from the result (in place when mutating). |
+
+```typescript
+// OK: extra keys kept; age stays a string unless you also set from
+validate<User>(data, 'relaxed');
+
+// Coercion is a separate axis:
+validate<User>(data, { mode: 'relaxed', from: 'query' });
+```
+
+#### `interface GuardOptions`
+
+Options for `is` / `isSchema`. Always mutate in place (no `mutate` / `errorFactory`).
+
+| Property | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `mode` | `ValidationMode` | `'strict'` | Unknown-key policy (`strict` / `relaxed` / `strip`). Not coercion — see `ValidationMode` above. |
+| `from` | `'json' \| 'query' \| ((val, ctx) => any)` | `undefined` | In-place coercion for nested fields. Custom callbacks receive `(val, PathContext & { kind: CoercionKind })`. Root replacement fails the guard. |
+
+#### `interface AssertGuardOptions`
+
+Extends `GuardOptions` for `assertGuard` / `assertGuardSchema`.
+
+| Property | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `errorFactory` | `(errors: IValidationError[]) => Error` | `undefined` | Custom error factory when the guard throws. |
+
 #### `interface ValidationOptions`
 
-Configuration options to customize validator behavior.
+Extends `GuardOptions` for `validate` / `validateSchema` (adds `mutate`; no `errorFactory`).
 
 | Property | Type | Default | Description |
 | :--- | :--- | :--- | :--- |
-| `mode` | `'strict' \| 'relaxed' \| 'strip'` | `'strict'` | Validation mode strategy (strict key checking, relaxed, or key stripping). |
-| `tryConvert` | `boolean` | `false` | Coerces compatible input primitives (e.g. numeric strings to numbers, ISO strings to Date). |
-| `wrapArrays` | `boolean` | `false` | Wraps non-array values into single-element arrays if an array is expected. |
-| `schema` | `any` | `undefined` | Custom JSON Schema instance. |
-| `errorFactory` | `(errors: IValidationError[]) => Error` | `undefined` | Custom error factory for `assert` throwing. |
+| `mode` | `ValidationMode` | `'strict'` | Unknown-key policy (`strict` / `relaxed` / `strip`). Not coercion — see `ValidationMode` above. |
+| `from` | `'json' \| 'query' \| ((val, ctx) => any)` | `undefined` | Input conversion mode. `'json'` revives JSON-impossible types. `'query'` also coerces querystring shapes. A custom function is `(val, { key, path, parent, root, index?, kind }) => any` and runs only on type mismatch. `kind` is a `CoercionKind` dispatch tag (not `typeof` / a TS type). `key` is the nearest named path segment (for `[n]` leaves, the closest named key above). |
+| `mutate` | `boolean` | `false` | `true`: always write onto the input. `false`: always allocate new containers. |
+
+#### `interface AssertOptions`
+
+Extends `ValidationOptions` for `assert` / `assertSchema`.
+
+| Property | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `errorFactory` | `(errors: IValidationError[]) => Error` | `undefined` | Custom error factory when assert throws. |
+
+#### `type CoercionKind` / `interface PathContext` / `type FromCoercionContext`
+
+- `CoercionKind`: expected runtime kind for custom `from` (`'Date' \| 'Array' \| …`) — a dispatch tag, not `typeof`.
+- `PathContext`: `{ key, path, parent, root, index? }` shared by `constraint.Custom` and custom `from`.
+- `FromCoercionContext`: `PathContext & { kind: CoercionKind }`.
 
 #### `interface IValidation<T>`
 
@@ -262,6 +370,7 @@ Details of a validation check failure.
 - `path`: `string`
 - `value`: `any`
 - `error`: `string` (the constraint description or custom message)
+- `issues?`: `IValidationError[]` — nested failures (used for unions: one summary error with per-arm details)
 
 #### `type WithModifiers<T, M>`
 
@@ -294,7 +403,7 @@ Used to apply value constraints to types.
 | `constraint.MinItems<N, Msg?>` | Restricts array length to $\ge N$. |
 | `constraint.MaxItems<N, Msg?>` | Restricts array length to $\le N$. |
 | `constraint.UniqueItems<Msg?>` | Restricts arrays to deeply unique items. |
-| `constraint.Custom<Fn, Msg?>` | Runs a custom validation function: `(val, ctx) => boolean`. |
+| `constraint.Custom<Fn, Msg?>` | Runs a custom validation function: `(val, PathContext) => boolean` (`key`, `path`, `parent`, `root`, optional `index`). |
 | `constraint.Requires<Path | [Paths], Msg?>` | Enforces that other object property paths exist. |
 | `constraint.Message<Msg>` | Fallback custom error message. |
 
@@ -302,20 +411,29 @@ Used to apply value constraints to types.
 
 Standard formats for string primitives.
 
-- `format.Email`: RFC-5322 email.
+- `format.Email`: Practical mailbox check (`local@domain`, length limits, DNS-like domain with a real TLD). Not full RFC 5322.
+- `format.IdnEmail`: Like email, but Unicode local/domain labels allowed.
 - `format.UUID`: UUID (v1-v5).
 - `format.URL`: HTTP/HTTPS/FTP URLs.
 - `format.IPv4` / `format.IPv6`: IP addresses.
-- `format.Date`: ISO date `YYYY-MM-DD`.
-- `format.DateTime`: ISO date-time.
+- `format.Date`: `YYYY-MM-DD` validated via `new Date(...)` (calendar overflow like `2024-02-31` is allowed). With `from: 'query'`, the runtime value becomes a `Date` (the TypeScript type remains `string & format.Date`).
+- `format.DateTime`: date-time validated via `new Date(...)`. With `from: 'query'`, returns a `Date`; otherwise keeps the string.
 - `format.ObjectId`: MongoDB 24-character hex ObjectId.
 - `format.Duration`: ISO-8601 duration.
-- `format.Time`: Time string `HH:MM:SS`.
+- `format.Time`: Time string `HH:MM:SS` with a required timezone (`Z` or `±HH:MM`), e.g. `19:55:00Z`.
 - `format.Byte`: Base64 string.
 - `format.Password`: Any string (always valid placeholder).
 - `format.Regex`: Valid regular expression string.
-- `format.Hostname`: Valid domain name.
-- `format.URI`: Valid URI.
+- `format.Hostname`: ASCII domain name (includes `localhost`).
+- `format.IdnHostname`: Internationalized hostname (Unicode labels).
+- `format.URI`: Absolute URI.
+- `format.UriReference`: Absolute URI or relative reference.
+- `format.IRI`: Absolute IRI (Unicode URI).
+- `format.IriReference`: Absolute IRI or relative reference.
+- `format.UriTemplate`: RFC 6570 URI template.
+- Unknown `Format<'...'>` strings fail validation at runtime.
+
+Object and record shapes require **plain objects** (`Object.prototype` or `null` prototype). Class instances, `Date`, `Map`, `Set`, typed arrays, etc. are rejected unless the type is a dedicated instance type (`Date`, `Map`, …).
 
 #### `transform` Namespace
 
@@ -325,9 +443,9 @@ Sanitizes and converts input values during validation.
 - `transform.LowerCase`: Converts string to lowercase.
 - `transform.UpperCase`: Converts string to uppercase.
 - `transform.Capitalize`: Capitalizes the first letter.
-- `transform.ToNumber`: Coerces inputs to numbers.
-- `transform.ToBoolean`: Coerces inputs to booleans.
-- `transform.ToDate`: Coerces inputs to Date objects.
+- `transform.ToNumber`: Same coercion as `from: 'query'` for numbers (non-empty numeric strings → `parseFloat`).
+- `transform.ToBoolean`: Same coercion as `from: 'query'` for booleans (`true`/`false`/`1`/`0`/`yes`/`no`/`on`/`off`); unknown values are left unchanged and fail the boolean check.
+- `transform.ToDate`: Same coercion as `from: 'query'` for dates (parseable strings and finite timestamps).
 - `transform.Custom<Fn>`: Custom mapping function: `(val) => any`.
 
 #### `tag` Namespace
@@ -338,14 +456,18 @@ Sanitizes and converts input values during validation.
 
 ## Troubleshooting
 
-### `validate`, `is`, or `assert` calls return empty results or throw at runtime
-- **Cause**: The compiler transformer did not execute during build.
-- **Diagnostics Check**: Inspect your built `.js` code. If the output still contains `validate<User>(data)` or other generic validation calls as functions, compilation was bypassed.
+### `validate`, `is`, or `assert` throw “transformer was not applied”
+- **Cause**: The compiler transformer did not rewrite the call at build time. Untransformed stubs always throw.
+- **Diagnostics Check**: Inspect your built `.js` output. If it still contains `validate(...)` / `is(...)` / `assert(...)` as package imports rather than `MetadataStore.validate(...)` (etc.), the transformer did not run.
 - **Fix**:
   1. Verify `npx ts-patch install` was executed successfully.
-  2. Verify the transformer plugin is registered in `tsconfig.json`.
+  2. Verify `{ "transform": "@webergency-utils/typechecker/transformer" }` is registered in `tsconfig.json` `compilerOptions.plugins`.
   3. Ensure your bundler or compiler CLI compiles using patched `tsc`.
 
+### IDE does not report constraint errors on literals
+- **Cause**: The optional language service plugin is not loaded.
+- **Fix**: Add `{ "name": "@webergency-utils/typechecker/plugin" }` alongside the transformer entry in `tsconfig.json` plugins, and restart the TypeScript language service in your editor.
+
 ---
 
 ## Maintenance

package/dist/engine/generators.d.ts

@@ -11,7 +11,7 @@ export declare function createLiteralCheck(value: string | number | boolean | ts
 export declare function createArrayCheck(elementValidator: ts.Expression, requiredUtils: Set<string>): ts.Expression;
 export declare function createTemplateLiteralCheck(regexStr: string, expected: string, requiredUtils: Set<string>): ts.Expression;
 export declare function createUnionCheck(checks: ts.Expression[], requiredUtils: Set<string>, expected?: string): ts.Expression;
-export declare function createObjectCheck(props: any[], requiredUtils: Set<string>, expected?: string): ts.Expression;
+export declare function createObjectCheck(props: any[], requiredUtils: Set<string>, expected?: string, indexValidator?: ts.Expression): ts.Expression;
 export declare function createRecordCheck(valueValidator: ts.Expression, requiredUtils: Set<string>): ts.Expression;
 export declare function createTupleCheck(checks: ts.Expression[], requiredUtils: Set<string>): ts.Expression;
 export declare function createDateCheck(requiredUtils: Set<string>): ts.Expression;
@@ -21,3 +21,4 @@ export declare function createUndefinedCheck(requiredUtils: Set<string>): ts.Exp
 export declare function createIntersectionCheck(checks: ts.Expression[], requiredUtils: Set<string>): ts.Expression;
 export declare function createSetCheck(elementValidator: ts.Expression, requiredUtils: Set<string>): ts.Expression;
 export declare function createMapCheck(keyValidator: ts.Expression, valueValidator: ts.Expression, requiredUtils: Set<string>): ts.Expression;
+export declare function createInstanceOfCheck(typeName: string, requiredUtils: Set<string>): ts.Expression;

package/dist/engine/generators.js

@@ -79,7 +79,7 @@ export function createConstrainedPrimitiveCheck(baseType, constraints, requiredU
             return `validators.pattern(v, path, ctx, new RegExp(${JSON.stringify(c.value)}), ${JSON.stringify('Pattern<' + c.value + '>')}${msgArg})`;
         }
         if (c.type === 'format') {
-            return `validators.format(v, path, ctx, ${JSON.stringify(c.value)}${msgArg})`;
+            return `v = validators.format(v, path, ctx, ${JSON.stringify(c.value)}${msgArg})`;
         }
         if (c.type === 'minItems') {
             return `validators.minItems(v, path, ctx, ${valStr}${msgArg})`;
@@ -118,13 +118,13 @@ export function createConstrainedPrimitiveCheck(baseType, constraints, requiredU
                 return 'if (typeof v === \'string\' && v.length > 0) v = v.charAt(0).toUpperCase() + v.slice(1)';
             }
             if (tc.type === 'transform' && tc.value === 'tonumber') {
-                return 'v = Number(v)';
+                return 'v = validators.coerceQueryNumber(v)';
             }
             if (tc.type === 'transform' && tc.value === 'toboolean') {
-                return 'v = (v === \'true\' || v === \'1\' || v === true || v === 1)';
+                return 'v = validators.coerceQueryBoolean(v)';
             }
             if (tc.type === 'transform' && tc.value === 'todate') {
-                return 'v = new Date(v)';
+                return 'v = validators.coerceQueryDate(v)';
             }
             if (tc.type === 'transform_custom') {
                 return `v = ${tc.value}(v)`;
@@ -188,19 +188,39 @@ export function createUnionCheck(checks, requiredUtils, expected = 'Type<Union>'
         ts.factory.createStringLiteral(expected)
     ]));
 }
-export function createObjectCheck(props, requiredUtils, expected = 'object') {
+export function createObjectCheck(props, requiredUtils, expected = 'object', indexValidator) {
     requiredUtils.add('validators');
-    const propDefinitions = props.map((p, i) => ts.factory.createArrayLiteralExpression([
+    const propDefinitions = props.map((p) => ts.factory.createArrayLiteralExpression([
         ts.factory.createStringLiteral(p.name),
         p.isOptional ? ts.factory.createTrue() : ts.factory.createFalse(),
         p.validator
     ]));
     const allowedKeys = props.map(p => ts.factory.createStringLiteral(p.name));
+    if (indexValidator) {
+        const tpl = `
+        (v, path, ctx) => {
+            const obj = validators.object(v, path, ctx, undefined, __EXPECTED__);
+            if (obj === false) return v;
+            const data = validators.objectShell(obj, ctx);
+            validators.props(obj, data, path, ctx, __PROPS__);
+            validators.additionalProps(obj, data, path, ctx, __KEYS__, __INDEX__);
+            return data;
+        }
+        `;
+        return injectNodes(templateToAst(tpl), {
+            '__KEYS__': ts.factory.createArrayLiteralExpression(allowedKeys),
+            '__EXPECTED__': ts.factory.createStringLiteral(expected),
+            '__PROPS__': ts.factory.createArrayLiteralExpression(propDefinitions, true),
+            '__INDEX__': indexValidator
+        });
+    }
     const tpl = `
     (v, path, ctx) => {
-        if (!validators.object(v, path, ctx, __KEYS__, __EXPECTED__)) return v;
-        const data = ctx.mode === 'strip' ? {} : v;
-        validators.props(v, data, path, ctx, __PROPS__);
+        const obj = validators.object(v, path, ctx, __KEYS__, __EXPECTED__);
+        if (obj === false) return v;
+        const data = validators.objectShell(obj, ctx);
+        validators.props(obj, data, path, ctx, __PROPS__);
+        validators.stripExtras(data, ctx, __KEYS__);
         return data;
     }
     `;
@@ -243,10 +263,11 @@ export function createIntersectionCheck(checks, requiredUtils) {
     const tpl = `
     (v, path, ctx) => {
         const checks = __CHECKS__;
-        let data = ctx.mode === "strip" ? (typeof v === "object" && v !== null && !Array.isArray(v) ? {} : v) : v;
+        let data = validators.objectShell(v, ctx);
         for (let i = 0; i < checks.length; i++) {
             const val = checks[i](v, path, ctx);
-            if (ctx.mode === "strip" && typeof val === "object" && val !== null) Object.assign(data, val);
+            if (typeof val === "object" && val !== null && !Array.isArray(val) && typeof data === "object" && data !== null && !Array.isArray(data)) Object.assign(data, val);
+            else data = val;
         }
         return data;
     }
@@ -265,3 +286,8 @@ export function createMapCheck(keyValidator, valueValidator, requiredUtils) {
     const tpl = '(v, path, ctx) => validators.map(v, path, ctx, __KEY__, __VALUE__)';
     return injectNodes(templateToAst(tpl), { '__KEY__': keyValidator, '__VALUE__': valueValidator });
 }
+export function createInstanceOfCheck(typeName, requiredUtils) {
+    requiredUtils.add('validators');
+    const tpl = `(v, path, ctx) => validators.instanceOf(v, path, ctx, ${JSON.stringify(typeName)})`;
+    return templateToAst(tpl);
+}