@react-hive/honey-utils 4.3.0 → 5.0.0

package/README.md

@@ -99,7 +99,7 @@ splitStringIntoWords('hello world');
  * Generate a hash from a string
  */
 const hash = hashString('background-color: red;');
-// ➜ 'e4k1z0x'
+// ➜ '1s0s409'
 ```
 
 ### Encoding Utilities
@@ -230,6 +230,7 @@ import {
     intersection,
     difference,
     toggleArrayItem,
+    toMapBy,
     pipe,
     compose,
 } from '@react-hive/honey-utils';
@@ -290,6 +291,16 @@ toggleArrayItem(['a', 'b'], 'b', false);
 toggleArrayItem(['a', 'b'], 'a');
 // ➜ ['b']
 
+/**
+ * Index an array by a key
+ */
+const users = [{ id: 'u1', name: 'Ann' }, { id: 'u2', name: 'Bob' }];
+
+toMapBy(users, user => user.id);
+// ➜ Map { 'u1' => { id: 'u1', name: 'Ann' }, 'u2' => { id: 'u2', name: 'Bob' } }
+toMapBy(users, user => user.id, user => user.name);
+// ➜ Map { 'u1' => 'Ann', 'u2' => 'Bob' }
+
 /**
  * Compose functions from left to right
  */
@@ -709,7 +720,7 @@ function divide(a: number, b: number): number {
 ---
 
 - `isString(value: unknown): value is string` - Checks if a value is a `string`.
-- `isNilOrEmptyString(value: unknown): value is null | undefined` - Checks if a value is `null`, `undefined`, or an empty string.
+- `isNilOrEmptyString(value: unknown): value is null | undefined | ''` - Checks if a value is `null`, `undefined`, or an empty string.
 - `toKebabCase(input: string): string` - Converts a string to kebab-case.
 - `camelToDashCase(input: string): string` - Converts camelCase to dash-case.
 - `splitStringIntoWords(input: string): string[]` - Splits a string into an array of words.
@@ -744,7 +755,7 @@ function divide(a: number, b: number): number {
 
 ---
 
-- `definedProps<T extends object>(obj: T): DefinedProps<T>` - Creates a new object by removing all properties whose values are `undefined`.
+- `definedProps<T extends object>(obj: T): DefinedProps<T>` - Creates a new object by removing all properties whose values are `undefined`, symbol-keyed ones included. A key that may be `undefined` comes out optional.
 
 ### Array Utilities
 
@@ -754,8 +765,9 @@ function divide(a: number, b: number): number {
 - `isEmptyArray(value: unknown): value is []` - Checks if a value is an empty array.
 - `compact<T>(array: (T | Falsy)[]): T[]` – Returns a new array with all falsy values (false, null, undefined, 0, '', NaN) removed, preserving only truthy items of type `T`.
 - `unique<T>(array: T[]): T[]` - Returns a new array with all duplicate elements removed. Keeps only the first occurrence of each value.
-- `chunk<T>(array: T[], size: number): T[][]` - Splits an array into smaller arrays ("chunks") of the specified size.
-- `intersection<T>(...arrays: T[][]): T[]` - Returns an array of elements that exist in all provided arrays.
+- `toMapBy<Item, Key, Value>(items: readonly Item[], getKey: (item: Item, index: number) => Key, getValue?: (item: Item, index: number) => Value): Map<Key, Item | Value>` - Indexes an array by a key: a `Map` from each item's key to the item, or to what `getValue` returns for it. Where two items share a key, the later one wins.
+- `chunk<T>(array: T[], size: number): T[][]` - Splits an array into smaller arrays ("chunks") of the specified size. Throws unless `size` is a positive whole number.
+- `intersection<T>(...arrays: T[][]): T[]` - Returns an array of elements that exist in all provided arrays, each once, in the order of the first array.
 - `difference<T>(array: T[], exclude: T[]): T[]` - Returns a new array that contains items from `array` that are not present in `exclude`.
 - `pipe(...fns: Function[]): Function` - Composes unary functions left-to-right. Returns a new function that applies all given functions in a sequence.
 - `compose(...fns: Function[]): Function` - Composes unary functions **right-to-left**. Same as `pipe`, but applies functions in reverse order.
@@ -770,7 +782,7 @@ function divide(a: number, b: number): number {
 - `noop(): void` - A no-operation function.
 - `not<Args extends any[]>(fn: (...args: Args) => any): (...args: Args) => boolean` - Creates a new function that negates the result of the given predicate function. Useful for logical inversions, e.g., turning `isEven` into `isOdd`.
 - `invokeIfFunction<Args extends any[], Result>(input: ((...args: Args) => Result) | Result, ...args: Args): Result` - Invokes the input if it's a function, otherwise returns it as-is.
-- `once<T extends (...args: any[]) => any>(fn: T): T` - Wraps a function so it can only be executed once. The result of the first invocation is cached and returned for all subsequent calls. Preserves both the original function’s parameter types and `this` binding.
+- `once<T extends (...args: any[]) => any>(fn: T): T` - Wraps a function so it can only be executed once. The result of the first invocation is cached and returned for all subsequent calls; if it throws, every call throws that same error. Preserves both the original function’s parameter types and `this` binding.
 
 ### Type Guards
 
@@ -779,9 +791,9 @@ function divide(a: number, b: number): number {
 - `assert(condition: any, message: string): asserts condition` - Asserts that a condition is truthy, throwing an error with the provided message if it's not.
 - `isNumber(value: unknown): value is number` - Checks if a value is a `number`.
 - `isBool(value: unknown): value is boolean` - Checks if a value is a `boolean`.
-- `isObject(value: unknown): value is object` - Checks if a value is an `object`.
+- `isObject(value: unknown): value is object` - Checks if a value is an `object`, `null` excluded.
 - `isNil(value: unknown): value is null | undefined` - Checks if a value is `null` or `undefined`.
-- `isEmptyObject(value: unknown): value is Record<string, never>` - Checks if a value is an empty object.
+- `isEmptyObject(value: unknown): value is Record<string, never>` - Checks if a value is an empty object - no own enumerable properties, symbol-keyed ones included.
 - `isNull(value: unknown): value is null` - Checks if a value is `null`.
 - `isUndefined(value: unknown): value is undefined` - Checks if a value is `undefined`.
 - `isDefined<T>(value: T): value is NonNullable<T>` - Checks if a value is neither `null` nor `undefined`.
@@ -838,7 +850,7 @@ function divide(a: number, b: number): number {
 - `cloneBlob(blob: Blob): Blob` - Creates a clone of a Blob object with the same content and type as the original.
 - `getElementOffsetRect(element: HTMLElement): DOMRect` - Returns a `DOMRect` representing the element's layout position using `offsetLeft`, `offsetTop`, and `clientWidth`/`clientHeight`.
 - `isAnchorHtmlElement(element: HTMLElement): element is HTMLAnchorElement` - Determines whether the provided element is an `<a>` tag. Acts as a type guard that narrows the element to `HTMLAnchorElement`.
-- `isContentEditableHtmlElement(element: HTMLElement): boolean` - Returns `true` if the element has `contenteditable="true"`, making it user-editable and implicitly focusable.
+- `isContentEditableHtmlElement(element: HTMLElement): boolean` - Returns `true` if the element's `contenteditable` is `""`, `"true"` or `"plaintext-only"` (in any case), making it user-editable and implicitly focusable.
 
 #### File
 
@@ -890,8 +902,8 @@ function divide(a: number, b: number): number {
 - `everyAsync<Item>(array: Item[], predicate): Promise<boolean>` - Returns `true` if **all** items in the array pass the async predicate.
 - `findAsync<Item>(array: Item[], predicate): Promise<Nullable<Item>>` - Returns the first array item that passes the async predicate, or `null` if no match is found.
 - `delay(delayMs: number): Promise<void>` - Creates a promise that resolves after the specified delay in milliseconds.
-- `timeout<T>(promise: Promise<T>, timeoutMs: number, message?: string): Promise<T>` - Wraps a promise with a timeout. If the promise does not settle within the given duration, it rejects with a timeout error.
-- `retry<Task, TaskResult>(task: Task, options?: RetryOptions): Function` - Wraps an asynchronous function with retry logic, with configurable max attempts, delay between retries, exponential backoff, and retry callbacks.
+- `timeout<T>(promise: Promise<T>, timeoutMs: number, message?: string): Promise<T>` - Wraps a promise with a timeout. If the promise does not settle within the given duration, it rejects with a timeout error. Its timer is cleared however the race ends.
+- `retry<Args, TaskResult>(task: (...args: Args) => Promise<TaskResult>, options?: RetryOptions): (...args: Args) => Promise<TaskResult>` - Wraps an asynchronous function with retry logic, with configurable max attempts (at least one), delay between retries, exponential backoff, and retry callbacks.
 
 ### Intersection Utilities
 
@@ -906,7 +918,7 @@ function divide(a: number, b: number): number {
 
 #### Focus
 
-- `isHtmlElementFocusable(element: Nullable<HTMLElement>): boolean` - Checks whether an element is considered focusable according to browser rules. Factors include: visibility, `display`, `disabled`, `tabindex`, native focusable tags, `contenteditable`, and presence of a non-null `tabindex`.
+- `isHtmlElementFocusable(element: Nullable<HTMLElement>): boolean` - Checks whether an element is considered focusable according to browser rules. Factors include: visibility, `display` (an ancestor's too), `:disabled` (a disabled `<fieldset>`'s controls too), a valid `tabindex` (negative removes it, non-negative makes any element focusable), native focusable tags, and `contenteditable`.
 - `getFocusableHtmlElements(container: HTMLElement): HTMLElement[]` - Returns all focusable descendant elements within a container, using `isHtmlElementFocusable` to filter them.
 - `moveFocusWithinContainer(direction: FocusMoveDirection, container?: Nullable<HTMLElement>, options?: MoveFocusWithinContainerOptions): void` - Moves focus to the next or previous focusable element within a container. Supports cyclic navigation, optional wrapping control, and custom focus index resolution for advanced keyboard navigation patterns (e.g. roving tabindex).
 

package/dist/README.md

@@ -99,7 +99,7 @@ splitStringIntoWords('hello world');
  * Generate a hash from a string
  */
 const hash = hashString('background-color: red;');
-// ➜ 'e4k1z0x'
+// ➜ '1s0s409'
 ```
 
 ### Encoding Utilities
@@ -230,6 +230,7 @@ import {
     intersection,
     difference,
     toggleArrayItem,
+    toMapBy,
     pipe,
     compose,
 } from '@react-hive/honey-utils';
@@ -290,6 +291,16 @@ toggleArrayItem(['a', 'b'], 'b', false);
 toggleArrayItem(['a', 'b'], 'a');
 // ➜ ['b']
 
+/**
+ * Index an array by a key
+ */
+const users = [{ id: 'u1', name: 'Ann' }, { id: 'u2', name: 'Bob' }];
+
+toMapBy(users, user => user.id);
+// ➜ Map { 'u1' => { id: 'u1', name: 'Ann' }, 'u2' => { id: 'u2', name: 'Bob' } }
+toMapBy(users, user => user.id, user => user.name);
+// ➜ Map { 'u1' => 'Ann', 'u2' => 'Bob' }
+
 /**
  * Compose functions from left to right
  */
@@ -709,7 +720,7 @@ function divide(a: number, b: number): number {
 ---
 
 - `isString(value: unknown): value is string` - Checks if a value is a `string`.
-- `isNilOrEmptyString(value: unknown): value is null | undefined` - Checks if a value is `null`, `undefined`, or an empty string.
+- `isNilOrEmptyString(value: unknown): value is null | undefined | ''` - Checks if a value is `null`, `undefined`, or an empty string.
 - `toKebabCase(input: string): string` - Converts a string to kebab-case.
 - `camelToDashCase(input: string): string` - Converts camelCase to dash-case.
 - `splitStringIntoWords(input: string): string[]` - Splits a string into an array of words.
@@ -744,7 +755,7 @@ function divide(a: number, b: number): number {
 
 ---
 
-- `definedProps<T extends object>(obj: T): DefinedProps<T>` - Creates a new object by removing all properties whose values are `undefined`.
+- `definedProps<T extends object>(obj: T): DefinedProps<T>` - Creates a new object by removing all properties whose values are `undefined`, symbol-keyed ones included. A key that may be `undefined` comes out optional.
 
 ### Array Utilities
 
@@ -754,8 +765,9 @@ function divide(a: number, b: number): number {
 - `isEmptyArray(value: unknown): value is []` - Checks if a value is an empty array.
 - `compact<T>(array: (T | Falsy)[]): T[]` – Returns a new array with all falsy values (false, null, undefined, 0, '', NaN) removed, preserving only truthy items of type `T`.
 - `unique<T>(array: T[]): T[]` - Returns a new array with all duplicate elements removed. Keeps only the first occurrence of each value.
-- `chunk<T>(array: T[], size: number): T[][]` - Splits an array into smaller arrays ("chunks") of the specified size.
-- `intersection<T>(...arrays: T[][]): T[]` - Returns an array of elements that exist in all provided arrays.
+- `toMapBy<Item, Key, Value>(items: readonly Item[], getKey: (item: Item, index: number) => Key, getValue?: (item: Item, index: number) => Value): Map<Key, Item | Value>` - Indexes an array by a key: a `Map` from each item's key to the item, or to what `getValue` returns for it. Where two items share a key, the later one wins.
+- `chunk<T>(array: T[], size: number): T[][]` - Splits an array into smaller arrays ("chunks") of the specified size. Throws unless `size` is a positive whole number.
+- `intersection<T>(...arrays: T[][]): T[]` - Returns an array of elements that exist in all provided arrays, each once, in the order of the first array.
 - `difference<T>(array: T[], exclude: T[]): T[]` - Returns a new array that contains items from `array` that are not present in `exclude`.
 - `pipe(...fns: Function[]): Function` - Composes unary functions left-to-right. Returns a new function that applies all given functions in a sequence.
 - `compose(...fns: Function[]): Function` - Composes unary functions **right-to-left**. Same as `pipe`, but applies functions in reverse order.
@@ -770,7 +782,7 @@ function divide(a: number, b: number): number {
 - `noop(): void` - A no-operation function.
 - `not<Args extends any[]>(fn: (...args: Args) => any): (...args: Args) => boolean` - Creates a new function that negates the result of the given predicate function. Useful for logical inversions, e.g., turning `isEven` into `isOdd`.
 - `invokeIfFunction<Args extends any[], Result>(input: ((...args: Args) => Result) | Result, ...args: Args): Result` - Invokes the input if it's a function, otherwise returns it as-is.
-- `once<T extends (...args: any[]) => any>(fn: T): T` - Wraps a function so it can only be executed once. The result of the first invocation is cached and returned for all subsequent calls. Preserves both the original function’s parameter types and `this` binding.
+- `once<T extends (...args: any[]) => any>(fn: T): T` - Wraps a function so it can only be executed once. The result of the first invocation is cached and returned for all subsequent calls; if it throws, every call throws that same error. Preserves both the original function’s parameter types and `this` binding.
 
 ### Type Guards
 
@@ -779,9 +791,9 @@ function divide(a: number, b: number): number {
 - `assert(condition: any, message: string): asserts condition` - Asserts that a condition is truthy, throwing an error with the provided message if it's not.
 - `isNumber(value: unknown): value is number` - Checks if a value is a `number`.
 - `isBool(value: unknown): value is boolean` - Checks if a value is a `boolean`.
-- `isObject(value: unknown): value is object` - Checks if a value is an `object`.
+- `isObject(value: unknown): value is object` - Checks if a value is an `object`, `null` excluded.
 - `isNil(value: unknown): value is null | undefined` - Checks if a value is `null` or `undefined`.
-- `isEmptyObject(value: unknown): value is Record<string, never>` - Checks if a value is an empty object.
+- `isEmptyObject(value: unknown): value is Record<string, never>` - Checks if a value is an empty object - no own enumerable properties, symbol-keyed ones included.
 - `isNull(value: unknown): value is null` - Checks if a value is `null`.
 - `isUndefined(value: unknown): value is undefined` - Checks if a value is `undefined`.
 - `isDefined<T>(value: T): value is NonNullable<T>` - Checks if a value is neither `null` nor `undefined`.
@@ -838,7 +850,7 @@ function divide(a: number, b: number): number {
 - `cloneBlob(blob: Blob): Blob` - Creates a clone of a Blob object with the same content and type as the original.
 - `getElementOffsetRect(element: HTMLElement): DOMRect` - Returns a `DOMRect` representing the element's layout position using `offsetLeft`, `offsetTop`, and `clientWidth`/`clientHeight`.
 - `isAnchorHtmlElement(element: HTMLElement): element is HTMLAnchorElement` - Determines whether the provided element is an `<a>` tag. Acts as a type guard that narrows the element to `HTMLAnchorElement`.
-- `isContentEditableHtmlElement(element: HTMLElement): boolean` - Returns `true` if the element has `contenteditable="true"`, making it user-editable and implicitly focusable.
+- `isContentEditableHtmlElement(element: HTMLElement): boolean` - Returns `true` if the element's `contenteditable` is `""`, `"true"` or `"plaintext-only"` (in any case), making it user-editable and implicitly focusable.
 
 #### File
 
@@ -890,8 +902,8 @@ function divide(a: number, b: number): number {
 - `everyAsync<Item>(array: Item[], predicate): Promise<boolean>` - Returns `true` if **all** items in the array pass the async predicate.
 - `findAsync<Item>(array: Item[], predicate): Promise<Nullable<Item>>` - Returns the first array item that passes the async predicate, or `null` if no match is found.
 - `delay(delayMs: number): Promise<void>` - Creates a promise that resolves after the specified delay in milliseconds.
-- `timeout<T>(promise: Promise<T>, timeoutMs: number, message?: string): Promise<T>` - Wraps a promise with a timeout. If the promise does not settle within the given duration, it rejects with a timeout error.
-- `retry<Task, TaskResult>(task: Task, options?: RetryOptions): Function` - Wraps an asynchronous function with retry logic, with configurable max attempts, delay between retries, exponential backoff, and retry callbacks.
+- `timeout<T>(promise: Promise<T>, timeoutMs: number, message?: string): Promise<T>` - Wraps a promise with a timeout. If the promise does not settle within the given duration, it rejects with a timeout error. Its timer is cleared however the race ends.
+- `retry<Args, TaskResult>(task: (...args: Args) => Promise<TaskResult>, options?: RetryOptions): (...args: Args) => Promise<TaskResult>` - Wraps an asynchronous function with retry logic, with configurable max attempts (at least one), delay between retries, exponential backoff, and retry callbacks.
 
 ### Intersection Utilities
 
@@ -906,7 +918,7 @@ function divide(a: number, b: number): number {
 
 #### Focus
 
-- `isHtmlElementFocusable(element: Nullable<HTMLElement>): boolean` - Checks whether an element is considered focusable according to browser rules. Factors include: visibility, `display`, `disabled`, `tabindex`, native focusable tags, `contenteditable`, and presence of a non-null `tabindex`.
+- `isHtmlElementFocusable(element: Nullable<HTMLElement>): boolean` - Checks whether an element is considered focusable according to browser rules. Factors include: visibility, `display` (an ancestor's too), `:disabled` (a disabled `<fieldset>`'s controls too), a valid `tabindex` (negative removes it, non-negative makes any element focusable), native focusable tags, and `contenteditable`.
 - `getFocusableHtmlElements(container: HTMLElement): HTMLElement[]` - Returns all focusable descendant elements within a container, using `isHtmlElementFocusable` to filter them.
 - `moveFocusWithinContainer(direction: FocusMoveDirection, container?: Nullable<HTMLElement>, options?: MoveFocusWithinContainerOptions): void` - Moves focus to the next or previous focusable element within a container. Supports cyclic navigation, optional wrapping control, and custom focus index resolution for advanced keyboard navigation patterns (e.g. roving tabindex).
 

package/dist/a11y/focus/is-html-element-focusable.d.ts

@@ -1,15 +1,17 @@
-import type { Nullable } from '~/types';
+import type { Nullable } from '../../types';
 export declare const FOCUSABLE_HTML_TAGS: string[];
 /**
  * Determines whether an HTMLElement is focusable under standard browser rules.
  *
  * The function checks a combination of factors:
- * - The element must be rendered (not `display: none` or `visibility: hidden`).
- * - Disabled form controls are never focusable.
- * - Elements with `tabindex="-1"` are intentionally removed from the focus order.
+ * - The element must be rendered: neither it nor an ancestor has `display: none`, and it is not
+ *   `visibility: hidden`.
+ * - Disabled form controls are never focusable - including those inside a disabled `<fieldset>`.
+ * - Elements with a negative `tabindex` are intentionally removed from the focus order.
+ * - Any element with a valid, non-negative `tabindex` is focusable. A `tabindex` that is not an
+ *   integer is ignored, as browsers ignore it.
  * - Certain native HTML elements are inherently focusable (e.g. inputs, buttons, anchors with `href`).
- * - Elements with `contenteditable="true"` are treated as focusable.
- * - Any element with a valid `tabindex` (not null) is considered focusable.
+ * - Editable elements (`contenteditable`) are treated as focusable.
  *
  * This logic approximates how browsers and the accessibility tree
  * determine real-world focusability—not just tabindex presence.

package/dist/a11y/focus/move-focus-within-container.d.ts

@@ -1,4 +1,4 @@
-import type { Nullable } from '~/types';
+import type { Nullable } from '../../types';
 export type FocusMoveDirection = 'next' | 'previous';
 export interface MoveFocusWithinContainerOptions {
     /**

package/dist/array/chunk.d.ts

@@ -6,11 +6,14 @@
  * @template T - The type of the items in the array.
  *
  * @param array - The input array to be chunked.
- * @param size - The size of each chunk. Must be greater than 0.
+ * @param size - The size of each chunk. Must be a positive whole number.
  *
  * @returns An array of chunks, where each chunk is an array of the specified size
  *          (except possibly the last chunk, which may be smaller).
  *
+ * @throws {Error} When `size` is not a positive whole number - a fractional size would give
+ *         chunks of other sizes, and `Infinity` none at all.
+ *
  * @example
  * ```ts
  * chunk([1, 2, 3, 4, 5], 2); // [[1, 2], [3, 4], [5]]

package/dist/array/compose.d.ts

@@ -1,17 +1,21 @@
-type ComposeFn = (arg: unknown) => unknown;
+/**
+ * Any unary function: one taking a typed argument is assignable here, where it is not to
+ * `ComposeFn`.
+ */
+type AnyUnaryFn = (arg: never) => unknown;
 type Compose = {
     <A, R>(fn1: (a: A) => R): (a: A) => R;
     <A, B, R>(fn1: (b: B) => R, fn2: (a: A) => B): (a: A) => R;
     <A, B, C, R>(fn1: (c: C) => R, fn2: (b: B) => C, fn3: (a: A) => B): (a: A) => R;
     <A, B, C, D, R>(fn1: (d: D) => R, fn2: (c: C) => D, fn3: (b: B) => C, fn4: (a: A) => B): (a: A) => R;
     <A, B, C, D, E, R>(fn1: (e: E) => R, fn2: (d: D) => E, fn3: (c: C) => D, fn4: (b: B) => C, fn5: (a: A) => B): (a: A) => R;
-    (...fns: ComposeFn[]): (arg: unknown) => unknown;
+    (...fns: AnyUnaryFn[]): (arg: unknown) => unknown;
 };
 /**
  * Composes multiple unary functions into a single function, applying them from **right to left**.
  *
  * Often used for building functional pipelines where the innermost function runs first.
- * Types are inferred up to 5 chained functions for full type safety.
+ * Types are inferred up to 5 chained functions for full type safety. Beyond that, it falls back to the unknown.
  *
  * @param fns - A list of unary functions to compose.
  *

package/dist/array/get-adjacent-items.d.ts

@@ -1,4 +1,4 @@
-import type { Nullable } from '~/types';
+import type { Nullable } from '../types';
 export interface AdjacentItems<T> {
     previousItem: Nullable<T>;
     currentItem: Nullable<T>;

package/dist/array/index.d.ts

@@ -9,3 +9,4 @@ export * from './is-array';
 export * from './is-empty-array';
 export * from './get-adjacent-items';
 export * from './toggle-array-item';
+export * from './to-map-by';

package/dist/array/intersection.d.ts

@@ -5,7 +5,8 @@
  *
  * @param arrays - Two or more arrays to find common elements from.
  *
- * @returns A new array containing only the elements that exist in all input arrays.
+ * @returns A new array containing only the elements that exist in all input arrays, each once, in
+ *          the order of the first array.
  *
  * @example
  * ```ts

package/dist/array/is-array.d.ts

@@ -4,5 +4,11 @@
  * @param value - The value to check.
  *
  * @returns `true` if the value is an array; otherwise, `false`.
+ *
+ * @example
+ * ```ts
+ * isArray([1, 2]); // true
+ * isArray('12'); // false
+ * ```
  */
 export declare const isArray: (value: unknown) => value is unknown[];

package/dist/array/is-empty-array.d.ts

@@ -4,5 +4,12 @@
  * @param value - The value to check.
  *
  * @returns `true` if the value is an empty array; otherwise, `false`.
+ *
+ * @example
+ * ```ts
+ * isEmptyArray([]); // true
+ * isEmptyArray([1]); // false
+ * isEmptyArray({}); // false
+ * ```
  */
 export declare const isEmptyArray: (value: unknown) => value is [];

package/dist/array/pipe.d.ts

@@ -1,11 +1,14 @@
-type PipeFn = (arg: unknown) => unknown;
+/**
+ * Any unary function: one taking a typed argument is assignable here, where it is not to `PipeFn`.
+ */
+type AnyUnaryFn = (arg: never) => unknown;
 type Pipe = {
     <A, B>(fn1: (a: A) => B): (a: A) => B;
     <A, B, C>(fn1: (a: A) => B, fn2: (b: B) => C): (a: A) => C;
     <A, B, C, D>(fn1: (a: A) => B, fn2: (b: B) => C, fn3: (c: C) => D): (a: A) => D;
     <A, B, C, D, E>(fn1: (a: A) => B, fn2: (b: B) => C, fn3: (c: C) => D, fn4: (d: D) => E): (a: A) => E;
     <A, B, C, D, E, F>(fn1: (a: A) => B, fn2: (b: B) => C, fn3: (c: C) => D, fn4: (d: D) => E, fn5: (e: E) => F): (a: A) => F;
-    (...fns: PipeFn[]): (arg: unknown) => unknown;
+    (...fns: AnyUnaryFn[]): (arg: unknown) => unknown;
 };
 /**
  * Composes multiple unary functions into a single function, applying them from left to right.

package/dist/array/to-map-by.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Indexes an array by a key: a `Map` from each item's key to the item itself.
+ *
+ * Items are added in order, so where two share a key the later one wins, as with
+ * `new Map(entries)`.
+ *
+ * @template Item - The type of the items in the array.
+ * @template Key - The type of the keys.
+ *
+ * @param items - The items to index.
+ * @param getKey - Returns the key an item is stored under.
+ *
+ * @returns A new `Map` from each key to its item.
+ *
+ * @example
+ * ```ts
+ * const users = [{ id: 'u1', name: 'Ann' }, { id: 'u2', name: 'Bob' }];
+ *
+ * toMapBy(users, user => user.id);
+ * // Map { 'u1' => { id: 'u1', name: 'Ann' }, 'u2' => { id: 'u2', name: 'Bob' } }
+ * ```
+ */
+export declare function toMapBy<Item, Key>(items: readonly Item[], getKey: (item: Item, index: number) => Key): Map<Key, Item>;
+/**
+ * Indexes an array by a key: a `Map` from each item's key to what `getValue` returns for the item.
+ *
+ * Items are added in order, so where two share a key the later one wins, as with
+ * `new Map(entries)`.
+ *
+ * @template Item - The type of the items in the array.
+ * @template Key - The type of the keys.
+ * @template Value - The type of the values.
+ *
+ * @param items - The items to index.
+ * @param getKey - Returns the key an item is stored under.
+ * @param getValue - Returns the value stored for an item.
+ *
+ * @returns A new `Map` from each key to its value.
+ *
+ * @example
+ * ```ts
+ * const users = [{ id: 'u1', name: 'Ann' }, { id: 'u2', name: 'Bob' }];
+ *
+ * toMapBy(users, user => user.id, user => user.name);
+ * // Map { 'u1' => 'Ann', 'u2' => 'Bob' }
+ * ```
+ */
+export declare function toMapBy<Item, Key, Value>(items: readonly Item[], getKey: (item: Item, index: number) => Key, getValue: (item: Item, index: number) => Value): Map<Key, Value>;

package/dist/async/async.d.ts

@@ -1,4 +1,4 @@
-import type { Nullable } from '~/types';
+import type { Nullable } from '../types';
 /**
  * Checks if a value is a Promise.
  *
@@ -109,6 +109,9 @@ export declare const filterParallel: <Item>(array: Item[], predicate: (item: Ite
 /**
  * Asynchronously checks if at least one element in the array satisfies the async condition.
  *
+ * Runs one item at a time, in order, and stops at the first item that satisfies it - as
+ * `Array.prototype.some` does.
+ *
  * @param array - The array of items to check.
  * @param predicate - An async function that returns a boolean.
  *
@@ -118,6 +121,9 @@ export declare const someAsync: <Item>(array: Item[], predicate: (item: Item, in
 /**
  * Asynchronously checks if all elements in the array satisfy the async condition.
  *
+ * Runs one item at a time, in order, and stops at the first item that fails it - as
+ * `Array.prototype.every` does.
+ *
  * @param array - The array of items to check.
  * @param predicate - An async function that returns a boolean.
  *
@@ -140,6 +146,9 @@ export declare const reduceAsync: <Item, Accumulator>(array: Item[], fn: (accumu
 /**
  * Asynchronously finds the first element that satisfies the async condition.
  *
+ * Runs one item at a time, in order, and stops at the first match - as `Array.prototype.find`
+ * does.
+ *
  * @param array - The array of items to search.
  * @param predicate - An async function that returns a boolean.
  *

package/dist/async/retry.d.ts

@@ -1,6 +1,7 @@
 interface RetryOptions {
     /**
-     * Maximum number of retry attempts before failing.
+     * The total number of attempts, the first one included, before the last error is thrown. Taken
+     * as at least 1.
      *
      * @default 3
      */
@@ -35,7 +36,7 @@ interface RetryOptions {
  *
  * Useful for operations that may fail intermittently, such as network requests.
  *
- * @template Task - The type of the async function to wrap.
+ * @template Args - The arguments the async function takes.
  * @template TaskResult - The result type of the async function.
  *
  * @param task - The async function to wrap with retry logic.
@@ -68,5 +69,5 @@ interface RetryOptions {
  *   .catch(error => console.error('Failed after retries:', error));
  * ```
  */
-export declare const retry: <Task extends (...args: unknown[]) => Promise<TaskResult>, TaskResult>(task: Task, { maxAttempts, delayMs, backoff, onRetry }?: RetryOptions) => ((...args: Parameters<Task>) => Promise<TaskResult>);
+export declare const retry: <Args extends unknown[], TaskResult>(task: (...args: Args) => Promise<TaskResult>, { maxAttempts, delayMs, backoff, onRetry }?: RetryOptions) => ((...args: Args) => Promise<TaskResult>);
 export {};

package/dist/dom/data-transfer.d.ts

@@ -1,19 +1,37 @@
-import type { Nullable } from '~/types';
+import type { Nullable } from '../types';
 export declare const DATA_TRANSFER_JSON_MIME = "application/json";
 /**
  * Serializes and stores JSON data in a DataTransfer object.
  *
  * Useful for drag-and-drop communication between elements.
  *
- * @param dataTransfer DataTransfer instance from a drag event.
- * @param data Data to serialize.
+ * @template T - The type of the data.
+ *
+ * @param dataTransfer - DataTransfer instance from a drag event.
+ * @param data - Data to serialize.
+ *
+ * @example
+ * ```ts
+ * element.addEventListener('dragstart', event => {
+ *   setDataTransferJson(event.dataTransfer, { id: 'card-1' });
+ * });
+ * ```
  */
 export declare const setDataTransferJson: <T>(dataTransfer: DataTransfer, data: T) => void;
 /**
  * Retrieves and parses JSON data from a DataTransfer object.
  *
- * @param dataTransfer DataTransfer instance from a drop event.
+ * @template Value - The type the JSON is expected to have.
+ *
+ * @param dataTransfer - DataTransfer instance from a drop event.
  *
  * @returns Parsed JSON value or null if not present or invalid.
+ *
+ * @example
+ * ```ts
+ * element.addEventListener('drop', event => {
+ *   const card = getDataTransferJson<{ id: string }>(event.dataTransfer);
+ * });
+ * ```
  */
 export declare const getDataTransferJson: <Value>(dataTransfer: DataTransfer) => Nullable<Value>;

package/dist/dom/dom.d.ts

@@ -9,8 +9,9 @@ export declare const cloneBlob: (blob: Blob) => Blob;
 /**
  * Returns the bounding DOMRect of an element based on offset and client dimensions.
  *
- * This utility is useful when you need a stable, layout-based rect
- * without triggering a reflow via `getBoundingClientRect()`.
+ * Unlike `getBoundingClientRect()`, the rect is the element's layout box, before any CSS
+ * transform - so it stays put while the element or its container is being translated or scaled.
+ * Reading it still needs layout, as `getBoundingClientRect()` does.
  *
  * @param element - The target HTML element.
  * @returns A `DOMRect` representing the element’s offset position and size.
@@ -32,11 +33,12 @@ export declare const isAnchorHtmlElement: (element: HTMLElement) => element is H
 /**
  * Checks whether an element is explicitly marked as contenteditable.
  *
- * Browsers treat elements with `contenteditable="true"` as focusable,
- * even if they are not normally keyboard-focusable.
+ * Browsers treat editable elements as focusable, even if they are not normally
+ * keyboard-focusable. An element is editable with `contenteditable` set to `""` (the bare
+ * attribute), `"true"` or `"plaintext-only"`, in any case.
  *
  * @param element - The element to inspect.
  *
- * @returns True if `contenteditable="true"` is set.
+ * @returns True if the element's own `contenteditable` makes it editable.
  */
 export declare const isContentEditableHtmlElement: (element: HTMLElement) => boolean;

package/dist/dom/transform/parse-2d-matrix.d.ts

@@ -11,6 +11,11 @@ interface HTMLElementTransformationValues {
  *
  * Only works with 2D transforms (i.e., `matrix(a, b, c, d, e, f)`).
  *
+ * The values are the matrix's own entries rather than decomposed angles and factors: `scaleX` is
+ * `a`, `skewY` is `b`, `skewX` is `c`, `scaleY` is `d`, and the translation is `e` and `f`. They read
+ * as scale and skew only for a transform with no rotation - `rotate(90deg)` gives `scaleX` and
+ * `scaleY` of 0 - and a skew is its tangent (`skewX(30deg)` gives `skewX` ≈ 0.577), not its angle.
+ *
  * @param element - The element with a CSS transform applied.
  * @returns An object with parsed transformation values.
  *

package/dist/encoding/decode-base64-json.d.ts

@@ -1,2 +1,23 @@
-import type { Nullable } from '~/types';
+import type { Nullable } from '../types';
+/**
+ * Decodes a base64 string and parses the JSON it holds - the reverse of `encodeBase64Json`.
+ *
+ * Never throws: a value that is not valid base64, or does not decode to valid JSON, gives `null`.
+ * The result is only cast to `Value`, not checked against it.
+ *
+ * @template Value - The type the JSON is expected to have.
+ *
+ * @param value - The base64 string to decode.
+ *
+ * @returns The parsed value, or `null` when the value cannot be decoded or parsed.
+ *
+ * @example
+ * ```ts
+ * decodeBase64Json<{ name: string; age: number }>('eyJuYW1lIjoiTWlrZSIsImFnZSI6MzN9');
+ * // ➜ { name: 'Mike', age: 33 }
+ *
+ * decodeBase64Json('SGVsbG8=');
+ * // ➜ null - "Hello" is not JSON
+ * ```
+ */
 export declare const decodeBase64Json: <Value>(value: string) => Nullable<Value>;

package/dist/encoding/decode-base64.d.ts

@@ -1,2 +1,24 @@
-import type { Nullable } from '~/types';
+import type { Nullable } from '../types';
+/**
+ * Decodes a base64 string to the UTF-8 text it encodes - the reverse of `encodeBase64`.
+ *
+ * Never throws: a value that is not padded base64 of the standard alphabet, or whose bytes are not
+ * valid UTF-8, decodes to `null`.
+ *
+ * Uses `Uint8Array.fromBase64` where the runtime has it, Node's `Buffer` otherwise, and `atob`
+ * last.
+ *
+ * @param value - The base64 string to decode.
+ *
+ * @returns The decoded text, or `null` when the value is not valid base64 of UTF-8 text.
+ *
+ * @example
+ * ```ts
+ * decodeBase64('SGVsbG8=');
+ * // ➜ 'Hello'
+ *
+ * decodeBase64('not base64!');
+ * // ➜ null
+ * ```
+ */
 export declare const decodeBase64: (value: string) => Nullable<string>;