bupkis 0.0.2

package/src/assertion/impl/async.ts

@@ -0,0 +1,284 @@
+/**
+ * Asynchronous assertion implementations.
+ *
+ * This module contains all built-in asynchronous assertion implementations for
+ * working with Promises and async operations. It provides assertions for
+ * Promise resolution, rejection, and async function behavior validation with
+ * comprehensive error handling.
+ *
+ * @packageDocumentation
+ */
+
+import { inspect } from 'node:util';
+import { z } from 'zod/v4';
+
+import { isA, isNonNullObject, isString } from '../../guards.js';
+import {
+  ClassSchema,
+  FunctionSchema,
+  WrappedPromiseLikeSchema,
+} from '../../schema.js';
+import { valueToSchema } from '../../util.js';
+import { createAsyncAssertion } from '../create.js';
+
+const trapAsyncFnError = async (fn: () => unknown) => {
+  try {
+    await fn();
+  } catch (err) {
+    return err;
+  }
+};
+
+const trapPromiseError = async (promise: PromiseLike<unknown>) => {
+  try {
+    await promise;
+  } catch (err) {
+    return err;
+  }
+};
+
+export const AsyncAssertions = [
+  createAsyncAssertion(
+    [FunctionSchema, ['to resolve', 'to fulfill']],
+    async (subject) => {
+      try {
+        await subject();
+        return true;
+      } catch {
+        return false;
+      }
+    },
+  ),
+  createAsyncAssertion(
+    [WrappedPromiseLikeSchema, ['to resolve', 'to fulfill']],
+    async (subject) => {
+      try {
+        await subject;
+        return true;
+      } catch {
+        return false;
+      }
+    },
+  ),
+
+  // Non-parameterized "to reject" assertions
+  createAsyncAssertion([FunctionSchema, 'to reject'], async (subject) => {
+    let rejected = false;
+    try {
+      await subject();
+    } catch {
+      rejected = true;
+    }
+    return rejected;
+  }),
+  createAsyncAssertion(
+    [WrappedPromiseLikeSchema, 'to reject'],
+    async (subject) => {
+      let rejected = false;
+      try {
+        await subject;
+      } catch {
+        rejected = true;
+      }
+      return rejected;
+    },
+  ),
+  // Parameterized "to reject" with class constructor
+  createAsyncAssertion(
+    [FunctionSchema, ['to reject with a', 'to reject with an'], ClassSchema],
+    async (subject, ctor) => {
+      const error = await trapAsyncFnError(subject);
+      if (!error) {
+        return false;
+      }
+      return isA(error, ctor);
+    },
+  ),
+  createAsyncAssertion(
+    [
+      WrappedPromiseLikeSchema,
+      ['to reject with a', 'to reject with an'],
+      ClassSchema,
+    ],
+    async (subject, ctor) => {
+      const error = await trapPromiseError(subject);
+      if (!error) {
+        return false;
+      }
+      return isA(error, ctor);
+    },
+  ),
+
+  // Parameterized "to reject" with string, RegExp, or object patterns
+  createAsyncAssertion(
+    [
+      FunctionSchema,
+      ['to reject with'],
+      z.union([z.string(), z.instanceof(RegExp), z.looseObject({})]),
+    ],
+    async (subject, param) => {
+      const error = await trapAsyncFnError(subject);
+      if (!error) {
+        return false;
+      }
+
+      if (isString(param)) {
+        return z
+          .object({
+            message: z.coerce.string().pipe(z.literal(param)),
+          })
+          .or(z.coerce.string().pipe(z.literal(param)))
+          .safeParse(error).success;
+      } else if (isA(param, RegExp)) {
+        return z
+          .object({
+            message: z.coerce.string().regex(param),
+          })
+          .or(z.coerce.string().regex(param))
+          .safeParse(error).success;
+      } else if (isNonNullObject(param)) {
+        return valueToSchema(param, { strict: false }).safeParse(error).success;
+      } else {
+        throw new TypeError(`Invalid parameter schema: ${inspect(param)}`);
+      }
+    },
+  ),
+  createAsyncAssertion(
+    [
+      WrappedPromiseLikeSchema,
+      ['to reject with'],
+      z.union([z.string(), z.instanceof(RegExp), z.looseObject({})]),
+    ],
+    async (subject, param) => {
+      const error = await trapPromiseError(subject);
+      if (!error) {
+        return false;
+      }
+
+      if (isString(param)) {
+        return z
+          .object({
+            message: z.coerce.string().pipe(z.literal(param)),
+          })
+          .or(z.coerce.string().pipe(z.literal(param)))
+          .safeParse(error).success;
+      } else if (isA(param, RegExp)) {
+        return z
+          .object({
+            message: z.coerce.string().regex(param),
+          })
+          .or(z.coerce.string().regex(param))
+          .safeParse(error).success;
+      } else if (isNonNullObject(param)) {
+        return valueToSchema(param, { strict: false }).safeParse(error).success;
+      } else {
+        throw new TypeError(`Invalid parameter schema: ${inspect(param)}`);
+      }
+    },
+  ),
+
+  createAsyncAssertion(
+    [
+      WrappedPromiseLikeSchema,
+      ['to fulfill with value satisfying', 'to resolve to value satisfying'],
+      z.union([z.string(), z.instanceof(RegExp), z.looseObject({})]),
+    ],
+    async (promise, param) => {
+      let value: unknown;
+      try {
+        value = await promise;
+      } catch (err) {
+        return {
+          actual: err,
+          expect: 'promise to not reject',
+          message: `Expected promise to not reject, but it rejected with ${inspect(
+            err,
+          )}`,
+        };
+      }
+      if (isString(param)) {
+        return z
+          .object({
+            message: z.coerce.string().pipe(z.literal(param)),
+          })
+          .or(z.coerce.string().pipe(z.literal(param)))
+          .safeParse(value).success;
+      } else if (isA(param, RegExp)) {
+        return z
+          .object({
+            message: z.coerce.string().regex(param),
+          })
+          .or(z.coerce.string().regex(param))
+          .safeParse(value).success;
+      } else if (isNonNullObject(param)) {
+        const schema = valueToSchema(param);
+        const result = schema.safeParse(value);
+        if (!result.success) {
+          return {
+            actual: value,
+            expected: param,
+            message: `Expected resolved value to satisfy schema ${inspect(
+              param,
+            )}, but it does not`,
+          };
+        }
+        return true;
+      } else {
+        throw new TypeError(`Invalid parameter schema: ${inspect(param)}`);
+      }
+    },
+  ),
+
+  createAsyncAssertion(
+    [
+      FunctionSchema,
+      ['to fulfill with value satisfying', 'to resolve to value satisfying'],
+      z.union([z.string(), z.instanceof(RegExp), z.looseObject({})]),
+    ],
+    async (subject, param) => {
+      let value: unknown;
+      try {
+        value = await subject();
+      } catch (err) {
+        return {
+          actual: err,
+          expect: 'function to not throw',
+          message: `Expected function to not throw, but it threw ${inspect(
+            err,
+          )}`,
+        };
+      }
+
+      if (isString(param)) {
+        return z
+          .object({
+            message: z.coerce.string().pipe(z.literal(param)),
+          })
+          .or(z.coerce.string().pipe(z.literal(param)))
+          .safeParse(value).success;
+      } else if (isA(param, RegExp)) {
+        return z
+          .object({
+            message: z.coerce.string().regex(param),
+          })
+          .or(z.coerce.string().regex(param))
+          .safeParse(value).success;
+      } else if (isNonNullObject(param)) {
+        const schema = valueToSchema(param);
+        const result = schema.safeParse(value);
+        if (!result.success) {
+          return {
+            actual: value,
+            expected: param,
+            message: `Expected resolved value to satisfy schema ${inspect(
+              param,
+            )}, but it does not`,
+          };
+        }
+        return true;
+      } else {
+        throw new TypeError(`Invalid parameter schema: ${inspect(param)}`);
+      }
+    },
+  ),
+] as const;

package/src/assertion/impl/index.ts

@@ -0,0 +1,2 @@
+export { AsyncAssertions } from './async.js';
+export { SyncAssertions } from './sync.js';

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

@@ -0,0 +1,111 @@
+import { z } from 'zod/v4';
+
+import { BupkisRegistry } from '../../metadata.js';
+import {
+  AsyncFunctionSchema,
+  ClassSchema,
+  FalsySchema,
+  FunctionSchema,
+  PrimitiveSchema,
+  PropertyKeySchema,
+  StrongSetSchema,
+  TruthySchema,
+} from '../../schema.js';
+import { createAssertion } from '../create.js';
+
+/**
+ * Basic synchronous assertions.
+ */
+export const BasicAssertions = [
+  createAssertion(['to be a string'], z.string()),
+  createAssertion([['to be a number', 'to be finite']], z.number()),
+  createAssertion(['to be infinite'], z.literal([Infinity, -Infinity])),
+  createAssertion(['to be Infinity'], z.literal(Infinity)),
+  createAssertion(['to be -Infinity'], z.literal(-Infinity)),
+  createAssertion(
+    [['to be a boolean', 'to be boolean', 'to be a bool']],
+    z.boolean(),
+  ),
+  createAssertion(
+    [['to be positive', 'to be a positive number']],
+    z.number().positive(),
+  ),
+  createAssertion(
+    [['to be a positive integer', 'to be a positive int']],
+    z.number().int().positive(),
+  ),
+  createAssertion(
+    [['to be negative', 'to be a negative number']],
+    z.number().negative(),
+  ),
+  createAssertion(
+    [['to be a negative integer', 'to be a negative int']],
+    z.number().int().negative(),
+  ),
+  createAssertion(['to be true'], z.literal(true)),
+  createAssertion(['to be false'], z.literal(false)),
+  createAssertion([['to be a bigint', 'to be a BigInt']], z.bigint()),
+  createAssertion([['to be a symbol', 'to be a Symbol']], z.symbol()),
+  createAssertion(['to be a function'], FunctionSchema),
+  createAssertion(['to be an async function'], AsyncFunctionSchema),
+  createAssertion(['to be NaN'], z.nan()),
+  createAssertion(
+    [
+      [
+        'to be an integer',
+        'to be a safe integer',
+        'to be an int',
+        'to be a safe int',
+      ],
+    ],
+    z.number().int(),
+  ),
+  createAssertion(['to be null'], z.null()),
+  createAssertion(['to be undefined'], z.undefined()),
+  createAssertion([['to be an array', 'to be array']], z.array(z.any())),
+  createAssertion([['to be a date', 'to be a Date']], z.date()),
+  createAssertion([['to be a class', 'to be a constructor']], ClassSchema),
+  createAssertion(['to be a primitive'], PrimitiveSchema),
+
+  createAssertion(
+    [['to be a RegExp', 'to be a regex', 'to be a regexp']],
+    z.instanceof(RegExp),
+  ),
+  createAssertion([['to be truthy', 'to exist', 'to be ok']], TruthySchema),
+  createAssertion(['to be falsy'], FalsySchema),
+  createAssertion(
+    ['to be an object'],
+    z
+      .any()
+      .nonoptional()
+      .refine((value) => typeof value == 'object' && value !== null)
+      .describe(
+        'Returns true for any non-null value where `typeof value` is `object`',
+      )
+      .register(BupkisRegistry, { name: 'Object' }),
+  ),
+  createAssertion(
+    [['to be a record', 'to be a plain object']],
+    z.record(PropertyKeySchema, z.unknown()),
+  ),
+  createAssertion([z.array(z.any()), 'to be empty'], z.array(z.any()).max(0)),
+  createAssertion(
+    [z.record(z.any(), z.unknown()), 'to be empty'],
+    z
+      .record(z.any(), z.unknown())
+      .refine((obj) => Reflect.ownKeys(obj).length === 0),
+  ),
+  createAssertion(['to be an Error'], z.instanceof(Error)),
+
+  // String emptiness assertions
+  createAssertion([z.string(), 'to be empty'], z.string().max(0)),
+  createAssertion([z.string(), 'to be non-empty'], z.string().min(1)),
+
+  // General existence/value checks
+  createAssertion(['to be defined'], z.unknown().nonoptional()),
+
+  // Basic collection type assertions
+  createAssertion(['to be a Set'], StrongSetSchema),
+  createAssertion(['to be a WeakMap'], z.instanceof(WeakMap)),
+  createAssertion(['to be a WeakSet'], z.instanceof(WeakSet)),
+] as const;

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

@@ -0,0 +1,108 @@
+import { z } from 'zod/v4';
+
+import { isNullOrNonObject } from '../../guards.js';
+import { StrongMapSchema, StrongSetSchema } from '../../schema.js';
+import { createAssertion } from '../create.js';
+
+export const CollectionAssertions = [
+  // Map assertions (including WeakMap)
+  createAssertion(
+    [z.map(z.any(), z.any()), ['to contain', 'to include'], z.any()],
+    (subject, key) => subject.has(key),
+  ),
+  // Size-based assertions only for strong Maps (not WeakMaps)
+  createAssertion(
+    [StrongMapSchema, 'to have size', z.number()],
+    (subject, expectedSize) => subject.size === expectedSize,
+  ),
+  createAssertion(
+    [StrongMapSchema, 'to be empty'],
+    (subject) => subject.size === 0,
+  ),
+  // Set assertions (including WeakSet)
+  createAssertion(
+    [z.set(z.any()), ['to contain', 'to include'], z.any()],
+    (subject, value) => subject.has(value),
+  ),
+  // Size-based assertions only for strong Sets (not WeakSets)
+  createAssertion(
+    [StrongSetSchema, 'to have size', z.number()],
+    (subject, expectedSize) => subject.size === expectedSize,
+  ),
+  createAssertion(
+    [StrongSetSchema, 'to be empty'],
+    (subject) => subject.size === 0,
+  ),
+  // WeakMap specific assertions
+  createAssertion(
+    [z.instanceof(WeakMap), ['to contain', 'to include'], z.any()],
+    (subject, key) => {
+      // WeakMap.has only works with object keys
+      if (isNullOrNonObject(key)) {
+        return false;
+      }
+      return subject.has(key as WeakKey);
+    },
+  ),
+  // WeakSet specific assertions
+  createAssertion(
+    [z.instanceof(WeakSet), ['to contain', 'to include'], z.any()],
+    (subject, value) => {
+      // WeakSet.has only works with object values
+      if (isNullOrNonObject(value)) {
+        return false;
+      }
+      return subject.has(value as WeakKey);
+    },
+  ),
+  // Array assertions
+  createAssertion(
+    [z.array(z.any()), ['to contain', 'to include'], z.any()],
+    (subject, value) => subject.includes(value),
+  ),
+  createAssertion(
+    [z.array(z.any()), 'to have size', z.number()],
+    (subject, expectedSize) => subject.length === expectedSize,
+  ),
+  createAssertion(
+    [z.array(z.any()), 'to have length', z.number()],
+    (subject, expectedLength) => subject.length === expectedLength,
+  ),
+
+  // Array emptiness assertions
+  createAssertion([z.array(z.any()), 'to be non-empty'], (subject) => {
+    if (subject.length === 0) {
+      return {
+        actual: subject.length,
+        expected: 'non-empty array',
+        message: 'Expected array to be non-empty',
+      };
+    }
+  }),
+
+  // Object assertions
+  createAssertion(
+    [
+      z.looseObject({}),
+      ['to have keys', 'to have properties', 'to have props'],
+      z.tuple([z.string()], z.string()),
+    ],
+    (_, keys) =>
+      z.looseObject(
+        Object.fromEntries(keys.map((k) => [k, z.unknown().nonoptional()])),
+      ),
+  ),
+  createAssertion(
+    [z.looseObject({}), 'to have size', z.number().int().nonnegative()],
+    (subject, expectedSize) => {
+      const actual = Object.keys(subject).length;
+      if (actual !== expectedSize) {
+        return {
+          actual: actual,
+          expected: expectedSize,
+          message: `Expected object to have ${expectedSize} keys, but it has ${actual} keys`,
+        };
+      }
+    },
+  ),
+] as const;

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

@@ -0,0 +1,25 @@
+import { z } from 'zod/v4';
+
+import { NullProtoObjectSchema, PropertyKeySchema } from '../../schema.js';
+import { createAssertion } from '../create.js';
+
+export const EsotericAssertions = [
+  createAssertion(['to have a null prototype'], NullProtoObjectSchema),
+  createAssertion(
+    [PropertyKeySchema, 'to be an enumerable property of', z.looseObject({})],
+    (subject, obj) =>
+      !!Object.getOwnPropertyDescriptor(obj, subject)?.enumerable,
+  ),
+  createAssertion(
+    ['to be sealed'],
+    z.any().refine((obj) => Object.isSealed(obj)),
+  ),
+  createAssertion(
+    ['to be frozen'],
+    z.any().refine((obj) => Object.isFrozen(obj)),
+  ),
+  createAssertion(
+    ['to be extensible'],
+    z.any().refine((obj) => Object.isExtensible(obj)),
+  ),
+] as const;