bupkis 0.7.2 → 0.9.0

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

@@ -16,7 +16,7 @@
 import { inspect } from 'node:util';
 import { z } from 'zod/v4';
 
-import { BupkisError, InvalidSchemaError } from '../../error.js';
+import { BupkisError, InvalidObjectSchemaError } from '../../error.js';
 import { isA, isError, isNonNullObject, isString } from '../../guards.js';
 import {
   ArrayLikeSchema,
@@ -34,10 +34,13 @@ import {
 import { createAssertion } from '../create.js';
 import { trapError } from './assertion-util.js';
 
+const { freeze } = Object;
+const { abs } = Math;
+
 /**
  * For {@link typeOfAssertion}
  */
-const knownTypes = Object.freeze(
+const knownTypes = freeze(
   new Set([
     'string',
     'number',
@@ -271,7 +274,7 @@ export const numberWithinRangeAssertion = createAssertion(
 export const numberCloseToAssertion = createAssertion(
   [z.number(), 'to be close to', z.number(), z.number().optional()],
   (subject, expected, tolerance = 1e-9) => {
-    const diff = Math.abs(subject - expected);
+    const diff = abs(subject - expected);
     if (diff > tolerance) {
       return {
         actual: subject,
@@ -634,14 +637,19 @@ export const arrayDeepEqualAssertion = createAssertion(
 export const functionThrowsAssertion = createAssertion(
   [FunctionSchema, 'to throw'],
   (subject) => {
-    const error = trapError(subject);
-    if (!error) {
+    const { error, result } = trapError(subject);
+    if (error === undefined) {
       return {
-        actual: error,
+        actual: result,
         message: `Expected function to throw, but it did not`,
       };
     }
   },
+  {
+    anchor: 'function-to-throw-any',
+    category: 'function',
+    redirect: 'to-throw',
+  },
 );
 
 /**
@@ -671,21 +679,27 @@ export const functionThrowsAssertion = createAssertion(
 export const functionThrowsTypeAssertion = createAssertion(
   [FunctionSchema, ['to throw a', 'to throw an'], ConstructibleSchema],
   (subject, ctor) => {
-    const error = trapError(subject);
-    if (!error) {
-      return false;
+    const { error, result } = trapError(subject);
+    if (error === undefined) {
+      return {
+        actual: result,
+        expected: `to throw instance of ${ctor.name}`,
+        message: 'Expected function to throw, but it did not',
+      };
     }
-    if (!(error instanceof ctor)) {
-      let message: string;
-      if (isError(error)) {
-        message = `Expected function to throw an instance of ${ctor.name}, but it threw ${error.constructor.name}`;
-      } else {
-        message = `Expected function to throw an instance of ${ctor.name}, but it threw a non-object value: ${error as unknown}`;
+    if (!isA(error, ctor)) {
+      if (isNonNullObject(error)) {
+        const err = error as object;
+        return {
+          actual: err.constructor.name,
+          expected: ctor.name,
+          message: `Expected function to throw with an instance of ${ctor.name}, but it threw with a ${err.constructor.name}`,
+        };
       }
       return {
-        actual: error,
-        expected: ctor,
-        message,
+        actual: typeof error,
+        expected: ctor.name,
+        message: `Expected function to throw with an instance of ${ctor.name}, but it threw a value of type ${typeof error}: ${inspect(error)}`,
       };
     }
   },
@@ -723,33 +737,41 @@ export const functionThrowsTypeAssertion = createAssertion(
  *
  * @group Parametric Assertions (Sync)
  */
-export const functionThrowsMatchingAssertion = createAssertion(
+export const functionThrowsSatisfyingAssertion = createAssertion(
   [FunctionSchema, ['to throw', 'to throw error satisfying'], z.any()],
   (subject, param) => {
-    const error = trapError(subject);
-    if (!error) {
-      return false;
+    const { error, result } = trapError(subject);
+    if (error === undefined) {
+      return {
+        actual: result,
+        expected: 'to throw',
+        message: 'Expected function to throw, but it did not',
+      };
     }
 
     if (isString(param)) {
-      return z
-        .looseObject({
-          message: z.coerce.string().pipe(z.literal(param)),
-        })
-        .or(z.coerce.string().pipe(z.literal(param)))
-        .safeParse(error).success;
+      return {
+        schema: z
+          .looseObject({
+            message: z.coerce.string().pipe(z.literal(param)),
+          })
+          .or(z.coerce.string().pipe(z.literal(param))),
+        subject: error,
+      };
     } else if (isA(param, RegExp)) {
-      return z
-        .looseObject({
-          message: z.coerce.string().regex(param),
-        })
-        .or(z.coerce.string().regex(param))
-        .safeParse(error).success;
+      return {
+        schema: z
+          .looseObject({
+            message: z.coerce.string().regex(param),
+          })
+          .or(z.coerce.string().regex(param)),
+        subject: error,
+      };
     } else if (isNonNullObject(param)) {
       const schema = valueToSchema(param, valueToSchemaOptionsForSatisfies);
-      return schema.safeParse(error).success;
+      return { schema, subject: error };
     } else {
-      throw new InvalidSchemaError(
+      throw new InvalidObjectSchemaError(
         `Invalid parameter schema: ${inspect(param, { depth: 2 })}`,
         { schema: param },
       );
@@ -795,7 +817,14 @@ export const functionThrowsTypeSatisfyingAssertion = createAssertion(
     z.any(),
   ],
   (subject, ctor, param) => {
-    const error = trapError(subject);
+    const { error, result } = trapError(subject);
+    if (error === undefined) {
+      return {
+        actual: result,
+        expected: `to throw instance of ${ctor.name}`,
+        message: 'Expected function to throw, but it did not',
+      };
+    }
     if (!isA(error, ctor)) {
       return {
         actual: error,
@@ -808,31 +837,29 @@ export const functionThrowsTypeSatisfyingAssertion = createAssertion(
     let schema: undefined | z.ZodType;
     // TODO: can valueToSchema handle the first two conditional branches?
     if (isString(param)) {
-      schema = z
-        .looseObject({
-          message: z.coerce.string().pipe(z.literal(param)),
-        })
-        .or(z.coerce.string().pipe(z.literal(param)));
+      schema = z.looseObject({
+        message: z.coerce.string().pipe(z.literal(param)),
+      });
+      // .or(z.coerce.string().pipe(z.literal(param)));
     } else if (isA(param, RegExp)) {
-      schema = z
-        .looseObject({
-          message: z.coerce.string().regex(param),
-        })
-        .or(z.coerce.string().regex(param));
+      schema = z.looseObject({
+        message: z.coerce.string().regex(param),
+      });
+      // .or(z.coerce.string().regex(param));
     } else if (isNonNullObject(param)) {
       schema = valueToSchema(param, valueToSchemaOptionsForSatisfies);
     }
     if (!schema) {
-      throw new InvalidSchemaError(
+      throw new InvalidObjectSchemaError(
         `Invalid parameter schema: ${inspect(param, { depth: 2 })}`,
         { schema: param },
       );
     }
 
-    const result = schema.safeParse(error);
-    if (!result.success) {
-      return result.error;
-    }
+    return {
+      schema,
+      subject: error,
+    };
   },
 );
 

package/src/assertion/impl/sync.ts

@@ -100,7 +100,7 @@ import {
   errorMessageMatchingAssertion,
   functionArityAssertion,
   functionThrowsAssertion,
-  functionThrowsMatchingAssertion,
+  functionThrowsSatisfyingAssertion,
   functionThrowsTypeAssertion,
   functionThrowsTypeSatisfyingAssertion,
   instanceOfAssertion,
@@ -215,7 +215,7 @@ export const SyncParametricAssertions = [
   arrayDeepEqualAssertion,
   functionThrowsAssertion,
   functionThrowsTypeAssertion,
-  functionThrowsMatchingAssertion,
+  functionThrowsSatisfyingAssertion,
   functionThrowsTypeSatisfyingAssertion,
   stringIncludesAssertion,
   stringMatchesAssertion,

package/src/assertion/index.ts

@@ -11,7 +11,7 @@
  */
 
 export { BupkisRegistry } from '../metadata.js';
-export * from './assertion-types.js';
+export type * from './assertion-types.js';
 export { BupkisAssertion } from './assertion.js';
 export { createAssertion, createAsyncAssertion } from './create.js';
 export * from './impl/async.js';

package/src/assertion/slotify.ts

@@ -11,11 +11,17 @@
 import { inspect } from 'util';
 import { z } from 'zod/v4';
 
-import type { AssertionParts, AssertionSlots } from './assertion-types.js';
+import type {
+  AssertionParts,
+  AssertionSlots,
+  PhraseLiteral,
+  PhraseLiteralChoice,
+} from './assertion-types.js';
 
 import { kStringLiteral } from '../constant.js';
 import { AssertionImplementationError } from '../error.js';
 import {
+  isPhrase,
   isPhraseLiteral,
   isPhraseLiteralChoice,
   isZodType,
@@ -30,35 +36,29 @@ import { BupkisRegistry } from '../metadata.js';
  * processing string literals and Zod schemas, registering metadata for runtime
  * introspection, and handling validation constraints such as preventing "not "
  * prefixes in string literal parts.
+ * @function
  * @param parts Assertion parts
  * @returns Slots
+ * @internal
  */
 export const slotify = <const Parts extends AssertionParts>(
   parts: Parts,
 ): AssertionSlots<Parts> =>
   parts.flatMap((part, index) => {
     const result: z.ZodType[] = [];
-    if (index === 0 && (isPhraseLiteralChoice(part) || isPhraseLiteral(part))) {
+    if (index === 0 && isPhrase(part)) {
       result.push(z.unknown().describe('subject'));
     }
 
     if (isPhraseLiteralChoice(part)) {
       if (part.some((p) => p.startsWith('not '))) {
         throw new AssertionImplementationError(
-          `PhraseLiteralChoice at parts[${index}] must not include phrases starting with "not ": ${inspect(
+          `PhraseLiteralChoice at parts[${index}] must not include phrases starting with "not "; refactor to be a positive assertion: ${inspect(
             part,
           )}`,
         );
       }
-      result.push(
-        z
-          .literal(part)
-          .brand('string-literal')
-          .register(BupkisRegistry, {
-            [kStringLiteral]: true,
-            values: part,
-          }),
-      );
+      result.push(createPhraseLiteralChoiceSchema(part));
     } else if (isPhraseLiteral(part)) {
       if (part.startsWith('not ')) {
         throw new AssertionImplementationError(
@@ -67,15 +67,19 @@ export const slotify = <const Parts extends AssertionParts>(
           )}`,
         );
       }
-      result.push(
-        z
-          .literal(part)
-          .brand('string-literal')
-          .register(BupkisRegistry, {
-            [kStringLiteral]: true,
-            value: part,
-          }),
-      );
+      result.push(createPhraseLiteralSchema(part));
+    } else if (typeof part === 'string' && part === 'and') {
+      // Special case: "and" is allowed when followed by a ZodType (for conjunctify)
+      if (index + 1 >= parts.length || !isZodType(parts[index + 1])) {
+        throw new AssertionImplementationError(
+          `"and" at parts[${index}] must be followed by a Zod schema but was followed by ${
+            index + 1 >= parts.length
+              ? 'nothing'
+              : `${inspect(parts[index + 1])} (${typeof parts[index + 1]})`
+          }`,
+        );
+      }
+      result.push(createPhraseLiteralSchema(part));
     } else {
       if (!isZodType(part)) {
         throw new AssertionImplementationError(
@@ -88,3 +92,45 @@ export const slotify = <const Parts extends AssertionParts>(
     }
     return result;
   }) as unknown as AssertionSlots<Parts>;
+
+/**
+ * Creates a schema for a choice of phrase literals
+ *
+ * This schema is a branded literal schema to differentiate regular strings from
+ * phrases.
+ *
+ * @function
+ * @param part Phrase literal choice (tuple of strings)
+ * @returns Schema
+ */
+const createPhraseLiteralChoiceSchema = (
+  part: PhraseLiteralChoice,
+): z.core.$ZodBranded<z.ZodLiteral<string>, 'string-literal'> =>
+  z
+    .literal(part)
+    .brand('string-literal')
+    .register(BupkisRegistry, {
+      [kStringLiteral]: true,
+      values: part,
+    });
+
+/**
+ * Creates a schema for a single phrase literal
+ *
+ * This schema is a branded literal schema to differentiate regular strings from
+ * phrases.
+ *
+ * @function
+ * @param part Phrase literal (string)
+ * @returns Schema
+ */
+const createPhraseLiteralSchema = (
+  part: PhraseLiteral,
+): z.core.$ZodBranded<z.ZodLiteral<string>, 'string-literal'> =>
+  z
+    .literal(part)
+    .brand('string-literal')
+    .register(BupkisRegistry, {
+      [kStringLiteral]: true,
+      value: part,
+    });

package/src/bootstrap.ts

@@ -15,6 +15,7 @@ import { createUse } from './use.js';
  * Factory function that creates both synchronous and asynchronous assertion
  * engines.
  *
+ * @function
  * @returns Object containing {@link expect} and {@link expectAsync} functions
  * @internal
  */