bupkis 0.6.0 → 0.7.2

package/src/error.ts

@@ -10,16 +10,67 @@ import { AssertionError as NodeAssertionError } from 'node:assert';
 
 import {
   kBupkisAssertionError,
+  kBupkisError,
   kBupkisFailAssertionError,
   kBupkisNegatedAssertionError,
 } from './constant.js';
 import { isA } from './guards.js';
 
+/**
+ * Options for {@link AssertionImplementationError}
+ *
+ * @group Error Options
+ */
+export interface AssertionImplementationErrorOptions extends ErrorOptions {
+  /**
+   * The result returned by an assertion implementation that caused this error.
+   */
+  result?: unknown;
+}
+/**
+ * Options for {@link InvalidMetadataError}
+ *
+ * @group Error Options
+ */
+export interface InvalidMetadataErrorOptions extends ErrorOptions {
+  /**
+   * The invalid metadata.
+   */
+  metadata?: unknown;
+}
+
+/**
+ * Options for {@link InvalidSchemaError}
+ *
+ * @group Error Options
+ */
+export interface InvalidSchemaErrorOptions extends ErrorOptions {
+  /**
+   * The invalid schema
+   */
+  schema?: unknown;
+}
+
+/**
+ * Options for {@link UnknownAssertionError}
+ *
+ * @group Error Options
+ */
+export interface UnknownAssertionErrorOptions<T extends readonly unknown[]>
+  extends ErrorOptions {
+  /**
+   * The arguments passed to {@link bupkis!expect | expect} or
+   * {@link bupkis!expectAsync | expectAsync} which caused this error.
+   */
+  args: T;
+}
+
 /**
  * _BUPKIS_' s custom `AssertionError` class, which is just a thin wrapper
  * around Node.js' {@link NodeAssertionError AssertionError}.
  *
  * @group Core API
+ * @group Errors
  */
 export class AssertionError extends NodeAssertionError {
   /**
@@ -43,9 +94,52 @@ export class AssertionError extends NodeAssertionError {
   }
 }
 
+/**
+ * Base class for all custom errors thrown by <span
+ * class="bupkis">BUPKIS</span>.
+ *
+ * Typically only thrown when it should be impossible to throw.
+ *
+ * @group Errors
+ */
+export class BupkisError extends Error {
+  [kBupkisError] = true;
+
+  override name = 'BupkisError';
+
+  static isBupkisError(err: unknown): err is BupkisError {
+    return isA(err, Error) && Object.hasOwn(err, kBupkisError);
+  }
+}
+
+/**
+ * Error type used when an assertion implementation throws an error (this likely
+ * means there's a bug in the assertion implementation).
+ *
+ * @group Errors
+ */
+export class AssertionImplementationError extends BupkisError {
+  readonly code = 'ERR_BUPKIS_ASSERTION_IMPL';
+
+  override name = 'AssertionImplementationError';
+
+  readonly result: unknown;
+
+  constructor(
+    message: string,
+    options: AssertionImplementationErrorOptions = {},
+  ) {
+    const { result, ...rest } = options;
+    super(message, rest);
+    this.result = result;
+  }
+}
+
 /**
  * Variant of an {@link AssertionError} that is thrown when
  * {@link bupkis!expect.fail} is called.
+ *
+ * @group Errors
  */
 export class FailAssertionError extends AssertionError {
   /**
@@ -63,10 +157,52 @@ export class FailAssertionError extends AssertionError {
   }
 }
 
+/**
+ * Error type used when assertion metadata is invalid.
+ *
+ * @remarks
+ * This should never be thrown unless someone monkeyed with the metadata
+ * registry.
+ * @group Errors
+ */
+export class InvalidMetadataError extends BupkisError {
+  readonly code = 'ERR_BUPKIS_INVALID_METADATA';
+
+  readonly metadata?: unknown;
+
+  override name = 'InvalidMetadataError';
+
+  constructor(message: string, options: InvalidMetadataErrorOptions = {}) {
+    const { metadata, ...rest } = options;
+    super(message, rest);
+    this.metadata = metadata;
+  }
+}
+
+/**
+ * Thrown from certain assertions when the result of `valueToSchema` is invalid.
+ *
+ * @group Errors
+ */
+export class InvalidSchemaError extends BupkisError {
+  readonly code = 'ERR_BUPKIS_INVALID_SCHEMA';
+
+  override name = 'InvalidSchemaError';
+
+  readonly schema?: unknown;
+
+  constructor(message: string, options: InvalidSchemaErrorOptions = {}) {
+    const { schema, ...rest } = options;
+    super(message, rest);
+    this.schema = schema;
+  }
+}
+
 /**
  * Error type used internally to catch failed negated assertions.
  *
  * @internal
+ * @group Errors
  */
 export class NegatedAssertionError extends AssertionError {
   [kBupkisNegatedAssertionError] = true;
@@ -80,3 +216,55 @@ export class NegatedAssertionError extends AssertionError {
     );
   }
 }
+
+/**
+ * Thrown when `expect()` is called with something async.
+ *
+ * @group Errors
+ */
+export class UnexpectedAsyncError extends BupkisError {
+  readonly code = 'ERR_BUPKIS_UNEXPECTED_ASYNC';
+
+  override name = 'UnexpectedAsyncError';
+}
+
+/**
+ * Thrown when we cannot match the parameters to {@link bupkis!expect | expect}
+ * or {@link bupkis!expectAsync | expectAsync} to any known assertion.
+ *
+ * @group Errors
+ */
+export class UnknownAssertionError<
+  T extends readonly unknown[],
+> extends BupkisError {
+  readonly args: T;
+
+  readonly code = 'ERR_BUPKIS_UNKNOWN_ASSERTION';
+
+  override name = 'UnknownAssertionError';
+
+  constructor(message: string, options: UnknownAssertionErrorOptions<T>) {
+    const { args, ...rest } = options;
+    super(message, rest);
+    this.args = args;
+  }
+}
+
+/**
+ * Thrown when a value cannot be converted to a schema using `valueToSchema()`.
+ *
+ * @remarks
+ * Currently, this includes the presence of an own property `__proto__` or an
+ * empty object (because this will match anything; though maybe we should change
+ * that).
+ * @group Errors
+ */
+export class ValueToSchemaError extends BupkisError {
+  readonly code = 'ERR_BUPKIS_SATISFACTION';
+
+  override name = 'SatisfactionError';
+
+  constructor(message: string, options: ErrorOptions = {}) {
+    super(message, options);
+  }
+}

package/src/expect.ts

@@ -1,4 +1,4 @@
-import Debug from 'debug';
+import createDebug from 'debug';
 import { inspect } from 'util';
 
 import {
@@ -20,6 +20,7 @@ import {
   AssertionError,
   FailAssertionError,
   NegatedAssertionError,
+  UnknownAssertionError,
 } from './error.js';
 import { isAssertionFailure, isString } from './guards.js';
 import {
@@ -35,7 +36,7 @@ import {
 } from './types.js';
 import { createUse } from './use.js';
 
-const debug = Debug('bupkis:expect');
+const debug = createDebug('bupkis:expect');
 
 /**
  * Creates an asynchronous expect function by extending a parent expectAsync
@@ -175,7 +176,9 @@ export function createExpectAsyncFunction<
   U extends ExpectAsync<AnyAsyncAssertions>,
 >(assertions: T, expect?: U) {
   debug(
-    'Creating expectAsync function with %d assertions',
+    'ℹ Creating expectAsync function with %d new assertions and %d existing assertions (%d total)',
+    assertions.length,
+    expect?.assertions.length ?? 0,
     assertions.length + (expect?.assertions.length ?? 0),
   );
   const expectAsyncFunction = async (...args: readonly unknown[]) => {
@@ -351,7 +354,9 @@ export function createExpectSyncFunction<
   ParentExpect extends Expect<AnySyncAssertions>,
 >(assertions: Assertions, expect?: ParentExpect) {
   debug(
-    'Creating expect function with %d assertions',
+    'ℹ Creating expect function with %d new assertions and %d existing assertions (%d total)',
+    assertions.length,
+    expect?.assertions.length ?? 0,
     assertions.length + (expect?.assertions.length ?? 0),
   );
   const expectFunction = (...args: readonly unknown[]) => {
@@ -424,7 +429,6 @@ const execute = <
   }
 
   try {
-    debug('Executing negated assertion: %s', assertion);
     const result = assertion.execute(
       parsedValues,
       args,
@@ -498,7 +502,6 @@ const executeAsync = async <
   }
 
   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({
@@ -526,6 +529,10 @@ const executeAsync = async <
 };
 
 /**
+ * Processes negation keywords in the arguments and returns whether negation is
+ * requested along with arguments stripped of the leading negation (to enable
+ * assertion matching).
+ *
  * @internal
  */
 const maybeProcessNegation = (
@@ -545,13 +552,18 @@ const maybeProcessNegation = (
 };
 
 /**
+ * Throws an error indicating that no valid assertion could be found for the
+ * provided arguments.
+ *
+ * @param args The arguments that were passed to the expect function
  * @internal
  */
 const throwInvalidParametersError = (args: readonly unknown[]): never => {
   const inspectedArgs = inspect(args, { depth: 1 });
-  debug(`Invalid arguments. No assertion matched: ${inspectedArgs}`);
-  throw new TypeError(
+  debug('Invalid arguments. No assertion matched: %s', inspectedArgs);
+  throw new UnknownAssertionError(
     `Invalid arguments. No assertion matched: ${inspectedArgs}`,
+    { args },
   );
 };
 
@@ -581,22 +593,31 @@ const detectNegation = (
   };
 };
 
+/**
+ * {@inheritdoc FailFn}
+ */
 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.
+ * Used by a {@link UseFn} to create base properties of {@link Expect}.
  */
 export function createBaseExpect<
   T extends AnySyncAssertions,
   U extends AnyAsyncAssertions,
 >(syncAssertions: T, asyncAssertions: U, type: 'sync'): ExpectSyncProps<T, U>;
+/**
+ * Used by a {@link UseFn} to create base properties of {@link ExpectAsync}.
+ */
 export function createBaseExpect<
   T extends AnySyncAssertions,
   U extends AnyAsyncAssertions,
 >(syncAssertions: T, asyncAssertions: U, type: 'async'): ExpectAsyncProps<U, T>;
+/**
+ * Used by a {@link UseFn} to create base properties of {@link Expect} or
+ * {@link ExpectAsync}.
+ */
 export function createBaseExpect<
   T extends AnySyncAssertions,
   U extends AnyAsyncAssertions,

package/src/guards.ts

@@ -97,7 +97,10 @@ 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> =>
-  isObject(value) && 'then' in value && isFunction(value.then);
+  isObject(value) &&
+  'then' in value &&
+  isFunction(value.then) &&
+  value.then.length > 0;
 
 /**
  * Returns `true` if the given value is a constructable function (i.e., a

package/src/index.ts

@@ -19,7 +19,8 @@ import { z } from 'zod/v4';
 import { expect as sacrificialExpect } from './bootstrap.js';
 export * as assertions from './assertion/impl/index.js';
 export { expect, expectAsync } from './bootstrap.js';
-export { AssertionError } from './error.js';
+export * from './error.js';
+export * as schema from './schema.js';
 
 /**
  * Re-export of most (all?) types defined within <span

package/src/value-to-schema.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod/v4';
 
+import { ValueToSchemaError } from './error.js';
 import {
   isExpectItExecutor,
   isNonNullObject,
@@ -100,7 +101,7 @@ export const valueToSchema = (
       if (isExpectItExecutor(value)) {
         // Only allow nested assertions when strict is false (e.g., "to satisfy" semantics)
         if (strict) {
-          throw new TypeError(
+          throw new ValueToSchemaError(
             'ExpectItExecutor (expect.it) functions are not allowed in strict mode. ' +
               'Use "to satisfy" assertions for nested expectations.',
           );
@@ -142,7 +143,7 @@ export const valueToSchema = (
     try {
       // Check for objects with own __proto__ property - these can cause unexpected behavior
       if (Object.hasOwn(value, '__proto__')) {
-        throw new TypeError(
+        throw new ValueToSchemaError(
           'Objects with an own "__proto__" property are not supported by valueToSchema',
         );
       }