bupkis 0.18.2 → 1.0.0

package/dist/assertion/create.d.cts

@@ -0,0 +1,85 @@
+/**
+ * Assertion creation factory functions with type-safe sync/async separation.
+ *
+ * This module provides the core factory functions for creating both synchronous
+ * and asynchronous assertions in the Bupkis assertion framework. It implements
+ * a dual-creation pattern where `createAssertion()` creates synchronous-only
+ * assertions and `createAsyncAssertion()` creates potentially asynchronous
+ * assertions, using branded Zod schema types to enforce compile-time safety and
+ * prevent accidental mixing of sync and async implementations.
+ *
+ * The module supports two primary assertion implementation types:
+ *
+ * - **Schema-based assertions**: Using {@link z.ZodType Zod schemas} for
+ *   validation
+ * - **Function-based assertions**: Using implementation functions that return
+ *   boolean, void, or Zod schemas for dynamic validation
+ *
+ * @remarks
+ * The factory functions use branded types to distinguish between synchronous
+ * and asynchronous schema implementations at compile time. This prevents
+ * accidentally passing async schemas to sync assertion creators and vice versa,
+ * ensuring type safety throughout the assertion system.
+ * @example Creating a synchronous string assertion:
+ *
+ * ```ts
+ * import { createAssertion } from './create.js';
+ * import { z } from 'zod';
+ *
+ * const stringAssertion = createAssertion(['to be a string'], z.string());
+ * ```
+ *
+ * @example Creating an asynchronous Promise resolution assertion:
+ *
+ * ```ts
+ * import { createAsyncAssertion } from './create.js';
+ *
+ * const promiseAssertion = createAsyncAssertion(
+ *   ['to resolve'],
+ *   async (promise) => {
+ *     try {
+ *       await promise;
+ *       return true;
+ *     } catch {
+ *       return false;
+ *     }
+ *   },
+ * );
+ * ```
+ *
+ * @example Creating parameterized assertions:
+ *
+ * ```ts
+ * import { createAssertion } from './create.js';
+ * import { z } from 'zod';
+ *
+ * const greaterThanAssertion = createAssertion(
+ *   [z.number(), 'to be greater than', z.number()],
+ *   (subject, expected) => subject > expected,
+ * );
+ * ```
+ *
+ * @packageDocumentation
+ * @see {@link AssertionParts} for assertion part structure
+ * @see {@link AssertionSlots} for processed slot definitions
+ * @see {@link AssertionImplSync} for synchronous implementation types
+ * @see {@link AssertionImplAsync} for asynchronous implementation types
+ */
+import { type CreateAssertionFn, type CreateAsyncAssertionFn } from "./assertion-types.cjs";
+/**
+ * {@inheritDoc CreateAssertionFn}
+ *
+ * @function
+ * @throws {TypeError} Invalid assertion implementation type
+ * @group Assertion Creation
+ */
+export declare const createAssertion: CreateAssertionFn;
+/**
+ * {@inheritDoc CreateAsyncAssertionFn}
+ *
+ * @function
+ * @throws {TypeError} Invalid assertion implementation type
+ * @group Assertion Creation
+ */
+export declare const createAsyncAssertion: CreateAsyncAssertionFn;
+//# sourceMappingURL=create.d.ts.map

package/dist/assertion/create.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../src/assertion/create.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkEG;AA0BH,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,sBAAsB,EAC5B,8BAA6B;AAG9B;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,EAAE,iBAmC7B,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,EAAE,sBAmClC,CAAC"}

package/dist/assertion/create.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Assertion creation factory functions with type-safe sync/async separation.
+ *
+ * This module provides the core factory functions for creating both synchronous
+ * and asynchronous assertions in the Bupkis assertion framework. It implements
+ * a dual-creation pattern where `createAssertion()` creates synchronous-only
+ * assertions and `createAsyncAssertion()` creates potentially asynchronous
+ * assertions, using branded Zod schema types to enforce compile-time safety and
+ * prevent accidental mixing of sync and async implementations.
+ *
+ * The module supports two primary assertion implementation types:
+ *
+ * - **Schema-based assertions**: Using {@link z.ZodType Zod schemas} for
+ *   validation
+ * - **Function-based assertions**: Using implementation functions that return
+ *   boolean, void, or Zod schemas for dynamic validation
+ *
+ * @remarks
+ * The factory functions use branded types to distinguish between synchronous
+ * and asynchronous schema implementations at compile time. This prevents
+ * accidentally passing async schemas to sync assertion creators and vice versa,
+ * ensuring type safety throughout the assertion system.
+ * @example Creating a synchronous string assertion:
+ *
+ * ```ts
+ * import { createAssertion } from './create.js';
+ * import { z } from 'zod';
+ *
+ * const stringAssertion = createAssertion(['to be a string'], z.string());
+ * ```
+ *
+ * @example Creating an asynchronous Promise resolution assertion:
+ *
+ * ```ts
+ * import { createAsyncAssertion } from './create.js';
+ *
+ * const promiseAssertion = createAsyncAssertion(
+ *   ['to resolve'],
+ *   async (promise) => {
+ *     try {
+ *       await promise;
+ *       return true;
+ *     } catch {
+ *       return false;
+ *     }
+ *   },
+ * );
+ * ```
+ *
+ * @example Creating parameterized assertions:
+ *
+ * ```ts
+ * import { createAssertion } from './create.js';
+ * import { z } from 'zod';
+ *
+ * const greaterThanAssertion = createAssertion(
+ *   [z.number(), 'to be greater than', z.number()],
+ *   (subject, expected) => subject > expected,
+ * );
+ * ```
+ *
+ * @packageDocumentation
+ * @see {@link AssertionParts} for assertion part structure
+ * @see {@link AssertionSlots} for processed slot definitions
+ * @see {@link AssertionImplSync} for synchronous implementation types
+ * @see {@link AssertionImplAsync} for asynchronous implementation types
+ */
+import { type CreateAssertionFn, type CreateAsyncAssertionFn } from "./assertion-types.js";
+/**
+ * {@inheritDoc CreateAssertionFn}
+ *
+ * @function
+ * @throws {TypeError} Invalid assertion implementation type
+ * @group Assertion Creation
+ */
+export declare const createAssertion: CreateAssertionFn;
+/**
+ * {@inheritDoc CreateAsyncAssertionFn}
+ *
+ * @function
+ * @throws {TypeError} Invalid assertion implementation type
+ * @group Assertion Creation
+ */
+export declare const createAsyncAssertion: CreateAsyncAssertionFn;
+//# sourceMappingURL=create.d.ts.map

package/dist/assertion/create.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../src/assertion/create.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkEG;AA0BH,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,sBAAsB,EAC5B,6BAA6B;AAG9B;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,EAAE,iBAmC7B,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,EAAE,sBAmClC,CAAC"}

package/dist/assertion/create.js

@@ -0,0 +1,143 @@
+/**
+ * Assertion creation factory functions with type-safe sync/async separation.
+ *
+ * This module provides the core factory functions for creating both synchronous
+ * and asynchronous assertions in the Bupkis assertion framework. It implements
+ * a dual-creation pattern where `createAssertion()` creates synchronous-only
+ * assertions and `createAsyncAssertion()` creates potentially asynchronous
+ * assertions, using branded Zod schema types to enforce compile-time safety and
+ * prevent accidental mixing of sync and async implementations.
+ *
+ * The module supports two primary assertion implementation types:
+ *
+ * - **Schema-based assertions**: Using {@link z.ZodType Zod schemas} for
+ *   validation
+ * - **Function-based assertions**: Using implementation functions that return
+ *   boolean, void, or Zod schemas for dynamic validation
+ *
+ * @remarks
+ * The factory functions use branded types to distinguish between synchronous
+ * and asynchronous schema implementations at compile time. This prevents
+ * accidentally passing async schemas to sync assertion creators and vice versa,
+ * ensuring type safety throughout the assertion system.
+ * @example Creating a synchronous string assertion:
+ *
+ * ```ts
+ * import { createAssertion } from './create.js';
+ * import { z } from 'zod';
+ *
+ * const stringAssertion = createAssertion(['to be a string'], z.string());
+ * ```
+ *
+ * @example Creating an asynchronous Promise resolution assertion:
+ *
+ * ```ts
+ * import { createAsyncAssertion } from './create.js';
+ *
+ * const promiseAssertion = createAsyncAssertion(
+ *   ['to resolve'],
+ *   async (promise) => {
+ *     try {
+ *       await promise;
+ *       return true;
+ *     } catch {
+ *       return false;
+ *     }
+ *   },
+ * );
+ * ```
+ *
+ * @example Creating parameterized assertions:
+ *
+ * ```ts
+ * import { createAssertion } from './create.js';
+ * import { z } from 'zod';
+ *
+ * const greaterThanAssertion = createAssertion(
+ *   [z.number(), 'to be greater than', z.number()],
+ *   (subject, expected) => subject > expected,
+ * );
+ * ```
+ *
+ * @packageDocumentation
+ * @see {@link AssertionParts} for assertion part structure
+ * @see {@link AssertionSlots} for processed slot definitions
+ * @see {@link AssertionImplSync} for synchronous implementation types
+ * @see {@link AssertionImplAsync} for asynchronous implementation types
+ */
+import { z } from 'zod';
+import { AssertionImplementationError } from "../error.js";
+import { isFunction, isStandardSchema, isZodType } from "../guards.js";
+import { CreateAssertionInputSchema, CreateAssertionInputSchemaAsync, } from "../internal-schema.js";
+import { BupkisAssertionFunctionAsync, BupkisAssertionSchemaAsync, } from "./assertion-async.js";
+import { BupkisAssertionStandardSchemaAsync } from "./assertion-standard-schema-async.js";
+import { BupkisAssertionStandardSchemaSync } from "./assertion-standard-schema-sync.js";
+import { BupkisAssertionFunctionSync, BupkisAssertionSchemaSync, } from "./assertion-sync.js";
+import { slotify } from "./slotify.js";
+/**
+ * {@inheritDoc CreateAssertionFn}
+ *
+ * @function
+ * @throws {TypeError} Invalid assertion implementation type
+ * @group Assertion Creation
+ */
+export const createAssertion = (parts, impl) => {
+    // Validate inputs using Zod schema
+    try {
+        CreateAssertionInputSchema.parse([parts, impl]);
+    }
+    catch (err) {
+        if (err instanceof z.ZodError) {
+            throw new AssertionImplementationError(`Invalid input parameters: ${z.prettifyError(err)}`, { cause: err });
+        }
+        /* c8 ignore next */
+        throw err;
+    }
+    const slots = slotify(parts);
+    if (isZodType(impl)) {
+        return new BupkisAssertionSchemaSync(parts, slots, impl);
+    }
+    else if (isStandardSchema(impl)) {
+        return new BupkisAssertionStandardSchemaSync(parts, slots, impl);
+    }
+    else if (isFunction(impl)) {
+        return new BupkisAssertionFunctionSync(parts, slots, impl);
+    }
+    // should be impossible if CreateAssertionInputSchema is correct
+    /* c8 ignore next */
+    throw new AssertionImplementationError('Assertion implementation must be a function, Zod schema, or Standard Schema');
+};
+/**
+ * {@inheritDoc CreateAsyncAssertionFn}
+ *
+ * @function
+ * @throws {TypeError} Invalid assertion implementation type
+ * @group Assertion Creation
+ */
+export const createAsyncAssertion = (parts, impl) => {
+    // Validate inputs using Zod schema
+    try {
+        CreateAssertionInputSchemaAsync.parse([parts, impl]);
+    }
+    catch (err) {
+        if (err instanceof z.ZodError) {
+            throw new AssertionImplementationError(`Invalid input parameters: ${z.prettifyError(err)}`, { cause: err });
+        }
+        /* c8 ignore next */
+        throw err;
+    }
+    const slots = slotify(parts);
+    if (isZodType(impl)) {
+        return new BupkisAssertionSchemaAsync(parts, slots, impl);
+    }
+    else if (isStandardSchema(impl)) {
+        return new BupkisAssertionStandardSchemaAsync(parts, slots, impl);
+    }
+    else if (isFunction(impl)) {
+        return new BupkisAssertionFunctionAsync(parts, slots, impl);
+    }
+    // should be impossible if CreateAssertionInputSchemaAsync is correct
+    /* c8 ignore next */
+    throw new AssertionImplementationError('Assertion implementation must be a function, Zod schema, or Standard Schema');
+};
+//# sourceMappingURL=create.js.map

package/dist/assertion/create.js.map

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

package/dist/assertion/format-assertion-failure.cjs

@@ -0,0 +1,63 @@
+"use strict";
+/**
+ * Utility for formatting AssertionFailure objects with custom diff support.
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatAssertionFailure = void 0;
+const diff_js_1 = require("../diff.cjs");
+/**
+ * Formats an AssertionFailure into a diff string for error output.
+ *
+ * Precedence:
+ *
+ * 1. `diff` property - returned as-is
+ * 2. `formatActual`/`formatExpected` - used to serialize values for jest-diff
+ * 3. Default - uses jest-diff with raw actual/expected values
+ *
+ * @function
+ * @param failure - The AssertionFailure to format
+ * @returns Formatted diff string, or null if no diff can be generated
+ */
+const formatAssertionFailure = (failure) => {
+    const { actual, diff, diffOptions, expected, formatActual, formatExpected } = failure;
+    // Precedence 1: Pre-computed diff string
+    if (diff !== undefined) {
+        return diff;
+    }
+    // Need both actual and expected for diff generation
+    if (!(0, diff_js_1.shouldGenerateDiff)(actual, expected)) {
+        return null;
+    }
+    // Precedence 2: Custom formatters
+    // Wrap in try-catch to provide clearer error messages if formatters throw
+    let formattedActual = actual;
+    if (formatActual) {
+        try {
+            formattedActual = formatActual(actual);
+        }
+        catch (error) {
+            throw new Error(`AssertionFailure formatActual threw: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+        }
+    }
+    let formattedExpected = expected;
+    if (formatExpected) {
+        try {
+            formattedExpected = formatExpected(expected);
+        }
+        catch (error) {
+            throw new Error(`AssertionFailure formatExpected threw: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+        }
+    }
+    // Precedence 3: Default jest-diff
+    return (0, diff_js_1.generateDiff)(formattedExpected, formattedActual, {
+        aAnnotation: 'expected',
+        bAnnotation: 'actual',
+        expand: false,
+        includeChangeCounts: true,
+        ...diffOptions,
+    });
+};
+exports.formatAssertionFailure = formatAssertionFailure;
+//# sourceMappingURL=format-assertion-failure.js.map

package/dist/assertion/format-assertion-failure.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-assertion-failure.js","sourceRoot":"","sources":["../../src/assertion/format-assertion-failure.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;AAIH,yCAA8D;AAE9D;;;;;;;;;;;;GAYG;AACI,MAAM,sBAAsB,GAAG,CACpC,OAAyB,EACV,EAAE;IACjB,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,YAAY,EAAE,cAAc,EAAE,GACzE,OAAO,CAAC;IAEV,yCAAyC;IACzC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,oDAAoD;IACpD,IAAI,CAAC,IAAA,4BAAkB,EAAC,MAAM,EAAE,QAAQ,CAAC,EAAE,CAAC;QAC1C,OAAO,IAAI,CAAC;IACd,CAAC;IAED,kCAAkC;IAClC,0EAA0E;IAC1E,IAAI,eAAe,GAAG,MAAM,CAAC;IAC7B,IAAI,YAAY,EAAE,CAAC;QACjB,IAAI,CAAC;YACH,eAAe,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;QACzC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CACb,wCAAwC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,EAChG,EAAE,KAAK,EAAE,KAAK,EAAE,CACjB,CAAC;QACJ,CAAC;IACH,CAAC;IAED,IAAI,iBAAiB,GAAG,QAAQ,CAAC;IACjC,IAAI,cAAc,EAAE,CAAC;QACnB,IAAI,CAAC;YACH,iBAAiB,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAC;QAC/C,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CACb,0CAA0C,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,EAClG,EAAE,KAAK,EAAE,KAAK,EAAE,CACjB,CAAC;QACJ,CAAC;IACH,CAAC;IAED,kCAAkC;IAClC,OAAO,IAAA,sBAAY,EAAC,iBAAiB,EAAE,eAAe,EAAE;QACtD,WAAW,EAAE,UAAU;QACvB,WAAW,EAAE,QAAQ;QACrB,MAAM,EAAE,KAAK;QACb,mBAAmB,EAAE,IAAI;QACzB,GAAG,WAAW;KACf,CAAC,CAAC;AACL,CAAC,CAAC;AAlDW,QAAA,sBAAsB,0BAkDjC"}

package/dist/assertion/format-assertion-failure.d.cts

@@ -0,0 +1,21 @@
+/**
+ * Utility for formatting AssertionFailure objects with custom diff support.
+ *
+ * @packageDocumentation
+ */
+import type { AssertionFailure } from "./assertion-types.cjs";
+/**
+ * Formats an AssertionFailure into a diff string for error output.
+ *
+ * Precedence:
+ *
+ * 1. `diff` property - returned as-is
+ * 2. `formatActual`/`formatExpected` - used to serialize values for jest-diff
+ * 3. Default - uses jest-diff with raw actual/expected values
+ *
+ * @function
+ * @param failure - The AssertionFailure to format
+ * @returns Formatted diff string, or null if no diff can be generated
+ */
+export declare const formatAssertionFailure: (failure: AssertionFailure) => null | string;
+//# sourceMappingURL=format-assertion-failure.d.ts.map

package/dist/assertion/format-assertion-failure.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-assertion-failure.d.ts","sourceRoot":"","sources":["../../src/assertion/format-assertion-failure.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,8BAA6B;AAI7D;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,sBAAsB,GACjC,SAAS,gBAAgB,KACxB,IAAI,GAAG,MAgDT,CAAC"}

package/dist/assertion/format-assertion-failure.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Utility for formatting AssertionFailure objects with custom diff support.
+ *
+ * @packageDocumentation
+ */
+import type { AssertionFailure } from "./assertion-types.js";
+/**
+ * Formats an AssertionFailure into a diff string for error output.
+ *
+ * Precedence:
+ *
+ * 1. `diff` property - returned as-is
+ * 2. `formatActual`/`formatExpected` - used to serialize values for jest-diff
+ * 3. Default - uses jest-diff with raw actual/expected values
+ *
+ * @function
+ * @param failure - The AssertionFailure to format
+ * @returns Formatted diff string, or null if no diff can be generated
+ */
+export declare const formatAssertionFailure: (failure: AssertionFailure) => null | string;
+//# sourceMappingURL=format-assertion-failure.d.ts.map

package/dist/assertion/format-assertion-failure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-assertion-failure.d.ts","sourceRoot":"","sources":["../../src/assertion/format-assertion-failure.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,6BAA6B;AAI7D;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,sBAAsB,GACjC,SAAS,gBAAgB,KACxB,IAAI,GAAG,MAgDT,CAAC"}

package/dist/assertion/format-assertion-failure.js

@@ -0,0 +1,59 @@
+/**
+ * Utility for formatting AssertionFailure objects with custom diff support.
+ *
+ * @packageDocumentation
+ */
+import { generateDiff, shouldGenerateDiff } from "../diff.js";
+/**
+ * Formats an AssertionFailure into a diff string for error output.
+ *
+ * Precedence:
+ *
+ * 1. `diff` property - returned as-is
+ * 2. `formatActual`/`formatExpected` - used to serialize values for jest-diff
+ * 3. Default - uses jest-diff with raw actual/expected values
+ *
+ * @function
+ * @param failure - The AssertionFailure to format
+ * @returns Formatted diff string, or null if no diff can be generated
+ */
+export const formatAssertionFailure = (failure) => {
+    const { actual, diff, diffOptions, expected, formatActual, formatExpected } = failure;
+    // Precedence 1: Pre-computed diff string
+    if (diff !== undefined) {
+        return diff;
+    }
+    // Need both actual and expected for diff generation
+    if (!shouldGenerateDiff(actual, expected)) {
+        return null;
+    }
+    // Precedence 2: Custom formatters
+    // Wrap in try-catch to provide clearer error messages if formatters throw
+    let formattedActual = actual;
+    if (formatActual) {
+        try {
+            formattedActual = formatActual(actual);
+        }
+        catch (error) {
+            throw new Error(`AssertionFailure formatActual threw: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+        }
+    }
+    let formattedExpected = expected;
+    if (formatExpected) {
+        try {
+            formattedExpected = formatExpected(expected);
+        }
+        catch (error) {
+            throw new Error(`AssertionFailure formatExpected threw: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+        }
+    }
+    // Precedence 3: Default jest-diff
+    return generateDiff(formattedExpected, formattedActual, {
+        aAnnotation: 'expected',
+        bAnnotation: 'actual',
+        expand: false,
+        includeChangeCounts: true,
+        ...diffOptions,
+    });
+};
+//# sourceMappingURL=format-assertion-failure.js.map

package/dist/assertion/format-assertion-failure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-assertion-failure.js","sourceRoot":"","sources":["../../src/assertion/format-assertion-failure.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,mBAAmB;AAE9D;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CACpC,OAAyB,EACV,EAAE;IACjB,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,YAAY,EAAE,cAAc,EAAE,GACzE,OAAO,CAAC;IAEV,yCAAyC;IACzC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,oDAAoD;IACpD,IAAI,CAAC,kBAAkB,CAAC,MAAM,EAAE,QAAQ,CAAC,EAAE,CAAC;QAC1C,OAAO,IAAI,CAAC;IACd,CAAC;IAED,kCAAkC;IAClC,0EAA0E;IAC1E,IAAI,eAAe,GAAG,MAAM,CAAC;IAC7B,IAAI,YAAY,EAAE,CAAC;QACjB,IAAI,CAAC;YACH,eAAe,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;QACzC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CACb,wCAAwC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,EAChG,EAAE,KAAK,EAAE,KAAK,EAAE,CACjB,CAAC;QACJ,CAAC;IACH,CAAC;IAED,IAAI,iBAAiB,GAAG,QAAQ,CAAC;IACjC,IAAI,cAAc,EAAE,CAAC;QACnB,IAAI,CAAC;YACH,iBAAiB,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAC;QAC/C,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CACb,0CAA0C,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,EAClG,EAAE,KAAK,EAAE,KAAK,EAAE,CACjB,CAAC;QACJ,CAAC;IACH,CAAC;IAED,kCAAkC;IAClC,OAAO,YAAY,CAAC,iBAAiB,EAAE,eAAe,EAAE;QACtD,WAAW,EAAE,UAAU;QACvB,WAAW,EAAE,QAAQ;QACrB,MAAM,EAAE,KAAK;QACb,mBAAmB,EAAE,IAAI;QACzB,GAAG,WAAW;KACf,CAAC,CAAC;AACL,CAAC,CAAC"}

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

@@ -0,0 +1,68 @@
+"use strict";
+/**
+ * Utility functions for assertion implementations
+ *
+ * @internal
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.trapError = exports.trapPromiseError = exports.trapAsyncFnError = void 0;
+/**
+ * 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
+ */
+const trapAsyncFnError = async (fn) => {
+    try {
+        const result = await fn();
+        return { result };
+    }
+    catch (error) {
+        return {
+            error: error ?? new TypeError(`Function rejected with undefined: ${fn}`),
+        };
+    }
+};
+exports.trapAsyncFnError = trapAsyncFnError;
+/**
+ * Awaits & traps a Promise, capturing any rejection error.
+ *
+ * @function
+ * @param promise The `Promise` to trap
+ * @returns Result object
+ */
+const trapPromiseError = async (promise) => {
+    try {
+        const result = await promise;
+        return { result };
+    }
+    catch (error) {
+        return { error: error ?? new TypeError('Promise rejected with undefined') };
+    }
+};
+exports.trapPromiseError = trapPromiseError;
+/**
+ * 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
+ */
+const trapError = (fn) => {
+    try {
+        const result = fn();
+        return { result };
+    }
+    catch (error) {
+        return { error: error ?? new TypeError(`Function threw undefined: ${fn}`) };
+    }
+};
+exports.trapError = trapError;
+//# sourceMappingURL=assertion-util.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"assertion-util.js","sourceRoot":"","sources":["../../../src/assertion/impl/assertion-util.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAKH;;;;;;;;GAQG;AACI,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;AAXW,QAAA,gBAAgB,oBAW3B;AAEF;;;;;;GAMG;AACI,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;AATW,QAAA,gBAAgB,oBAS3B;AAEF;;;;;;;;;GASG;AACI,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;AAPW,QAAA,SAAS,aAOpB"}

package/dist/assertion/impl/assertion-util.d.cts

@@ -0,0 +1,36 @@
+/**
+ * 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 declare const trapAsyncFnError: (fn: () => unknown) => Promise<TrapResult>;
+/**
+ * Awaits & traps a Promise, capturing any rejection error.
+ *
+ * @function
+ * @param promise The `Promise` to trap
+ * @returns Result object
+ */
+export declare const trapPromiseError: (promise: PromiseLike<unknown>) => Promise<TrapResult>;
+/**
+ * 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 declare const trapError: (fn: () => unknown) => TrapResult;
+//# sourceMappingURL=assertion-util.d.ts.map

package/dist/assertion/impl/assertion-util.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assertion-util.d.ts","sourceRoot":"","sources":["../../../src/assertion/impl/assertion-util.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,GAC3B,IAAI,MAAM,OAAO,KAChB,OAAO,CAAC,UAAU,CASpB,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,GAC3B,SAAS,WAAW,CAAC,OAAO,CAAC,KAC5B,OAAO,CAAC,UAAU,CAOpB,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,SAAS,GAAI,IAAI,MAAM,OAAO,KAAG,UAO7C,CAAC"}

package/dist/assertion/impl/assertion-util.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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 declare const trapAsyncFnError: (fn: () => unknown) => Promise<TrapResult>;
+/**
+ * Awaits & traps a Promise, capturing any rejection error.
+ *
+ * @function
+ * @param promise The `Promise` to trap
+ * @returns Result object
+ */
+export declare const trapPromiseError: (promise: PromiseLike<unknown>) => Promise<TrapResult>;
+/**
+ * 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 declare const trapError: (fn: () => unknown) => TrapResult;
+//# sourceMappingURL=assertion-util.d.ts.map

package/dist/assertion/impl/assertion-util.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assertion-util.d.ts","sourceRoot":"","sources":["../../../src/assertion/impl/assertion-util.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,GAC3B,IAAI,MAAM,OAAO,KAChB,OAAO,CAAC,UAAU,CASpB,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,GAC3B,SAAS,WAAW,CAAC,OAAO,CAAC,KAC5B,OAAO,CAAC,UAAU,CAOpB,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,SAAS,GAAI,IAAI,MAAM,OAAO,KAAG,UAO7C,CAAC"}