@webergency-utils/typechecker 0.1.9 → 0.2.1

package/README.md

@@ -1,38 +1,77 @@
 # @webergency-utils/typechecker
 
-`@webergency-utils/typechecker` is a high-performance, zero-runtime-dependency TypeScript compiler plugin (transformer) that converts your static TypeScript types into optimized, hashed, and hoisted runtime validators.
+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.
 
-It is designed to work seamlessly with the `@webergency-utils/server` library, automatically enforcing strict data validation at compile time, and provides standard validation API wrappers matching `typia` with extended options for coercion and array handling.
+[![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
 
-## Features
+```typescript
+import { validate, constraint, format } from '@webergency-utils/typechecker';
 
-- **⚡ Blazing Fast**: No runtime schema parsing or generic reflection. Code is generated at compile time as highly optimized JavaScript pipelines.
-- **📦 Zero Dependency**: The generated code has absolutely zero external dependencies.
-- **🔄 Advanced Type Checking**: Full support for Unions, Intersections, Nested Objects, Tuples, and Optional Properties.
-- **🏷️ Tag-Based Validation**: Custom JSON-Schema validation tags directly inside your TypeScript types (e.g. `MinLength<8>`, `Format<'email'>`).
-- **🛡️ Multiple Validation Modes**: Easily switch between `'strict'`, `'relaxed'`, and `'strip'` modes.
-- **📈 Coercion & Coalescing**: Extended options for type conversion and single-value array wrapping (highly useful for HTTP Query parameters!).
+interface User {
+  id: string & format.UUID;
+  name: string & constraint.MinLength<2>;
+  age: number & constraint.Minimum<18>;
+}
 
----
+const input: unknown = {
+  id: '550e8400-e29b-41d4-a716-446655440000',
+  name: 'Alice',
+  age: 25,
+};
+
+// Validate input against the User type definition
+const result = validate<User>(input);
+
+if (result.success) {
+  // TypeScript narrows type to User here
+  console.log('User is valid:', result.data);
+} else {
+  console.error('Validation failed:', result.errors);
+}
+```
 
-## Installation
+## Installation & Setup
 
-Since this library is a TypeScript compiler plugin, you will need a tool like `ts-patch` or `ts-node` to hook into the compilation process.
+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
+
+Install the core package, along with `ts-patch` as a development dependency:
 
 ```bash
 npm install @webergency-utils/typechecker
-npm install -D ts-patch
+npm install --save-dev ts-patch
 ```
 
-Run `ts-patch install` to patch your local TypeScript installation.
+### 2. Inject Compiler Hook
 
----
+Run the patcher command to set up `ts-patch` inside your local TypeScript installation:
 
-## Configuration
+```bash
+npx ts-patch install
+```
+
+> [!NOTE]
+> It is recommended to add `ts-patch install` to your `package.json` `prepare` script so it runs automatically after every dependency installation.
+
+### 3. Configure tsconfig.json
 
-Update your `tsconfig.json` to include the transformer in the `compilerOptions.plugins` array:
+Register the typechecker **transformer** (and optionally the language service plugin) under `compilerOptions.plugins` in `tsconfig.json`:
 
 ```json
 {
@@ -41,337 +80,328 @@ Update your `tsconfig.json` to include the transformer in the `compilerOptions.p
     "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.
 ---
 
-## Usage
+## Architecture & Internals
 
-You can validate unknown data anywhere in your code. The transformer intercepts these calls and replaces them with direct, optimized validation functions.
+The package utilizes a custom TypeScript compiler transformer and language service plugin to deliver highly efficient type-safe runtime validations.
 
-```typescript
-import { is, assert, assertGuard, validate } from '@webergency-utils/typechecker';
+### Build-Time Compilation Flow
 
-interface Payload {
-  id: string;
-  active: boolean;
-}
+```mermaid
+graph TD
+    A[TypeScript Source Code] --> B[ts-patch / Compiler Hook]
+    B --> C[TypeScript compiler plugin / Transformer]
+    C --> D[Extract types via compiler TypeChecker]
+    D --> E[Generate optimized JS validator function]
+    E --> F[Hoisted Validator Registry & MetadataStore registration]
+    F --> G[Replace source call with MetadataStore invocation]
+    G --> H[Emit optimized JavaScript files]
+```
 
-const data: unknown = JSON.parse('{"id": "123", "active": true}');
+1. **Build-Time Transformation**: The compiler transformer intercepts calls to validation helper functions (`validate`, `is`, `assert`, `assertGuard`, `jsonSchema`) containing generic arguments.
+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`.
 
-// 1. is() - returns a boolean (type guard)
-if (is<Payload>(data)) {
-  console.log(data.id); // Narrowed to 'Payload'
-}
+### External dependencies
 
-// 2. assert() - returns the narrowed value or throws an error
-const validData = assert<Payload>(data);
+- **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.
 
-// 3. assertGuard() - asserts the type for the current scope in-place
-assertGuard<Payload>(data);
-console.log(data.id); // Narrowed in-place
+### Static Constraint Diagnostics
 
-// 4. validate() - returns a structured validation result with errors
-const result = validate<Payload>(data);
-if (result.success) {
-  console.log(result.data);
-} else {
-  console.error(result.errors); // Array of formatted errors
-}
+The package includes an IDE / Language Service plugin that statically checks literal values against type constraints during editing or compilation:
+
+```typescript
+import { constraint } from '@webergency-utils/typechecker';
+
+// This yields a compilation error directly in the IDE:
+// Type '5' is not assignable to type 'number & Minimum<18>'.
+const age: number & constraint.Minimum<18> = 5;
 ```
 
 ---
 
-### 3. Extended Options & Validation Modes
+## Glossary
+
+- [`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 that returns `true` if a value already matches `T` (no coercion; `from` is ignored).
+- [`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 already matches `T` and narrows the outer scope (no coercion; `from` is ignored).
+- [`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.).
+- [`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.
 
-All validation APIs accept either a string `ValidationMode` or a custom `ValidationOptions` object:
+---
 
-```typescript
-export type ValidationMode = 'strict' | 'relaxed' | 'strip';
+## API Reference
 
-export interface ValidationOptions {
-  mode?: ValidationMode;    // default: 'strict'
-  tryConvert?: boolean;     // Converts string numbers, booleans, and dates (ideal for query parameters)
-  wrapArrays?: boolean;     // Wraps a single value into an array if the type expects an array
-}
-```
+### Validation Functions
 
-#### Examples:
-```typescript
-// Relaxed Mode (ignores additional properties)
-const user = assert<User>(data, 'relaxed');
-
-// Strip Mode (strips out any unknown properties from returned object)
-const cleanUser = assert<User>(data, 'strip');
-
-// Query-String Coercion
-const query = assert<SearchQuery>(rawQuery, {
-  mode: 'strip',
-  tryConvert: true, // Coerces "18" -> 18, "true" -> true, etc.
-  wrapArrays: true  // Coerces "tag" -> ["tag"] if tags: string[] is expected
-});
-```
+#### `validate<T>(input: unknown, options?: ValidationMode | ValidationOptions): IValidation<ResolveDefaults<T>>`
 
----
+Validates input data against type `T` and returns a structured validation result.
 
-### 4. Error Reporting & Grouping
+- **Parameters**:
+  - `input`: The value to validate.
+  - `options` (optional): Either a `ValidationMode` string ('strict' | 'relaxed' | 'strip') or a `ValidationOptions` object.
+- **Returns**: `IValidation<ResolveDefaults<T>>` containing validation status, converted/stripped data, and error details.
+- **Example**:
+  ```typescript
+  const result = validate<User>(data, 'strip');
+  ```
 
-When validation fails using `validate<T>()`, you receive a highly structured array of errors. To make this easy to consume for humans, LLMs, and UI libraries (like React Hook Form), the library provides a `groupErrorsByPath` helper that organizes these errors by their exact JSON path.
+#### `is<T>(input: unknown, options?: ValidationMode | ValidationOptions): input is ResolveDefaults<T>`
 
-The error strings follow a deterministic, parser-friendly `Constraint<Value>` format.
+A type guard function checking if the input matches type `T`. Does **not** coerce; `from` is ignored.
 
-```typescript
-import { validate, groupErrorsByPath, Minimum } from '@webergency-utils/typechecker';
+- **Parameters**:
+  - `input`: The value to check.
+  - `options` (optional): Either a `ValidationMode` string or a `ValidationOptions` object (`from` has no effect).
+- **Returns**: `boolean` (`true` if valid, `false` otherwise). Narrows type of `input` to `ResolveDefaults<T>` on success.
+- **Example**:
+  ```typescript
+  if (is<User>(data)) {
+    console.log(data.name);
+  }
+  ```
 
-interface Payload {
-  id: string;
-  role: "admin" | "user";
-  age: number & Minimum<18>;
-  metadata: { tag: string } | { priority: number };
-}
+#### `assert<T>(input: unknown, options?: ValidationMode | ValidationOptions): ResolveDefaults<T>`
 
-const data = {
-  id: 123,           // Error: expected string, got number
-  role: "guest",     // Error: literal union mismatch
-  age: 15,           // Error: minimum constraint failed
-  metadata: { }      // Error: complex union mismatch
-};
+Validates input data and returns it, throwing a validation error on failure.
 
-const result = validate<Payload>(data);
-if (!result.success) {
-  const grouped = groupErrorsByPath(result.errors);
-  console.log(JSON.stringify(grouped, null, 2));
-}
-```
+- **Parameters**:
+  - `input`: The value to validate.
+  - `options` (optional): Either a `ValidationMode` string or a `ValidationOptions` 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**:
+  ```typescript
+  const user = assert<User>(data);
+  ```
 
-**Output:**
-```json
-{
-  "id": {
-    "value": 123,
-    "errors": ["Type<string>"]
-  },
-  "role": {
-    "value": "guest",
-    "errors": [
-      "Literal<'admin'>",
-      "Literal<'user'>"
-    ]
-  },
-  "age": {
-    "value": 15,
-    "errors": ["Minimum<18>"]
-  },
-  "metadata": {
-    "value": {},
-    "errors": ["Type<{tag:string}|{priority:number}>"]
-  },
-  "metadata.tag": {
-    "value": undefined,
-    "errors": ["Type<string>"]
-  },
-  "metadata.priority": {
-    "value": undefined,
-    "errors": ["Type<number>"]
-  }
-}
-```
+#### `assertGuard<T>(input: unknown, options?: ValidationMode | ValidationOptions): asserts input is ResolveDefaults<T>`
 
-This flattened, grouped output is incredibly powerful—it tells the developer (or an AI agent) exactly *why* a complex union or object failed down to the very specific branch and missing property constraint.
+An assertion guard that throws a validation error if the input does not match type `T`. Does **not** coerce; `from` is ignored.
 
----
+- **Parameters**:
+  - `input`: The value to check.
+  - `options` (optional): Either a `ValidationMode` string or a `ValidationOptions` object (`from` has no effect).
+- **Returns**: `void`. Narrows the type of `input` in the enclosing scope on success.
+- **Throws**: `Error` if validation fails (or a custom error via `options.errorFactory`).
+- **Example**:
+  ```typescript
+  assertGuard<User>(data);
+  ```
 
-### 5. Deep/External Type Validation (WithModifiers)
+#### `jsonSchema<T>(): any`
 
-If you have deeply nested objects or external types that you cannot edit directly, you can add validation tags to specific properties using dot-notation path references. This prevents you from having to retype the entire structure.
+Generates a raw JSON Schema draft-07 object matching type `T` at compile time.
 
-```typescript
-import { WithModifiers, constraint, format } from '@webergency-utils/typechecker';
-
-// External type we cannot edit directly
-interface ExternalUser {
-  id: string;
-  profile?: {
-    details: {
-      email: string;
-      password: string;
-    }
-  }
-}
+- **Returns**: `any` (a JSON Schema object).
+- **Example**:
+  ```typescript
+  const userSchema = jsonSchema<User>();
+  ```
 
-// Decorate specific paths using dot notation
-type ValidatedUser = WithModifiers<ExternalUser, {
-  'profile.details.email': format.Email;
-  'profile.details.password': constraint.MinLength<8>;
-}>;
-```
+---
 
-### 6. Cross-Field Dependencies (Requires)
+### Utility Functions and Classes
 
-You can specify that a property requires the presence of other properties in the same object using absolute paths or relative dot-notation paths (e.g., `.sibling`, `..grandparent.cousin`):
+#### `convertPropertyCasing<T, C extends CasingFormat>(obj: T, casing: C, options?: ConvertCasingOptions): ConvertPropertyCasing<T, C>`
 
-```typescript
-import { WithModifiers, constraint } from '@webergency-utils/typechecker';
-
-interface DBConfig {
-  ssl?: boolean;
-  cert?: string;
-  auth?: {
-    username?: string;
-    password?: string;
-  }
-}
+Recursively converts all property keys of an object to the specified casing format.
 
-type SecureConfig = WithModifiers<DBConfig, {
-  // Absolute check: if "ssl" is defined, "cert" must exist at root
-  'ssl': constraint.Requires<'cert'>;
+- **Parameters**:
+  - `obj`: The source object.
+  - `casing`: A `CasingFormat` string value (`'snake_case' | 'SNAKE_CASE' | 'camelCase' | 'camelCaseID' | 'PascalCase' | 'PascalCaseID' | 'kebab-case' | 'dot.case'`).
+  - `options` (optional): `ConvertCasingOptions` object.
+- **Returns**: The casing-converted object with updated TypeScript property keys.
+- **Example**:
+  ```typescript
+  const apiResponse = convertPropertyCasing(user, 'camelCase');
+  ```
 
-  // Relative check: if "auth.password" is defined, its sibling "username" must exist
-  'auth.password': constraint.Requires<'.username'>;
-}>;
-```
+#### `toZodIssues(errors: IValidationError[]): any[]`
 
-### 7. Custom Error Messages
+Converts internal validation errors into Zod-compatible issues. Flattens nested union `issues` into a flat list.
 
-You can specify custom error messages for constraint violations. Most constraint tags accept a custom message as an optional template argument, or you can use the `Message<Msg>` tag:
+- **Parameters**:
+  - `errors`: Array of `IValidationError`.
+- **Returns**: An array of Zod-like issues.
 
-```typescript
-import { validate, constraint, Message } from '@webergency-utils/typechecker';
+#### `groupErrorsByPath(errors: IValidationError[]): Record<string, { value: any, errors: string[] }>`
 
-interface User {
-  // Direct message in constraint tag
-  age: number & constraint.Minimum<18, "Must be 18 or older">;
+Groups validation errors by path, including nested `issues` from failed unions.
 
-  // Fallback property message via Message<T>
-  email: string & constraint.Format<'email'> & Message<"Please supply a valid email address">;
-}
-```
+- **Parameters**:
+  - `errors`: Array of `IValidationError`.
+- **Returns**: A map of path → `{ value, errors }`.
 
-### 8. Zod Compatibility
+#### `coerceQueryNumber(v: any): any` / `coerceQueryBoolean(v: any): any` / `coerceQueryDate(v: any): any` / `coerceJsonDate(v: any): any`
 
-If you are integrating with libraries that expect Zod-style validation errors (such as React Hook Form or API gateways), you can convert the validation errors using the `toZodIssues` helper or throw a `ZodLikeError` which wraps the issues:
+Shared coercion helpers used by `from: 'query'` / `from: 'json'` and by `transform.ToNumber` / `ToBoolean` / `ToDate`.
 
-```typescript
-import { validate, toZodIssues, ZodLikeError } from '@webergency-utils/typechecker';
+#### `class ZodLikeError extends Error`
 
-const result = validate<User>(data);
-if (!result.success) {
-  // 1. Convert errors array to Zod-compliant issues
-  const zodIssues = toZodIssues(result.errors);
-  console.log(zodIssues); // [{ code: "custom", path: ["age"], message: "Minimum<18>", received: 15 }]
+An error class wrapper that transforms internal validation errors into a Zod-like error structure.
 
-  // 2. Or throw a Zod-like Error
-  throw new ZodLikeError(result.errors);
-}
-```
+- **Constructor**: `constructor(errors: IValidationError[])`
+- **Properties**:
+  - `name`: `'ZodError'`
+  - `issues`: Zod-like issue array.
 
 ---
 
-## Supported Validation & Modifier Namespaces
-
-The library provides validation tags and modifiers grouped into four logical namespaces. These can be imported directly or used via their namespaces (e.g., `constraint.MinLength` vs `MinLength`).
-
-### 1. `constraint` Namespace
-Impose structural and value-based constraints on primitives:
-
-- `MinLength<N, Msg?>`: Minimum string length.
-- `MaxLength<N, Msg?>`: Maximum string length.
-- `Length<Min, Max>`: Helper combining MinLength and MaxLength.
-- `Pattern<RegExp, Msg?>`: Regular expression validation.
-- `Minimum<N, Msg?>` / `Maximum<N, Msg?>`: Inclusive numeric bounds (supports `number | bigint`).
-- `ExclusiveMinimum<N, Msg?>` / `ExclusiveMaximum<N, Msg?>`: Exclusive numeric bounds.
-- `Range<Min, Max>`: Helper combining Minimum and Maximum.
-- `MultipleOf<N, Msg?>`: Enforces that the value is a multiple of `N`.
-- `MinItems<N, Msg?>` / `MaxItems<N, Msg?>`: Array size constraints.
-- `UniqueItems<Msg?>`: Enforces that all elements in an array or Set are deeply unique.
-- `Custom<Fn, Msg?>`: Executes a custom validation function: `(val, ctx) => boolean`.
-- `Requires<Paths, Msg?>`: Enforces cross-field dependency validation.
-- `Message<Msg>`: Attaches a fallback custom error message to a property.
-
-### 2. `format` Namespace
-Pre-defined string formatting shortcuts:
-
-- `format.Email`: RFC 5322 Email.
-- `format.UUID`: UUID (v1-v5) format.
-- `format.URL`: Full URL validation (HTTP/HTTPS/FTP).
-- `format.IPv4` / `format.IPv6`: IP address validation.
-- `format.DateTime`: ISO-8601 Date Time string.
-- `format.Date`: ISO Date (YYYY-MM-DD).
-- `format.Time`: Time string (HH:MM:SS).
-- `format.Duration`: ISO-8601 duration (e.g., PT1H).
-- `format.ObjectId`: 24-character MongoDB ObjectId.
-- `format.Byte`: Base64 encoded string.
-- `format.Password`: Always valid string, placeholder for password parameters.
-- `format.Regex`: Valid regular expression string.
-- `format.Hostname`: Valid domain name/hostname.
-- `format.URI`: Valid URI.
+### Interfaces and Types
 
-### 3. `transform` Namespace
-Coerce or sanitize values before validation:
+#### `interface ValidationOptions`
 
-- `transform.Trim`: Trims whitespace from both ends of a string.
-- `transform.LowerCase`: Converts string to lowercase.
-- `transform.UpperCase`: Converts string to uppercase.
-- `transform.Capitalize`: Capitalizes the first letter of a string.
-- `transform.ToNumber`: Coerces inputs to numbers.
-- `transform.ToBoolean`: Coerces inputs to booleans.
-- `transform.ToDate`: Coerces string timestamp to a Date object.
-- `transform.Custom<Fn>`: Applies a custom mapping function `(val) => any`.
+Configuration options to customize validator behavior.
 
-### 4. `tag` Namespace
-Define defaults for optional fields:
+| Property | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `mode` | `'strict' \| 'relaxed' \| 'strip'` | `'strict'` | Validation mode strategy (strict key checking, relaxed, or key stripping). |
+| `from` | `'json' \| 'query' \| ((key, value, type) => any)` | `undefined` | Input conversion mode for `validate` / `assert`. `'json'` revives JSON-impossible types (Date, RegExp, bigint, Set, Map). `'query'` also coerces querystring shapes (string→number/boolean, timestamps→Date, etc.). A function is called only on type mismatch. Ignored by `is` / `assertGuard`. |
+| `wrapArrays` | `boolean` | `false` | Wraps non-array values into single-element arrays if an array is expected. |
+| `mutate` | `boolean` | `false` | When true, write validated/coerced values onto the input. Default false: always return new containers. |
+| `schema` | `any` | `undefined` | Custom JSON Schema instance. |
+| `errorFactory` | `(errors: IValidationError[]) => Error` | `undefined` | Custom error factory for `assert` throwing. |
 
-- `tag.Default<Value>`: Injects the specified `Value` if the property is `undefined` at validation time.
+#### `interface IValidation<T>`
 
-### Assignability & compile-time constants
+Result object returned by `validate`.
 
-Constraint tags use **optional** phantom properties (same pattern as `tag.Default`), so plain values assign to tagged types:
+- `success`: `boolean`
+- `data?`: `T`
+- `errors?`: `IValidationError[]`
 
-```typescript
-const age: number & Minimum<18> = 18; // OK
-const plain: { age: number } = { age: 5 };
-const tagged: { age: number & Minimum<18> } = plain; // OK
-```
+#### `interface IValidationError`
 
-When the TypeScript plugin is enabled, **compile-time constants** that violate constraints produce diagnostics:
+Details of a validation check failure.
 
-```typescript
-const tooYoung: number & Minimum<18> = 5;           // Error: does not satisfy Minimum<18>
-const short: string & MinLength<3> = 'ab';           // Error: does not satisfy MinLength<3>
-const empty: string[] & MinItems<1> = [];            // Error: does not satisfy MinItems<1>
-const dupes: number[] & UniqueItems = [1, 1];        // Error: does not satisfy UniqueItems
-```
+- `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)
 
-Non-constants (`number`, variables, function results) are not checked statically — use `is` / `assert` / `validate` at runtime.
+#### `type WithModifiers<T, M>`
 
-#### Example:
-```typescript
-import { MinLength, Minimum, Format, UniqueItems, tag, transform, constraint } from '@webergency-utils/typechecker';
-
-interface Profile {
-  email: string & Format<'email'> & transform.Trim & transform.LowerCase;
-  password: string & MinLength<8>;
-  age: number & Minimum<18> & constraint.Message<"Must be 18+">;
-  luckyNumbers: number[] & UniqueItems;
-  role: string & tag.Default<"user">;
-}
-```
+Applies constraint, format, or transformation tags to properties of type `T` using a path mapping `M`.
+
+- **Generics**:
+  - `T`: The baseline type to wrap.
+  - `M`: A key-value map where keys are dot-separated paths (e.g., `'profile.email'`) and values are tags.
 
 ---
 
-## How it Works
+### Tags & Modifiers
+
+#### `constraint` Namespace
+
+Used to apply value constraints to types.
+
+| Tag | Description |
+| :--- | :--- |
+| `constraint.MinLength<N, Msg?>` | Restricts string length to $\ge N$. |
+| `constraint.MaxLength<N, Msg?>` | Restricts string length to $\le N$. |
+| `constraint.Length<Min, Max>` | Shorthand for `MinLength<Min> & MaxLength<Max>`. |
+| `constraint.Pattern<Regex, Msg?>` | Validates string using regular expression `Regex`. |
+| `constraint.Minimum<N, Msg?>` | Inclusive minimum value restriction for `number | bigint`. |
+| `constraint.Maximum<N, Msg?>` | Inclusive maximum value restriction for `number | bigint`. |
+| `constraint.Range<Min, Max>` | Shorthand for `Minimum<Min> & Maximum<Max>`. |
+| `constraint.ExclusiveMinimum<N, Msg?>` | Exclusive minimum value restriction for `number | bigint`. |
+| `constraint.ExclusiveMaximum<N, Msg?>` | Exclusive maximum value restriction for `number | bigint`. |
+| `constraint.MultipleOf<N, Msg?>` | Restricts `number | bigint` to multiples of `N`. |
+| `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.Requires<Path | [Paths], Msg?>` | Enforces that other object property paths exist. |
+| `constraint.Message<Msg>` | Fallback custom error message. |
+
+#### `format` Namespace
+
+Standard formats for string primitives.
+
+- `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`: `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` 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`: 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
 
-1. **AST Analysis**: The transformer scans compile-time type signatures and generates highly nested, direct runtime checks.
-2. **Circular References**: Safely handles recursive and circular types by generating self-referencing lazy functions.
-3. **Hoisting & Deduping**: Identical type validations are hoisted to top-level constants and shared, minimizing footprint.
-4. **Clean Emitted JS**: The output compiles into vanilla JS, utilizing direct, blazing-fast validation logic.
+Sanitizes and converts input values during validation.
+
+- `transform.Trim`: Trims string whitespace.
+- `transform.LowerCase`: Converts string to lowercase.
+- `transform.UpperCase`: Converts string to uppercase.
+- `transform.Capitalize`: Capitalizes the first letter.
+- `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
+
+- `tag.Default<Value>`: Injects `Value` when a property is undefined. Removes the optional modifier (`?`) when resolved with `ResolveDefaults<T>`.
 
 ---
 
-## License
+## Troubleshooting
+
+### `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 `{ "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
+
+This package is actively maintained.
 
-MIT © radixxko / [webergency-utils](https://github.com/webergency-utils)
+Bug reports and pull requests are welcome. Security issues and critical
+regressions are prioritized. New features are considered when they align
+with the package's existing scope.