bupkis 0.1.2 → 0.3.0

package/src/expect.ts

@@ -1,14 +1,6 @@
 import Debug from 'debug';
 import { inspect } from 'util';
 
-import {
-  type Expect,
-  type ExpectAsync,
-  type ExpectAsyncFunction,
-  type ExpectAsyncProps,
-  type ExpectFunction,
-  type ExpectSyncProps,
-} from './api.js';
 import {
   type AnyAsyncAssertion,
   type AnyAsyncAssertions,
@@ -24,19 +16,160 @@ import {
   type ParsedValues,
 } from './assertion/assertion-types.js';
 import { createAssertion, createAsyncAssertion } from './assertion/create.js';
-import { AssertionError, NegatedAssertionError } from './error.js';
+import {
+  AssertionError,
+  FailAssertionError,
+  NegatedAssertionError,
+} from './error.js';
 import { isAssertionFailure, isString } from './guards.js';
+import {
+  type Expect,
+  type ExpectAsync,
+  type ExpectAsyncFunction,
+  type ExpectAsyncProps,
+  type ExpectFunction,
+  type ExpectSyncProps,
+  type FailFn,
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  type UseFn,
+} from './types.js';
 import { createUse } from './use.js';
 
 const debug = Debug('bupkis:expect');
 
+/**
+ * Creates an asynchronous expect function by extending a parent expectAsync
+ * function with additional assertions.
+ *
+ * This overload combines assertions from an existing parent expectAsync
+ * function with new assertions, creating a unified expectAsync function that
+ * supports both sets of assertions. The resulting function inherits all type
+ * information from both the parent and new assertions, providing complete
+ * TypeScript intellisense and type safety for Promise-based testing scenarios.
+ *
+ * @example
+ *
+ * ```typescript
+ * const baseExpectAsync = createExpectAsyncFunction(basicAsyncAssertions);
+ * const extendedExpectAsync = createExpectAsyncFunction(
+ *   customAsyncAssertions,
+ *   baseExpectAsync,
+ * );
+ *
+ * // Can use both basic and custom async assertions
+ * await extendedExpectAsync(promise, 'to resolve'); // From basic assertions
+ * await extendedExpectAsync(promise, 'to resolve with custom data'); // From custom assertions
+ * ```
+ *
+ * @param assertions - Array of new asynchronous assertion objects to add
+ * @param expect - Parent expectAsync function whose assertions will be
+ *   inherited
+ * @returns ExpectAsync function with combined assertion types from both parent
+ *   and new assertions
+ * @throws {@link AssertionError} When an assertion fails in normal
+ *   (non-negated) mode
+ * @throws {@link NegatedAssertionError} When a negated assertion fails
+ * @throws {Error} When no matching assertion can be found for the provided
+ *   arguments
+ */
 export function createExpectAsyncFunction<
   T extends AnyAsyncAssertions,
   U extends ExpectAsync<AnyAsyncAssertions>,
 >(assertions: T, expect: U): ExpectAsyncFunction<T & U['assertions']>;
+
+/**
+ * Creates a new asynchronous expect function with the provided assertions.
+ *
+ * This overload creates a standalone expectAsync function from the provided
+ * assertions without inheriting from any parent function. This is typically
+ * used to create the initial expectAsync function or when you want a clean
+ * slate without any inherited assertions for Promise-based testing.
+ *
+ * @example
+ *
+ * ```typescript
+ * const expectAsync = createExpectAsyncFunction(asyncAssertions);
+ * await expectAsync(promise, 'to resolve');
+ * await expectAsync(rejectedPromise, 'to reject');
+ * await expectAsync(promise, 'to resolve to', expectedValue);
+ * ```
+ *
+ * @param assertions - Array of asynchronous assertion objects that define the
+ *   available assertion phrases and Promise-based logic
+ * @returns An asynchronous expect function that can execute the provided
+ *   assertions using natural language syntax
+ * @throws {@link AssertionError} When an assertion fails in normal
+ *   (non-negated) mode
+ * @throws {@link NegatedAssertionError} When a negated assertion fails
+ * @throws {Error} When no matching assertion can be found for the provided
+ *   arguments
+ */
 export function createExpectAsyncFunction<T extends AnyAsyncAssertions>(
   assertions: T,
 ): ExpectAsyncFunction<T>;
+
+/**
+ * Implementation function that creates an asynchronous expect function with
+ * optional parent inheritance.
+ *
+ * This is the concrete implementation that handles both overload cases for
+ * Promise-based assertions. It creates an expectAsync function that uses a
+ * two-phase matching algorithm: first seeking exact phrase matches for optimal
+ * performance, then falling back to partial matches if needed. The function
+ * processes negation keywords, combines parent assertions with new ones, and
+ * ensures all operations are properly awaited.
+ *
+ * The matching algorithm prioritizes exact matches to minimize performance
+ * overhead, but provides flexibility through partial matching when exact
+ * phrases don't align. This enables natural language flexibility while
+ * maintaining execution speed for common async assertion patterns.
+ *
+ * @remarks
+ * The function performs async assertion matching in the following order:
+ *
+ * 1. Awaits `Promise.resolve()` to ensure the function is always asynchronous
+ * 2. Processes negation keywords ('not', 'to not') to determine assertion mode
+ * 3. Combines parent assertions (if provided) with new assertions in execution
+ *    order
+ * 4. Attempts to parse arguments against each assertion's expected phrase pattern
+ *    using `parseValuesAsync`
+ * 5. Prioritizes exact phrase matches over partial matches for performance
+ * 6. Executes the first successful match using {@link executeAsync} or throws an
+ *    error if none found
+ *
+ * Performance considerations: The function loops through all available
+ * assertions for each call, but uses early termination when exact matches are
+ * found. For performance-critical code, consider using assertion functions with
+ * fewer total assertions or more specific phrase patterns to reduce matching
+ * overhead.
+ *
+ * All assertion execution is properly awaited to handle Promise-based
+ * validation logic, error handling, and negation scenarios in asynchronous
+ * contexts.
+ * @example
+ *
+ * ```typescript
+ * // Used internally by both public overloads
+ * const expectAsync1 = createExpectAsyncFunction(assertions); // No parent
+ * const expectAsync2 = createExpectAsyncFunction(assertions, parent); // With parent
+ * ```
+ *
+ * @param assertions - Array of asynchronous assertion objects to make available
+ * @param expect - Optional parent expectAsync function to inherit assertions
+ *   from
+ * @returns Asynchronous expect function that processes natural language
+ *   assertions with Promise support
+ * @throws {@link AssertionError} When an assertion fails in normal
+ *   (non-negated) mode
+ * @throws {@link NegatedAssertionError} When a negated assertion fails (e.g.,
+ *   `await expectAsync(promise, 'not to resolve')`)
+ * @throws {Error} When no matching assertion can be found for the provided
+ *   arguments
+ * @internal This is the concrete implementation used by the public overloads
+ * @see {@link createExpectSyncFunction} for creating synchronous expect functions
+ * @see {@link createAsyncAssertion} for creating individual async assertion objects
+ * @see {@link ExpectAsync} for the main expectAsync interface
+ */
 export function createExpectAsyncFunction<
   T extends AnyAsyncAssertions,
   U extends ExpectAsync<AnyAsyncAssertions>,
@@ -87,18 +220,136 @@ export function createExpectAsyncFunction<
   return expectAsyncFunction;
 }
 
+/**
+ * Creates a synchronous expect function by extending a parent expect function
+ * with additional assertions.
+ *
+ * This overload combines assertions from an existing parent expect function
+ * with new assertions, creating a unified expect function that supports both
+ * sets of assertions. The resulting function inherits all type information from
+ * both the parent and new assertions, providing complete TypeScript
+ * intellisense and type safety.
+ *
+ * @example
+ *
+ * ```typescript
+ * const baseExpect = createExpectSyncFunction(basicAssertions);
+ * const extendedExpect = createExpectSyncFunction(
+ *   customAssertions,
+ *   baseExpect,
+ * );
+ *
+ * // Can use both basic and custom assertions
+ * extendedExpect(42, 'to be a number'); // From basic assertions
+ * extendedExpect(obj, 'to have custom prop'); // From custom assertions
+ * ```
+ *
+ * @param assertions - Array of new synchronous assertion objects to add
+ * @param expect - Parent expect function whose assertions will be inherited
+ * @returns Expect function with combined assertion types from both parent and
+ *   new assertions
+ * @throws {@link AssertionError} When an assertion fails in normal
+ *   (non-negated) mode
+ * @throws {@link NegatedAssertionError} When a negated assertion fails
+ * @throws {Error} When no matching assertion can be found for the provided
+ *   arguments
+ */
 export function createExpectSyncFunction<
-  T extends AnySyncAssertions,
-  U extends Expect<AnySyncAssertions>,
->(assertions: T, expect: U): ExpectFunction<T & U['assertions']>;
+  Assertions extends AnySyncAssertions,
+  ParentExpect extends Expect<AnySyncAssertions>,
+>(
+  assertions: Assertions,
+  expect: ParentExpect,
+): ExpectFunction<Assertions & ParentExpect['assertions']>;
 
-export function createExpectSyncFunction<T extends AnySyncAssertions>(
-  assertions: T,
-): ExpectFunction<T>;
+/**
+ * Creates a new synchronous expect function with the provided assertions.
+ *
+ * This overload creates a standalone expect function from the provided
+ * assertions without inheriting from any parent function. This is typically
+ * used to create the initial expect function or when you want a clean slate
+ * without any inherited assertions.
+ *
+ * @example
+ *
+ * ```typescript
+ * const expect = createExpectSyncFunction(basicAssertions);
+ * expect(42, 'to be a number');
+ * expect('hello', 'to be a string');
+ * expect([], 'to be empty');
+ * ```
+ *
+ * @param assertions - Array of synchronous assertion objects that define the
+ *   available assertion phrases and logic
+ * @returns A synchronous expect function that can execute the provided
+ *   assertions using natural language syntax
+ * @throws {@link AssertionError} When an assertion fails in normal
+ *   (non-negated) mode
+ * @throws {@link NegatedAssertionError} When a negated assertion fails
+ * @throws {Error} When no matching assertion can be found for the provided
+ *   arguments
+ */
+export function createExpectSyncFunction<Assertions extends AnySyncAssertions>(
+  assertions: Assertions,
+): ExpectFunction<Assertions>;
+
+/**
+ * Implementation function that creates a synchronous expect function with
+ * optional parent inheritance.
+ *
+ * This is the concrete implementation that handles both overload cases. It
+ * creates an expect function that uses a two-phase matching algorithm: first
+ * seeking exact phrase matches for optimal performance, then falling back to
+ * partial matches if needed. The function processes negation keywords and
+ * combines parent assertions with new ones.
+ *
+ * The matching algorithm prioritizes exact matches to minimize performance
+ * overhead, but provides flexibility through partial matching when exact
+ * phrases don't align. This enables natural language flexibility while
+ * maintaining execution speed for common assertion patterns.
+ *
+ * @remarks
+ * The function performs assertion matching in the following order:
+ *
+ * 1. Processes negation keywords ('not', 'to not') to determine assertion mode
+ * 2. Combines parent assertions (if provided) with new assertions in execution
+ *    order
+ * 3. Attempts to parse arguments against each assertion's expected phrase pattern
+ * 4. Prioritizes exact phrase matches over partial matches for performance
+ * 5. Executes the first successful match or throws an error if none found
+ *
+ * Performance considerations: The function loops through all available
+ * assertions for each call, but uses early termination when exact matches are
+ * found. For performance-critical code, consider using assertion functions with
+ * fewer total assertions or more specific phrase patterns to reduce matching
+ * overhead.
+ * @example
+ *
+ * ```typescript
+ * // Used internally by both public overloads
+ * const expect1 = createExpectSyncFunction(assertions); // No parent
+ * const expect2 = createExpectSyncFunction(assertions, parent); // With parent
+ * ```
+ *
+ * @param assertions - Array of synchronous assertion objects to make available
+ * @param expect - Optional parent expect function to inherit assertions from
+ * @returns Synchronous expect function that processes natural language
+ *   assertions
+ * @throws {@link AssertionError} When an assertion fails in normal
+ *   (non-negated) mode
+ * @throws {@link NegatedAssertionError} When a negated assertion fails (e.g.,
+ *   `expect(42, 'not to be a number')`)
+ * @throws {Error} When no matching assertion can be found for the provided
+ *   arguments
+ * @internal This is the concrete implementation used by the public overloads
+ * @see {@link createExpectAsyncFunction} for creating asynchronous expect functions
+ * @see {@link createAssertion} for creating individual assertion objects
+ * @see {@link Expect} for the main expect interface
+ */
 export function createExpectSyncFunction<
-  T extends AnySyncAssertions,
-  U extends Expect<AnySyncAssertions>,
->(assertions: T, expect?: U) {
+  Assertions extends AnySyncAssertions,
+  ParentExpect extends Expect<AnySyncAssertions>,
+>(assertions: Assertions, expect?: ParentExpect) {
   debug(
     'Creating expect function with %d assertions',
     assertions.length + (expect?.assertions.length ?? 0),
@@ -330,10 +581,14 @@ const detectNegation = (
   };
 };
 
-const fail = (reason?: string): never => {
-  throw new AssertionError({ message: reason });
+const fail: FailFn = (reason?: string): never => {
+  throw new FailAssertionError({ message: reason });
 };
 
+/**
+ * Used by a {@link UseFn} to create base properties of the {@link Expect} and
+ * {@link ExpectAsync} functions.
+ */
 export function createBaseExpect<
   T extends AnySyncAssertions,
   U extends AnyAsyncAssertions,

package/src/guards.ts

@@ -2,52 +2,91 @@
  * Type guard functions and runtime type checking utilities.
  *
  * This module provides various type guard functions for runtime type checking,
- * including guards for Zod schemas, constructors, Promise-like objects, and
- * assertion parts. These are used throughout the library for safe type
+ * including guards for Zod schemas, constructors, {@link PromiseLike} objects,
+ * and assertion parts. These are used throughout the library for safe type
  * narrowing and validation.
  *
+ * @category API
+ * @example
+ *
+ * ```ts
+ * import * as guards from 'bupkis/guards';
+ * ```
+ *
  * @packageDocumentation
  */
 
 import { type Primitive } from 'type-fest';
-import { z } from 'zod';
+import { z } from 'zod/v4';
 
 import type {
   AssertionFailure,
   AssertionPart,
   PhraseLiteralChoice,
 } from './assertion/assertion-types.js';
-import type { Constructor } from './types.js';
+import type { Constructor, ZodTypeMap } from './types.js';
 
 /**
- * Returns true if the given value looks like a Zod schema (v4), determined by
- * the presence of an internal `def.type` field.
+ * Returns `true` if the given value looks like a Zod v4 schema, determined by
+ * the presence of an internal {@link z.core.$ZodTypeDef} field.
  *
  * Note: This relies on Zod's internal shape and is intended for runtime
  * discrimination within this library.
  *
- * @template T
+ * @template T - The specific ZodType to check for (based on def.type)
  * @param value - Value to test
- * @returns Whether the value is Zod-like
+ * @returns Whether the value is `ZodType`-like
  */
-export const isZodType = (value: unknown): value is z.ZodType =>
-  !!(
-    value &&
-    typeof value === 'object' &&
+export function isZodType<T extends keyof ZodTypeMap>(
+  value: unknown,
+  type: T,
+): value is ZodTypeMap[T];
+/**
+ * Returns `true` if the given value looks like a Zod v4 schema, determined by
+ * the presence of an internal {@link z.core.$ZodTypeDef} field.
+ *
+ * Note: This relies on Zod's internal shape and is intended for runtime
+ * discrimination within this library.
+ *
+ * @param value - Value to test
+ * @returns Whether the value is `ZodType`-like
+ */
+export function isZodType(value: unknown): value is z.ZodType;
+export function isZodType<T extends keyof ZodTypeMap>(
+  value: unknown,
+  type?: T,
+): value is T extends keyof ZodTypeMap ? ZodTypeMap[T] : z.ZodType {
+  const isValid =
+    isObject(value) &&
     'def' in value &&
-    value.def &&
+    !!value.def &&
     typeof value.def === 'object' &&
-    'type' in value.def
-  );
+    'type' in value.def;
+
+  if (!isValid) return false;
+  if (type === undefined) return true;
+
+  return (value as z.ZodType).def.type === type;
+}
 
 /**
- * Returns true if the given value is a {@link z.ZodPromise} schema.
+ * Type guard for a plain object.
+ *
+ * @param value Value to test
+ * @returns `true` if the value is a plain object, `false` otherwise
+ */
+export const isObject = (value: unknown): value is NonNullable<object> => {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+};
+
+/**
+ * Returns `true` if the given value is a {@link z.ZodPromise} schema.
  *
  * @param value - Value to test
  * @returns `true` if the value is a `ZodPromise` schema; `false` otherwise
  */
 export const isZodPromise = (value: unknown): value is z.ZodPromise =>
-  isZodType(value) && value.def.type === 'promise';
+  isZodType(value, 'promise');
 
 /**
  * Checks if a value is "promise-like", meaning it is a "thenable" object.
@@ -56,23 +95,24 @@ export const isZodPromise = (value: unknown): value is z.ZodPromise =>
  * @returns `true` if the value is promise-like, `false` otherwise
  */
 export const isPromiseLike = (value: unknown): value is PromiseLike<unknown> =>
-  !!(
-    value &&
-    typeof value === 'object' &&
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
-    typeof (value as any).then === 'function'
-  );
+  isObject(value) && 'then' in value && isFunction(value.then);
 
 /**
- * Returns true if the given value is a constructable function (i.e., a class).
+ * Returns `true` if the given value is a constructable function (i.e., a
+ * class).
  *
- * This may be the only way we can determine, at runtime, if a function is a
- * constructor without actually calling it.
+ * This works by wrapping `fn` in a {@link Proxy}, attaching a no-op
+ * {@link ProxyHandler.construct} trap to it, then attempting to construct the
+ * proxy via `new`.
  *
+ * @privateRemarks
+ * This may be the only way we can determine, at runtime, if a function is a
+ * constructor without actually calling it. I am unsure if this only works for
+ * classes.
  * @param fn - Function to test
  * @returns Whether the function is constructable
  */
-export const isConstructable = (fn: unknown): fn is Constructor => {
+export const isConstructible = (fn: unknown): fn is Constructor => {
   if (fn === Symbol || fn === BigInt) {
     return false;
   }
@@ -121,14 +161,16 @@ const AssertionFailureSchema: z.ZodType<AssertionFailure> = z.object({
     .describe('A human-readable message describing the failure'),
 });
 
+/**
+ * Type guard for a {@link AssertionFailure} object
+ *
+ * @param value Value to check
+ * @returns `true` if the value is an `AssertionFailure`, `false` otherwise
+ * @internal
+ */
 export const isAssertionFailure = (value: unknown): value is AssertionFailure =>
   AssertionFailureSchema.safeParse(value).success;
 
-export const isAsyncFunction = (
-  value: unknown,
-): value is (...args: any[]) => Promise<any> =>
-  isFunction(value) && value.constructor.name === 'AsyncFunction';
-
 /**
  * Type guard for a string value
  *
@@ -179,43 +221,6 @@ export const isPhraseLiteralChoice = (
 export const isPhraseLiteral = (value: AssertionPart): value is string =>
   isString(value) && !value.startsWith('not ');
 
-export type PrimitiveTypeName =
-  | 'bigint'
-  | 'boolean'
-  | 'function'
-  | 'null'
-  | 'number'
-  | 'object'
-  | 'string'
-  | 'symbol'
-  | 'undefined';
-
-export type PrimitiveTypeNameToType<T extends PrimitiveTypeName> =
-  T extends 'undefined'
-    ? undefined
-    : T extends 'object'
-      ? null | object
-      : T extends 'function'
-        ? (...args: any[]) => any
-        : T extends 'string'
-          ? string
-          : T extends 'number'
-            ? number
-            : T extends 'boolean'
-              ? boolean
-              : T extends 'bigint'
-                ? bigint
-                : T extends 'symbol'
-                  ? symbol
-                  : never;
-
-export const isType = <T extends PrimitiveTypeName>(
-  a: unknown,
-  b: T,
-): a is PrimitiveTypeNameToType<T> => {
-  return typeof a === b;
-};
-
 export const isA = <T extends Constructor>(
   value: unknown,
   ctor: T,

package/src/index.ts

@@ -6,24 +6,85 @@
  * guards, schema definitions, utility functions, and error types.
  *
  * @module bupkis
+ * @category API
+ * @example
+ *
+ * ```ts
+ * import { expect, expectAsync, z, createAssertion } from 'bupkis';
+ * ```
+ *
+ * @showGroups
  */
 
-import { expect as sacrificialExpect } from './bootstrap.js';
-export type * from './api.js';
+import { z } from 'zod/v4';
 
-export * as assertion from './assertion/index.js';
+import { expect as sacrificialExpect } from './bootstrap.js';
 export { expect, expectAsync } from './bootstrap.js';
 
-export * as error from './error.js';
-export * as guards from './guards.js';
+export { AssertionError } from './error.js';
 
-export type * as metadata from './metadata.js';
-export * as schema from './schema.js';
+/**
+ * Re-export of most (all?) types defined within <span
+ * class="bupkis">Bupkis</span>.
+ *
+ * @example
+ *
+ * ```ts
+ * import { types } from 'bupkis';
+ * ```
+ */
 export type * as types from './types.js';
-export * as util from './util.js';
 
-export { z } from 'zod/v4';
+/**
+ * Re-export of {@link https://zod.dev Zod v4} for use in custom assertion
+ * implementations.
+ */
+export { z };
 
+/**
+ * @primaryExport
+ */
+export type {
+  Bupkis,
+  CreateAssertionFn,
+  CreateAsyncAssertionFn,
+  Expect,
+  ExpectAsync,
+  FailFn,
+  UseFn,
+  ZodTypeMap,
+} from './types.js';
 export { createAssertion, createAsyncAssertion, fail, use };
-const { createAssertion, createAsyncAssertion, fail, use, ..._rest } =
-  sacrificialExpect;
+const {
+  /**
+   * The main factory function for creating asynchronous assertions.
+   *
+   * Exported from the entry point; is also a property of {@link Expect} and
+   * {@link ExpectAsync}.
+   *
+   * @function
+   */
+  createAssertion,
+  /**
+   * The main factory function for creating asynchronous assertions.
+   *
+   * Exported from the entry point; is also a property of {@link Expect} and
+   * {@link ExpectAsync}.
+   *
+   * @function
+   */
+  createAsyncAssertion,
+  /**
+   * {@inheritDoc FailFn}
+   *
+   * @function
+   */
+  fail,
+  /**
+   * {@inheritDoc UseFn}
+   *
+   * @function
+   */
+  use,
+  ..._rest
+} = sacrificialExpect;

package/src/metadata.ts

@@ -2,18 +2,17 @@
  * Defines Bupkis' Zod metadata registry
  *
  * @packageDocumentation
+ * @internal
  */
 
-import { z } from 'zod';
+import { z } from 'zod/v4';
 
 import { kStringLiteral } from './constant.js';
 
 /**
  * Metadata stored in Zod registry
- *
- * @knipignore
  */
-export type BupkisMeta = z.infer<typeof BupkisRegistrySchema>;
+type BupkisMeta = z.infer<typeof BupkisRegistrySchema>;
 
 /**
  * Zod metadata registry for Bupkis