@spudlabs/guardis 0.4.0

package/esm/src/types.d.ts

@@ -0,0 +1,318 @@
+import type { StandardSchemaV1 } from "../specs/standard-schema-spec.v1.js";
+import type { includes, tupleHas } from "./utilities.js";
+/**
+ * Context for tracking validation paths and collecting issues during validation.
+ * Only present during `validate()` calls, not during regular type guard checks.
+ */
+export interface Context {
+    /** The current path being validated (array of property keys and indices) */
+    readonly path: ReadonlyArray<PropertyKey>;
+    /** The collected validation issues */
+    readonly issues: StandardSchemaV1.Issue[];
+    /** Creates a new context with the segment added to the path */
+    pushPath(segment: PropertyKey): Context;
+    /** Adds an issue at the current path */
+    addIssue(message: string): void;
+}
+type Helpers = {
+    /** Check for required property with optional custom error message */
+    has: <K extends PropertyKey, G = unknown>(t: object, k: K, guard?: (v: unknown) => v is G, errorMessage?: string) => t is {
+        [K2 in K]: G;
+    };
+    /** Check that a property does not exist with optional custom error message */
+    hasNot: <K extends PropertyKey>(t: object, k: K, errorMessage?: string) => t is {
+        [K2 in K]: never;
+    };
+    /** Check for optional property with optional custom error message */
+    hasOptional: <K extends PropertyKey, G = unknown>(t: object, k: K, guard?: (v: unknown) => v is G, errorMessage?: string) => t is {
+        [K2 in K]+?: G;
+    };
+    tupleHas: typeof tupleHas;
+    includes: typeof includes;
+    /** Check if a key exists in an object with optional custom error message */
+    keyOf: <T extends object>(k: unknown, t: T, errorMessage?: string) => k is keyof T;
+    /** Returns null and adds custom error message to context if during validation */
+    fail: (message: string) => null;
+};
+/** Helpers extended with internal context access for validation */
+export type HelpersWithContext = Helpers & {
+    _ctx?: Context;
+};
+/** A parser is a function that takes an unknown and returns T or null */
+export type Parser<T = unknown> = (val: unknown, helper: Helpers) => T | null;
+export type ExtendedParser<T1, T2 extends T1 = T1> = (val: T1, helper: Helpers) => T2 | null;
+export type Predicate<T> = (val: unknown) => val is T;
+export type StrictTypeGuard<T> = (value: unknown, errorMsg?: string) => value is T;
+/**
+ * Represents a type guard function with additional utility methods.
+ *
+ * A TypeGuard is a function that determines if a value is of type T, providing
+ * type narrowing in TypeScript. This type extends the basic type guard with:
+ * - strict mode validation
+ * - assertion functions that throw errors for invalid values
+ * - utilities for handling non-empty and optional values
+ *
+ * @template T1 The type being guarded
+ */
+export interface TypeGuard<T1> extends StandardSchemaV1<T1> {
+    /**
+     * A utility to gain access to the type being guarded. Can be used
+     * to infer the type in other parts of the code.
+     *
+     * @example
+     * ```typescript
+     * type GuardedType = typeof isString._TYPE; // string
+     * ```
+     */
+    _TYPE: T1;
+    /**
+     * A type guard function that checks if the value is of type T.
+     * @param value The value to check
+     * @returns true if the value is of type T, otherwise false
+     */
+    (value: unknown): value is T1;
+    /**
+     * A type guard function that checks if the value is of type T or T2.
+     * This is useful for creating unions of types.
+     * @param guard A type guard for T2
+     * @returns A new type guard that checks if the value is of type T or T2
+     */
+    or: <T2>(guard: Predicate<T2>) => TypeGuard<T1 | T2>;
+    /**
+     * A strict type guard that throws an error if the value is not of type T.
+     * @param value The value to check
+     * @param errorMsg Optional error message to include in the thrown error
+     * @returns true if the value is of type T, otherwise throws an error
+     */
+    strict: StrictTypeGuard<T1>;
+    /**
+     * An assertion function that throws an error if the value is not of type T.
+     * This is useful for ensuring that a value meets the type requirements at runtime.
+     *
+     * Unfortunately, TypeScript does not support the inference of assertion functions
+     * so the function must be invoked by declaring an intermediate variable and specifying
+     * the type.
+     *
+     * Example:
+     * ```typescript
+     * const value: unknown = someValue();
+     *
+     * const assertIsString: typeof isString.assert = isString.assert;
+     * assertIsString(value, "Expected a string");
+     * // After this line, TypeScript knows that value is a string
+     * ```
+     * @param value The value to check
+     * @param errorMsg Optional error message to include in the thrown error
+     * @returns Asserts that the value is of type T
+     */
+    assert: (value: unknown, errorMsg?: string) => asserts value is T1;
+    /**
+     * Validates the value against the schema. If the value is of type T1,
+     * it returns a success result with the value, otherwise it returns a failure result with issues.
+     *
+     * Included as a shortcut to the `validate` method of the StandardSchemaV1 interface.
+     * @param value The value to validate
+     * @returns
+     */
+    validate: (value: unknown) => StandardSchemaV1.Result<T1>;
+    /**
+     * Extends the current type guard with an additional parser, building upon
+     * the existing type guard. The new type guard will first check if the value
+     * passes the original type guard, and if it does, it will then apply the
+     * additional parser.
+     * @param {Function} parse An additional parser to further validate the type.
+     * @returns {Function} A new type guard that combines the original and additional parsers.
+     */
+    extend: IsExtensible<T1> extends false ? never : T1 extends Record<string, unknown> ? {
+        <S extends TypeGuardShape>(shape: S): TypeGuard<T1 & InferShape<S>>;
+        <S extends TypeGuardShape>(name: string, shape: S): TypeGuard<T1 & InferShape<S>>;
+        <T2 extends T1>(parse: ExtendedParser<T1, T2>): TypeGuard<T2>;
+        <T2 extends T1>(name: string, parse: ExtendedParser<T1, T2>): TypeGuard<T2>;
+    } : {
+        <T2 extends T1>(parse: ExtendedParser<T1, T2>): TypeGuard<T2>;
+        <T2 extends T1>(name: string, parse: ExtendedParser<T1, T2>): TypeGuard<T2>;
+    };
+    optional: {
+        /**
+         * A type guard that checks if the value is either undefined or of type T.
+         * @param value The value to check
+         * @returns true if the value is of type T or undefined, otherwise false
+         */
+        (value: unknown): value is T1 | undefined;
+        /**
+         * A strict type guard that throws an error if the value is defined but not of type T.
+         * @param value The value to check
+         * @param errorMsg Optional error message to include in the thrown error
+         * @returns true if the value is of type T, otherwise throws an error
+         */
+        strict: (value: unknown, errorMsg?: string) => value is T1 | undefined;
+        /**
+         * An assertion function that throws an error if the value is defined but not of type T.
+         * This is useful for ensuring that a value meets the type requirements at runtime.
+         *
+         * Unfortunately, TypeScript does not support the inference of assertion functions
+         * so the function must be invoked by declaring an intermediate variable and specifying
+         * the type.
+         *
+         * Example:
+         * ```typescript
+         * const value: unknown = someValue();
+         *
+         * const assertIsOptionalString: typeof isString.optional.assert = isString.optional.assert;
+         * assertIsOptionalString(value, "Expected a string or undefined");
+         * // After this line, TypeScript knows that value is a string
+         * ```
+         * @param value The value to check
+         * @param errorMsg Optional error message to include in the thrown error
+         * @returns Asserts that the value is of type T
+         */
+        assert: (value: unknown, errorMsg?: string) => asserts value is T1 | undefined;
+        /**
+         * Validates the value against the schema, accepting undefined as valid.
+         * @param value The value to validate
+         * @returns A success result with the value (including undefined), or a failure result with issues.
+         */
+        validate: (value: unknown) => StandardSchemaV1.Result<T1 | undefined>;
+        /**
+         * A type guard function that checks if the value is of type T1 | undefined | T2.
+         * This is useful for creating unions of types.
+         * @param guard A type guard for T2
+         * @returns A new type guard that checks if the value is of type T1 | undefined | T2
+         */
+        or: <T2>(guard: Predicate<T2>) => TypeGuard<T1 | undefined | T2>;
+        /**
+         * A type guard that checks if the value is not empty and of type T | undefined.
+         * An empty value is defined as null, an empty string, an empty array,
+         * or an empty object.
+         * @param value The value to check
+         * @returns true if the value is of type T and not empty, otherwise false
+         *
+         * @note This method is equivalent to calling `isString.notEmpty.optional`
+         * on a type guard named `isString`.
+         */
+        notEmpty: CanBeEmpty<T1> extends false ? never : TypeGuard<T1 | undefined>["notEmpty"];
+    };
+    notEmpty: CanBeEmpty<T1> extends false ? never : {
+        /**
+         * A type guard that checks if the value is not empty and of type T.
+         * An empty value is defined as null, undefined, an empty string, an empty array,
+         * or an empty object.
+         * @param value The value to check
+         * @returns true if the value is of type T and not empty, otherwise false
+         */
+        (value: unknown): value is T1;
+        /**
+         * A strict type guard that throws an error if the value is not of type T
+         * or if the value is empty (null, undefined, empty string, empty array, or empty object).
+         * @param value The value to check
+         * @param errorMsg Optional error message to include in the thrown error
+         * @returns true if the value is of type T, otherwise throws an error
+         */
+        strict: StrictTypeGuard<T1>;
+        /**
+         * An assertion function that throws an error if the value is not of type T or if it is
+         * empty. An empty value is defined as null, undefined, an empty string,
+         * an empty array, or an empty object. This is useful for ensuring that a value meets
+         * the type requirements at runtime.
+         *
+         * Unfortunately, TypeScript does not support the inference of assertion functions
+         * so the function must be invoked by declaring an intermediate variable and specifying
+         * the type.
+         *
+         * Example:
+         * ```typescript
+         * const value: unknown = someValue();
+         *
+         * const assertIsNotEmptyString: typeof isString.notEmpty.assert = isString.notEmpty.assert;
+         * assertIsNotEmptyString(value, "Expected a non-empty string");
+         * // After this line, TypeScript knows that value is a string
+         * ```
+         * @param value The value to check
+         * @param errorMsg Optional error message to include in the thrown error
+         * @returns Asserts that the value is of type T
+         */
+        assert: (value: unknown, errorMsg?: string) => asserts value is T1;
+        /**
+         * Validates the value against the schema, ensuring it is not empty. If the value is of
+         * type T1 and not empty, it returns a success result with the value, otherwise it
+         * returns a failure result with issues.
+         *
+         * Included as a shortcut to the `validate` method of the StandardSchemaV1 interface.
+         * @param value The value to validate
+         * @returns
+         */
+        validate: (value: unknown) => StandardSchemaV1.Result<T1>;
+        /**
+         * A type guard function that checks if the value is of type T1 or T2.
+         * This is useful for creating unions of types.
+         * @param guard A type guard for T2
+         * @returns A new type guard that checks if the value is of type T1 or T2
+         */
+        or: <T2>(guard: Predicate<T2>) => TypeGuard<T1 | T2>;
+        /**
+         * A type guard that checks if the value is not empty and of type T | undefined.
+         * An empty value is defined as null, an empty string, an empty array,
+         * or an empty object.
+         * @param value The value to check
+         * @returns true if the value is of type T and not empty, otherwise false
+         *
+         * @note This method is equivalent to calling `isString.optional.notEmpty`
+         * on a type guard named `isString`.
+         */
+        optional: TypeGuard<T1 | undefined>["optional"];
+    };
+}
+/** Helper type to extract the guarded type from a TypeGuard */
+export type GuardedType<G> = G extends TypeGuard<infer T> ? T : never;
+/** A named parser entry with an explicit name for error messages. */
+export type NamedParser = {
+    parse: Parser;
+    name: string;
+};
+/** A single entry in a ParserRecords config: a parser function, a named parser, or a shape. */
+export type ParserEntry = Parser | NamedParser | TypeGuardShape;
+/** A record describing various types and their parsers or shapes. This can be used to generate
+ * a customized Is dictionary. */
+export type ParserRecords = Record<string, ParserEntry>;
+/** Infers the guarded type from a ParserEntry (parser function, named parser, or shape). */
+export type InferEntry<P> = P extends Parser<infer T> ? T : P extends NamedParser ? (P["parse"] extends Parser<infer T> ? T : never) : P extends TypeGuardShape ? InferShape<P> : never;
+/** Any valid primitive json value. */
+export type JsonPrimitive = string | number | boolean | null;
+/** An array of JSON-able values. */
+export type JsonArray = JsonValue[] | readonly JsonValue[];
+/** An object containing only JSON-able values. */
+export type JsonObject = {
+    [Key in string]: JsonValue;
+} & {
+    [Key in string]?: JsonValue | undefined;
+};
+/** The complete set of JSON-able data types. */
+export type JsonValue = JsonPrimitive | JsonObject | JsonArray;
+/** Construct a tuple of unknowns, up to size 10. */
+export type TupleOfLength<N extends number> = N extends 0 ? [] : N extends 1 ? [unknown] : N extends 2 ? [unknown, unknown] : N extends 3 ? [unknown, unknown, unknown] : N extends 4 ? [unknown, unknown, unknown, unknown] : N extends 5 ? [unknown, unknown, unknown, unknown, unknown] : N extends 6 ? [unknown, unknown, unknown, unknown, unknown, unknown] : N extends 7 ? [unknown, unknown, unknown, unknown, unknown, unknown, unknown] : N extends 8 ? [unknown, unknown, unknown, unknown, unknown, unknown, unknown, unknown] : N extends 9 ? [unknown, unknown, unknown, unknown, unknown, unknown, unknown, unknown, unknown] : unknown[];
+/** Replace the type at position X in tuple T with type R */
+export type ReplaceTupleIndex<T extends readonly unknown[], X extends number, R> = {
+    readonly [K in keyof T]: K extends `${X}` ? R : T[K];
+};
+/** Utility type to determine if a type can be "empty" */
+export type CanBeEmpty<T> = T extends null | undefined | string | unknown[] | readonly unknown[] | Record<PropertyKey, unknown> ? true : false;
+/** Utility type to determine if a type is extensible */
+export type IsExtensible<T> = T extends null | undefined ? false : true;
+/** A guard predicate function — broad enough for TypeGuard, .optional, .notEmpty, and custom guards */
+export type TypeGuardPredicate = ((value: unknown) => boolean) & {
+    validate?: (value: unknown) => any;
+};
+/** A shape object mapping property names to guard predicates or nested shapes */
+export type TypeGuardShape = {
+    [key: string]: TypeGuardPredicate | TypeGuardShape;
+};
+/** Cosmetic type flattener for IDE tooltips */
+export type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/** Recursively infers the TypeScript type from a TypeGuardShape */
+export type InferShape<S extends TypeGuardShape> = Simplify<{
+    [K in keyof S]: S[K] extends (value: unknown) => value is infer T ? T : S[K] extends TypeGuardShape ? InferShape<S[K]> : never;
+}>;
+export {};
+//# sourceMappingURL=types.d.ts.map

package/esm/src/types.d.ts.map

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

package/esm/src/types.js

@@ -0,0 +1 @@
+export {};

package/esm/src/utilities.d.ts

@@ -0,0 +1,95 @@
+import type { Context, GuardedType, TypeGuard } from "./types.js";
+/**
+ * Utility to verify if a property exists in an object. Checks that
+ * k is a key in t. If a guard method is provided, it will also check
+ * that the value at k passes the guard.
+ * @param {object} t The object to check for property k.
+ * @param {string|number|Symbol} k The key for property k.
+ * @param {Function|undefined} guard The optional type guard to validate t[k].
+ * @param {Context|undefined} ctx Optional validation context for path tracking.
+ *        Note: ctx is expected to already include the key in its path when passed.
+ * @param {string|undefined} errorMessage Optional custom error message to use instead of default.
+ * @returns {boolean}
+ */
+export declare function hasProperty<K extends PropertyKey, G = unknown>(t: object, k: K, guard?: (v: unknown) => v is G, ctx?: Context, errorMessage?: string): t is {
+    [K2 in K]: G;
+};
+/**
+ * Checks if an object does not have a specific property.
+ *
+ * This function determines whether the given property key `k` does not exist
+ * in the object `t`. It uses TypeScript's type guard feature to refine the type
+ * of the object, ensuring that the property `k` is absent or explicitly `undefined`.
+ *
+ * @template K - The type of the property key to check.
+ * @param t - The object to check for the absence of the property.
+ * @param k - The property key to verify.
+ * @param ctx - Optional validation context for path tracking.
+ * @param errorMessage - Optional custom error message to use instead of default.
+ * @returns A boolean indicating whether the property `k` does not exist in the object `t`.
+ */
+export declare function doesNotHaveProperty<K extends PropertyKey>(t: object, k: K, ctx?: Context, errorMessage?: string): t is {
+    [K2 in K]: never;
+};
+/**
+ * Checks if an object has an optional property that passes a type guard.
+ *
+ * This function verifies if a property is either:
+ * - Undefined (which is valid for optional properties)
+ * - Present and passes the specified type guard
+
+ * @param t - The object to check
+ * @param k - The property key to look for
+ * @param guard - Optional function that checks if the value is of type G
+ * @param ctx - Optional validation context for path tracking
+ * @param errorMessage - Optional custom error message to use instead of default
+ * @returns Type predicate indicating if the object has the optional property of type G
+ */
+export declare function hasOptionalProperty<K extends PropertyKey, G = unknown>(t: object, k: K, guard?: (v: unknown) => v is G, ctx?: Context, errorMessage?: string): t is {
+    [K2 in K]+?: G;
+};
+/**
+ * Utility to verify if a value is included in a tuple.
+ * @param {array} t The tuple to check for the presence of index i.
+ * @param {unknown} i The index to check.
+ * @param {Function} guard The type guard to validate t[i].
+ * @returns {boolean}
+ */
+export declare function tupleHas<T extends readonly unknown[], I extends number, G = unknown>(t: T, i: I, guard: (v: unknown) => v is G): t is T & {
+    [K in I]: G;
+};
+/**
+ * Determines whether the specified value `i` is included in the array `t`.
+ * Useful for checking if a value is part of a union type represented by a tuple.
+ * @typeParam T - A readonly array of unknown elements.
+ * @param t - The array to search within.
+ * @param v - The value to search for in the array.
+ * @returns `true` if `v` is found in `t`, otherwise `false`.
+ */
+export declare function includes<T extends readonly unknown[]>(t: T, v: unknown): v is T[number];
+/**
+ * Determines if a given property key exists as a key in the specified object.
+ *
+ * @template T - The type of the object to check against.
+ * @param k - The property key to check.
+ * @param t - The object to check the property key against.
+ * @returns A boolean indicating whether the property key exists in the object.
+ */
+export declare function keyOf<T extends object>(k: unknown, t: T, ctx?: Context, errorMessage?: string): k is keyof T;
+/**
+ * Formats an error message based on the provided value and optional metadata.
+ *
+ * @param value - The value that caused the error.
+ * @param name - An optional name of the expected type or condition.
+ * @returns A formatted error message string indicating the expected type (if provided) and the received value.
+ */
+export declare function formatErrorMessage(value: unknown, name?: string): string;
+/**
+ * Creates a union type guard from a list of type guards.
+ *
+ * @typeParam G - A tuple of `TypeGuard<unknown>` types (must have at least one guard).
+ * @param guards - The type guards to combine into a union.
+ * @returns A type guard that accepts any value accepted by at least one of the provided guards.
+ */
+export declare const unionOf: <G extends readonly [TypeGuard<unknown>, ...TypeGuard<unknown>[]]>(...guards: G) => TypeGuard<GuardedType<G[number]>>;
+//# sourceMappingURL=utilities.d.ts.map

package/esm/src/utilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utilities.d.ts","sourceRoot":"","sources":["../../src/src/utilities.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAElE;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,WAAW,EAAE,CAAC,GAAG,OAAO,EAC5D,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,CAAC,EACJ,KAAK,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,CAAC,IAAI,CAAC,EAC9B,GAAG,CAAC,EAAE,OAAO,EACb,YAAY,CAAC,EAAE,MAAM,GACpB,CAAC,IAAI;KAAG,EAAE,IAAI,CAAC,GAAG,CAAC;CAAE,CAmCvB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,WAAW,EACvD,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,CAAC,EACJ,GAAG,CAAC,EAAE,OAAO,EACb,YAAY,CAAC,EAAE,MAAM,GACpB,CAAC,IAAI;KAAG,EAAE,IAAI,CAAC,GAAG,KAAK;CAAE,CAM3B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,WAAW,EAAE,CAAC,GAAG,OAAO,EACpE,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,CAAC,EACJ,KAAK,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,CAAC,IAAI,CAAC,EAC9B,GAAG,CAAC,EAAE,OAAO,EACb,YAAY,CAAC,EAAE,MAAM,GACpB,CAAC,IAAI;KAAG,EAAE,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC;CAAE,CAIzB;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,SAAS,OAAO,EAAE,EAAE,CAAC,SAAS,MAAM,EAAE,CAAC,GAAG,OAAO,EAClF,CAAC,EAAE,CAAC,EACJ,CAAC,EAAE,CAAC,EACJ,KAAK,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,CAAC,IAAI,CAAC,GAC5B,CAAC,IAAI,CAAC,GAAG;KAAG,CAAC,IAAI,CAAC,GAAG,CAAC;CAAE,CAE1B;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,SAAS,OAAO,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAEvF;AAED;;;;;;;GAOG;AACH,wBAAgB,KAAK,CAAC,CAAC,SAAS,MAAM,EACpC,CAAC,EAAE,OAAO,EACV,CAAC,EAAE,CAAC,EACJ,GAAG,CAAC,EAAE,OAAO,EACb,YAAY,CAAC,EAAE,MAAM,GACpB,CAAC,IAAI,MAAM,CAAC,CAYd;AAiCD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAQxE;AAED;;;;;;GAMG;AACH,eAAO,MAAM,OAAO,GAAI,CAAC,SAAS,SAAS,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,GAAG,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC,EACtF,GAAG,QAAQ,CAAC,KACX,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAYlC,CAAC"}

package/esm/src/utilities.js

@@ -0,0 +1,196 @@
+import { isUndefined } from "./guard.js";
+import { hasContext } from "./introspect.js";
+/**
+ * Utility to verify if a property exists in an object. Checks that
+ * k is a key in t. If a guard method is provided, it will also check
+ * that the value at k passes the guard.
+ * @param {object} t The object to check for property k.
+ * @param {string|number|Symbol} k The key for property k.
+ * @param {Function|undefined} guard The optional type guard to validate t[k].
+ * @param {Context|undefined} ctx Optional validation context for path tracking.
+ *        Note: ctx is expected to already include the key in its path when passed.
+ * @param {string|undefined} errorMessage Optional custom error message to use instead of default.
+ * @returns {boolean}
+ */
+export function hasProperty(t, k, guard, ctx, errorMessage) {
+    if (!(k in t)) {
+        if (ctx)
+            ctx.addIssue(errorMessage ?? `Missing required property: ${String(k)}`);
+        return false;
+    }
+    if (!guard)
+        return true;
+    const value = t[k];
+    // If custom errorMessage provided, use simple boolean check and add custom message on failure
+    if (errorMessage) {
+        if (!guard(value)) {
+            if (ctx) {
+                ctx.addIssue(errorMessage);
+                // Note: Returns true despite failure to avoid short-circuiting && chains in parsers,
+                // allowing collection of multiple property errors. This is safe because validate()
+                // checks ctx.issues and returns { issues } instead of { value } when errors exist.
+                return true;
+            }
+            return false;
+        }
+        return true;
+    }
+    // If context is provided, use context-aware validation if available on the guard
+    if (ctx && hasContext(guard)) {
+        guard._.context(value, ctx); // Run validation, errors accumulate in ctx
+        // Note: Returns true despite potential failure to avoid short-circuiting && chains,
+        // enabling multi-property error collection. Safe because validate() checks ctx.issues.
+        return true;
+    }
+    return guard(value);
+}
+/**
+ * Checks if an object does not have a specific property.
+ *
+ * This function determines whether the given property key `k` does not exist
+ * in the object `t`. It uses TypeScript's type guard feature to refine the type
+ * of the object, ensuring that the property `k` is absent or explicitly `undefined`.
+ *
+ * @template K - The type of the property key to check.
+ * @param t - The object to check for the absence of the property.
+ * @param k - The property key to verify.
+ * @param ctx - Optional validation context for path tracking.
+ * @param errorMessage - Optional custom error message to use instead of default.
+ * @returns A boolean indicating whether the property `k` does not exist in the object `t`.
+ */
+export function doesNotHaveProperty(t, k, ctx, errorMessage) {
+    if (k in t) {
+        if (ctx)
+            ctx.addIssue(errorMessage ?? `Unexpected property: ${String(k)}`);
+        return false;
+    }
+    return true;
+}
+/**
+ * Checks if an object has an optional property that passes a type guard.
+ *
+ * This function verifies if a property is either:
+ * - Undefined (which is valid for optional properties)
+ * - Present and passes the specified type guard
+
+ * @param t - The object to check
+ * @param k - The property key to look for
+ * @param guard - Optional function that checks if the value is of type G
+ * @param ctx - Optional validation context for path tracking
+ * @param errorMessage - Optional custom error message to use instead of default
+ * @returns Type predicate indicating if the object has the optional property of type G
+ */
+export function hasOptionalProperty(t, k, guard, ctx, errorMessage) {
+    if (isUndefined(t[k]))
+        return true;
+    return hasProperty(t, k, guard, ctx, errorMessage);
+}
+/**
+ * Utility to verify if a value is included in a tuple.
+ * @param {array} t The tuple to check for the presence of index i.
+ * @param {unknown} i The index to check.
+ * @param {Function} guard The type guard to validate t[i].
+ * @returns {boolean}
+ */
+export function tupleHas(t, i, guard) {
+    return (i in t) && guard(t[i]);
+}
+/**
+ * Determines whether the specified value `i` is included in the array `t`.
+ * Useful for checking if a value is part of a union type represented by a tuple.
+ * @typeParam T - A readonly array of unknown elements.
+ * @param t - The array to search within.
+ * @param v - The value to search for in the array.
+ * @returns `true` if `v` is found in `t`, otherwise `false`.
+ */
+export function includes(t, v) {
+    return t.includes(v);
+}
+/**
+ * Determines if a given property key exists as a key in the specified object.
+ *
+ * @template T - The type of the object to check against.
+ * @param k - The property key to check.
+ * @param t - The object to check the property key against.
+ * @returns A boolean indicating whether the property key exists in the object.
+ */
+export function keyOf(k, t, ctx, errorMessage) {
+    if (typeof k !== "string" && typeof k !== "number" && typeof k !== "symbol") {
+        if (ctx)
+            ctx.addIssue(errorMessage ?? `Invalid key type: ${typeof k}`);
+        return false;
+    }
+    if (!(k in t)) {
+        if (ctx)
+            ctx.addIssue(errorMessage ?? `Key "${String(k)}" not found in object`);
+        return false;
+    }
+    return true;
+}
+/**
+ * Safely stringifies a value for error messages, handling edge cases that JSON.stringify cannot.
+ */
+function safeStringify(value) {
+    if (value === null)
+        return "null";
+    if (value === undefined)
+        return "undefined";
+    const type = typeof value;
+    if (type === "string")
+        return `'${value}'`;
+    if (type === "boolean")
+        return String(value);
+    if (type === "symbol")
+        return value.toString();
+    if (type === "function") {
+        const fn = value;
+        return `[Function${fn.name ? `: ${fn.name}` : ""}]`;
+    }
+    if (type === "bigint")
+        return `${String(value)}n`;
+    if (type === "number") {
+        if (Number.isNaN(value))
+            return "NaN";
+        if (!Number.isFinite(value))
+            return value === Infinity ? "Infinity" : "-Infinity";
+        return String(value);
+    }
+    // Objects and arrays - wrap in try/catch for circular references
+    try {
+        return JSON.stringify(value, (_key, val) => (typeof val === "bigint" ? `${String(val)}n` : val));
+    }
+    catch {
+        return Object.prototype.toString.call(value);
+    }
+}
+/**
+ * Formats an error message based on the provided value and optional metadata.
+ *
+ * @param value - The value that caused the error.
+ * @param name - An optional name of the expected type or condition.
+ * @returns A formatted error message string indicating the expected type (if provided) and the received value.
+ */
+export function formatErrorMessage(value, name) {
+    const received = safeStringify(value);
+    if (name) {
+        return `Expected ${name}. Received: ${received}`;
+    }
+    return `Invalid value. Received: ${received}`;
+}
+/**
+ * Creates a union type guard from a list of type guards.
+ *
+ * @typeParam G - A tuple of `TypeGuard<unknown>` types (must have at least one guard).
+ * @param guards - The type guards to combine into a union.
+ * @returns A type guard that accepts any value accepted by at least one of the provided guards.
+ */
+export const unionOf = (...guards) => {
+    if (guards.length === 0) {
+        throw new Error("unionOf requires at least one type guard");
+    }
+    let store = guards[0];
+    for (let i = 1; i < guards.length; i++) {
+        store = store.or(guards[i]);
+    }
+    return store;
+};