/* * @license @wistia/type-guards v0.15.0 * * Copyright (c) 2023-2026, Wistia, Inc. and its affiliates. * * This source code is unlicensed, all rights reserved. */ import { EmptyObject, Get, Paths, UnknownRecord } from "type-fest"; //#region src/guards/hasKey.d.ts /** * Curried function that tests if an input is an object * _and_ that a key that was passed in is a property of that object. * * @param value - The input object to test. * @param key - The key to test if it is a property of the input record. * @returns A function that takes an unknown input and then tests if the * input is an object and whether the key is a property of that object or not. * * @example * hasKey({ a: 1 }, 'a'); // true * hasKey({ a: 1 }, 'b'); // false * * @category Records */ declare const hasKey: (value: unknown, key: Key) => value is Record; //#endregion //#region src/guards/isArray.d.ts /** * Checks if the provided value is an array. * * @param value - The value to check. * @returns True if the value is an array, false otherwise. * * @example * isArray([1, 2]); // true * isArray('abc'); // false * * @category Arrays */ declare const isArray: (value: unknown) => value is unknown[]; //#endregion //#region src/guards/isAsyncFunction.d.ts /** * Checks if the provided value is an async function. * * @param value - The value to check. * @returns True if the value is an async function, false otherwise. * * @remarks * Detection relies on `constructor.name === 'AsyncFunction'` and is a * heuristic: async functions transpiled to regular functions return false, * async generator functions return false, and a forged `constructor` * property can fool the check. Bound async functions return true, since * `bind` preserves the prototype chain. Synchronous functions that return * promises also return false. * * @example * isAsyncFunction(async () => {}); // true * isAsyncFunction(() => {}); // false * * @category Primitives */ declare const isAsyncFunction: (value: unknown) => value is (...args: unknown[]) => Promise; //#endregion //#region src/guards/isBigInt.d.ts /** * Checks if the provided value is a bigint. * * @param value - The value to check. * @returns True if the value is a bigint, false otherwise. * * @example * isBigInt(10n); // true * isBigInt(10); // false * * @category Primitives */ declare const isBigInt: (value: unknown) => value is bigint; //#endregion //#region src/guards/isBoolean.d.ts /** * Checks if the provided value is a boolean. * * @param value - The value to check. * @returns True if the value is a boolean, false otherwise. * * @example * isBoolean(true); // true * isBoolean(1); // false * * @category Primitives */ declare const isBoolean: (value: unknown) => value is boolean; //#endregion //#region src/guards/isDate.d.ts /** * Checks if the provided value is an instance of Date. * * @param value - The value to check. * @returns True if the value is a Date instance, false otherwise. * * @remarks * Matches `Date` instances only. Does not parse date strings or * accept numeric timestamps. * * @example * isDate(new Date()); // true * isDate('2024-01-01'); // false * * @category Primitives */ declare const isDate: (value: unknown) => value is Date; //#endregion //#region src/guards/isEmptyArray.d.ts /** * Checks if the provided value is an empty array. * * @param value - The value to check. * @returns True if the value is an empty array, false otherwise. * * @example * isEmptyArray([]); // true * isEmptyArray([1]); // false * * @category Arrays */ declare const isEmptyArray: (value: unknown) => value is never[]; //#endregion //#region src/guards/isEmptyRecord.d.ts /** * Checks if the provided value is an object with no own properties. * * @param value - The value to check. * @returns True if the value is an empty object, false otherwise. * * @example * isEmptyRecord({}); // true * isEmptyRecord({ a: 1 }); // false * * @category Records */ declare const isEmptyRecord: (value: unknown) => value is EmptyObject; //#endregion //#region src/guards/isEmptyString.d.ts /** * Checks if the provided value is an empty string. * * @param value - The value to check. * @returns True if the value is an empty string, false otherwise. * * @example * isEmptyString(''); // true * isEmptyString('a'); // false * * @category Strings */ declare const isEmptyString: (value: unknown) => value is ''; //#endregion //#region src/guards/isError.d.ts /** * Checks if the provided value is an instance of Error. * * @param value - The value to check. * @returns True if the value is an Error instance, false otherwise. * * @remarks * Matches subclasses of `Error` too (e.g. `TypeError`, custom errors). * * @example * isError(new Error('boom')); // true * isError('boom'); // false * * @category Primitives */ declare const isError: (value: unknown) => value is Error; //#endregion //#region src/types/Falsy.d.ts /** * Represents a value that is falsy. * * @example * type X = Falsy; // number | '' | 0n | false | null | undefined */ type Falsy = typeof NaN | '' | 0n | false | null | undefined; //#endregion //#region src/guards/isFalsy.d.ts /** * Checks if the provided value is falsy. * * @param value - The value to check. * @returns True if the value is falsy, false otherwise. * * @remarks * Returns true for `false`, `0`, `-0`, `0n`, `''`, `null`, `undefined`, * and `NaN`. * * @example * isFalsy(0); // true * isFalsy(1); // false * * @category Truthy / falsy */ declare const isFalsy: (value: unknown) => value is Falsy; //#endregion //#region src/guards/isFiniteNumber.d.ts /** * Checks if the provided value is a finite number. * * @param value - The value to check. * @returns True if the value is a finite number, false otherwise. * * @example * isFiniteNumber(42); // true * isFiniteNumber(Infinity); // false * * @category Primitives */ declare const isFiniteNumber: (value: unknown) => value is number; //#endregion //#region src/guards/isFunction.d.ts /** * Checks if the provided value is a function. * * @param value - The value to check. * @returns True if the value is a function, false otherwise. * * @example * isFunction(() => {}); // true * isFunction({}); // false * * @category Primitives */ declare const isFunction: (value: unknown) => value is (...args: unknown[]) => unknown; //#endregion //#region src/guards/isHtmlButtonElement.d.ts /** * Checks if the provided value is an HTMLButtonElement. * * @param value - The value to check. * @returns True if the value is an HTMLButtonElement, false otherwise. * * @example * isHtmlButtonElement(document.createElement('button')); // true * isHtmlButtonElement(document.createElement('div')); // false * * @category DOM */ declare const isHtmlButtonElement: (value: unknown) => value is HTMLButtonElement; //#endregion //#region src/guards/isHtmlElement.d.ts /** * Checks if the provided value is an HTMLElement. * * @param value - The value to check. * @returns True if the value is an HTMLElement, false otherwise. * * @example * isHtmlElement(document.body); // true * isHtmlElement('div'); // false * * @category DOM */ declare const isHtmlElement: (value: unknown) => value is HTMLElement; //#endregion //#region src/guards/isHtmlInputElement.d.ts /** * Checks if the provided value is an HTMLInputElement. * * @param value - The value to check. * @returns True if the value is an HTMLInputElement, false otherwise. * * @example * isHtmlInputElement(document.createElement('input')); // true * isHtmlInputElement(document.createElement('div')); // false * * @category DOM */ declare const isHtmlInputElement: (value: unknown) => value is HTMLInputElement; //#endregion //#region src/guards/isHtmlVideoElement.d.ts /** * Checks if the provided value is an HTMLVideoElement. * * @param value - The value to check. * @returns True if the value is an HTMLVideoElement, false otherwise. * * @example * isHtmlVideoElement(document.createElement('video')); // true * isHtmlVideoElement(document.createElement('div')); // false * * @category DOM */ declare const isHtmlVideoElement: (value: unknown) => value is HTMLVideoElement; //#endregion //#region src/guards/isInteger.d.ts /** * Checks if the provided value is an integer. * * @param value - The value to check. * @returns True if the value is an integer, false otherwise. * * @remarks * Uses `Number.isInteger`, so non-finite values (`NaN`, `Infinity`) * return false. * * @example * isInteger(5); // true * isInteger(5.5); // false * * @category Primitives */ declare const isInteger: (value: unknown) => value is number; //#endregion //#region src/guards/isIterable.d.ts /** * Checks if the provided value implements the iterable protocol. * * @param value - The value to check. * @returns True if the value is iterable, false otherwise. * * @remarks * Strings are iterable and return true. Plain objects without * `Symbol.iterator` return false. * * @example * isIterable([1, 2, 3]); // true * isIterable({}); // false * * @category Primitives */ declare const isIterable: (value: unknown) => value is Iterable; //#endregion //#region src/guards/isMap.d.ts /** * Checks if the provided value is an instance of Map. * * @param value - The value to check. * @returns True if the value is a Map instance, false otherwise. * * @remarks * WeakMap instances return false. * * @example * isMap(new Map()); // true * isMap({}); // false * * @category Primitives */ declare const isMap: (value: unknown) => value is Map; //#endregion //#region src/guards/isMouseEvent.d.ts /** * Checks if the provided value is a MouseEvent. * * @param value - The value to check. * @returns True if the value is a MouseEvent, false otherwise. * * @example * isMouseEvent(new MouseEvent('click')); // true * isMouseEvent(new Event('change')); // false * * @category DOM */ declare const isMouseEvent: (value: unknown) => value is MouseEvent; //#endregion //#region src/guards/isNaN.d.ts /** * Checks if the provided value is NaN (Not a Number). * * @param value - The value to check. * @returns True if the value is NaN, false otherwise. * * @remarks * Uses `Number.isNaN` (not the coercive global `isNaN`), so only the * literal `NaN` value returns true. * * @example * isNaN(Number.NaN); // true * isNaN(0); // false * * @category Primitives */ declare const isNaN: (value: unknown) => value is number; //#endregion //#region src/types/Nil.d.ts /** * Represents a value that is either null or undefined. * * @example * type X = Nil; // null | undefined */ type Nil = null | undefined; //#endregion //#region src/guards/isNil.d.ts /** * Checks if the provided value is null or undefined. * * @param value - The value to check. * @returns True if the value is null or undefined, false otherwise. * * @example * isNil(null); // true * isNil(0); // false * * @category Primitives */ declare const isNil: (value: unknown) => value is Nil; //#endregion //#region src/guards/isNonBlankString.d.ts /** * Checks if the provided value is a non-blank string (not empty and not whitespace-only). * Use {@link isNonEmptyString} when whitespace-only strings are acceptable (e.g. preserving * intentional formatting). * * @param value - The value to check. * @returns True if the value is a string with at least one non-whitespace character, false otherwise. * * @example * isNonBlankString('a'); // true * isNonBlankString(' '); // false * * @category Strings */ declare const isNonBlankString: (value: unknown) => value is string; //#endregion //#region src/types/Nilable.d.ts /** * Represents a value that can be of type `A` or be null/undefined. * * @template A - The type of the value. * * @example * type Maybe = Nilable; // string | null | undefined */ type Nilable = A | Nil; //#endregion //#region src/types/NonEmptyArray.d.ts /** * Represents an array that contains at least one element. * * @template T - The type of the array elements. * * @example * type Ids = NonEmptyArray; // [number, ...number[]] */ type NonEmptyArray = [T, ...T[]]; //#endregion //#region src/guards/isNonEmptyArray.d.ts /** * Checks if the provided value is a non-empty array. * * @param value - The value to check. Can be null or undefined. * @returns True if the value is a non-empty array, false otherwise. * * @example * isNonEmptyArray([1]); // true * isNonEmptyArray([]); // false * * @category Arrays */ declare const isNonEmptyArray: (value: Nilable) => value is NonEmptyArray; //#endregion //#region src/guards/isNonEmptyRecord.d.ts /** * Checks if the provided value is an object with at least one own property. * * @param value - The value to check. * @returns True if the value is a non-empty object, false otherwise. * * @example * isNonEmptyRecord({ a: 1 }); // true * isNonEmptyRecord({}); // false * * @category Records */ declare const isNonEmptyRecord: (value: unknown) => value is Record; //#endregion //#region src/guards/isNonEmptyString.d.ts /** * Checks if the provided value is a non-empty string. Whitespace-only strings like `" "` pass. * Use {@link isNonBlankString} when whitespace-only strings should be rejected (e.g. user input * validation). * * @param value - The value to check. * @returns True if the value is a non-empty string, false otherwise. * * @example * isNonEmptyString('a'); // true * isNonEmptyString(''); // false * * @category Strings */ declare const isNonEmptyString: (value: unknown) => value is string; //#endregion //#region src/guards/isNonNaNNumber.d.ts /** * Checks if the provided value is a number that is not NaN. * * @param value - The value to check. * @returns True if the value is a number and not NaN, false otherwise. * * @example * isNonNaNNumber(42); // true * isNonNaNNumber(Number.NaN); // false * * @category Primitives */ declare const isNonNaNNumber: (value: unknown) => value is number; //#endregion //#region src/guards/isNotArray.d.ts /** * Checks if the provided value is not an array. * * @param value - The value to check. * @returns True if the value is not an array, false otherwise. * * @example * isNotArray('x'); // true * isNotArray([]); // false * * @category Negated */ declare const isNotArray: (value: unknown) => value is Exclude; //#endregion //#region src/guards/isNotBoolean.d.ts /** * Checks if the provided value is not a boolean. * * @param value - The value to check. * @returns True if the value is not a boolean, false otherwise. * * @example * isNotBoolean(1); // true * isNotBoolean(true); // false * * @category Negated */ declare const isNotBoolean: (value: unknown) => value is Exclude; //#endregion //#region src/guards/isNotFunction.d.ts /** * Checks if the provided value is not a function. * * @param value - The value to check. * @returns True if the value is not a function, false otherwise. * * @example * isNotFunction(1); // true * isNotFunction(() => {}); // false * * @category Negated */ declare const isNotFunction: (value: unknown) => value is Exclude unknown>; //#endregion //#region src/guards/isNotNil.d.ts /** * Checks if the provided value is neither null nor undefined. * * @param value - The value to check. * @returns True if the value is not null or undefined, false otherwise. * * @remarks * Common in `.filter(isNotNil)` to drop `null`/`undefined` from arrays * with narrowing. * * @example * isNotNil(0); // true * isNotNil(null); // false * * const items: (string | null)[] = ['a', null, 'b']; * const clean: string[] = items.filter(isNotNil); // ['a', 'b'] * * @category Negated */ declare const isNotNil: (value: Nil | T) => value is T; //#endregion //#region src/guards/isNotNull.d.ts /** * Checks if the provided value is not null. * * @param value - The value to check. * @returns True if the value is not null, false otherwise. * * @example * isNotNull(undefined); // true * isNotNull(null); // false * * @category Negated */ declare const isNotNull: (value: unknown) => value is Exclude; //#endregion //#region src/guards/isNotNumber.d.ts /** * Checks if the provided value is not a number. * * @param value - The value to check. * @returns True if the value is not a number, false otherwise. * * @example * isNotNumber('1'); // true * isNotNumber(1); // false * * @category Negated */ declare const isNotNumber: (value: unknown) => value is Exclude; //#endregion //#region src/guards/isNotRecord.d.ts /** * Checks if the provided value is not an object. * * @param value - The value to check. * @returns True if the value is not a record (object), false otherwise. * * @example * isNotRecord([]); // true * isNotRecord({}); // false * * @category Negated */ declare const isNotRecord: (value: unknown) => value is Exclude>; //#endregion //#region src/guards/isNotString.d.ts /** * Checks if the provided value is not a string. * * @param value - The value to check. * @returns True if the value is not a string, false otherwise. * * @example * isNotString(1); // true * isNotString('a'); // false * * @category Negated */ declare const isNotString: (value: unknown) => value is Exclude; //#endregion //#region src/types/Undefinable.d.ts /** * Represents a value that can be of type `A` or `undefined`. * * @template A - The type of the value. * * @example * type X = Undefinable; // string | undefined */ type Undefinable = A | undefined; //#endregion //#region src/guards/isNotUndefined.d.ts /** * Checks if the provided value is not undefined. * * @param value - The value to check. * @returns True if the value is not undefined, false otherwise. * * @example * isNotUndefined(null); // true * isNotUndefined(undefined); // false * * @category Negated */ declare const isNotUndefined: (value: Undefinable) => value is Exclude; //#endregion //#region src/guards/isNotVoid.d.ts /** * Checks if the provided value is not void. * * @param value - The value to check. * @returns True if the value is not void (defined), false otherwise. * * @example * isNotVoid(0); // true * isNotVoid(undefined); // false * * @category Negated */ declare const isNotVoid: (value: unknown) => value is Exclude; //#endregion //#region src/guards/isNull.d.ts /** * Checks if the provided value is null. * * @param value - The value to check. * @returns True if the value is null, false otherwise. * * @example * isNull(null); // true * isNull(undefined); // false * * @category Primitives */ declare const isNull: (value: unknown) => value is null; //#endregion //#region src/guards/isNumber.d.ts /** * Checks if the provided value is a number. * * @param value - The value to check. * @returns True if the value is a number, false otherwise. * * @remarks * `NaN` is a `number`, so `isNumber(NaN)` is true. Use `isInteger` or * combine with `!isNaN(value)` if you need a finite number. * * @example * isNumber(1); // true * isNumber('1'); // false * * @category Primitives */ declare const isNumber: (value: unknown) => value is number; //#endregion //#region src/guards/isPlainObject.d.ts /** * Checks if the provided value is a plain object created with `{}` or `Object.create(null)`. * Returns false for arrays, `Date`, `Map`, `RegExp`, boxed primitives, and class instances. * * @param value - The value to check. * @returns True if the value is a plain object, false otherwise. * * @example * isPlainObject({}); // true * isPlainObject(new Date()); // false * * @category Records */ declare const isPlainObject: (value: unknown) => value is Record; //#endregion //#region src/guards/isPromise.d.ts /** * Checks if the provided value is a Promise, including promise-like objects * that implement `then`, `catch`, and `finally`. * * @param value - The value to check. * @returns True if the value is a Promise or promise-like object, false otherwise. * * @remarks * The full `Promise` method surface is required so the narrowed type is * accurate: `then`, `catch`, and `finally` must all be functions. Thenables * that only implement a subset are rejected. * * @example * isPromise(Promise.resolve()); // true * isPromise({ then: () => 1 }); // false * * @category Primitives */ declare const isPromise: (value: unknown) => value is Promise; //#endregion //#region src/guards/isRecord.d.ts /** * Checks if the provided value is a non-null object that is not an array. * * @param value - The value to check. * @returns True if the value is an object (but not an array), false otherwise. * * @example * isRecord({}); // true * isRecord([]); // false * * @category Records */ declare const isRecord: (value: unknown) => value is Record; //#endregion //#region src/guards/isRegExp.d.ts /** * Checks if the provided value is an instance of RegExp. * * @param value - The value to check. * @returns True if the value is a RegExp instance, false otherwise. * * @example * isRegExp(/abc/); // true * isRegExp('/abc/'); // false * * @category Primitives */ declare const isRegExp: (value: unknown) => value is RegExp; //#endregion //#region src/guards/isSet.d.ts /** * Checks if the provided value is an instance of Set. * * @param value - The value to check. * @returns True if the value is a Set instance, false otherwise. * * @remarks * WeakSet instances return false. * * @example * isSet(new Set()); // true * isSet([]); // false * * @category Primitives */ declare const isSet: (value: unknown) => value is Set; //#endregion //#region src/guards/isString.d.ts /** * Checks if the provided value is a string. * * @param value - The value to check. * @returns True if the value is a string, false otherwise. * * @example * isString('hi'); // true * isString(42); // false * * @category Primitives */ declare const isString: (value: unknown) => value is string; //#endregion //#region src/guards/isSvgElement.d.ts /** * Checks if the provided value is an SVGElement. * * @param value - The value to check. * @returns True if the value is an SVGElement, false otherwise. * * @example * isSvgElement(document.createElementNS('http://www.w3.org/2000/svg', 'svg')); // true * isSvgElement(document.createElement('div')); // false * * @category DOM */ declare const isSvgElement: (value: unknown) => value is SVGElement; //#endregion //#region src/guards/isSymbol.d.ts /** * Checks if the provided value is a symbol. * * @param value - The value to check. * @returns True if the value is a symbol, false otherwise. * * @example * isSymbol(Symbol('a')); // true * isSymbol('symbol'); // false * * @category Primitives */ declare const isSymbol: (value: unknown) => value is symbol; //#endregion //#region src/guards/isTextNode.d.ts /** * Checks if the provided value is a Text node. * * @param value - The value to check. * @returns True if the value is a Text node, false otherwise. * * @example * isTextNode(document.createTextNode('hi')); // true * isTextNode(document.createElement('div')); // false * * @category DOM */ declare const isTextNode: (value: unknown) => value is Text; //#endregion //#region src/guards/isTruthy.d.ts /** * Checks if the provided value is truthy. * * @param value - The value to check. * @returns True if the value is truthy, false otherwise. * * @remarks * The complement of `isFalsy`. Does not provide narrowing on its own; * use `isNotNil` or a specific positive guard when narrowing matters. * * @example * isTruthy(1); // true * isTruthy(0); // false * * @category Truthy / falsy */ declare const isTruthy: (value: unknown) => boolean; //#endregion //#region src/guards/isUndefined.d.ts /** * Checks if the provided value is undefined. * * @param value - The value to check. * @returns True if the value is undefined, false otherwise. * * @example * isUndefined(undefined); // true * isUndefined(null); // false * * @category Primitives */ declare const isUndefined: (value: unknown) => value is undefined; //#endregion //#region src/guards/isVoid.d.ts /** * Checks if the provided value is void. * * @param value - The value to check. * @returns True if the value is void (undefined), false otherwise. * * @example * isVoid(undefined); // true * isVoid(0); // false * * @category Primitives */ declare const isVoid: (value: unknown) => value is void; //#endregion //#region src/guards/isWeakMap.d.ts /** * Checks if the provided value is an instance of WeakMap. * * @param value - The value to check. * @returns True if the value is a WeakMap instance, false otherwise. * * @remarks * Map instances return false. Narrows to `WeakMap`, since * weak collections accept non-registered symbols as keys (ES2023). * * @example * isWeakMap(new WeakMap()); // true * isWeakMap(new Map()); // false * * @category Primitives */ declare const isWeakMap: (value: unknown) => value is WeakMap; //#endregion //#region src/guards/isWeakSet.d.ts /** * Checks if the provided value is an instance of WeakSet. * * @param value - The value to check. * @returns True if the value is a WeakSet instance, false otherwise. * * @remarks * Set instances return false. Narrows to `WeakSet`, since weak * collections accept non-registered symbols as members (ES2023). * * @example * isWeakSet(new WeakSet()); // true * isWeakSet(new Set()); // false * * @category Primitives */ declare const isWeakSet: (value: unknown) => value is WeakSet; //#endregion //#region src/guards/readonlyArrayIncludes.d.ts /** * Checks if a readonly array includes the given element, with type narrowing. * * @param arr - The readonly array to search. * @param elem - The element to search for. * @returns True if the array includes the element, false otherwise. * * @example * const arr = ['a', 'b'] as const; * readonlyArrayIncludes(arr, 'a'); // true * readonlyArrayIncludes(arr, 'z'); // false * * @category Arrays */ declare const readonlyArrayIncludes: (arr: readonly T[], elem: unknown) => elem is T; //#endregion //#region src/types/Arrayable.d.ts /** * Represents a value that can be of type `T` or an array of `T`. * * @template T - The type of the value. * * @example * type Tags = Arrayable; // string | string[] */ type Arrayable = T | T[]; //#endregion //#region src/types/NestedNonNullable.d.ts /** * Retrieves the type of a deeply nested property from an object while removing null and undefined. * * @template T - The object type. * @template P - The path to the nested property as a string literal. * * @remarks * This type recursively traverses the object along the given path and applies `NonNullable` to the resulting type. * It may fail for excessively deep property paths or in the presence of circular references. In such cases, consider * using nested `NonNullable` definitions to avoid errors such as: * - TS2589: Type instantiation is excessively deep and possibly infinite. * - TS2615: Type of property 'XYZ' circularly references itself in mapped type. * * @example * type User = { profile?: { name?: string } }; * type Name = NestedNonNullable; // string */ type NestedNonNullable & string> = NonNullable>; //#endregion //#region src/types/NilableArray.d.ts /** * Represents an array that can be null or undefined, and its elements can also be null or undefined. * * @template T - The type of the non-null/undefined elements in the array. * * @example * type Items = NilableArray; // (string | null | undefined)[] | null | undefined */ type NilableArray = Nilable[]>; //#endregion //#region src/types/NotNilable.d.ts /** * Represents a value of type `A` that is guaranteed to be neither null nor undefined. * * @template A - The type to be filtered. * * @example * type X = NotNilable; // string */ type NotNilable = Exclude; //#endregion //#region src/types/Nullable.d.ts /** * Represents a value that can be of type `A` or `null`. * * @template A - The type of the value. * * @example * type X = Nullable; // string | null */ type Nullable = A | null; //#endregion //#region src/types/NullableProperties.d.ts /** * Makes every property of a record nullable. * * @template T - The record type. * * @example * type User = { name: string; age: number }; * type X = NullableProperties; // { name: string | null; age: number | null } */ type NullableProperties = { [Key in keyof T]: Nullable; }; //#endregion //#region src/types/Truthy.d.ts /** * Represents a value that is truthy. * * @template T - The type of the value. * * @example * type X = Truthy; // string */ type Truthy = Exclude; //#endregion //#region src/utilities/buildTimeDuration.d.ts type TimeDuration = { seconds: number; minutes: number; hours: number; }; /** * Returns an object representing a duration in seconds, minutes and hours. * * @param numberOfMilliseconds - The duration in milliseconds. * @returns The duration split into hours, minutes and seconds. * * @example * buildTimeDuration(3723000); // { hours: 1, minutes: 2, seconds: 3 } */ declare const buildTimeDuration: (numberOfMilliseconds: number) => TimeDuration; //#endregion //#region src/utilities/coerceToBoolean.d.ts /** * Converts the boolean string values 'true' and 'false' into the * corresponding boolean. Any other value is coerced with `Boolean()`. * * @param value - The value to coerce. * @returns The value as a boolean. * * @example * coerceToBoolean('true'); // true * coerceToBoolean('false'); // false * coerceToBoolean(0); // false */ declare const coerceToBoolean: (value: unknown) => boolean; //#endregion //#region src/utilities/dateOnlyString.d.ts type DateOnlyStringOptions = { timeZone?: string; /** * When set to true, the returned string will omit the year. * e.g. "Jun 3" instead of "Jun 3, 2021" */ omitYear?: boolean; }; /** * Converts a Date object into a date only string, e.g. 'Jun 3, 2021', * or 'Jun 3' if omitYear is true. Formats with the en-US locale. * * @param date - The Date to format; gracefully handles any value. * @param options - Formatting options. * @param options.timeZone - The time zone to display the date in. Defaults to the current time zone. * @param options.omitYear - If true, display the date without the year. * @returns The formatted date string, or '' for invalid input. * * @example * dateOnlyString(new Date(2011, 11, 15)); // 'Dec 15, 2011' */ declare const dateOnlyString: (date: unknown, { timeZone, omitYear }?: DateOnlyStringOptions) => string; //#endregion //#region src/utilities/dateOnlyISOString.d.ts /** * Converts a Date object into a date only string formatted to ISO 8601, * e.g. '2021-06-03'. * * @param date - The Date to format; gracefully handles any value. * @param options - Formatting options. * @param options.timeZone - The time zone to display the date in. Defaults to the current time zone. * @returns The formatted date string, or '' for invalid input. * * @example * dateOnlyISOString(new Date(2011, 11, 15)); // '2011-12-15' */ declare const dateOnlyISOString: (date: unknown, { timeZone }?: DateOnlyStringOptions) => string; //#endregion //#region src/utilities/dateOnlyStringForSentence.d.ts /** * Converts a Date object into a date only string for use in a sentence, * e.g. 'June 3, 2021'. Formats with the en-US locale. * * @param date - The Date to format; gracefully handles any value. * @param options - Formatting options. * @param options.timeZone - The time zone to display the date in. Defaults to the current time zone. * @returns The formatted date string, or '' for invalid input. * * @example * dateOnlyStringForSentence(new Date(2011, 11, 15)); // 'December 15, 2011' */ declare const dateOnlyStringForSentence: (date: unknown, { timeZone }?: DateOnlyStringOptions) => string; //#endregion //#region src/utilities/dateOnlyStringNumeric.d.ts /** * Converts a Date object into a date only string formatted numerically, * e.g. '06/03/2021'. Formats with the en-US locale. * * @param date - The Date to format; gracefully handles any value. * @param options - Formatting options. * @param options.timeZone - The time zone to display the date in. Defaults to the current time zone. * @returns The formatted date string, or '' for invalid input. * * @example * dateOnlyStringNumeric(new Date(2011, 11, 15)); // '12/15/2011' */ declare const dateOnlyStringNumeric: (date: unknown, { timeZone }?: DateOnlyStringOptions) => string; //#endregion //#region src/utilities/dateTimeRounded.d.ts type DateTimeRoundedOverload = { (dateTime: Date, toISOString?: true): string | null; (dateTime: Date, toISOString: false): Date | null; }; /** * Rounds a Date up to the next half hour boundary. * * @param dateTime - The Date to round. * @param toISOString - Whether to return an ISO-8601 string instead of a Date. * @returns The rounded value as a string or Date depending on toISOString. * * @example * dateTimeRounded(new Date(2015, 10, 7, 0, 10)); // '2015-11-07T00:30:00.000Z' (in UTC) * dateTimeRounded(new Date(2015, 10, 7, 0, 40), false); // new Date(2015, 10, 7, 1, 0) */ declare const dateTimeRounded: DateTimeRoundedOverload; //#endregion //#region src/utilities/dateTimeString.d.ts /** * Converts a Date, timestamp, or date string into a date and time string, * e.g. 'Jun 3, 2021, 11:52 AM'. Formats with the en-US locale. * * NOTE: you should probably use timeAgoString when trying to display * an updated/created timestamp. * * @param date - The Date, timestamp, or date string to format; gracefully handles any value. * @param options - Formatting options. * @param options.timeZone - The time zone to display the date in. Defaults to the current time zone. * @param options.omitYear - If true, display the date without the year. * @returns The formatted date string, or '' for invalid input. * * @example * dateTimeString(new Date(2011, 11, 15, 7, 30)); // 'Dec 15, 2011, 7:30 AM' */ declare const dateTimeString: (date: Date | number | string | null | undefined, { timeZone, omitYear }?: DateOnlyStringOptions) => string; //#endregion //#region src/utilities/dateTimeStringForSentence.d.ts /** * Converts a Date object into a date and time string for use in a sentence, * e.g. 'June 3, 2021, 11:52 AM'. Formats with the en-US locale. * * NOTE: you should probably use timeAgoString when trying to display * an updated/created timestamp. * * @param date - The Date to format; gracefully handles any value. * @param options - Formatting options. * @param options.timeZone - The time zone to display the date in. Defaults to the current time zone. * @returns The formatted date string, or '' for invalid input. * * @example * dateTimeStringForSentence(new Date(2011, 11, 15, 7, 30)); // 'December 15, 2011, 7:30 AM' */ declare const dateTimeStringForSentence: (date: unknown, { timeZone }?: DateOnlyStringOptions) => string; //#endregion //#region src/utilities/dateToDateTime.d.ts type WistiaDateTimeObject = { minutes: number; hours: number; dayOfMonth: number; year: number; month: number; }; /** * Converts a Date object into a plain object of its local date and time parts. * * @param date - The Date object to convert. * @returns The date parts, or null if the value is not a Date. * * @example * dateToDateTime(new Date(2011, 11, 15, 3, 10)); * // { year: 2011, month: 11, dayOfMonth: 15, hours: 3, minutes: 10 } */ declare const dateToDateTime: (date: Date | null | undefined) => WistiaDateTimeObject | null; //#endregion //#region src/utilities/dateTimeToDate.d.ts /** * Converts a plain object of date and time parts into a Date object. * * @param dateTime - The date parts to convert. * @returns The converted Date, or null if year, month, or dayOfMonth is missing. * * @example * dateTimeToDate({ year: 2015, month: 10, dayOfMonth: 7, hours: 4, minutes: 15 }); * // new Date(2015, 10, 7, 4, 15) */ declare const dateTimeToDate: (dateTime: Partial | null | undefined) => Date | null; //#endregion //#region src/utilities/dateTimeToISO.d.ts /** * Converts a plain object of date and time parts into an ISO-8601 string. * * @param dateTime - The date parts to convert. * @returns The ISO-8601 string, or null if year, month, or dayOfMonth is missing. * * @example * dateTimeToISO({ year: 2015, month: 10, dayOfMonth: 7, hours: 4, minutes: 15 }); * // '2015-11-07T04:15:00.000Z' (in UTC) */ declare const dateTimeToISO: (dateTime: Partial) => string | null; //#endregion //#region src/utilities/dateUTCOffset.d.ts /** * Given a date, shows the UTC offset of the current time zone, e.g. '+02:00'. * * @param date - The Date to calculate the offset for. * @returns The UTC offset string. * * @example * dateUTCOffset(new Date(2011, 11, 15)); // '+00:00' (when run in UTC) */ declare const dateUTCOffset: (date: Date) => string; //#endregion //#region src/utilities/dayOfWeekString.d.ts /** * Converts a Date object into a day of the week string, e.g. 'Thursday'. * Formats with the en-US locale. * * @param date - The Date to format. * @param options - Formatting options. * @param options.timeZone - The time zone to display the date in. Defaults to the current time zone. * @returns The formatted day of the week, or '' for null or invalid input. * * @example * dayOfWeekString(new Date(2011, 11, 15)); // 'Thursday' */ declare const dayOfWeekString: (date: Date | null, { timeZone }?: DateOnlyStringOptions) => string; //#endregion //#region src/utilities/deepMerge.d.ts type AllKeys = T extends unknown ? Extract : never; type IndexValue = T extends unknown ? K extends keyof T ? T[K] : never : never; type MergeableFunction = (...args: never[]) => unknown; type OverwrittenValues = string | number | boolean | bigint | symbol | Date | RegExp | Map | Set | Error | Promise | MergeableFunction; type DeepMerged = [T] extends [unknown[]] ? { [K in keyof T]: DeepMerged; } : [T] extends [OverwrittenValues] ? T : [T] extends [object] ? { [K in AllKeys]: DeepMerged>; } : T; type DeepMergeResult[]> = [T[number]] extends [never] ? Record : DeepMerged; /** * Deeply merges objects without mutating them, inferring the return type from * the inputs. Plain objects are merged recursively, arrays are concatenated * with duplicate items removed (by reference for object items), and all other * values (including class instances) are overwritten in the order of the * provided arguments. The prototype-polluting keys `__proto__`, `constructor`, * and `prototype` are dropped. Symbol-keyed properties are not merged. * * @param objects - The objects to merge. * @returns A new object containing the merged result. * @throws TypeError when an argument is an array. * * @example * deepMerge({ a: { b: 1 }, c: [1] }, { a: { d: 2 }, c: [2] }); * // { a: { b: 1, d: 2 }, c: [1, 2] } */ declare const deepMerge: []>(...objects: T) => DeepMergeResult; //#endregion //#region src/utilities/getObjectEntries.d.ts /** * Returns the entries of an object with strongly typed keys and values. * * @param obj - The object to get entries from. * @returns An array of [key, value] tuples. * * @example * getObjectEntries({ a: 1, b: 2 }); // [['a', 1], ['b', 2]] */ declare const getObjectEntries: >(obj: T) => [keyof T, T[keyof T]][]; //#endregion //#region src/utilities/getObjectKeys.d.ts /** * Returns the keys of an object with strongly typed key type. * * @param obj - The object to get keys from. * @returns An array of the object's keys. * * @example * getObjectKeys({ a: 1, b: 2 }); // ['a', 'b'] */ declare const getObjectKeys: >(obj: T) => (keyof T)[]; //#endregion //#region src/utilities/getObjectValues.d.ts /** * Returns the values of an object with strongly typed value type. * * @param obj - The object to get values from. * @returns An array of the object's values. * * @example * getObjectValues({ a: 1, b: 2 }); // [1, 2] */ declare const getObjectValues: >(obj: T) => T[keyof T][]; //#endregion //#region src/utilities/isUrl.d.ts /** * Loosely validates a URL string. * * @param value - The value to validate. * @returns True if the value appears to be a URL, false otherwise. * * @example * isUrl('https://wistia.com'); // true * isUrl('not a url'); // false */ declare const isUrl: (value: unknown) => boolean; //#endregion //#region src/utilities/mediaDurationString.d.ts /** * A string representation of a duration for a media. Assumes most medias * are under an hour so only shows hours if media is over an hour. * * @param numberOfMilliseconds - The duration in milliseconds. * @returns The formatted duration string. * * @example * mediaDurationString(234230); // '3:54' * mediaDurationString(23423000); // '6:30:23' */ declare const mediaDurationString: (numberOfMilliseconds: number) => string; //#endregion //#region src/utilities/millisecondsToDurationISOString.d.ts /** * Given a number of milliseconds, returns the ISO 8601 duration string * rounded down from the number of seconds. * * @param numberOfMilliseconds - The duration in milliseconds. * @returns The ISO 8601 duration string. * * @example * millisecondsToDurationISOString(33000); // 'PT33S' * millisecondsToDurationISOString(3605000); // 'PT1H5S' */ declare const millisecondsToDurationISOString: (numberOfMilliseconds: number) => string; //#endregion //#region src/utilities/monthDayStringNumeric.d.ts /** * Converts a Date object into a month and day string formatted numerically, * e.g. '06/03'. Formats with the en-US locale. * * @param date - The Date to format; gracefully handles any value. * @param options - Formatting options. * @param options.timeZone - The time zone to display the date in. Defaults to the current time zone. * @returns The formatted date string, or '' for invalid input. * * @example * monthDayStringNumeric(new Date(2011, 11, 15)); // '12/15' */ declare const monthDayStringNumeric: (date: unknown, { timeZone }?: DateOnlyStringOptions) => string; //#endregion //#region src/utilities/parseDateString.d.ts /** * Loosely parses a human-entered date string into a Date at local midnight. * Accepts 'today' and 'tomorrow', month name prefixes (resolved to the next * 1st of that month), and common numeric and month-name formats, with a * native Date fallback for anything else. * * @param str - The date string to parse. * @returns The parsed Date at local midnight, or null if unparseable. * * @example * parseDateString('Jan 5, 2025'); // Date for 2025-01-05 at local midnight * parseDateString('garbage'); // null */ declare const parseDateString: (str: string) => Date | null; //#endregion //#region src/utilities/sessionDurationString.d.ts /** * A string representation of a duration for a user session. Assumes that * sessions may or may not be more than an hour. To prevent confusion all * times show hours, even those that are less than an hour. * * @param numberOfMilliseconds - The duration in milliseconds. * @returns The formatted duration string. * * @example * sessionDurationString(2342300); // '0:39:02' */ declare const sessionDurationString: (numberOfMilliseconds: number) => string; //#endregion //#region src/utilities/stripExtension.d.ts /** * Removes the file extension from a string. * * @param str - The string to remove the file extension from. * @returns The string without its file extension. * * @example * stripExtension('config.yml'); // 'config' * stripExtension('example.test.ts'); // 'example.test' */ declare const stripExtension: (str: string) => string; //#endregion //#region src/utilities/timeAgoString.d.ts type TimeAgoOptions = { nowAnchor?: Date; includeTime?: boolean; }; /** * Shows time ago relative to current time, e.g. '< 1 minute ago', * '33 minutes ago', 'Today, 3:30 PM', 'Yesterday, 6:22 AM', * 'Nov 11, 11:32 AM', or 'Feb 23, 2020, 1:55 PM'. When includeTime is * false: 'Today', 'Yesterday', 'on Thursday', 'Nov 11', 'Feb 23, 2020'. * * NOTE: timeAgoString doesn't support multiple time zones since doing so * would complicate calculations for whether to use "Today" or "Yesterday". * * @param date - The date relative to now. * @param options - Formatting options. * @param options.nowAnchor - The date used to calculate relative to now. Defaults to the current date but can be overwritten for tests. * @param options.includeTime - Whether to include the time in the output. Defaults to true. * @returns The relative date string, or '' for invalid input. * * @example * timeAgoString(new Date(Date.now() - 30_000)); // '< 1 minute ago' */ declare const timeAgoString: (date: Date, { nowAnchor, includeTime }?: TimeAgoOptions) => string; //#endregion //#region src/utilities/timeOnlyString.d.ts /** * Converts a Date object into a time only string, e.g. '7:30 AM'. * Formats with the en-US locale. * * @param date - The Date to format; gracefully handles any value. * @param options - Formatting options. * @param options.timeZone - The time zone to display the time in. Defaults to the current time zone. * @returns The formatted time string, or '' for invalid input. * * @example * timeOnlyString(new Date(2011, 11, 15, 7, 30)); // '7:30 AM' */ declare const timeOnlyString: (date: unknown, { timeZone }?: DateOnlyStringOptions) => string; //#endregion //#region src/utilities/tupleIncludes.d.ts /** * Checks if a tuple includes the given item, with type narrowing. * * @param tuple - The tuple to search. * @param item - The item to search for. * @returns True if the tuple includes the item, false otherwise. * * @example * const tuple = ['x', 'y'] as const; * tupleIncludes(tuple, 'x'); // true * tupleIncludes(tuple, 'z'); // false */ declare const tupleIncludes: (tuple: TTuple, item: TItem) => item is TTuple[number]; //#endregion export { type Arrayable, type DateOnlyStringOptions, type DateTimeRoundedOverload, type DeepMerged, type Falsy, type NestedNonNullable, type Nil, type Nilable, type NilableArray, type NonEmptyArray, type NotNilable, type Nullable, type NullableProperties, type TimeAgoOptions, type TimeDuration, type Truthy, type Undefinable, type WistiaDateTimeObject, buildTimeDuration, coerceToBoolean, dateOnlyISOString, dateOnlyString, dateOnlyStringForSentence, dateOnlyStringNumeric, dateTimeRounded, dateTimeString, dateTimeStringForSentence, dateTimeToDate, dateTimeToISO, dateToDateTime, dateUTCOffset, dayOfWeekString, deepMerge, getObjectEntries, getObjectKeys, getObjectValues, hasKey, isArray, isAsyncFunction, isBigInt, isBoolean, isDate, isEmptyArray, isEmptyRecord, isEmptyString, isError, isFalsy, isFiniteNumber, isFunction, isHtmlButtonElement, isHtmlElement, isHtmlInputElement, isHtmlVideoElement, isInteger, isIterable, isMap, isMouseEvent, isNaN, isNil, isNonBlankString, isNonEmptyArray, isNonEmptyRecord, isNonEmptyString, isNonNaNNumber, isNotArray, isNotBoolean, isNotFunction, isNotNil, isNotNull, isNotNumber, isNotRecord, isNotString, isNotUndefined, isNotVoid, isNull, isNumber, isPlainObject, isPromise, isRecord, isRegExp, isSet, isString, isSvgElement, isSymbol, isTextNode, isTruthy, isUndefined, isUrl, isVoid, isWeakMap, isWeakSet, mediaDurationString, millisecondsToDurationISOString, monthDayStringNumeric, parseDateString, readonlyArrayIncludes, sessionDurationString, stripExtension, timeAgoString, timeOnlyString, tupleIncludes }; //# sourceMappingURL=index.d.mts.map