@webergency-utils/typechecker 0.2.1 → 0.2.3

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,35 @@ 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).
+
+Only the documented schema subset is compiled. Recognized validation keywords that are not implemented
+(for example `enum`, `oneOf`, and `not`) throw during schema compilation instead of silently accepting data.
+Schema `pattern` values are rejected when they exceed the safety limit or contain common catastrophic-backtracking constructs.
+
+- **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
@@ -226,6 +256,8 @@ Generates a raw JSON Schema draft-07 object matching type `T` at compile time.
 #### `convertPropertyCasing<T, C extends CasingFormat>(obj: T, casing: C, options?: ConvertCasingOptions): ConvertPropertyCasing<T, C>`
 
 Recursively converts all property keys of an object to the specified casing format.
+If two source keys normalize to the same output key, conversion throws instead of silently discarding a value.
+Special keys such as `__proto__` are preserved as own data properties without changing the result prototype.
 
 - **Parameters**:
   - `obj`: The source object.
@@ -270,25 +302,71 @@ 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` | `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`: write in place while validating (half-changed input on failure is allowed; union arms still use a side tree). `false`: always allocate new containers. |
+
+#### `interface AssertOptions`
+
+Extends `ValidationOptions` for `assert` / `assertSchema`.
 
 | 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. |
+| `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>`
 
 Result object returned by `validate`.
 
 - `success`: `boolean`
-- `data?`: `T`
+- `data?`: `T` — present only when `success` is `true`
 - `errors?`: `IValidationError[]`
 
 #### `interface IValidationError`
@@ -331,7 +409,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. |
 
@@ -371,7 +449,7 @@ Sanitizes and converts input values during validation.
 - `transform.LowerCase`: Converts string to lowercase.
 - `transform.UpperCase`: Converts string to uppercase.
 - `transform.Capitalize`: Capitalizes the first letter.
-- `transform.ToNumber`: Same coercion as `from: 'query'` for numbers (non-empty numeric strings → `parseFloat`).
+- `transform.ToNumber`: Same coercion as `from: 'query'` for numbers. The entire trimmed string must be a finite decimal/scientific number; partial strings, hexadecimal syntax, `NaN`, and infinities are rejected.
 - `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`.

package/dist/engine/generators.js

@@ -76,7 +76,7 @@ export function createConstrainedPrimitiveCheck(baseType, constraints, requiredU
             return `validators.multipleOf(v, path, ctx, ${valStr}${msgArg})`;
         }
         if (c.type === 'pattern') {
-            return `validators.pattern(v, path, ctx, new RegExp(${JSON.stringify(c.value)}), ${JSON.stringify('Pattern<' + c.value + '>')}${msgArg})`;
+            return `validators.pattern(v, path, ctx, validators.safeRegExp(${JSON.stringify(c.value)}), ${JSON.stringify('Pattern<' + c.value + '>')}${msgArg})`;
         }
         if (c.type === 'format') {
             return `v = validators.format(v, path, ctx, ${JSON.stringify(c.value)}${msgArg})`;
@@ -171,7 +171,7 @@ export function createArrayCheck(elementValidator, requiredUtils) {
 }
 export function createTemplateLiteralCheck(regexStr, expected, requiredUtils) {
     requiredUtils.add('validators');
-    const tpl = `(v, path, ctx) => validators.templateLiteral(v, path, ctx, new RegExp(${JSON.stringify(regexStr)}), ${JSON.stringify(expected)})`;
+    const tpl = `(v, path, ctx) => validators.templateLiteral(v, path, ctx, validators.safeRegExp(${JSON.stringify(regexStr)}), ${JSON.stringify(expected)})`;
     return stripPositions(templateToAst(tpl));
 }
 export function createUnionCheck(checks, requiredUtils, expected = 'Type<Union>') {
@@ -196,6 +196,7 @@ export function createObjectCheck(props, requiredUtils, expected = 'object', ind
         p.validator
     ]));
     const allowedKeys = props.map(p => ts.factory.createStringLiteral(p.name));
+    const allowedKeySet = ts.factory.createNewExpression(ts.factory.createIdentifier('Set'), undefined, [ts.factory.createArrayLiteralExpression(allowedKeys)]);
     if (indexValidator) {
         const tpl = `
         (v, path, ctx) => {
@@ -208,7 +209,7 @@ export function createObjectCheck(props, requiredUtils, expected = 'object', ind
         }
         `;
         return injectNodes(templateToAst(tpl), {
-            '__KEYS__': ts.factory.createArrayLiteralExpression(allowedKeys),
+            '__KEYS__': allowedKeySet,
             '__EXPECTED__': ts.factory.createStringLiteral(expected),
             '__PROPS__': ts.factory.createArrayLiteralExpression(propDefinitions, true),
             '__INDEX__': indexValidator
@@ -225,7 +226,7 @@ export function createObjectCheck(props, requiredUtils, expected = 'object', ind
     }
     `;
     return injectNodes(templateToAst(tpl), {
-        '__KEYS__': ts.factory.createArrayLiteralExpression(allowedKeys),
+        '__KEYS__': allowedKeySet,
         '__EXPECTED__': ts.factory.createStringLiteral(expected),
         '__PROPS__': ts.factory.createArrayLiteralExpression(propDefinitions, true)
     });
@@ -266,7 +267,7 @@ export function createIntersectionCheck(checks, requiredUtils) {
         let data = validators.objectShell(v, ctx);
         for (let i = 0; i < checks.length; i++) {
             const val = checks[i](v, path, ctx);
-            if (typeof val === "object" && val !== null && !Array.isArray(val) && typeof data === "object" && data !== null && !Array.isArray(data)) Object.assign(data, val);
+            if (typeof val === "object" && val !== null && !Array.isArray(val) && typeof data === "object" && data !== null && !Array.isArray(data)) validators.assign(data, val);
             else data = val;
         }
         return data;

package/dist/engine/hoister.js

@@ -1,39 +1,43 @@
 import ts from '../ts.js';
 export function hoistRegistrations(sourceFile, cache, requiredUtils, schemasMap) {
-    if (cache.size === 0 && requiredUtils.size === 0) {
+    const hasSchemas = !!(schemasMap && schemasMap.size > 0);
+    if (cache.size === 0 && requiredUtils.size === 0 && !hasSchemas) {
         return sourceFile;
     }
+    const declaredNames = collectDeclaredNames(sourceFile.statements);
     const utilityStatements = [
         // 1. import "@webergency-utils/typechecker/runtime";
         ts.factory.createImportDeclaration(undefined, undefined, ts.factory.createStringLiteral('@webergency-utils/typechecker/runtime'), undefined)
     ];
-    if (!hasVariableDeclaration(sourceFile.statements, 'validators') &&
-        !hasVariableDeclaration(utilityStatements, 'validators')) {
+    const utilityNames = new Set();
+    if (!declaredNames.has('validators') && !utilityNames.has('validators')) {
+        utilityNames.add('validators');
         utilityStatements.push(ts.factory.createVariableStatement(undefined, ts.factory.createVariableDeclarationList([
             ts.factory.createVariableDeclaration(ts.factory.createIdentifier('validators'), undefined, undefined, ts.factory.createPropertyAccessExpression(ts.factory.createIdentifier('globalThis'), '__WEBERGENCY_TYPECHECKER_VALIDATORS__'))
         ], ts.NodeFlags.Const)));
     }
-    if (!hasVariableDeclaration(sourceFile.statements, 'MetadataStore') &&
-        !hasVariableDeclaration(utilityStatements, 'MetadataStore')) {
+    if (!declaredNames.has('MetadataStore') && !utilityNames.has('MetadataStore')) {
+        utilityNames.add('MetadataStore');
         utilityStatements.push(ts.factory.createVariableStatement(undefined, ts.factory.createVariableDeclarationList([
             ts.factory.createVariableDeclaration(ts.factory.createIdentifier('MetadataStore'), undefined, undefined, ts.factory.createPropertyAccessExpression(ts.factory.createIdentifier('globalThis'), '__WEBERGENCY_TYPECHECKER_METADATA_STORE__'))
         ], ts.NodeFlags.Const)));
     }
     const variablePrepends = [];
     const registrationAppends = [];
+    const prependedNames = new Set(utilityNames);
     for (const [hash, expr] of cache.entries()) {
+        const valName = `__val_${hash}`;
         // const __val_hash = expr;
-        if (!hasVariableDeclaration(sourceFile.statements, `__val_${hash}`) &&
-            !hasVariableDeclaration(utilityStatements, `__val_${hash}`) &&
-            !hasVariableDeclaration(variablePrepends, `__val_${hash}`)) {
+        if (!declaredNames.has(valName) && !prependedNames.has(valName)) {
+            prependedNames.add(valName);
             variablePrepends.push(ts.factory.createVariableStatement(undefined, ts.factory.createVariableDeclarationList([
-                ts.factory.createVariableDeclaration(ts.factory.createIdentifier(`__val_${hash}`), undefined, undefined, expr)
+                ts.factory.createVariableDeclaration(ts.factory.createIdentifier(valName), undefined, undefined, expr)
             ], ts.NodeFlags.Const)));
         }
         // MetadataStore.registerValidator(hash, __val_hash);
         registrationAppends.push(ts.factory.createExpressionStatement(ts.factory.createCallExpression(ts.factory.createPropertyAccessExpression(ts.factory.createIdentifier('MetadataStore'), 'registerValidator'), undefined, [
             ts.factory.createStringLiteral(hash),
-            ts.factory.createIdentifier(`__val_${hash}`)
+            ts.factory.createIdentifier(valName)
         ])));
     }
     if (schemasMap) {
@@ -92,15 +96,17 @@ function findInsertionIndex(statements) {
     }
     return statements.length;
 }
-function hasVariableDeclaration(statements, name) {
+function collectDeclaredNames(statements) {
+    const names = new Set();
     for (const statement of statements) {
-        if (ts.isVariableStatement(statement)) {
-            for (const decl of statement.declarationList.declarations) {
-                if (ts.isIdentifier(decl.name) && decl.name.text === name) {
-                    return true;
-                }
+        if (!ts.isVariableStatement(statement)) {
+            continue;
+        }
+        for (const decl of statement.declarationList.declarations) {
+            if (ts.isIdentifier(decl.name)) {
+                names.add(decl.name.text);
             }
         }
     }
-    return false;
+    return names;
 }

package/dist/engine/resolver.d.ts

@@ -1,5 +1,5 @@
 import ts from '../ts.js';
-export declare function buildValidator(type: ts.Type, checker: ts.TypeChecker, validatorsMap: Map<string, ts.Expression>, requiredUtils: Set<string>): ts.Expression;
+export declare function buildValidator(type: ts.Type, checker: ts.TypeChecker, validatorsMap: Map<string, ts.Expression>, requiredUtils: Set<string>, hash?: string): ts.Expression;
 export declare function generateHash(type: ts.Type, checker: ts.TypeChecker): string;
 export declare function objectToAst(val: any): ts.Expression;
 export declare function getTypeComplexity(type: ts.Type, checker: ts.TypeChecker, visited: Set<number>): number;

package/dist/engine/resolver.js

@@ -129,13 +129,13 @@ function tryMergeObjectIntersection(types, checker, validatorsMap, requiredUtils
     }
     return createObjectCheck([...propMap.values()], requiredUtils, expected, indexValidator);
 }
-export function buildValidator(type, checker, validatorsMap, requiredUtils) {
-    const hash = generateHash(type, checker);
-    if (validatorsMap.has(hash)) {
-        return ts.factory.createIdentifier(`__val_${hash}`);
+export function buildValidator(type, checker, validatorsMap, requiredUtils, hash) {
+    const resolvedHash = hash ?? generateHash(type, checker);
+    if (validatorsMap.has(resolvedHash)) {
+        return ts.factory.createIdentifier(`__val_${resolvedHash}`);
     }
     // Set placeholder to handle circularity
-    validatorsMap.set(hash, ts.factory.createIdentifier(`PENDING_${hash}`));
+    validatorsMap.set(resolvedHash, ts.factory.createIdentifier(`PENDING_${resolvedHash}`));
     let result;
     const flags = type.getFlags();
     const isUnion = (((flags & ts.TypeFlags.Union) !== 0 || type.isUnion()) && type.types) ? true : false;
@@ -537,9 +537,9 @@ export function buildValidator(type, checker, validatorsMap, requiredUtils) {
             result = createPrimitiveCheck('any', requiredUtils);
         }
     }
-    validatorsMap.delete(hash);
-    validatorsMap.set(hash, result);
-    return ts.factory.createIdentifier(`__val_${hash}`);
+    validatorsMap.delete(resolvedHash);
+    validatorsMap.set(resolvedHash, result);
+    return ts.factory.createIdentifier(`__val_${resolvedHash}`);
 }
 function buildStructuralSignature(type, checker, visited = new Set()) {
     const flags = type.getFlags();
@@ -674,9 +674,16 @@ function buildStructuralSignature(type, checker, visited = new Set()) {
     }
     return 'any';
 }
+const hashByType = new WeakMap();
 export function generateHash(type, checker) {
+    const cached = hashByType.get(type);
+    if (cached) {
+        return cached;
+    }
     const structuralSig = buildStructuralSignature(type, checker);
-    return createHash('sha256').update(structuralSig).digest('hex').substring(0, 16);
+    const hash = createHash('sha256').update(structuralSig).digest('hex').substring(0, 16);
+    hashByType.set(type, hash);
+    return hash;
 }
 export function objectToAst(val) {
     if (val === null) {

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/casing.js

@@ -70,9 +70,26 @@ export function convertPropertyCasing(obj, casing, options) {
         return obj.map((item) => convertPropertyCasing(item, casing, options));
     }
     const result = {};
+    const sourceKeys = new Map();
     for (const [key, value] of Object.entries(obj)) {
         const newKey = formatCasing(key, casing, options);
-        result[newKey] = convertPropertyCasing(value, casing, options);
+        const previousKey = sourceKeys.get(newKey);
+        if (previousKey !== undefined) {
+            throw new Error(`Casing conversion collision: ${previousKey} and ${key} both map to ${newKey}`);
+        }
+        sourceKeys.set(newKey, key);
+        const nested = convertPropertyCasing(value, casing, options);
+        if (newKey !== '__proto__' && newKey !== 'constructor' && newKey !== 'prototype') {
+            result[newKey] = nested;
+        }
+        else {
+            Object.defineProperty(result, newKey, {
+                value: nested,
+                enumerable: true,
+                configurable: true,
+                writable: true
+            });
+        }
     }
     return result;
 }

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,27 +7,57 @@ 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`: write in place while validating. `false` (default): allocate new containers. */
     mutate?: boolean;
-    schema?: any;
+}
+/** Options for `assert` / `assertSchema`. */
+export interface AssertOptions extends ValidationOptions {
     errorFactory?: (errors: IValidationError[]) => Error;
 }
+declare function createSafeRegex(source: string, flags?: string): RegExp;
 /** Query-style number coercion — shared by `from: 'query'` and `transform.ToNumber`. */
 export declare function coerceQueryNumber(v: any): any;
 /** Query-style boolean coercion — shared by `from: 'query'` and `transform.ToBoolean`. */
@@ -40,6 +71,8 @@ export declare const validators: {
     coerceQueryBoolean: typeof coerceQueryBoolean;
     coerceQueryDate: typeof coerceQueryDate;
     coerceJsonDate: typeof coerceJsonDate;
+    safeRegExp: typeof createSafeRegex;
+    assign: (target: any, source: any) => any;
     string: (v: any, path: string, ctx: ValidationContext) => any;
     number: (v: any, path: string, ctx: ValidationContext) => any;
     bigint: (v: any, path: string, ctx: ValidationContext) => any;
@@ -53,9 +86,9 @@ export declare const validators: {
     array: (v: any, path: string, ctx: ValidationContext, childValidator: Function) => any;
     props: (v: any, data: any, path: string, ctx: ValidationContext, props: [string, boolean, Function][]) => void;
     objectShell: (v: any, ctx: ValidationContext) => any;
-    stripExtras: (data: any, ctx: ValidationContext, allowedKeys?: string[]) => any;
-    additionalProps: (v: any, data: any, path: string, ctx: ValidationContext, knownKeys: string[], childValidator: Function) => void;
-    object: (v: any, path: string, ctx: ValidationContext, allowedKeys?: string[], expected?: string) => any;
+    stripExtras: (data: any, ctx: ValidationContext, allowedKeys?: string[] | Set<string>) => any;
+    additionalProps: (v: any, data: any, path: string, ctx: ValidationContext, knownKeys: string[] | Set<string>, childValidator: Function) => void;
+    object: (v: any, path: string, ctx: ValidationContext, allowedKeys?: string[] | Set<string>, expected?: string) => any;
     templateLiteral: (v: any, path: string, ctx: ValidationContext, regex: RegExp, expected: string) => any;
     minLength: (v: string, path: string, ctx: ValidationContext, min: number, message?: string) => string;
     maxLength: (v: string, path: string, ctx: ValidationContext, max: number, message?: string) => string;
@@ -90,13 +123,13 @@ 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[];
-        data: any;
+        data?: any;
     };
 }
 export declare function groupErrorsByPath(errors: IValidationError[]): Record<string, {