bupkis 0.0.2

package/src/assertion/assertion.ts

@@ -0,0 +1,234 @@
+/**
+ * Core assertion class and parsing engine.
+ *
+ * This module implements the main `Assertion` class which handles parsing,
+ * validation, and execution of assertions. It provides the foundational
+ * infrastructure for converting assertion parts into executable validation
+ * logic with comprehensive error handling and type safety.
+ *
+ * @packageDocumentation
+ */
+
+import Debug from 'debug';
+import slug from 'slug';
+import { type ArrayValues } from 'type-fest';
+import { inspect } from 'util';
+import { z } from 'zod/v4';
+
+import { kStringLiteral } from '../constant.js';
+import { AssertionError } from '../error.js';
+import { BupkisRegistry } from '../metadata.js';
+import {
+  type Assertion,
+  type AssertionImpl,
+  type AssertionParts,
+  type AssertionSlots,
+  type ParsedResult,
+  type ParsedValues,
+} from './assertion-types.js';
+
+const debug = Debug('bupkis:assertion');
+
+/**
+ * Modified charmap for {@link slug} to use underscores to replace hyphens (and
+ * for hyphens to replace everything else that needs replacing).
+ *
+ * @see {@link BupkisAssertion.generateUniqueId} for usage
+ */
+const SLUG_CHARMAP = { ...slug.charmap, '-': '_' };
+
+export abstract class BupkisAssertion<
+  Parts extends AssertionParts,
+  Impl extends AssertionImpl<Parts>,
+  Slots extends AssertionSlots<Parts>,
+> implements Assertion<Parts, Impl, Slots>
+{
+  readonly id: string;
+
+  constructor(
+    readonly parts: Parts,
+    readonly slots: Slots,
+    readonly impl: Impl,
+  ) {
+    this.id = this.generateAssertionId();
+    debug('Created assertion %s', this);
+  }
+
+  /**
+   * Parses raw arguments synchronously against this `Assertion`'s Slots to
+   * determine if they match this `Assertion`.
+   *
+   * @param args Raw arguments provided to `expect()`
+   * @returns Result of parsing attempt
+   */
+
+  /**
+   * @returns String representation
+   */
+  public toString(): string {
+    const expand = (zodType: z.core.$ZodType | z.ZodType): string => {
+      const def = 'def' in zodType ? zodType.def : zodType._zod.def;
+      switch (def.type) {
+        case 'custom': {
+          const meta = BupkisRegistry.get(zodType);
+          if (meta?.name) {
+            // our name
+            return `{${meta.name}}`;
+          } else if ('Class' in zodType._zod.bag) {
+            // internal Zod class name. will probably break.
+            return `{${(zodType._zod.bag.Class as new (...args: any[]) => any).name}}`;
+          }
+          return '{custom}';
+        }
+        case 'default':
+          return `{${expand((def as z.core.$ZodDefaultDef).innerType)}}`;
+        case 'enum':
+          return `${Object.keys((def as z.core.$ZodEnumDef<any>).entries as Record<PropertyKey, unknown>).join(' / ')}`;
+        case 'intersection':
+          return `${expand((def as z.core.$ZodIntersectionDef<z.core.$ZodType>).left)} & ${expand((def as z.core.$ZodIntersectionDef<z.core.$ZodType>).right)}`;
+        case 'literal':
+          return (def as z.core.$ZodLiteralDef<any>).values
+            .map((value) => `'${value}'`)
+            .join(' / ');
+        case 'map':
+          return `{Map<${expand((def as z.core.$ZodMapDef).keyType)}, ${expand((def as z.core.$ZodMapDef).valueType)}>`;
+        case 'nonoptional':
+          return `${expand((def as z.core.$ZodNonOptionalDef).innerType)}!`;
+        case 'nullable':
+          return `${expand((def as z.core.$ZodNullableDef).innerType)}? | null`;
+        case 'optional':
+          return `${expand((def as z.core.$ZodOptionalDef).innerType)}?`;
+        case 'record':
+          return `{Record<${expand((def as z.core.$ZodRecordDef).keyType)}, ${expand((def as z.core.$ZodRecordDef).valueType)}>`;
+        case 'set':
+          return `{Set<${expand((def as z.core.$ZodSetDef).valueType)}>`;
+
+        case 'tuple':
+          return `[${(def as z.core.$ZodTupleDef).items.map(expand).join(', ')}]`;
+        case 'union':
+          return (
+            (def as z.core.$ZodUnionDef<any>).options as z.core.$ZodType[]
+          )
+            .map(expand)
+            .join(' | ');
+        default:
+          return `{${def.type}}`;
+      }
+    };
+    return `"${this.slots.map(expand).join(' ')}"`;
+  }
+
+  protected maybeParseValuesArgMismatch<Args extends readonly unknown[]>(
+    args: Args,
+  ): ParsedResult<Parts> | undefined {
+    if (this.slots.length !== args.length) {
+      return {
+        success: false,
+      };
+    }
+  }
+
+  /**
+   * TODO: Fix the return types here. This is all sorts of confusing.
+   *
+   * @param slot Slot to check
+   * @param slotIndex Index of slot
+   * @param rawArg Raw argument
+   * @returns
+   */
+  protected parseSlotForLiteral<Slot extends ArrayValues<Slots>>(
+    slot: Slot,
+    slotIndex: number,
+    rawArg: unknown,
+  ): boolean | ParsedResult<Parts> {
+    const meta = BupkisRegistry.get(slot) ?? {};
+    // our branded literal slots are also tagged in meta for runtime
+    if (kStringLiteral in meta) {
+      if ('value' in meta) {
+        if (rawArg !== meta.value) {
+          return {
+            success: false,
+          };
+        }
+      } else if ('values' in meta) {
+        const allowed = meta.values as readonly string[];
+        if (!allowed.includes(`${rawArg}`)) {
+          return {
+            success: false,
+          };
+        }
+      } else {
+        /* c8 ignore next */
+        throw new TypeError(
+          `Invalid metadata for slot ${slotIndex} with value ${inspect(rawArg)}`,
+        );
+      }
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * 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`
+   */
+  protected translateZodError(
+    stackStartFn: (...args: any[]) => any,
+    zodError: z.ZodError,
+    ...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,
+    });
+  }
+
+  /**
+   * Generates a unique¹ ID for this assertion by combining content, structure,
+   * and type information.
+   *
+   * - `s` is slot count
+   * - `p` is part count
+   *
+   * Slugifies the string representation of the assertion. Does not collapse
+   * adjacent hyphens, as hyphens are significant in phrase literals.
+   *
+   * @remarks
+   * ¹: "Unique" here means "unique enough" for practical purposes. This is not
+   * cryptographically unique, nor does it need to be. The goal is to avoid
+   * collisions in common scenarios while keeping the ID human-readable.
+   * @returns A human-readable unique identifier
+   */
+  private generateAssertionId(): string {
+    const baseSlug = slug(`${this}`, {
+      charmap: SLUG_CHARMAP,
+    });
+
+    // Add structural signature for additional uniqueness
+    // Use simple slot count and parts count as differentiators
+    const signature = `${this.slots.length}s${this.parts.length}p`;
+
+    return `${baseSlug}-${signature}`;
+  }
+}

package/src/assertion/create.ts

@@ -0,0 +1,226 @@
+/**
+ * Assertion creation factory functions with type-safe sync/async separation.
+ *
+ * This module provides the core factory functions for creating both synchronous
+ * and asynchronous assertions in the Bupkis assertion framework. It implements
+ * a dual-creation pattern where `createAssertion()` creates synchronous-only
+ * assertions and `createAsyncAssertion()` creates potentially asynchronous
+ * assertions, using branded Zod schema types to enforce compile-time safety and
+ * prevent accidental mixing of sync and async implementations.
+ *
+ * The module supports two primary assertion implementation types:
+ *
+ * - **Schema-based assertions**: Using {@link z.ZodType Zod schemas} for
+ *   validation
+ * - **Function-based assertions**: Using implementation functions that return
+ *   boolean, void, or Zod schemas for dynamic validation
+ *
+ * @remarks
+ * The factory functions use branded types to distinguish between synchronous
+ * and asynchronous schema implementations at compile time. This prevents
+ * accidentally passing async schemas to sync assertion creators and vice versa,
+ * ensuring type safety throughout the assertion system.
+ * @example Creating a synchronous string assertion:
+ *
+ * ```ts
+ * import { createAssertion } from './create.js';
+ * import { z } from 'zod/v4';
+ *
+ * const stringAssertion = createAssertion(['to be a string'], z.string());
+ * ```
+ *
+ * @example Creating an asynchronous Promise resolution assertion:
+ *
+ * ```ts
+ * import { createAsyncAssertion } from './create.js';
+ *
+ * const promiseAssertion = createAsyncAssertion(
+ *   ['to resolve'],
+ *   async (promise) => {
+ *     try {
+ *       await promise;
+ *       return true;
+ *     } catch {
+ *       return false;
+ *     }
+ *   },
+ * );
+ * ```
+ *
+ * @example Creating parameterized assertions:
+ *
+ * ```ts
+ * import { createAssertion } from './create.js';
+ * import { z } from 'zod/v4';
+ *
+ * const greaterThanAssertion = createAssertion(
+ *   [z.number(), 'to be greater than', z.number()],
+ *   (subject, expected) => subject > expected,
+ * );
+ * ```
+ *
+ * @packageDocumentation
+ * @see {@link AssertionParts} for assertion part structure
+ * @see {@link AssertionSlots} for processed slot definitions
+ * @see {@link AssertionImplSync} for synchronous implementation types
+ * @see {@link AssertionImplAsync} for asynchronous implementation types
+ */
+
+import { z } from 'zod/v4';
+
+import type {
+  AssertionFunctionAsync,
+  AssertionFunctionSync,
+  AssertionImplAsync,
+  AssertionImplFnAsync,
+  AssertionImplFnSync,
+  AssertionImplSchemaAsync,
+  AssertionImplSchemaSync,
+  AssertionImplSync,
+  AssertionParts,
+  AssertionSchemaAsync,
+  AssertionSchemaSync,
+  AssertionSlots,
+  RawAssertionImplSchemaSync,
+} from './assertion-types.js';
+
+import { isFunction, isString, isZodType } from '../guards.js';
+import {
+  BupkisAssertionFunctionAsync,
+  BupkisAssertionSchemaAsync,
+} from './assertion-async.js';
+import {
+  BupkisAssertionFunctionSync,
+  BupkisAssertionSchemaSync,
+} from './assertion-sync.js';
+import { slotify } from './slotify.js';
+
+/**
+ * Create a synchronous `Assertion` from {@link AssertionParts parts} and a
+ * {@link z.ZodType Zod schema}.
+ *
+ * @param parts Assertion parts defining the shape of the assertion
+ * @param impl Implementation as a Zod schema
+ * @returns New `SchemaAssertion` instance
+ * @throws {TypeError} Invalid assertion implementation type
+ */
+export function createAssertion<
+  const Parts extends AssertionParts,
+  Impl extends RawAssertionImplSchemaSync<Parts>,
+  Slots extends AssertionSlots<Parts>,
+>(
+  parts: Parts,
+  impl: Impl,
+): AssertionSchemaSync<Parts, AssertionImplSchemaSync<Parts>, Slots>;
+/**
+ * Create a synchronous `Assertion` from {@link AssertionParts parts} and an
+ * implementation function.
+ *
+ * @param parts Assertion parts defining the shape of the assertion
+ * @param impl Implementation as a function
+ * @returns New `FunctionAssertion` instance
+ * @throws {TypeError} Invalid assertion implementation type
+ */
+export function createAssertion<
+  const Parts extends AssertionParts,
+  Impl extends AssertionImplFnSync<Parts>,
+  Slots extends AssertionSlots<Parts>,
+>(parts: Parts, impl: Impl): AssertionFunctionSync<Parts, Impl, Slots>;
+export function createAssertion<
+  Impl extends AssertionImplSync<Parts>,
+  const Parts extends AssertionParts,
+>(parts: Parts, impl: Impl) {
+  if (!Array.isArray(parts)) {
+    throw new TypeError('First parameter must be an array');
+  }
+  if (parts.length === 0) {
+    throw new TypeError('At least one value is required for an assertion');
+  }
+  if (
+    !parts.every(
+      (part) => isString(part) || Array.isArray(part) || isZodType(part),
+    )
+  ) {
+    throw new TypeError('All assertion parts must be strings or Zod schemas');
+  }
+  if (!impl) {
+    throw new TypeError('An assertion implementation is required');
+  }
+  try {
+    const slots = slotify<Parts>(parts);
+
+    if (isZodType(impl)) {
+      return new BupkisAssertionSchemaSync(parts, slots, impl);
+    } else if (isFunction(impl)) {
+      return new BupkisAssertionFunctionSync(parts, slots, impl);
+    }
+  } catch (err) {
+    if (err instanceof z.ZodError) {
+      throw new TypeError(z.prettifyError(err));
+    }
+    throw err;
+  }
+  throw new TypeError(
+    'Assertion implementation must be a function, Zod schema or Zod schema factory',
+  );
+}
+/**
+ * Create an async `Assertion` from {@link AssertionParts parts} and an async
+ * {@link z.ZodType Zod schema}.
+ *
+ * @param parts Assertion parts defining the shape of the assertion
+ * @param impl Implementation as a Zod schema (potentially async)
+ * @returns New `BupkisAssertionSchemaAsync` instance
+ * @throws {TypeError} Invalid assertion implementation type
+ */
+export function createAsyncAssertion<
+  const Parts extends AssertionParts,
+  Impl extends AssertionImplSchemaAsync<Parts>,
+  Slots extends AssertionSlots<Parts>,
+>(parts: Parts, impl: Impl): AssertionSchemaAsync<Parts, Impl, Slots>;
+
+/**
+ * Create an async `Assertion` from {@link AssertionParts parts} and an
+ * implementation function.
+ *
+ * @param parts Assertion parts defining the shape of the assertion
+ * @param impl Implementation as a function (potentially async)
+ * @returns New `FunctionAssertion` instance
+ * @throws {TypeError} Invalid assertion implementation type
+ */
+export function createAsyncAssertion<
+  const Parts extends AssertionParts,
+  Impl extends AssertionImplFnAsync<Parts>,
+  Slots extends AssertionSlots<Parts>,
+>(parts: Parts, impl: Impl): AssertionFunctionAsync<Parts, Impl, Slots>;
+export function createAsyncAssertion<
+  const Parts extends AssertionParts,
+  Impl extends AssertionImplAsync<Parts>,
+>(parts: Parts, impl: Impl) {
+  if (!Array.isArray(parts)) {
+    throw new TypeError('First parameter must be an array');
+  }
+  if (parts.length === 0) {
+    throw new TypeError('At least one value is required for an assertion');
+  }
+  if (
+    !parts.every(
+      (part) => isString(part) || Array.isArray(part) || isZodType(part),
+    )
+  ) {
+    throw new TypeError('All assertion parts must be strings or Zod schemas');
+  }
+  if (!impl) {
+    throw new TypeError('An assertion implementation is required');
+  }
+  const slots = slotify<Parts>(parts);
+
+  if (isZodType(impl)) {
+    return new BupkisAssertionSchemaAsync(parts, slots, impl);
+  } else if (isFunction(impl)) {
+    return new BupkisAssertionFunctionAsync(parts, slots, impl);
+  }
+  throw new TypeError(
+    'Assertion implementation must be a function, Zod schema or Zod schema factory',
+  );
+}

package/src/assertion/impl/README.md

@@ -0,0 +1,13 @@
+# Assertion Implementations
+
+This dir contains all the built-in assertions that come with _BUPKIS_.
+
+They are sorted into the following files:
+
+- `async.ts`: Assertions concerning asynchronous functions
+- `sync-basic.ts`: Basic assertions that don't take parameters, e.g. "to be a string", "to be empty", "to be an Error", etc.
+- `sync-collection.ts`: Assertions concerning collections (arrays, `Set`s, `Map`s, objects); may or may not be parametric
+- `sync-esoteric.ts`: Arcane assertions
+- `sync-parametric.ts`: Assertions that take parameters, e.g. "to be greater than", "to be one of", "to have property", etc.
+
+All sync assertions are collected and re-exported from `sync.ts`.