bupkis 0.1.2 → 0.3.0

package/src/schema.ts

@@ -1,14 +1,34 @@
 /**
- * Zod schema definitions for common types and validation patterns.
+ * Arguably-useful Zod schemas for common types and validation patterns.
  *
  * 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 Zod's
- * limitations.
+ * 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.
  *
- * @document schema.md
+ * For example, we have {@link FunctionSchema} which accepts any
+ * function—regardless of its signature. We need this because Zod v4's
+ * `z.function()` no longer returns a `ZodType` (ref:
+ * {@link https://zod.dev/v4/changelog | Zod v4 Migration Guide}) and so behaves
+ * differently. `FunctionSchema` allows us to work with functions as _values_
+ * instead of something to be implemented.
+ *
+ * Similarly—but not a new development—`z.promise()` does not parse a
+ * {@link Promise} object; it parses the _fulfilled value_. This is not what we
+ * want for "is a Promise" assertions, but it _can_ be useful for making sense
+ * of the fulfilled value. To solve this, we have
+ * {@link WrappedPromiseLikeSchema} (which explicitly supports
+ * {@link PromiseLike}/"thenable" objects).
+ *
+ * @category API
+ * @example
+ *
+ * ```ts
+ * import * as schema from 'bupkis/schema';
+ * ```
+ *
  * @packageDocumentation
  */
 
@@ -16,26 +36,25 @@ import { z } from 'zod/v4';
 
 import {
   isA,
-  isConstructable,
+  isConstructible,
   isFunction,
   isNonNullObject,
   isPromiseLike,
 } from './guards.js';
 import { BupkisRegistry } from './metadata.js';
-import { type Constructor } from './types.js';
+import { type Constructor, type MutableOrReadonly } from './types.js';
 
 /**
  * A Zod schema that validates JavaScript classes or constructor 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.
  *
- * @remarks
+ * @privateRemarks
  * The schema is registered in the {@link BupkisRegistry} with the name
  * `ClassSchema` for later reference and type checking purposes.
- * @category Schema
  * @example
  *
  * ```typescript
@@ -49,10 +68,12 @@ import { type Constructor } from './types.js';
  * ClassSchema.parse(() => {}); // ✗ Throws validation error
  * ClassSchema.parse({}); // ✗ Throws validation error
  * ```
+ *
+ * @group Schema
  */
 
 export const ClassSchema = z
-  .custom<Constructor>(isConstructable)
+  .custom<Constructor>(isConstructible)
   .register(BupkisRegistry, { name: 'ClassSchema' })
   .describe('Class / Constructor');
 
@@ -65,10 +86,9 @@ export const ClassSchema = z
  * including regular functions, arrow functions, async functions, generator
  * functions, and methods.
  *
- * @remarks
+ * @privateRemarks
  * The schema is registered in the {@link BupkisRegistry} with the name
  * `FunctionSchema` for later reference and type checking purposes.
- * @category Schema
  * @example
  *
  * ```typescript
@@ -80,9 +100,11 @@ export const ClassSchema = z
  * FunctionSchema.parse('not a function'); // ✗ Throws validation error
  * FunctionSchema.parse({}); // ✗ Throws validation error
  * ```
+ *
+ * @group Schema
  */
 export const FunctionSchema = z
-  .custom<(...args: any[]) => any>(isFunction)
+  .custom<(...args: MutableOrReadonly<unknown[]>) => unknown>(isFunction)
   .register(BupkisRegistry, {
     name: 'FunctionSchema',
   })
@@ -98,10 +120,9 @@ export const FunctionSchema = z
  * types that JavaScript automatically converts to property keys when used in
  * object access or assignment operations.
  *
- * @remarks
+ * @privateRemarks
  * The schema is registered in the `BupkisRegistry` with the name
  * `PropertyKeySchema` for later reference and type checking purposes.
- * @category Schema
  * @example
  *
  * ```typescript
@@ -111,6 +132,8 @@ export const FunctionSchema = z
  * PropertyKeySchema.parse({}); // ✗ Throws validation error
  * PropertyKeySchema.parse(null); // ✗ Throws validation error
  * ```
+ *
+ * @group Schema
  */
 export const PropertyKeySchema = z
   .union([z.string(), z.number(), z.symbol()])
@@ -126,12 +149,11 @@ export const PropertyKeySchema = z
  * resolved value, meaning the result of parsing remains a Promise or thenable
  * object.
  *
- * @remarks
+ * @privateRemarks
  * The schema is registered in the `BupkisRegistry` with the name
  * `WrappedPromiseLikeSchema` for later reference and type checking purposes.
  * This is useful when you need to validate that something is thenable without
  * automatically resolving it.
- * @category Schema
  * @example
  *
  * ```typescript
@@ -140,6 +162,8 @@ export const PropertyKeySchema = z
  * WrappedPromiseLikeSchema.parse(42); // ✗ Throws validation error
  * WrappedPromiseLikeSchema.parse({}); // ✗ Throws validation error
  * ```
+ *
+ * @group Schema
  */
 export const WrappedPromiseLikeSchema = z
   .custom<PromiseLike<unknown>>((value) => isPromiseLike(value))
@@ -159,7 +183,6 @@ export const WrappedPromiseLikeSchema = z
  * @remarks
  * The schema is registered in the `BupkisRegistry` with the name
  * `StrongMapSchema` for later reference and type checking purposes.
- * @category Schema
  * @example
  *
  * ```typescript
@@ -172,6 +195,8 @@ export const WrappedPromiseLikeSchema = z
  * const weakMap = new WeakMap();
  * StrongMapSchema.parse(weakMap); // ✗ Throws validation error
  * ```
+ *
+ * @group Schema
  */
 export const StrongMapSchema = z
   .instanceof(Map)
@@ -190,7 +215,6 @@ export const StrongMapSchema = z
  * @remarks
  * The schema is registered in the `BupkisRegistry` with the name
  * `StrongSetSchema` for later reference and type checking purposes.
- * @category Schema
  * @example
  *
  * ```typescript
@@ -200,6 +224,8 @@ export const StrongMapSchema = z
  * const weakSet = new WeakSet();
  * StrongSetSchema.parse(weakSet); // ✗ Throws validation error
  * ```
+ *
+ * @group Schema
  */
 export const StrongSetSchema = z
   .instanceof(Set)
@@ -216,10 +242,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.
- * @category Schema
+ *
+ * Changing this to be a `ZodRecord` would be nice, but that would end up
+ * blasting away the original object's prototype.
  * @example
  *
  * ```typescript
@@ -233,14 +261,24 @@ export const StrongSetSchema = z
  * const emptyObj = {};
  * NullProtoObjectSchema.parse(emptyObj); // ✗ Throws validation error
  * ```
+ *
+ * @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.
  *
@@ -249,13 +287,12 @@ 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
  * declared with `async`, as this determination requires static analysis that is
  * not available at runtime.
- * @category Schema
  * @example
  *
  * ```typescript
@@ -275,6 +312,8 @@ export const NullProtoObjectSchema = z
  * const regularFn = () => 42;
  * AsyncFunctionSchema.parse(regularFn); // ✗ Throws validation error
  * ```
+ *
+ * @group Schema
  */
 export const AsyncFunctionSchema = FunctionSchema.refine(
   (value) => Object.prototype.toString.call(value) === '[object AsyncFunction]',
@@ -290,10 +329,9 @@ 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.
- * @category Schema
  * @example
  *
  * ```typescript
@@ -307,6 +345,8 @@ export const AsyncFunctionSchema = FunctionSchema.refine(
  * TruthySchema.parse(''); // ✗ Throws validation error
  * TruthySchema.parse(null); // ✗ Throws validation error
  * ```
+ *
+ * @group Schema
  */
 export const TruthySchema = z
   .any()
@@ -325,10 +365,9 @@ 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.
- * @category Schema
  * @example
  *
  * ```typescript
@@ -345,6 +384,8 @@ export const TruthySchema = z
  * FalsySchema.parse('hello'); // ✗ Throws validation error
  * FalsySchema.parse({}); // ✗ Throws validation error
  * ```
+ *
+ * @group Schema
  */
 export const FalsySchema = z
   .any()
@@ -362,10 +403,9 @@ 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.
- * @category Schema
  * @example
  *
  * ```typescript
@@ -380,6 +420,8 @@ export const FalsySchema = z
  * PrimitiveSchema.parse([]); // ✗ Throws validation error (array)
  * PrimitiveSchema.parse(() => {}); // ✗ Throws validation error (function)
  * ```
+ *
+ * @group Schema
  */
 export const PrimitiveSchema = z
   .union([
@@ -404,12 +446,11 @@ export const PrimitiveSchema = z
  * it useful for validating collections where the specific array mutability or
  * tuple structure is not critical.
  *
- * @remarks
+ * @privateRemarks
  * The schema is registered in the {@link BupkisRegistry} with the name
  * `ArrayLike` for later reference and type checking purposes. This schema is
  * particularly useful when you need to accept various forms of array-like data
  * without being restrictive about mutability or exact tuple structure.
- * @category Schema
  * @example
  *
  * ```typescript
@@ -421,11 +462,13 @@ export const PrimitiveSchema = z
  * ArrayLikeSchema.parse({}); // ✗ Throws validation error
  * ArrayLikeSchema.parse(null); // ✗ Throws validation error
  * ```
+ *
+ * @group Schema
  */
 export const ArrayLikeSchema = z
   .union([
-    z.array(z.any()),
-    z.tuple([z.any()], z.any()),
+    z.array(z.unknown()),
+    z.tuple([z.unknown()], z.unknown()),
     z.looseObject({ length: z.number().nonnegative().int() }),
   ])
   .describe('Array-like value')
@@ -442,10 +485,9 @@ 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.
- * @category Schema
  * @example
  *
  * ```typescript
@@ -457,6 +499,8 @@ export const ArrayLikeSchema = z
  * RegExpSchema.parse(/abc/.source); // ✗ Throws validation error (string pattern)
  * RegExpSchema.parse({}); // ✗ Throws validation error (object)
  * ```
+ *
+ * @group Schema
  */
 export const RegExpSchema = z
   .instanceof(RegExp)