bupkis 0.0.2

package/src/constant.ts

@@ -0,0 +1,37 @@
+/**
+ * Shared constants and symbols used throughout the library.
+ *
+ * This module defines unique symbols and constants that are used internally for
+ * marking and identifying special values and types within the assertion
+ * system.
+ *
+ * @packageDocumentation
+ * @internal
+ */
+
+/**
+ * Symbol flagging the value as a Bupkis-created string literal, which will be
+ * omitted from the parameters to an `AssertionImpl`.
+ *
+ * @internal
+ */
+
+export const kStringLiteral: unique symbol = Symbol('bupkis:string-literal');
+
+/**
+ * Symbol used to flag an `AssertionError` as our own.
+ *
+ * @internal
+ */
+
+export const kBupkisAssertionError: unique symbol = Symbol('bupkis-error');
+
+/**
+ * Symbol used to flag a `NegatedAssertionError`
+ *
+ * @internal
+ */
+
+export const kBupkisNegatedAssertionError: unique symbol = Symbol(
+  'bupkis-negated-error',
+);

package/src/error.ts

@@ -0,0 +1,47 @@
+/**
+ * Error types thrown by _BUPKIS_, including {@link AssertionError}.
+ *
+ * @privateRemarks
+ * Other custom errors should go here.
+ * @packageDocumentation
+ */
+
+import { AssertionError as NodeAssertionError } from 'node:assert';
+
+import {
+  kBupkisAssertionError,
+  kBupkisNegatedAssertionError,
+} from './constant.js';
+import { isA } from './guards.js';
+
+/**
+ * _BUPKIS_' s custom `AssertionError` class, which is just a thin wrapper
+ * around Node.js' {@link NodeAssertionError AssertionError}.
+ *
+ * @public
+ */
+export class AssertionError extends NodeAssertionError {
+  [kBupkisAssertionError] = true;
+
+  static isAssertionError(err: unknown): err is AssertionError {
+    return (
+      isA(err, NodeAssertionError) && Object.hasOwn(err, kBupkisAssertionError)
+    );
+  }
+}
+
+/**
+ * Error type used internally to catch failed negated assertions.
+ *
+ * @internal
+ */
+export class NegatedAssertionError extends AssertionError {
+  [kBupkisNegatedAssertionError] = true;
+
+  static isNegatedAssertionError(err: unknown): err is NegatedAssertionError {
+    return (
+      isA(err, AssertionError) &&
+      Object.hasOwn(err, kBupkisNegatedAssertionError)
+    );
+  }
+}

package/src/expect.ts

@@ -0,0 +1,364 @@
+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,
+  type AnySyncAssertion,
+  type AnySyncAssertions,
+  type AssertionAsync,
+  type AssertionImplAsync,
+  type AssertionImplSync,
+  type AssertionParts,
+  type AssertionSlots,
+  type AssertionSync,
+  type ParsedResult,
+  type ParsedValues,
+} from './assertion/assertion-types.js';
+import { createAssertion, createAsyncAssertion } from './assertion/create.js';
+import { AssertionError, NegatedAssertionError } from './error.js';
+import { isAssertionFailure, isString } from './guards.js';
+import { createUse } from './use.js';
+
+const debug = Debug('bupkis:expect');
+
+export function createExpectAsyncFunction<
+  T extends AnyAsyncAssertions,
+  U extends ExpectAsync<AnyAsyncAssertions>,
+>(assertions: T, expect: U): ExpectAsyncFunction<T & U['assertions']>;
+export function createExpectAsyncFunction<T extends AnyAsyncAssertions>(
+  assertions: T,
+): ExpectAsyncFunction<T>;
+export function createExpectAsyncFunction<
+  T extends AnyAsyncAssertions,
+  U extends ExpectAsync<AnyAsyncAssertions>,
+>(assertions: T, expect?: U) {
+  debug(
+    'Creating expectAsync function with %d assertions',
+    assertions.length + (expect?.assertions.length ?? 0),
+  );
+  const expectAsyncFunction = async (...args: readonly unknown[]) => {
+    await Promise.resolve();
+    const [isNegated, processedArgs] = maybeProcessNegation(args);
+    const candidates: Array<{
+      assertion: AnyAsyncAssertion;
+      parseResult: ParsedResult<AssertionParts>;
+    }> = [];
+    for (const assertion of [...(expect?.assertions ?? []), ...assertions]) {
+      const parseResult = await assertion.parseValuesAsync(processedArgs);
+      const { exactMatch, parsedValues, success } = parseResult;
+
+      if (success) {
+        if (exactMatch) {
+          return executeAsync(
+            assertion,
+            parsedValues,
+            [...args],
+            expectAsyncFunction,
+            isNegated,
+            parseResult,
+          );
+        }
+        candidates.push({ assertion, parseResult });
+      }
+    }
+    if (candidates.length) {
+      const { assertion, parseResult } = candidates[0]!;
+      return executeAsync(
+        assertion as any,
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+        parseResult.parsedValues as any,
+        [...args],
+        expectAsyncFunction,
+        isNegated,
+        parseResult,
+      );
+    }
+    throwInvalidParametersError(args);
+  };
+  return expectAsyncFunction;
+}
+
+export function createExpectSyncFunction<
+  T extends AnySyncAssertions,
+  U extends Expect<AnySyncAssertions>,
+>(assertions: T, expect: U): ExpectFunction<T & U['assertions']>;
+
+export function createExpectSyncFunction<T extends AnySyncAssertions>(
+  assertions: T,
+): ExpectFunction<T>;
+export function createExpectSyncFunction<
+  T extends AnySyncAssertions,
+  U extends Expect<AnySyncAssertions>,
+>(assertions: T, expect?: U) {
+  debug(
+    'Creating expect function with %d assertions',
+    assertions.length + (expect?.assertions.length ?? 0),
+  );
+  const expectFunction = (...args: readonly unknown[]) => {
+    const [isNegated, processedArgs] = maybeProcessNegation(args);
+    const candidates: Array<{
+      assertion: AnySyncAssertion;
+      parseResult: ParsedResult<AssertionParts>;
+    }> = [];
+    for (const assertion of [...(expect?.assertions ?? []), ...assertions]) {
+      const parseResult = assertion.parseValues(processedArgs);
+      const { exactMatch, parsedValues, success } = parseResult;
+
+      if (success) {
+        if (exactMatch) {
+          return execute(
+            assertion,
+            parsedValues,
+            [...args],
+            expectFunction,
+            isNegated,
+            parseResult,
+          );
+        }
+        candidates.push({ assertion, parseResult });
+      }
+    }
+    if (candidates.length) {
+      const { assertion, parseResult } = candidates[0]!;
+      return execute(
+        assertion as any,
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+        parseResult.parsedValues as any,
+        [...args],
+        expectFunction,
+        isNegated,
+        parseResult,
+      );
+    }
+    throwInvalidParametersError(args);
+  };
+  return expectFunction;
+}
+
+/**
+ * Executes an assertion with optional negation logic.
+ *
+ * @privateRemarks
+ * This is here because `Assertion` doesn't know anything about negation and
+ * probably shouldn't.
+ * @param assertion - The assertion to execute
+ * @param parsedValues - Parsed values for the assertion
+ * @param args - Original arguments passed to expect
+ * @param stackStartFn - Function for stack trace management
+ * @param isNegated - Whether the assertion should be negated
+ */
+const execute = <
+  T extends AssertionSync<Parts, AssertionImplSync<Parts>, Slots>,
+  Parts extends AssertionParts,
+  Slots extends AssertionSlots<Parts>,
+>(
+  assertion: T,
+  parsedValues: ParsedValues<Parts>,
+  args: unknown[],
+  stackStartFn: (...args: any[]) => any,
+  isNegated: boolean,
+  parseResult?: ParsedResult<Parts>,
+): void => {
+  if (!isNegated) {
+    return assertion.execute(parsedValues, args, stackStartFn, parseResult);
+  }
+
+  try {
+    debug('Executing negated assertion: %s', assertion);
+    const result = assertion.execute(
+      parsedValues,
+      args,
+      stackStartFn,
+      parseResult,
+    );
+    if (isAssertionFailure(result)) {
+      throw new NegatedAssertionError({
+        actual: result.actual,
+        expected: result.expected,
+        message:
+          result.message ??
+          `Expected assertion ${assertion} to fail (due to negation), but it passed`,
+        stackStartFn,
+      });
+    }
+    // If we reach here, the assertion passed but we expected it to fail
+    throw new NegatedAssertionError({
+      message: `Expected assertion to fail (due to negation), but it passed: ${assertion}`,
+      stackStartFn,
+    });
+  } catch (error) {
+    // Check if this is the negation error we just threw
+    if (NegatedAssertionError.isNegatedAssertionError(error)) {
+      // This is our negation error, re-throw it
+      throw error;
+    }
+
+    if (AssertionError.isAssertionError(error)) {
+      // The assertion failed as expected for negation - this is success
+      return;
+    }
+
+    debug('Non-assertion error thrown during negated assertion: %O', error);
+    // Re-throw non-assertion errors (like TypeErrors, etc.)
+    throw error;
+  }
+};
+
+/**
+ * Executes an assertion with optional negation logic (async version).
+ *
+ * @privateRemarks
+ * This is here because `Assertion` doesn't know anything about negation and
+ * probably shouldn't.
+ * @param assertion - The assertion to execute
+ * @param parsedValues - Parsed values for the assertion
+ * @param args - Original arguments passed to expectAsync
+ * @param stackStartFn - Function for stack trace management
+ * @param isNegated - Whether the assertion should be negated
+ */
+export const executeAsync = async <
+  T extends AssertionAsync<Parts, AssertionImplAsync<Parts>, Slots>,
+  Parts extends AssertionParts,
+  Slots extends AssertionSlots<Parts>,
+>(
+  assertion: T,
+  parsedValues: ParsedValues<Parts>,
+  args: unknown[],
+  stackStartFn: (...args: any[]) => any,
+  isNegated: boolean,
+  parseResult?: ParsedResult<Parts>,
+): Promise<void> => {
+  if (!isNegated) {
+    return assertion.executeAsync(
+      parsedValues,
+      args,
+      stackStartFn,
+      parseResult,
+    );
+  }
+
+  try {
+    debug('Executing negated async assertion: %s', assertion);
+    await assertion.executeAsync(parsedValues, args, stackStartFn, parseResult);
+    // If we reach here, the assertion passed but we expected it to fail
+    throw new NegatedAssertionError({
+      message: `Expected assertion to fail (due to negation), but it passed: ${assertion}`,
+      stackStartFn,
+    });
+  } catch (error) {
+    // Check if this is the negation error we just threw
+    if (NegatedAssertionError.isNegatedAssertionError(error)) {
+      // This is our negation error, re-throw it
+      throw error;
+    }
+
+    if (AssertionError.isAssertionError(error)) {
+      // The assertion failed as expected for negation - this is success
+      return;
+    }
+    debug(
+      'Non-assertion error thrown during negated async assertion: %O',
+      error,
+    );
+    // Re-throw non-assertion errors (like TypeErrors, etc.)
+    throw error;
+  }
+};
+
+/**
+ * @internal
+ */
+const maybeProcessNegation = (
+  args: readonly unknown[],
+): [isNegated: boolean, processedArgs: readonly unknown[]] => {
+  let isNegated = false;
+  let processedArgs = args;
+
+  if (args.length >= 2 && isString(args[1])) {
+    const { cleanedPhrase, isNegated: detected } = detectNegation(args[1]);
+    if (detected) {
+      isNegated = true;
+      processedArgs = [args[0], cleanedPhrase, ...args.slice(2)];
+    }
+  }
+  return [isNegated, processedArgs];
+};
+
+/**
+ * @internal
+ */
+const throwInvalidParametersError = (args: readonly unknown[]): never => {
+  const inspectedArgs = inspect(args, { depth: 1 });
+  debug(`Invalid arguments. No assertion matched: ${inspectedArgs}`);
+  throw new TypeError(
+    `Invalid arguments. No assertion matched: ${inspectedArgs}`,
+  );
+};
+
+/**
+ * Detects if an assertion phrase starts with "not " and returns the cleaned
+ * phrase.
+ *
+ * @param phrase - The assertion phrase to check
+ * @returns Object with `isNegated` flag and `cleanedPhrase`
+ */
+
+const detectNegation = (
+  phrase: string,
+): {
+  cleanedPhrase: string;
+  isNegated: boolean;
+} => {
+  if (phrase.startsWith('not ')) {
+    return {
+      cleanedPhrase: phrase.substring(4), // Remove "not "
+      isNegated: true,
+    };
+  }
+  return {
+    cleanedPhrase: phrase,
+    isNegated: false,
+  };
+};
+
+const fail = (reason?: string): never => {
+  throw new AssertionError({ message: reason });
+};
+
+export function createBaseExpect<
+  T extends AnySyncAssertions,
+  U extends AnyAsyncAssertions,
+>(syncAssertions: T, asyncAssertions: U, type: 'sync'): ExpectSyncProps<T, U>;
+export function createBaseExpect<
+  T extends AnySyncAssertions,
+  U extends AnyAsyncAssertions,
+>(syncAssertions: T, asyncAssertions: U, type: 'async'): ExpectAsyncProps<U, T>;
+export function createBaseExpect<
+  T extends AnySyncAssertions,
+  U extends AnyAsyncAssertions,
+>(syncAssertions: T, asyncAssertions: U, type: 'async' | 'sync') {
+  return type === 'sync'
+    ? {
+        assertions: syncAssertions,
+        createAssertion,
+        createAsyncAssertion,
+        fail,
+        use: createUse(syncAssertions, asyncAssertions),
+      }
+    : {
+        assertions: asyncAssertions,
+        createAssertion,
+        createAsyncAssertion,
+        fail,
+        use: createUse(syncAssertions, asyncAssertions),
+      };
+}

package/src/guards.ts

@@ -0,0 +1,223 @@
+/**
+ * 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
+ * narrowing and validation.
+ *
+ * @packageDocumentation
+ */
+
+import { type Primitive } from 'type-fest';
+import { z } from 'zod';
+
+import type {
+  AssertionFailure,
+  AssertionPart,
+  PhraseLiteralChoice,
+} from './assertion/assertion-types.js';
+import type { Constructor } 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.
+ *
+ * Note: This relies on Zod's internal shape and is intended for runtime
+ * discrimination within this library.
+ *
+ * @template T
+ * @param value - Value to test
+ * @returns Whether the value is Zod-like
+ */
+export const isZodType = (value: unknown): value is z.ZodType =>
+  !!(
+    value &&
+    typeof value === 'object' &&
+    'def' in value &&
+    value.def &&
+    typeof value.def === 'object' &&
+    'type' in value.def
+  );
+
+/**
+ * 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';
+
+/**
+ * Checks if a value is "promise-like", meaning it is a "thenable" object.
+ *
+ * @param value - Value to test
+ * @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'
+  );
+
+/**
+ * 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.
+ *
+ * @param fn - Function to test
+ * @returns Whether the function is constructable
+ */
+export const isConstructable = (fn: any): fn is Constructor => {
+  try {
+    // this will throw if there is no `[[construct]]` slot.. or so I've heard.
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+    new new Proxy(fn, { construct: () => ({}) })();
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * Type guard for a boolean value
+ *
+ * @param value Value to check
+ * @returns `true` if the value is a boolean, `false` otherwise
+ */
+export const isBoolean = (value: unknown): value is boolean =>
+  typeof value === 'boolean';
+
+/**
+ * Type guard for a function value
+ *
+ * @param value Value to check
+ * @returns `true` if the value is a function, `false` otherwise
+ */
+export const isFunction = (value: unknown): value is (...args: any[]) => any =>
+  typeof value === 'function';
+
+const AssertionFailureSchema: z.ZodType<AssertionFailure> = z.object({
+  actual: z
+    .unknown()
+    .optional()
+    .describe('The actual value or description of what actually occurred'),
+  expected: z
+    .unknown()
+    .optional()
+    .describe(
+      'The expected value or description of what was expected to occur',
+    ),
+  message: z
+    .string()
+    .optional()
+    .describe('A human-readable message describing the failure'),
+});
+
+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
+ *
+ * @param value Value to check
+ * @returns `true` if the value is a string, `false` otherwise
+ */
+export const isString = (value: unknown): value is string =>
+  typeof value === 'string';
+
+/**
+ * Type guard for a non-null object value
+ *
+ * @param value Value to check
+ * @returns `true` if the value is an object and not null, `false` otherwise
+ */
+export const isNonNullObject = (value: unknown): value is object =>
+  typeof value === 'object' && value !== null;
+
+/**
+ * Type guard for a null or non-object value
+ *
+ * @param value Value to check
+ * @returns `true` if the value is null or not an object, `false` otherwise
+ */
+export const isNullOrNonObject = (value: unknown): value is null | Primitive =>
+  typeof value !== 'object' || value === null;
+
+/**
+ * Type guard for a {@link PhraseLiteralChoice}, which is a tuple of strings.
+ *
+ * @param value Assertion part to check
+ * @returns `true` if the part is a `PhraseLiteralChoice`, `false` otherwise
+ * @internal
+ */
+export const isPhraseLiteralChoice = (
+  value: AssertionPart,
+): value is PhraseLiteralChoice =>
+  Array.isArray(value) && value.every(isPhraseLiteral);
+
+/**
+ * Type guard for a {@link PhraseLiteral}, which is just a string that does not
+ * begin with `not `.
+ *
+ * @param value Assertion part to check
+ * @returns `true` if the part is a `PhraseLiteral`, `false` otherwise
+ * @internal
+ */
+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,
+): value is InstanceType<T> => {
+  return isNonNullObject(value) && value instanceof ctor;
+};
+
+export const isError = (value: unknown): value is Error => isA(value, Error);

package/src/index.ts

@@ -0,0 +1,29 @@
+/**
+ * Main entry point for the Bupkis assertion library.
+ *
+ * This module exports all public APIs including the main `expect` function,
+ * asynchronous `expectAsync` function, assertion creation utilities, type
+ * guards, schema definitions, utility functions, and error types.
+ *
+ * @module bupkis
+ */
+
+import { expect as sacrificialExpect } from './bootstrap.js';
+export type * from './api.js';
+
+export * as assertion from './assertion/index.js';
+export { expect, expectAsync } from './bootstrap.js';
+
+export * as error from './error.js';
+export * as guards from './guards.js';
+
+export type * as metadata from './metadata.js';
+export * as schema from './schema.js';
+export type * as types from './types.js';
+export * as util from './util.js';
+
+export { z } from 'zod/v4';
+
+export { createAssertion, createAsyncAssertion, fail, use };
+const { createAssertion, createAsyncAssertion, fail, use, ..._rest } =
+  sacrificialExpect;