bupkis 0.3.0 → 0.4.0

package/src/schema.ts

@@ -37,15 +37,21 @@ import { z } from 'zod/v4';
 import {
   isA,
   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
@@ -54,28 +60,28 @@ import { type Constructor, type MutableOrReadonly } from './types.js';
  *
  * @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
+export const ConstructibleSchema = z
   .custom<Constructor>(isConstructible)
-  .register(BupkisRegistry, { name: 'ClassSchema' })
-  .describe('Class / Constructor');
+  .register(BupkisRegistry, { name: 'ConstructibleSchema' })
+  .describe('Constructible Function');
 
 /**
  * A Zod schema that validates any JavaScript function.
@@ -506,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
  */
@@ -398,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}.
  */
@@ -412,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.
@@ -600,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.
@@ -646,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.
  */

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,

package/src/value-to-schema.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod/v4';
 
 import {
+  isExpectItExecutor,
   isNonNullObject,
   isObject,
   isPromiseLike,
@@ -100,6 +101,30 @@ export const valueToSchema = (
     case 'boolean':
       return literalPrimitives ? z.literal(value as boolean) : z.boolean();
     case 'function':
+      // Check if this is an ExpectItExecutor
+      if (isExpectItExecutor(value)) {
+        // Only allow nested assertions when strict is false (e.g., "to satisfy" semantics)
+        if (strict) {
+          throw new TypeError(
+            'ExpectItExecutor (expect.it) functions are not allowed in strict mode. ' +
+              'Use "to satisfy" assertions for nested expectations.',
+          );
+        }
+        // Return a schema that executes the ExpectItExecutor when validated
+        return z.custom<unknown>(
+          (subject: unknown) => {
+            try {
+              value(subject);
+              return true;
+            } catch {
+              return false;
+            }
+          },
+          {
+            message: 'Failed expect.it assertion',
+          },
+        );
+      }
       return z.function();
     case 'number':
       return literalPrimitives ? z.literal(value as number) : z.number();