@budsbox/lib-es 2.3.0 → 3.0.0

package/dist/guards/message.js

@@ -0,0 +1,224 @@
+import { entries } from '#object';
+import { isArray, isDate, isError, isFunction, isMap, isNil, isNotNil, isObject, isPrimitive, isSet, isString, isSymbol, isWeakMapLike, isWeakSetLike, } from './check.js';
+import { getPredicateDescriptor } from './describe.js';
+/**
+ * Creates an expected message string for a given predicate, value, and value name.
+ *
+ * This function validates that the predicate is a valid function and constructs
+ * an informative error message describing what was expected of the `value` in
+ * terms of the `predicate`'s description or descriptor. This message integrates
+ * details about the provided `value` to aid debugging.
+ *
+ * @internal
+ * @param predicate - The predicate function used to test the value. Must be a valid function.
+ * @param value - The value being evaluated against the predicate.
+ * @param valueName - The name of the value being tested. Defaults to `'value'`.
+ * @returns A formatted string message describing the expected value and its type.
+ * @throws {TypeError} if the `predicate` is not a function.
+ */
+export const formatPredicateExpectedMessage = (predicate, value, valueName = 'value') => {
+    const { condition, isType, isValue } = getPredicateConditions(predicate);
+    return `Expected ${valueName} ${condition}, got${isType ? ` ${debugValueType(value)}` : ''}${isValue ?
+        isType ? [' (', debugValueString(value), ')'].join('')
+            : ` ${debugValueString(value)}`
+        : ''} instead`;
+};
+/**
+ * Generates a description of the conditions associated with a given predicate.
+ * The description includes whether the predicate is a type guard, a value check, or both.
+ *
+ * @internal
+ * @param predicate - The predicate whose conditions are to be analyzed and described.
+ * @param nested - A flag indicating if the predicate is part of a nested structure. Defaults to `false`.
+ * @returns An object comprising:
+ * - `condition`: A string describing the predicate's conditions.
+ * - `isType`: A boolean indicating whether the predicate is a type guard.
+ * - `isValue`: A boolean indicating whether the predicate checks a value.
+ * @typeParam Predicate - The expected type of the predicate parameter.
+ */
+export const getPredicateConditions = (predicate, nested = false) => {
+    const descriptor = getPredicateDescriptor(predicate);
+    if (isNil(descriptor))
+        return {
+            condition: defaultDescription(predicate),
+            isType: false,
+            isValue: true,
+        };
+    const descriptorEntry = entries(descriptor)[0];
+    if (descriptorEntry[0] === 'condition') {
+        return { condition: descriptorEntry[1], isType: false, isValue: true };
+    }
+    else if (descriptorEntry[0] === 'type') {
+        return {
+            condition: nested ? descriptorEntry[1] : `to be ${descriptorEntry[1]}`,
+            isType: true,
+            isValue: false,
+        };
+    }
+    else {
+        const [conjunction, predicates] = descriptorEntry;
+        const separator = `, ${conjunction} `;
+        let isType = false, isValue = false;
+        const typeGuards = [];
+        const plains = [];
+        for (const p of predicates) {
+            const pc = getPredicateConditions(p, true);
+            isType || (isType = pc.isType);
+            isValue || (isValue = pc.isValue);
+            if (pc.isValue) {
+                plains.push(pc.isType ? `(${pc.condition})` : pc.condition);
+            }
+            else if (pc.isType) {
+                typeGuards.push(pc.condition);
+            }
+        }
+        const typeGuardString = typeGuards.length === 1 ?
+            typeGuards[0]
+            : [typeGuards.slice(0, -1).join(',')]
+                .concat(typeGuards.slice(-1))
+                .join(separator);
+        const plainString = plains.join(separator);
+        const isPrintableTypes = typeGuards.length > 0;
+        const condition = `${isPrintableTypes ? `to be ${typeGuardString}` : ''}${isValue ? `${isPrintableTypes ? separator : ''}${plainString}` : ''}`;
+        return { condition, isType, isValue };
+    }
+};
+/**
+ * Determines the type description of a given value in a human-readable format.
+ *
+ * - If the value is `null`, `undefined`, or a `Symbol`, it will return the string representation.
+ * - If the value is a primitive type (e.g., `number`, `string`, `boolean`), it will return the result of `typeof value`.
+ * - If the value is a function, it will return `'function'`.
+ * - If the value is an array, it will return `'array'`.
+ * - For objects, it will return the `Symbol.toStringTag` or the internal `[[Class]]` property of the object.
+ *
+ * @param value - The value whose type needs to be determined.
+ * @returns A string representation of the value's type.
+ */
+export const debugValueType = (value) => {
+    if (isNil(value) || isSymbol(value))
+        return String(value);
+    if (Number.isNaN(value))
+        return 'NaN';
+    if (isPrimitive(value))
+        return typeof value;
+    if (isFunction(value))
+        return 'function';
+    if (isArray(value))
+        return 'array';
+    const proto = Object.getPrototypeOf(value);
+    if (proto === Object.prototype || proto === null)
+        return 'object';
+    return `${objectTag(value)} object`;
+};
+/**
+ * Generates a string representation of a given value for debugging purposes.
+ *
+ * The function handles various data types and outputs an appropriate string representation:
+ * - Strings are truncated to 15 characters and represented in JSON format.
+ * - Primitives are converted to their string form.
+ * - Functions are represented by their name or identified as anonymous.
+ * - Arrays are truncated to a preview of up to 5 elements, followed by `...` if there are more.
+ * - Objects attempt to serialize to JSON, truncating lengthy results, or falling back to custom fallback logic.
+ *
+ * @param value - A value of any type to be represented as a debug string.
+ * @param options
+ * @returns A debug-friendly string representation of the provided value.
+ */
+export const debugValueString = (value, { maxLength = 15, maxDepth = 2, maxItems = 3, seen = new WeakSet(), } = {}) => {
+    if (isString(value)) {
+        return JSON.stringify(clamp(value, maxLength));
+    }
+    if (isPrimitive(value))
+        return String(value);
+    if (seen.has(value))
+        return '[Circular]';
+    if (isFunction(value))
+        return value.name.length > 0 ?
+            `function ${value.name}`
+            : 'anonymous function';
+    if (isArray(value)) {
+        if (maxDepth === 0)
+            return '[...]';
+        const debugSlice = value.slice(0, maxItems).map((item) => debugValueString(item, {
+            maxLength,
+            maxDepth: maxDepth - 1,
+            maxItems,
+            seen,
+        }));
+        return `[${debugSlice.join(',')}${value.length > maxItems ? ', ...' : ''}]`;
+    }
+    if (isDate(value))
+        return `Date(${Number.isNaN(value.getTime()) ? 'Invalid' : value.toISOString()})`;
+    if (isError(value))
+        return `${value.name}(${debugValueString(value.message)})`;
+    const tag = shortObjectTag(value);
+    if (isMap(value) || isSet(value))
+        return `${tag}(${String(value.size)})`;
+    if (isWeakMapLike(value) || isWeakSetLike(value))
+        return `${tag}(?)`;
+    if ('toString' in value &&
+        // eslint-disable-next-line @typescript-eslint/unbound-method
+        isFunction(value.toString) &&
+        value.toString !== Object.prototype.toString) {
+        // eslint-disable-next-line @typescript-eslint/no-base-to-string
+        return `${tag}(${value.toString()})`;
+    }
+    try {
+        return `${tag}(${clamp(JSON.stringify(value), maxLength)})`;
+    }
+    catch {
+        return `${shortObjectTag(value)} object`;
+    }
+};
+/**
+ *
+ * @param value
+ */
+export const formatError = (value) => {
+    const { name, message } = value;
+    let codePart, causePart;
+};
+/**
+ * Constructs a dot-notation or bracket-notation string representation
+ * for accessing nested properties of an object based on the provided keys.
+ *
+ * @internal
+ * @param sourceName - The base name of the object or source from which properties are being accessed.
+ * @param keys - A variadic list of property keys representing the nested path.
+ *               Each key will be used to generate the accessor string.
+ * @returns A string representing the accessor path in dot-notation for valid identifiers
+ *          or bracket-notation for non-identifier keys.
+ * @remarks The function is intended to be used for generating error messages.
+ */
+export const formatAccessString = (sourceName, ...keys) => keys.reduce((acc, key) => `${acc}${isString(key) && /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(key) ? `.${key}` : `[${debugValueString(key)}]`}`, sourceName);
+/**
+ * Extracts and returns the `Symbol.toStringTag` or internal `[[Class]]` property of a given object as a string.
+ *
+ * The method utilizes `Object.prototype.toString` to determine the object type
+ * and removes the surrounding `[object ...]` syntax to provide the type name.
+ *
+ * @param value - The input value from which the object tag will be extracted.
+ * @returns The name of the internal `[[Class]]` corresponding to the input value.
+ */
+export const shortObjectTag = (value) => Object.prototype.toString.call(value).slice(8, -1);
+/**
+ *
+ * @param value
+ */
+export const objectTag = (value) => {
+    if (isObject(value)) {
+        const ctor = [
+            value.constructor,
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+            Object.getPrototypeOf(value)?.constructor,
+        ].find(isFunction);
+        const ctorName = isNotNil(ctor) && ctor.name ? ctor.name : 'Object';
+        const tag = Symbol.toStringTag in value ? value[Symbol.toStringTag] : ctorName;
+        return `${ctorName}${isString(tag) && tag !== ctorName ? `[${tag}]` : ''}`;
+    }
+    return shortObjectTag(value);
+};
+const defaultDescription = (predicate) => `to satisfy ${predicate.name || '(anonymous)'} predicate`;
+const clamp = (str, maxLength) => str.length > maxLength ? `${str.slice(0, maxLength)}...` : str;
+//# sourceMappingURL=message.js.map

package/dist/guards/prop.d.ts

@@ -0,0 +1,232 @@
+import type { IsNever, IsUnknown, IterableElement, KeysOfUnion } from 'type-fest';
+import type { AnyRecord, CustomRecord, DistributedPropValue, Infer, IsEmptyObject, NarrowedType, Nil, Predicate, TypePredicate, Undef, ValuePredicate, WithFallback } from '@budsbox/lib-types';
+/** @ignore */
+export declare function hasProp(source: Nil, prop: PropertyKey, ...rest: HasPropRest): source is never;
+/** @ignore */
+export declare function hasProp(source: unknown, prop: ProtectedKey, ...rest: HasPropRest): source is never;
+/**
+ * Checks if a property exists on the provided source object.
+ *
+ * Narrows the source type to include the specified property key with an unknown value.
+ *
+ * @param source - The object to check.
+ * @param key - The property key to verify.
+ * @param checkProto - Whether to check the prototype chain.
+ * @returns Boolean indicating whether the property exists.
+ * @throws {@link !TypeError} If the provided key is not a valid property key.
+ * @throws {@link !TypeError} If the provided checkProto flag is not a boolean.
+ * @typeParam TSource - The source object type.
+ * @typeParam TKey - The property key type.
+ * @remarks The `__proto__` and `constructor` keys are always considered non-existent.
+ * {@label NO_PREDICATE}
+ * @category Checks
+ */
+export declare function hasProp<TSource, TKey extends PropertyKey>(source: TSource, key: TKey, checkProto?: boolean): source is SourceNarrowed<TSource, TKey>;
+/**
+ * Checks if a property exists on a non-null source and passes a type guard test.
+ *
+ * Narrows both the source type and the property value type based on the provided type guard.
+ *
+ * @param source - The object to check.
+ * @param key - The property key to verify.
+ * @param typeGuard - A type guard to narrow the property value type.
+ * Accepts the property value as the only parameter.
+ * @param checkProto - Whether to check the prototype chain.
+ * @returns Boolean indicating whether the property exists and satisfies the type guard.
+ * @throws {@link !TypeError} In the following cases:
+ * - If the provided `key` is not a valid property key.
+ * - If the provided `checkProto` flag is not a boolean.
+ * - If the provided type guard is not a function.
+ * - If the provided type guard does not return a boolean.
+ * @typeParam TSource - The source object type.
+ * @typeParam TKey - The property key type.
+ * @typeParam TGuard - The type guard type.
+ * @remarks The `__proto__` and `constructor` keys are always considered non-existent.
+ * {@label TYPE_GUARD}
+ */
+export declare function hasProp<TSource, TKey extends PropertyKey, TGuard extends TypePredicate<PropValue<TSource, TKey>>>(source: TSource, key: TKey, typeGuard: TGuard, checkProto?: boolean): source is SourceNarrowedWithTypeGuard<TSource, TKey, TGuard>;
+/**
+ * Checks if a property exists on the provided source and optionally passes a test.
+ *
+ * This overload doesn't narrow a type,
+ * because the predicate may reject valid property values without invalidating their existence,
+ * which would cause incorrect type elimination in the `else` branch.
+ * If you need type narrowing for the property value, use the type guard overload instead.
+ * Alternatively, you can split the checks: `hasProp(source, key) && test(source[key])`.
+ *
+ * @param source - The object to check.
+ * @param key - The property key to verify.
+ * @param predicate - An optional predicate to test the property value.
+ * Accepts the property value as the only parameter.
+ * @param checkProto - Whether to check the prototype chain.
+ * @returns Boolean indicating whether the property exists and satisfies the test.
+ * @throws {@link !TypeError} In the following cases:
+ * - If the provided key is not a valid property key.
+ * - If the provided checkProto flag is not a boolean.
+ * - If the provided predicate is not a function.
+ * - If the provided predicate does not return a boolean.
+ * @remarks The `__proto__` and `constructor` keys are always considered non-existent.
+ * @typeParam TSource - The source object type.
+ * @typeParam TKey - The property key type.
+ * {@label PREDICATE}
+ */
+export declare function hasProp<TSource, TKey extends PropertyKey>(source: TSource, key: TKey, predicate: ValuePredicate<PropValue<TSource, TKey>>, checkProto?: boolean): boolean;
+/** @ignore */
+export declare function assertProp(source: Nil, key: PropertyKey, ...rest: AssertPropRest): never;
+/** @ignore */
+export declare function assertProp(source: unknown, key: ProtectedKey, ...rest: AssertPropRest): never;
+/**
+ * Asserts that a property exists on the provided source object.
+ *
+ * Narrows the source type to include the specified property key with an unknown value.
+ *
+ * @param source - The object to check.
+ * @param key - The property key to verify.
+ * @param rest - Optional parameters: checkProto flag and sourceName for error messages.
+ * @returns void if the assertion succeeds, otherwise throws an error.
+ * {@label NO_PREDICATE}
+ * @throws {@link !TypeError} In the following cases:
+ * - If the source is nil.
+ * - If the provided key is not a valid property key.
+ * - If the property does not exist.
+ * @typeParam TSource - The source object type.
+ * @typeParam TKey - The property key type.
+ * @remarks The `__proto__` and `constructor` keys are always considered non-existent.
+ * @category Assertions
+ */
+export declare function assertProp<TSource, TKey extends StrictKey<TSource>>(source: TSource, key: TKey, ...rest: WithoutPredicate<AssertPropRest>): asserts source is SourceNarrowed<TSource, TKey>;
+/**
+ * Asserts that a property exists on a non-null source and passes a type guard test.
+ *
+ * Narrows both the source type and the property value type based on the provided type guard.
+ *
+ * @param source - The object to check.
+ * @param key - The property key to verify.
+ * @param typeGuard - A type guard to narrow the property value type.
+ * Accepts the property value as the only parameter.
+ * @param rest - Optional parameters: `checkProto` flag and `sourceName` for error messages.
+ * @returns void if the assertion succeeds, otherwise throws an error.
+ * {@label TYPE_GUARD}
+ * @throws {@link !TypeError} In the following cases:
+ * - If the source is nil.
+ * - If the provided key is not a valid property key.
+ * - If the property does not exist.
+ * - If the provided type guard is not a function.
+ * - If the provided type guard does not return a boolean.
+ * - If the property value fails the type guard test.
+ * @typeParam TSource - The source object type.
+ * @typeParam TKey - The property key type.
+ * @typeParam TGuard - The type guard type.
+ * @remarks The `__proto__` and `constructor` keys are always considered non-existent.
+ * @category Assertions
+ */
+export declare function assertProp<TSource, TKey extends StrictKey<TSource>, TGuard extends TypePredicate<PropValue<TSource, TKey>>>(source: TSource, key: TKey, typeGuard: TGuard, ...rest: WithoutPredicate<AssertPropRest>): asserts source is SourceNarrowedWithTypeGuard<TSource, TKey, TGuard>;
+/**
+ * Asserts that a property exists on the provided source and optionally passes a test.
+ *
+ * @param source - The object to check.
+ * @param key - The property key to verify.
+ * @param predicate - An optional predicate to test the property value.
+ * Accepts the property value as the only parameter.
+ * @param rest - Optional parameters: checkProto flag and sourceName for error messages.
+ * @returns void if the assertion succeeds, otherwise throws an error.
+ * {@label PREDICATE}
+ * @throws {@link !TypeError} In the following cases:
+ * - If the source is nil.
+ * - If the provided key is not a valid property key.
+ * - If the property does not exist.
+ * - If the provided predicate is not a function.
+ * - If the provided predicate does not return a boolean.
+ * - If the property value fails the predicate test.
+ * @typeParam TSource - The source object type.
+ * @typeParam TKey - The property key type.
+ * @remarks The `__proto__` and `constructor` keys are always considered non-existent.
+ * @category Assertions
+ */
+export declare function assertProp<TSource, TKey extends StrictKey<TSource>>(source: TSource, key: TKey, predicate?: ValuePredicate<PropValue<TSource, TKey>>, ...rest: WithoutPredicate<AssertPropRest>): asserts source is SourceNarrowed<TSource, TKey>;
+/**
+ * Asserts that a property either does not exist or passes a type guard test.
+ *
+ * Narrows both the source type and the property value type based on the provided type guard.
+ *
+ * @param source - The object to check.
+ * @param key - The property key to verify.
+ * @param typeGuard - A type guard to narrow the property value type.
+ * Accepts the property value as the only parameter.
+ * @param rest - Optional parameters: `checkProto` flag and `sourceName` for error messages.
+ * @returns void.
+ * {@label TYPE_GUARD}
+ * @throws {@link !TypeError} In the following cases:
+ * - If the provided key is not a valid property key.
+ * - If the provided type guard is not a function.
+ * - If the provided type guard does not return a boolean.
+ * - If the property exists but fails the type guard test.
+ * @typeParam TSource - The source object type.
+ * @typeParam TKey - The property key type.
+ * @typeParam TGuard - The type guard type.
+ * @remarks The `__proto__` and `constructor` keys are always considered non-existent.
+ * @category Assertions
+ */
+export declare function assertOptionalProp<TSource, TKey extends PropertyKey, TGuard extends TypePredicate<PropValue<TSource, TKey>>>(source: TSource, key: TKey, typeGuard: TGuard, ...rest: WithoutPredicate<AssertPropRest>): asserts source is SourceEliminated<TSource, TKey> | SourceNarrowedWithTypeGuard<TSource, TKey, TGuard, true>;
+/**
+ * Asserts that a property either does not exist or passes a predicate test.
+ *
+ * @param source - The object to check.
+ * @param key - The property key to verify.
+ * @param predicate - A predicate to test the property value if it exists.
+ * Accepts the property value as the only parameter.
+ * @param rest - Optional parameters: `checkProto` flag and `sourceName` for error messages.
+ * @returns void.
+ * {@label PREDICATE}
+ * @throws {@link !TypeError} In the following cases:
+ * - If the provided key is not a valid property key.
+ * - If the provided predicate is not a function.
+ * - If the provided predicate does not return a boolean.
+ * - If the property exists but fails the predicate test.
+ * @typeParam TSource - The source object type.
+ * @typeParam TKey - The property key type.
+ * @remarks The `__proto__` and `constructor` keys are always considered non-existent.
+ * @category Assertions
+ */
+export declare function assertOptionalProp<TSource, TKey extends PropertyKey>(source: TSource, key: TKey, predicate: ValuePredicate<PropValue<TSource, TKey>>, ...rest: WithoutPredicate<AssertPropRest>): asserts source is SourceEliminated<TSource, TKey> | SourceNarrowed<TSource, TKey, true>;
+declare const protectedKeys: Set<"constructor" | "__proto__">;
+type PropValue<TSource, TKey extends PropertyKey> = WithFallback<DistributedPropValue<TSource, TKey, true>>;
+type StrictKey<TSource> = WithFallback<KeysOfUnion<TSource>, PropertyKey>;
+/**
+ * Represents a utility type that narrows the source object `TSource`
+ * to include a subset of properties defined by `TKey` with their respective value types.
+ *
+ * If `TSource` is compatible with the specified property key and value criteria,
+ * it extends `CustomRecord` to provide the narrowed structure. Otherwise, it falls
+ * back to the specified fallback type.
+ *
+ * @internal
+ * @typeParam TSource - The source object type to be narrowed.
+ * @typeParam TKey - The property key or keys to narrow down on.
+ * @typeParam TPartial - A boolean flag indicating whether the properties in `TKey` should be optional.
+ * @inline
+ */
+type SourceNarrowed<TSource, TKey extends PropertyKey, TPartial extends boolean = false> = WithFallback<TSource extends AnyRecord<TKey, unknown> ? TSource & CustomRecord<TKey, PropValue<TSource, TKey>, TPartial> : never, TSource & CustomRecord<TKey, PropValue<TSource, TKey>, TPartial>>;
+/**
+ * @preventInline
+ * @ignore
+ */
+type SourceNarrowedWithTypeGuard<TSource, TKey extends PropertyKey, TGuard extends TypePredicate, TPartial extends boolean = false> = WithFallback<TSource extends AnyRecord<TKey, unknown> ? IsNever<TSource[TKey & keyof TSource] & NarrowedType<TGuard>> extends true ? never : TSource & CustomRecord<TKey, NarrowedType<TGuard>, TPartial> : never, TSource & CustomRecord<TKey, NarrowedType<TGuard>, TPartial>>;
+/**
+ * @preventInline
+ * @ignore
+ */
+type SourceEliminated<TSource, TKey extends PropertyKey> = TSource extends Readonly<Record<TKey, unknown>> ? never : TSource extends AnyRecord<TKey, unknown> ? Infer<IsEmptyObject<Omit<TSource, TKey>> extends true ? never : TSource & CustomRecord<TKey, never, true>> : IsUnknown<TSource> extends true ? (null | undefined) & TSource : TSource;
+type HasPropRest = readonly [checkProto?: Undef<boolean>] | readonly [predicate?: Undef<Predicate>, checkProto?: Undef<boolean>] | readonly [predicate?: Undef<Predicate>];
+type AssertPropRest = readonly [
+    ...(HasPropRest | []),
+    sourceName?: Undef<string>
+];
+/**
+ * @preventInline
+ * @ignore
+ */
+type WithoutPredicate<TRest extends readonly unknown[]> = Exclude<TRest, readonly [predicate?: Undef<Predicate>, ...rest: unknown[]]>;
+type ProtectedKey = IterableElement<typeof protectedKeys>;
+export {};
+//# sourceMappingURL=prop.d.ts.map

package/dist/guards/prop.js

@@ -0,0 +1,45 @@
+import { assertFunction, assertNotNil, assertPropKey, callPredicate, invariant, normalizeOptionalRest, } from './assert.js';
+import { isBoolean, isFunction, isNil, isString } from './check.js';
+import { formatAccessString, formatDebugValue, formatPredicateExpectedMessage, } from './format.js';
+export function hasProp(source, key, ...rest) {
+    assertPropKey(key, 'key');
+    invariant(rest.length <= 2, () => `Expected 2, 3, or 4 arguments, got ${String(rest.length + 2)} instead.`);
+    let predicate = () => true, checkProto = false, index = 0;
+    if (isFunction(rest[index]))
+        predicate = rest[index++];
+    if (isBoolean(rest[index]))
+        checkProto = rest[index++];
+    invariant(index >= rest.length, () => `Invalid arguments. Unexpected arguments at position ${String(index + 2)}: ${rest
+        .slice(index)
+        .map((arg) => formatDebugValue(arg, { maxDepth: 1 }))
+        .join(', ')}`);
+    return (!isNil(source) &&
+        propExists(source, key, checkProto) &&
+        callPredicate(predicate, source[key]));
+}
+export function assertProp(source, key, ...rest) {
+    assertPropKey(key, 'key');
+    const [predicate = () => true, checkProto = false, sourceName = 'source'] = normalizeOptionalRest([isFunction, isBoolean, isString], rest, 2);
+    assertNotNil(source, sourceName);
+    invariant(propExists(source, key, checkProto), () => checkProto ?
+        `Expected ${formatAccessString(sourceName, key)} to exist`
+        : `Expected ${sourceName} to have own property ${formatDebugValue(key)}`);
+    const propValue = source[key];
+    invariant(callPredicate(predicate, propValue), () => formatPredicateExpectedMessage(predicate, propValue, formatAccessString(sourceName, key)));
+}
+export function assertOptionalProp(source, key, predicate, ...rest) {
+    assertPropKey(key, 'key');
+    assertFunction(predicate, 'predicate');
+    const [checkProto = false, sourceName = 'source'] = normalizeOptionalRest([isBoolean, isString], rest, 2);
+    if (isNil(source) || !propExists(source, key, checkProto))
+        return;
+    const propValue = source[key];
+    invariant(callPredicate(predicate, propValue), () => formatPredicateExpectedMessage(predicate, propValue, formatAccessString(sourceName, key)));
+}
+/* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Internals ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ */
+const protectedKeys = new Set(['constructor', '__proto__']);
+const propExists = (source, key, checkProto) => 
+// a little (not exhaustive) guard against prototype pollution
+!protectedKeys.has(key) &&
+    (checkProto ? key in Object(source) : Object.hasOwn(source, key));
+//# sourceMappingURL=prop.js.map