bupkis 0.5.1 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [0.6.0](https://github.com/boneskull/bupkis/compare/bupkis-v0.5.1...bupkis-v0.6.0) (2025-09-22)
+
+
+### Features
+
+* **assertions:** create expectAsync.it ([fb4db5a](https://github.com/boneskull/bupkis/commit/fb4db5afc4d2ab6e0affc073ab03c670264a3bbd))
+
+
+### Bug Fixes
+
+* **assertions:** "map/set to have size greater than" now expects nonnegative int size ([2355ba0](https://github.com/boneskull/bupkis/commit/2355ba0494baeb5050024e6fadd8a28a900f5dcc))
+* **assertions:** narrow some schemas ([fc0b708](https://github.com/boneskull/bupkis/commit/fc0b7086ba898a43f3c9558aff6ede30723e38c6))
+
 ## [0.5.1](https://github.com/boneskull/bupkis/compare/bupkis-v0.5.0...bupkis-v0.5.1) (2025-09-18)
 
 

package/README.md

@@ -1,8 +1,8 @@
 <p align="center">
-  <img src="./site/media/bupkis-logo-512.png" width="512px" align="center" alt="BUPKIS: The Glory of Certainty"/>
+  <a href="/"><img src="./site/media/bupkis-logo-512.png" width="512px" align="center" alt="BUPKIS: The Glory of Certainty"/></a>
   <h1 align="center"><span class="bupkis">⁓ BUPKIS ⁓<span></h1>
   <p align="center">
-    Uncommonly extensible assertions for the beautiful people
+    <em>“Uncommonly Extensible Assertions for The Beautiful People”</em>
     <br/>
     <small>by <a href="https://github.com/boneskull" title="@boneskull on GitHub">@boneskull</a></small>
   </p>
@@ -23,7 +23,7 @@
 
 Look, we're ~~old~~ ~~wizened~~ ~~experienced~~ knowledgeable and we've written a lot of tests. We've used a lot of assertion libraries. There are ones we prefer and ones we don't.
 
-But none of them do quite what _BUPKIS_ does. We want an assertion library that prioritizes:
+But none of them do quite what **BUPKIS** does. We want an assertion library that prioritizes:
 
 - Type safety
 - Uncompromisable extensibility
@@ -33,7 +33,7 @@ We can think of several that tick two-thirds of those boxes! But _we demand the
 
 > ⚠️ **Caution!**
 >
-> Assertion libraries tend come in two flavors: chainable or stiff & traditional. But because these styles are likely _familiar_ to you, you may hate _BUPKIS_.
+> Assertion libraries tend come in two flavors: chainable or stiff & traditional. But because these styles are likely _familiar_ to you, you may hate **BUPKIS**.
 >
 > We _want_ you to like it, yes. But if you don't, we're content with just making our point and asking the following favor of the reader:
 >
@@ -43,9 +43,9 @@ The following is a brief overview of the design choices we made to serve these g
 
 ### Natural Language Assertions
 
-In _BUPKIS_, "natural language" is the means to the end of "a small API surface".
+In **BUPKIS**, "natural language" is the means to the end of "a small API surface".
 
-When you're using _BUPKIS_, you **don't** write this:
+When you're using **BUPKIS**, you **don't** write this:
 
 ```js
 expect(actual).toEqual(expected);
@@ -73,7 +73,7 @@ If another assertion library wants you to write:
 expect(actual).to.be.a('string');
 ```
 
-Then _BUPKIS_ wants you to write:
+Then **BUPKIS** wants you to write:
 
 ```js
 expect(actual, 'to be a string');
@@ -81,7 +81,7 @@ expect(actual, 'to be a string');
 expect(actual, 'to be an string');
 ```
 
-Can't remember the phrase? Did you forget a word or make a typo? Maybe you also forgot **_BUPKIS_ is type-safe?!** You'll get a nice squiggly for your trouble.
+Can't remember the phrase? Did you forget a word or make a typo? Maybe you also forgot \***\*BUPKIS** is type-safe?!\*\* You'll get a nice squiggly for your trouble.
 
 This isn't black magic. It ain't no _cauldron_. We're not just _throwing rat tails and `string`s into a function and stirring that shit up._
 
@@ -95,9 +95,9 @@ You may wonder how this could this be anything _but_ loosey-goosey _senselessnes
 
 To formalize the conventions at a high level:
 
-- The first parameter to a _BUPKIS_ assertion is always the _subject_ ([def.](https://bupkis.zip/documents/Reference.Glossary_of_Terms#subject)).
+- The first parameter to a **BUPKIS** assertion is always the _subject_ ([def.](https://bupkis.zip/documents/Reference.Glossary_of_Terms#subject)).
 
-- The "string" part of a _BUPKIS_ assertion is known as a _phrase_. Every expectation will contain _at minimum_ one (1) phrase. As you can see from the above "to be a string" example, phrases often have aliases.
+- The "string" part of a **BUPKIS** assertion is known as a _phrase_. Every expectation will contain _at minimum_ one (1) phrase. As you can see from the above "to be a string" example, phrases often have aliases.
 
 - Assertions may have multiple phrases or parameters, but the simplest assertions always look like this:
 
@@ -155,7 +155,7 @@ To formalize the conventions at a high level:
 
 ### Custom Assertions Built With Zod
 
-[Zod][] is a popular object validation library which does some heavy lifting for _BUPKIS_—most of the built-in assertions are implemented using Zod schemas. And so _BUPKIS_ extends this capability to you.
+[Zod][] is a popular object validation library which does some heavy lifting for **BUPKIS**—most of the built-in assertions are implemented using Zod schemas. And so **BUPKIS** extends this capability to you.
 
 An example will be illuminating. What follows is a ~~stupid~~ ~~quick~~ _stupid_ example of a creating and "registering" a basic assertion _which can be invoked using two different phrases_:
 
@@ -189,7 +189,7 @@ expect('skiball lavatory', 'to be a string');
 
 ### Excruciating Type Safety
 
-We have tried to make _BUPKIS_ is as type-safe as possible. To be clear, _that is pretty damn possible_. This means:
+We have tried to make **BUPKIS** is as type-safe as possible. To be clear, _that is pretty damn possible_. This means:
 
 - Every built-in assertion is fully type-safe and is declared as an overload for `expect()` or `expectAsync()`.
 - Every _custom_ assertion is _also_ fully type-safe and is declared as an overload for `expect()` or `expectAsync()` (as returned from `use()`)
@@ -201,15 +201,15 @@ We have tried to make _BUPKIS_ is as type-safe as possible. To be clear, _that i
 
 **Node.js**: ^20.19.0, ^22.12.0, >=23
 
-_BUPKIS_ has a peer dependency on [Zod][] v4+, but will install it as an optional dependency if you are not already using it.
+**BUPKIS** has a peer dependency on [Zod][] v4+, but will install it as an optional dependency if you are not already using it.
 
-_BUPKIS_ ships as a dual CJS/ESM package.
+**BUPKIS** ships as a dual CJS/ESM package.
 
-> Disclaimer: _BUPKIS_ has been designed to run on Node.js in a development environment. Anyone attempting to deploy _BUPKIS_ to some server somewhere will get what is coming to them.
+> Disclaimer: **BUPKIS** has been designed to run on Node.js in a development environment. Anyone attempting to deploy **BUPKIS** to some server somewhere will get what is coming to them.
 
 ## Installation
 
-```bash
+```sh
 npm install bupkis -D
 ```
 
@@ -221,14 +221,14 @@ npm install bupkis -D
 
 ## Acknowledgements
 
-- [Unexpected][] is the main inspiration for _BUPKIS_. However, creating types for this library was exceedingly difficult (and was in fact the first thing we tried). Despite that drawback, we found it exquisitely usable.
-- [Zod][] is a popular object validation library upon which _BUPKIS_ builds many of its own assertions.
+- [Unexpected][] is the main inspiration for **BUPKIS**. However, creating types for this library was exceedingly difficult (and was in fact the first thing we tried). Despite that drawback, we found it exquisitely usable.
+- [Zod][] is a popular object validation library upon which **BUPKIS** builds many of its own assertions.
 - [fast-check][]: Thanks to Nicholas Dubien for this library. There is **no better library** for an assertion library to use to test itself! Well, besides itself, we mean. How about _in addition to_ itself? Yes. Thank you!
 - [tshy][] from Isaac Schlueter. Thanks for making dual ESM/CJS packages easy and not too fancy.
 - [TypeDoc][] it really documents the hell out of TypeScript projects.
 - [@cjihrig](https://github.com/cjihrig) and other Node.js contributors for the thoughtfulness put into [`node:test`](https://nodejs.org/api/test.html) that make it my current test-runner-of-choice.
 
-## Why is it called _BUPKIS_?
+## Why is it called **BUPKIS**?
 
 TODO: think of good reason and fill in later
 

package/dist/commonjs/assertion/assertion-types.d.ts

@@ -7,15 +7,23 @@
  * 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/v4';
+import { z } from 'zod/v4';
 /**
  * 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
  */
@@ -26,6 +34,7 @@ export type AnyAssertion = AnyAsyncAssertion | AnySyncAssertion;
  * 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>;
@@ -35,6 +44,7 @@ export type AnyAssertions = NonEmptyTuple<AnyAssertion>;
  * 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
  */
@@ -54,6 +64,7 @@ export type AnyAsyncAssertions = NonEmptyTuple<AnyAsyncAssertion>;
  * 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
  */
@@ -64,6 +75,7 @@ export type AnySyncAssertion = AssertionFunctionSync<any, any, any> | 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>;
@@ -73,6 +85,8 @@ export type AnySyncAssertions = NonEmptyTuple<AnySyncAssertion>;
  * 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>> {
     readonly id: string;
@@ -95,6 +109,11 @@ export interface Assertion<Parts extends AssertionParts, Impl extends AssertionI
      */
     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.
@@ -114,6 +133,12 @@ export interface AssertionAsync<Parts extends AssertionParts = AssertionParts, I
      */
     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
@@ -130,18 +155,24 @@ export interface AssertionFailure {
 }
 /**
  * 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>;
 /**
@@ -152,6 +183,7 @@ export type AssertionImpl<Parts extends AssertionParts> = AssertionImplAsync<Par
  * logic.
  *
  * @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
  */
@@ -169,12 +201,15 @@ export type AssertionImplAsync<Parts extends AssertionParts> = AssertionImplFnAs
  * @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.
+ *
+ * @group Assertion Implementation
  */
 export type AssertionImplFnReturnType<Parts extends AssertionParts> = AssertionFailure | boolean | void | z.ZodError | z.ZodType<ParsedSubject<Parts>>;
 /**
@@ -189,6 +224,7 @@ export type AssertionImplFnReturnType<Parts extends AssertionParts> = AssertionF
  * @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
  */
@@ -197,10 +233,14 @@ export type AssertionImplFnSync<Parts extends AssertionParts> = (...values: Pars
  * 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>> : z.infer<Part>;
 /**
  * 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,
@@ -219,6 +259,7 @@ export type AssertionImplParts<Parts extends readonly AssertionPart[]> = Parts e
  * 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
@@ -233,6 +274,7 @@ export type AssertionImplSchemaAsync<Parts extends AssertionParts> = z.core.$Zod
  * 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
@@ -246,18 +288,7 @@ export type AssertionImplSchemaSync<Parts extends AssertionParts> = z.core.$ZodB
  * logic, while schema implementations use Zod schemas for validation.
  *
  * @template Parts - The assertion parts tuple defining the assertion structure
- * @see {@link AssertionImplFnSync} for function-based implementations
- * @see {@link AssertionImplSchemaSync} for schema-based implementations
- * @see {@link AssertionImplAsync} for async implementation unions
- */
-/**
- * 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 for validation.
- *
- * @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
@@ -283,6 +314,7 @@ export type AssertionImplSync<Parts extends AssertionParts> = AssertionImplFnSyn
  * type Part3 = z.ZodString;
  * ```
  *
+ * @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
@@ -310,6 +342,7 @@ export type AssertionPart = Phrase | z.ZodType;
  * ```
  *
  * @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
@@ -335,6 +368,7 @@ export type AssertionParts = NonEmptyTuple<AssertionPart>;
  * ```
  *
  * @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
@@ -343,9 +377,19 @@ export type AssertionPartsToSlots<Parts extends readonly AssertionPart[]> = Part
     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;
 }
@@ -375,6 +419,7 @@ export interface AssertionSchemaSync<Parts extends AssertionParts, Impl extends
  * ```
  *
  * @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
@@ -411,6 +456,7 @@ export type AssertionSlot<Part extends AssertionPart> = Part extends string ? Ph
  * ```
  *
  * @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
@@ -419,6 +465,11 @@ export type AssertionSlots<Parts extends AssertionParts = AssertionParts> = Part
     infer First extends AssertionPart,
     ...infer _ extends AssertionParts
 ] ? First extends PhraseLiteral | PhraseLiteralChoice ? NoNeverTuple<readonly [z.ZodUnknown, ...AssertionPartsToSlots<Parts>]> : NoNeverTuple<AssertionPartsToSlots<Parts>> : never;
+/**
+ * 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.
@@ -440,6 +491,8 @@ export interface AssertionSync<Parts extends AssertionParts = AssertionParts, Im
 }
 /**
  * The base structure for parsed assertion results.
+ *
+ * @group Internal Assertion Types
  */
 export interface BaseParsedResult<Parts extends AssertionParts> {
     /**
@@ -458,6 +511,66 @@ export interface BaseParsedResult<Parts extends AssertionParts> {
      */
     success: boolean;
 }
+/**
+ * The main factory function for creating synchronous assertions.
+ *
+ * @group Core API
+ */
+export interface CreateAssertionFn {
+    /**
+     * 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, metadata?: AssertionMetadata): 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, metadata?: AssertionMetadata): AssertionFunctionSync<Parts, Impl, Slots>;
+}
+/**
+ * The main factory function for creating asynchronous assertions.
+ *
+ * @group Core API
+ */
+export interface CreateAsyncAssertionFn {
+    /**
+     * 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, metadata?: AssertionMetadata): 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, metadata?: AssertionMetadata): AssertionFunctionAsync<Parts, Impl, Slots>;
+}
 /**
  * Utility type for parsed values that may be empty.
  *
@@ -467,6 +580,7 @@ export interface BaseParsedResult<Parts extends AssertionParts> {
  * 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
  */
@@ -497,6 +611,7 @@ export type MaybeEmptyParsedValues<Parts extends readonly AssertionPart[]> = NoN
  * ```
  *
  * @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
  */
@@ -529,6 +644,7 @@ export type NoNeverTuple<T extends readonly unknown[]> = T extends readonly [
  * ```
  *
  * @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
@@ -542,6 +658,7 @@ export type ParsedResult<Parts extends AssertionParts = AssertionParts> = Parsed
  * 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
  */
@@ -558,6 +675,7 @@ export interface ParsedResultFailure extends BaseParsedResult<never> {
  * 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
  */
@@ -596,6 +714,7 @@ export interface ParsedResultSuccess<Parts extends AssertionParts> extends BaseP
  * ```
  *
  * @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
  */
@@ -619,6 +738,7 @@ export type ParsedSubject<Parts extends AssertionParts> = ParsedValues<Parts> ex
  * ```
  *
  * @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
@@ -641,6 +761,7 @@ export type ParsedValues<Parts extends AssertionParts = AssertionParts> = MaybeE
  * 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
@@ -669,6 +790,7 @@ export type Phrase = PhraseLiteral | PhraseLiteralChoice;
  * // 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
@@ -698,6 +820,7 @@ export type PhraseLiteral = string;
  * // 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
@@ -715,6 +838,7 @@ export type PhraseLiteralChoice = NonEmptyTuple<string>;
  * 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
@@ -734,11 +858,27 @@ export type PhraseLiteralChoiceSlot<H extends readonly [string, ...string[]]> =
  * 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.
  *
@@ -749,8 +889,38 @@ export type PhraseLiteralSlot<T extends string> = z.core.$ZodBranded<z.ZodLitera
  *
  * @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>>;
+/**
+ * Metadata associated with an assertion, for internal use by documentation
+ * tooling.
+ *
+ * @private
+ */
+export declare const AssertionMetadataSchema: z.ZodObject<{
+    anchor: z.ZodString;
+    category: z.ZodEnum<{
+        object: "object";
+        function: "function";
+        date: "date";
+        promise: "promise";
+        error: "error";
+        collections: "collections";
+        equality: "equality";
+        numeric: "numeric";
+        other: "other";
+        primitives: "primitives";
+        strings: "strings";
+    }>;
+    redirectName: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+/**
+ * {@inheritDoc AssertionMetadataSchema}
+ *
+ * @private
+ */
+export type AssertionMetadata = z.infer<typeof AssertionMetadataSchema>;
 //# sourceMappingURL=assertion-types.d.ts.map