@webergency-utils/typechecker 0.1.10 → 0.2.2

package/dist/runtime/validators.d.ts

@@ -1,29 +1,80 @@
+/** Controls unknown object keys only — not coercion. Use `from` for conversion. */
 export type ValidationMode = 'strict' | 'relaxed' | 'strip';
 export interface IValidationError {
     path: string;
     value: any;
     error: string;
+    /** Nested failures (e.g. per-arm errors for a failed union). */
+    issues?: IValidationError[];
 }
+/** 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;
-    tryConvert?: boolean;
-    wrapArrays?: boolean;
+    from?: FromOption;
+    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;
-    tryConvert?: boolean;
-    wrapArrays?: boolean;
-    schema?: any;
+    from?: FromOption;
+}
+/** 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;
+}
+/** Options for `assert` / `assertSchema`. */
+export interface AssertOptions extends ValidationOptions {
     errorFactory?: (errors: IValidationError[]) => Error;
 }
+/** 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`. */
+export declare function coerceQueryBoolean(v: any): any;
+/** JSON-wire Date revival (ISO / date-parseable strings only). */
+export declare function coerceJsonDate(v: any): any;
+/** Query-style Date coercion — shared by `from: 'query'` and `transform.ToDate`. */
+export declare function coerceQueryDate(v: any): any;
 export declare const validators: {
+    coerceQueryNumber: typeof coerceQueryNumber;
+    coerceQueryBoolean: typeof coerceQueryBoolean;
+    coerceQueryDate: typeof coerceQueryDate;
+    coerceJsonDate: typeof coerceJsonDate;
     string: (v: any, path: string, ctx: ValidationContext) => any;
     number: (v: any, path: string, ctx: ValidationContext) => any;
     bigint: (v: any, path: string, ctx: ValidationContext) => any;
     boolean: (v: any, path: string, ctx: ValidationContext) => any;
+    function: (v: any, path: string, ctx: ValidationContext) => any;
     date: (v: any, path: string, ctx: ValidationContext) => any;
     regexp: (v: any, path: string, ctx: ValidationContext) => any;
     null: (v: any, path: string, ctx: ValidationContext) => null;
@@ -31,7 +82,10 @@ export declare const validators: {
     literal: (v: any, path: string, ctx: ValidationContext, expected: any) => any;
     array: (v: any, path: string, ctx: ValidationContext, childValidator: Function) => any;
     props: (v: any, data: any, path: string, ctx: ValidationContext, props: [string, boolean, Function][]) => void;
-    object: (v: any, path: string, ctx: ValidationContext, allowedKeys?: string[], expected?: string) => boolean;
+    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;
     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;
@@ -41,7 +95,7 @@ export declare const validators: {
     exclusiveMaximum: (v: number | bigint, path: string, ctx: ValidationContext, max: number | bigint, message?: string) => number | bigint;
     multipleOf: (v: number | bigint, path: string, ctx: ValidationContext, n: number | bigint, message?: string) => number | bigint;
     pattern: (v: string, path: string, ctx: ValidationContext, regex: RegExp, expected: string, message?: string) => string;
-    format: (v: string, path: string, ctx: ValidationContext, format: string, message?: string) => string;
+    format: (v: string, path: string, ctx: ValidationContext, format: string, message?: string) => any;
     minItems: (v: any[], path: string, ctx: ValidationContext, min: number, message?: string) => any[];
     maxItems: (v: any[], path: string, ctx: ValidationContext, max: number, message?: string) => any[];
     uniqueItems: (v: any[], path: string, ctx: ValidationContext, message?: string) => any[];
@@ -49,6 +103,9 @@ export declare const validators: {
     union: (v: any, path: string, ctx: ValidationContext, checks: Function[], expected?: string) => any;
     tuple: (v: any, path: string, ctx: ValidationContext, checks: Function[]) => any;
     any: (v: any) => any;
+    never: (v: any, path: string, ctx: ValidationContext) => any;
+    symbol: (v: any, path: string, ctx: ValidationContext) => any;
+    instanceOf: (v: any, path: string, ctx: ValidationContext, typeName: string) => any;
     requires: (v: any, path: string, ctx: ValidationContext, reqs: string[], message?: string) => any;
     record: (v: any, path: string, ctx: ValidationContext, childValidator: Function) => any;
     set: (v: any, path: string, ctx: ValidationContext, childValidator: Function, message?: string) => any;
@@ -63,8 +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;
+    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[];
@@ -77,13 +135,9 @@ export declare function groupErrorsByPath(errors: IValidationError[]): Record<st
 }>;
 export declare const MetadataStore: MetadataStoreClass;
 export declare function compileSchema(schema: any): (v: any, path: string, ctx: any) => any;
-export declare function toZodIssues(errors: IValidationError[]): {
-    code: string;
-    path: (string | number)[];
-    message: string;
-    received: any;
-}[];
+export declare function toZodIssues(errors: IValidationError[]): any[];
 export declare class ZodLikeError extends Error {
     issues: any[];
     constructor(errors: IValidationError[]);
 }
+export {};