bupkis 0.2.0 → 0.4.0

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,46 +36,52 @@ import { z } from 'zod/v4';
 
 import {
   isA,
-  isConstructable,
+  isConstructible,
+  isExpectItExecutor,
   isFunction,
   isNonNullObject,
   isPromiseLike,
 } from './guards.js';
 import { BupkisRegistry } from './metadata.js';
-import { type Constructor, type MutableOrReadonly } from './types.js';
+import {
+  type Constructor,
+  type ExpectItExecutor,
+  type MutableOrReadonly,
+  type SatisfyPatternValue,
+} from './types.js';
 
 /**
- * A Zod schema that validates JavaScript classes or constructor functions.
+ * A Zod schema that validates JavaScript constructible functions.
  *
  * 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
  * The schema is registered in the {@link BupkisRegistry} with the name
- * `ClassSchema` for later reference and type checking purposes.
+ * `ConstructibleSchema` for later reference and type checking purposes.
  * @example
  *
  * ```typescript
  * class MyClass {}
  * function MyConstructor() {}
  *
- * ClassSchema.parse(MyClass); // ✓ Valid
- * ClassSchema.parse(MyConstructor); // ✓ Valid
- * ClassSchema.parse(Array); // ✓ Valid
- * ClassSchema.parse(Date); // ✓ Valid
- * ClassSchema.parse(() => {}); // ✗ Throws validation error
- * ClassSchema.parse({}); // ✗ Throws validation error
+ * ConstructibleSchema.parse(MyClass); // ✓ Valid
+ * ConstructibleSchema.parse(MyConstructor); // ✓ Valid
+ * ConstructibleSchema.parse(Array); // ✓ Valid
+ * ConstructibleSchema.parse(Date); // ✓ Valid
+ * ConstructibleSchema.parse(() => {}); // ✗ Throws validation error
+ * ConstructibleSchema.parse({}); // ✗ Throws validation error
  * ```
  *
  * @group Schema
  */
 
-export const ClassSchema = z
-  .custom<Constructor>(isConstructable)
-  .register(BupkisRegistry, { name: 'ClassSchema' })
-  .describe('Class / Constructor');
+export const ConstructibleSchema = z
+  .custom<Constructor>(isConstructible)
+  .register(BupkisRegistry, { name: 'ConstructibleSchema' })
+  .describe('Constructible Function');
 
 /**
  * A Zod schema that validates any JavaScript function.
@@ -242,9 +248,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 +269,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 +293,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 +335,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 +371,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 +409,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 +491,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
@@ -495,3 +512,84 @@ export const RegExpSchema = z
   .instanceof(RegExp)
   .describe('A RegExp instance')
   .register(BupkisRegistry, { name: 'RegExp' });
+
+/**
+ * A recursive Zod schema that validates values allowed in "to satisfy"
+ * assertion patterns.
+ *
+ * This schema defines the allowed structure for patterns used with "to satisfy"
+ * and "to be like" assertions. It supports a recursive structure that can
+ * contain:
+ *
+ * - **Primitive values**: strings, numbers, booleans, null, undefined, bigint,
+ *   symbols
+ * - **Regular expressions**: for pattern matching against string values
+ * - **ExpectItExecutor functions**: nested assertions created via `expect.it()`
+ * - **Objects**: with properties that recursively follow this same pattern
+ * - **Arrays**: with elements that recursively follow this same pattern
+ *
+ * The schema handles the special semantics required for "to satisfy"
+ * assertions:
+ *
+ * - RegExp values are used for pattern testing rather than exact matching
+ * - ExpectItExecutor functions are executed as nested assertions
+ * - Objects and arrays can contain any combination of the above recursively
+ *
+ * @privateRemarks
+ * Uses `z.lazy()` to handle recursive object and array structures without
+ * causing infinite recursion during schema definition. The schema is registered
+ * in the `BupkisRegistry` for reference and type checking.
+ * @example
+ *
+ * ```typescript
+ * // Primitive values
+ * SatisfyPatternSchema.parse('hello'); // ✓ Valid
+ * SatisfyPatternSchema.parse(42); // ✓ Valid
+ * SatisfyPatternSchema.parse(true); // ✓ Valid
+ *
+ * // Regular expressions for pattern matching
+ * SatisfyPatternSchema.parse(/test/); // ✓ Valid
+ *
+ * // ExpectItExecutor functions
+ * SatisfyPatternSchema.parse(expect.it('to be a string')); // ✓ Valid
+ *
+ * // Complex nested structures
+ * SatisfyPatternSchema.parse({
+ *   name: expect.it('to be a string'),
+ *   email: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
+ *   age: expect.it('to be greater than', 0),
+ *   tags: [expect.it('to be a string')],
+ * }); // ✓ Valid
+ *
+ * // Invalid values
+ * SatisfyPatternSchema.parse(new Date()); // ✗ Invalid (not supported type)
+ * SatisfyPatternSchema.parse(() => {}); // ✗ Invalid (regular function, not ExpectItExecutor)
+ * ```
+ *
+ * @group Schema
+ */
+export const SatisfyPatternSchema: z.ZodType<SatisfyPatternValue> = z
+  .lazy(() =>
+    z.union([
+      // Primitive types
+      z.string(),
+      z.number(),
+      z.boolean(),
+      z.null(),
+      z.undefined(),
+      z.bigint(),
+      z.symbol(),
+
+      // Special types for "to satisfy" semantics
+      z.instanceof(RegExp), // For pattern matching
+      z.custom<ExpectItExecutor<any>>(isExpectItExecutor, {
+        message:
+          'Expected an ExpectItExecutor function (created with expect.it())',
+      }), // For nested assertions
+
+      // Recursive structures
+      z.array(SatisfyPatternSchema), // Arrays of satisfy patterns
+      z.record(z.string(), SatisfyPatternSchema), // Objects with satisfy pattern values
+    ]),
+  )
+  .register(BupkisRegistry, { name: 'SatisfyPatternSchema' });

package/src/types.ts

@@ -53,6 +53,8 @@ import type {
   RawAssertionImplSchemaSync,
 } from './assertion/assertion-types.js';
 
+import { type kExpectIt } from './constant.js';
+
 /**
  * Creates a negated version of a tuple of
  * {@link AssertionPart | AssertionParts}.
@@ -110,8 +112,6 @@ export interface BaseExpect {
   fail: FailFn;
 }
 
-export type * from './assertion/assertion-types.js';
-
 /**
  * The main API as returned by a {@link UseFn}.
  *
@@ -166,6 +166,8 @@ export interface Bupkis<
   >;
 }
 
+export type * from './assertion/assertion-types.js';
+
 /**
  * Helper type to concatenate two tuples
  */
@@ -269,14 +271,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.
@@ -405,6 +400,125 @@ export type ExpectFunction<
   }>
 >;
 
+/**
+ * Creates embeddable assertion functions that can be used with `to satisfy`.
+ *
+ * This type generates a union of all possible `expect.it` function signatures
+ * based on the available synchronous assertions. Each assertion contributes its
+ * own function signature to create embeddable executors that can be used within
+ * object patterns for complex validation scenarios.
+ *
+ * The resulting functions are designed to be used exclusively within `'to
+ * satisfy'` assertion contexts, where they provide type-safe pattern matching
+ * for nested object structures. Direct execution of these functions outside of
+ * their intended context is not supported.
+ *
+ * @example
+ *
+ * ```typescript
+ * // Create embeddable assertion functions
+ * const isString = expect.it('to be a string');
+ * const isPositive = expect.it('to be greater than', 0);
+ *
+ * // Use within 'to satisfy' patterns
+ * expect(user, 'to satisfy', {
+ *   name: isString,
+ *   age: isPositive,
+ *   email: /\S+@\S+/,
+ * });
+ * ```
+ *
+ * @template SyncAssertions - Array of synchronous assertion objects that define
+ *   the available assertion logic for embeddable functions
+ * @see {@link ExpectItFunction} for individual function signature generation
+ * @see {@link ExpectItExecutor} for the executor function interface
+ */
+export type ExpectIt<
+  SyncAssertions extends AnySyncAssertions = BuiltinSyncAssertions,
+> = UnionToIntersection<
+  TupleToUnion<{
+    [K in keyof SyncAssertions]: SyncAssertions[K] extends AnySyncAssertion
+      ? SyncAssertions[K]['parts'] extends AssertionParts
+        ? ExpectItFunction<SyncAssertions[K]['parts']>
+        : never
+      : never;
+  }>
+>;
+
+/**
+ * Interface for executor functions created by `expect.it()`.
+ *
+ * ExpectItExecutor functions are the result of calling `expect.it()` with
+ * assertion parameters. They encapsulate the assertion logic and can be
+ * executed later within `'to satisfy'` pattern matching contexts. These
+ * functions are marked with an internal symbol to distinguish them from regular
+ * functions during pattern validation.
+ *
+ * The executor accepts a subject value and performs the embedded assertion
+ * logic against it. The subject type is constrained by the Zod schema that
+ * represents the first part of the assertion definition, ensuring type safety
+ * during pattern matching.
+ *
+ * @example
+ *
+ * ```typescript
+ * const isStringExecutor = expect.it('to be a string');
+ * // isStringExecutor is an ExpectItExecutor<z.ZodString>
+ *
+ * // Used within satisfy patterns
+ * expect({ name: 'Alice' }, 'to satisfy', {
+ *   name: isStringExecutor, // Validates that name is a string
+ * });
+ * ```
+ *
+ * @template Subject - The Zod schema type that constrains the subject parameter
+ * @see {@link ExpectItFunction} for the factory function that creates executors
+ */
+export interface ExpectItExecutor<Subject extends z.ZodType> {
+  (subject: z.infer<Subject>): void;
+  [kExpectIt]: true;
+}
+
+/**
+ * Function signature for creating ExpectItExecutor instances.
+ *
+ * This type represents the factory function that creates embeddable assertion
+ * executors from assertion parts. It takes the assertion parameters (excluding
+ * the subject) and returns an executor function that can be embedded within
+ * `'to satisfy'` patterns.
+ *
+ * The function signature is derived from assertion parts by removing the first
+ * part (which becomes the subject type for the executor) and using the
+ * remaining parts as parameters. This allows for natural language assertion
+ * creation that mirrors the main `expect()` function but produces reusable
+ * executor functions.
+ *
+ * The resulting executor is constrained to only work with subjects that match
+ * the first assertion part, providing compile-time type safety for pattern
+ * matching scenarios.
+ *
+ * @example
+ *
+ * ```typescript
+ * // For assertion parts: [z.string(), 'to match', z.instanceof(RegExp)]
+ * // Results in function: (pattern: RegExp) => ExpectItExecutor<z.ZodString>
+ * const matchesPattern = expect.it('to match', /^[A-Z]/);
+ *
+ * expect({ code: 'ABC123' }, 'to satisfy', {
+ *   code: matchesPattern, // Validates that code matches the pattern
+ * });
+ * ```
+ *
+ * @template Parts - Tuple of assertion parts that define the function signature
+ *   and executor constraints
+ * @see {@link ExpectItExecutor} for the returned executor interface
+ * @see {@link TupleTail} for parameter extraction from assertion parts
+ * @see {@link SlotsFromParts} for type slot generation
+ */
+export type ExpectItFunction<Parts extends AssertionParts> = (
+  ...args: MutableOrReadonly<TupleTail<SlotsFromParts<Parts>>>
+) => Parts[0] extends z.ZodType ? ExpectItExecutor<Parts[0]> : never;
+
 /**
  * Properties of {@link expect}.
  */
@@ -419,6 +533,8 @@ export interface ExpectSyncProps<
    */
   assertions: SyncAssertions;
 
+  it: ExpectIt<SyncAssertions>;
+
   /**
    * Function to add more assertions to this `expect()`, returning a new
    * `expect()` and `expectAsync()` pair with the combined assertions.
@@ -607,6 +723,23 @@ export type MutableOrReadonly<Tuple extends readonly unknown[]> =
  */
 export type Negation<S extends string> = `not ${S}`;
 
+export type SatisfyPatternValue =
+  | bigint
+  | boolean
+  | ExpectItExecutor<any>
+  | Map<SatisfyPatternValue, SatisfyPatternValue>
+  | null
+  | number
+  | RegExp
+  | SatisfyPatternValue[]
+  | Set<SatisfyPatternValue>
+  | string
+  | symbol
+  | undefined
+  | WeakMap<Extract<SatisfyPatternValue, object>, SatisfyPatternValue>
+  | WeakSet<Extract<SatisfyPatternValue, object>>
+  | { [key: string]: SatisfyPatternValue };
+
 /**
  * Converts AssertionParts to complete function parameter types for expect
  * functions.
@@ -653,6 +786,29 @@ export type SlotsFromParts<Parts extends AssertionParts> = NoNeverTuple<
     : never
 >;
 
+/**
+ * Gets the tail (all elements except the first) of a tuple type.
+ *
+ * Unlike ArrayTail from type-fest, this preserves the tuple structure as a
+ * readonly tuple rather than converting to an array type.
+ *
+ * @example
+ *
+ * ```typescript
+ * type Example = TupleTail<readonly [string, number, boolean]>; // readonly [number, boolean]
+ * type Single = TupleTail<readonly [string]>; // readonly []
+ * type Empty = TupleTail<readonly []>; // readonly []
+ * ```
+ *
+ * @template T - The tuple type to get the tail of
+ */
+export type TupleTail<T extends readonly unknown[]> = T extends readonly [
+  unknown,
+  ...infer Rest,
+]
+  ? Rest
+  : readonly [];
+
 /**
  * The type of a `use()` function.
  */
@@ -684,3 +840,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;
+}

package/src/use.ts

@@ -5,6 +5,7 @@ import {
   type AnyAsyncAssertions,
   type AnySyncAssertions,
 } from './assertion/assertion-types.js';
+import { kExpectIt } from './constant.js';
 import {
   createBaseExpect,
   createExpectAsyncFunction,
@@ -12,11 +13,31 @@ import {
 } from './expect.js';
 import {
   type Concat,
+  type ExpectIt,
   type FilterAsyncAssertions,
   type FilterSyncAssertions,
   type UseFn,
 } from './types.js';
 
+const createExpectIt = <SyncAssertions extends AnySyncAssertions>(
+  expect: any,
+): ExpectIt<SyncAssertions> => {
+  const expectIt = (...args: readonly unknown[]) => {
+    const func = Object.assign(
+      (subject: unknown) => {
+        const allArgs = [subject, ...args];
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+        expect(...allArgs);
+      },
+      {
+        [kExpectIt]: true,
+      },
+    );
+    return func;
+  };
+  return expectIt as unknown as ExpectIt<SyncAssertions>;
+};
+
 export function createUse<
   const T extends AnySyncAssertions,
   const U extends AnyAsyncAssertions,
@@ -50,6 +71,7 @@ export function createUse<
     const expect = Object.assign(
       expectFunction,
       createBaseExpect(allSyncAssertions, allAsyncAssertions, 'sync'),
+      { it: createExpectIt(expectFunction) },
     );
     const expectAsync = Object.assign(
       expectAsyncFunction,