bupkis 0.2.0 → 0.4.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-basic.ts

@@ -3,7 +3,7 @@ import { z } from 'zod/v4';
 import { BupkisRegistry } from '../../metadata.js';
 import {
   AsyncFunctionSchema,
-  ClassSchema,
+  ConstructibleSchema,
   FalsySchema,
   FunctionSchema,
   PrimitiveSchema,
@@ -64,7 +64,10 @@ export const BasicAssertions = [
   createAssertion(['to be undefined'], z.undefined()),
   createAssertion([['to be an array', 'to be array']], z.array(z.any())),
   createAssertion([['to be a date', 'to be a Date']], z.date()),
-  createAssertion([['to be a class', 'to be a constructor']], ClassSchema),
+  createAssertion(
+    [['to be a class', 'to be a constructor']],
+    ConstructibleSchema,
+  ),
   createAssertion(['to be a primitive'], PrimitiveSchema),
 
   createAssertion(

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

@@ -5,9 +5,9 @@ import { StrongMapSchema, StrongSetSchema } from '../../schema.js';
 import { createAssertion } from '../create.js';
 
 export const CollectionAssertions = [
-  // Map assertions (including WeakMap)
+  // Map assertions (including WeakMap) - use StrongMapSchema instead of z.map for better type inference
   createAssertion(
-    [z.map(z.any(), z.any()), ['to contain', 'to include'], z.any()],
+    [StrongMapSchema, ['to contain', 'to include'], z.any()],
     (subject, key) => subject.has(key),
   ),
   // Size-based assertions only for strong Maps (not WeakMaps)
@@ -21,7 +21,7 @@ export const CollectionAssertions = [
   ),
   // Set assertions (including WeakSet)
   createAssertion(
-    [z.set(z.any()), ['to contain', 'to include'], z.any()],
+    [StrongSetSchema, ['to contain', 'to include'], z.any()],
     (subject, value) => subject.has(value),
   ),
   // Size-based assertions only for strong Sets (not WeakSets)

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

@@ -4,14 +4,19 @@ import { z } from 'zod/v4';
 import { isA, isError, isNonNullObject, isString } from '../../guards.js';
 import {
   ArrayLikeSchema,
-  ClassSchema,
+  ConstructibleSchema,
   FunctionSchema,
   RegExpSchema,
+  SatisfyPatternSchema,
   StrongMapSchema,
   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 => {
@@ -51,7 +56,7 @@ const knownTypes = Object.freeze(
 
 export const ParametricAssertions = [
   createAssertion(
-    [['to be an instance of', 'to be a'], ClassSchema],
+    [['to be an instance of', 'to be a'], ConstructibleSchema],
     (_, ctor) => z.instanceof(ctor),
   ),
   createAssertion(
@@ -304,19 +309,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);
@@ -328,7 +333,7 @@ export const ParametricAssertions = [
     }
   }),
   createAssertion(
-    [FunctionSchema, ['to throw a', 'to thrown an'], ClassSchema],
+    [FunctionSchema, ['to throw a', 'to thrown an'], ConstructibleSchema],
     (subject, ctor) => {
       const error = trapError(subject);
       if (!error) {
@@ -376,10 +381,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)}`);
@@ -390,12 +392,13 @@ export const ParametricAssertions = [
     [
       FunctionSchema,
       ['to throw a', 'to thrown an'],
-      ClassSchema,
+      ConstructibleSchema,
       'satisfying',
       z.union([z.string(), z.instanceof(RegExp), z.looseObject({})]),
     ],
     (subject, ctor, param) => {
       const error = trapError(subject);
+
       if (!isA(error, ctor)) {
         return {
           actual: error,
@@ -405,47 +408,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 +443,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) =>
@@ -465,16 +461,13 @@ export const ParametricAssertions = [
     [
       z.looseObject({}).nonoptional(),
       ['to satisfy', 'to be like'],
-      z.looseObject({}),
+      SatisfyPatternSchema,
     ],
-    (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,
+    [ArrayLikeSchema, ['to satisfy', 'to be like'], SatisfyPatternSchema],
+    (_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`
  *
@@ -35,3 +43,5 @@ export const kBupkisAssertionError: unique symbol = Symbol('bupkis-error');
 export const kBupkisNegatedAssertionError: unique symbol = Symbol(
   'bupkis-negated-error',
 );
+
+export const kExpectIt: unique symbol = Symbol('bupkis-expect-it');

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,9 @@ import type {
   AssertionPart,
   PhraseLiteralChoice,
 } from './assertion/assertion-types.js';
-import type { Constructor } from './types.js';
+import type { Constructor, ExpectItExecutor, ZodTypeMap } from './types.js';
+
+import { kExpectIt } from './constant.js';
 
 /**
  * Returns `true` if the given value looks like a Zod v4 schema, determined by
@@ -33,28 +35,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 +97,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 +114,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;
   }
@@ -194,6 +223,30 @@ export const isPhraseLiteralChoice = (
 export const isPhraseLiteral = (value: AssertionPart): value is string =>
   isString(value) && !value.startsWith('not ');
 
+/**
+ * Generic type guard for instanceof checks.
+ *
+ * This function provides a type-safe way to check if a value is an instance of
+ * a given constructor, with proper type narrowing for TypeScript. It combines
+ * the null/object check with instanceof to ensure the value is a valid object
+ * before performing the instance check.
+ *
+ * @example
+ *
+ * ```typescript
+ * const obj = new Date();
+ * if (isA(obj, Date)) {
+ *   // obj is now typed as Date
+ *   console.log(obj.getTime());
+ * }
+ * ```
+ *
+ * @template T - The constructor type to check against
+ * @param value - Value to test
+ * @param ctor - Constructor function to check instanceof
+ * @returns `true` if the value is an instance of the constructor, `false`
+ *   otherwise
+ */
 export const isA = <T extends Constructor>(
   value: unknown,
   ctor: T,
@@ -201,4 +254,58 @@ export const isA = <T extends Constructor>(
   return isNonNullObject(value) && value instanceof ctor;
 };
 
+/**
+ * Type guard for Error instances.
+ *
+ * This function checks if a value is an instance of the Error class or any of
+ * its subclasses. It's useful for error handling and type narrowing when
+ * working with unknown values that might be errors.
+ *
+ * @example
+ *
+ * ```typescript
+ * try {
+ *   throw new TypeError('Something went wrong');
+ * } catch (err) {
+ *   if (isError(err)) {
+ *     // err is now typed as Error
+ *     console.log(err.message);
+ *   }
+ * }
+ * ```
+ *
+ * @param value - Value to test
+ * @returns `true` if the value is an Error instance, `false` otherwise
+ */
 export const isError = (value: unknown): value is Error => isA(value, Error);
+
+/**
+ * Type guard for {@link ExpectItExecutor} functions.
+ *
+ * This function checks if a value is an {@link ExpectItExecutor} function
+ * created by {@link bupkis!expect.it | expect.it()}. {@link ExpectItExecutor}
+ * functions are special functions that contain assertion logic and are marked
+ * with an internal symbol for identification. They are used in nested
+ * assertions within "to satisfy" patterns and other complex assertion
+ * scenarios.
+ *
+ * @example
+ *
+ * ```typescript
+ * const executor = expect.it('to be a string');
+ * if (isExpectItExecutor(executor)) {
+ *   // executor is now typed as ExpectItExecutor
+ *   // Can be used in satisfaction patterns
+ * }
+ * ```
+ *
+ * @template Subject - The subject type that the executor function operates on
+ * @param value - Value to test
+ * @returns `true` if the value is an ExpectItExecutor function, `false`
+ *   otherwise
+ */
+export const isExpectItExecutor = <Subject extends z.ZodType = z.ZodUnknown>(
+  value: unknown,
+): value is ExpectItExecutor<Subject> => {
+  return isFunction(value) && kExpectIt in value && value[kExpectIt] === true;
+};

package/src/index.ts

@@ -50,8 +50,11 @@ export type {
   CreateAsyncAssertionFn,
   Expect,
   ExpectAsync,
+  ExpectIt,
+  ExpectItExecutor,
   FailFn,
   UseFn,
+  ZodTypeMap,
 } from './types.js';
 export { createAssertion, createAsyncAssertion, fail, use };
 const {