# @wistia/type-guards

> Runtime type guards, utility types, and utility functions for TypeScript. Every guard is a `value is T` predicate that narrows `unknown` values; every type is a small composable building block; utilities are general-purpose helper functions.

## Install

```sh
npm install @wistia/type-guards
yarn add @wistia/type-guards
pnpm add @wistia/type-guards
```

## Import

```ts
import { isString, isNotNil, type Nilable } from '@wistia/type-guards';
```

## Guards

<!-- AUTOGEN:LLMS-GUARDS:START -->
Primitives:

- `isAsyncFunction(value)` — `value is (...args: unknown[]) => Promise<unknown>`
- `isBigInt(value)` — `value is bigint`
- `isBoolean(value)` — `value is boolean`
- `isDate(value)` — `value is Date`
- `isError(value)` — `value is Error`
- `isFiniteNumber(value)` — `value is number`
- `isFunction(value)` — `value is (...args: unknown[]) => unknown`
- `isInteger(value)` — `value is number`
- `isIterable(value)` — `value is Iterable<unknown>`
- `isMap(value)` — `value is Map<unknown, unknown>`
- `isNaN(value)` — `value is number`
- `isNil(value)` — `value is Nil`
- `isNonNaNNumber(value)` — `value is number`
- `isNull(value)` — `value is null`
- `isNumber(value)` — `value is number`
- `isPromise(value)` — `value is Promise<unknown>`
- `isRegExp(value)` — `value is RegExp`
- `isSet(value)` — `value is Set<unknown>`
- `isString(value)` — `value is string`
- `isSymbol(value)` — `value is symbol`
- `isUndefined(value)` — `value is undefined`
- `isVoid(value)` — `value is void`
- `isWeakMap(value)` — `value is WeakMap<WeakKey, unknown>`
- `isWeakSet(value)` — `value is WeakSet<WeakKey>`

Arrays:

- `isArray(value)` — `value is unknown[]`
- `isEmptyArray(value)` — `value is never[]`
- `isNonEmptyArray(value)` — `value is NonEmptyArray<T>`
- `readonlyArrayIncludes(arr, elem)` — `value is T`

Records (plain objects, not arrays):

- `hasKey(value, key)` — `value is Record<Key, Value>`
- `isEmptyRecord(value)` — `value is EmptyObject`
- `isNonEmptyRecord(value)` — `value is Record<string, unknown>`
- `isPlainObject(value)` — `value is Record<string, unknown>`
- `isRecord(value)` — `value is Record<string, unknown>`

Strings:

- `isEmptyString(value)` — `value is ''`
- `isNonBlankString(value)` — `value is string`
- `isNonEmptyString(value)` — `value is string`

Truthy / falsy:

- `isFalsy(value)` — `value is Falsy`
- `isTruthy(value)` — returns `boolean`

Negated:

- `isNotArray(value)` — `value is Exclude<unknown, unknown[]>`
- `isNotBoolean(value)` — `value is Exclude<unknown, boolean>`
- `isNotFunction(value)` — `value is Exclude<unknown, (...args: unknown[]) => unknown>`
- `isNotNil(value)` — `value is T`
- `isNotNull(value)` — `value is Exclude<T, null>`
- `isNotNumber(value)` — `value is Exclude<unknown, number>`
- `isNotRecord(value)` — `value is Exclude<unknown, Record<string, unknown>>`
- `isNotString(value)` — `value is Exclude<unknown, string>`
- `isNotUndefined(value)` — `value is Exclude<T, undefined>`
- `isNotVoid(value)` — `value is Exclude<unknown, void>`

DOM:

- `isHtmlButtonElement(value)` — `value is HTMLButtonElement`
- `isHtmlElement(value)` — `value is HTMLElement`
- `isHtmlInputElement(value)` — `value is HTMLInputElement`
- `isHtmlVideoElement(value)` — `value is HTMLVideoElement`
- `isMouseEvent(value)` — `value is MouseEvent`
- `isSvgElement(value)` — `value is SVGElement`
- `isTextNode(value)` — `value is Text`
<!-- AUTOGEN:LLMS-GUARDS:END -->

## Types

<!-- AUTOGEN:LLMS-TYPES:START -->
- `Arrayable<T>` — `T | T[]`
- `Falsy` — `typeof Number.NaN | '' | 0n | false | null | undefined`
- `NestedNonNullable<T, P extends Paths<T> & string>` — `NonNullable<Get<T, P>>`
- `Nil` — `null | undefined`
- `Nilable<A>` — `A | Nil`
- `NilableArray<T>` — `Nilable<Nilable<T>[]>`
- `NonEmptyArray<T>` — `[T, ...T[]]`
- `NotNilable<A>` — `Exclude<A, Nil>`
- `Nullable<A>` — `A | null`
- `NullableProperties<T extends UnknownRecord>` — `{ [Key in keyof T]: Nullable<T[Key]> }`
- `Truthy<T>` — `Exclude<T, Falsy>`
- `Undefinable<A>` — `A | undefined`
<!-- AUTOGEN:LLMS-TYPES:END -->

## Utilities

<!-- AUTOGEN:LLMS-UTILITIES:START -->
- `buildTimeDuration(numberOfMilliseconds)` — returns `TimeDuration`
- `coerceToBoolean(value)` — returns `boolean`
- `dateOnlyISOString(date, { timeZone = defaultTimeZone })` — returns `string`
- `dateOnlyString(date, { timeZone = defaultTimeZone, omitYear = false })` — returns `string`
- `dateOnlyStringForSentence(date, { timeZone = defaultTimeZone })` — returns `string`
- `dateOnlyStringNumeric(date, { timeZone = defaultTimeZone })` — returns `string`
- `dateTimeRounded(dateTime, toISOString = true)` — returns `string | Date | null`
- `dateTimeString(date, { timeZone = defaultTimeZone, omitYear = false })` — returns `string`
- `dateTimeStringForSentence(date, { timeZone = defaultTimeZone })` — returns `string`
- `dateTimeToDate(dateTime)` — returns `Date | null`
- `dateTimeToISO(dateTime)` — returns `string | null`
- `dateToDateTime(date)` — returns `WistiaDateTimeObject | null`
- `dateUTCOffset(date)` — returns `string`
- `dayOfWeekString(date, { timeZone = defaultTimeZone })` — returns `string`
- `deepMerge(...objects)` — returns `DeepMergeResult<T>`
- `getObjectEntries(obj)` — returns `[keyof T, T[keyof T]][]`
- `getObjectKeys(obj)` — returns `(keyof T)[]`
- `getObjectValues(obj)` — returns `T[keyof T][]`
- `isUrl(value)` — returns `boolean`
- `mediaDurationString(numberOfMilliseconds)` — returns `string`
- `millisecondsToDurationISOString(numberOfMilliseconds)` — returns `string`
- `monthDayStringNumeric(date, { timeZone = defaultTimeZone })` — returns `string`
- `parseDateString(str)` — returns `Date | null`
- `sessionDurationString(numberOfMilliseconds)` — returns `string`
- `stripExtension(str)` — returns `string`
- `timeAgoString(date, { nowAnchor = new Date(), includeTime = true })` — returns `string`
- `timeOnlyString(date, { timeZone = defaultTimeZone })` — returns `string`
- `tupleIncludes(tuple, item)` — returns `item is TTuple[number]`
<!-- AUTOGEN:LLMS-UTILITIES:END -->

## See also

- `llms-full.txt` — every export with signature and example, in a single document
- `README.md` — human-readable docs
- `dist/index.d.mts` — typed entry point with full TSDoc on every export