bupkis 0.1.2 → 0.3.0

package/src/assertion/impl/index.ts

@@ -1,2 +1,2 @@
 export { AsyncAssertions } from './async.js';
-export { SyncAssertions } from './sync.js';
+export { SyncAssertions as SyncAssertions } from './sync.js';

package/src/assertion/impl/sync-esoteric.ts

@@ -1,10 +1,10 @@
 import { z } from 'zod/v4';
 
-import { NullProtoObjectSchema, PropertyKeySchema } from '../../schema.js';
+import { DictionarySchema, PropertyKeySchema } from '../../schema.js';
 import { createAssertion } from '../create.js';
 
 export const EsotericAssertions = [
-  createAssertion(['to have a null prototype'], NullProtoObjectSchema),
+  createAssertion(['to have a null prototype'], DictionarySchema),
   createAssertion(
     [PropertyKeySchema, 'to be an enumerable property of', z.looseObject({})],
     (subject, obj) =>

package/src/assertion/impl/sync-parametric.ts

@@ -11,7 +11,11 @@ import {
   StrongSetSchema,
   WrappedPromiseLikeSchema,
 } from '../../schema.js';
-import { valueToSchema } from '../../util.js';
+import {
+  valueToSchema,
+  valueToSchemaOptionsForDeepEqual,
+  valueToSchemaOptionsForSatisfies,
+} from '../../value-to-schema.js';
 import { createAssertion } from '../create.js';
 
 const trapError = (fn: () => unknown): unknown => {
@@ -135,7 +139,7 @@ export const ParametricAssertions = [
 
   // Number range and approximation assertions
   createAssertion(
-    [z.number(), 'to be within', z.number(), z.number()],
+    [z.number(), ['to be within', 'to be between'], z.number(), z.number()],
     (subject, min, max) => {
       if (subject < min || subject > max) {
         return {
@@ -304,19 +308,19 @@ export const ParametricAssertions = [
       }
     },
   ),
-  // @ts-expect-error fix later
   createAssertion(
     [
       z.looseObject({}),
       ['to deep equal', 'to deeply equal'],
       z.looseObject({}),
     ],
-    (_, expected) => valueToSchema(expected, { strict: true }),
+    (_, expected) => valueToSchema(expected, valueToSchemaOptionsForDeepEqual),
   ),
-  // @ts-expect-error fix later
   createAssertion(
     [ArrayLikeSchema, ['to deep equal', 'to deeply equal'], ArrayLikeSchema],
-    (_, expected) => valueToSchema(expected, { strict: true }),
+    (_, expected) => {
+      return valueToSchema(expected, valueToSchemaOptionsForDeepEqual);
+    },
   ),
   createAssertion([FunctionSchema, 'to throw'], (subject) => {
     const error = trapError(subject);
@@ -376,10 +380,7 @@ export const ParametricAssertions = [
           .or(z.coerce.string().regex(param))
           .safeParse(error).success;
       } else if (isNonNullObject(param)) {
-        const schema = valueToSchema(param, {
-          literalPrimitives: true,
-          strict: true,
-        });
+        const schema = valueToSchema(param, valueToSchemaOptionsForSatisfies);
         return schema.safeParse(error).success;
       } else {
         throw new TypeError(`Invalid parameter schema: ${inspect(param)}`);
@@ -396,6 +397,7 @@ export const ParametricAssertions = [
     ],
     (subject, ctor, param) => {
       const error = trapError(subject);
+
       if (!isA(error, ctor)) {
         return {
           actual: error,
@@ -405,47 +407,32 @@ export const ParametricAssertions = [
             : `Expected function to throw an instance of ${ctor.name}, but it threw a non-object value: ${error as unknown}`,
         };
       }
-
+      let schema: undefined | z.ZodType;
+      // TODO: can valueToSchema handle the first two conditional branches?
       if (isString(param)) {
-        const result = z
+        schema = z
           .looseObject({
-            message: z.coerce.string().refine((msg) => msg.includes(param)),
+            message: z.coerce.string().pipe(z.literal(param)),
           })
-          .or(z.coerce.string().refine((str) => str.includes(param)))
-          .safeParse(error);
-        if (!result.success) {
-          return {
-            actual: isError(error) ? error.message : String(error),
-            expected: `error with message containing "${param}"`,
-            message: `Expected error message to contain "${param}", but got: ${isError(error) ? error.message : String(error)}`,
-          };
-        }
+          .or(z.coerce.string().pipe(z.literal(param)));
       } else if (isA(param, RegExp)) {
-        const result = z
+        schema = z
           .looseObject({
             message: z.coerce.string().regex(param),
           })
-          .or(z.coerce.string().regex(param))
-          .safeParse(error);
-        if (!result.success) {
-          return {
-            actual: isError(error) ? error.message : String(error),
-            expected: `error with message matching ${param}`,
-            message: `Expected error message to match ${param}, but got: ${isError(error) ? error.message : String(error)}`,
-          };
-        }
+          .or(z.coerce.string().regex(param));
       } else if (isNonNullObject(param)) {
-        const schema = valueToSchema(param);
-        const result = schema.safeParse(error);
-        if (!result.success) {
-          return {
-            actual: error as unknown,
-            expected: param,
-            message: `Expected error to match object: ${inspect(param)}, but got: ${inspect(error)}`,
-          };
-        }
-      } else {
-        throw new TypeError(`Invalid parameter schema: ${inspect(param)}`);
+        schema = valueToSchema(param, valueToSchemaOptionsForSatisfies);
+      }
+      if (!schema) {
+        throw new TypeError(
+          `Invalid parameter schema: ${inspect(param, { depth: 2 })}`,
+        );
+      }
+
+      const result = schema.safeParse(error);
+      if (!result.success) {
+        return result.error;
       }
     },
   ),
@@ -455,7 +442,15 @@ export const ParametricAssertions = [
       ['includes', 'contains', 'to include', 'to contain'],
       z.string(),
     ],
-    (subject, expected) => subject.includes(expected),
+    (subject, expected) => {
+      if (!subject.includes(expected)) {
+        return {
+          actual: subject,
+          expected: `string including "${expected}"`,
+          message: `Expected "${subject}" to include "${expected}"`,
+        };
+      }
+    },
   ),
 
   createAssertion([z.string(), 'to match', RegExpSchema], (subject, regex) =>
@@ -467,14 +462,11 @@ export const ParametricAssertions = [
       ['to satisfy', 'to be like'],
       z.looseObject({}),
     ],
-    (_subject, shape) =>
-      // eslint-disable-next-line @typescript-eslint/no-empty-object-type
-      valueToSchema(shape) as unknown as z.ZodType<{}, z.core.$loose>,
+    (_subject, shape) => valueToSchema(shape, valueToSchemaOptionsForSatisfies),
   ),
   createAssertion(
     [ArrayLikeSchema, ['to satisfy', 'to be like'], ArrayLikeSchema],
-    (_subject, shape) =>
-      valueToSchema(shape) as unknown as typeof ArrayLikeSchema,
+    (_subject, shape) => valueToSchema(shape, valueToSchemaOptionsForSatisfies),
   ),
   createAssertion(
     [FunctionSchema, 'to have arity', z.number().int().nonnegative()],

package/src/assertion/impl/sync.ts

@@ -9,6 +9,7 @@
  * @packageDocumentation
  */
 
+import { CallbackSyncAssertions } from './callback.js';
 import { BasicAssertions } from './sync-basic.js';
 import { CollectionAssertions } from './sync-collection.js';
 import { EsotericAssertions } from './sync-esoteric.js';
@@ -19,10 +20,12 @@ export const SyncAssertions = [
   ...BasicAssertions,
   ...EsotericAssertions,
   ...ParametricAssertions,
+  ...CallbackSyncAssertions,
 ] as const;
 
 export {
   BasicAssertions,
+  CallbackSyncAssertions,
   CollectionAssertions,
   EsotericAssertions,
   ParametricAssertions,

package/src/bootstrap.ts

@@ -1,23 +1,21 @@
 /**
  * Factory function for creating the main assertion functions.
  *
- * This module provides the `bootstrap()` function that creates both synchronous
- * and asynchronous assertion engines. It contains the core implementation
- * previously split between `expect.ts` and `expect-async.ts`.
+ * This module provides the {@link bootstrap} function that creates both
+ * synchronous and asynchronous assertion engines.
  *
  * @packageDocumentation
  */
 
-import { type Expect, type ExpectAsync } from './api.js';
-import { SyncAssertions } from './assertion/impl/sync.js';
-import { AsyncAssertions } from './assertion/index.js';
+import { AsyncAssertions, SyncAssertions } from './assertion/index.js';
+import { type Expect, type ExpectAsync } from './types.js';
 import { createUse } from './use.js';
 
 /**
  * Factory function that creates both synchronous and asynchronous assertion
  * engines.
  *
- * @returns Object containing `expect` and `expectAsync` functions
+ * @returns Object containing {@link expect} and {@link expectAsync} functions
  * @internal
  */
 const bootstrap = (): {
@@ -34,9 +32,21 @@ const bootstrap = (): {
 
 const api = bootstrap();
 
-/** {@inheritDoc Expect} */
-const { expect } = api;
-/** {@inheritDoc ExpectAsync} */
-const { expectAsync } = api;
+const {
+  /**
+   * The main synchronous assertion function which can execute only built-in
+   * assertions.
+   *
+   * @function
+   */
+  expect,
+  /**
+   * The main asynchronous assertion function which can execute only built-in
+   * assertions.
+   *
+   * @function
+   */
+  expectAsync,
+} = api;
 
 export { expect, expectAsync };

package/src/constant.ts

@@ -26,6 +26,14 @@ export const kStringLiteral: unique symbol = Symbol('bupkis:string-literal');
 
 export const kBupkisAssertionError: unique symbol = Symbol('bupkis-error');
 
+/**
+ * Symbol used to flag a `FailAssertionError`
+ *
+ * @internal
+ */
+export const kBupkisFailAssertionError: unique symbol =
+  Symbol('bupkis-fail-error');
+
 /**
  * Symbol used to flag a `NegatedAssertionError`
  *

package/src/error.ts

@@ -7,25 +7,94 @@
  */
 
 import { AssertionError as NodeAssertionError } from 'node:assert';
+import { z } from 'zod/v4';
 
 import {
   kBupkisAssertionError,
+  kBupkisFailAssertionError,
   kBupkisNegatedAssertionError,
 } from './constant.js';
 import { isA } from './guards.js';
+import { type AssertionParts, type ParsedValues } from './types.js';
 
 /**
  * _BUPKIS_' s custom `AssertionError` class, which is just a thin wrapper
  * around Node.js' {@link NodeAssertionError AssertionError}.
- *
- * @public
  */
 export class AssertionError extends NodeAssertionError {
+  /**
+   * @internal
+   */
   [kBupkisAssertionError] = true;
 
-  static isAssertionError(err: unknown): err is AssertionError {
+  override name = 'AssertionError';
+
+  /**
+   * Translates a {@link z.ZodError} into an {@link AssertionError} with a
+   * human-friendly message.
+   *
+   * @remarks
+   * This does not handle parameterized assertions with more than one parameter
+   * too cleanly; it's unclear how a test runner would display the expected
+   * values. This will probably need a fix in the future.
+   * @param stackStartFn The function to start the stack trace from
+   * @param zodError The original `ZodError`
+   * @param values Values which caused the error
+   * @returns New `AssertionError`
+   */
+  static fromZodError<Parts extends AssertionParts>(
+    zodError: z.ZodError,
+    stackStartFn: (...args: any[]) => any,
+    values: ParsedValues<Parts>,
+  ): AssertionError {
+    const flat = z.flattenError(zodError);
+
+    let pretty = flat.formErrors.join('; ');
+    for (const [keypath, errors] of Object.entries(flat.fieldErrors)) {
+      pretty += `; ${keypath}: ${(errors as unknown[]).join('; ')}`;
+    }
+
+    const [actual, ...expected] = values as unknown as [unknown, ...unknown[]];
+
+    return new AssertionError({
+      actual,
+      expected: expected.length === 1 ? expected[0] : expected,
+      message: `Assertion ${this} failed: ${pretty}`,
+      operator: `${this}`,
+      stackStartFn,
+    });
+  }
+
+  /**
+   * Type guard for an instance of this error.
+   *
+   * @param value Some value
+   * @returns `true` if `value` is an instance of `AssertionError`
+   */
+  static isAssertionError(value: unknown): value is AssertionError {
     return (
-      isA(err, NodeAssertionError) && Object.hasOwn(err, kBupkisAssertionError)
+      isA(value, NodeAssertionError) &&
+      Object.hasOwn(value, kBupkisAssertionError)
+    );
+  }
+}
+
+/**
+ * Variant of an {@link AssertionError} that is thrown when
+ * {@link bupkis!expect.fail} is called.
+ */
+export class FailAssertionError extends AssertionError {
+  /**
+   * @internal
+   */
+  [kBupkisFailAssertionError] = true;
+
+  override name = 'FailAssertionError';
+
+  static isFailAssertionError(err: unknown): err is FailAssertionError {
+    return (
+      isA(err, FailAssertionError) &&
+      Object.hasOwn(err, kBupkisFailAssertionError)
     );
   }
 }
@@ -38,6 +107,8 @@ export class AssertionError extends NodeAssertionError {
 export class NegatedAssertionError extends AssertionError {
   [kBupkisNegatedAssertionError] = true;
 
+  override name = 'NegatedAssertionError';
+
   static isNegatedAssertionError(err: unknown): err is NegatedAssertionError {
     return (
       isA(err, AssertionError) &&