@wistia/utils 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,159 @@
+# @wistia/utils
+
+## 1.0.0
+
+### Major Changes
+
+- [#280](https://github.com/wistia/utils/pull/280) [`4201db5`](https://github.com/wistia/utils/commit/4201db5b2561fa55400a97ae8fd0446d96b0e725) Thanks [@okize](https://github.com/okize)! - feat!: drop commonJS support (ESM only)
+
+## 0.17.0
+
+### Minor Changes
+
+- [#275](https://github.com/wistia/type-guards/pull/275) [`feabe44`](https://github.com/wistia/type-guards/commit/feabe441245825095c43ed58a37bdf2724d23a70) Thanks [@okize](https://github.com/okize)! - Add the `isEmail` utility, ported from the Wistia app
+
+## 0.16.0
+
+### Minor Changes
+
+- [#273](https://github.com/wistia/type-guards/pull/273) [`1e36fd8`](https://github.com/wistia/type-guards/commit/1e36fd8762af671d8bd24e028787c58589129ac1) Thanks [@okize](https://github.com/okize)! - Add the `noOpFn`, `noOpFnReturningFalse`, `noOpFnReturningNull`, and `asyncNoOpFn` utilities and the `NoOpFn`, `NoOpFnReturningFalse`, `NoOpFnReturningNull`, `AsyncNoOpFn`, and `AsyncOrSyncNoOpFn` types. Each function does nothing; they serve as default or placeholder callbacks
+
+## 0.15.0
+
+### Minor Changes
+
+- [#251](https://github.com/wistia/type-guards/pull/251) [`7740fc8`](https://github.com/wistia/type-guards/commit/7740fc8d652831074d429aa207500e226c49f8e5) Thanks [@okize](https://github.com/okize)! - Add the `deepMerge` utility and `DeepMerged` type. Deeply merges objects without mutating them, inferring the return type from the inputs; plain objects merge recursively, arrays concatenate with duplicates removed, and other values are overwritten in argument order
+
+## 0.14.0
+
+### Minor Changes
+
+- [#247](https://github.com/wistia/type-guards/pull/247) [`e4c822c`](https://github.com/wistia/type-guards/commit/e4c822cde3e776b2985da90cfc20ddbaa03d5435) Thanks [@okize](https://github.com/okize)! - Add the date and time utilities from `@wistia/ui`: `buildTimeDuration`, `dateOnlyISOString`, `dateOnlyString`, `dateOnlyStringForSentence`, `dateOnlyStringNumeric`, `dateTimeRounded`, `dateTimeString`, `dateTimeStringForSentence`, `dateTimeToDate`, `dateTimeToISO`, `dateToDateTime`, `dateUTCOffset`, `dayOfWeekString`, `mediaDurationString`, `millisecondsToDurationISOString`, `monthDayStringNumeric`, `parseDateString`, `sessionDurationString`, `timeAgoString`, and `timeOnlyString`, plus the `DateOnlyStringOptions`, `DateTimeRoundedOverload`, `TimeAgoOptions`, `TimeDuration`, and `WistiaDateTimeObject` types
+
+## 0.13.1
+
+### Patch Changes
+
+- [#240](https://github.com/wistia/type-guards/pull/240) [`9e86ea9`](https://github.com/wistia/type-guards/commit/9e86ea9b9271da61f3e90dbd41b2e01b347ad0ba) Thanks [@okize](https://github.com/okize)! - fix: narrow `isRecord` to `Record<string, unknown>` instead of `EmptyObject | Record<string, unknown>`
+
+  The `EmptyObject` union member was redundant — `Record<string, unknown>` already
+  accepts `{}` — and it broke the guard's primary use: because `EmptyObject` has no
+  index signature, every `value['someKey']` read after a passing `isRecord` check
+  failed with TS7053. `isNotRecord`'s declared type is updated to match; its
+  resolved type is unchanged.
+
+## 0.13.0
+
+### Minor Changes
+
+- [#235](https://github.com/wistia/type-guards/pull/235) [`6a92f7f`](https://github.com/wistia/type-guards/commit/6a92f7f744b6268308031dadd9ddc0b4c475297c) Thanks [@okize](https://github.com/okize)! - feat: add guards `isRegExp`, `isBigInt`, `isSymbol`, `isPromise`, `isIterable`, `isMap`, `isSet`, `isWeakMap`, `isWeakSet`, `isAsyncFunction`
+
+## 0.12.0
+
+### Minor Changes
+
+- [#233](https://github.com/wistia/type-guards/pull/233) [`ff94757`](https://github.com/wistia/type-guards/commit/ff947573899f4265e68a3a8ab9e7842da8d9fedf) Thanks [@okize](https://github.com/okize)! - feat: add guards `isNonBlankString`, `isNonNaNNumber`, `isFiniteNumber`, `isPlainObject`, `isHtmlElement`, `isHtmlInputElement`, `isHtmlVideoElement`, `isHtmlButtonElement`, `isSvgElement`, `isTextNode`, `readonlyArrayIncludes`, `isMouseEvent` and utilities `getObjectEntries`, `getObjectKeys`, `getObjectValues`, `tupleIncludes`
+
+## 0.11.4
+
+### Patch Changes
+
+- [#225](https://github.com/wistia/type-guards/pull/225) [`d3b2734`](https://github.com/wistia/type-guards/commit/d3b273448baff8c4e17061846214eb5bbfca9466) Thanks [@okize](https://github.com/okize)! - feat: add `NullableProperties` type
+
+## 0.11.3
+
+### Patch Changes
+
+- [#217](https://github.com/wistia/type-guards/pull/217) [`0f0b7bb`](https://github.com/wistia/type-guards/commit/0f0b7bba1cd0dd8af8d5d0dda4ff80d88e9e6ee4) Thanks [@okize](https://github.com/okize)! - feat: add llms.txt and llms-full.txt for agent consumption
+
+## 0.11.2
+
+### Patch Changes
+
+- [#211](https://github.com/wistia/type-guards/pull/211) [`6c2bbcd`](https://github.com/wistia/type-guards/commit/6c2bbcdd41a68886429d9d0ef2ff7784cedc7207) Thanks [@okize](https://github.com/okize)! - fix: split index.ts into per-guard files under `src`
+
+## 0.11.1
+
+### Patch Changes
+
+- [#206](https://github.com/wistia/type-guards/pull/206) [`ec39edd`](https://github.com/wistia/type-guards/commit/ec39edd03204174e1956e16d4567efb2c6122253) Thanks [@okize](https://github.com/okize)! - feat: add `Arrayable` type
+
+## 0.11.0
+
+### Minor Changes
+
+- [#194](https://github.com/wistia/type-guards/pull/194) [`ef44620`](https://github.com/wistia/type-guards/commit/ef446209c3099ac53cbc17a18b18df09d779c0a3) Thanks [@okize](https://github.com/okize)! - feat: add `isDate` type guard
+
+## 0.10.0
+
+### Minor Changes
+
+- [#182](https://github.com/wistia/type-guards/pull/182) [`b1ce2fe`](https://github.com/wistia/type-guards/commit/b1ce2fe8beccb9375cbc25bf534ab57b313bb45c) Thanks [@okize](https://github.com/okize)! - feat: switch build from `tsup` to `tsdown`
+
+## 0.9.3
+
+### Patch Changes
+
+- [#163](https://github.com/wistia/type-guards/pull/163) [`67fe310`](https://github.com/wistia/type-guards/commit/67fe310ce9dd5f14e24694bdd3cd5342476c28cf) Thanks [@okize](https://github.com/okize)! - fix: remove remaining GH links from `package.json`
+
+## 0.9.2
+
+### Patch Changes
+
+- [#161](https://github.com/wistia/type-guards/pull/161) [`966b9ea`](https://github.com/wistia/type-guards/commit/966b9eafdd667ac0a82891aec91ff73d41879eba) Thanks [@okize](https://github.com/okize)! - fix: set license to MIT
+
+## 0.9.1
+
+### Patch Changes
+
+- [#113](https://github.com/wistia/type-guards/pull/113) [`1be4586`](https://github.com/wistia/type-guards/commit/1be458654816bc1b3752fd0648c592d7189e6cb2) Thanks [@okize](https://github.com/okize)! - fix: ensure build emits correct commonjs & esm exports
+
+## 0.9.0
+
+### Minor Changes
+
+- [#109](https://github.com/wistia/type-guards/pull/109) [`6f54871`](https://github.com/wistia/type-guards/commit/6f548712fec133bc9d9c47aab226e3d8ed9568bd) Thanks [@okize](https://github.com/okize)! - feat: add isTruthy type guard
+
+## 0.8.0
+
+### Minor Changes
+
+- [#107](https://github.com/wistia/type-guards/pull/107) [`2bae8ba`](https://github.com/wistia/type-guards/commit/2bae8baff6f069686d76f53cba0e1b396aa456e1) Thanks [@okize](https://github.com/okize)! - feat: add isFalsy type guard
+
+## 0.7.0
+
+### Minor Changes
+
+- [#73](https://github.com/wistia/type-guards/pull/73) [`38c0b23`](https://github.com/wistia/type-guards/commit/38c0b231692a2b16335913d6862387dbc1b0306e) Thanks [@okize](https://github.com/okize)! - feat: add isNotRecord type guard
+
+- [#91](https://github.com/wistia/type-guards/pull/91) [`9b2beed`](https://github.com/wistia/type-guards/commit/9b2beeddfbf456007dce87f6afba5e85796f59f1) Thanks [@okize](https://github.com/okize)! - feat: add `isNotVoid` type guard
+
+## 0.6.0
+
+### Minor Changes
+
+- [#69](https://github.com/wistia/type-guards/pull/69) [`cacf785`](https://github.com/wistia/type-guards/commit/cacf785d526a01ed134d5dbd6b7d595012dc20f5) Thanks [@okize](https://github.com/okize)! - feat: add isNotArray type guard
+
+## 0.5.0
+
+### Minor Changes
+
+- [`ab086eb`](https://github.com/wistia/type-guards/commit/ab086eb1d095522cdfa80d3e1f330afea0bb826f) Thanks [@okize](https://github.com/okize)! - feat: add `isNotBoolean` type guard
+
+## 0.4.0
+
+### Minor Changes
+
+- [#61](https://github.com/wistia/type-guards/pull/61) [`41f8d7b`](https://github.com/wistia/type-guards/commit/41f8d7b3d6e18012df2615412df8586ad1872424) Thanks [@okize](https://github.com/okize)! - feat: add `isNotFunction` type guard
+
+## 0.3.0
+
+### Minor Changes
+
+- [#56](https://github.com/wistia/type-guards/pull/56) [`08804e5`](https://github.com/wistia/type-guards/commit/08804e53af325090ff26894f953cdc972fe8c660) Thanks [@okize](https://github.com/okize)! - feat: add `isNotNumber` type guard
+
+## 0.2.0
+
+### Minor Changes
+
+- [`e873b82`](https://github.com/wistia/type-guards/commit/e873b82478bf8868cb99dc0d5ad70e10226f9d40) Thanks [@okize](https://github.com/okize)! - feat: add `isNotString` type guard

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Wistia, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -1,3 +1,238 @@
-# Temporary Holding Version
+# utils
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+This library provides a set of type guards that help safely check and narrow down types at runtime, making it easier to handle data validation and type checking in a type-safe manner. It also ships a set of general-purpose utility functions and utility types.
+
+## Install
+
+```sh
+npm install @wistia/utils
+```
+
+```sh
+yarn add @wistia/utils
+```
+
+```sh
+pnpm add @wistia/utils
+```
+
+## Usage
+
+Every guard is a `value is T` predicate, so TypeScript narrows the value inside the `if` block:
+
+```ts
+import { isNonEmptyString, isNotNil } from '@wistia/utils';
+
+function greet(value: unknown): string {
+  if (isNonEmptyString(value)) {
+    return `Hello, ${value}`;
+  }
+  return 'Hello, stranger';
+}
+
+const names: (string | null | undefined)[] = ['Alice', null, 'Bob'];
+const cleaned: string[] = names.filter(isNotNil); // ['Alice', 'Bob']
+```
+
+## Guards
+
+<!-- AUTOGEN:README-GUARDS:START -->
+
+### Primitives
+
+| Guard                    | Narrows to                                 |
+| ------------------------ | ------------------------------------------ |
+| `isAsyncFunction(value)` | `(...args: unknown[]) => Promise<unknown>` |
+| `isBigInt(value)`        | `bigint`                                   |
+| `isBoolean(value)`       | `boolean`                                  |
+| `isDate(value)`          | `Date`                                     |
+| `isError(value)`         | `Error`                                    |
+| `isFiniteNumber(value)`  | `number`                                   |
+| `isFunction(value)`      | `(...args: unknown[]) => unknown`          |
+| `isInteger(value)`       | `number`                                   |
+| `isIterable(value)`      | `Iterable<unknown>`                        |
+| `isMap(value)`           | `Map<unknown, unknown>`                    |
+| `isNaN(value)`           | `number`                                   |
+| `isNil(value)`           | `Nil`                                      |
+| `isNonNaNNumber(value)`  | `number`                                   |
+| `isNull(value)`          | `null`                                     |
+| `isNumber(value)`        | `number`                                   |
+| `isPromise(value)`       | `Promise<unknown>`                         |
+| `isRegExp(value)`        | `RegExp`                                   |
+| `isSet(value)`           | `Set<unknown>`                             |
+| `isString(value)`        | `string`                                   |
+| `isSymbol(value)`        | `symbol`                                   |
+| `isUndefined(value)`     | `undefined`                                |
+| `isVoid(value)`          | `void`                                     |
+| `isWeakMap(value)`       | `WeakMap<WeakKey, unknown>`                |
+| `isWeakSet(value)`       | `WeakSet<WeakKey>`                         |
+
+### Arrays
+
+| Guard                              | Narrows to         |
+| ---------------------------------- | ------------------ |
+| `isArray(value)`                   | `unknown[]`        |
+| `isEmptyArray(value)`              | `never[]`          |
+| `isNonEmptyArray(value)`           | `NonEmptyArray<T>` |
+| `readonlyArrayIncludes(arr, elem)` | `T`                |
+
+### Records (plain objects, not arrays)
+
+| Guard                     | Narrows to                |
+| ------------------------- | ------------------------- |
+| `hasKey(value, key)`      | `Record<Key, Value>`      |
+| `isEmptyRecord(value)`    | `EmptyObject`             |
+| `isNonEmptyRecord(value)` | `Record<string, unknown>` |
+| `isPlainObject(value)`    | `Record<string, unknown>` |
+| `isRecord(value)`         | `Record<string, unknown>` |
+
+### Strings
+
+| Guard                     | Narrows to |
+| ------------------------- | ---------- |
+| `isEmptyString(value)`    | `''`       |
+| `isNonBlankString(value)` | `string`   |
+| `isNonEmptyString(value)` | `string`   |
+
+### Truthy / falsy
+
+| Guard             | Narrows to |
+| ----------------- | ---------- |
+| `isFalsy(value)`  | `Falsy`    |
+| `isTruthy(value)` | `boolean`  |
+
+### Negated
+
+The `isNot*` variants are useful as `.filter` predicates to drop the unwanted type:
+
+| Guard                   | Narrows to                                          |
+| ----------------------- | --------------------------------------------------- |
+| `isNotArray(value)`     | `Exclude<unknown, unknown[]>`                       |
+| `isNotBoolean(value)`   | `Exclude<unknown, boolean>`                         |
+| `isNotFunction(value)`  | `Exclude<unknown, (...args: unknown[]) => unknown>` |
+| `isNotNil(value)`       | `T`                                                 |
+| `isNotNull(value)`      | `Exclude<T, null>`                                  |
+| `isNotNumber(value)`    | `Exclude<unknown, number>`                          |
+| `isNotRecord(value)`    | `Exclude<unknown, Record<string, unknown>>`         |
+| `isNotString(value)`    | `Exclude<unknown, string>`                          |
+| `isNotUndefined(value)` | `Exclude<T, undefined>`                             |
+| `isNotVoid(value)`      | `Exclude<unknown, void>`                            |
+
+### DOM
+
+| Guard                        | Narrows to          |
+| ---------------------------- | ------------------- |
+| `isHtmlButtonElement(value)` | `HTMLButtonElement` |
+| `isHtmlElement(value)`       | `HTMLElement`       |
+| `isHtmlInputElement(value)`  | `HTMLInputElement`  |
+| `isHtmlVideoElement(value)`  | `HTMLVideoElement`  |
+| `isMouseEvent(value)`        | `MouseEvent`        |
+| `isSvgElement(value)`        | `SVGElement`        |
+| `isTextNode(value)`          | `Text`              |
+
+<!-- AUTOGEN:README-GUARDS:END -->
+
+## Types
+
+<!-- AUTOGEN:README-TYPES:START -->
+
+| Type                                                | Resolves to                                                   |
+| --------------------------------------------------- | ------------------------------------------------------------- |
+| `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:README-TYPES:END -->
+
+## Utilities
+
+General-purpose helper functions that complement the guards. Unlike guards, these are not type predicates.
+
+<!-- AUTOGEN:README-UTILITIES:START -->
+
+| Utility                                                                  | Returns                        |
+| ------------------------------------------------------------------------ | ------------------------------ |
+| `asyncNoOpFn()`                                                          | `Promise<void>`                |
+| `buildTimeDuration(numberOfMilliseconds)`                                | `TimeDuration`                 |
+| `coerceToBoolean(value)`                                                 | `boolean`                      |
+| `dateOnlyISOString(date, { timeZone = defaultTimeZone })`                | `string`                       |
+| `dateOnlyString(date, { timeZone = defaultTimeZone, omitYear = false })` | `string`                       |
+| `dateOnlyStringForSentence(date, { timeZone = defaultTimeZone })`        | `string`                       |
+| `dateOnlyStringNumeric(date, { timeZone = defaultTimeZone })`            | `string`                       |
+| `dateTimeRounded(dateTime, toISOString = true)`                          | `string \| Date \| null`       |
+| `dateTimeString(date, { timeZone = defaultTimeZone, omitYear = false })` | `string`                       |
+| `dateTimeStringForSentence(date, { timeZone = defaultTimeZone })`        | `string`                       |
+| `dateTimeToDate(dateTime)`                                               | `Date \| null`                 |
+| `dateTimeToISO(dateTime)`                                                | `string \| null`               |
+| `dateToDateTime(date)`                                                   | `WistiaDateTimeObject \| null` |
+| `dateUTCOffset(date)`                                                    | `string`                       |
+| `dayOfWeekString(date, { timeZone = defaultTimeZone })`                  | `string`                       |
+| `deepMerge(...objects)`                                                  | `DeepMergeResult<T>`           |
+| `getObjectEntries(obj)`                                                  | `[keyof T, T[keyof T]][]`      |
+| `getObjectKeys(obj)`                                                     | `(keyof T)[]`                  |
+| `getObjectValues(obj)`                                                   | `T[keyof T][]`                 |
+| `isEmail(value)`                                                         | `boolean`                      |
+| `isUrl(value)`                                                           | `boolean`                      |
+| `mediaDurationString(numberOfMilliseconds)`                              | `string`                       |
+| `millisecondsToDurationISOString(numberOfMilliseconds)`                  | `string`                       |
+| `monthDayStringNumeric(date, { timeZone = defaultTimeZone })`            | `string`                       |
+| `noOpFn()`                                                               | `void`                         |
+| `noOpFnReturningFalse()`                                                 | `false`                        |
+| `noOpFnReturningNull()`                                                  | `null`                         |
+| `parseDateString(str)`                                                   | `Date \| null`                 |
+| `sessionDurationString(numberOfMilliseconds)`                            | `string`                       |
+| `stripExtension(str)`                                                    | `string`                       |
+| `timeAgoString(date, { nowAnchor = new Date(), includeTime = true })`    | `string`                       |
+| `timeOnlyString(date, { timeZone = defaultTimeZone })`                   | `string`                       |
+| `tupleIncludes(tuple, item)`                                             | `item is TTuple[number]`       |
+
+<!-- AUTOGEN:README-UTILITIES:END -->
+
+## Patterns
+
+Filter 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']
+```
+
+Safely access a key on an unknown value:
+
+```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;
+}
+```
+
+Combine guards to handle a discriminated input:
+
+```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';
+}
+```
+
+## Agent-friendly docs
+
+Every export has a TSDoc `@example` block, so IDEs and LLM agents see usage at the call site via the bundled `.d.ts`. The package also ships `llms.txt` (compact index) and `llms-full.txt` (every signature plus an example) at the package root, following the [llmstxt.org](https://llmstxt.org) convention.