bguard 0.6.0 → 0.7.1

package/lib/core.d.mts

@@ -1,6 +1,7 @@
-import { BaseType, TranslationErrorMap, ValidationErrorData, MetaContext, TransformCallback, WithNull, WithUndefined } from './commonTypes.mjs';
-import { InferType } from './InferType.mjs';
+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;
@@ -8,20 +9,96 @@ declare class ExceptionContext {
     readonly pathToError: string;
     readonly errors?: ValidationErrorData[] | undefined;
     readonly meta?: MetaContext | undefined;
-    constructor(initialReceived: unknown, t: TranslationErrorMap, pathToError: string, errors?: ValidationErrorData[] | undefined, meta?: MetaContext | undefined);
-    createChild(childPathToError: string, childMeta?: MetaContext): ExceptionContext;
+    /** 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;
 }
-type RequiredValidation = (received: any, ctx: ExceptionContext) => 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;
@@ -33,21 +110,58 @@ interface ValidatorContext {
 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} The schema instance with the added custom validation.
+     * @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');
+     * });
      */
-    custom(...validators: RequiredValidation[]): this;
+    customAsync(...validators: AsyncRequiredValidation<AssertInput<this>>[]): this;
     /**
      * Marks the schema as nullable, allowing the value to be `null`.
      *
-     * @returns {WithNull<this>} The schema instance marked as nullable.
+     * @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>} The schema instance marked as optional.
+     * @returns {WithUndefined<this>} A new schema instance marked as optional.
      */
     optional(): WithUndefined<this>;
     /**
@@ -55,7 +169,7 @@ declare class CommonSchema {
      *
      * @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>): this;
+    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,
@@ -63,7 +177,7 @@ declare class CommonSchema {
      *
      * @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} The updated schema with the applied transformation.
+     * @returns {this} A new schema with the applied transformation.
      *
      * @example
      * const schema = string()
@@ -77,14 +191,14 @@ declare class CommonSchema {
      * // Parsing '' will be transformed to null and will pass due to .nullable().
      * parseOrFail(schema, '');
      */
-    transformBeforeValidation<In>(cb: TransformCallback<In, InferType<this>>): this;
+    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} The updated schema with the assigned ID.
+     * @returns {this} A new schema with the assigned ID.
      *
      * @example
      * const schema = string().id('username');
@@ -95,7 +209,7 @@ declare class CommonSchema {
      * The description can be used when displaying validation errors or for documentation purposes.
      *
      * @param {string} value - The description for the schema.
-     * @returns {this} The updated schema with the added description.
+     * @returns {this} A new schema with the added description.
      *
      * @example
      * const schema = string().description('The username of the account holder.');
@@ -141,17 +255,14 @@ interface ParseOptions {
      */
     lng?: string;
 }
-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;
@@ -195,6 +306,25 @@ interface ParseOptions {
  * // 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?: ParseOptions): [ValidationErrorData[], undefined] | [undefined, InferType<T>];
+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 { CommonSchema, ExceptionContext, type ObjectShapeSchemaType, type RequiredValidation, type ValidatorContext, parse, parseOrFail };
+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

@@ -1,6 +1,7 @@
-import { BaseType, TranslationErrorMap, ValidationErrorData, MetaContext, TransformCallback, WithNull, WithUndefined } from './commonTypes.js';
-import { InferType } from './InferType.js';
+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;
@@ -8,20 +9,96 @@ declare class ExceptionContext {
     readonly pathToError: string;
     readonly errors?: ValidationErrorData[] | undefined;
     readonly meta?: MetaContext | undefined;
-    constructor(initialReceived: unknown, t: TranslationErrorMap, pathToError: string, errors?: ValidationErrorData[] | undefined, meta?: MetaContext | undefined);
-    createChild(childPathToError: string, childMeta?: MetaContext): ExceptionContext;
+    /** 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;
 }
-type RequiredValidation = (received: any, ctx: ExceptionContext) => 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;
@@ -33,21 +110,58 @@ interface ValidatorContext {
 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} The schema instance with the added custom validation.
+     * @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');
+     * });
      */
-    custom(...validators: RequiredValidation[]): this;
+    customAsync(...validators: AsyncRequiredValidation<AssertInput<this>>[]): this;
     /**
      * Marks the schema as nullable, allowing the value to be `null`.
      *
-     * @returns {WithNull<this>} The schema instance marked as nullable.
+     * @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>} The schema instance marked as optional.
+     * @returns {WithUndefined<this>} A new schema instance marked as optional.
      */
     optional(): WithUndefined<this>;
     /**
@@ -55,7 +169,7 @@ declare class CommonSchema {
      *
      * @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>): this;
+    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,
@@ -63,7 +177,7 @@ declare class CommonSchema {
      *
      * @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} The updated schema with the applied transformation.
+     * @returns {this} A new schema with the applied transformation.
      *
      * @example
      * const schema = string()
@@ -77,14 +191,14 @@ declare class CommonSchema {
      * // Parsing '' will be transformed to null and will pass due to .nullable().
      * parseOrFail(schema, '');
      */
-    transformBeforeValidation<In>(cb: TransformCallback<In, InferType<this>>): this;
+    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} The updated schema with the assigned ID.
+     * @returns {this} A new schema with the assigned ID.
      *
      * @example
      * const schema = string().id('username');
@@ -95,7 +209,7 @@ declare class CommonSchema {
      * The description can be used when displaying validation errors or for documentation purposes.
      *
      * @param {string} value - The description for the schema.
-     * @returns {this} The updated schema with the added description.
+     * @returns {this} A new schema with the added description.
      *
      * @example
      * const schema = string().description('The username of the account holder.');
@@ -141,17 +255,14 @@ interface ParseOptions {
      */
     lng?: string;
 }
-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;
@@ -195,6 +306,25 @@ interface ParseOptions {
  * // 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?: ParseOptions): [ValidationErrorData[], undefined] | [undefined, InferType<T>];
+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 { CommonSchema, ExceptionContext, type ObjectShapeSchemaType, type RequiredValidation, type ValidatorContext, parse, parseOrFail };
+export { type AssertInput, type AsyncRequiredValidation, CommonSchema, ExceptionContext, type LazySchemaType, type ObjectShapeSchemaType, type RecordSchemaType, type RequiredValidation, type ValidatorContext, parse, parseAsync, parseOrFail, parseOrFailAsync };

package/lib/core.js

@@ -3,15 +3,19 @@
 
 
 
-var _chunkVN4GLOENjs = require('./chunk-VN4GLOEN.js');
+
+
+var _chunk6LUSV3SSjs = require('./chunk-6LUSV3SS.js');
+require('./chunk-ZJGY6EOE.js');
 require('./chunk-VBTWYDEM.js');
-require('./chunk-TJQ5NVL4.js');
-require('./chunk-FIDPCCCW.js');
-require('./chunk-AXKX5BGH.js');
+require('./chunk-LHEU4XAC.js');
+require('./chunk-ZWFSAKQK.js');
+
+
 
 
 
 
 
-exports.CommonSchema = _chunkVN4GLOENjs.CommonSchema; exports.ExceptionContext = _chunkVN4GLOENjs.ExceptionContext; exports.parse = _chunkVN4GLOENjs.parse; exports.parseOrFail = _chunkVN4GLOENjs.parseOrFail;
+exports.CommonSchema = _chunk6LUSV3SSjs.CommonSchema; exports.ExceptionContext = _chunk6LUSV3SSjs.ExceptionContext; exports.parse = _chunk6LUSV3SSjs.parse; exports.parseAsync = _chunk6LUSV3SSjs.parseAsync; exports.parseOrFail = _chunk6LUSV3SSjs.parseOrFail; exports.parseOrFailAsync = _chunk6LUSV3SSjs.parseOrFailAsync;
 //# sourceMappingURL=core.js.map

package/lib/core.js.map

@@ -1 +1 @@
-{"version":3,"sources":["/home/runner/work/bguard/bguard/lib/core.js"],"names":[],"mappings":"AAAA;AACE;AACA;AACA;AACA;AACF,sDAA4B;AAC5B,+BAA4B;AAC5B,+BAA4B;AAC5B,+BAA4B;AAC5B,+BAA4B;AAC5B;AACE;AACA;AACA;AACA;AACF,+MAAC","file":"/home/runner/work/bguard/bguard/lib/core.js"}
+{"version":3,"sources":["/home/runner/work/bguard/bguard/lib/core.js"],"names":[],"mappings":"AAAA;AACE;AACA;AACA;AACA;AACA;AACA;AACF,sDAA4B;AAC5B,+BAA4B;AAC5B,+BAA4B;AAC5B,+BAA4B;AAC5B,+BAA4B;AAC5B;AACE;AACA;AACA;AACA;AACA;AACA;AACF,+TAAC","file":"/home/runner/work/bguard/bguard/lib/core.js"}

package/lib/core.mjs

@@ -2,16 +2,20 @@ import {
   CommonSchema,
   ExceptionContext,
   parse,
-  parseOrFail
-} from "./chunk-QIPGUTIG.mjs";
+  parseAsync,
+  parseOrFail,
+  parseOrFailAsync
+} from "./chunk-LDZFOOWN.mjs";
+import "./chunk-65X7NTUS.mjs";
 import "./chunk-YBVMP4EI.mjs";
-import "./chunk-OE3L7EKN.mjs";
-import "./chunk-ZTCXXAKD.mjs";
-import "./chunk-2ANPCB4O.mjs";
+import "./chunk-C76DLZFD.mjs";
+import "./chunk-O2WD4JBG.mjs";
 export {
   CommonSchema,
   ExceptionContext,
   parse,
-  parseOrFail
+  parseAsync,
+  parseOrFail,
+  parseOrFailAsync
 };
 //# sourceMappingURL=core.mjs.map

package/lib/exceptions.d.mts

@@ -4,9 +4,13 @@ declare class ValidationError extends Error {
     expected: unknown;
     received: unknown;
     pathToError: string;
+    /** The same location as `pathToError`, as keys. */
+    path: readonly PropertyKey[];
+    /** The translation key of this failure, stable across locales. */
+    code: string;
     message: string;
     meta?: MetaContext;
-    constructor(expected: unknown, received: unknown, pathToError: string, message: string, meta?: MetaContext);
+    constructor(expected: unknown, received: unknown, pathToError: string, message: string, meta?: MetaContext, path?: readonly PropertyKey[], code?: string);
 }
 declare class BuildSchemaError extends Error {
 }

package/lib/exceptions.d.ts

@@ -4,9 +4,13 @@ declare class ValidationError extends Error {
     expected: unknown;
     received: unknown;
     pathToError: string;
+    /** The same location as `pathToError`, as keys. */
+    path: readonly PropertyKey[];
+    /** The translation key of this failure, stable across locales. */
+    code: string;
     message: string;
     meta?: MetaContext;
-    constructor(expected: unknown, received: unknown, pathToError: string, message: string, meta?: MetaContext);
+    constructor(expected: unknown, received: unknown, pathToError: string, message: string, meta?: MetaContext, path?: readonly PropertyKey[], code?: string);
 }
 declare class BuildSchemaError extends Error {
 }

package/lib/exceptions.js

@@ -1,9 +1,9 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true});
 
 
-var _chunkFIDPCCCWjs = require('./chunk-FIDPCCCW.js');
+var _chunkZWFSAKQKjs = require('./chunk-ZWFSAKQK.js');
 
 
 
-exports.BuildSchemaError = _chunkFIDPCCCWjs.BuildSchemaError; exports.ValidationError = _chunkFIDPCCCWjs.ValidationError;
+exports.BuildSchemaError = _chunkZWFSAKQKjs.BuildSchemaError; exports.ValidationError = _chunkZWFSAKQKjs.ValidationError;
 //# sourceMappingURL=exceptions.js.map

package/lib/exceptions.mjs

@@ -1,7 +1,7 @@
 import {
   BuildSchemaError,
   ValidationError
-} from "./chunk-ZTCXXAKD.mjs";
+} from "./chunk-O2WD4JBG.mjs";
 export {
   BuildSchemaError,
   ValidationError