@wistia/utils 0.0.0-stage → 1.0.0

package/llms-full.txt

@@ -0,0 +1,1195 @@
+# @wistia/utils — full reference
+
+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. Side-effect free, tree-shakeable, ESM
+and CJS builds.
+
+## Install
+
+```sh
+npm install @wistia/utils
+yarn add @wistia/utils
+pnpm add @wistia/utils
+```
+
+## Import
+
+```ts
+import {
+  isString,
+  isNotNil,
+  isNonEmptyArray,
+  type Nilable,
+  type NonEmptyArray,
+} from '@wistia/utils';
+```
+
+## Guards
+
+<!-- AUTOGEN:LLMS-FULL-GUARDS:START -->
+### `hasKey`
+
+```ts
+hasKey<Key extends string, Value>(value: unknown, key: Key): value is Record<Key, Value>
+```
+
+```ts
+hasKey({ a: 1 }, 'a'); // true
+hasKey({ a: 1 }, 'b'); // false
+```
+
+### `isArray`
+
+```ts
+isArray(value: unknown): value is unknown[]
+```
+
+```ts
+isArray([1, 2]); // true
+isArray('abc');  // false
+```
+
+### `isAsyncFunction`
+
+```ts
+isAsyncFunction(value: unknown): value is (...args: unknown[]) => Promise<unknown>
+```
+
+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.
+
+```ts
+isAsyncFunction(async () => {}); // true
+isAsyncFunction(() => {});       // false
+```
+
+### `isBigInt`
+
+```ts
+isBigInt(value: unknown): value is bigint
+```
+
+```ts
+isBigInt(10n); // true
+isBigInt(10);  // false
+```
+
+### `isBoolean`
+
+```ts
+isBoolean(value: unknown): value is boolean
+```
+
+```ts
+isBoolean(true); // true
+isBoolean(1);    // false
+```
+
+### `isDate`
+
+```ts
+isDate(value: unknown): value is Date
+```
+
+Matches `Date` instances only. Does not parse date strings or
+accept numeric timestamps.
+
+```ts
+isDate(new Date());   // true
+isDate('2024-01-01'); // false
+```
+
+### `isEmptyArray`
+
+```ts
+isEmptyArray(value: unknown): value is never[]
+```
+
+```ts
+isEmptyArray([]);  // true
+isEmptyArray([1]); // false
+```
+
+### `isEmptyRecord`
+
+```ts
+isEmptyRecord(value: unknown): value is EmptyObject
+```
+
+```ts
+isEmptyRecord({});       // true
+isEmptyRecord({ a: 1 }); // false
+```
+
+### `isEmptyString`
+
+```ts
+isEmptyString(value: unknown): value is ''
+```
+
+```ts
+isEmptyString('');  // true
+isEmptyString('a'); // false
+```
+
+### `isError`
+
+```ts
+isError(value: unknown): value is Error
+```
+
+Matches subclasses of `Error` too (e.g. `TypeError`, custom errors).
+
+```ts
+isError(new Error('boom')); // true
+isError('boom');            // false
+```
+
+### `isFalsy`
+
+```ts
+isFalsy(value: unknown): value is Falsy
+```
+
+Returns true for `false`, `0`, `-0`, `0n`, `''`, `null`, `undefined`,
+and `NaN`.
+
+```ts
+isFalsy(0); // true
+isFalsy(1); // false
+```
+
+### `isFiniteNumber`
+
+```ts
+isFiniteNumber(value: unknown): value is number
+```
+
+```ts
+isFiniteNumber(42);       // true
+isFiniteNumber(Infinity); // false
+```
+
+### `isFunction`
+
+```ts
+isFunction(value: unknown): value is (...args: unknown[]) => unknown
+```
+
+```ts
+isFunction(() => {}); // true
+isFunction({});       // false
+```
+
+### `isHtmlButtonElement`
+
+```ts
+isHtmlButtonElement(value: unknown): value is HTMLButtonElement
+```
+
+```ts
+isHtmlButtonElement(document.createElement('button')); // true
+isHtmlButtonElement(document.createElement('div'));    // false
+```
+
+### `isHtmlElement`
+
+```ts
+isHtmlElement(value: unknown): value is HTMLElement
+```
+
+```ts
+isHtmlElement(document.body); // true
+isHtmlElement('div');         // false
+```
+
+### `isHtmlInputElement`
+
+```ts
+isHtmlInputElement(value: unknown): value is HTMLInputElement
+```
+
+```ts
+isHtmlInputElement(document.createElement('input')); // true
+isHtmlInputElement(document.createElement('div'));   // false
+```
+
+### `isHtmlVideoElement`
+
+```ts
+isHtmlVideoElement(value: unknown): value is HTMLVideoElement
+```
+
+```ts
+isHtmlVideoElement(document.createElement('video')); // true
+isHtmlVideoElement(document.createElement('div'));   // false
+```
+
+### `isInteger`
+
+```ts
+isInteger(value: unknown): value is number
+```
+
+Uses `Number.isInteger`, so non-finite values (`NaN`, `Infinity`)
+return false.
+
+```ts
+isInteger(5);   // true
+isInteger(5.5); // false
+```
+
+### `isIterable`
+
+```ts
+isIterable(value: unknown): value is Iterable<unknown>
+```
+
+Strings are iterable and return true. Plain objects without
+`Symbol.iterator` return false.
+
+```ts
+isIterable([1, 2, 3]); // true
+isIterable({});        // false
+```
+
+### `isMap`
+
+```ts
+isMap(value: unknown): value is Map<unknown, unknown>
+```
+
+WeakMap instances return false.
+
+```ts
+isMap(new Map()); // true
+isMap({});        // false
+```
+
+### `isMouseEvent`
+
+```ts
+isMouseEvent(value: unknown): value is MouseEvent
+```
+
+```ts
+isMouseEvent(new MouseEvent('click')); // true
+isMouseEvent(new Event('change'));     // false
+```
+
+### `isNaN`
+
+```ts
+isNaN(value: unknown): value is number
+```
+
+Uses `Number.isNaN` (not the coercive global `isNaN`), so only the
+literal `NaN` value returns true.
+
+```ts
+isNaN(Number.NaN); // true
+isNaN(0);          // false
+```
+
+### `isNil`
+
+```ts
+isNil(value: unknown): value is Nil
+```
+
+```ts
+isNil(null); // true
+isNil(0);    // false
+```
+
+### `isNonBlankString`
+
+```ts
+isNonBlankString(value: unknown): value is string
+```
+
+```ts
+isNonBlankString('a');   // true
+isNonBlankString('   '); // false
+```
+
+### `isNonEmptyArray`
+
+```ts
+isNonEmptyArray<T>(value: Nilable<T[] | UnknownRecord>): value is NonEmptyArray<T>
+```
+
+```ts
+isNonEmptyArray([1]); // true
+isNonEmptyArray([]);  // false
+```
+
+### `isNonEmptyRecord`
+
+```ts
+isNonEmptyRecord(value: unknown): value is Record<string, unknown>
+```
+
+```ts
+isNonEmptyRecord({ a: 1 }); // true
+isNonEmptyRecord({});       // false
+```
+
+### `isNonEmptyString`
+
+```ts
+isNonEmptyString(value: unknown): value is string
+```
+
+```ts
+isNonEmptyString('a'); // true
+isNonEmptyString('');  // false
+```
+
+### `isNonNaNNumber`
+
+```ts
+isNonNaNNumber(value: unknown): value is number
+```
+
+```ts
+isNonNaNNumber(42);         // true
+isNonNaNNumber(Number.NaN); // false
+```
+
+### `isNotArray`
+
+```ts
+isNotArray(value: unknown): value is Exclude<unknown, unknown[]>
+```
+
+```ts
+isNotArray('x'); // true
+isNotArray([]);  // false
+```
+
+### `isNotBoolean`
+
+```ts
+isNotBoolean(value: unknown): value is Exclude<unknown, boolean>
+```
+
+```ts
+isNotBoolean(1);    // true
+isNotBoolean(true); // false
+```
+
+### `isNotFunction`
+
+```ts
+isNotFunction(value: unknown): value is Exclude<unknown, (...args: unknown[]) => unknown>
+```
+
+```ts
+isNotFunction(1);        // true
+isNotFunction(() => {}); // false
+```
+
+### `isNotNil`
+
+```ts
+isNotNil<T>(value: Nil | T): value is T
+```
+
+Common in `.filter(isNotNil)` to drop `null`/`undefined` from arrays
+with narrowing.
+
+```ts
+isNotNil(0);    // true
+isNotNil(null); // false
+
+const items: (string | null)[] = ['a', null, 'b'];
+const clean: string[] = items.filter(isNotNil); // ['a', 'b']
+```
+
+### `isNotNull`
+
+```ts
+isNotNull<T>(value: unknown): value is Exclude<T, null>
+```
+
+```ts
+isNotNull(undefined); // true
+isNotNull(null);      // false
+```
+
+### `isNotNumber`
+
+```ts
+isNotNumber(value: unknown): value is Exclude<unknown, number>
+```
+
+```ts
+isNotNumber('1'); // true
+isNotNumber(1);   // false
+```
+
+### `isNotRecord`
+
+```ts
+isNotRecord(value: unknown): value is Exclude<unknown, Record<string, unknown>>
+```
+
+```ts
+isNotRecord([]); // true
+isNotRecord({}); // false
+```
+
+### `isNotString`
+
+```ts
+isNotString(value: unknown): value is Exclude<unknown, string>
+```
+
+```ts
+isNotString(1);   // true
+isNotString('a'); // false
+```
+
+### `isNotUndefined`
+
+```ts
+isNotUndefined<T>(value: Undefinable<T>): value is Exclude<T, undefined>
+```
+
+```ts
+isNotUndefined(null);      // true
+isNotUndefined(undefined); // false
+```
+
+### `isNotVoid`
+
+```ts
+isNotVoid(value: unknown): value is Exclude<unknown, void>
+```
+
+```ts
+isNotVoid(0);         // true
+isNotVoid(undefined); // false
+```
+
+### `isNull`
+
+```ts
+isNull(value: unknown): value is null
+```
+
+```ts
+isNull(null);      // true
+isNull(undefined); // false
+```
+
+### `isNumber`
+
+```ts
+isNumber(value: unknown): value is number
+```
+
+`NaN` is a `number`, so `isNumber(NaN)` is true. Use `isInteger` or
+combine with `!isNaN(value)` if you need a finite number.
+
+```ts
+isNumber(1);   // true
+isNumber('1'); // false
+```
+
+### `isPlainObject`
+
+```ts
+isPlainObject(value: unknown): value is Record<string, unknown>
+```
+
+```ts
+isPlainObject({});         // true
+isPlainObject(new Date()); // false
+```
+
+### `isPromise`
+
+```ts
+isPromise(value: unknown): value is Promise<unknown>
+```
+
+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.
+
+```ts
+isPromise(Promise.resolve()); // true
+isPromise({ then: () => 1 }); // false
+```
+
+### `isRecord`
+
+```ts
+isRecord(value: unknown): value is Record<string, unknown>
+```
+
+```ts
+isRecord({}); // true
+isRecord([]); // false
+```
+
+### `isRegExp`
+
+```ts
+isRegExp(value: unknown): value is RegExp
+```
+
+```ts
+isRegExp(/abc/);   // true
+isRegExp('/abc/'); // false
+```
+
+### `isSet`
+
+```ts
+isSet(value: unknown): value is Set<unknown>
+```
+
+WeakSet instances return false.
+
+```ts
+isSet(new Set()); // true
+isSet([]);        // false
+```
+
+### `isString`
+
+```ts
+isString(value: unknown): value is string
+```
+
+```ts
+isString('hi'); // true
+isString(42);   // false
+```
+
+### `isSvgElement`
+
+```ts
+isSvgElement(value: unknown): value is SVGElement
+```
+
+```ts
+isSvgElement(document.createElementNS('http://www.w3.org/2000/svg', 'svg')); // true
+isSvgElement(document.createElement('div'));                                // false
+```
+
+### `isSymbol`
+
+```ts
+isSymbol(value: unknown): value is symbol
+```
+
+```ts
+isSymbol(Symbol('a')); // true
+isSymbol('symbol');    // false
+```
+
+### `isTextNode`
+
+```ts
+isTextNode(value: unknown): value is Text
+```
+
+```ts
+isTextNode(document.createTextNode('hi')); // true
+isTextNode(document.createElement('div')); // false
+```
+
+### `isTruthy`
+
+```ts
+isTruthy(value: unknown): boolean
+```
+
+The complement of `isFalsy`. Does not provide narrowing on its own;
+use `isNotNil` or a specific positive guard when narrowing matters.
+
+```ts
+isTruthy(1); // true
+isTruthy(0); // false
+```
+
+### `isUndefined`
+
+```ts
+isUndefined(value: unknown): value is undefined
+```
+
+```ts
+isUndefined(undefined); // true
+isUndefined(null);      // false
+```
+
+### `isVoid`
+
+```ts
+isVoid(value: unknown): value is void
+```
+
+```ts
+isVoid(undefined); // true
+isVoid(0);         // false
+```
+
+### `isWeakMap`
+
+```ts
+isWeakMap(value: unknown): value is WeakMap<WeakKey, unknown>
+```
+
+Map instances return false. Narrows to `WeakMap<WeakKey, unknown>`, since
+weak collections accept non-registered symbols as keys (ES2023).
+
+```ts
+isWeakMap(new WeakMap()); // true
+isWeakMap(new Map());     // false
+```
+
+### `isWeakSet`
+
+```ts
+isWeakSet(value: unknown): value is WeakSet<WeakKey>
+```
+
+Set instances return false. Narrows to `WeakSet<WeakKey>`, since weak
+collections accept non-registered symbols as members (ES2023).
+
+```ts
+isWeakSet(new WeakSet()); // true
+isWeakSet(new Set());     // false
+```
+
+### `readonlyArrayIncludes`
+
+```ts
+readonlyArrayIncludes<T>(arr: readonly T[], elem: unknown): elem is T
+```
+
+```ts
+const arr = ['a', 'b'] as const;
+readonlyArrayIncludes(arr, 'a'); // true
+readonlyArrayIncludes(arr, 'z'); // false
+```
+<!-- AUTOGEN:LLMS-FULL-GUARDS:END -->
+
+## Types
+
+<!-- AUTOGEN:LLMS-FULL-TYPES:START -->
+### `Arrayable<T>`
+
+```ts
+type Arrayable<T> = T | T[];
+type Tags = Arrayable<string>; // string | string[]
+```
+
+### `Falsy`
+
+```ts
+type Falsy = typeof Number.NaN | '' | 0n | false | null | undefined;
+type X = Falsy; // number | '' | 0n | false | null | undefined
+```
+
+### `NestedNonNullable<T, P extends Paths<T> & string>`
+
+```ts
+type NestedNonNullable<T, P extends Paths<T> & string> = NonNullable<Get<T, P>>;
+type User = { profile?: { name?: string } };
+type Name = NestedNonNullable<User, 'profile.name'>; // string
+```
+
+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.
+
+### `Nil`
+
+```ts
+type Nil = null | undefined;
+type X = Nil; // null | undefined
+```
+
+### `Nilable<A>`
+
+```ts
+type Nilable<A> = A | Nil;
+type Maybe = Nilable<string>; // string | null | undefined
+```
+
+### `NilableArray<T>`
+
+```ts
+type NilableArray<T> = Nilable<Nilable<T>[]>;
+type Items = NilableArray<string>; // (string | null | undefined)[] | null | undefined
+```
+
+### `NonEmptyArray<T>`
+
+```ts
+type NonEmptyArray<T> = [T, ...T[]];
+type Ids = NonEmptyArray<number>; // [number, ...number[]]
+```
+
+### `NotNilable<A>`
+
+```ts
+type NotNilable<A> = Exclude<A, Nil>;
+type X = NotNilable<string | null | undefined>; // string
+```
+
+### `Nullable<A>`
+
+```ts
+type Nullable<A> = A | null;
+type X = Nullable<string>; // string | null
+```
+
+### `NullableProperties<T extends UnknownRecord>`
+
+```ts
+type NullableProperties<T extends UnknownRecord> = { [Key in keyof T]: Nullable<T[Key]> };
+type User = { name: string; age: number };
+type X = NullableProperties<User>; // { name: string | null; age: number | null }
+```
+
+### `Truthy<T>`
+
+```ts
+type Truthy<T> = Exclude<T, Falsy>;
+type X = Truthy<string | 0 | null>; // string
+```
+
+### `Undefinable<A>`
+
+```ts
+type Undefinable<A> = A | undefined;
+type X = Undefinable<string>; // string | undefined
+```
+<!-- AUTOGEN:LLMS-FULL-TYPES:END -->
+
+## Utilities
+
+<!-- AUTOGEN:LLMS-FULL-UTILITIES:START -->
+### `asyncNoOpFn`
+
+```ts
+asyncNoOpFn(): Promise<void>
+```
+
+```ts
+await asyncNoOpFn(); // undefined
+```
+
+### `buildTimeDuration`
+
+```ts
+buildTimeDuration(numberOfMilliseconds: number): TimeDuration
+```
+
+```ts
+buildTimeDuration(3723000); // { hours: 1, minutes: 2, seconds: 3 }
+```
+
+### `coerceToBoolean`
+
+```ts
+coerceToBoolean(value: unknown): boolean
+```
+
+```ts
+coerceToBoolean('true');  // true
+coerceToBoolean('false'); // false
+coerceToBoolean(0);       // false
+```
+
+### `dateOnlyISOString`
+
+```ts
+dateOnlyISOString(date: unknown, { timeZone = defaultTimeZone }: DateOnlyStringOptions = {}): string
+```
+
+```ts
+dateOnlyISOString(new Date(2011, 11, 15)); // '2011-12-15'
+```
+
+### `dateOnlyString`
+
+```ts
+dateOnlyString(
+  date: unknown,
+  { timeZone = defaultTimeZone, omitYear = false }: DateOnlyStringOptions = {},
+): string
+```
+
+```ts
+dateOnlyString(new Date(2011, 11, 15)); // 'Dec 15, 2011'
+```
+
+### `dateOnlyStringForSentence`
+
+```ts
+dateOnlyStringForSentence(
+  date: unknown,
+  { timeZone = defaultTimeZone }: DateOnlyStringOptions = {},
+): string
+```
+
+```ts
+dateOnlyStringForSentence(new Date(2011, 11, 15)); // 'December 15, 2011'
+```
+
+### `dateOnlyStringNumeric`
+
+```ts
+dateOnlyStringNumeric(
+  date: unknown,
+  { timeZone = defaultTimeZone }: DateOnlyStringOptions = {},
+): string
+```
+
+```ts
+dateOnlyStringNumeric(new Date(2011, 11, 15)); // '12/15/2011'
+```
+
+### `dateTimeRounded`
+
+```ts
+dateTimeRounded(dateTime: Date, toISOString = true): string | Date | null
+```
+
+```ts
+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)
+```
+
+### `dateTimeString`
+
+```ts
+dateTimeString(
+  date: Date | number | string | null | undefined,
+  { timeZone = defaultTimeZone, omitYear = false }: DateOnlyStringOptions = {},
+): string
+```
+
+```ts
+dateTimeString(new Date(2011, 11, 15, 7, 30)); // 'Dec 15, 2011, 7:30 AM'
+```
+
+### `dateTimeStringForSentence`
+
+```ts
+dateTimeStringForSentence(
+  date: unknown,
+  { timeZone = defaultTimeZone }: DateOnlyStringOptions = {},
+): string
+```
+
+```ts
+dateTimeStringForSentence(new Date(2011, 11, 15, 7, 30)); // 'December 15, 2011, 7:30 AM'
+```
+
+### `dateTimeToDate`
+
+```ts
+dateTimeToDate(dateTime: Partial<WistiaDateTimeObject> | null | undefined): Date | null
+```
+
+```ts
+dateTimeToDate({ year: 2015, month: 10, dayOfMonth: 7, hours: 4, minutes: 15 });
+// new Date(2015, 10, 7, 4, 15)
+```
+
+### `dateTimeToISO`
+
+```ts
+dateTimeToISO(dateTime: Partial<WistiaDateTimeObject>): string | null
+```
+
+```ts
+dateTimeToISO({ year: 2015, month: 10, dayOfMonth: 7, hours: 4, minutes: 15 });
+// '2015-11-07T04:15:00.000Z' (in UTC)
+```
+
+### `dateToDateTime`
+
+```ts
+dateToDateTime(date: Date | null | undefined): WistiaDateTimeObject | null
+```
+
+```ts
+dateToDateTime(new Date(2011, 11, 15, 3, 10));
+// { year: 2011, month: 11, dayOfMonth: 15, hours: 3, minutes: 10 }
+```
+
+### `dateUTCOffset`
+
+```ts
+dateUTCOffset(date: Date): string
+```
+
+```ts
+dateUTCOffset(new Date(2011, 11, 15)); // '+00:00' (when run in UTC)
+```
+
+### `dayOfWeekString`
+
+```ts
+dayOfWeekString(
+  date: Date | null,
+  { timeZone = defaultTimeZone }: DateOnlyStringOptions = {},
+): string
+```
+
+```ts
+dayOfWeekString(new Date(2011, 11, 15)); // 'Thursday'
+```
+
+### `deepMerge`
+
+```ts
+deepMerge<T extends Record<string, unknown>[]>(...objects: T): DeepMergeResult<T>
+```
+
+```ts
+deepMerge({ a: { b: 1 }, c: [1] }, { a: { d: 2 }, c: [2] });
+// { a: { b: 1, d: 2 }, c: [1, 2] }
+```
+
+### `getObjectEntries`
+
+```ts
+getObjectEntries<T extends Record<string, unknown>>(obj: T): [keyof T, T[keyof T]][]
+```
+
+```ts
+getObjectEntries({ a: 1, b: 2 }); // [['a', 1], ['b', 2]]
+```
+
+### `getObjectKeys`
+
+```ts
+getObjectKeys<T extends Record<string, unknown>>(obj: T): (keyof T)[]
+```
+
+```ts
+getObjectKeys({ a: 1, b: 2 }); // ['a', 'b']
+```
+
+### `getObjectValues`
+
+```ts
+getObjectValues<T extends Record<string, unknown>>(obj: T): T[keyof T][]
+```
+
+```ts
+getObjectValues({ a: 1, b: 2 }); // [1, 2]
+```
+
+### `isEmail`
+
+```ts
+isEmail(value: string): boolean
+```
+
+```ts
+isEmail('user@example.com'); // true
+isEmail('user@example');     // false
+```
+
+### `isUrl`
+
+```ts
+isUrl(value: unknown): boolean
+```
+
+```ts
+isUrl('https://wistia.com'); // true
+isUrl('not a url');          // false
+```
+
+### `mediaDurationString`
+
+```ts
+mediaDurationString(numberOfMilliseconds: number): string
+```
+
+```ts
+mediaDurationString(234230);   // '3:54'
+mediaDurationString(23423000); // '6:30:23'
+```
+
+### `millisecondsToDurationISOString`
+
+```ts
+millisecondsToDurationISOString(numberOfMilliseconds: number): string
+```
+
+```ts
+millisecondsToDurationISOString(33000);   // 'PT33S'
+millisecondsToDurationISOString(3605000); // 'PT1H5S'
+```
+
+### `monthDayStringNumeric`
+
+```ts
+monthDayStringNumeric(
+  date: unknown,
+  { timeZone = defaultTimeZone }: DateOnlyStringOptions = {},
+): string
+```
+
+```ts
+monthDayStringNumeric(new Date(2011, 11, 15)); // '12/15'
+```
+
+### `noOpFn`
+
+```ts
+noOpFn(): void
+```
+
+```ts
+noOpFn(); // undefined
+```
+
+### `noOpFnReturningFalse`
+
+```ts
+noOpFnReturningFalse(): false
+```
+
+```ts
+noOpFnReturningFalse(); // false
+```
+
+### `noOpFnReturningNull`
+
+```ts
+noOpFnReturningNull(): null
+```
+
+```ts
+noOpFnReturningNull(); // null
+```
+
+### `parseDateString`
+
+```ts
+parseDateString(str: string): Date | null
+```
+
+```ts
+parseDateString('Jan 5, 2025'); // Date for 2025-01-05 at local midnight
+parseDateString('garbage');     // null
+```
+
+### `sessionDurationString`
+
+```ts
+sessionDurationString(numberOfMilliseconds: number): string
+```
+
+```ts
+sessionDurationString(2342300); // '0:39:02'
+```
+
+### `stripExtension`
+
+```ts
+stripExtension(str: string): string
+```
+
+```ts
+stripExtension('config.yml');      // 'config'
+stripExtension('example.test.ts'); // 'example.test'
+```
+
+### `timeAgoString`
+
+```ts
+timeAgoString(
+  date: Date,
+  { nowAnchor = new Date(), includeTime = true }: TimeAgoOptions = {},
+): string
+```
+
+```ts
+timeAgoString(new Date(Date.now() - 30_000)); // '< 1 minute ago'
+```
+
+### `timeOnlyString`
+
+```ts
+timeOnlyString(date: unknown, { timeZone = defaultTimeZone }: DateOnlyStringOptions = {}): string
+```
+
+```ts
+timeOnlyString(new Date(2011, 11, 15, 7, 30)); // '7:30 AM'
+```
+
+### `tupleIncludes`
+
+```ts
+tupleIncludes<TTuple extends readonly TItem[], TItem>(
+  tuple: TTuple,
+  item: TItem,
+): item is TTuple[number]
+```
+
+```ts
+const tuple = ['x', 'y'] as const;
+tupleIncludes(tuple, 'x'); // true
+tupleIncludes(tuple, 'z'); // false
+```
+<!-- AUTOGEN:LLMS-FULL-UTILITIES:END -->
+
+## Patterns
+
+Filter out nullish values from a list, with narrowing:
+
+```ts
+import { isNotNil } from '@wistia/utils';
+
+const raw: (string | null | undefined)[] = ['a', null, 'b', undefined];
+const clean: string[] = raw.filter(isNotNil); // ['a', 'b']
+```
+
+Narrow a parameter before using it:
+
+```ts
+import { isString, isNonEmptyArray } from '@wistia/utils';
+
+function describe(value: unknown): string {
+  if (isString(value)) return value.toUpperCase();
+  if (isNonEmptyArray<unknown>(value)) return `${value.length} items`;
+  return 'other';
+}
+```
+
+Safely access an unknown object key:
+
+```ts
+import { hasKey } from '@wistia/utils';
+
+function readName(value: unknown): string | undefined {
+  if (hasKey<'name', string>(value, 'name') && typeof value.name === 'string') {
+    return value.name;
+  }
+  return undefined;
+}
+```