bupkis 0.18.2 → 1.0.0

package/dist/assertion/impl/assertion-util.js

@@ -0,0 +1,62 @@
+/**
+ * Utility functions for assertion implementations
+ *
+ * @internal
+ * @packageDocumentation
+ */
+/**
+ * Executes & traps a `Promise` rejected from an async function, capturing the
+ * error.
+ *
+ * @function
+ * @param fn The function to execute that may throw an error or return a
+ *   `Promise`
+ * @returns Rejection or whatever was fulfilled
+ */
+export const trapAsyncFnError = async (fn) => {
+    try {
+        const result = await fn();
+        return { result };
+    }
+    catch (error) {
+        return {
+            error: error ?? new TypeError(`Function rejected with undefined: ${fn}`),
+        };
+    }
+};
+/**
+ * Awaits & traps a Promise, capturing any rejection error.
+ *
+ * @function
+ * @param promise The `Promise` to trap
+ * @returns Result object
+ */
+export const trapPromiseError = async (promise) => {
+    try {
+        const result = await promise;
+        return { result };
+    }
+    catch (error) {
+        return { error: error ?? new TypeError('Promise rejected with undefined') };
+    }
+};
+/**
+ * Executes & traps a synchronous function that may throw, capturing any thrown
+ * error and discarding the result.
+ *
+ * @remarks
+ * Avoids throwing `undefined` for some reason.
+ * @function
+ * @param fn Function to execute
+ * @returns Result object
+ */
+export const trapError = (fn) => {
+    try {
+        const result = fn();
+        return { result };
+    }
+    catch (error) {
+        return { error: error ?? new TypeError(`Function threw undefined: ${fn}`) };
+    }
+};
+//# sourceMappingURL=assertion-util.js.map

package/dist/assertion/impl/assertion-util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assertion-util.js","sourceRoot":"","sources":["../../../src/assertion/impl/assertion-util.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,KAAK,EACnC,EAAiB,EACI,EAAE;IACvB,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,EAAE,EAAE,CAAC;QAC1B,OAAO,EAAE,MAAM,EAAE,CAAC;IACpB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO;YACL,KAAK,EAAE,KAAK,IAAI,IAAI,SAAS,CAAC,qCAAqC,EAAE,EAAE,CAAC;SACzE,CAAC;IACJ,CAAC;AACH,CAAC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,KAAK,EACnC,OAA6B,EACR,EAAE;IACvB,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC;QAC7B,OAAO,EAAE,MAAM,EAAE,CAAC;IACpB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,EAAE,KAAK,EAAE,KAAK,IAAI,IAAI,SAAS,CAAC,iCAAiC,CAAC,EAAE,CAAC;IAC9E,CAAC;AACH,CAAC,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,EAAiB,EAAc,EAAE;IACzD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,EAAE,EAAE,CAAC;QACpB,OAAO,EAAE,MAAM,EAAE,CAAC;IACpB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,EAAE,KAAK,EAAE,KAAK,IAAI,IAAI,SAAS,CAAC,6BAA6B,EAAE,EAAE,CAAC,EAAE,CAAC;IAC9E,CAAC;AACH,CAAC,CAAC"}

package/dist/assertion/impl/async-iterable.cjs

@@ -0,0 +1,627 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AsyncIterableAssertions = exports.asyncIterableRejectsWithErrorSatisfyingAssertion = exports.asyncIterableRejectsWithTypeAssertion = exports.asyncIterableRejectsAssertion = exports.asyncIterableCompletesAssertion = exports.asyncIterableYieldsSequenceSatisfyingAssertion = exports.asyncIterableYieldsExactlyAssertion = exports.asyncIterableEmptyAssertion = exports.asyncIterableYieldsAtMostAssertion = exports.asyncIterableYieldsAtLeastAssertion = exports.asyncIterableYieldsCountAssertion = exports.asyncIterableYieldsLastExhaustivelyAssertion = exports.asyncIterableYieldsLastAssertion = exports.asyncIterableYieldsFirstExhaustivelyAssertion = exports.asyncIterableYieldsFirstAssertion = exports.asyncIterableYieldsItemsExhaustivelyAssertion = exports.asyncIterableYieldsItemsSatisfyingAssertion = exports.asyncIterableYieldsExhaustivelyAssertion = exports.asyncIterableYieldsAssertion = void 0;
+// do not remove; otherwise zshy will not resolve the .d.ts file; it must be referenced directly
+// eslint-disable-next-line @typescript-eslint/triple-slash-reference
+/// <reference path="./shims.d.ts" />
+/**
+ * Iterable assertions for asynchronous iterables and iterators.
+ *
+ * These assertions test async iterables using the **async iteration protocol**
+ * (`Symbol.asyncIterator`), including async generators, Node.js Readable
+ * streams, and Web ReadableStreams.
+ *
+ * @packageDocumentation
+ * @groupDescription Async Iterable Assertions
+ * Assertions for asynchronous iterables and iterators using the async iteration protocol.
+ *
+ * @showGroup
+ */
+const node_util_1 = require("node:util");
+const zod_1 = require("zod");
+const schema_js_1 = require("../../schema.cjs");
+const value_to_schema_js_1 = require("../../value-to-schema.cjs");
+const create_js_1 = require("../create.cjs");
+const iteration_util_js_1 = require("./iteration-util.cjs");
+// =============================================================================
+// 'to yield' assertions - check if ANY item matches
+// =============================================================================
+/**
+ * Asserts that an async iterable yields a value satisfying the expected shape.
+ *
+ * Uses partial/satisfy semantics (like `'to satisfy'`). The assertion passes if
+ * ANY yielded value matches the expected shape.
+ *
+ * @example
+ *
+ * ```ts
+ * await expectAsync(asyncGenerator(), 'to yield', 'value'); // passes
+ * await expectAsync(nodeReadable, 'to emit', 'chunk'); // passes
+ * await expectAsync(response.body, 'to yield value satisfying', {
+ *   data: 'test',
+ * }); // Web Stream
+ * ```
+ *
+ * @group Async Iterable Assertions
+ * @bupkisAnchor async-iterable-to-yield-any
+ * @bupkisAssertionCategory iterable
+ */
+exports.asyncIterableYieldsAssertion = (0, create_js_1.createAsyncAssertion)([
+    schema_js_1.AsyncIterableOrIteratorSchema,
+    ['to yield', 'to emit', 'to yield value satisfying'],
+    schema_js_1.UnknownSchema,
+], async (subject, expected) => {
+    const iterator = (0, iteration_util_js_1.toAsyncIterator)(subject);
+    const schema = (0, value_to_schema_js_1.valueToSchema)(expected, value_to_schema_js_1.valueToSchemaOptionsForSatisfies);
+    let next = await iterator.next();
+    while (!next.done) {
+        if (schema.safeParse(next.value).success) {
+            return; // success - found a matching value
+        }
+        next = await iterator.next();
+    }
+    return {
+        message: `Expected async iterable to yield a value satisfying ${(0, node_util_1.inspect)(expected)}, but none matched`,
+    };
+});
+/**
+ * Asserts that an async iterable yields a value exhaustively matching the
+ * expected value.
+ *
+ * Uses deep equality semantics (like `'to equal'`). Extra properties on yielded
+ * values cause failure.
+ *
+ * @example
+ *
+ * ```ts
+ * await expectAsync(asyncGen(), 'to yield value exhaustively satisfying', {
+ *   a: 1,
+ * }); // passes if { a: 1 } exactly is yielded
+ * ```
+ *
+ * @group Async Iterable Assertions
+ * @bupkisAnchor async-iterable-to-yield-value-exhaustively-satisfying-any
+ * @bupkisAssertionCategory iterable
+ */
+exports.asyncIterableYieldsExhaustivelyAssertion = (0, create_js_1.createAsyncAssertion)([
+    schema_js_1.AsyncIterableOrIteratorSchema,
+    'to yield value exhaustively satisfying',
+    schema_js_1.UnknownSchema,
+], async (subject, expected) => {
+    const iterator = (0, iteration_util_js_1.toAsyncIterator)(subject);
+    const schema = (0, value_to_schema_js_1.valueToSchema)(expected, value_to_schema_js_1.valueToSchemaOptionsForDeepEqual);
+    let next = await iterator.next();
+    while (!next.done) {
+        if (schema.safeParse(next.value).success) {
+            return; // success - found an exact match
+        }
+        next = await iterator.next();
+    }
+    return {
+        message: `Expected async iterable to yield a value exhaustively satisfying ${(0, node_util_1.inspect)(expected)}, but none matched`,
+    };
+});
+// =============================================================================
+// 'to yield items satisfying' - ALL items must match
+// =============================================================================
+/**
+ * Asserts that ALL yielded values individually satisfy the expected shape.
+ *
+ * Uses partial/satisfy semantics. Every item yielded must match.
+ *
+ * @example
+ *
+ * ```ts
+ * await expectAsync(asyncGen(), 'to yield items satisfying', {
+ *   type: 'data',
+ * });
+ * ```
+ *
+ * @group Async Iterable Assertions
+ * @bupkisAnchor async-iterable-to-yield-items-satisfying-any
+ * @bupkisAssertionCategory iterable
+ */
+exports.asyncIterableYieldsItemsSatisfyingAssertion = (0, create_js_1.createAsyncAssertion)([schema_js_1.AsyncIterableOrIteratorSchema, 'to yield items satisfying', schema_js_1.UnknownSchema], async (subject, expected) => {
+    const iterator = (0, iteration_util_js_1.toAsyncIterator)(subject);
+    const schema = (0, value_to_schema_js_1.valueToSchema)(expected, value_to_schema_js_1.valueToSchemaOptionsForSatisfies);
+    let index = 0;
+    let next = await iterator.next();
+    while (!next.done) {
+        const result = schema.safeParse(next.value);
+        if (!result.success) {
+            return {
+                message: `Expected all items to satisfy ${(0, node_util_1.inspect)(expected)}, but item at index ${index} did not match: ${(0, node_util_1.inspect)(next.value)}`,
+            };
+        }
+        index++;
+        next = await iterator.next();
+    }
+});
+/**
+ * Asserts that ALL yielded values individually match with deep equality.
+ *
+ * Uses strict equality semantics. Every item yielded must exactly match.
+ *
+ * @example
+ *
+ * ```ts
+ * await expectAsync(asyncGen(), 'to yield items exhaustively satisfying', {
+ *   a: 1,
+ * });
+ * ```
+ *
+ * @group Async Iterable Assertions
+ * @bupkisAnchor async-iterable-to-yield-items-exhaustively-satisfying-any
+ * @bupkisAssertionCategory iterable
+ */
+exports.asyncIterableYieldsItemsExhaustivelyAssertion = (0, create_js_1.createAsyncAssertion)([
+    schema_js_1.AsyncIterableOrIteratorSchema,
+    'to yield items exhaustively satisfying',
+    schema_js_1.UnknownSchema,
+], async (subject, expected) => {
+    const iterator = (0, iteration_util_js_1.toAsyncIterator)(subject);
+    const schema = (0, value_to_schema_js_1.valueToSchema)(expected, value_to_schema_js_1.valueToSchemaOptionsForDeepEqual);
+    let index = 0;
+    let next = await iterator.next();
+    while (!next.done) {
+        const result = schema.safeParse(next.value);
+        if (!result.success) {
+            return {
+                message: `Expected all items to exhaustively satisfy ${(0, node_util_1.inspect)(expected)}, but item at index ${index} did not match: ${(0, node_util_1.inspect)(next.value)}`,
+            };
+        }
+        index++;
+        next = await iterator.next();
+    }
+});
+// =============================================================================
+// First/Last assertions
+// =============================================================================
+/**
+ * Asserts that the first yielded value satisfies the expected shape.
+ *
+ * Uses partial/satisfy semantics.
+ *
+ * @example
+ *
+ * ```ts
+ * await expectAsync(asyncGen(), 'to yield first', { type: 'header' });
+ * ```
+ *
+ * @group Async Iterable Assertions
+ * @bupkisAnchor async-iterable-to-yield-first-any
+ * @bupkisAssertionCategory iterable
+ */
+exports.asyncIterableYieldsFirstAssertion = (0, create_js_1.createAsyncAssertion)([
+    schema_js_1.AsyncIterableOrIteratorSchema,
+    ['to yield first', 'to yield first satisfying'],
+    schema_js_1.UnknownSchema,
+], async (subject, expected) => {
+    const iterator = (0, iteration_util_js_1.toAsyncIterator)(subject);
+    const result = await iterator.next();
+    if (result.done) {
+        return {
+            message: 'Expected async iterable to yield at least one value, but it was empty',
+        };
+    }
+    const schema = (0, value_to_schema_js_1.valueToSchema)(expected, value_to_schema_js_1.valueToSchemaOptionsForSatisfies);
+    if (!schema.safeParse(result.value).success) {
+        return {
+            message: `Expected first yielded value to satisfy ${(0, node_util_1.inspect)(expected)}, but got ${(0, node_util_1.inspect)(result.value)}`,
+        };
+    }
+});
+/**
+ * Asserts that the first yielded value exhaustively matches.
+ *
+ * Uses deep equality semantics.
+ *
+ * @example
+ *
+ * ```ts
+ * await expectAsync(asyncGen(), 'to yield first exhaustively satisfying', {
+ *   a: 1,
+ * });
+ * ```
+ *
+ * @group Async Iterable Assertions
+ * @bupkisAnchor async-iterable-to-yield-first-exhaustively-satisfying-any
+ * @bupkisAssertionCategory iterable
+ */
+exports.asyncIterableYieldsFirstExhaustivelyAssertion = (0, create_js_1.createAsyncAssertion)([
+    schema_js_1.AsyncIterableOrIteratorSchema,
+    'to yield first exhaustively satisfying',
+    schema_js_1.UnknownSchema,
+], async (subject, expected) => {
+    const iterator = (0, iteration_util_js_1.toAsyncIterator)(subject);
+    const result = await iterator.next();
+    if (result.done) {
+        return {
+            message: 'Expected async iterable to yield at least one value, but it was empty',
+        };
+    }
+    const schema = (0, value_to_schema_js_1.valueToSchema)(expected, value_to_schema_js_1.valueToSchemaOptionsForDeepEqual);
+    if (!schema.safeParse(result.value).success) {
+        return {
+            message: `Expected first yielded value to exhaustively satisfy ${(0, node_util_1.inspect)(expected)}, but got ${(0, node_util_1.inspect)(result.value)}`,
+        };
+    }
+});
+/**
+ * Asserts that the last yielded value satisfies the expected shape.
+ *
+ * Uses partial/satisfy semantics. Note: fully consumes the async iterator.
+ *
+ * @example
+ *
+ * ```ts
+ * await expectAsync(asyncGen(), 'to yield last', { type: 'footer' });
+ * ```
+ *
+ * @group Async Iterable Assertions
+ * @bupkisAnchor async-iterable-to-yield-last-any
+ * @bupkisAssertionCategory iterable
+ */
+exports.asyncIterableYieldsLastAssertion = (0, create_js_1.createAsyncAssertion)([
+    schema_js_1.AsyncIterableOrIteratorSchema,
+    ['to yield last', 'to yield last satisfying'],
+    schema_js_1.UnknownSchema,
+], async (subject, expected) => {
+    const { hasValue, lastValue } = await (0, iteration_util_js_1.iterateFullyAsync)(subject);
+    if (!hasValue) {
+        return {
+            message: 'Expected async iterable to yield at least one value, but it was empty',
+        };
+    }
+    const schema = (0, value_to_schema_js_1.valueToSchema)(expected, value_to_schema_js_1.valueToSchemaOptionsForSatisfies);
+    if (!schema.safeParse(lastValue).success) {
+        return {
+            message: `Expected last yielded value to satisfy ${(0, node_util_1.inspect)(expected)}, but got ${(0, node_util_1.inspect)(lastValue)}`,
+        };
+    }
+});
+/**
+ * Asserts that the last yielded value exhaustively matches.
+ *
+ * Uses deep equality semantics. Note: fully consumes the async iterator.
+ *
+ * @example
+ *
+ * ```ts
+ * await expectAsync(asyncGen(), 'to yield last exhaustively satisfying', {
+ *   b: 2,
+ * });
+ * ```
+ *
+ * @group Async Iterable Assertions
+ * @bupkisAnchor async-iterable-to-yield-last-exhaustively-satisfying-any
+ * @bupkisAssertionCategory iterable
+ */
+exports.asyncIterableYieldsLastExhaustivelyAssertion = (0, create_js_1.createAsyncAssertion)([
+    schema_js_1.AsyncIterableOrIteratorSchema,
+    'to yield last exhaustively satisfying',
+    schema_js_1.UnknownSchema,
+], async (subject, expected) => {
+    const { hasValue, lastValue } = await (0, iteration_util_js_1.iterateFullyAsync)(subject);
+    if (!hasValue) {
+        return {
+            message: 'Expected async iterable to yield at least one value, but it was empty',
+        };
+    }
+    const schema = (0, value_to_schema_js_1.valueToSchema)(expected, value_to_schema_js_1.valueToSchemaOptionsForDeepEqual);
+    if (!schema.safeParse(lastValue).success) {
+        return {
+            message: `Expected last yielded value to exhaustively satisfy ${(0, node_util_1.inspect)(expected)}, but got ${(0, node_util_1.inspect)(lastValue)}`,
+        };
+    }
+});
+// =============================================================================
+// Cardinality assertions
+// =============================================================================
+/**
+ * Asserts that an async iterable yields exactly the specified count of values.
+ *
+ * @example
+ *
+ * ```ts
+ * await expectAsync(asyncGen(), 'to yield count', 5);
+ * ```
+ *
+ * @group Async Iterable Assertions
+ * @bupkisAnchor async-iterable-to-yield-count-number
+ * @bupkisAssertionCategory iterable
+ */
+exports.asyncIterableYieldsCountAssertion = (0, create_js_1.createAsyncAssertion)([schema_js_1.AsyncIterableOrIteratorSchema, 'to yield count', schema_js_1.NonNegativeIntegerSchema], async (subject, expectedCount) => {
+    const actual = await (0, iteration_util_js_1.countAsync)(subject);
+    if (actual !== expectedCount) {
+        return {
+            actual,
+            expected: expectedCount,
+            message: `Expected async iterable to yield ${expectedCount} value(s), but yielded ${actual}`,
+        };
+    }
+});
+/**
+ * Asserts that an async iterable yields at least the specified count of values.
+ *
+ * @example
+ *
+ * ```ts
+ * await expectAsync(asyncGen(), 'to yield at least', 3);
+ * ```
+ *
+ * @group Async Iterable Assertions
+ * @bupkisAnchor async-iterable-to-yield-at-least-number
+ * @bupkisAssertionCategory iterable
+ */
+exports.asyncIterableYieldsAtLeastAssertion = (0, create_js_1.createAsyncAssertion)([
+    schema_js_1.AsyncIterableOrIteratorSchema,
+    'to yield at least',
+    schema_js_1.NonNegativeIntegerSchema,
+], async (subject, minCount) => {
+    const actual = await (0, iteration_util_js_1.countAsync)(subject);
+    if (actual < minCount) {
+        return {
+            actual,
+            expected: `at least ${minCount}`,
+            message: `Expected async iterable to yield at least ${minCount} value(s), but yielded ${actual}`,
+        };
+    }
+});
+/**
+ * Asserts that an async iterable yields at most the specified count of values.
+ *
+ * @example
+ *
+ * ```ts
+ * await expectAsync(asyncGen(), 'to yield at most', 10);
+ * ```
+ *
+ * @group Async Iterable Assertions
+ * @bupkisAnchor async-iterable-to-yield-at-most-number
+ * @bupkisAssertionCategory iterable
+ */
+exports.asyncIterableYieldsAtMostAssertion = (0, create_js_1.createAsyncAssertion)([schema_js_1.AsyncIterableOrIteratorSchema, 'to yield at most', schema_js_1.NonNegativeIntegerSchema], async (subject, maxCount) => {
+    const actual = await (0, iteration_util_js_1.countAsync)(subject);
+    if (actual > maxCount) {
+        return {
+            actual,
+            expected: `at most ${maxCount}`,
+            message: `Expected async iterable to yield at most ${maxCount} value(s), but yielded ${actual}`,
+        };
+    }
+});
+/**
+ * Asserts that an async iterable yields nothing (is empty).
+ *
+ * @remarks
+ * Use `'not to be an empty iterable'` or `'to yield at least', 1` for non-empty
+ * assertions.
+ * @example
+ *
+ * ```ts
+ * await expectAsync(emptyAsyncGen(), 'to be an empty iterable');
+ * ```
+ *
+ * @group Async Iterable Assertions
+ * @bupkisAnchor async-iterable-to-be-an-empty-iterable
+ * @bupkisAssertionCategory iterable
+ */
+exports.asyncIterableEmptyAssertion = (0, create_js_1.createAsyncAssertion)([schema_js_1.AsyncIterableOrIteratorSchema, 'to be an empty iterable'], async (subject) => {
+    const iterator = (0, iteration_util_js_1.toAsyncIterator)(subject);
+    const result = await iterator.next();
+    if (!result.done) {
+        return {
+            message: `Expected async iterable to be empty, but it yielded at least one value: ${(0, node_util_1.inspect)(result.value)}`,
+        };
+    }
+});
+// =============================================================================
+// Sequence/Collection assertions
+// =============================================================================
+/**
+ * Asserts that an async iterable yields exactly the specified values in order.
+ *
+ * Uses deep equality semantics. The iterable must yield the exact same number
+ * of values in the exact same order.
+ *
+ * @example
+ *
+ * ```ts
+ * await expectAsync(asyncGen(), 'to yield exactly', [1, 2, 3]);
+ * ```
+ *
+ * @group Async Iterable Assertions
+ * @bupkisAnchor async-iterable-to-yield-exactly-array
+ * @bupkisAssertionCategory iterable
+ */
+exports.asyncIterableYieldsExactlyAssertion = (0, create_js_1.createAsyncAssertion)([schema_js_1.AsyncIterableOrIteratorSchema, 'to yield exactly', zod_1.z.array(schema_js_1.UnknownSchema)], async (subject, expected) => {
+    const actual = await (0, iteration_util_js_1.collectAsync)(subject);
+    const schema = (0, value_to_schema_js_1.valueToSchema)(expected, value_to_schema_js_1.valueToSchemaOptionsForDeepEqual);
+    return { schema, subject: actual };
+});
+/**
+ * Asserts that an async iterable yields values that satisfy the expected
+ * sequence.
+ *
+ * Uses satisfy/partial matching semantics on the collected array.
+ *
+ * @example
+ *
+ * ```ts
+ * await expectAsync(asyncGen(), 'to yield sequence satisfying', [
+ *   { type: 'start' },
+ *   { type: 'end' },
+ * ]);
+ * ```
+ *
+ * @group Async Iterable Assertions
+ * @bupkisAnchor async-iterable-to-yield-sequence-satisfying-array
+ * @bupkisAssertionCategory iterable
+ */
+exports.asyncIterableYieldsSequenceSatisfyingAssertion = (0, create_js_1.createAsyncAssertion)([
+    schema_js_1.AsyncIterableOrIteratorSchema,
+    ['to yield sequence satisfying', 'to yield array satisfying'],
+    zod_1.z.array(schema_js_1.UnknownSchema),
+], async (subject, expected) => {
+    const actual = await (0, iteration_util_js_1.collectAsync)(subject);
+    const schema = (0, value_to_schema_js_1.valueToSchema)(expected, value_to_schema_js_1.valueToSchemaOptionsForSatisfies);
+    return { schema, subject: actual };
+});
+// =============================================================================
+// Completion/Error assertions (async-only)
+// =============================================================================
+/**
+ * Asserts that an async iterable completes without throwing.
+ *
+ * Fully consumes the iterator and verifies no error is thrown during iteration.
+ *
+ * @example
+ *
+ * ```ts
+ * await expectAsync(asyncGenerator(), 'to complete'); // passes if no error
+ * await expectAsync(nodeReadable, 'to finish'); // passes if stream ends cleanly
+ * ```
+ *
+ * @group Async Iterable Assertions
+ * @bupkisAnchor async-iterable-to-complete
+ * @bupkisAssertionCategory iterable
+ */
+exports.asyncIterableCompletesAssertion = (0, create_js_1.createAsyncAssertion)([schema_js_1.AsyncIterableOrIteratorSchema, ['to complete', 'to finish']], async (subject) => {
+    const { completed, error } = await (0, iteration_util_js_1.iterateFullyAsync)(subject);
+    if (!completed) {
+        return {
+            message: `Expected async iterable to complete, but it rejected with: ${(0, node_util_1.inspect)(error)}`,
+        };
+    }
+});
+/**
+ * Asserts that an async iterable rejects during iteration.
+ *
+ * @example
+ *
+ * ```ts
+ * await expectAsync(failingStream, 'to reject'); // passes if iteration rejects
+ * await expectAsync(failingStream, 'to be rejected'); // alias
+ * ```
+ *
+ * @group Async Iterable Assertions
+ * @bupkisAnchor async-iterable-to-reject
+ * @bupkisAssertionCategory iterable
+ */
+exports.asyncIterableRejectsAssertion = (0, create_js_1.createAsyncAssertion)([schema_js_1.AsyncIterableOrIteratorSchema, ['to reject', 'to be rejected']], async (subject) => {
+    const { completed } = await (0, iteration_util_js_1.iterateFullyAsync)(subject);
+    if (completed) {
+        return {
+            message: 'Expected async iterable to reject, but it completed successfully',
+        };
+    }
+});
+/**
+ * Asserts that an async iterable rejects with a specific error type.
+ *
+ * @example
+ *
+ * ```ts
+ * await expectAsync(failingStream, 'to reject with a', TypeError);
+ * await expectAsync(failingStream, 'to reject with an', Error);
+ * ```
+ *
+ * @group Async Iterable Assertions
+ * @bupkisAnchor async-iterable-to-reject-with-a-constructor
+ * @bupkisAssertionCategory iterable
+ */
+exports.asyncIterableRejectsWithTypeAssertion = (0, create_js_1.createAsyncAssertion)([
+    schema_js_1.AsyncIterableOrIteratorSchema,
+    ['to reject with a', 'to reject with an'],
+    schema_js_1.ConstructibleSchema,
+], async (subject, expectedType) => {
+    const { completed, error } = await (0, iteration_util_js_1.iterateFullyAsync)(subject);
+    if (completed) {
+        return {
+            message: `Expected async iterable to reject with ${expectedType.name}, but it completed successfully`,
+        };
+    }
+    if (!(error instanceof expectedType)) {
+        return {
+            message: `Expected async iterable to reject with ${expectedType.name}, but got ${(0, node_util_1.inspect)(error)}`,
+        };
+    }
+});
+/**
+ * Asserts that an async iterable rejects with an error satisfying a shape.
+ *
+ * @example
+ *
+ * ```ts
+ * await expectAsync(failingStream, 'to reject with error satisfying', {
+ *   message: 'Connection failed',
+ * });
+ * await expectAsync(
+ *   failingStream,
+ *   'to be rejected with error satisfying',
+ *   {
+ *     code: 'ECONNREFUSED',
+ *   },
+ * );
+ * ```
+ *
+ * @group Async Iterable Assertions
+ * @bupkisAnchor async-iterable-to-reject-with-error-satisfying-any
+ * @bupkisAssertionCategory iterable
+ */
+exports.asyncIterableRejectsWithErrorSatisfyingAssertion = (0, create_js_1.createAsyncAssertion)([
+    schema_js_1.AsyncIterableOrIteratorSchema,
+    [
+        'to reject with error satisfying',
+        'to be rejected with error satisfying',
+    ],
+    schema_js_1.UnknownSchema,
+], async (subject, expectedShape) => {
+    const { completed, error } = await (0, iteration_util_js_1.iterateFullyAsync)(subject);
+    if (completed) {
+        return {
+            message: `Expected async iterable to reject with error satisfying ${(0, node_util_1.inspect)(expectedShape)}, but it completed successfully`,
+        };
+    }
+    const schema = (0, value_to_schema_js_1.valueToSchema)(expectedShape, value_to_schema_js_1.valueToSchemaOptionsForSatisfies);
+    if (!schema.safeParse(error).success) {
+        return {
+            message: `Expected async iterable to reject with error satisfying ${(0, node_util_1.inspect)(expectedShape)}, but got ${(0, node_util_1.inspect)(error)}`,
+        };
+    }
+});
+// =============================================================================
+// Export all async iterable assertions as a tuple
+// =============================================================================
+/**
+ * All asynchronous iterable assertions bundled as a tuple for convenient
+ * registration.
+ */
+exports.AsyncIterableAssertions = [
+    // 'to yield' - any item matches
+    exports.asyncIterableYieldsAssertion,
+    exports.asyncIterableYieldsExhaustivelyAssertion,
+    // 'to yield items' - all items must match
+    exports.asyncIterableYieldsItemsSatisfyingAssertion,
+    exports.asyncIterableYieldsItemsExhaustivelyAssertion,
+    // First/last assertions
+    exports.asyncIterableYieldsFirstAssertion,
+    exports.asyncIterableYieldsFirstExhaustivelyAssertion,
+    exports.asyncIterableYieldsLastAssertion,
+    exports.asyncIterableYieldsLastExhaustivelyAssertion,
+    // Cardinality
+    exports.asyncIterableYieldsCountAssertion,
+    exports.asyncIterableYieldsAtLeastAssertion,
+    exports.asyncIterableYieldsAtMostAssertion,
+    exports.asyncIterableEmptyAssertion,
+    // Sequence
+    exports.asyncIterableYieldsExactlyAssertion,
+    exports.asyncIterableYieldsSequenceSatisfyingAssertion,
+    // Completion/error (async-only)
+    exports.asyncIterableCompletesAssertion,
+    exports.asyncIterableRejectsAssertion,
+    exports.asyncIterableRejectsWithTypeAssertion,
+    exports.asyncIterableRejectsWithErrorSatisfyingAssertion,
+];
+//# sourceMappingURL=async-iterable.js.map