bguard 0.5.0 → 0.7.0

package/lib/core.d.mts

@@ -0,0 +1,330 @@
+import { BaseType, TranslationErrorMap, ValidationErrorData, MetaContext, TransformCallback, WithBGuardType, WithArray, WithTuple, WithObject, WithRecord, WithNull, WithUndefined, WithDefault, WithInput } from './commonTypes.mjs';
+import { InferInput, InferType } from './InferType.mjs';
+import { ctxSymbol } from './helpers/constants.mjs';
+import { StandardSchemaProps } from './standardSchema.mjs';
+
+declare class ExceptionContext {
+    readonly initialReceived: unknown;
+    readonly t: TranslationErrorMap;
+    readonly pathToError: string;
+    readonly errors?: ValidationErrorData[] | undefined;
+    readonly meta?: MetaContext | undefined;
+    /** The same location as `pathToError`, as keys. A string path cannot be taken apart again
+     * reliably, because a key may itself contain a dot or a bracket. */
+    readonly path: readonly PropertyKey[];
+    /** Where async validations are collected. Absent during a synchronous parse, which is how one
+     * is detected and reported rather than silently skipped. */
+    readonly pending?: PendingValidation[] | undefined;
+    constructor(initialReceived: unknown, t: TranslationErrorMap, pathToError: string, errors?: ValidationErrorData[] | undefined, meta?: MetaContext | undefined, 
+    /** The same location as `pathToError`, as keys. A string path cannot be taken apart again
+     * reliably, because a key may itself contain a dot or a bracket. */
+    path?: readonly PropertyKey[], 
+    /** Where async validations are collected. Absent during a synchronous parse, which is how one
+     * is detected and reported rather than silently skipped. */
+    pending?: PendingValidation[] | undefined);
+    /**
+     * The same location, reporting into a different errors list.
+     *
+     * A union tries each member against a throwaway list so a member that does not match is not fatal.
+     * An async validation reached inside the winning member is awaited long after that decision, so it
+     * has to be re-pointed at the real list or its issues would be collected where nobody reads them.
+     */
+    withErrors(errors?: ValidationErrorData[]): ExceptionContext;
+    /**
+     * Records async validations to be awaited once the walk is over.
+     *
+     * Throws during a synchronous parse rather than dropping them: a validation that never runs is worse
+     * than a clear instruction to use parseAsync.
+     */
+    enqueueAsync(validations: AsyncRequiredValidation[], received: unknown): void;
+    /**
+     * Descends into a property or an index, deriving both forms of the location from the same key so
+     * they cannot disagree.
+     */
+    createChild(pathSegment: PropertyKey, childMeta?: MetaContext): ExceptionContext;
+    ref(path: string): unknown;
+    addIssue(expected: unknown, received: unknown, messageKey: string): never | void;
+}
+/**
+ * A validation function run against an already type-checked value.
+ *
+ * `T` is the value the assert knows how to inspect, and it is what stops a string assert from
+ * being attached to a number schema: `custom` asks for `RequiredValidation<AssertInput<this>>`,
+ * and function parameters are compared contravariantly under `strictFunctionTypes`.
+ *
+ * An assert that genuinely accepts anything should declare `RequiredValidation<unknown>`, which
+ * stays assignable to every schema. The default of `any` is deliberate, so that custom asserts
+ * written against the previous signature keep compiling.
+ */
+type RequiredValidation<T = any> = (received: T, ctx: ExceptionContext) => void;
+/**
+ * A validation that has to wait for something — a database lookup, an HTTP call.
+ *
+ * Registered with `customAsync` and run by `parseAsync`. Asserts only add issues, they never change the
+ * value, so the value the synchronous walk produced is already final by the time these run.
+ */
+type AsyncRequiredValidation<T = any> = (received: T, ctx: ExceptionContext) => Promise<void>;
+/** An async validation that has been reached, waiting to be awaited once the walk is over. */
+interface PendingValidation {
+    validations: AsyncRequiredValidation[];
+    received: unknown;
+    ctx: ExceptionContext;
+}
+/**
+ * The runtime value a schema hands to its asserts. Nullish is stripped, because `innerCheck`
+ * returns before running asserts when the value is `null` or `undefined`.
+ */
+type AssertInput<T> = T extends WithBGuardType<unknown, infer Y> ? NonNullable<Y> : T extends WithArray<unknown, unknown> ? unknown[] : T extends WithTuple<unknown, unknown> ? unknown[] : T extends WithObject<unknown, unknown> ? Record<string, unknown> : T extends WithRecord<unknown, unknown, unknown> ? Record<string, unknown> : unknown;
+type ObjectShapeSchemaType = Record<string, CommonSchema>;
+interface RecordSchemaType {
+    key: CommonSchema;
+    value: CommonSchema;
+}
+interface LazySchemaType {
+    /** The name codeGen emits at the recursion point, instead of descending forever. */
+    typeName: string;
+    getSchema: () => CommonSchema;
+    /** Filled on first use, so the thunk runs once however many values are validated. */
+    resolved?: CommonSchema;
+}
+interface ValidatorContext {
+    type: BaseType[];
+    isNullable?: boolean;
+    isOptional?: boolean;
+    requiredValidations: RequiredValidation[];
+    asyncValidations?: AsyncRequiredValidation[];
+    array?: CommonSchema;
+    object?: ObjectShapeSchemaType;
+    union?: CommonSchema[];
+    record?: RecordSchemaType;
+    tuple?: CommonSchema[];
+    lazy?: LazySchemaType;
+    allowUnrecognizedObjectProps?: boolean;
+    strictType?: boolean;
+    strictTypeValue?: unknown;
+    date?: boolean;
+    defaultValue?: unknown;
+    meta?: MetaContext;
+    transformListBefore?: TransformCallback<any, any>[];
+}
+declare class CommonSchema {
+    [ctxSymbol]: ValidatorContext;
+    constructor(ctx: ValidatorContext);
+    /**
+     * The Standard Schema v1 interface, which lets a bguard schema be used by any library that accepts
+     * a validator without either side knowing about the other.
+     *
+     * A getter rather than a stored property, so it costs nothing until something asks for it and is
+     * not copied by `clone`. `types` is declared but deliberately never assigned: the spec defines it
+     * as type-only. Input and output are reported separately, so a consumer generating a form asks for
+     * what the schema takes rather than what it returns.
+     */
+    get '~standard'(): StandardSchemaProps<InferInput<this>, InferType<this>>;
+    /**
+     * Returns a copy of this schema that carries its own context.
+     *
+     * Every refining method goes through this, so a schema can be shared between properties and
+     * reused as a base without one use leaking into another. Construction is deliberately bypassed:
+     * the subclass constructors validate their arguments and take extra parameters, and neither
+     * applies when deriving from an already-valid schema.
+     *
+     * Public because deriving a schema is a reasonable thing to do from outside as well — the object
+     * utilities need it to rebuild a property schema without touching the one they were handed.
+     */
+    clone(): this;
+    /**
+     * @param validators - One or more custom validation functions.
+     * @returns {this} A new schema instance with the added custom validation.
+     */
+    custom(...validators: RequiredValidation<AssertInput<this>>[]): this;
+    /**
+     * Adds validations that have to wait for something, such as a database lookup.
+     *
+     * These run only under `parseAsync` or `parseOrFailAsync`; a synchronous parse reports a
+     * `BuildSchemaError` rather than skipping them. They are awaited after the structural walk is
+     * complete, all together, so several slow checks across a schema cost one round of waiting.
+     *
+     * @param validators - One or more async validation functions.
+     * @returns {this} A new schema instance with the added validations.
+     * @example
+     * const schema = string().customAsync(async (received, ctx) => {
+     *   if (await isTaken(received)) ctx.addIssue('an unused name', received, 'name is taken');
+     * });
+     */
+    customAsync(...validators: AsyncRequiredValidation<AssertInput<this>>[]): this;
+    /**
+     * Marks the schema as nullable, allowing the value to be `null`.
+     *
+     * @returns {WithNull<this>} A new schema instance marked as nullable.
+     */
+    nullable(): WithNull<this>;
+    /**
+     * Marks the schema as optional, allowing the value to be `undefined`.
+     *
+     * @returns {WithUndefined<this>} A new schema instance marked as optional.
+     */
+    optional(): WithUndefined<this>;
+    /**
+     * Marks the schema as optional, allowing the value to be `undefined`.
+     *
+     * @returns {this} The schema instance. This method should be used as a last one because it does the check of previous methods and
+     */
+    default(defaultValue: InferType<this>): WithDefault<this>;
+    /**
+     * Applies a transformation to the input value before any validation occurs.
+     * The transformation should return a value of the same type as the inferred type of the schema,
+     * ensuring that the overall type is not altered.
+     *
+     * @template In - The type of the input value before transformation (defaults to `unknown`).
+     * @param {TransformCallback<In, InferType<this>>} cb - The callback function that performs the transformation.
+     * @returns {this} A new schema with the applied transformation.
+     *
+     * @example
+     * const schema = string()
+     *   .nullable()
+     *   .transformBeforeValidation((val) => val + '') // Ensure the value is a string
+     *   .transformBeforeValidation((val: string) => (val === '' ? null : val)); // Convert empty strings to null
+     *
+     * // Parse 'test' will pass as 'test' is a valid string longer than 3 characters.
+     * parseOrFail(schema, 'test');
+     *
+     * // Parsing '' will be transformed to null and will pass due to .nullable().
+     * parseOrFail(schema, '');
+     */
+    transformBeforeValidation<In>(cb: TransformCallback<In, InferType<this>>): WithInput<this, In>;
+    /**
+     * Assigns a unique identifier to the schema.
+     * This ID can be used to track or map validation errors back to specific fields
+     * in a form or other structures.
+     *
+     * @param {string} value - The unique identifier for the schema.
+     * @returns {this} A new schema with the assigned ID.
+     *
+     * @example
+     * const schema = string().id('username');
+     */
+    id(value: string): this;
+    /**
+     * Provides a description for the schema, offering additional context or information.
+     * The description can be used when displaying validation errors or for documentation purposes.
+     *
+     * @param {string} value - The description for the schema.
+     * @returns {this} A new schema with the added description.
+     *
+     * @example
+     * const schema = string().description('The username of the account holder.');
+     */
+    description(value: string): this;
+    private meta;
+    protected defaultValueCheck(): void;
+}
+/**
+ * Parses and validates a value against the provided schema, returning a type-safe result.
+ *
+ * This function will throw a `ValidationError` if the value does not conform to the schema.
+ * The inferred TypeScript type of the returned value will match the structure defined by the schema.
+ *
+ * @template T
+ * @param {T} schema - The schema to validate the received value against. This schema dictates the expected structure and type of the value.
+ * @param {unknown} receivedValue - The value to be validated and parsed according to the schema.
+ * @param {ParseOptions} options - Options
+ * @param {ParseOptions.lng} options.lng -  Set language keyword to map Error message
+ * @returns {InferType<T>} The validated value, with its TypeScript type inferred from the schema.
+ *
+ * @throws {ValidationError} If the received value does not match the schema, a `ValidationError` will be thrown.
+ * @throws {Error} If an unexpected error occurs during validation, an error will be thrown with a generic message.
+ *
+ * @example
+ * const schema = object({
+ *   name: string(),
+ *   age: number(),
+ * });
+ *
+ * const result = parseOrFail(schema, { name: 'Alice', age: 30 });
+ * // result will be inferred as { name: string; age: number }
+ *
+ * parseOrFail(schema, { name: 'Alice', age: '30' });
+ * // Throws ValidationError because 'age' should be a number, not a string.
+ */
+declare function parseOrFail<T extends CommonSchema>(schema: T, receivedValue: unknown, options?: ParseOptions): InferType<T>;
+interface ParseOptions {
+    /**
+     * Set language keyword to map error messages.
+     * @default 'default'
+     * @example 'sr' or 'Serbia' or any string to identify language
+     */
+    lng?: string;
+}
+interface ParseAllOptions extends ParseOptions {
+    /**
+     * If true, collects all validation errors and returns them.
+     * If false or undefined, returns the first validation error it can find and stops looking,
+     * which provides a small runtime optimization.
+     *
+     * Declared only where it is honoured. `parseOrFail` throws on the first error by definition, and it
+     * used to accept this flag and ignore it.
+     * @default undefined
+     */
+    getAllErrors?: boolean;
+}
+/**
+ * Parses and validates a value against the provided schema, returning a type-safe parsedValue.
+ *
+ * This function will throw a `ValidationError` if the value does not conform to the schema.
+ * The inferred TypeScript type of the returned value will match the structure defined by the schema.
+ *
+ * @template T
+ * @param {T} schema - The schema to validate the received value against. This schema dictates the expected structure and type of the value.
+ * @param {unknown} receivedValue - The value to be validated and parsed according to the schema.
+ * @param {ParseOptions} options - Options
+ * @param {ParseOptions.lng} options.lng -  Set language keyword to map Error messages
+ * @param {ParseOptions.lng} options.getAllErrors - If `false` or `undefined` - returns the first validation error it can find and stops looking, which provides a small runtime optimization.
+ * @returns {[undefined, InferType<T>]} A tuple of [undefined, InferType<T>] if parsing is successful.
+ * @returns {[ValidationErrorData[], undefined]} A tuple of [ValidationErrorData[], undefined]] if errors occur.
+ *
+ * @example
+ * const schema = object({
+ *   name: string(),
+ *   age: number(),
+ * });
+ *
+ * const [errors, parsedValue]  = parse(schema, { name: 'Alice', age: 30 });
+ * // parsedValue will be inferred as { name: string; age: number }
+ *
+ *
+ *  const [errors, parsedValue] = parse(schema, { name: 'Alice', age: '30' });
+ * // First element in array "errors" will have an error because 'age' should be a number, not a string.
+ * // Array 'errors' returns only one element.
+ *
+ *
+ *  const [errors, parsedValue] = parse(schema, { name: true, age: '30' }, { getAllErrors: true});
+ * // Returns array "errors" with multiple errors because 'age' should be a number and 'name' a string.
+ * // With provided options { getAllErrors: true}, we can expecte more than one error in 'errors' array.
+ *
+ *
+ *  const [errors, parsedValue] = parse(schema, { name: true, age: '30' }, { lng: 'SR'});
+ * // First element in array "errors" will have an error because 'age' should be a number, not a string.
+ * // With provided options { lng: 'SR'}, errors will be translated to a language mapped with keyword 'SR'
+ */
+declare function parse<T extends CommonSchema>(schema: T, receivedValue: unknown, options?: ParseAllOptions): [ValidationErrorData[], null] | [null, InferType<T>];
+/**
+ * The asynchronous counterpart of {@link parse}, for schemas carrying `customAsync` validations.
+ *
+ * The structure is validated synchronously first and the async validations run afterwards, all
+ * together. That means their issues come after the synchronous ones in the returned array, and that an
+ * async validation is never reached for a value the synchronous pass already rejected structurally.
+ *
+ * @example
+ * const [errors, value] = await parseAsync(schema, received, { getAllErrors: true });
+ */
+declare function parseAsync<T extends CommonSchema>(schema: T, receivedValue: unknown, options?: ParseAllOptions): Promise<[ValidationErrorData[], null] | [null, InferType<T>]>;
+/**
+ * The asynchronous counterpart of {@link parseOrFail}.
+ *
+ * Unlike the synchronous version it cannot stop at the first error, because the async validations have
+ * to be awaited before anything can be reported. It throws the first error found, in the same order
+ * `parseAsync` reports them.
+ */
+declare function parseOrFailAsync<T extends CommonSchema>(schema: T, receivedValue: unknown, options?: ParseOptions): Promise<InferType<T>>;
+
+export { type AssertInput, type AsyncRequiredValidation, CommonSchema, ExceptionContext, type LazySchemaType, type ObjectShapeSchemaType, type RecordSchemaType, type RequiredValidation, type ValidatorContext, parse, parseAsync, parseOrFail, parseOrFailAsync };

package/lib/core.d.ts

@@ -0,0 +1,330 @@
+import { BaseType, TranslationErrorMap, ValidationErrorData, MetaContext, TransformCallback, WithBGuardType, WithArray, WithTuple, WithObject, WithRecord, WithNull, WithUndefined, WithDefault, WithInput } from './commonTypes.js';
+import { InferInput, InferType } from './InferType.js';
+import { ctxSymbol } from './helpers/constants.js';
+import { StandardSchemaProps } from './standardSchema.js';
+
+declare class ExceptionContext {
+    readonly initialReceived: unknown;
+    readonly t: TranslationErrorMap;
+    readonly pathToError: string;
+    readonly errors?: ValidationErrorData[] | undefined;
+    readonly meta?: MetaContext | undefined;
+    /** The same location as `pathToError`, as keys. A string path cannot be taken apart again
+     * reliably, because a key may itself contain a dot or a bracket. */
+    readonly path: readonly PropertyKey[];
+    /** Where async validations are collected. Absent during a synchronous parse, which is how one
+     * is detected and reported rather than silently skipped. */
+    readonly pending?: PendingValidation[] | undefined;
+    constructor(initialReceived: unknown, t: TranslationErrorMap, pathToError: string, errors?: ValidationErrorData[] | undefined, meta?: MetaContext | undefined, 
+    /** The same location as `pathToError`, as keys. A string path cannot be taken apart again
+     * reliably, because a key may itself contain a dot or a bracket. */
+    path?: readonly PropertyKey[], 
+    /** Where async validations are collected. Absent during a synchronous parse, which is how one
+     * is detected and reported rather than silently skipped. */
+    pending?: PendingValidation[] | undefined);
+    /**
+     * The same location, reporting into a different errors list.
+     *
+     * A union tries each member against a throwaway list so a member that does not match is not fatal.
+     * An async validation reached inside the winning member is awaited long after that decision, so it
+     * has to be re-pointed at the real list or its issues would be collected where nobody reads them.
+     */
+    withErrors(errors?: ValidationErrorData[]): ExceptionContext;
+    /**
+     * Records async validations to be awaited once the walk is over.
+     *
+     * Throws during a synchronous parse rather than dropping them: a validation that never runs is worse
+     * than a clear instruction to use parseAsync.
+     */
+    enqueueAsync(validations: AsyncRequiredValidation[], received: unknown): void;
+    /**
+     * Descends into a property or an index, deriving both forms of the location from the same key so
+     * they cannot disagree.
+     */
+    createChild(pathSegment: PropertyKey, childMeta?: MetaContext): ExceptionContext;
+    ref(path: string): unknown;
+    addIssue(expected: unknown, received: unknown, messageKey: string): never | void;
+}
+/**
+ * A validation function run against an already type-checked value.
+ *
+ * `T` is the value the assert knows how to inspect, and it is what stops a string assert from
+ * being attached to a number schema: `custom` asks for `RequiredValidation<AssertInput<this>>`,
+ * and function parameters are compared contravariantly under `strictFunctionTypes`.
+ *
+ * An assert that genuinely accepts anything should declare `RequiredValidation<unknown>`, which
+ * stays assignable to every schema. The default of `any` is deliberate, so that custom asserts
+ * written against the previous signature keep compiling.
+ */
+type RequiredValidation<T = any> = (received: T, ctx: ExceptionContext) => void;
+/**
+ * A validation that has to wait for something — a database lookup, an HTTP call.
+ *
+ * Registered with `customAsync` and run by `parseAsync`. Asserts only add issues, they never change the
+ * value, so the value the synchronous walk produced is already final by the time these run.
+ */
+type AsyncRequiredValidation<T = any> = (received: T, ctx: ExceptionContext) => Promise<void>;
+/** An async validation that has been reached, waiting to be awaited once the walk is over. */
+interface PendingValidation {
+    validations: AsyncRequiredValidation[];
+    received: unknown;
+    ctx: ExceptionContext;
+}
+/**
+ * The runtime value a schema hands to its asserts. Nullish is stripped, because `innerCheck`
+ * returns before running asserts when the value is `null` or `undefined`.
+ */
+type AssertInput<T> = T extends WithBGuardType<unknown, infer Y> ? NonNullable<Y> : T extends WithArray<unknown, unknown> ? unknown[] : T extends WithTuple<unknown, unknown> ? unknown[] : T extends WithObject<unknown, unknown> ? Record<string, unknown> : T extends WithRecord<unknown, unknown, unknown> ? Record<string, unknown> : unknown;
+type ObjectShapeSchemaType = Record<string, CommonSchema>;
+interface RecordSchemaType {
+    key: CommonSchema;
+    value: CommonSchema;
+}
+interface LazySchemaType {
+    /** The name codeGen emits at the recursion point, instead of descending forever. */
+    typeName: string;
+    getSchema: () => CommonSchema;
+    /** Filled on first use, so the thunk runs once however many values are validated. */
+    resolved?: CommonSchema;
+}
+interface ValidatorContext {
+    type: BaseType[];
+    isNullable?: boolean;
+    isOptional?: boolean;
+    requiredValidations: RequiredValidation[];
+    asyncValidations?: AsyncRequiredValidation[];
+    array?: CommonSchema;
+    object?: ObjectShapeSchemaType;
+    union?: CommonSchema[];
+    record?: RecordSchemaType;
+    tuple?: CommonSchema[];
+    lazy?: LazySchemaType;
+    allowUnrecognizedObjectProps?: boolean;
+    strictType?: boolean;
+    strictTypeValue?: unknown;
+    date?: boolean;
+    defaultValue?: unknown;
+    meta?: MetaContext;
+    transformListBefore?: TransformCallback<any, any>[];
+}
+declare class CommonSchema {
+    [ctxSymbol]: ValidatorContext;
+    constructor(ctx: ValidatorContext);
+    /**
+     * The Standard Schema v1 interface, which lets a bguard schema be used by any library that accepts
+     * a validator without either side knowing about the other.
+     *
+     * A getter rather than a stored property, so it costs nothing until something asks for it and is
+     * not copied by `clone`. `types` is declared but deliberately never assigned: the spec defines it
+     * as type-only. Input and output are reported separately, so a consumer generating a form asks for
+     * what the schema takes rather than what it returns.
+     */
+    get '~standard'(): StandardSchemaProps<InferInput<this>, InferType<this>>;
+    /**
+     * Returns a copy of this schema that carries its own context.
+     *
+     * Every refining method goes through this, so a schema can be shared between properties and
+     * reused as a base without one use leaking into another. Construction is deliberately bypassed:
+     * the subclass constructors validate their arguments and take extra parameters, and neither
+     * applies when deriving from an already-valid schema.
+     *
+     * Public because deriving a schema is a reasonable thing to do from outside as well — the object
+     * utilities need it to rebuild a property schema without touching the one they were handed.
+     */
+    clone(): this;
+    /**
+     * @param validators - One or more custom validation functions.
+     * @returns {this} A new schema instance with the added custom validation.
+     */
+    custom(...validators: RequiredValidation<AssertInput<this>>[]): this;
+    /**
+     * Adds validations that have to wait for something, such as a database lookup.
+     *
+     * These run only under `parseAsync` or `parseOrFailAsync`; a synchronous parse reports a
+     * `BuildSchemaError` rather than skipping them. They are awaited after the structural walk is
+     * complete, all together, so several slow checks across a schema cost one round of waiting.
+     *
+     * @param validators - One or more async validation functions.
+     * @returns {this} A new schema instance with the added validations.
+     * @example
+     * const schema = string().customAsync(async (received, ctx) => {
+     *   if (await isTaken(received)) ctx.addIssue('an unused name', received, 'name is taken');
+     * });
+     */
+    customAsync(...validators: AsyncRequiredValidation<AssertInput<this>>[]): this;
+    /**
+     * Marks the schema as nullable, allowing the value to be `null`.
+     *
+     * @returns {WithNull<this>} A new schema instance marked as nullable.
+     */
+    nullable(): WithNull<this>;
+    /**
+     * Marks the schema as optional, allowing the value to be `undefined`.
+     *
+     * @returns {WithUndefined<this>} A new schema instance marked as optional.
+     */
+    optional(): WithUndefined<this>;
+    /**
+     * Marks the schema as optional, allowing the value to be `undefined`.
+     *
+     * @returns {this} The schema instance. This method should be used as a last one because it does the check of previous methods and
+     */
+    default(defaultValue: InferType<this>): WithDefault<this>;
+    /**
+     * Applies a transformation to the input value before any validation occurs.
+     * The transformation should return a value of the same type as the inferred type of the schema,
+     * ensuring that the overall type is not altered.
+     *
+     * @template In - The type of the input value before transformation (defaults to `unknown`).
+     * @param {TransformCallback<In, InferType<this>>} cb - The callback function that performs the transformation.
+     * @returns {this} A new schema with the applied transformation.
+     *
+     * @example
+     * const schema = string()
+     *   .nullable()
+     *   .transformBeforeValidation((val) => val + '') // Ensure the value is a string
+     *   .transformBeforeValidation((val: string) => (val === '' ? null : val)); // Convert empty strings to null
+     *
+     * // Parse 'test' will pass as 'test' is a valid string longer than 3 characters.
+     * parseOrFail(schema, 'test');
+     *
+     * // Parsing '' will be transformed to null and will pass due to .nullable().
+     * parseOrFail(schema, '');
+     */
+    transformBeforeValidation<In>(cb: TransformCallback<In, InferType<this>>): WithInput<this, In>;
+    /**
+     * Assigns a unique identifier to the schema.
+     * This ID can be used to track or map validation errors back to specific fields
+     * in a form or other structures.
+     *
+     * @param {string} value - The unique identifier for the schema.
+     * @returns {this} A new schema with the assigned ID.
+     *
+     * @example
+     * const schema = string().id('username');
+     */
+    id(value: string): this;
+    /**
+     * Provides a description for the schema, offering additional context or information.
+     * The description can be used when displaying validation errors or for documentation purposes.
+     *
+     * @param {string} value - The description for the schema.
+     * @returns {this} A new schema with the added description.
+     *
+     * @example
+     * const schema = string().description('The username of the account holder.');
+     */
+    description(value: string): this;
+    private meta;
+    protected defaultValueCheck(): void;
+}
+/**
+ * Parses and validates a value against the provided schema, returning a type-safe result.
+ *
+ * This function will throw a `ValidationError` if the value does not conform to the schema.
+ * The inferred TypeScript type of the returned value will match the structure defined by the schema.
+ *
+ * @template T
+ * @param {T} schema - The schema to validate the received value against. This schema dictates the expected structure and type of the value.
+ * @param {unknown} receivedValue - The value to be validated and parsed according to the schema.
+ * @param {ParseOptions} options - Options
+ * @param {ParseOptions.lng} options.lng -  Set language keyword to map Error message
+ * @returns {InferType<T>} The validated value, with its TypeScript type inferred from the schema.
+ *
+ * @throws {ValidationError} If the received value does not match the schema, a `ValidationError` will be thrown.
+ * @throws {Error} If an unexpected error occurs during validation, an error will be thrown with a generic message.
+ *
+ * @example
+ * const schema = object({
+ *   name: string(),
+ *   age: number(),
+ * });
+ *
+ * const result = parseOrFail(schema, { name: 'Alice', age: 30 });
+ * // result will be inferred as { name: string; age: number }
+ *
+ * parseOrFail(schema, { name: 'Alice', age: '30' });
+ * // Throws ValidationError because 'age' should be a number, not a string.
+ */
+declare function parseOrFail<T extends CommonSchema>(schema: T, receivedValue: unknown, options?: ParseOptions): InferType<T>;
+interface ParseOptions {
+    /**
+     * Set language keyword to map error messages.
+     * @default 'default'
+     * @example 'sr' or 'Serbia' or any string to identify language
+     */
+    lng?: string;
+}
+interface ParseAllOptions extends ParseOptions {
+    /**
+     * If true, collects all validation errors and returns them.
+     * If false or undefined, returns the first validation error it can find and stops looking,
+     * which provides a small runtime optimization.
+     *
+     * Declared only where it is honoured. `parseOrFail` throws on the first error by definition, and it
+     * used to accept this flag and ignore it.
+     * @default undefined
+     */
+    getAllErrors?: boolean;
+}
+/**
+ * Parses and validates a value against the provided schema, returning a type-safe parsedValue.
+ *
+ * This function will throw a `ValidationError` if the value does not conform to the schema.
+ * The inferred TypeScript type of the returned value will match the structure defined by the schema.
+ *
+ * @template T
+ * @param {T} schema - The schema to validate the received value against. This schema dictates the expected structure and type of the value.
+ * @param {unknown} receivedValue - The value to be validated and parsed according to the schema.
+ * @param {ParseOptions} options - Options
+ * @param {ParseOptions.lng} options.lng -  Set language keyword to map Error messages
+ * @param {ParseOptions.lng} options.getAllErrors - If `false` or `undefined` - returns the first validation error it can find and stops looking, which provides a small runtime optimization.
+ * @returns {[undefined, InferType<T>]} A tuple of [undefined, InferType<T>] if parsing is successful.
+ * @returns {[ValidationErrorData[], undefined]} A tuple of [ValidationErrorData[], undefined]] if errors occur.
+ *
+ * @example
+ * const schema = object({
+ *   name: string(),
+ *   age: number(),
+ * });
+ *
+ * const [errors, parsedValue]  = parse(schema, { name: 'Alice', age: 30 });
+ * // parsedValue will be inferred as { name: string; age: number }
+ *
+ *
+ *  const [errors, parsedValue] = parse(schema, { name: 'Alice', age: '30' });
+ * // First element in array "errors" will have an error because 'age' should be a number, not a string.
+ * // Array 'errors' returns only one element.
+ *
+ *
+ *  const [errors, parsedValue] = parse(schema, { name: true, age: '30' }, { getAllErrors: true});
+ * // Returns array "errors" with multiple errors because 'age' should be a number and 'name' a string.
+ * // With provided options { getAllErrors: true}, we can expecte more than one error in 'errors' array.
+ *
+ *
+ *  const [errors, parsedValue] = parse(schema, { name: true, age: '30' }, { lng: 'SR'});
+ * // First element in array "errors" will have an error because 'age' should be a number, not a string.
+ * // With provided options { lng: 'SR'}, errors will be translated to a language mapped with keyword 'SR'
+ */
+declare function parse<T extends CommonSchema>(schema: T, receivedValue: unknown, options?: ParseAllOptions): [ValidationErrorData[], null] | [null, InferType<T>];
+/**
+ * The asynchronous counterpart of {@link parse}, for schemas carrying `customAsync` validations.
+ *
+ * The structure is validated synchronously first and the async validations run afterwards, all
+ * together. That means their issues come after the synchronous ones in the returned array, and that an
+ * async validation is never reached for a value the synchronous pass already rejected structurally.
+ *
+ * @example
+ * const [errors, value] = await parseAsync(schema, received, { getAllErrors: true });
+ */
+declare function parseAsync<T extends CommonSchema>(schema: T, receivedValue: unknown, options?: ParseAllOptions): Promise<[ValidationErrorData[], null] | [null, InferType<T>]>;
+/**
+ * The asynchronous counterpart of {@link parseOrFail}.
+ *
+ * Unlike the synchronous version it cannot stop at the first error, because the async validations have
+ * to be awaited before anything can be reported. It throws the first error found, in the same order
+ * `parseAsync` reports them.
+ */
+declare function parseOrFailAsync<T extends CommonSchema>(schema: T, receivedValue: unknown, options?: ParseOptions): Promise<InferType<T>>;
+
+export { type AssertInput, type AsyncRequiredValidation, CommonSchema, ExceptionContext, type LazySchemaType, type ObjectShapeSchemaType, type RecordSchemaType, type RequiredValidation, type ValidatorContext, parse, parseAsync, parseOrFail, parseOrFailAsync };