@webergency-utils/typechecker 0.1.9 → 0.1.10

package/README.md

@@ -1,38 +1,64 @@
 # @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.
+[![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)
 
-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.
+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.
 
----
+## 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 & 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.
 
-## Installation
+### 1. Install Dependencies
 
-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.
+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
+```
 
-Update your `tsconfig.json` to include the transformer in the `compilerOptions.plugins` array:
+> [!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
+
+Register the typechecker transform plugin under the `plugins` array of `compilerOptions` in your `tsconfig.json`:
 
 ```json
 {
@@ -49,329 +75,283 @@ Update your `tsconfig.json` to include the transformer in the `compilerOptions.p
 
 ---
 
-## 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'
-}
+### Static Constraint Diagnostics
 
-// 2. assert() - returns the narrowed value or throws an error
-const validData = assert<Payload>(data);
+The package includes an IDE / Language Service plugin that statically checks literal values against type constraints during editing or compilation:
 
-// 3. assertGuard() - asserts the type for the current scope in-place
-assertGuard<Payload>(data);
-console.log(data.id); // Narrowed in-place
+```typescript
+import { constraint } from '@webergency-utils/typechecker';
 
-// 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
-}
+// 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
 
-All validation APIs accept either a string `ValidationMode` or a custom `ValidationOptions` object:
+- [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.
 
-```typescript
-export type ValidationMode = 'strict' | 'relaxed' | 'strip';
+---
 
-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
-}
-```
+## API Reference
 
-#### 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
-});
-```
+### Validation Functions
 
----
+#### `validate<T>(input: unknown, options?: ValidationMode | ValidationOptions): IValidation<ResolveDefaults<T>>`
 
-### 4. Error Reporting & Grouping
+Validates input data against type `T` and returns a structured validation result.
 
-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.
+- **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');
+  ```
 
-The error strings follow a deterministic, parser-friendly `Constraint<Value>` format.
+#### `is<T>(input: unknown, options?: ValidationMode | ValidationOptions): input is ResolveDefaults<T>`
 
-```typescript
-import { validate, groupErrorsByPath, Minimum } from '@webergency-utils/typechecker';
+A type guard function checking if the input matches type `T`.
 
-interface Payload {
-  id: string;
-  role: "admin" | "user";
-  age: number & Minimum<18>;
-  metadata: { tag: string } | { priority: number };
-}
+- **Parameters**:
+  - `input`: The value to check.
+  - `options` (optional): Either a `ValidationMode` string or a `ValidationOptions` object.
+- **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);
+  }
+  ```
 
-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
-};
+#### `assert<T>(input: unknown, options?: ValidationMode | ValidationOptions): ResolveDefaults<T>`
 
-const result = validate<Payload>(data);
-if (!result.success) {
-  const grouped = groupErrorsByPath(result.errors);
-  console.log(JSON.stringify(grouped, null, 2));
-}
-```
+Validates input data and returns it, throwing a validation error on failure.
 
-**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>"]
-  }
-}
-```
+- **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);
+  ```
+
+#### `assertGuard<T>(input: unknown, options?: ValidationMode | ValidationOptions): asserts input is ResolveDefaults<T>`
+
+An assertion guard that throws a validation error if the input does not match type `T`.
+
+- **Parameters**:
+  - `input`: The value to check.
+  - `options` (optional): Either a `ValidationMode` string or a `ValidationOptions` object.
+- **Returns**: `void`. Narrows the type of `input` in the enclosing scope on success.
+- **Throws**: `Error` if validation fails.
+- **Example**:
+  ```typescript
+  assertGuard<User>(data);
+  ```
+
+#### `jsonSchema<T>(): any`
 
-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.
+Generates a raw JSON Schema draft-07 object matching type `T` at compile time.
+
+- **Returns**: `any` (a JSON Schema object).
+- **Example**:
+  ```typescript
+  const userSchema = jsonSchema<User>();
+  ```
 
 ---
 
-### 5. Deep/External Type Validation (WithModifiers)
+### Utility Functions and Classes
 
-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.
+#### `convertPropertyCasing<T, C extends CasingFormat>(obj: T, casing: C, options?: ConvertCasingOptions): ConvertPropertyCasing<T, C>`
 
-```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;
-    }
-  }
-}
+Recursively converts all property keys of an object to the specified casing format.
 
-// Decorate specific paths using dot notation
-type ValidatedUser = WithModifiers<ExternalUser, {
-  'profile.details.email': format.Email;
-  'profile.details.password': constraint.MinLength<8>;
-}>;
-```
+- **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');
+  ```
 
-### 6. Cross-Field Dependencies (Requires)
+#### `toZodIssues(errors: IValidationError[]): any[]`
 
-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`):
+Converts internal validation errors into Zod-compatible issues.
 
-```typescript
-import { WithModifiers, constraint } from '@webergency-utils/typechecker';
-
-interface DBConfig {
-  ssl?: boolean;
-  cert?: string;
-  auth?: {
-    username?: string;
-    password?: string;
-  }
-}
+- **Parameters**:
+  - `errors`: Array of `IValidationError`.
+- **Returns**: An array of Zod-like issues.
 
-type SecureConfig = WithModifiers<DBConfig, {
-  // Absolute check: if "ssl" is defined, "cert" must exist at root
-  'ssl': constraint.Requires<'cert'>;
+#### `class ZodLikeError extends Error`
 
-  // Relative check: if "auth.password" is defined, its sibling "username" must exist
-  'auth.password': constraint.Requires<'.username'>;
-}>;
-```
+An error class wrapper that transforms internal validation errors into a Zod-like error structure.
 
-### 7. Custom Error Messages
+- **Constructor**: `constructor(errors: IValidationError[])`
+- **Properties**:
+  - `name`: `'ZodError'`
+  - `issues`: Zod-like issue array.
 
-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:
+---
 
-```typescript
-import { validate, constraint, Message } from '@webergency-utils/typechecker';
+### Interfaces and Types
 
-interface User {
-  // Direct message in constraint tag
-  age: number & constraint.Minimum<18, "Must be 18 or older">;
+#### `interface ValidationOptions`
 
-  // Fallback property message via Message<T>
-  email: string & constraint.Format<'email'> & Message<"Please supply a valid email address">;
-}
-```
+Configuration options to customize validator behavior.
 
-### 8. Zod Compatibility
+| 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. |
 
-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:
+#### `interface IValidation<T>`
 
-```typescript
-import { validate, toZodIssues, ZodLikeError } from '@webergency-utils/typechecker';
+Result object returned by `validate`.
 
-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 }]
+- `success`: `boolean`
+- `data?`: `T`
+- `errors?`: `IValidationError[]`
 
-  // 2. Or throw a Zod-like Error
-  throw new ZodLikeError(result.errors);
-}
-```
+#### `interface IValidationError`
+
+Details of a validation check failure.
+
+- `path`: `string`
+- `value`: `any`
+- `error`: `string` (the constraint description or custom message)
+
+#### `type WithModifiers<T, M>`
+
+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.
 
 ---
 
-## 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.
+### 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`: RFC-5322 email.
+- `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.ObjectId`: MongoDB 24-character hex ObjectId.
+- `format.Duration`: ISO-8601 duration.
+- `format.Time`: Time string `HH:MM:SS`.
+- `format.Byte`: Base64 string.
+- `format.Password`: Any string (always valid placeholder).
 - `format.Regex`: Valid regular expression string.
-- `format.Hostname`: Valid domain name/hostname.
+- `format.Hostname`: Valid domain name.
 - `format.URI`: Valid URI.
 
-### 3. `transform` Namespace
-Coerce or sanitize values before validation:
+#### `transform` Namespace
 
-- `transform.Trim`: Trims whitespace from both ends of a string.
+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 of a string.
+- `transform.Capitalize`: Capitalizes the first letter.
 - `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`.
-
-### 4. `tag` Namespace
-Define defaults for optional fields:
-
-- `tag.Default<Value>`: Injects the specified `Value` if the property is `undefined` at validation time.
-
-### Assignability & compile-time constants
-
-Constraint tags use **optional** phantom properties (same pattern as `tag.Default`), so plain values assign to tagged types:
+- `transform.ToDate`: Coerces inputs to Date objects.
+- `transform.Custom<Fn>`: Custom mapping function: `(val) => any`.
 
-```typescript
-const age: number & Minimum<18> = 18; // OK
-const plain: { age: number } = { age: 5 };
-const tagged: { age: number & Minimum<18> } = plain; // OK
-```
-
-When the TypeScript plugin is enabled, **compile-time constants** that violate constraints produce diagnostics:
-
-```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
-```
+#### `tag` Namespace
 
-Non-constants (`number`, variables, function results) are not checked statically — use `is` / `assert` / `validate` at runtime.
-
-#### 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">;
-}
-```
+- `tag.Default<Value>`: Injects `Value` when a property is undefined. Removes the optional modifier (`?`) when resolved with `ResolveDefaults<T>`.
 
 ---
 
-## How it Works
+## Troubleshooting
 
-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.
+### `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.
+- **Fix**:
+  1. Verify `npx ts-patch install` was executed successfully.
+  2. Verify the transformer plugin is registered in `tsconfig.json`.
+  3. Ensure your bundler or compiler CLI compiles using patched `tsc`.
 
 ---
 
-## License
+## 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.

package/dist/engine/staticAsserts.js

@@ -168,7 +168,7 @@ export function evaluateStaticConstraints(constant, constraints) {
         else if (c.type === 'multipleOf' && constant.kind === 'number') {
             const v = constant.value;
             const n = c.value;
-            let ok = true;
+            let ok;
             if (typeof v === 'bigint' || typeof n === 'bigint') {
                 ok = BigInt(v) % BigInt(n) === 0n;
             }

package/dist/plugin.d.ts

@@ -0,0 +1,7 @@
+import ts from 'typescript';
+declare function init(modules: {
+    typescript: typeof ts;
+}): {
+    create: (info: ts.server.PluginCreateInfo) => any;
+};
+export default init;

package/dist/plugin.js

@@ -0,0 +1,30 @@
+import { collectStaticConstraintDiagnostics } from './engine/staticAsserts.js';
+function init(modules) {
+    function create(info) {
+        const proxy = Object.create(null);
+        const ls = info.languageService;
+        for (const key of Object.keys(ls)) {
+            proxy[key] = ls[key];
+        }
+        proxy.getSemanticDiagnostics = (fileName) => {
+            const base = ls.getSemanticDiagnostics(fileName);
+            const program = ls.getProgram();
+            if (!program) {
+                return base;
+            }
+            const sourceFile = program.getSourceFile(fileName);
+            if (!sourceFile || sourceFile.isDeclarationFile) {
+                return base;
+            }
+            if (fileName.includes('node_modules')) {
+                return base;
+            }
+            const checker = program.getTypeChecker();
+            const extra = collectStaticConstraintDiagnostics(sourceFile, checker);
+            return [...base, ...extra];
+        };
+        return proxy;
+    }
+    return { create };
+}
+export default init;

package/dist/runtime/casing.d.ts

@@ -12,7 +12,7 @@ type SnakeToPascal<S extends string> = Capitalize<SnakeToCamel<S>>;
 type SnakeToKebab<S extends string> = S extends `${infer L}_${infer R}` ? `${L}-${SnakeToKebab<R>}` : S;
 type SnakeToDot<S extends string> = S extends `${infer L}_${infer R}` ? `${L}.${SnakeToDot<R>}` : S;
 type SnakeToUpperSnake<S extends string> = Uppercase<S>;
-type ReplaceId<S extends string> = S extends `${infer L}Id` ? `${L}ID` : S extends `id` ? `ID` : S extends `Id` ? `ID` : S;
+type ReplaceId<S extends string> = S extends `${infer L}Id` ? `${L}ID` : S extends 'id' ? 'ID' : S extends 'Id' ? 'ID' : S;
 type ToCamelCaseID<S extends string> = ReplaceId<SnakeToCamel<S>>;
 type ToPascalCaseID<S extends string> = ReplaceId<SnakeToPascal<S>>;
 type Leading<S extends string> = S extends `_${infer R}` ? `_${Leading<R>}` : S extends `-${infer R}` ? `-${Leading<R>}` : S extends `.${infer R}` ? `.${Leading<R>}` : S extends `$${infer R}` ? `$${Leading<R>}` : '';
@@ -20,9 +20,9 @@ type Trailing<S extends string> = S extends `${infer L}_` ? `${Trailing<L>}_` :
 type StripLeading<S extends string> = S extends `_${infer R}` ? StripLeading<R> : S extends `-${infer R}` ? StripLeading<R> : S extends `.${infer R}` ? StripLeading<R> : S extends `$${infer R}` ? StripLeading<R> : S;
 type StripTrailing<S extends string> = S extends `${infer L}_` ? StripTrailing<L> : S extends `${infer L}-` ? StripTrailing<L> : S extends `${infer L}.` ? StripTrailing<L> : S extends `${infer L}$` ? StripTrailing<L> : S;
 type FormatCoreCasing<S extends string, Casing extends CasingFormat> = Casing extends 'snake_case' ? Normalized<S> : Casing extends 'SNAKE_CASE' ? SnakeToUpperSnake<Normalized<S>> : Casing extends 'camelCase' ? SnakeToCamel<Normalized<S>> : Casing extends 'PascalCase' ? SnakeToPascal<Normalized<S>> : Casing extends 'kebab-case' ? SnakeToKebab<Normalized<S>> : Casing extends 'dot.case' ? SnakeToDot<Normalized<S>> : Casing extends 'camelCaseID' ? ToCamelCaseID<Normalized<S>> : Casing extends 'PascalCaseID' ? ToPascalCaseID<Normalized<S>> : S;
-export type FormatCasing<S extends string, Casing extends CasingFormat, Options extends ConvertCasingOptions = {}> = Options['preserveEnds'] extends false ? FormatCoreCasing<StripLeading<StripTrailing<S>>, Casing> : `${Leading<S>}${FormatCoreCasing<StripLeading<StripTrailing<S>>, Casing>}${Trailing<S>}`;
+export type FormatCasing<S extends string, Casing extends CasingFormat, Options extends ConvertCasingOptions = Record<never, never>> = Options['preserveEnds'] extends false ? FormatCoreCasing<StripLeading<StripTrailing<S>>, Casing> : `${Leading<S>}${FormatCoreCasing<StripLeading<StripTrailing<S>>, Casing>}${Trailing<S>}`;
 type ExtractArray<T> = T extends any[] ? T : never;
-export type ConvertPropertyCasing<T, Casing extends CasingFormat, Options extends ConvertCasingOptions = {}> = T extends [infer F, ...infer R] ? [ConvertPropertyCasing<F, Casing, Options>, ...ExtractArray<ConvertPropertyCasing<R, Casing, Options>>] : T extends (infer E)[] ? ConvertPropertyCasing<E, Casing, Options>[] : T extends string | number | boolean | symbol | bigint | null | undefined ? T : T extends Date | RegExp | Function | Map<any, any> | Set<any> | Promise<any> ? T : T extends object ? {
+export type ConvertPropertyCasing<T, Casing extends CasingFormat, Options extends ConvertCasingOptions = Record<never, never>> = T extends [infer F, ...infer R] ? [ConvertPropertyCasing<F, Casing, Options>, ...ExtractArray<ConvertPropertyCasing<R, Casing, Options>>] : T extends (infer E)[] ? ConvertPropertyCasing<E, Casing, Options>[] : T extends string | number | boolean | symbol | bigint | null | undefined ? T : T extends Date | RegExp | Function | Map<any, any> | Set<any> | Promise<any> ? T : T extends object ? {
     [K in keyof T as K extends string ? FormatCasing<K, Casing, Options> : K]: ConvertPropertyCasing<T[K], Casing, Options>;
 } : T;
 export declare function convertPropertyCasing<T, C extends CasingFormat>(obj: T, casing: C, options?: ConvertCasingOptions): ConvertPropertyCasing<T, C>;

package/dist/runtime/casing.js

@@ -2,7 +2,7 @@ function normalizeString(str) {
     if (/^[A-Z0-9_]+$/.test(str)) {
         str = str.toLowerCase();
     }
-    str = str.replace(/[-\.]/g, '_');
+    str = str.replace(/[-.]/g, '_');
     str = str.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase();
     return str.replace(/_+/g, '_').replace(/^_|_$/g, '');
 }
@@ -12,7 +12,7 @@ function formatCasing(str, casing, options = {}) {
     let trailing = '';
     let core = str;
     if (preserveEnds) {
-        const match = str.match(/^([_\-\.\$]*)(.*?)([_\-\.\$]*)$/);
+        const match = str.match(/^([_\-.$]*)(.*?)([_\-.$]*)$/);
         if (match) {
             leading = match[1];
             core = match[2];
@@ -20,10 +20,10 @@ function formatCasing(str, casing, options = {}) {
         }
     }
     else {
-        core = str.replace(/^([_\-\.\$]*)/, '').replace(/([_\-\.\$]*)$/, '');
+        core = str.replace(/^([_\-.$]*)/, '').replace(/([_\-.$]*)$/, '');
     }
     const normalized = normalizeString(core);
-    let formatted = '';
+    let formatted;
     if (casing === 'snake_case') {
         formatted = normalized;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webergency-utils/typechecker",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "type": "module",
   "description": "TypeScript compiler plugin for runtime validation",
   "author": "radixxko",
@@ -24,6 +24,12 @@
       "import": "./dist/transformer.js",
       "require": "./dist/transformer.js",
       "default": "./dist/transformer.js"
+    },
+    "./plugin": {
+      "types": "./dist/plugin.d.ts",
+      "import": "./dist/plugin.js",
+      "require": "./dist/plugin.js",
+      "default": "./dist/plugin.js"
     }
   },
   "files": [
@@ -31,11 +37,11 @@
   ],
   "scripts": {
     "lint": "eslint .",
+    "test": "vitest run",
+    "coverage": "vitest run --coverage",
     "clean": "rm -rf ./dist/* node_modules package-lock.json && npm i",
-    "commit": "node -e \"const version = require('./package.json').version.trim(); require('child_process').execSync('git add . && git commit -m \\\"Version ' + version + '\\\"');\"",
     "build": "npm run clean && tsc && node update_imports.js",
-    "test": "vitest run",
-    "test:coverage": "vitest run --coverage",
+    "commit": "node -e \"const version = require('./package.json').version.trim(); require('child_process').execSync('git add . && git commit -m \\\"Version ' + version + '\\\"');\"",
     "version": "npm run build && npm publish --access public && npm run commit && git push"
   },
   "repository": {

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 webergency-utils
-
-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.