@webergency-utils/typechecker 0.2.1 → 0.2.2

package/README.md

@@ -107,7 +107,7 @@ 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`.
@@ -135,10 +135,11 @@ const age: number & constraint.Minimum<18> = 5;
 ## 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).
+- [`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 already matches `T` and narrows the outer scope (no coercion; `from` is ignored).
+- [`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.
@@ -166,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`. Does **not** coerce; `from` is ignored.
+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 (`from` has no effect).
+  - `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
@@ -181,13 +182,13 @@ A type guard function checking if the input matches type `T`. Does **not** coerc
   }
   ```
 
-#### `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**:
@@ -195,13 +196,13 @@ 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`. Does **not** coerce; `from` is ignored.
+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 (`from` has no effect).
+  - `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 (or a custom error via `options.errorFactory`).
 - **Example**:
@@ -219,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
@@ -270,18 +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). |
-| `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. |
+| `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>`
 
@@ -331,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. |
 

package/dist/index.d.ts

@@ -1,28 +1,26 @@
 import { ResolveDefaults } from './runtime/tags.js';
-import type { IValidationError } from './runtime/validators.js';
+import type { IValidationError, ValidationMode, GuardOptions, AssertGuardOptions, ValidationOptions, AssertOptions } from './runtime/validators.js';
 export interface IValidation<T> {
     success: boolean;
     data?: T;
     errors?: IValidationError[];
 }
-export type ValidationMode = 'strict' | 'relaxed' | 'strip';
-export interface ValidationOptions {
-    mode?: ValidationMode;
-    from?: 'json' | 'query' | ((key: string, value: any, type: 'string' | 'number' | 'boolean' | 'bigint' | 'function' | 'symbol' | 'never' | 'Date' | 'RegExp' | 'Set' | 'Map' | 'Array' | 'Object' | 'instance' | 'null' | 'undefined' | 'tuple' | 'literal') => any);
-    wrapArrays?: boolean;
-    /** When true, write validated/coerced values onto the input. Default false: always return new containers. */
-    mutate?: boolean;
-    schema?: any;
-    errorFactory?: (errors: any[]) => Error;
-}
-/** Returns whether `input` already matches `T`. Does not coerce; `from` is ignored. */
-export declare function is<T>(_input: unknown, _options?: ValidationMode | ValidationOptions): _input is ResolveDefaults<T>;
+/** Type guard for `T`. Mutates in place; root-level coercion that replaces the value fails the guard. */
+export declare function is<T>(_input: unknown, _options?: ValidationMode | GuardOptions): _input is ResolveDefaults<T>;
 /** Validates and returns the (possibly coerced) value. Use `from` when conversion is needed. */
-export declare function assert<T>(_input: unknown, _options?: ValidationMode | ValidationOptions): ResolveDefaults<T>;
-/** Asserts `input` already matches `T`. Does not coerce; `from` is ignored. */
-export declare function assertGuard<T>(_input: unknown, _options?: ValidationMode | ValidationOptions): asserts _input is ResolveDefaults<T>;
+export declare function assert<T>(_input: unknown, _options?: ValidationMode | AssertOptions): ResolveDefaults<T>;
+/** Asserts `input` is `T`. Mutates in place; root-level coercion that replaces the value throws. */
+export declare function assertGuard<T>(_input: unknown, _options?: ValidationMode | AssertGuardOptions): asserts _input is ResolveDefaults<T>;
 export declare function validate<T>(_input: unknown, _options?: ValidationMode | ValidationOptions): IValidation<ResolveDefaults<T>>;
 export declare function jsonSchema<T>(): any;
+/** Schema type-predicate. Mutates in place; root-level coercion that replaces the value fails. */
+export declare function isSchema(_schema: any, _input: unknown, _options?: ValidationMode | GuardOptions): boolean;
+/** Validates `input` against a JSON Schema value and returns the (possibly coerced) data. */
+export declare function assertSchema<T = any>(_schema: any, _input: unknown, _options?: ValidationMode | AssertOptions): T;
+/** Schema assertion guard. Mutates in place; root-level coercion that replaces the value throws. */
+export declare function assertGuardSchema(_schema: any, _input: unknown, _options?: ValidationMode | AssertGuardOptions): void;
+/** Validates `input` against a JSON Schema value. */
+export declare function validateSchema<T = any>(_schema: any, _input: unknown, _options?: ValidationMode | ValidationOptions): IValidation<T>;
 export * from './runtime/validators.js';
 export * from './runtime/tags.js';
 export * from './runtime/casing.js';

package/dist/index.js

@@ -1,5 +1,5 @@
 const TRANSFORMER_MISSING = 'Typechecker transformer was not applied. Register { "transform": "@webergency-utils/typechecker/transformer" } in tsconfig plugins (requires ts-patch).';
-/** Returns whether `input` already matches `T`. Does not coerce; `from` is ignored. */
+/** Type guard for `T`. Mutates in place; root-level coercion that replaces the value fails the guard. */
 export function is(_input, _options) {
     throw new Error(TRANSFORMER_MISSING);
 }
@@ -7,7 +7,7 @@ export function is(_input, _options) {
 export function assert(_input, _options) {
     throw new Error(TRANSFORMER_MISSING);
 }
-/** Asserts `input` already matches `T`. Does not coerce; `from` is ignored. */
+/** Asserts `input` is `T`. Mutates in place; root-level coercion that replaces the value throws. */
 export function assertGuard(_input, _options) {
     throw new Error(TRANSFORMER_MISSING);
 }
@@ -17,6 +17,22 @@ export function validate(_input, _options) {
 export function jsonSchema() {
     throw new Error(TRANSFORMER_MISSING);
 }
+/** Schema type-predicate. Mutates in place; root-level coercion that replaces the value fails. */
+export function isSchema(_schema, _input, _options) {
+    throw new Error(TRANSFORMER_MISSING);
+}
+/** Validates `input` against a JSON Schema value and returns the (possibly coerced) data. */
+export function assertSchema(_schema, _input, _options) {
+    throw new Error(TRANSFORMER_MISSING);
+}
+/** Schema assertion guard. Mutates in place; root-level coercion that replaces the value throws. */
+export function assertGuardSchema(_schema, _input, _options) {
+    throw new Error(TRANSFORMER_MISSING);
+}
+/** Validates `input` against a JSON Schema value. */
+export function validateSchema(_schema, _input, _options) {
+    throw new Error(TRANSFORMER_MISSING);
+}
 export * from './runtime/validators.js';
 export * from './runtime/tags.js';
 export * from './runtime/casing.js';

package/dist/runtime/validators.d.ts

@@ -1,3 +1,4 @@
+/** Controls unknown object keys only — not coercion. Use `from` for conversion. */
 export type ValidationMode = 'strict' | 'relaxed' | 'strip';
 export interface IValidationError {
     path: string;
@@ -6,25 +7,54 @@ export interface IValidationError {
     /** Nested failures (e.g. per-arm errors for a failed union). */
     issues?: IValidationError[];
 }
-/** Internal expected-type labels for custom `from` callbacks. Not exported from the package. */
-type BaseType = 'string' | 'number' | 'boolean' | 'bigint' | 'function' | 'symbol' | 'never' | 'Date' | 'RegExp' | 'Set' | 'Map' | 'Array' | 'Object' | 'instance' | 'null' | 'undefined' | 'tuple' | 'literal';
-type FromOption = 'json' | 'query' | ((key: string, value: any, type: BaseType) => any);
+/** Expected runtime kind for custom `from` — a dispatch tag, not `typeof` / a TS type. */
+export type CoercionKind = 'string' | 'number' | 'boolean' | 'bigint' | 'function' | 'symbol' | 'never' | 'Date' | 'RegExp' | 'Set' | 'Map' | 'Array' | 'Object' | 'instance' | 'null' | 'undefined' | 'tuple' | 'literal';
+/** Shared context for `constraint.Custom` and custom `from` callbacks. */
+export interface PathContext {
+    /** Nearest named property; for `[n]` leaves, the closest named segment above. */
+    key: string;
+    path: string;
+    parent: any;
+    root: any;
+    /** Set when the leaf path segment is an array index. */
+    index?: number;
+}
+export type FromCoercionContext = PathContext & {
+    kind: CoercionKind;
+};
+type FromOption = 'json' | 'query' | ((val: any, ctx: FromCoercionContext) => any);
 export interface ValidationContext {
     success: boolean;
     errors: IValidationError[];
     mode: ValidationMode;
     from?: FromOption;
-    wrapArrays?: boolean;
     mutate?: boolean;
     root?: any;
 }
-export interface ValidationOptions {
+/** Options for `is` / `isSchema`. Always mutate; no `mutate` / `errorFactory`. */
+export interface GuardOptions {
+    /**
+     * Unknown-key policy for closed objects (default `'strict'`).
+     * - `'strict'` — reject properties not in the type/schema
+     * - `'relaxed'` — allow and keep unknown properties (does **not** coerce values)
+     * - `'strip'` — drop unknown properties from the result (in place when mutating)
+     *
+     * Coercion / revival is controlled only by `from`, never by `mode`.
+     */
     mode?: ValidationMode;
     from?: FromOption;
-    wrapArrays?: boolean;
-    /** When true, write validated/coerced values onto the input. Default false: always return new containers. */
+}
+/** Options for `assertGuard` / `assertGuardSchema`. */
+export interface AssertGuardOptions extends GuardOptions {
+    errorFactory?: (errors: IValidationError[]) => Error;
+}
+/** Options for `validate` / `validateSchema`. */
+export interface ValidationOptions extends GuardOptions {
+    /** `true`: always write onto the input. `false` (default): always allocate new containers. */
     mutate?: boolean;
-    schema?: any;
+}
+/** Options for `assert` / `assertSchema`. */
+export interface AssertOptions extends ValidationOptions {
     errorFactory?: (errors: IValidationError[]) => Error;
 }
 /** Query-style number coercion — shared by `from: 'query'` and `transform.ToNumber`. */
@@ -90,9 +120,9 @@ export declare class MetadataStoreClass {
     registerSchema(hash: string, schema: any): void;
     getSchema(hash: string): any;
     getOrCompileSchema(schema: any): Function;
-    is(validator: Function, value: any, options?: ValidationMode | ValidationOptions): boolean;
-    assert(validator: Function, value: any, options?: ValidationMode | ValidationOptions): any;
-    assertGuard(validator: Function, value: any, options?: ValidationMode | ValidationOptions): void;
+    is(validator: Function, value: any, options?: ValidationMode | GuardOptions): boolean;
+    assert(validator: Function, value: any, options?: ValidationMode | AssertOptions): any;
+    assertGuard(validator: Function, value: any, options?: ValidationMode | AssertGuardOptions): void;
     validate(validator: Function, value: any, options?: ValidationMode | ValidationOptions): {
         success: boolean;
         errors: IValidationError[];

package/dist/runtime/validators.js

@@ -44,28 +44,38 @@ function wantsQuery(ctx) {
 function wantsJsonRevive(ctx) {
     return ctx.from === 'json' || ctx.from === 'query';
 }
-function pathKey(path) {
-    if (!path) {
-        return '';
+function isIndexSegment(seg) {
+    return seg.startsWith('[') && seg.endsWith(']');
+}
+function pathContext(path, ctx) {
+    const pathParts = tokenizePath(path);
+    const parentPath = joinPathSegments(pathParts.slice(0, -1));
+    const parent = getValueAtPath(ctx.root, parentPath);
+    const last = pathParts[pathParts.length - 1];
+    let index;
+    if (last && isIndexSegment(last)) {
+        const parsed = parseInt(last.slice(1, -1), 10);
+        if (!Number.isNaN(parsed)) {
+            index = parsed;
+        }
     }
-    const bracket = path.lastIndexOf('[');
-    const dot = path.lastIndexOf('.');
-    if (bracket > dot) {
-        const end = path.lastIndexOf(']');
-        if (end > bracket) {
-            return path.slice(bracket + 1, end);
+    let key = '';
+    for (let i = pathParts.length - 1; i >= 0; i--) {
+        if (!isIndexSegment(pathParts[i])) {
+            key = pathParts[i];
+            break;
         }
     }
-    if (dot >= 0) {
-        return path.slice(dot + 1);
+    if (index === undefined) {
+        return { key, path, parent, root: ctx.root };
     }
-    return path;
+    return { key, path, parent, root: ctx.root, index };
 }
-function fromCustom(ctx, path, value, type) {
+function fromCustom(ctx, path, value, kind) {
     if (typeof ctx.from !== 'function') {
         return value;
     }
-    return ctx.from(pathKey(path), value, type);
+    return ctx.from(value, { ...pathContext(path, ctx), kind });
 }
 /** Query-style number coercion — shared by `from: 'query'` and `transform.ToNumber`. */
 export function coerceQueryNumber(v) {
@@ -519,7 +529,7 @@ export const validators = {
     },
     array: (v, path, ctx, childValidator) => {
         if (!Array.isArray(v)) {
-            if (ctx.wrapArrays && v !== undefined && v !== null) {
+            if (wantsQuery(ctx) && v !== undefined && v !== null) {
                 v = [v];
             }
             else if (typeof ctx.from === 'function') {
@@ -807,12 +817,7 @@ export const validators = {
         return v;
     },
     custom: (v, path, ctx, fn, message) => {
-        const pathParts = tokenizePath(path);
-        const parentPath = joinPathSegments(pathParts.slice(0, -1));
-        const parent = getValueAtPath(ctx.root, parentPath);
-        const last = pathParts[pathParts.length - 1];
-        const index = last && last.startsWith('[') ? parseInt(last.slice(1, -1), 10) : undefined;
-        if (!fn(v, { parent, root: ctx.root, path, index: Number.isNaN(index) ? undefined : index })) {
+        if (!fn(v, pathContext(path, ctx))) {
             report(ctx, path, fn.name ? `Custom<${fn.name}>` : 'Custom', v, message);
         }
         return v;
@@ -1145,20 +1150,22 @@ export class MetadataStoreClass {
     is(validator, value, options) {
         const opt = options;
         const mode = typeof opt === 'string' ? opt : (opt?.mode || 'strict');
-        // Type predicates require the value already match T — never coerce.
-        const wrapArrays = typeof opt === 'object' ? opt?.wrapArrays : undefined;
-        const mutate = typeof opt === 'object' ? opt?.mutate === true : false;
-        const ctx = { success: true, errors: [], mode, wrapArrays, mutate, root: value };
-        validator(value, '', ctx);
-        return ctx.success;
+        const from = typeof opt === 'object' ? opt?.from : undefined;
+        // Always mutate — no returned data. Root must stay the same binding (res === value).
+        const ctx = { success: true, errors: [], mode, from, mutate: true, root: value };
+        const res = validator(value, '', ctx);
+        if (!ctx.success) {
+            return false;
+        }
+        // Primitive / replaced roots cannot update the caller's binding — treat as not matching.
+        return res === value;
     }
     assert(validator, value, options) {
         const opt = options;
         const mode = typeof opt === 'string' ? opt : (opt?.mode || 'strict');
         const from = typeof opt === 'object' ? opt?.from : undefined;
-        const wrapArrays = typeof opt === 'object' ? opt?.wrapArrays : undefined;
         const mutate = typeof opt === 'object' ? opt?.mutate === true : false;
-        const ctx = { success: true, errors: [], mode, from, wrapArrays, mutate, root: value };
+        const ctx = { success: true, errors: [], mode, from, mutate, root: value };
         const res = validator(value, '', ctx);
         if (!ctx.success) {
             if (typeof opt === 'object' && opt?.errorFactory) {
@@ -1171,25 +1178,31 @@ export class MetadataStoreClass {
     assertGuard(validator, value, options) {
         const opt = options;
         const mode = typeof opt === 'string' ? opt : (opt?.mode || 'strict');
-        // Assertion predicates require the value already match T — never coerce.
-        const wrapArrays = typeof opt === 'object' ? opt?.wrapArrays : undefined;
-        const mutate = typeof opt === 'object' ? opt?.mutate === true : false;
-        const ctx = { success: true, errors: [], mode, wrapArrays, mutate, root: value };
-        validator(value, '', ctx);
-        if (!ctx.success) {
-            if (typeof opt === 'object' && opt?.errorFactory) {
-                throw opt.errorFactory(ctx.errors);
-            }
-            throw new Error('Validation Error: ' + ctx.errors.map(e => e.path ? `${e.path}: ${e.error}` : e.error).join(', '));
+        const from = typeof opt === 'object' ? opt?.from : undefined;
+        // Always mutate — no returned data. Root must stay the same binding (res === value).
+        const ctx = { success: true, errors: [], mode, from, mutate: true, root: value };
+        const res = validator(value, '', ctx);
+        if (ctx.success && res === value) {
+            return;
+        }
+        // Root was replaced (e.g. primitive coerce) — binding unchanged; report a normal type failure.
+        if (ctx.success && res !== value) {
+            ctx.success = true;
+            ctx.errors.length = 0;
+            ctx.from = undefined;
+            validator(value, '', ctx);
+        }
+        if (typeof opt === 'object' && opt?.errorFactory) {
+            throw opt.errorFactory(ctx.errors);
         }
+        throw new Error('Validation Error: ' + ctx.errors.map(e => e.path ? `${e.path}: ${e.error}` : e.error).join(', '));
     }
     validate(validator, value, options) {
         const opt = options;
         const mode = typeof opt === 'string' ? opt : (opt?.mode || 'strict');
         const from = typeof opt === 'object' ? opt?.from : undefined;
-        const wrapArrays = typeof opt === 'object' ? opt?.wrapArrays : undefined;
         const mutate = typeof opt === 'object' ? opt?.mutate === true : false;
-        const ctx = { success: true, errors: [], mode, from, wrapArrays, mutate, root: value };
+        const ctx = { success: true, errors: [], mode, from, mutate, root: value };
         const res = validator(value, '', ctx);
         return { success: ctx.success, errors: ctx.errors, data: res };
     }

package/dist/transformer.js

@@ -3,7 +3,14 @@ import { buildValidator, generateHash, buildJsonSchema, objectToAst } from './en
 export { buildValidator, generateHash, buildJsonSchema } from './engine/resolver.js';
 import { hoistRegistrations } from './engine/hoister.js';
 import { installStaticConstraintDiagnostics } from './engine/staticAsserts.js';
-const RUNTIME_FUNCTIONS = ['is', 'assert', 'assertGuard', 'validate', 'jsonSchema'];
+const TYPE_FUNCTIONS = ['is', 'assert', 'assertGuard', 'validate', 'jsonSchema'];
+const SCHEMA_FUNCTIONS = ['isSchema', 'assertSchema', 'assertGuardSchema', 'validateSchema'];
+function metadataCall(method, args) {
+    return ts.factory.createCallExpression(ts.factory.createPropertyAccessExpression(ts.factory.createIdentifier('MetadataStore'), method), undefined, args);
+}
+function argOrUndefined(args, index) {
+    return args[index] || ts.factory.createIdentifier('undefined');
+}
 export default function transformer(program) {
     const checker = program.getTypeChecker();
     installStaticConstraintDiagnostics(program);
@@ -13,14 +20,29 @@ export default function transformer(program) {
             const schemasCache = new Map();
             const requiredUtils = new Set();
             const visitor = (node) => {
-                // Skip visiting ImportDeclarations to preserve their original symbols and avoid compiler crashes
                 if (ts.isImportDeclaration(node)) {
                     return node;
                 }
-                // Handle runtime function calls (is, assert, assertGuard, validate, jsonSchema)
                 if (ts.isCallExpression(node) && ts.isIdentifier(node.expression)) {
                     const fnName = node.expression.text;
-                    if (RUNTIME_FUNCTIONS.includes(fnName)) {
+                    if (SCHEMA_FUNCTIONS.includes(fnName)) {
+                        requiredUtils.add('MetadataStore');
+                        const schemaArg = argOrUndefined(node.arguments, 0);
+                        const inputArg = argOrUndefined(node.arguments, 1);
+                        const optionsArg = argOrUndefined(node.arguments, 2);
+                        const compiled = metadataCall('getOrCompileSchema', [schemaArg]);
+                        if (fnName === 'validateSchema') {
+                            return metadataCall('validate', [compiled, inputArg, optionsArg]);
+                        }
+                        if (fnName === 'isSchema') {
+                            return metadataCall('is', [compiled, inputArg, optionsArg]);
+                        }
+                        if (fnName === 'assertSchema') {
+                            return metadataCall('assert', [compiled, inputArg, optionsArg]);
+                        }
+                        return metadataCall('assertGuard', [compiled, inputArg, optionsArg]);
+                    }
+                    if (TYPE_FUNCTIONS.includes(fnName)) {
                         const typeArg = node.typeArguments?.[0];
                         if (typeArg) {
                             const type = checker.getTypeFromTypeNode(typeArg);
@@ -32,69 +54,22 @@ export default function transformer(program) {
                                 const schemaObj = buildJsonSchema(type, checker);
                                 schemasCache.set(hash, objectToAst(schemaObj));
                             }
-                            let getCall;
-                            const arg0 = node.arguments[0] || ts.factory.createIdentifier('undefined');
-                            const arg1 = node.arguments[1] || ts.factory.createIdentifier('undefined');
-                            let hasSchema = false;
-                            let schemaExpr;
-                            if (node.arguments[1]) {
-                                const optArg = node.arguments[1];
-                                const optType = checker.getTypeAtLocation(optArg);
-                                const schemaProp = optType.getProperty('schema');
-                                if (schemaProp) {
-                                    hasSchema = true;
-                                    if (ts.isObjectLiteralExpression(optArg)) {
-                                        const prop = optArg.properties.find(p => {
-                                            if (ts.isPropertyAssignment(p) && ts.isIdentifier(p.name) && p.name.text === 'schema') {
-                                                return true;
-                                            }
-                                            if (ts.isShorthandPropertyAssignment(p) && p.name.text === 'schema') {
-                                                return true;
-                                            }
-                                            return false;
-                                        });
-                                        if (prop) {
-                                            if (ts.isPropertyAssignment(prop)) {
-                                                schemaExpr = prop.initializer;
-                                            }
-                                            else if (ts.isShorthandPropertyAssignment(prop)) {
-                                                schemaExpr = prop.name;
-                                            }
-                                        }
-                                    }
-                                    if (!schemaExpr) {
-                                        schemaExpr = ts.factory.createPropertyAccessExpression(optArg, 'schema');
-                                    }
-                                }
-                            }
-                            if (hasSchema && schemaExpr) {
-                                const compileAccess = ts.factory.createPropertyAccessExpression(ts.factory.createIdentifier('MetadataStore'), 'getOrCompileSchema');
-                                getCall = ts.factory.createCallExpression(compileAccess, undefined, [schemaExpr]);
-                            }
-                            else {
-                                const mdStoreAccess = ts.factory.createPropertyAccessExpression(ts.factory.createIdentifier('MetadataStore'), 'getValidator');
-                                getCall = ts.factory.createCallExpression(mdStoreAccess, undefined, [ts.factory.createStringLiteral(hash)]);
-                            }
+                            const inputArg = argOrUndefined(node.arguments, 0);
+                            const optionsArg = argOrUndefined(node.arguments, 1);
+                            const getValidator = metadataCall('getValidator', [ts.factory.createStringLiteral(hash)]);
                             if (fnName === 'jsonSchema') {
-                                const getSchemaAccess = ts.factory.createPropertyAccessExpression(ts.factory.createIdentifier('MetadataStore'), 'getSchema');
-                                return ts.factory.createCallExpression(getSchemaAccess, undefined, [ts.factory.createStringLiteral(hash)]);
-                            }
-                            else if (fnName === 'validate') {
-                                const mdStoreAccess = ts.factory.createPropertyAccessExpression(ts.factory.createIdentifier('MetadataStore'), 'validate');
-                                return ts.factory.createCallExpression(mdStoreAccess, undefined, [getCall, arg0, arg1]);
+                                return metadataCall('getSchema', [ts.factory.createStringLiteral(hash)]);
                             }
-                            else if (fnName === 'is') {
-                                const mdStoreAccess = ts.factory.createPropertyAccessExpression(ts.factory.createIdentifier('MetadataStore'), 'is');
-                                return ts.factory.createCallExpression(mdStoreAccess, undefined, [getCall, arg0, arg1]);
+                            if (fnName === 'validate') {
+                                return metadataCall('validate', [getValidator, inputArg, optionsArg]);
                             }
-                            else if (fnName === 'assert') {
-                                const mdStoreAccess = ts.factory.createPropertyAccessExpression(ts.factory.createIdentifier('MetadataStore'), 'assert');
-                                return ts.factory.createCallExpression(mdStoreAccess, undefined, [getCall, arg0, arg1]);
+                            if (fnName === 'is') {
+                                return metadataCall('is', [getValidator, inputArg, optionsArg]);
                             }
-                            else if (fnName === 'assertGuard') {
-                                const mdStoreAccess = ts.factory.createPropertyAccessExpression(ts.factory.createIdentifier('MetadataStore'), 'assertGuard');
-                                return ts.factory.createCallExpression(mdStoreAccess, undefined, [getCall, arg0, arg1]);
+                            if (fnName === 'assert') {
+                                return metadataCall('assert', [getValidator, inputArg, optionsArg]);
                             }
+                            return metadataCall('assertGuard', [getValidator, inputArg, optionsArg]);
                         }
                     }
                 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webergency-utils/typechecker",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "type": "module",
   "description": "TypeScript compiler plugin for runtime validation",
   "author": "radixxko",