bupkis 0.18.1 → 0.18.2

package/dist/assertion/assertion-types.d.cts

@@ -1,1086 +0,0 @@
-/**
- * Core type definitions for the assertion system.
- *
- * This module defines all the fundamental types used throughout the assertion
- * framework, including assertion parts, implementation functions, parsed
- * values, and type inference utilities. These types enable type-safe assertion
- * creation and execution.
- *
- * @packageDocumentation
- *
- * @groupDescription Assertion Types
- * Types related to the implementation of assertions.
- * @groupDescription Internal Assertion Interfaces
- * Interfaces which define the structure of assertions and their components.
- * @groupDescription Assertion Implementation
- * Types related to the implementation of an assertion.
- */
-import { type NonEmptyTuple } from 'type-fest';
-import { type z } from 'zod';
-import type { DiffOptions } from "../diff.cjs";
-import type { StandardSchemaV1 } from "../standard-schema.cjs";
-import type { AsyncAssertions, SyncAssertions } from "./impl/index.cjs";
-/**
- * Union type representing any assertion, either synchronous or asynchronous.
- *
- * This type combines all possible assertion types into a single union for cases
- * where the synchronous/asynchronous nature is not known at compile time.
- *
- * @group Internal Assertion Types
- * @see {@link AnyAsyncAssertion} for async-specific assertions
- * @see {@link AnySyncAssertion} for sync-specific assertions
- */
-export type AnyAssertion = AnyAsyncAssertion | AnySyncAssertion;
-/**
- * Non-empty tuple type containing any assertions.
- *
- * Used to represent collections of assertions where at least one assertion must
- * be present.
- *
- * @group Internal Assertion Types
- * @see {@link AnyAssertion} for individual assertion types
- */
-export type AnyAssertions = NonEmptyTuple<AnyAssertion>;
-/**
- * Union type representing any asynchronous assertion.
- *
- * This includes both function-based and schema-based async assertions but
- * excludes synchronous assertions to maintain type safety.
- *
- * @group Internal Assertion Types
- * @see {@link AssertionFunctionAsync} for function-based async assertions
- * @see {@link AssertionSchemaAsync} for schema-based async assertions
- */
-export type AnyAsyncAssertion = AssertionAsync<any, any, any>;
-/**
- * Non-empty tuple type containing any asynchronous assertions.
- *
- * Used to represent collections of async assertions where at least one
- * assertion must be present.
- *
- * @see {@link AnyAsyncAssertion} for individual async assertion types
- */
-export type AnyAsyncAssertions = NonEmptyTuple<AnyAsyncAssertion>;
-/**
- * Union type representing any synchronous assertion.
- *
- * This includes both function-based and schema-based sync assertions but
- * excludes asynchronous assertions to maintain type safety.
- *
- * @group Internal Assertion Types
- * @see {@link AssertionFunctionSync} for function-based sync assertions
- * @see {@link AssertionSchemaSync} for schema-based sync assertions
- */
-export type AnySyncAssertion = AssertionSync<any, any, any>;
-/**
- * Non-empty tuple type containing any synchronous assertions.
- *
- * Used to represent collections of sync assertions where at least one assertion
- * must be present.
- *
- * @group Internal Assertion Types
- * @see {@link AnySyncAssertion} for individual sync assertion types
- */
-export type AnySyncAssertions = NonEmptyTuple<AnySyncAssertion>;
-/**
- * Interface for the base abstract `Assertion` class.
- *
- * This interface defines the contract for assertion instances, including
- * properties for assertion parts, implementation, slots, and methods for
- * parsing and executing assertions both synchronously and asynchronously.
- *
- * @group Internal Assertion Interfaces
- */
-export interface Assertion<Parts extends AssertionParts, Impl extends AssertionImpl<Parts>, Slots extends AssertionSlots<Parts>> {
-    /**
-     * Extracts phrase literals from this assertion for use in dispatch indexing.
-     *
-     * Returns phrases from the first phrase literal slot found (typically slot 1
-     * for subject-first assertions, or slot 0 for phrase-first assertions).
-     * Handles both single phrase literals and phrase literal choices.
-     *
-     * @returns Array of phrase strings for indexing, or empty array if none found
-     */
-    getIndexPhrases(): readonly string[];
-    /**
-     * Unique identifier for this assertion
-     */
-    readonly id: string;
-    /**
-     * The implementation function or schema for this assertion.
-     */
-    readonly impl: Impl;
-    /**
-     * The assertion parts used to create this assertion.
-     *
-     * Available at runtime for introspection.
-     */
-    readonly parts: Parts;
-    /**
-     * The slots derived from assertion parts for validation.
-     */
-    readonly slots: Slots;
-    /**
-     * Returns the string representation of this assertion.
-     *
-     * @privateRemarks
-     * The existence of this method suppresses
-     * `@typescript-eslint/no-base-to-string` lint errors.
-     */
-    toString(): string;
-}
-/**
- * Type for an object which represents a discrete asynchronous assertion.
- *
- * @group Internal Assertion Interfaces
- */
-export interface AssertionAsync<Parts extends AssertionParts = AssertionParts, Impl extends AssertionImplAsync<Parts> = AssertionImplAsync<Parts>, Slots extends AssertionSlots<Parts> = AssertionSlots<Parts>> extends Assertion<Parts, Impl, Slots> {
-    /**
-     * Execute the assertion implementation asynchronously.
-     *
-     * @param parsedValues Parameters for the assertion implementation
-     * @param args Raw parameters passed to `expectAsync()`
-     * @param stackStartFn Function to use as stack start for error reporting
-     * @param parseResult Optional parse result containing cached validation data
-     */
-    executeAsync(parsedValues: ParsedValues<Parts>, args: unknown[], stackStartFn: (...args: any[]) => any, parseResult?: ParsedResult<Parts>): Promise<void>;
-    /**
-     * Parses raw arguments asynchronously against this assertion's slots to
-     * determine if they match this assertion.
-     *
-     * @param args Raw arguments provided to `expectAsync()`
-     * @returns Result of parsing attempt
-     */
-    parseValuesAsync<Args extends readonly unknown[]>(args: Args): Promise<ParsedResult<Parts>>;
-}
-/**
- * Object which may be returned from assertion function implementations to
- * provide better failure reporting to the end-user.
- *
- * @group Assertion Creation
- */
-export interface AssertionFailure {
-    /**
-     * The actual value or condition that was encountered
-     */
-    actual?: unknown;
-    /**
-     * Pre-computed diff string. When provided, this bypasses jest-diff entirely
-     * and is used as-is in the error output. Takes precedence over
-     * `formatActual`, `formatExpected`, and `diffOptions`.
-     *
-     * @example
-     *
-     * ```typescript
-     * return {
-     *   actual: myDate,
-     *   expected: otherDate,
-     *   diff: `  Expected: ${formatDate(otherDate)}\n  Actual:   ${formatDate(myDate)}`,
-     *   message: 'Dates are not on the same day',
-     * };
-     * ```
-     */
-    diff?: string;
-    /**
-     * Override default jest-diff options. Only used when `diff` is not provided.
-     *
-     * @see {@link https://npm.im/jest-diff | jest-diff} for available options
-     */
-    diffOptions?: DiffOptions;
-    /**
-     * The expected value or condition that was not met
-     */
-    expected?: unknown;
-    /**
-     * Custom formatter for the actual value in diff output. Only used when `diff`
-     * is not provided. The returned string is passed to jest-diff.
-     *
-     * @example
-     *
-     * ```typescript
-     * return {
-     *   actual: sortedActual,
-     *   expected: sortedExpected,
-     *   formatActual: (v) => `[sorted] ${inspect(v)}`,
-     *   formatExpected: (v) => `[sorted] ${inspect(v)}`,
-     * };
-     * ```
-     *
-     * @param value - The actual value to format
-     * @returns String representation for diff display
-     */
-    formatActual?: (value: unknown) => string;
-    /**
-     * Custom formatter for the expected value in diff output. Only used when
-     * `diff` is not provided. The returned string is passed to jest-diff.
-     *
-     * @param value - The expected value to format
-     * @returns String representation for diff display
-     */
-    formatExpected?: (value: unknown) => string;
-    /**
-     * A human-readable message describing the failure
-     */
-    message?: string | undefined;
-}
-/**
- * An async assertion with a function implementation.
- *
- * @group Internal Assertion Interfaces
- */
-export interface AssertionFunctionAsync<Parts extends AssertionParts, Impl extends AssertionImplFnAsync<Parts>, Slots extends AssertionSlots<Parts>> extends AssertionAsync<Parts, Impl, Slots> {
-    impl: Impl;
-}
-/**
- * A synchronous assertion with a function implementation.
- *
- * @group Internal Assertion Interfaces
- */
-export interface AssertionFunctionSync<Parts extends AssertionParts, Impl extends AssertionImplFnSync<Parts>, Slots extends AssertionSlots<Parts>> extends AssertionSync<Parts, Impl, Slots> {
-    impl: Impl;
-}
-/**
- * Any type of assertion implementation.
- *
- * @group Assertion Implementation
- */
-export type AssertionImpl<Parts extends AssertionParts> = AssertionImplAsync<Parts> | AssertionImplSync<Parts>;
-/**
- * Union type representing any async assertion implementation.
- *
- * This encompasses both function-based and schema-based implementations for
- * asynchronous assertions, providing a type-safe way to handle async assertion
- * logic including Standard Schema validators.
- *
- * @template Parts - The assertion parts defining the structure
- * @group Assertion Implementation
- * @see {@link AssertionImplFnAsync} for function-based async implementations
- * @see {@link AssertionImplSchemaAsync} for schema-based async implementations
- */
-export type AssertionImplAsync<Parts extends AssertionParts> = AssertionImplFnAsync<Parts> | AssertionImplSchemaAsync<Parts> | StandardSchemaV1;
-/**
- * The implementation of an assertion as an async function.
- *
- * An asynchronous implementation function that validates assertion arguments
- * and returns a Promise resolving to validation results. The function receives
- * parsed values from the assertion parts and can return various types
- * indicating validation success or failure.
- *
- * @template Parts - The assertion parts defining the structure
- * @param values - The parsed values corresponding to assertion parts
- * @returns Promise resolving to boolean indicating pass/fail, void for success,
- *   ZodType for dynamic validation, or AssertionFailure object for detailed
- *   error information
- * @group Assertion Implementation
- * @see {@link AssertionImplFnSync} for sync function implementations
- * @see {@link ParsedValues} for the input parameter structure
- */
-export type AssertionImplFnAsync<Parts extends AssertionParts> = (...values: ParsedValues<Parts>) => AssertionImplFnReturnType<Parts> | Promise<AssertionImplFnReturnType<Parts>>;
-/**
- * The return type of an assertion implementation function.
- *
- * Functions can return various types to indicate validation results, including
- * Standard Schema validators for dynamic validation.
- *
- * @group Assertion Implementation
- */
-export type AssertionImplFnReturnType<Parts extends AssertionParts> = AssertionFailure | AssertionParseRequest | boolean | StandardSchemaV1<ParsedSubject<Parts>> | void | z.ZodError | z.ZodType<ParsedSubject<Parts>>;
-/**
- * The implementation of an assertion as a sync function.
- *
- * A synchronous implementation function that validates assertion arguments and
- * returns validation results. The function receives parsed values from the
- * assertion parts and can return various types indicating validation success or
- * failure.
- *
- * @template Parts - The assertion parts defining the structure
- * @param values - The parsed values corresponding to assertion parts
- * @returns Boolean indicating pass/fail, void for success, ZodType for dynamic
- *   validation, or AssertionFailure object for detailed error information
- * @group Assertion Implementation
- * @see {@link AssertionImplFnAsync} for async function implementations
- * @see {@link ParsedValues} for the input parameter structure
- */
-export type AssertionImplFnSync<Parts extends AssertionParts> = (...values: ParsedValues<Parts>) => AssertionImplFnReturnType<Parts>;
-/**
- * Maps an {@link AssertionPart} to a parameter to an {@link AssertionImpl}.
- *
- * This omits {@link Phrase} parts, which are not received by the implementation.
- *
- * @group Assertion Implementation
- */
-export type AssertionImplPart<Part extends AssertionPart> = Part extends PhraseLiteral | PhraseLiteralChoice ? never : Part extends z.ZodPromise ? Promise<z.infer<Part>> : Part extends z.ZodType ? z.infer<Part> : Part extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<Part> : never;
-/**
- * Maps {@link AssertionParts} to their corresponding {@link AssertionImplPart}.
- *
- * @group Assertion Implementation
- */
-export type AssertionImplParts<Parts extends readonly AssertionPart[]> = Parts extends readonly [
-    infer First extends AssertionPart,
-    ...infer Rest extends readonly AssertionPart[]
-] ? readonly [AssertionImplPart<First>, ...AssertionImplParts<Rest>] : readonly [];
-/**
- * A Zod schema implementation created with createAsync() - potentially
- * asynchronous
- */
-/**
- * Type for an async assertion implementation using a Zod schema.
- *
- * This represents a branded Zod schema that validates the assertion subject
- * asynchronously. The schema must match the parsed subject type derived from
- * the assertion parts and is branded with 'async-schema' for compile-time type
- * safety.
- *
- * @template Parts - The assertion parts tuple defining the assertion structure
- * @group Assertion Implementation
- * @see {@link AssertionImplSchemaSync} for synchronous schema implementations
- * @see {@link AssertionImplFnAsync} for function-based async implementations
- * @see {@link ParsedSubject} for subject type derivation
- */
-export type AssertionImplSchemaAsync<Parts extends AssertionParts> = z.core.$ZodBranded<z.ZodType<ParsedSubject<Parts>>, 'async-schema'>;
-/**
- * Type for a synchronous assertion implementation using a Zod schema.
- *
- * This represents a branded Zod schema that validates the assertion subject
- * synchronously. The schema must match the parsed subject type derived from the
- * assertion parts and is branded with 'sync-schema' for compile-time type
- * safety.
- *
- * @template Parts - The assertion parts tuple defining the assertion structure
- * @group Assertion Implementation
- * @see {@link AssertionImplSchemaAsync} for asynchronous schema implementations
- * @see {@link AssertionImplFnSync} for function-based sync implementations
- * @see {@link ParsedSubject} for subject type derivation
- */
-export type AssertionImplSchemaSync<Parts extends AssertionParts> = z.core.$ZodBranded<z.ZodType<ParsedSubject<Parts>>, 'sync-schema'>;
-/**
- * Union type for all synchronous assertion implementations.
- *
- * This represents either a function-based or schema-based implementation for
- * synchronous assertions. Function implementations provide custom validation
- * logic, while schema implementations use Zod schemas or Standard Schema
- * validators.
- *
- * @template Parts - The assertion parts tuple defining the assertion structure
- * @group Assertion Implementation
- * @see {@link AssertionImplFnSync} for function-based implementations
- * @see {@link AssertionImplSchemaSync} for schema-based implementations
- * @see {@link AssertionImplAsync} for async implementation unions
- */
-export type AssertionImplSync<Parts extends AssertionParts> = AssertionImplFnSync<Parts> | AssertionImplSchemaSync<Parts> | StandardSchemaV1;
-/**
- * When you want to use a schema in an assertion implementation function against
- * some value that _isn't_ the subject, you can return this object and <span
- * class="bupkis">BUPKIS</span> will do it for you (with better diffs).
- *
- * Supports both Zod schemas and Standard Schema v1 compliant validators.
- *
- * @group Assertion Creation
- */
-export type AssertionParseRequest = {
-    subject: unknown;
-} & ({
-    asyncSchema: StandardSchemaV1 | z.ZodType;
-    schema?: never;
-} | {
-    asyncSchema?: never;
-    schema: StandardSchemaV1 | z.ZodType;
-});
-/**
- * Union type representing the fundamental building blocks of an assertion.
- *
- * An assertion part can be either a phrase (string literal or choice of
- * literals) that describes the natural language portion of the assertion, or a
- * schema (Zod or Standard Schema) that defines validation constraints for
- * assertion arguments.
- *
- * @example
- *
- * ```ts
- * // String literal phrase
- * type Part1 = 'to be a string';
- *
- * // String literal choice
- * type Part2 = ['to be', 'to equal'];
- *
- * // Zod schema for validation
- * type Part3 = z.ZodString;
- *
- * // Standard Schema for validation
- * type Part4 = StandardSchemaV1<string>;
- * ```
- *
- * @group Internal Assertion Types
- * @see {@link Phrase} for phrase-based parts
- * @see {@link AssertionParts} for complete assertion structure
- * @see {@link AssertionSlot} for compiled slot representation
- */
-export type AssertionPart = Phrase | StandardSchemaV1 | z.ZodType;
-/**
- * Non-empty tuple type representing the complete structure of an assertion.
- *
- * This defines the signature of an assertion by combining phrases (natural
- * language) and Zod schemas (validation constraints). The tuple must contain at
- * least one element and typically starts with a subject schema followed by
- * phrase literals and additional parameter schemas.
- *
- * @example
- *
- * ```ts
- * // Basic assertion: expect(value, 'to be a string')
- * type SimpleAssertion = ['to be a string'];
- *
- * // Parameterized assertion: expect(value, 'to be greater than', 5)
- * type ParametricAssertion = [z.number(), 'to be greater than', z.number()];
- *
- * // Choice-based assertion: expect(value, ['to be', 'to equal'], expected)
- * type ChoiceAssertion = [z.any(), ['to be', 'to equal'], z.any()];
- * ```
- *
- * @template Parts - Extends the base AssertionPart array with tuple constraints
- * @group Internal Assertion Types
- * @see {@link AssertionPart} for individual part types
- * @see {@link AssertionSlots} for compiled slot representation
- * @see {@link createAssertion} for assertion creation from parts
- */
-export type AssertionParts = readonly [Phrase, ...AssertionPart[]] | readonly [StandardSchemaV1 | z.ZodType, Phrase, ...AssertionPart[]];
-/**
- * Type-level mapping from assertion parts to their corresponding validation
- * slots.
- *
- * This recursive type processes each assertion part and converts it to a slot
- * that can be used for runtime validation. Phrase literals become branded
- * string schemas, while Zod types are preserved as-is. The resulting tuple may
- * contain `never` entries for invalid parts that should be filtered out.
- *
- * @example
- *
- * ```ts
- * // Input parts
- * type Parts = ['to be a string', z.number()];
- *
- * // Resulting slots (simplified)
- * type Slots = [PhraseLiteralSlot<'to be a string'>, z.ZodNumber];
- * ```
- *
- * @template Parts - The readonly array of assertion parts to process
- * @group Internal Assertion Types
- * @see {@link AssertionSlot} for individual slot type mapping
- * @see {@link AssertionSlots} for filtered and properly typed slot tuples
- * @see {@link NoNeverTuple} for filtering never entries
- */
-export type AssertionPartsToSlots<Parts extends readonly AssertionPart[]> = Parts extends readonly [
-    infer First extends AssertionPart,
-    ...infer Rest extends readonly AssertionPart[]
-] ? readonly [AssertionSlot<First>, ...AssertionPartsToSlots<Rest>] : readonly [];
-/**
- * An async assertion which is implemented using a Zod schema.
- *
- * @group Internal Assertion Interfaces
- */
-export interface AssertionSchemaAsync<Parts extends AssertionParts, Impl extends AssertionImplSchemaAsync<Parts>, Slots extends AssertionSlots<Parts>> extends AssertionAsync<Parts, Impl, Slots> {
-    impl: Impl;
-}
-/**
- * A synchronous assertion which is implemented using a Zod schema.
- *
- * @group Internal Assertion Interfaces
- */
-export interface AssertionSchemaSync<Parts extends AssertionParts, Impl extends AssertionImplSchemaSync<Parts>, Slots extends AssertionSlots<Parts>> extends AssertionSync<Parts, Impl, Slots> {
-    impl: Impl;
-}
-/**
- * Type-level mapping that converts an assertion part to its corresponding
- * validation slot.
- *
- * This maps each type of assertion part to a specific Zod schema that can be
- * used for runtime validation:
- *
- * - String literals become branded phrase literal slots
- * - String literal choices become branded phrase choice slots
- * - Zod types are preserved as-is
- * - Standard Schema validators become Zod types (see note below)
- * - Invalid parts become `never`
- *
- * **Important:** Standard Schema parts are typed as `z.ZodType` because at
- * runtime they are wrapped in `z.custom()` by `slotify`. This type reflects the
- * **runtime reality** rather than the input type. The wrapper allows slots to
- * use Zod's `.safeParse()` and `.def` properties uniformly, while the Standard
- * Schema's actual validation is called internally.
- *
- * **Order matters:** Must check `z.ZodType` before `StandardSchemaV1` because
- * Zod v4 implements Standard Schema v1, so all Zod types would match both.
- *
- * @example
- *
- * ```ts
- * // String literal -> branded slot
- * type Slot1 = AssertionSlot<'to be a string'>; // PhraseLiteralSlot<'to be a string'>
- *
- * // Choice -> branded choice slot
- * type Slot2 = AssertionSlot<['to be', 'to equal']>; // PhraseLiteralChoiceSlot<['to be', 'to equal']>
- *
- * // Zod type -> preserved
- * type Slot3 = AssertionSlot<z.ZodString>; // z.ZodString
- *
- * // Standard Schema -> wrapped at runtime
- * type Slot4 = AssertionSlot<v.string()>; // z.ZodType (generic, not specific wrapper type)
- * ```
- *
- * @template Part - The assertion part to convert to a slot
- * @group Internal Assertion Types
- * @see {@link PhraseLiteralSlot} for string literal slots
- * @see {@link PhraseLiteralChoiceSlot} for choice-based slots
- * @see {@link AssertionSlots} for complete slot tuples
- * @see `slotify` for the runtime transformation that wraps Standard Schema validators
- */
-export type AssertionSlot<Part extends AssertionPart> = Part extends string ? PhraseLiteralSlot<Part> : Part extends readonly [string, ...string[]] ? PhraseLiteralChoiceSlot<Part> : Part extends z.ZodType ? Part : Part extends StandardSchemaV1 ? z.ZodType : never;
-/**
- * Tuple type representing all validation slots derived from assertion parts.
- *
- * This type processes assertion parts to create a tuple of Zod schemas that can
- * be used for runtime argument validation. If the first part is a phrase, a
- * subject slot (`z.ZodUnknown`) is automatically prepended to accept the
- * assertion subject.
- *
- * The resulting tuple:
- *
- * 1. Has `never` entries filtered out to maintain proper tuple structure
- * 2. Will include an implicit subject slot {@link AssertionParts} with a
- *    {@link PhraseLiteral}/{@link PhraseLiteralChoice} in the first position.
- * 3. Contains branded slots for
- *    {@link PhraseLiteral PhraseLiterals}/{@link PhraseLiteralChoice PhraseLiteralChoices}
- *    to enable phrase matching; differentiates from a user-created
- *    {@link z.ZodLiteral ZodLiteral}.
- *
- * @example
- *
- * ```ts
- * // Phrase-first assertion gets subject slot
- * type Slots1 = AssertionSlots<['to be a string']>;
- * // Result: [z.ZodUnknown, PhraseLiteralSlot<'to be a string'>]
- *
- * // Schema-first assertion preserves structure
- * type Slots2 = AssertionSlots<[z.string(), 'to match', z.regexp()]>;
- * // Result: [z.ZodString, PhraseLiteralSlot<'to match'>, z.ZodRegExp]
- * ```
- *
- * @template Parts - The assertion parts to convert to slots
- * @group Internal Assertion Types
- * @see {@link AssertionSlot} for individual slot mapping
- * @see {@link AssertionPartsToSlots} for the underlying mapping logic
- * @see {@link NoNeverTuple} for never filtering
- */
-export type AssertionSlots<Parts extends AssertionParts = AssertionParts> = Parts extends readonly [
-    infer First extends AssertionPart,
-    ...infer _ extends AssertionParts
-] ? First extends PhraseLiteral | PhraseLiteralChoice ? NoNeverTuple<readonly [z.ZodUnknown, ...AssertionPartsToSlots<Parts>]> : NoNeverTuple<AssertionPartsToSlots<Parts>> : never;
-/**
- * An asynchronous assertion implemented using a Standard Schema v1 validator.
- *
- * This interface represents async assertions where the implementation is a
- * Standard Schema compliant validator that may perform asynchronous
- * validation.
- *
- * @template Parts - The assertion parts tuple defining structure
- * @template Impl - The Standard Schema implementation
- * @template Slots - The derived validation slots
- * @group Internal Assertion Interfaces
- */
-export interface AssertionStandardSchemaAsync<Parts extends AssertionParts, Impl extends StandardSchemaV1, Slots extends AssertionSlots<Parts>> extends AssertionAsync<Parts, Impl, Slots> {
-    impl: Impl;
-}
-/**
- * A synchronous assertion implemented using a Standard Schema v1 validator.
- *
- * This interface represents assertions where the implementation is a Standard
- * Schema compliant validator (from any library such as Valibot, ArkType,
- * etc.).
- *
- * @template Parts - The assertion parts tuple defining structure
- * @template Impl - The Standard Schema implementation
- * @template Slots - The derived validation slots
- * @group Internal Assertion Interfaces
- */
-export interface AssertionStandardSchemaSync<Parts extends AssertionParts, Impl extends StandardSchemaV1, Slots extends AssertionSlots<Parts>> extends AssertionSync<Parts, Impl, Slots> {
-    impl: Impl;
-}
-/**
- * A synchronous assertion of no specific implementation type.
- *
- * @group Internal Assertion Interfaces
- */
-export interface AssertionSync<Parts extends AssertionParts = AssertionParts, Impl extends AssertionImplSync<Parts> = AssertionImplSync<Parts>, Slots extends AssertionSlots<Parts> = AssertionSlots<Parts>> extends Assertion<Parts, Impl, Slots> {
-    /**
-     * Execute the assertion implementation synchronously.
-     *
-     * @param parsedValues Parameters for the assertion implementation
-     * @param args Raw parameters passed to `expectSync()`
-     * @param stackStartFn Function to use as stack start for error reporting
-     * @param parseResult Optional parse result containing cached validation data
-     */
-    execute(parsedValues: ParsedValues<Parts>, args: unknown[], stackStartFn: (...args: any[]) => any, parseResult?: ParsedResult<Parts>): void;
-    /**
-     * Parses raw arguments synchronously against this assertion's slots to
-     * determine if they match this assertion.
-     *
-     * @param args Raw arguments provided to `expectSync()`
-     * @returns Result of parsing attempt
-     */
-    parseValues<Args extends readonly unknown[]>(args: Args): ParsedResult<Parts>;
-}
-/**
- * The base structure for parsed assertion results.
- *
- * @group Internal Assertion Types
- */
-export interface BaseParsedResult<Parts extends AssertionParts> {
-    /**
-     * If success is `true`, then this will be `true` if all args matched the
-     * slots _and_ none of those args infer as `unknown` or `any`.
-     */
-    exactMatch?: boolean;
-    /**
-     * Present only if `success` is `true`. The parsed values mapped to the slots
-     * of an {@link Assertion}.
-     */
-    parsedValues?: ParsedValues<Parts>;
-    /**
-     * Whether the args were successfully parsed against the slots of an
-     * {@link Assertion}.
-     */
-    success: boolean;
-}
-/**
- * Type representing the collection of all builtin async assertions.
- *
- * This type represents the compile-time type of the `AsyncAssertions` constant,
- * providing type information for all async assertion implementations included
- * in the framework by default.
- *
- * @group Builtin Assertions
- * @see {@link AsyncAssertions} for the actual assertion implementations
- */
-export type BuiltinAsyncAssertions = typeof AsyncAssertions;
-/**
- * Type representing the collection of all builtin sync assertions.
- *
- * This type represents the compile-time type of the `SyncAssertions` constant,
- * providing type information for all synchronous assertion implementations
- * included in the framework by default.
- *
- * @group Builtin Assertions
- * @see {@link SyncAssertions} for the actual assertion implementations
- */
-export type BuiltinSyncAssertions = typeof SyncAssertions;
-/**
- * The main factory function for creating synchronous assertions.
- *
- * @group Core API
- */
-export interface CreateAssertionFn {
-    /**
-     * Create a synchronous `Assertion` from {@link AssertionParts | parts} and a
-     * Standard Schema validator.
-     *
-     * @template Parts Parts defining the shape of the assertion, including
-     *   Phrases and Zod schemas
-     * @template Impl Assertion implementation as a Standard Schema
-     * @template Slots Inferred slots based on the provided `Parts`
-     * @returns New `AssertionStandardSchemaSync` object
-     */
-    <const Parts extends AssertionParts, Impl extends StandardSchemaV1, Slots extends AssertionSlots<Parts>>(parts: Parts, impl: Impl): AssertionStandardSchemaSync<Parts, Impl, Slots>;
-    /**
-     * Create a synchronous `Assertion` from {@link AssertionParts | parts} and a
-     * {@link z.ZodType | Zod schema}.
-     *
-     * @template Parts Parts defining the shape of the assertion, including
-     *   Phrases and Zod schemas
-     * @template Impl Assertion implementation as a Zod schema
-     * @template Slots Inferred slots based on the provided `Parts`
-     * @returns New `AssertionSchemaSync` object
-     */
-    <const Parts extends AssertionParts, Impl extends RawAssertionImplSchemaSync<Parts>, Slots extends AssertionSlots<Parts>>(parts: Parts, impl: Impl): AssertionSchemaSync<Parts, AssertionImplSchemaSync<Parts>, Slots>;
-    /**
-     * Create a synchronous `Assertion` from {@link AssertionParts | parts} and an
-     * implementation function.
-     *
-     * @template Parts Parts defining the shape of the assertion, including
-     *   Phrases and Zod schemas
-     * @template Impl Assertion implementation as a function
-     * @template Slots Inferred slots based on the provided `Parts`
-     * @returns New `AssertionFunctionSync` object
-     */
-    <const Parts extends AssertionParts, Impl extends AssertionImplFnSync<Parts>, Slots extends AssertionSlots<Parts>>(parts: Parts, impl: Impl): AssertionFunctionSync<Parts, Impl, Slots>;
-}
-/**
- * The main factory function for creating asynchronous assertions.
- *
- * @group Core API
- */
-export interface CreateAsyncAssertionFn {
-    /**
-     * Create an async `Assertion` from {@link AssertionParts | parts} and a
-     * Standard Schema validator.
-     *
-     * @template Parts Parts defining the shape of the assertion, including
-     *   Phrases and Zod schemas
-     * @template Impl Assertion implementation as a Standard Schema
-     * @template Slots Inferred slots based on the provided `Parts`
-     * @returns New `AssertionStandardSchemaAsync` object
-     */
-    <const Parts extends AssertionParts, Impl extends StandardSchemaV1, Slots extends AssertionSlots<Parts>>(parts: Parts, impl: Impl): AssertionStandardSchemaAsync<Parts, Impl, Slots>;
-    /**
-     * Create an async {@link Assertion} from {@link AssertionParts | parts} and an
-     * {@link z.ZodType | Zod schema}.
-     *
-     * The Zod schema need not be async itself.
-     *
-     * @template Parts Parts defining the shape of the assertion, including
-     *   Phrases and Zod schemas
-     * @template Impl Assertion implementation as a Zod schema
-     * @template Slots Inferred slots based on the provided `Parts`
-     * @returns New `AssertionSchemaAsync` object
-     */
-    <const Parts extends AssertionParts, Impl extends RawAssertionImplSchemaAsync<Parts>, Slots extends AssertionSlots<Parts>>(parts: Parts, impl: Impl): AssertionSchemaAsync<Parts, AssertionImplSchemaAsync<Parts>, Slots>;
-    /**
-     * Create an async `Assertion` from {@link AssertionParts | parts} and an
-     * implementation function.
-     *
-     * @template Parts Parts defining the shape of the assertion, including
-     *   Phrases and Zod schemas
-     * @template Impl Assertion implementation as a function
-     * @template Slots Inferred slots based on the provided `Parts`
-     * @returns New `AssertionFunctionAsync` object
-     */
-    <const Parts extends AssertionParts, Impl extends AssertionImplFnAsync<Parts>, Slots extends AssertionSlots<Parts>>(parts: Parts, impl: Impl): AssertionFunctionAsync<Parts, Impl, Slots>;
-}
-/**
- * Utility type for parsed values that may be empty.
- *
- * This type processes assertion parts recursively to produce parsed values,
- * handling the case where no assertion parts are present (resulting in an empty
- * tuple). It uses `NoNeverTuple` to filter out `never` types that may arise
- * during the recursive processing.
- *
- * @template Parts - The assertion parts to process
- * @group Internal Assertion Types
- * @see {@link ParsedValues} for the standard parsed values type
- * @see {@link NoNeverTuple} for never-type filtering
- */
-export type MaybeEmptyParsedValues<Parts extends readonly AssertionPart[]> = NoNeverTuple<Parts extends readonly [
-    infer First extends AssertionPart,
-    ...infer Rest extends readonly AssertionPart[]
-] ? First extends PhraseLiteral | PhraseLiteralChoice ? readonly [
-    unknown,
-    AssertionImplPart<First>,
-    ...AssertionImplParts<Rest>
-] : readonly [AssertionImplPart<First>, ...AssertionImplParts<Rest>] : readonly []>;
-/**
- * Utility type that removes `never` entries from a tuple while preserving tuple
- * structure.
- *
- * This recursive type filters out `never` types from tuple types, which can
- * occur during type-level transformations. It maintains the readonly tuple
- * structure while removing invalid entries.
- *
- * @example
- *
- * ```ts
- * type WithNever = readonly [string, never, number, never];
- * type Filtered = NoNeverTuple<WithNever>; // readonly [string, number]
- *
- * type Empty = NoNeverTuple<readonly [never, never]>; // readonly []
- * type Mixed = NoNeverTuple<readonly [boolean, never, string]>; // readonly [boolean, string]
- * ```
- *
- * @template T - The readonly tuple type to filter
- * @group Utility Types
- * @see {@link AssertionPartsToSlots} for usage in slot processing
- * @see {@link AssertionSlots} for filtered slot tuples
- */
-export type NoNeverTuple<T extends readonly unknown[]> = T extends readonly [
-    infer First,
-    ...infer Rest
-] ? [First] extends [never] ? readonly [...NoNeverTuple<Rest>] : readonly [First, ...NoNeverTuple<Rest>] : readonly [];
-/**
- * Union type representing the result of parsing assertion arguments.
- *
- * This represents either a successful parse (containing validated arguments) or
- * a parse failure (indicating arguments don't match the assertion). Used by
- * `parseValues()` and `parseValuesAsync()` methods to communicate whether the
- * assertion can be executed with the given arguments.
- *
- * @example
- *
- * ```ts
- * // Successful parse
- * const success: ParsedResult<Parts> = {
- *   success: true,
- *   exactMatch: true,
- *   parsedValues: [subject, ...params],
- * };
- *
- * // Parse failure
- * const failure: ParsedResult<Parts> = {
- *   success: false,
- * };
- * ```
- *
- * @template Parts - The assertion parts tuple defining expected structure
- * @group Internal Assertion Types
- * @see {@link ParsedResultSuccess} for successful parse results
- * @see {@link ParsedResultFailure} for failed parse results
- * @see {@link AssertionSync.parseValues} and {@link AssertionAsync.parseValuesAsync} for usage context
- */
-export type ParsedResult<Parts extends AssertionParts = AssertionParts> = ParsedResultFailure | ParsedResultSuccess<Parts>;
-/**
- * Interface representing a failed argument parsing attempt.
- *
- * When assertion arguments don't match the expected slots (wrong number of
- * arguments, type mismatches, phrase literal mismatches), parsing fails and
- * returns this interface. The assertion cannot be executed with the provided
- * arguments.
- *
- * @group Internal Assertion Types
- * @see {@link ParsedResultSuccess} for successful parsing results
- * @see {@link BaseParsedResult} for shared result properties
- */
-export interface ParsedResultFailure extends BaseParsedResult<never> {
-    exactMatch?: never;
-    parsedValues?: never;
-    success: false;
-}
-/**
- * Interface representing a successful argument parsing attempt.
- *
- * When assertion arguments successfully match the expected slots, this
- * interface contains the validated arguments and metadata about the match
- * quality. The assertion can be executed using the `parsedValues`.
- *
- * @template Parts - The assertion parts tuple defining the expected structure
- * @group Internal Assertion Types
- * @see {@link ParsedResultFailure} for failed parsing results
- * @see {@link BaseParsedResult} for shared result properties
- */
-export interface ParsedResultSuccess<Parts extends AssertionParts> extends BaseParsedResult<Parts> {
-    exactMatch: boolean;
-    parsedValues: ParsedValues<Parts>;
-    /**
-     * Optional cached subject validation result for optimized schema assertions.
-     * When present, indicates that subject validation was already performed
-     * during parseValues() and doesn't need to be repeated in execute().
-     *
-     * Supports both Zod errors and Standard Schema issues.
-     */
-    subjectValidationResult?: {
-        data: any;
-        success: true;
-    } | {
-        error: z.ZodError;
-        success: false;
-    } | {
-        issues: ReadonlyArray<StandardSchemaV1.Issue>;
-        success: false;
-    };
-    success: true;
-}
-/**
- * Type extracting the subject (first argument) from parsed assertion values.
- *
- * This utility type extracts the subject of an assertion from the parsed values
- * tuple. The subject is always the first element and represents the value being
- * tested by the assertion.
- *
- * @example
- *
- * ```ts
- * // For assertion: expect(value, 'to be a string')
- * type Subject = ParsedSubject<Parts>; // typeof value
- *
- * // For assertion: expect(42, 'to be greater than', 10)
- * type NumericSubject = ParsedSubject<NumericParts>; // number
- * ```
- *
- * @template Parts - The assertion parts tuple defining the assertion structure
- * @group Internal Assertion Types
- * @see {@link ParsedValues} for the complete parsed values tuple
- * @see {@link AssertionImpl} for how subjects are used in implementations
- */
-export type ParsedSubject<Parts extends AssertionParts> = ParsedValues<Parts> extends readonly [infer Subject, ...any[]] ? Subject : never;
-/**
- * Tuple type containing validated arguments for assertion execution.
- *
- * This represents the final processed arguments that will be passed to an
- * assertion implementation function. The tuple contains the subject (first)
- * followed by any additional parameters, with phrase literals filtered out
- * since they're not passed to implementations.
- *
- * @example
- *
- * ```ts
- * // For assertion: expect(value, 'to be greater than', 10)
- * // ParsedValues = [typeof value, 10] (phrase literal removed)
- *
- * // For assertion: expect(obj, 'to satisfy', shape)
- * // ParsedValues = [typeof obj, typeof shape]
- * ```
- *
- * @template Parts - The assertion parts tuple defining the expected structure
- * @group Internal Assertion Types
- * @see {@link ParsedSubject} for extracting just the subject
- * @see {@link MaybeEmptyParsedValues} for the underlying value processing
- * @see {@link AssertionImpl} for how these values are consumed
- */
-export type ParsedValues<Parts extends AssertionParts = AssertionParts> = 0 extends 1 & Parts ? readonly unknown[] : MaybeEmptyParsedValues<Parts> extends readonly [] ? never : MaybeEmptyParsedValues<Parts>;
-/**
- * Union type combining both phrase literal types.
- *
- * A phrase represents the natural language portion of an assertion that
- * describes the expected behavior. It can be either a single string literal or
- * a choice between multiple string literals.
- *
- * @example
- *
- * ```ts
- * // Single phrase literal
- * type Phrase1 = PhraseLiteral; // "to be a string"
- *
- * // Choice phrase literal
- * type Phrase2 = PhraseLiteralChoice; // ["to be", "to equal"]
- * ```
- *
- * @group Assertion Creation
- * @see {@link PhraseLiteral} for single string phrases
- * @see {@link PhraseLiteralChoice} for choice-based phrases
- * @see {@link AssertionPart} for how phrases fit into assertion structure
- */
-export type Phrase = PhraseLiteral | PhraseLiteralChoice;
-/**
- * Type representing a single phrase literal string.
- *
- * This is a string literal that `expect()` will match exactly in its parameter
- * position. The phrase describes the natural language expectation for the
- * assertion. If the first item in assertion parts is a phrase literal, a
- * subject slot (`unknown`) is automatically added.
- *
- * Phrases cannot start with "not " as this would conflict with negation logic.
- *
- * @example
- *
- * ```ts
- * // Valid phrase literals
- * type Phrase1 = 'to be a string';
- * type Phrase2 = 'to have length';
- * type Phrase3 = 'to contain';
- *
- * // Usage in assertion
- * createAssertion(['to be a string'], z.string());
- * // expect(value, 'to be a string') ✓
- * ```
- *
- * @group Assertion Creation
- * @see {@link PhraseLiteralChoice} for multi-option phrases
- * @see {@link PhraseLiteralSlot} for compiled slot representation
- * @see {@link AssertionPart} for how phrases fit into assertion structure
- */
-export type PhraseLiteral = string;
-/**
- * Type representing a choice between multiple phrase literals.
- *
- * This allows an assertion to accept any of several equivalent phrase options,
- * providing flexibility in natural language expression. The type is a non-empty
- * readonly tuple of strings.
- *
- * @example
- *
- * ```ts
- * // Choice phrase literal
- * type Choice = ['to be', 'to equal'];
- *
- * // Usage in assertion
- * createAssertion(
- *   [z.any(), ['to be', 'to equal'], z.any()],
- *   (subject, expected) => subject === expected,
- * );
- *
- * // Both work:
- * // expect(value, 'to be', expected) ✓
- * // expect(value, 'to equal', expected) ✓
- * ```
- *
- * @group Assertion Creation
- * @see {@link PhraseLiteral} for single phrase options
- * @see {@link PhraseLiteralChoiceSlot} for compiled slot representation
- * @see {@link AssertionPart} for how phrases fit into assertion structure
- */
-export type PhraseLiteralChoice = NonEmptyTuple<string>;
-/**
- * Branded Zod type representing a compiled choice phrase slot.
- *
- * This is the runtime representation of a {@link PhraseLiteralChoice} that has
- * been processed into a validation slot. It includes metadata about the
- * available choice values for runtime phrase matching.
- *
- * @privateRemarks
- * The `__values` property might be redundant since values should be derivable
- * from the ZodLiteral metadata, but it provides type-level access to the
- * choices.
- * @template H - The readonly tuple of string choices
- * @group Internal Assertion Types
- * @see {@link PhraseLiteralChoice} for the source type
- * @see {@link PhraseLiteralSlot} for single phrase slots
- * @see {@link AssertionSlot} for slot type mapping
- */
-export type PhraseLiteralChoiceSlot<H extends readonly [string, ...string[]]> = z.core.$ZodBranded<z.ZodType, 'string-literal'> & {
-    readonly __values: H;
-};
-/**
- * Branded Zod type representing a compiled phrase literal slot.
- *
- * This is the runtime representation of a {@link PhraseLiteral} that has been
- * processed into a validation slot. The slot is branded with 'string-literal'
- * to distinguish it from regular string validation during assertion matching.
- *
- * @privateRemarks
- * This type might be redundant since the value should be derivable from the
- * ZodLiteral's value property, but it provides type-level access to the
- * literal.
- * @template T - The string literal type
- * @group Internal Assertion Types
- * @see {@link PhraseLiteral} for the source type
- * @see {@link PhraseLiteralChoiceSlot} for choice phrase slots
- * @see {@link AssertionSlot} for slot type mapping
- */
-export type PhraseLiteralSlot<T extends string> = z.core.$ZodBranded<z.ZodLiteral<T>, 'string-literal'>;
-/**
- * Type for a raw (unbranded) asynchronous schema assertion implementation.
- *
- * This represents a standard Zod schema without branding that validates the
- * assertion subject synchronously. Unlike {@link AssertionImplSchemaAsync}, this
- * type is not branded and represents the underlying schema before it is
- * processed by the assertion creation system.
- *
- * @template Parts The tuple defining the assertion structure
- * @useDeclaredType
- * @group Assertion Implementation
- * @see {@link AssertionImplSchemaAsync} for the branded version
- * @see {@link ParsedSubject} for subject type derivation
- */
-export type RawAssertionImplSchemaAsync<Parts extends AssertionParts> = z.ZodType<ParsedSubject<Parts>>;
-/**
- * Type for a raw (unbranded) synchronous schema assertion implementation.
- *
- * This represents a standard Zod schema without branding that validates the
- * assertion subject synchronously. Unlike {@link AssertionImplSchemaSync}, this
- * type is not branded and represents the underlying schema before it is
- * processed by the assertion creation system.
- *
- * @template Parts The tuple defining the assertion structure
- * @useDeclaredType
- * @group Assertion Implementation
- * @see {@link AssertionImplSchemaSync} for the branded version
- * @see {@link ParsedSubject} for subject type derivation
- */
-export type RawAssertionImplSchemaSync<Parts extends AssertionParts> = z.ZodType<ParsedSubject<Parts>>;
-//# sourceMappingURL=assertion-types.d.ts.map