bupkis 0.18.2 → 1.0.0

package/dist/guards.cjs

@@ -0,0 +1,291 @@
+"use strict";
+/**
+ * Type guard functions and runtime type checking utilities.
+ *
+ * This module provides various type guard functions for runtime type checking,
+ * including guards for Zod schemas, constructors, {@link PromiseLike} objects,
+ * and assertion parts. These are used throughout the library for safe type
+ * narrowing and validation.
+ *
+ * @module guards
+ * @category API
+ * @example
+ *
+ * ```ts
+ * import * as guards from 'bupkis/guards';
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isExpectItExecutor = exports.isError = exports.isA = exports.isPhrase = exports.isPhraseLiteralChoice = exports.isPhraseLiteral = exports.isWeakKey = exports.isNonNullObject = exports.isString = exports.isFunction = exports.isBoolean = exports.isConstructible = exports.isPromiseLike = exports.isObject = exports.isStandardSchema = void 0;
+exports.isZodType = isZodType;
+const constant_js_1 = require("./constant.cjs");
+const { isArray } = Array;
+function isZodType(value, type) {
+    const isValid = (0, exports.isObject)(value) &&
+        'def' in value &&
+        !!value.def &&
+        typeof value.def === 'object' &&
+        'type' in value.def;
+    if (!isValid) {
+        return false;
+    }
+    if (type === undefined) {
+        return true;
+    }
+    return value.def.type === type;
+}
+/**
+ * Returns `true` if the given value implements the Standard Schema v1
+ * interface.
+ *
+ * This guard checks for the presence of the `~standard` property with the
+ * required shape (version 1, vendor, validate function). It can detect any
+ * Standard Schema compliant library including Zod v4 (which implements the
+ * spec).
+ *
+ * @function
+ * @param value - Value to test
+ * @returns Whether the value is a Standard Schema v1 instance
+ * @see {@link https://standardschema.dev | Standard Schema Specification}
+ */
+const isStandardSchema = (value) => {
+    // Some Standard Schema compliant libraries (e.g. ArkType) implement schemas
+    // as callable objects (functions with properties), so we must accept both
+    // plain objects and functions here.
+    if (!(0, exports.isObject)(value) && !(0, exports.isFunction)(value)) {
+        return false;
+    }
+    const v = value;
+    const std = v['~standard'];
+    return ((0, exports.isObject)(std) &&
+        'version' in std &&
+        std.version === 1 &&
+        'vendor' in std &&
+        typeof std.vendor === 'string' &&
+        'validate' in std &&
+        typeof std.validate === 'function');
+};
+exports.isStandardSchema = isStandardSchema;
+/**
+ * Type guard for a plain object.
+ *
+ * @function
+ * @param value Value to test
+ * @returns `true` if the value is a plain object, `false` otherwise
+ */
+const isObject = (value) => typeof value === 'object' && value !== null && !isArray(value);
+exports.isObject = isObject;
+/**
+ * Checks if a value is "promise-like", meaning it is a "thenable" object.
+ *
+ * @function
+ * @param value - Value to test
+ * @returns `true` if the value is promise-like, `false` otherwise
+ */
+const isPromiseLike = (value) => (0, exports.isObject)(value) &&
+    'then' in value &&
+    (0, exports.isFunction)(value.then) &&
+    value.then.length > 0;
+exports.isPromiseLike = isPromiseLike;
+/**
+ * Returns `true` if the given value is a constructable function (i.e., a
+ * class).
+ *
+ * This works by wrapping `fn` in a {@link Proxy}, attaching a no-op
+ * {@link ProxyHandler.construct} trap to it, then attempting to construct the
+ * proxy via `new`.
+ *
+ * @privateRemarks
+ * This may be the only way we can determine, at runtime, if a function is a
+ * constructor without actually calling it. I am unsure if this only works for
+ * classes.
+ * @function
+ * @param fn - Function to test
+ * @returns Whether the function is constructable
+ */
+const isConstructible = (fn) => {
+    if (fn === Symbol || fn === BigInt) {
+        return false;
+    }
+    try {
+        // this will throw if there is no `[[construct]]` slot.. or so I've heard.
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-call, @bupkis/require-function-tag-in-arrow-functions
+        new new Proxy(fn, { construct: () => ({}) })();
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+exports.isConstructible = isConstructible;
+/**
+ * Type guard for a boolean value
+ *
+ * @function
+ * @param value Value to check
+ * @returns `true` if the value is a boolean, `false` otherwise
+ */
+const isBoolean = (value) => typeof value === 'boolean';
+exports.isBoolean = isBoolean;
+/**
+ * Type guard for a function value
+ *
+ * @function
+ * @param value Value to check
+ * @returns `true` if the value is a function, `false` otherwise
+ */
+const isFunction = (value) => typeof value === 'function';
+exports.isFunction = isFunction;
+/**
+ * Type guard for a string value
+ *
+ * @function
+ * @param value Value to check
+ * @returns `true` if the value is a string, `false` otherwise
+ */
+const isString = (value) => typeof value === 'string';
+exports.isString = isString;
+/**
+ * Type guard for a non-null object value
+ *
+ * @function
+ * @param value Value to check
+ * @returns `true` if the value is an object and not null, `false` otherwise
+ */
+const isNonNullObject = (value) => typeof value === 'object' && value !== null;
+exports.isNonNullObject = isNonNullObject;
+/**
+ * Type guard for a valid WeakKey (object, function, or symbol).
+ *
+ * WeakMaps and WeakSets can only use objects (including functions) or symbols
+ * as keys, not primitives like strings, numbers, booleans, null, or undefined.
+ *
+ * @function
+ * @param value Value to check
+ * @returns `true` if the value is a valid WeakKey (object, function, or
+ *   symbol), `false` otherwise
+ */
+const isWeakKey = (value) => (0, exports.isNonNullObject)(value) || (0, exports.isFunction)(value) || typeof value === 'symbol';
+exports.isWeakKey = isWeakKey;
+/**
+ * Type guard for a {@link PhraseLiteral}, which is just a string that does not
+ * begin with `not `.
+ *
+ * @function
+ * @param value Value to check
+ * @returns `true` if the value is a `PhraseLiteral`, `false` otherwise
+ * @internal
+ */
+const isPhraseLiteral = (value) => (0, exports.isString)(value) && value !== 'and';
+exports.isPhraseLiteral = isPhraseLiteral;
+/**
+ * Type guard for a {@link PhraseLiteralChoice}, which is a tuple of strings.
+ *
+ * @function
+ * @param value Value to check
+ * @returns `true` if the value is a `PhraseLiteralChoice`, `false` otherwise
+ * @internal
+ */
+const isPhraseLiteralChoice = (value) => isArray(value) &&
+    value.length >= 1 &&
+    value.every((item) => (0, exports.isPhraseLiteral)(item));
+exports.isPhraseLiteralChoice = isPhraseLiteralChoice;
+/**
+ * Type guard for a {@link PhraseLiteral} or {@link PhraseLiteralChoice}.
+ *
+ * @function
+ * @param value Value to check
+ * @returns `true` if the value is a `PhraseLiteral` or `PhraseLiteralChoice`,
+ *   `false` otherwise
+ */
+const isPhrase = (value) => (0, exports.isPhraseLiteral)(value) || (0, exports.isPhraseLiteralChoice)(value);
+exports.isPhrase = isPhrase;
+/**
+ * Generic type guard for instanceof checks.
+ *
+ * This function provides a type-safe way to check if a value is an instance of
+ * a given constructor, with proper type narrowing for TypeScript. It combines
+ * the null/object check with instanceof to ensure the value is a valid object
+ * before performing the instance check.
+ *
+ * @example
+ *
+ * ```typescript
+ * const obj = new Date();
+ * if (isA(obj, Date)) {
+ *   // obj is now typed as Date
+ *   console.log(obj.getTime());
+ * }
+ * ```
+ *
+ * @template T - The constructor type to check against
+ * @function
+ * @param value - Value to test
+ * @param ctor - Constructor function to check instanceof
+ * @returns `true` if the value is an instance of the constructor, `false`
+ *   otherwise
+ */
+const isA = (value, ctor) => (0, exports.isNonNullObject)(value) && value instanceof ctor;
+exports.isA = isA;
+/**
+ * Type guard for Error instances.
+ *
+ * This function checks if a value is an instance of the Error class or any of
+ * its subclasses. It's useful for error handling and type narrowing when
+ * working with unknown values that might be errors.
+ *
+ * Uses `Error.isError` if available.
+ *
+ * @example
+ *
+ * ```typescript
+ * try {
+ *   throw new TypeError('Something went wrong');
+ * } catch (err) {
+ *   if (isError(err)) {
+ *     // err is now typed as Error
+ *     console.log(err.message);
+ *   }
+ * }
+ * ```
+ *
+ * @function
+ * @param value - Value to test
+ * @returns `true` if the value is an Error instance, `false` otherwise
+ */
+exports.isError = 'isError' in Error && (0, exports.isFunction)(Error.isError)
+    ? // @ts-expect-error - Error.isError is new
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-call
+        (value) => Error.isError(value)
+    : (value) => (0, exports.isA)(value, Error);
+/**
+ * Type guard for {@link ExpectItExecutor} functions.
+ *
+ * This function checks if a value is an {@link ExpectItExecutor} function
+ * created by {@link bupkis!expect.it | expect.it()}. {@link ExpectItExecutor}
+ * functions are special functions that contain assertion logic and are marked
+ * with an internal symbol for identification. They are used in nested
+ * assertions within "to satisfy" patterns and other complex assertion
+ * scenarios.
+ *
+ * @example
+ *
+ * ```typescript
+ * const executor = expect.it('to be a string');
+ * if (isExpectItExecutor(executor)) {
+ *   // executor is now typed as ExpectItExecutor
+ *   // Can be used in satisfaction patterns
+ * }
+ * ```
+ *
+ * @template Subject - The subject type that the executor function operates on
+ * @function
+ * @param value - Value to test
+ * @returns `true` if the value is an ExpectItExecutor function, `false`
+ *   otherwise
+ */
+const isExpectItExecutor = (value) => (0, exports.isFunction)(value) &&
+    constant_js_1.kExpectIt in value &&
+    value[constant_js_1.kExpectIt] === true;
+exports.isExpectItExecutor = isExpectItExecutor;
+//# sourceMappingURL=guards.js.map

package/dist/guards.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.js","sourceRoot":"","sources":["../src/guards.ts"],"names":[],"mappings":"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"}

package/dist/guards.d.cts

@@ -0,0 +1,225 @@
+/**
+ * Type guard functions and runtime type checking utilities.
+ *
+ * This module provides various type guard functions for runtime type checking,
+ * including guards for Zod schemas, constructors, {@link PromiseLike} objects,
+ * and assertion parts. These are used throughout the library for safe type
+ * narrowing and validation.
+ *
+ * @module guards
+ * @category API
+ * @example
+ *
+ * ```ts
+ * import * as guards from 'bupkis/guards';
+ * ```
+ */
+import { type z } from 'zod';
+import type { PhraseLiteralChoice } from "./assertion/assertion-types.cjs";
+import type { StandardSchemaV1 } from "./standard-schema.cjs";
+import type { Constructor, ExpectItExecutor, PhraseLiteral, ZodTypeMap } from "./types.cjs";
+/**
+ * Returns `true` if the given value looks like a Zod v4 schema, determined by
+ * the presence of an internal {@link z.core.$ZodTypeDef} field.
+ *
+ * Note: This relies on Zod's internal shape and is intended for runtime
+ * discrimination within this library.
+ *
+ * @template T - The specific ZodType to check for (based on def.type)
+ * @param value - Value to test
+ * @returns Whether the value is `ZodType`-like
+ */
+export declare function isZodType<T extends keyof ZodTypeMap>(value: unknown, type: T): value is ZodTypeMap[T];
+/**
+ * Returns `true` if the given value looks like a Zod v4 schema, determined by
+ * the presence of an internal {@link z.core.$ZodTypeDef} field.
+ *
+ * Note: This relies on Zod's internal shape and is intended for runtime
+ * discrimination within this library.
+ *
+ * @param value - Value to test
+ * @returns Whether the value is `ZodType`-like
+ */
+export declare function isZodType(value: unknown): value is z.ZodType;
+/**
+ * Returns `true` if the given value implements the Standard Schema v1
+ * interface.
+ *
+ * This guard checks for the presence of the `~standard` property with the
+ * required shape (version 1, vendor, validate function). It can detect any
+ * Standard Schema compliant library including Zod v4 (which implements the
+ * spec).
+ *
+ * @function
+ * @param value - Value to test
+ * @returns Whether the value is a Standard Schema v1 instance
+ * @see {@link https://standardschema.dev | Standard Schema Specification}
+ */
+export declare const isStandardSchema: (value: unknown) => value is StandardSchemaV1;
+/**
+ * Type guard for a plain object.
+ *
+ * @function
+ * @param value Value to test
+ * @returns `true` if the value is a plain object, `false` otherwise
+ */
+export declare const isObject: (value: unknown) => value is NonNullable<object>;
+/**
+ * Checks if a value is "promise-like", meaning it is a "thenable" object.
+ *
+ * @function
+ * @param value - Value to test
+ * @returns `true` if the value is promise-like, `false` otherwise
+ */
+export declare const isPromiseLike: (value: unknown) => value is PromiseLike<unknown>;
+/**
+ * Returns `true` if the given value is a constructable function (i.e., a
+ * class).
+ *
+ * This works by wrapping `fn` in a {@link Proxy}, attaching a no-op
+ * {@link ProxyHandler.construct} trap to it, then attempting to construct the
+ * proxy via `new`.
+ *
+ * @privateRemarks
+ * This may be the only way we can determine, at runtime, if a function is a
+ * constructor without actually calling it. I am unsure if this only works for
+ * classes.
+ * @function
+ * @param fn - Function to test
+ * @returns Whether the function is constructable
+ */
+export declare const isConstructible: (fn: unknown) => fn is Constructor;
+/**
+ * Type guard for a boolean value
+ *
+ * @function
+ * @param value Value to check
+ * @returns `true` if the value is a boolean, `false` otherwise
+ */
+export declare const isBoolean: (value: unknown) => value is boolean;
+/**
+ * Type guard for a function value
+ *
+ * @function
+ * @param value Value to check
+ * @returns `true` if the value is a function, `false` otherwise
+ */
+export declare const isFunction: (value: unknown) => value is (...args: any[]) => any;
+/**
+ * Type guard for a string value
+ *
+ * @function
+ * @param value Value to check
+ * @returns `true` if the value is a string, `false` otherwise
+ */
+export declare const isString: (value: unknown) => value is string;
+/**
+ * Type guard for a non-null object value
+ *
+ * @function
+ * @param value Value to check
+ * @returns `true` if the value is an object and not null, `false` otherwise
+ */
+export declare const isNonNullObject: (value: unknown) => value is object;
+/**
+ * Type guard for a valid WeakKey (object, function, or symbol).
+ *
+ * WeakMaps and WeakSets can only use objects (including functions) or symbols
+ * as keys, not primitives like strings, numbers, booleans, null, or undefined.
+ *
+ * @function
+ * @param value Value to check
+ * @returns `true` if the value is a valid WeakKey (object, function, or
+ *   symbol), `false` otherwise
+ */
+export declare const isWeakKey: (value: unknown) => value is WeakKey;
+/**
+ * Type guard for a {@link PhraseLiteral} or {@link PhraseLiteralChoice}.
+ *
+ * @function
+ * @param value Value to check
+ * @returns `true` if the value is a `PhraseLiteral` or `PhraseLiteralChoice`,
+ *   `false` otherwise
+ */
+export declare const isPhrase: (value: unknown) => value is PhraseLiteral | PhraseLiteralChoice;
+/**
+ * Generic type guard for instanceof checks.
+ *
+ * This function provides a type-safe way to check if a value is an instance of
+ * a given constructor, with proper type narrowing for TypeScript. It combines
+ * the null/object check with instanceof to ensure the value is a valid object
+ * before performing the instance check.
+ *
+ * @example
+ *
+ * ```typescript
+ * const obj = new Date();
+ * if (isA(obj, Date)) {
+ *   // obj is now typed as Date
+ *   console.log(obj.getTime());
+ * }
+ * ```
+ *
+ * @template T - The constructor type to check against
+ * @function
+ * @param value - Value to test
+ * @param ctor - Constructor function to check instanceof
+ * @returns `true` if the value is an instance of the constructor, `false`
+ *   otherwise
+ */
+export declare const isA: <T extends Constructor>(value: unknown, ctor: T) => value is InstanceType<T>;
+/**
+ * Type guard for Error instances.
+ *
+ * This function checks if a value is an instance of the Error class or any of
+ * its subclasses. It's useful for error handling and type narrowing when
+ * working with unknown values that might be errors.
+ *
+ * Uses `Error.isError` if available.
+ *
+ * @example
+ *
+ * ```typescript
+ * try {
+ *   throw new TypeError('Something went wrong');
+ * } catch (err) {
+ *   if (isError(err)) {
+ *     // err is now typed as Error
+ *     console.log(err.message);
+ *   }
+ * }
+ * ```
+ *
+ * @function
+ * @param value - Value to test
+ * @returns `true` if the value is an Error instance, `false` otherwise
+ */
+export declare const isError: (value: unknown) => value is Error;
+/**
+ * Type guard for {@link ExpectItExecutor} functions.
+ *
+ * This function checks if a value is an {@link ExpectItExecutor} function
+ * created by {@link bupkis!expect.it | expect.it()}. {@link ExpectItExecutor}
+ * functions are special functions that contain assertion logic and are marked
+ * with an internal symbol for identification. They are used in nested
+ * assertions within "to satisfy" patterns and other complex assertion
+ * scenarios.
+ *
+ * @example
+ *
+ * ```typescript
+ * const executor = expect.it('to be a string');
+ * if (isExpectItExecutor(executor)) {
+ *   // executor is now typed as ExpectItExecutor
+ *   // Can be used in satisfaction patterns
+ * }
+ * ```
+ *
+ * @template Subject - The subject type that the executor function operates on
+ * @function
+ * @param value - Value to test
+ * @returns `true` if the value is an ExpectItExecutor function, `false`
+ *   otherwise
+ */
+export declare const isExpectItExecutor: <Subject extends z.ZodType = z.ZodUnknown>(value: unknown) => value is ExpectItExecutor<Subject>;
+//# sourceMappingURL=guards.d.ts.map

package/dist/guards.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../src/guards.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,OAAO,KAAK,EAAE,mBAAmB,EAAE,wCAAuC;AAC1E,OAAO,KAAK,EAAE,gBAAgB,EAAE,8BAA6B;AAC7D,OAAO,KAAK,EACV,WAAW,EACX,gBAAgB,EAChB,aAAa,EACb,UAAU,EACX,oBAAmB;AAMpB;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,UAAU,EAClD,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,CAAC,GACN,KAAK,IAAI,UAAU,CAAC,CAAC,CAAC,CAAC;AAC1B;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,CAAC,CAAC,OAAO,CAAC;AAsB9D;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,gBAAgB,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,gBAkB1D,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,WAAW,CAAC,MAAM,CACL,CAAC;AAEjE;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,WAAW,CAAC,OAAO,CAIpD,CAAC;AAExB;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,eAAe,GAAI,IAAI,OAAO,KAAG,EAAE,IAAI,WAYnD,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,OACxB,CAAC;AAE7B;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAC5C,CAAC;AAE9B;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,MACxB,CAAC;AAE5B;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,MACb,CAAC;AAE9C;;;;;;;;;;GAUG;AACH,eAAO,MAAM,SAAS,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,OACsB,CAAC;AA6B3E;;;;;;;GAOG;AACH,eAAO,MAAM,QAAQ,GACnB,OAAO,OAAO,KACb,KAAK,IAAI,aAAa,GAAG,mBAC4B,CAAC;AAEzD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,GAAG,GAAI,CAAC,SAAS,WAAW,EACvC,OAAO,OAAO,EACd,MAAM,CAAC,KACN,KAAK,IAAI,YAAY,CAAC,CAAC,CAAoD,CAAC;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,OAAO,UAIN,OAAO,KAAG,KAAK,IAAI,KAC0B,CAAC;AAE5D;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,kBAAkB,GAAI,OAAO,SAAS,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,UAAU,EACzE,OAAO,OAAO,KACb,KAAK,IAAI,gBAAgB,CAAC,OAAO,CAG+B,CAAC"}