bupkis 0.0.2 → 0.1.1

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [0.1.1](https://github.com/boneskull/bupkis/compare/bupkis-v0.1.0...bupkis-v0.1.1) (2025-09-09)
+
+
+### Bug Fixes
+
+* actually build before publish ([996c28e](https://github.com/boneskull/bupkis/commit/996c28e223ce488d07ea0b7633829ff25d510be3))
+
+## [0.1.0](https://github.com/boneskull/bupkis/compare/bupkis-v0.0.2...bupkis-v0.1.0) (2025-09-08)
+
+
+### Features
+
+* **use:** use() returns an object with a use() in it ([fb383d6](https://github.com/boneskull/bupkis/commit/fb383d6fb2f541085d2300664fe73b25c6249e42))
+
+
+### Bug Fixes
+
+* **package:** add description and homepage ([2ff82ea](https://github.com/boneskull/bupkis/commit/2ff82ea715280098f59612ba32da808308aced0e))
+
 ## [0.0.2](https://github.com/boneskull/bupkis/compare/bupkis-v0.0.1...bupkis-v0.0.2) (2025-09-07)
 
 

package/README.md

@@ -1,34 +1,51 @@
 <p align="center">
-  <img src="https://github.com/boneskull/bupkis/blob/main/assets/bupkis-logo-256.png" width="256px" align="center" alt="BUPKIS logo"/>
-  <h1 align="center"><em><span class="federo-caps">BUPKIS<span></em></h1>
+  <img src="./assets/bupkis-logo-512.png" width="512px" align="center" alt="BUPKIS logo"/>
+  <h1 align="center"><span class="twentieth-century-caps">⁓ BUPKIS ⁓<span></h1>
   <p align="center">
-    A well-typed and easily exensible <em>BDD-style</em> assertion library.
+    Uncommonly extensible assertions for the beautiful people
     <br/>
-    by <a href="https://github.com/boneskull">@boneskull</a>
+    <small>by <a href="https://github.com/boneskull">@boneskull</a></small>
   </p>
 </p>
 
+## Quick Links
+
+- [BUPKIS' Homepage][docs] (<https://bupkis.zip>)
+- [Assertion Reference][assertion-reference]
+- [Guide: Basic Usage][basic-usage]
+- [Guide: How to Create a Custom Assertion][create-a-custom-assertion]
+
 ## Motivation
 
+> "_Another_ assertion library? You cannot be serious. My test framework has its own assertions!"
+>
+> ‒sickos, probably
+
 Look, I'm ~~old~~ ~~wizened~~ ~~experienced~~ knowledegable and I've written a lot of tests. I've used a lot of assertion libraries. There are ones I prefer and ones I don't.
 
-But none of them do quite what _this_ does. The main goals of this library are:
+But none of them do quite what _BUPKIS_ does. I want an assertion library that prioritizes:
 
 - Type safety
-- Dead-simple creation of custom assertions
-- Minimal API surface
+- Uncompromisable extensibility
+- A small API surface
 
-A chainable API may provide type safety. But it seems to _guarantee_ implementing a custom assertion will be complicated. The API surface is necessarily a combinatoric explosion of methods.
+I can think of several that tick two-thirds of those boxes! But _I demand the total package_ (And You Should Too).
 
-> [!WARNING]
+> ⚠️ **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_.
+>
+> I _want_ you to like it, yes. But if you don't, I'm content with just making my point and asking the following favor of the reader:
 >
-> Because chainable APIs are familiar, you may hate _BUPKIS_ once you see some examples. You don't have to use it, but please: _don't confuse familiarity with usability_.
+> **Do not confuse _familiarity_ with _usability_.**
 
-To achieve these goals, I've adopted the following design principles:
+The following is a brief overview of the design choices We made to serve these goals.
 
-### Natural-Language Assertions
+### Natural Language Assertions
 
-In `bupkis` (stylized as "_BUPKIS_"), you **don't** write this:
+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:
 
 ```js
 expect(actual).toEqual(expected);
@@ -50,7 +67,7 @@ expect(actual, 'is equal to', expected);
 expect(actual, 'to strictly equal', expected);
 ```
 
-If Chai wants you to write:
+If another assertion library wants you to write:
 
 ```js
 expect(actual).to.be.a('string');
@@ -60,111 +77,150 @@ Then _BUPKIS_ wants you to write:
 
 ```js
 expect(actual, 'to be a string');
-// it is tolerant of poor/ironic grammar
+// it is tolerant of poor/ironic grammar, sometimes
 expect(actual, 'to be an string');
 ```
 
-Can't remember the string? 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.
 
-The "string" part of an expectation is known as a _phrase_. Every expectation will contain, at minimum, one phrase. As you can see from the above example, phrases often have aliases.
+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._
 
-You can negate just about any phrase:
+> "Preposterous! Codswallop!"
+>
+> ‒the reader and/or more sickos
 
-```js
-expect(actual, 'to be', expected);
-// did they not teach grammar in nerd school??
-expect(actual, 'not is', expected);
-
-expect(
-  () => throw new TypeError('aww, shucks'),
-  'to throw a',
-  TypeError,
-  'not satisfying',
-  /gol durn/,
-);
-```
+You may wonder how this could this be anything _but_ loosey-goosey _senselessness_. On the contrary—we have _conventions_!
 
-### Custom Assertions
+#### Conventions of `expect()`
 
-In _BUPKIS_, custom assertions are _first-class citizens_. You can create your own assertions with minimal boilerplate. You don't have to learn a new API or a new DSL (maybe); you just use [Zod][]. _It's so easy, even a **archaic human** could do it!_
+To formalize the conventions at a high level:
 
-Read [Guide: How to Create a Custom Assertion](https://boneskull.github.io/bupkis/documents/Guides.How_to_Create_a_Custom_Assertion) to learn more.
+- The first parameter to a _BUPKIS_ assertion is always the _subject_ ([def.](https://bupkis.zip/documents/Reference.Glossary_of_Terms#subject)).
 
-## Prerequisites
+- 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.
 
-_BUPKIS_ requires **Node.js ^20.19.0 || ^22.12.0 || >=23** and ships as a dual CJS/ESM package.
+- Assertions may have multiple phrases or parameters, but the simplest assertions always look like this:
 
-The library has been designed for Node.js environments and testing frameworks.
+  ```ts
+  expect(subject, 'phrase');
+  ```
 
-## Installation
+  ...and more complex assertions look like this:
 
-```bash
-npm install bupkis -D
-```
+  ```ts
+  expect(subject, 'phrase', [parameter?, phrase?, parameter?, ...]);
+  ```
 
-## Usage
+- One more convention worth mentioning is _negation_.
+
+  You can _negate_ just about any phrase by prepending it with `not` and a space. For example:
+
+  ```js
+  expect(actual, 'to be', expected);
+  expect(actual, 'not to be', expected);
+
+  expect(
+    () => throw new TypeError('aww, shucks'),
+    'not to throw a',
+    TypeError,
+    'satisfying',
+    /gol durn/,
+  );
+  ```
+
+  Handy!
+
+### 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.
 
-Here:
+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_:
 
 ```ts
-import { expect } from 'bupkis';
-
-// Basic type assertions
-expect('hello', 'to be a string');
-expect(42, 'to be a number');
-expect(true, 'to be a boolean');
-
-// Value comparisons
-expect(10, 'to equal', 10);
-expect('hello world', 'to contain', 'world');
-expect([1, 2, 3], 'to have length', 3);
-
-// Negation
-expect(42, 'not to be a string');
-expect('hello', 'not to equal', 'goodbye');
-
-// Object assertions
-const user = { name: 'Alice', age: 30 };
-expect(user, 'to be an object');
-expect(user, 'to have property', 'name');
-expect(user, 'to satisfy', { name: 'Alice' });
-```
+import { z, use, createAssertion } from 'bupkis';
 
-For comprehensive documentation and guides, visit the [project documentation](https://boneskull.github.io/bupkis/).
+const stringAssertion = createAssertion(
+  z.string(),
+  [['to be based', 'to be bussin']],
+  z.string(),
+);
 
-### Worth Mentioning Right Now
+const { expect } = use([stringAssertion]);
 
-_BUPKIS_ has two main exports:
+expect('chat', 'to be based');
+expect('fam', 'to be bussin');
 
-- `expect()`: the main entrypoint for synchronous assertions
-- `expectAsync()`: the main entrypoint for asynchronous assertions
+// did you know? includes all builtin assertions!
+expect('skiball lavatory', 'to be a string');
+```
 
-> [!IMPORTANT]
+> 📒 Registration?
 >
-> As of this writing, the assertions available in `expectAsync()` are all `Promise`-related (and custom assertions can even use an async schema for the subject); they are completely disjoint from the assertions available in `expect()`. **This will likely change in the future.**
+> "Registration" of an assertion (though there is no stateful "registry" anywhere) is as straightforward as passing an array of `Assertion` instances (created via `createAssertion()`/`createAsyncAssertion()`) to the `use()` function.
+>
+> `use()`, as exported from `bupkis`, returns a new `expect()`/`expectAsync()` pair that includes your custom assertions alongside all the built-in ones. The new `expect()`/`expectAsync()` functions are fully type-safe and aware of your custom assertions. They _also_ have a `.use()` method, which allows you to compose sets of assertions from disjoint sources.
+
+**Zod makes it extremely easy to create most custom assertions**. But despite its power, it can't do _everything_ we need an assertion to do; for those situations, there's also a [function-based API][custom-assertion-function] for use with [parametric][] and behavioral (e.g., involving function execution) assertions.
+
+👉 For an assiduous guide on creating assertions, read [Guide: How to Create a Custom Assertion][create-a-custom-assertion].
+
+### 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:
+
+- 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()`)
+- If an assertion demands the _subject_ be of a certain type, the TS compiler will squawk if you try to use an incompatible subject type. For example, `<Map> to have size <number>` will only accept a `Map` as the subject, and this will be obvious in your editor.
+
+> _Note_: `expect()` is not and cannot be a type guard; see the ["Caveats" Reference doc](http://bupkis.zip/documents/Reference.Caveats#expect-is-not-a-type-guard) for more information.
+
+## Prerequisites
 
-## Project Scope
+**Node.js**: ^20.19.0, ^22.12.0, >=23
 
-1. It's an assertion library
+_BUPKIS_ has a peer dependency on [Zod][] v4+, but will install it as an optional dependency if you are not already using it.
 
-### TODO
+_BUPKIS_ ships as a dual CJS/ESM package.
 
-## Prior Art & Appreciation
+> 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
+npm install bupkis -D
+```
+
+## Usage
+
+👉 See the [Basic Usage Guide](https://bupkis.zip/documents/guides.basic_usage) for a quick introduction.
+
+📖 Visit [https://bupkis.zip](https://bupkis.zip) for comprehensive guides and reference.
+
+## Acknowledgements
 
 - [Unexpected][] is the main inspiration for _BUPKIS_. However, creating types for this library is exceedingly difficult (and was in fact the first thing I tried). Despite that drawback, I find it more usable than any other assertion library I've tried.
-- [Zod][] is a popular object validation library which does most of the heavy lifting for _BUPKIS_. It's not an assertion library, but there's enough overlap in its use case that it makes sense to leverage it.
-- [fast-check][]: A big thanks to Nicholas Dubien for this library. There is **no better library** for an assertion library to use to test itself! Well, besides itself, I mean. How about _in addition to_ itself? Yes. Thank you!
+- [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, I 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.
 
-## A Note From The Author
+## Why is it called _BUPKIS_?
 
-> _"This is my assertion library. Many are like it, but this one is mine."_
->
-> ‒boneskull, 2025
+TODO: think of good reason and fill in later
 
 ## License
 
 Copyright © 2025 Christopher Hiller. Licensed under [BlueOak-1.0.0](https://blueoakcouncil.org/license/1.0.0).
 
 [zod]: https://zod.dev
+[docs]: https://bupkis.zip
+[basic-usage]: https://bupkis.zip/documents/guides.basic_usage
 [unexpected]: https://unexpected.js.org
 [fast-check]: https://fast-check.dev
+[parametric]: https://bupkis.zip/documents/Reference.Glossary_of_Terms#parametric-assertion
+[custom-assertion-function]: https://bupkis.zip/documents/guides.how_to_create_a_custom_assertion#using-a-function
+[create-a-custom-assertion]: https://bupkis.zip/documents/Guides.How_to_Create_a_Custom_Assertion
+[assertion-reference]: https://bupkis.zip/documents/reference.assertions
+[tshy]: https://github.com/isaacs/tshy
+[typedoc]: https://typedoc.org

package/dist/commonjs/api.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Contains the main API types
+ *
+ * @packageDocumentation
+ */
+import type { TupleToUnion, UnionToIntersection } from 'type-fest';
+import type { AnyAsyncAssertion, AnyAsyncAssertions, AnySyncAssertion, AnySyncAssertions, BuiltinAsyncAssertions, BuiltinSyncAssertions } from './assertion/assertion-types.js';
+import type { createAssertion, createAsyncAssertion } from './assertion/create.js';
+import { type InferredExpectSlots, type MutableOrReadonly, type UseFn } from './types.js';
+/**
+ * Base set of properties included in both {@link Expect} and {@link ExpectAsync}.
+ */
+export interface BaseExpect {
+    /**
+     * Creates a new synchronous assertion.
+     */
+    createAssertion: typeof createAssertion;
+    /**
+     * Creates a new asynchronous assertion.
+     */
+    createAsyncAssertion: typeof createAsyncAssertion;
+    /**
+     * Fails immediately with optional `reason`.
+     *
+     * @param reason Reason for failure
+     * @throws {AssertionError}
+     */
+    fail(this: void, reason?: string): never;
+}
+/**
+ * The main synchronous assertion function.
+ *
+ * Contains properties in {@link ExpectSyncProps}.
+ *
+ * @template T All synchronous assertions available
+ * @template U All asynchronous assertions available; for use in
+ *   {@link ExpectSyncProps.use}
+ * @useDeclaredType
+ * @see {@link expect}
+ */
+export type Expect<T extends AnySyncAssertions = BuiltinSyncAssertions, U extends AnyAsyncAssertions = BuiltinAsyncAssertions> = ExpectFunction<T> & ExpectSyncProps<T, U>;
+/**
+ * The main asynchronous assertion function.
+ *
+ * Contains properties in {@link ExpectSyncProps}.
+ *
+ * @useDeclaredType
+ * @see {@link expectAsync}
+ */
+export type ExpectAsync<T extends AnyAsyncAssertions = BuiltinAsyncAssertions, U extends AnySyncAssertions = BuiltinSyncAssertions> = ExpectAsyncFunction<T> & ExpectAsyncProps<T, U>;
+/**
+ * All function overloads for `expectAsync()`; part of {@link ExpectAsync}.
+ */
+export type ExpectAsyncFunction<T extends AnyAsyncAssertions = BuiltinAsyncAssertions> = UnionToIntersection<TupleToUnion<{
+    [K in keyof T]: T[K] extends AnyAsyncAssertion ? (...args: MutableOrReadonly<InferredExpectSlots<T[K]['parts']>>) => Promise<void> : never;
+}>>;
+/**
+ * Properties available on `expectAsync()`; part of {@link ExpectAsync}.
+ */
+export interface ExpectAsyncProps<T extends AnyAsyncAssertions, U extends AnySyncAssertions> extends BaseExpect {
+    /**
+     * Tuple of all assertions available in this `expect()`.
+     */
+    assertions: T;
+    /**
+     * Function to add more assertions to this `expect()`, returning a new
+     * `expect()` and `expectAsync()` pair with the combined assertions.
+     */
+    use: UseFn<U, T>;
+}
+/**
+ * All function overloads for `expect()`; part of {@link Expect}.
+ *
+ * @useDeclaredType
+ */
+export type ExpectFunction<T extends AnySyncAssertions = BuiltinSyncAssertions> = UnionToIntersection<TupleToUnion<{
+    [K in keyof T]: T[K] extends AnySyncAssertion ? (...args: MutableOrReadonly<InferredExpectSlots<T[K]['parts']>>) => void : never;
+}>>;
+/**
+ * Properties for `expect()`; part of {@link Expect}.
+ */
+export interface ExpectSyncProps<T extends AnySyncAssertions, U extends AnyAsyncAssertions> extends BaseExpect {
+    /**
+     * Tuple of all assertions available in this `expect()`.
+     */
+    assertions: T;
+    /**
+     * Function to add more assertions to this `expect()`, returning a new
+     * `expect()` and `expectAsync()` pair with the combined assertions.
+     */
+    use: UseFn<T, U>;
+}
+//# sourceMappingURL=api.d.ts.map

package/dist/commonjs/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../src/api.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAEnE,OAAO,KAAK,EACV,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,EACjB,sBAAsB,EACtB,qBAAqB,EACtB,MAAM,gCAAgC,CAAC;AACxC,OAAO,KAAK,EACV,eAAe,EACf,oBAAoB,EACrB,MAAM,uBAAuB,CAAC;AAI/B,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACtB,KAAK,KAAK,EACX,MAAM,YAAY,CAAC;AAEpB;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB;;OAEG;IACH,eAAe,EAAE,OAAO,eAAe,CAAC;IACxC;;OAEG;IACH,oBAAoB,EAAE,OAAO,oBAAoB,CAAC;IAClD;;;;;OAKG;IACH,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;CAC1C;AAED;;;;;;;;;;GAUG;AAEH,MAAM,MAAM,MAAM,CAChB,CAAC,SAAS,iBAAiB,GAAG,qBAAqB,EACnD,CAAC,SAAS,kBAAkB,GAAG,sBAAsB,IACnD,cAAc,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAE9C;;;;;;;GAOG;AAEH,MAAM,MAAM,WAAW,CACrB,CAAC,SAAS,kBAAkB,GAAG,sBAAsB,EACrD,CAAC,SAAS,iBAAiB,GAAG,qBAAqB,IACjD,mBAAmB,CAAC,CAAC,CAAC,GAAG,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAEpD;;GAEG;AAEH,MAAM,MAAM,mBAAmB,CAC7B,CAAC,SAAS,kBAAkB,GAAG,sBAAsB,IACnD,mBAAmB,CACrB,YAAY,CAAC;KACV,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,iBAAiB,GAC1C,CACE,GAAG,IAAI,EAAE,iBAAiB,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAC3D,OAAO,CAAC,IAAI,CAAC,GAClB,KAAK;CACV,CAAC,CACH,CAAC;AAEF;;GAEG;AAEH,MAAM,WAAW,gBAAgB,CAC/B,CAAC,SAAS,kBAAkB,EAC5B,CAAC,SAAS,iBAAiB,CAC3B,SAAQ,UAAU;IAClB;;OAEG;IACH,UAAU,EAAE,CAAC,CAAC;IACd;;;OAGG;IACH,GAAG,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,MAAM,cAAc,CACxB,CAAC,SAAS,iBAAiB,GAAG,qBAAqB,IACjD,mBAAmB,CACrB,YAAY,CAAC;KACV,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,gBAAgB,GACzC,CAAC,GAAG,IAAI,EAAE,iBAAiB,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,IAAI,GACxE,KAAK;CACV,CAAC,CACH,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,eAAe,CAC9B,CAAC,SAAS,iBAAiB,EAC3B,CAAC,SAAS,kBAAkB,CAC5B,SAAQ,UAAU;IAClB;;OAEG;IACH,UAAU,EAAE,CAAC,CAAC;IAEd;;;OAGG;IACH,GAAG,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;CAClB"}

package/dist/commonjs/api.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Contains the main API types
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=api.js.map

package/dist/commonjs/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../../src/api.ts"],"names":[],"mappings":";AAAA;;;;GAIG"}

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

@@ -0,0 +1,45 @@
+import { type AssertionAsync, type AssertionFunctionAsync, type AssertionImplAsync, type AssertionImplFnAsync, type AssertionImplSchemaAsync, type AssertionParts, type AssertionSchemaAsync, type AssertionSlots, type ParsedResult, type ParsedValues } from './assertion-types.js';
+import { BupkisAssertion } from './assertion.js';
+export declare abstract class BupkisAssertionAsync<Parts extends AssertionParts, Impl extends AssertionImplAsync<Parts>, Slots extends AssertionSlots<Parts>> extends BupkisAssertion<Parts, Impl, Slots> implements AssertionAsync<Parts, Impl, Slots> {
+    abstract executeAsync(parsedValues: ParsedValues<Parts>, args: unknown[], stackStartFn: (...args: any[]) => any, parseResult?: ParsedResult<Parts>): Promise<void>;
+    parseValuesAsync<Args extends readonly unknown[]>(args: Args): Promise<ParsedResult<Parts>>;
+}
+/**
+ * An assertion implemented as a Zod schema.
+ *
+ * Async schemas are supported via {@link expectAsync}.
+ */
+/**
+ * Optimized schema assertion that performs subject validation during
+ * parseValues() to eliminate double parsing for simple schema-based
+ * assertions.
+ *
+ * This class implements Option 2 from the z.function() analysis - it caches the
+ * subject validation result during argument parsing and reuses it during
+ * execution, eliminating the double parsing overhead.
+ */
+export declare class BupkisAssertionFunctionAsync<Parts extends AssertionParts, Impl extends AssertionImplFnAsync<Parts>, Slots extends AssertionSlots<Parts>> extends BupkisAssertionAsync<Parts, Impl, Slots> implements AssertionFunctionAsync<Parts, Impl, Slots> {
+    executeAsync(parsedValues: ParsedValues<Parts>, args: unknown[], stackStartFn: (...args: any[]) => any, _parseResult?: ParsedResult<Parts>): Promise<void>;
+}
+/**
+ * A class representing an assertion implemented as a function.
+ *
+ * This function may:
+ *
+ * 1. Return a `boolean` indicating pass/fail.
+ * 2. Return a `ZodType` which will be used to validate the subject.
+ * 3. Return a `Promise` resolving to either of the above (when called via
+ *    {@link expectAsync})
+ * 4. Throw a {@link AssertionError}; when called via {@link expectAsync}, reject
+ *    with an {@link AssertionError}
+ */
+export declare class BupkisAssertionSchemaAsync<Parts extends AssertionParts, Impl extends AssertionImplSchemaAsync<Parts>, Slots extends AssertionSlots<Parts>> extends BupkisAssertionAsync<Parts, Impl, Slots> implements AssertionSchemaAsync<Parts, Impl, Slots> {
+    executeAsync(parsedValues: ParsedValues<Parts>, _args: unknown[], stackStartFn: (...args: any[]) => any, _parseResult?: ParsedResult<Parts>): Promise<void>;
+    /**
+     * Determines if this assertion can be optimized (simple single-subject
+     * schema). Only simple assertions like ['to be a string'] with z.string()
+     * qualify.
+     */
+    private isSimpleSchemaAssertion;
+}
+//# sourceMappingURL=assertion-async.d.ts.map

package/dist/commonjs/assertion/assertion-async.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assertion-async.d.ts","sourceRoot":"","sources":["../../../src/assertion/assertion-async.ts"],"names":[],"mappings":"AAQA,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,sBAAsB,EAC3B,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,wBAAwB,EAC7B,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,YAAY,EAClB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAGjD,8BAAsB,oBAAoB,CACtC,KAAK,SAAS,cAAc,EAC5B,IAAI,SAAS,kBAAkB,CAAC,KAAK,CAAC,EACtC,KAAK,SAAS,cAAc,CAAC,KAAK,CAAC,CAErC,SAAQ,eAAe,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,CAC1C,YAAW,cAAc,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC;IAE7C,QAAQ,CAAC,YAAY,CACnB,YAAY,EAAE,YAAY,CAAC,KAAK,CAAC,EACjC,IAAI,EAAE,OAAO,EAAE,EACf,YAAY,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EACrC,WAAW,CAAC,EAAE,YAAY,CAAC,KAAK,CAAC,GAChC,OAAO,CAAC,IAAI,CAAC;IAEV,gBAAgB,CAAC,IAAI,SAAS,SAAS,OAAO,EAAE,EACpD,IAAI,EAAE,IAAI,GACT,OAAO,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;CA0ChC;AACD;;;;GAIG;AACH;;;;;;;;GAQG;AAEH,qBAAa,4BAA4B,CACrC,KAAK,SAAS,cAAc,EAC5B,IAAI,SAAS,oBAAoB,CAAC,KAAK,CAAC,EACxC,KAAK,SAAS,cAAc,CAAC,KAAK,CAAC,CAErC,SAAQ,oBAAoB,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,CAC/C,YAAW,sBAAsB,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC;IAEtC,YAAY,CACzB,YAAY,EAAE,YAAY,CAAC,KAAK,CAAC,EACjC,IAAI,EAAE,OAAO,EAAE,EACf,YAAY,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EACrC,YAAY,CAAC,EAAE,YAAY,CAAC,KAAK,CAAC,GACjC,OAAO,CAAC,IAAI,CAAC;CA8BjB;AAED;;;;;;;;;;;GAWG;AAEH,qBAAa,0BAA0B,CACnC,KAAK,SAAS,cAAc,EAC5B,IAAI,SAAS,wBAAwB,CAAC,KAAK,CAAC,EAC5C,KAAK,SAAS,cAAc,CAAC,KAAK,CAAC,CAErC,SAAQ,oBAAoB,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,CAC/C,YAAW,oBAAoB,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC;IAEpC,YAAY,CACzB,YAAY,EAAE,YAAY,CAAC,KAAK,CAAC,EACjC,KAAK,EAAE,OAAO,EAAE,EAChB,YAAY,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EACrC,YAAY,CAAC,EAAE,YAAY,CAAC,KAAK,CAAC,GACjC,OAAO,CAAC,IAAI,CAAC;IAahB;;;;OAIG;IACH,OAAO,CAAC,uBAAuB;CAehC"}

package/dist/commonjs/assertion/assertion-async.js

@@ -0,0 +1,154 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BupkisAssertionSchemaAsync = exports.BupkisAssertionFunctionAsync = exports.BupkisAssertionAsync = void 0;
+const debug_1 = __importDefault(require("debug"));
+const util_1 = require("util");
+const v4_1 = __importDefault(require("zod/v4"));
+const constant_js_1 = require("../constant.js");
+const error_js_1 = require("../error.js");
+const guards_js_1 = require("../guards.js");
+const metadata_js_1 = require("../metadata.js");
+const assertion_js_1 = require("./assertion.js");
+const debug = (0, debug_1.default)('bupkis:assertion:async');
+class BupkisAssertionAsync extends assertion_js_1.BupkisAssertion {
+    async parseValuesAsync(args) {
+        const { slots } = this;
+        const parsedValues = [];
+        if (slots.length !== args.length) {
+            return {
+                success: false,
+            };
+        }
+        let exactMatch = true;
+        for (let i = 0; i < slots.length; i++) {
+            const slot = slots[i];
+            const arg = args[i];
+            const parsedLiteralResult = this.parseSlotForLiteral(slot, i, arg);
+            if (parsedLiteralResult === true) {
+                continue;
+            }
+            else if (parsedLiteralResult !== false) {
+                return parsedLiteralResult;
+            }
+            // unknown/any accept anything
+            // IMPORTANT: do not use a type guard here; it will break inference
+            if (slot.def.type === 'unknown' || slot.def.type === 'any') {
+                debug('Skipping unknown/any slot validation for arg', arg);
+                parsedValues.push(arg);
+                exactMatch = false;
+                continue;
+            }
+            const result = await slot.safeParseAsync(arg);
+            if (!result.success) {
+                return {
+                    success: false,
+                };
+            }
+            parsedValues.push(result.data);
+        }
+        return {
+            exactMatch,
+            parsedValues: parsedValues,
+            success: true,
+        };
+    }
+}
+exports.BupkisAssertionAsync = BupkisAssertionAsync;
+/**
+ * An assertion implemented as a Zod schema.
+ *
+ * Async schemas are supported via {@link expectAsync}.
+ */
+/**
+ * Optimized schema assertion that performs subject validation during
+ * parseValues() to eliminate double parsing for simple schema-based
+ * assertions.
+ *
+ * This class implements Option 2 from the z.function() analysis - it caches the
+ * subject validation result during argument parsing and reuses it during
+ * execution, eliminating the double parsing overhead.
+ */
+class BupkisAssertionFunctionAsync extends BupkisAssertionAsync {
+    async executeAsync(parsedValues, args, stackStartFn, _parseResult) {
+        const { impl } = this;
+        const result = await impl(...parsedValues);
+        if ((0, guards_js_1.isZodType)(result)) {
+            try {
+                await result.parseAsync(parsedValues[0]);
+            }
+            catch (error) {
+                if ((0, guards_js_1.isA)(error, v4_1.default.ZodError)) {
+                    throw this.translateZodError(stackStartFn, error, ...parsedValues);
+                }
+                throw error;
+            }
+        }
+        else if ((0, guards_js_1.isBoolean)(result)) {
+            if (!result) {
+                throw new error_js_1.AssertionError({
+                    message: `Assertion ${this} failed for arguments: ${(0, util_1.inspect)(args)}`,
+                });
+            }
+        }
+        else if ((0, guards_js_1.isAssertionFailure)(result)) {
+            throw new error_js_1.AssertionError({
+                actual: result.actual,
+                expected: result.expected,
+                message: result.message ?? `Assertion ${this} failed`,
+            });
+        }
+        else if (result) {
+            throw new TypeError(`Invalid return type from assertion ${this}; expected boolean, ZodType, or AssertionFailure`);
+        }
+    }
+}
+exports.BupkisAssertionFunctionAsync = BupkisAssertionFunctionAsync;
+/**
+ * A class representing an assertion implemented as a function.
+ *
+ * This function may:
+ *
+ * 1. Return a `boolean` indicating pass/fail.
+ * 2. Return a `ZodType` which will be used to validate the subject.
+ * 3. Return a `Promise` resolving to either of the above (when called via
+ *    {@link expectAsync})
+ * 4. Throw a {@link AssertionError}; when called via {@link expectAsync}, reject
+ *    with an {@link AssertionError}
+ */
+class BupkisAssertionSchemaAsync extends BupkisAssertionAsync {
+    async executeAsync(parsedValues, _args, stackStartFn, _parseResult) {
+        // For async, fall back to standard implementation for now
+        const [subject] = parsedValues;
+        try {
+            await this.impl.parseAsync(subject);
+        }
+        catch (error) {
+            if ((0, guards_js_1.isA)(error, v4_1.default.ZodError)) {
+                throw this.translateZodError(stackStartFn, error, ...parsedValues);
+            }
+            throw error;
+        }
+    }
+    /**
+     * Determines if this assertion can be optimized (simple single-subject
+     * schema). Only simple assertions like ['to be a string'] with z.string()
+     * qualify.
+     */
+    isSimpleSchemaAssertion() {
+        // Only optimize if we have exactly one subject slot + string literal slots
+        // and no complex argument processing
+        const hasSubjectSlot = this.slots.length > 0 &&
+            (this.slots[0]?.def.type === 'unknown' ||
+                this.slots[0]?.def.type === 'any');
+        const allOtherSlotsAreLiterals = this.slots.slice(1).every((slot) => {
+            const meta = metadata_js_1.BupkisRegistry.get(slot) ?? {};
+            return constant_js_1.kStringLiteral in meta;
+        });
+        return hasSubjectSlot && allOtherSlotsAreLiterals;
+    }
+}
+exports.BupkisAssertionSchemaAsync = BupkisAssertionSchemaAsync;
+//# sourceMappingURL=assertion-async.js.map

package/dist/commonjs/assertion/assertion-async.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assertion-async.js","sourceRoot":"","sources":["../../../src/assertion/assertion-async.ts"],"names":[],"mappings":"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"}