bupkis 0.7.2 → 0.9.0

package/src/guards.ts

@@ -16,18 +16,24 @@
  * @packageDocumentation
  */
 
-import { type Primitive } from 'type-fest';
-import { z } from 'zod/v4';
+import { type z } from 'zod/v4';
 
 import type {
-  AssertionFailure,
   AssertionPart,
   PhraseLiteralChoice,
 } from './assertion/assertion-types.js';
-import type { Constructor, ExpectItExecutor, ZodTypeMap } from './types.js';
+import type {
+  AssertionParts,
+  Constructor,
+  ExpectItExecutor,
+  PhraseLiteral,
+  ZodTypeMap,
+} from './types.js';
 
 import { kExpectIt } from './constant.js';
 
+const { isArray } = Array;
+
 /**
  * Returns `true` if the given value looks like a Zod v4 schema, determined by
  * the presence of an internal {@link z.core.$ZodTypeDef} field.
@@ -43,6 +49,7 @@ 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.
@@ -65,8 +72,12 @@ export function isZodType<T extends keyof ZodTypeMap>(
     typeof value.def === 'object' &&
     'type' in value.def;
 
-  if (!isValid) return false;
-  if (type === undefined) return true;
+  if (!isValid) {
+    return false;
+  }
+  if (type === undefined) {
+    return true;
+  }
 
   return (value as z.ZodType).def.type === type;
 }
@@ -74,16 +85,18 @@ export function isZodType<T extends keyof ZodTypeMap>(
 /**
  * Type guard for a plain object.
  *
+ * @function
  * @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);
+  return typeof value === 'object' && value !== null && !isArray(value);
 };
 
 /**
  * Returns `true` if the given value is a {@link z.ZodPromise} schema.
  *
+ * @function
  * @param value - Value to test
  * @returns `true` if the value is a `ZodPromise` schema; `false` otherwise
  */
@@ -93,6 +106,7 @@ export const isZodPromise = (value: unknown): value is z.ZodPromise =>
 /**
  * Checks if a value is "promise-like", meaning it is a "thenable" object.
  *
+ * @function
  * @param value - Value to test
  * @returns `true` if the value is promise-like, `false` otherwise
  */
@@ -114,6 +128,7 @@ export const isPromiseLike = (value: unknown): value is PromiseLike<unknown> =>
  * This may be the only way we can determine, at runtime, if a function is a
  * constructor without actually calling it. I am unsure if this only works for
  * classes.
+ * @function
  * @param fn - Function to test
  * @returns Whether the function is constructable
  */
@@ -123,7 +138,7 @@ export const isConstructible = (fn: unknown): fn is Constructor => {
   }
   try {
     // this will throw if there is no `[[construct]]` slot.. or so I've heard.
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-call, custom/require-function-tag-in-arrow-functions
     new new Proxy(fn as any, { construct: () => ({}) })();
     return true;
   } catch {
@@ -134,6 +149,7 @@ export const isConstructible = (fn: unknown): fn is Constructor => {
 /**
  * Type guard for a boolean value
  *
+ * @function
  * @param value Value to check
  * @returns `true` if the value is a boolean, `false` otherwise
  */
@@ -143,42 +159,17 @@ export const isBoolean = (value: unknown): value is boolean =>
 /**
  * Type guard for a function value
  *
+ * @function
  * @param value Value to check
  * @returns `true` if the value is a function, `false` otherwise
  */
 export const isFunction = (value: unknown): value is (...args: any[]) => any =>
   typeof value === 'function';
 
-const AssertionFailureSchema: z.ZodType<AssertionFailure> = z.object({
-  actual: z
-    .unknown()
-    .optional()
-    .describe('The actual value or description of what actually occurred'),
-  expected: z
-    .unknown()
-    .optional()
-    .describe(
-      'The expected value or description of what was expected to occur',
-    ),
-  message: z
-    .string()
-    .optional()
-    .describe('A human-readable message describing the failure'),
-});
-
-/**
- * Type guard for a {@link AssertionFailure} object
- *
- * @param value Value to check
- * @returns `true` if the value is an `AssertionFailure`, `false` otherwise
- * @internal
- */
-export const isAssertionFailure = (value: unknown): value is AssertionFailure =>
-  AssertionFailureSchema.safeParse(value).success;
-
 /**
  * Type guard for a string value
  *
+ * @function
  * @param value Value to check
  * @returns `true` if the value is a string, `false` otherwise
  */
@@ -188,27 +179,20 @@ export const isString = (value: unknown): value is string =>
 /**
  * Type guard for a non-null object value
  *
+ * @function
  * @param value Value to check
  * @returns `true` if the value is an object and not null, `false` otherwise
  */
 export const isNonNullObject = (value: unknown): value is object =>
   typeof value === 'object' && value !== null;
 
-/**
- * Type guard for a null or non-object value
- *
- * @param value Value to check
- * @returns `true` if the value is null or not an object, `false` otherwise
- */
-export const isNullOrNonObject = (value: unknown): value is null | Primitive =>
-  typeof value !== 'object' || value === null;
-
 /**
  * Type guard for a valid WeakKey (object, function, or symbol).
  *
  * WeakMaps and WeakSets can only use objects (including functions) or symbols
  * as keys, not primitives like strings, numbers, booleans, null, or undefined.
  *
+ * @function
  * @param value Value to check
  * @returns `true` if the value is a valid WeakKey (object, function, or
  *   symbol), `false` otherwise
@@ -221,25 +205,40 @@ export const isWeakKey = (value: unknown): value is WeakKey =>
 /**
  * Type guard for a {@link PhraseLiteralChoice}, which is a tuple of strings.
  *
+ * @function
  * @param value Assertion part to check
  * @returns `true` if the part is a `PhraseLiteralChoice`, `false` otherwise
  * @internal
  */
 export const isPhraseLiteralChoice = (
-  value: AssertionPart,
+  value: unknown,
 ): value is PhraseLiteralChoice =>
-  Array.isArray(value) && value.every(isPhraseLiteral);
+  isArray(value) && value.every(isPhraseLiteral);
 
 /**
  * Type guard for a {@link PhraseLiteral}, which is just a string that does not
  * begin with `not `.
  *
+ * @function
  * @param value Assertion part to check
  * @returns `true` if the part is a `PhraseLiteral`, `false` otherwise
  * @internal
  */
-export const isPhraseLiteral = (value: AssertionPart): value is string =>
-  isString(value) && !value.startsWith('not ');
+export const isPhraseLiteral = (value: unknown): value is PhraseLiteral =>
+  isString(value) && !value.startsWith('not ') && value !== 'and';
+
+/**
+ * Type guard for a {@link PhraseLiteral} or {@link PhraseLiteralChoice}.
+ *
+ * @function
+ * @param value Value to check
+ * @returns `true` if the value is a `PhraseLiteral` or `PhraseLiteralChoice`,
+ *   `false` otherwise
+ */
+export const isPhrase = (
+  value: unknown,
+): value is PhraseLiteral | PhraseLiteralChoice =>
+  isPhraseLiteral(value) || isPhraseLiteralChoice(value);
 
 /**
  * Generic type guard for instanceof checks.
@@ -260,6 +259,7 @@ export const isPhraseLiteral = (value: AssertionPart): value is string =>
  * ```
  *
  * @template T - The constructor type to check against
+ * @function
  * @param value - Value to test
  * @param ctor - Constructor function to check instanceof
  * @returns `true` if the value is an instance of the constructor, `false`
@@ -292,6 +292,7 @@ export const isA = <T extends Constructor>(
  * }
  * ```
  *
+ * @function
  * @param value - Value to test
  * @returns `true` if the value is an Error instance, `false` otherwise
  */
@@ -318,6 +319,7 @@ export const isError = (value: unknown): value is Error => isA(value, Error);
  * ```
  *
  * @template Subject - The subject type that the executor function operates on
+ * @function
  * @param value - Value to test
  * @returns `true` if the value is an ExpectItExecutor function, `false`
  *   otherwise
@@ -327,3 +329,27 @@ export const isExpectItExecutor = <Subject extends z.ZodType = z.ZodUnknown>(
 ): value is ExpectItExecutor<Subject> => {
   return isFunction(value) && kExpectIt in value && value[kExpectIt] === true;
 };
+
+/**
+ * Type guard for an {@link AssertionPart}, which can be a {@link PhraseLiteral},
+ * {@link PhraseLiteralChoice}, or a Zod schema.
+ *
+ * @function
+ * @param value Value to check
+ * @returns `true` if the value is an `AssertionPart`, `false` otherwise
+ * @internal
+ */
+export const isAssertionPart = (value: unknown): value is AssertionPart =>
+  isPhraseLiteral(value) || isPhraseLiteralChoice(value) || isZodType(value);
+
+/**
+ * Type guard for {@link AssertionParts}, which is an array of
+ * {@link AssertionPart}.
+ *
+ * @function
+ * @param value Value to check
+ * @returns `true` if the value is an `AssertionParts`, `false` otherwise
+ * @internal
+ */
+export const isAssertionParts = (value: unknown): value is AssertionParts =>
+  isArray(value) && !!value.length && value.every(isAssertionPart);

package/src/internal-schema.ts

@@ -0,0 +1,246 @@
+/**
+ * Internal schemas
+ *
+ * @internal
+ * @packageDocumentation
+ */
+
+import { z } from 'zod/v4';
+
+import type {
+  AssertionFailure,
+  AssertionMetadata,
+  AssertionParseRequest,
+} from './types.js';
+
+import { isZodType } from './guards.js';
+
+/**
+ * Schema for internal assertion metadata.
+ *
+ * Used by documentation tooling.
+ */
+
+export const AssertionMetadataSchema: z.ZodType<AssertionMetadata> = z
+  .looseObject({
+    anchor: z.string().describe('Anchor ID for linking to this assertion.'),
+    category: z
+      .enum([
+        'collections',
+        'date',
+        'equality',
+        'error',
+        'function',
+        'numeric',
+        'object',
+        'other',
+        'primitives',
+        'promise',
+        'strings',
+      ])
+      .describe('Category to map to page of logically grouped assertions'),
+    redirect: z
+      .string()
+      .optional()
+      .describe(
+        'Redirect for assertion to its documentation page, including anchor',
+      ),
+  })
+  .describe(
+    'Metadata associated with an assertion, for internal use by documentation tooling.',
+  );
+
+/**
+ * Schema for {@link AssertionFailure}.
+ *
+ * @internal
+ */
+
+const AssertionFailureSchema: z.ZodType<AssertionFailure> = z
+  .object({
+    actual: z
+      .unknown()
+      .optional()
+      .describe('The actual value or description of what actually occurred'),
+    expected: z
+      .unknown()
+      .optional()
+      .describe(
+        'The expected value or description of what was expected to occur',
+      ),
+    message: z
+      .string()
+      .optional()
+      .describe('A human-readable message describing the failure'),
+  })
+  .describe('Potential return type of an assertion implementation function');
+
+/**
+ * @internal
+ */
+const ZodTypeSchema = z
+  .custom<z.ZodType>(isZodType, {
+    error: 'Must be a Zod schema',
+  })
+  .describe('A Zod schema within AssertionParts');
+
+/** @internal */
+const BaseAssertionParseRequestSchema = z.object({
+  subject: z.unknown().describe('The subject value to be validated'),
+});
+
+/**
+ * @internal
+ */
+const AssertionParseRequestSchema: z.ZodType<AssertionParseRequest> = z.union([
+  z.object({
+    ...BaseAssertionParseRequestSchema.shape,
+    schema: ZodTypeSchema.describe('The sync Zod schema to validate against'),
+  }),
+  z.object({
+    ...BaseAssertionParseRequestSchema.shape,
+    asyncSchema: ZodTypeSchema.describe(
+      'The async Zod schema to validate against',
+    ),
+  }),
+]);
+
+/**
+ * @internal
+ */
+const PhraseLiteralSchema = z
+  .stringFormat('PhraseLiteral', (value) => !value.startsWith('not '), {
+    error: 'Phrase literals may not begin with "not "',
+  })
+  .min(1, { error: 'Phrase literals must be at least 1 character long' })
+  .describe('A phrase literal within AssertionParts');
+
+/**
+ * @internal
+ */
+const PhraseLiteralChoiceSchema = z
+  .array(PhraseLiteralSchema)
+  .min(1, { error: 'Phrase literal choices must have at least one option' })
+  .describe(
+    'A choice of phrase literals, represented as an array of strings, within AssertionParts',
+  );
+/**
+ * @internal
+ */
+const AssertionImplSchemaSync = z
+  .union([
+    ZodTypeSchema,
+    z.function({
+      input: z.tuple([z.unknown()], z.unknown()),
+      output: z.union([
+        z.void(),
+        z.boolean(),
+        ZodTypeSchema,
+        AssertionFailureSchema,
+        AssertionParseRequestSchema,
+      ]),
+    }),
+  ])
+  .describe('A synchronous assertion implementation function');
+
+const AssertionImplSchemaAsync = z
+  .union([
+    ZodTypeSchema,
+    z.function({
+      input: z.tuple([z.unknown()], z.unknown()),
+      output: z.union([
+        z.void(),
+        z.boolean(),
+        ZodTypeSchema,
+        AssertionFailureSchema,
+        AssertionParseRequestSchema,
+        z.promise(z.void()),
+        z.promise(z.boolean()),
+        z.promise(ZodTypeSchema),
+        z.promise(AssertionFailureSchema),
+        z.promise(AssertionParseRequestSchema),
+      ]),
+    }),
+  ])
+  .describe('An async assertion implementation function');
+
+/**
+ * @internal
+ */
+const AssertionPartsSchema = z
+  .array(
+    z.union([PhraseLiteralSchema, PhraseLiteralChoiceSchema, ZodTypeSchema]),
+  )
+  .min(1, { error: 'At least one part is required for an assertion' })
+  .refine(
+    (parts) => {
+      // Special validation for 'and': it can only appear if followed by a ZodType
+      for (let i = 0; i < parts.length; i++) {
+        if (parts[i] === 'and') {
+          // 'and' must be followed by another part, and that part must be a ZodType
+          if (i === parts.length - 1 || !isZodType(parts[i + 1])) {
+            return false;
+          }
+        }
+      }
+      return true;
+    },
+    { error: '"and" can only appear when followed by a Zod schema' },
+  )
+  .describe('Assertion "parts" which define the input of an assertion');
+
+/**
+ * Type guard for a {@link AssertionFailure}.
+ *
+ * This cannot live in `guards.ts` because it would create a cycle.
+ *
+ * @function
+ * @param value Value to check
+ * @returns `true` if value is an AssertionFailure
+ * @internal
+ */
+export const isAssertionFailure = (
+  value: unknown,
+): value is AssertionFailure => {
+  return AssertionFailureSchema.safeParse(value).success;
+};
+
+/**
+ * @function
+ */
+export const isAssertionParseRequest = (
+  value: unknown,
+): value is AssertionParseRequest => {
+  return AssertionParseRequestSchema.safeParse(value).success;
+};
+
+/**
+ * @internal
+ */
+export const CreateAssertionInputSchema = z
+  .tuple([
+    AssertionPartsSchema,
+    AssertionImplSchemaSync,
+    z.optional(AssertionMetadataSchema),
+  ])
+  .describe('Parameters for createAssertion()');
+
+/**
+ * @internal
+ */
+export const CreateAssertionInputSchemaAsync = z
+  .tuple([
+    AssertionPartsSchema,
+    AssertionImplSchemaAsync,
+    z.optional(AssertionMetadataSchema),
+  ])
+  .describe('Parameters for createAsyncAssertion()');
+
+/**
+ * @function
+ * @param value
+ * @returns
+ * @knipignore
+ */
+export const isMetadata = (value: unknown): value is AssertionMetadata =>
+  AssertionMetadataSchema.safeParse(value).success;

package/src/schema.ts

@@ -50,6 +50,8 @@ import {
   type MutableOrReadonly,
 } from './types.js';
 
+const { getPrototypeOf, prototype: objectPrototype } = Object;
+
 /**
  * A Zod schema that validates JavaScript constructible functions.
  *
@@ -386,7 +388,7 @@ export const WrappedPromiseLikeSchema = z
  */
 export const DictionarySchema = z
   .custom<Record<PropertyKey, unknown>>(
-    (value) => isNonNullObject(value) && Object.getPrototypeOf(value) === null,
+    (value) => isNonNullObject(value) && getPrototypeOf(value) === null,
   )
   .describe('Object with null prototype')
   .register(BupkisRegistry, { name: 'dictionary' });
@@ -450,7 +452,7 @@ export const NullProtoObjectSchema = DictionarySchema;
  * @group Schema
  */
 export const AsyncFunctionSchema = FunctionSchema.refine(
-  (value) => Object.prototype.toString.call(value) === '[object AsyncFunction]',
+  (value) => objectPrototype.toString.call(value) === '[object AsyncFunction]',
 )
   .describe('Function declared with the `async` keyword')
   .register(BupkisRegistry, { name: 'async-function' });

package/src/use.ts

@@ -27,6 +27,8 @@ import {
   type UseFn,
 } from './types.js';
 
+const { assign } = Object;
+
 /**
  * Creates an `expect.it()` factory function for generating embeddable assertion
  * executors.
@@ -60,6 +62,7 @@ import {
  *
  * @template SyncAssertions - Array of synchronous assertion objects that define
  *   the available assertion logic for the embeddable functions
+ * @function
  * @param expect - The underlying expect function that will execute the
  *   assertions when the returned executors are called
  * @returns A factory function that creates {@link ExpectItExecutor} instances
@@ -72,8 +75,11 @@ import {
 const createExpectIt = <SyncAssertions extends AnySyncAssertions>(
   expect: any,
 ): ExpectIt<SyncAssertions> => {
+  /**
+   * @function
+   */
   const expectIt = (...args: readonly unknown[]) => {
-    const func = Object.assign(
+    const func = assign(
       (subject: unknown) => {
         const allArgs = [subject, ...args];
         // eslint-disable-next-line @typescript-eslint/no-unsafe-call
@@ -121,6 +127,7 @@ const createExpectIt = <SyncAssertions extends AnySyncAssertions>(
  *
  * @template AsyncAssertions - Array of asynchronous assertion objects that
  *   define the available assertion logic for the embeddable async functions
+ * @function
  * @param expectAsync - The underlying expectAsync function that will execute
  *   the assertions when the returned executors are called
  * @returns A factory function that creates {@link ExpectItExecutorAsync}
@@ -134,8 +141,11 @@ const createExpectIt = <SyncAssertions extends AnySyncAssertions>(
 const createExpectItAsync = <AsyncAssertions extends AnyAsyncAssertions>(
   expectAsync: any,
 ): ExpectItAsync<AsyncAssertions> => {
+  /**
+   * @function
+   */
   const expectItAsync = (...args: readonly unknown[]) => {
-    const func = Object.assign(
+    const func = assign(
       async (subject: unknown) => {
         const allArgs = [subject, ...args];
         // eslint-disable-next-line @typescript-eslint/no-unsafe-call
@@ -210,6 +220,7 @@ const createExpectItAsync = <AsyncAssertions extends AnyAsyncAssertions>(
  *   available in the composed functions
  * @template AsyncAssertions - Array of base asynchronous assertions that will
  *   be available in the composed functions
+ * @function
  * @param syncAssertions - Base synchronous assertions to include in all
  *   composed expect functions
  * @param asyncAssertions - Base asynchronous assertions to include in all
@@ -223,15 +234,18 @@ const createExpectItAsync = <AsyncAssertions extends AnyAsyncAssertions>(
  * @see {@link FilterAsyncAssertions} for how async assertions are extracted
  * @see {@link Concat} for how assertion arrays are combined
  */
-export function createUse<
+export const createUse = <
   const SyncAssertions extends AnySyncAssertions,
   const AsyncAssertions extends AnyAsyncAssertions,
 >(
   syncAssertions: SyncAssertions,
   asyncAssertions: AsyncAssertions,
-): UseFn<SyncAssertions, AsyncAssertions> {
+): UseFn<SyncAssertions, AsyncAssertions> => {
   const syncAssertionsIn = syncAssertions ?? [];
   const asyncAssertionsIn = asyncAssertions ?? [];
+  /**
+   * @function
+   */
   const use: UseFn<SyncAssertions, AsyncAssertions> = <
     AllAssertions extends readonly AnyAssertion[],
     FilteredSyncAssertions extends FilterSyncAssertions<AllAssertions>,
@@ -256,12 +270,12 @@ export function createUse<
     const expectFunction = createExpectSyncFunction(allSyncAssertions);
     const expectAsyncFunction = createExpectAsyncFunction(allAsyncAssertions);
 
-    const expect = Object.assign(
+    const expect = assign(
       expectFunction,
       createBaseExpect(allSyncAssertions, allAsyncAssertions, 'sync'),
       { it: createExpectIt(expectFunction) },
     );
-    const expectAsync = Object.assign(
+    const expectAsync = assign(
       expectAsyncFunction,
       createBaseExpect(allSyncAssertions, allAsyncAssertions, 'async'),
       { it: createExpectItAsync(expectAsyncFunction) },
@@ -276,4 +290,4 @@ export function createUse<
     };
   };
   return use;
-}
+};