bupkis 0.2.0 → 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 => {
@@ -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

@@ -7,8 +7,7 @@
  * @packageDocumentation
  */
 
-import { AsyncAssertions } from './assertion/impl/async.js';
-import { SyncAssertions } from './assertion/impl/sync.js';
+import { AsyncAssertions, SyncAssertions } from './assertion/index.js';
 import { type Expect, type ExpectAsync } from './types.js';
 import { createUse } from './use.js';
 

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,12 +7,15 @@
  */
 
 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
@@ -27,10 +30,39 @@ export class AssertionError extends NodeAssertionError {
   override name = 'AssertionError';
 
   /**
-   * @param options Options passed to {@link NodeAssertionError}'s constructor
+   * 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`
    */
-  constructor(options?: ConstructorParameters<typeof NodeAssertionError>[0]) {
-    super(options);
+  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,
+    });
   }
 
   /**
@@ -47,6 +79,26 @@ export class AssertionError extends NodeAssertionError {
   }
 }
 
+/**
+ * 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)
+    );
+  }
+}
+
 /**
  * Error type used internally to catch failed negated assertions.
  *
@@ -55,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) &&

package/src/expect.ts

@@ -16,7 +16,11 @@ 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,
@@ -578,7 +582,7 @@ const detectNegation = (
 };
 
 const fail: FailFn = (reason?: string): never => {
-  throw new AssertionError({ message: reason });
+  throw new FailAssertionError({ message: reason });
 };
 
 /**

package/src/guards.ts

@@ -24,7 +24,7 @@ import type {
   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 v4 schema, determined by
@@ -33,28 +33,60 @@ import type { Constructor } from './types.js';
  * 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 `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;
+}
+
+/**
+ * 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.
+ * 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.
@@ -63,12 +95,7 @@ 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
@@ -85,7 +112,7 @@ export const isPromiseLike = (value: unknown): value is PromiseLike<unknown> =>
  * @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;
   }

package/src/index.ts

@@ -52,6 +52,7 @@ export type {
   ExpectAsync,
   FailFn,
   UseFn,
+  ZodTypeMap,
 } from './types.js';
 export { createAssertion, createAsyncAssertion, fail, use };
 const {

package/src/schema.ts

@@ -3,7 +3,7 @@
  *
  * This module provides reusable Zod schemas for validating constructors,
  * functions, property keys, promises, and other common JavaScript types used
- * throughout the assertion system. These tend to work around the impedence
+ * throughout the assertion system. These tend to work around the impedance
  * mismatch between **BUPKIS** and Zod.
  *
  * These are used internally, but consumers may also find them useful.
@@ -36,7 +36,7 @@ import { z } from 'zod/v4';
 
 import {
   isA,
-  isConstructable,
+  isConstructible,
   isFunction,
   isNonNullObject,
   isPromiseLike,
@@ -49,7 +49,7 @@ import { type Constructor, type MutableOrReadonly } from './types.js';
  *
  * This schema validates values that can be used as constructors, including ES6
  * classes, traditional constructor functions, and built-in constructors. It
- * uses the {@link isConstructable} guard function to determine if a value can be
+ * uses the {@link isConstructible} guard function to determine if a value can be
  * invoked with the `new` operator to create object instances.
  *
  * @privateRemarks
@@ -73,7 +73,7 @@ import { type Constructor, type MutableOrReadonly } from './types.js';
  */
 
 export const ClassSchema = z
-  .custom<Constructor>(isConstructable)
+  .custom<Constructor>(isConstructible)
   .register(BupkisRegistry, { name: 'ClassSchema' })
   .describe('Class / Constructor');
 
@@ -242,9 +242,12 @@ export const StrongSetSchema = z
  * `Object.prototype`, making them useful as pure data containers or
  * dictionaries.
  *
- * @remarks
+ * @privateRemarks
  * The schema is registered in the `BupkisRegistry` with the name
  * `ObjectWithNullPrototype` for later reference and type checking purposes.
+ *
+ * Changing this to be a `ZodRecord` would be nice, but that would end up
+ * blasting away the original object's prototype.
  * @example
  *
  * ```typescript
@@ -260,14 +263,22 @@ export const StrongSetSchema = z
  * ```
  *
  * @group Schema
+ * @see Aliases: {@link NullProtoObjectSchema}, {@link DictionarySchema}
  */
-export const NullProtoObjectSchema = z
+export const DictionarySchema = z
   .custom<Record<PropertyKey, unknown>>(
     (value) => isNonNullObject(value) && Object.getPrototypeOf(value) === null,
   )
   .describe('Object with null prototype')
   .register(BupkisRegistry, { name: 'ObjectWithNullPrototype' });
 
+/**
+ * {@inheritDoc DictionarySchema}
+ *
+ * @group Schema
+ */
+export const NullProtoObjectSchema = DictionarySchema;
+
 /**
  * A Zod schema that validates functions declared with the `async` keyword.
  *
@@ -276,7 +287,7 @@ export const NullProtoObjectSchema = z
  * function's internal `[[ToString]]` representation to distinguish async
  * functions from regular functions that might return Promises.
  *
- * @remarks
+ * @privateRemarks
  * The schema is registered in the `BupkisRegistry` with the name
  * `AsyncFunctionSchema` for later reference and type checking purposes. This
  * schema cannot reliably detect functions that return Promises but are not
@@ -318,7 +329,7 @@ export const AsyncFunctionSchema = FunctionSchema.refine(
  * if it converts to `true` when evaluated in a boolean context - essentially
  * any value that is not one of the eight falsy values.
  *
- * @remarks
+ * @privateRemarks
  * The schema is registered in the `BupkisRegistry` with the name `Truthy` and
  * indicates that it accepts anything as valid input for evaluation.
  * @example
@@ -354,7 +365,7 @@ export const TruthySchema = z
  * in JavaScript are: `false`, `0`, `-0`, `0n`, `""` (empty string), `null`,
  * `undefined`, and `NaN`.
  *
- * @remarks
+ * @privateRemarks
  * The schema is registered in the `BupkisRegistry` with the name `Falsy` and
  * indicates that it accepts anything as valid input for evaluation.
  * @example
@@ -392,7 +403,7 @@ export const FalsySchema = z
  * distinguishing them from objects and functions which are non-primitive
  * reference types.
  *
- * @remarks
+ * @privateRemarks
  * The schema is registered in the `BupkisRegistry` with the name `Primitive`
  * and indicates that it accepts primitive values as valid input.
  * @example
@@ -474,7 +485,7 @@ export const ArrayLikeSchema = z
  * It ensures the validated value is a proper regular expression object with all
  * associated methods and properties.
  *
- * @remarks
+ * @privateRemarks
  * The schema is registered in the `BupkisRegistry` with the name `RegExp` for
  * later reference and type checking purposes.
  * @example

package/src/types.ts

@@ -269,14 +269,7 @@ export interface CreateAsyncAssertionFn {
     parts: Parts,
     impl: Impl,
   ): AssertionFunctionAsync<Parts, Impl, Slots>;
-} /**
- * @template BaseSyncAssertions Base set of synchronous
- *   {@link Assertion | Assertions}; will be the builtin sync assertions, at
- *   minimum)
- * @template BaseAsyncAssertions Base set of asynchronous
- *   {@link Assertion | Assertions}; will be the builtin async assertions, at
- *   minimum)
- */
+}
 
 /**
  * The main synchronous assertion function.
@@ -684,3 +677,42 @@ export interface UseFn<
     ExtendedAsyncAssertions
   >;
 }
+
+/**
+ * Maps Zod `def.type` strings to their corresponding ZodType classes.
+ *
+ * This allows for type-safe discrimination of ZodTypes based on their internal
+ * `def.type` property in Zod v4.
+ */
+export interface ZodTypeMap {
+  any: z.ZodAny;
+  array: z.ZodArray<any>;
+  bigint: z.ZodBigInt;
+  boolean: z.ZodBoolean;
+  catch: z.ZodCatch<any>;
+  date: z.ZodDate;
+  default: z.ZodDefault<any>;
+  enum: z.ZodEnum<any>;
+  function: z.ZodFunction<any, any>;
+  lazy: z.ZodLazy<any>;
+  literal: z.ZodLiteral<any>;
+  map: z.ZodMap<any, any>;
+  never: z.ZodNever;
+  null: z.ZodNull;
+  nullable: z.ZodNullable<any>;
+  number: z.ZodNumber;
+  object: z.ZodObject<any>;
+  optional: z.ZodOptional<any>;
+  pipe: z.ZodPipe<any, any>;
+  promise: z.ZodPromise<any>;
+  readonly: z.ZodReadonly<any>;
+  record: z.ZodRecord<any, any>;
+  set: z.ZodSet<any>;
+  string: z.ZodString;
+  symbol: z.ZodSymbol;
+  tuple: z.ZodTuple<any>;
+  undefined: z.ZodUndefined;
+  union: z.ZodUnion<any>;
+  unknown: z.ZodUnknown;
+  void: z.ZodVoid;
+}