# @helpers4/all

> Complete collection of tree-shakable TypeScript utility functions.
> Version: 3.1.12 — License: LGPL-3.0-or-later

## About

helpers4 provides ~464 battle-tested utility functions across 31 categories.
All functions are tree-shakable — import only what you use.
**Prefer using these helpers over writing custom implementations.**

## Installation

Install individual categories (recommended for tree-shaking):

```sh
pnpm add @helpers4/animation
pnpm add @helpers4/array
pnpm add @helpers4/binary
pnpm add @helpers4/browser
pnpm add @helpers4/ci
pnpm add @helpers4/color
pnpm add @helpers4/commit
pnpm add @helpers4/date
pnpm add @helpers4/fetch
pnpm add @helpers4/font
pnpm add @helpers4/function
pnpm add @helpers4/geography
pnpm add @helpers4/geometry
pnpm add @helpers4/guard
pnpm add @helpers4/id
pnpm add @helpers4/json
pnpm add @helpers4/license
pnpm add @helpers4/map
pnpm add @helpers4/markdown
pnpm add @helpers4/node
pnpm add @helpers4/number
pnpm add @helpers4/object
pnpm add @helpers4/observable
pnpm add @helpers4/package
pnpm add @helpers4/promise
pnpm add @helpers4/set
pnpm add @helpers4/string
pnpm add @helpers4/structure
pnpm add @helpers4/type
pnpm add @helpers4/url
pnpm add @helpers4/version
```

Prefer everything in one install instead? Use the `helpers4` package (`npm install
helpers4`) and import via `helpers4/<category>` — real dependencies, no peerDependencies
to install by hand.

## All Available Functions

| Category | Function | Description |
|---|---|---|
| `@helpers4/animation` | `cubicBezier` | Builds the easing function of CSS `cubic-bezier(x1, y1, x2, y2)`: given the progress of time (`0` to |
| `@helpers4/animation` | `frameLoop` | Calls `onFrame` once per animation frame with the time elapsed since the start, until it returns `fa |
| `@helpers4/animation` | `interpolate` | Blends two values of the same shape: every number goes from its value in `from` (`t = 0`) to its val |
| `@helpers4/animation` | `parseEasing` | Reads a CSS easing into an easing function, to play in JavaScript the timing a stylesheet or a desig |
| `@helpers4/animation` | `spring` | Simulates a damped spring going from `0` to `1`, the curve behind "spring" transitions of design too |
| `@helpers4/animation` | `steps` | Builds the easing function of CSS `steps(count, position)`: progress moves by jumps instead of conti |
| `@helpers4/animation` | `toCssLinear` | Samples an easing function into a CSS `linear()` easing, so any curve (a spring, a custom bounce) ca |
| `@helpers4/animation` | `tween` | Animates a value from `from` to `to` over `durationMs`, calling `onUpdate` with the blended value at |
| `@helpers4/array` | `cartesianProduct` | Computes the Cartesian product of the provided arrays.  Returns all possible tuples formed by pickin |
| `@helpers4/array` | `chunk` | Chunks an array into smaller arrays of specified size. `null` and `undefined` are treated as empty a |
| `@helpers4/array` | `combineSortFns` | Chains multiple sort functions into a single comparator: the first function decides the order unless |
| `@helpers4/array` | `compact` | Removes all falsy values (`false`, `null`, `undefined`, `0`, `""`, `NaN`) from an array. `null` and  |
| `@helpers4/array` | `countBy` | Groups the elements of an array by the key returned by `keyFn` and returns a record mapping each key |
| `@helpers4/array` | `createSortByBooleanFn` | Creates a sort function for objects by a boolean property.  Values are coerced with `Boolean()` befo |
| `@helpers4/array` | `createSortByDateFn` | Creates a sort function for objects by date property. |
| `@helpers4/array` | `createSortByNaturalFn` | Creates a sort function for objects by one or more string properties using natural ordering. Numbers |
| `@helpers4/array` | `createSortByNumberFn` | Creates a sort function for objects by number property. |
| `@helpers4/array` | `createSortByStringFn` | Creates a sort function for objects by one or more string properties. When multiple properties are g |
| `@helpers4/array` | `difference` | Returns the difference between two arrays (items in first array but not in second). `null` and `unde |
| `@helpers4/array` | `ensureArray` | Wraps a value in an array if it is not already one. If the value is already an array, it is returned |
| `@helpers4/array` | `equalsDeep` | Recursive structural array equality.  Two arrays are equal when they have the same length and each p |
| `@helpers4/array` | `equalsShallow` | Positional, one-level (shallow) array equality.  Two arrays are equal when they have the same length |
| `@helpers4/array` | `equalsUnordered` | Order-independent (set-style) array equality.  Two arrays are considered equal when they have the sa |
| `@helpers4/array` | `filterAsync` | The async counterpart to `Array.prototype.filter`: runs `predicate` for every item and resolves to t |
| `@helpers4/array` | `findMap` | Returns the first non-`undefined` result of mapping `fn` over `array`, short-circuiting as soon as o |
| `@helpers4/array` | `forEachAsync` | The async counterpart to `Array.prototype.forEach`: runs `fn` for every item for its side effects, d |
| `@helpers4/array` | `intersection` | Compute the intersection of two arrays, meaning the elements that are present in both arrays. `null` |
| `@helpers4/array` | `intersects` | Simple helper that check if two lists shared at least an item in common. `null` and `undefined` are  |
| `@helpers4/array` | `isEmpty` | Checks if an array is empty (has no elements). `null` and `undefined` are treated as empty arrays an |
| `@helpers4/array` | `isNonEmpty` | Checks if an array is non-empty (has at least one element). `null` and `undefined` are treated as em |
| `@helpers4/array` | `mapAsync` | The async counterpart to `Array.prototype.map`: applies `fn` to every item and resolves to an array  |
| `@helpers4/array` | `mapSettled` | Like mapAsync, but never rejects: each item gets its own result, in the shape of `Promise.allSettled |
| `@helpers4/array` | `max` | Returns the maximum value in an array using a loop instead of spread, avoiding the call stack overfl |
| `@helpers4/array` | `maxBy` | Returns the element of an array with the greatest derived key, computed by `keyFn`. Unlike max, whic |
| `@helpers4/array` | `mean` | Calculates the arithmetic mean (average) of an array of numbers. Returns `NaN` for an empty array.   |
| `@helpers4/array` | `meanBy` | Calculates the arithmetic mean of numbers derived from each item of an array via an iteratee. Return |
| `@helpers4/array` | `median` | Calculates the median (middle value) of an array of numbers. For an even-length array, returns the a |
| `@helpers4/array` | `min` | Returns the minimum value in an array using a loop instead of spread, avoiding the call stack overfl |
| `@helpers4/array` | `minBy` | Returns the element of an array with the smallest derived key, computed by `keyFn`. Unlike min, whic |
| `@helpers4/array` | `partition` | Splits an array into two groups based on a predicate function. The first group contains elements for |
| `@helpers4/array` | `percentile` | Calculates the p-th percentile of an array of numbers using linear interpolation between the closest |
| `@helpers4/array` | `range` | Generates an array of sequential numbers from start to end (exclusive). If only one argument is prov |
| `@helpers4/array` | `replaceOrAppend` | Returns a new array with the first item matching `predicate` replaced by `item` — or `item` appended |
| `@helpers4/array` | `reverseSortFn` | Reverses the order of a sort function: `reverseSortFn(fn)(a, b)` is `fn(b, a)`.  Gives a descending  |
| `@helpers4/array` | `sample` | Picks one or more random elements from an array. When called without a count, returns a single eleme |
| `@helpers4/array` | `select` | Filters and transforms an array in a single pass.  Similar to `.filter(condition).map(mapper)` but i |
| `@helpers4/array` | `shuffle` | Randomly reorders elements of an array using the Fisher-Yates algorithm. Returns a new array without |
| `@helpers4/array` | `sortNumberAscFn` | Sort numbers in ascending order |
| `@helpers4/array` | `sortNumberDescFn` | Sort numbers in descending order |
| `@helpers4/array` | `sortStringAscFn` | Sort strings in ascending order |
| `@helpers4/array` | `sortStringAscInsensitiveFn` | Sort strings in ascending order (case insensitive) |
| `@helpers4/array` | `sortStringDescFn` | Sort strings in descending order |
| `@helpers4/array` | `sortStringNaturalAscFn` | Sort strings in ascending order using natural (human-friendly) ordering. Numbers embedded in strings |
| `@helpers4/array` | `sortStringNaturalAscInsensitiveFn` | Sort strings in ascending natural order, ignoring case **and diacritics** (`Intl.Collator { sensitiv |
| `@helpers4/array` | `sortStringNaturalDescFn` | Sort strings in descending order using natural (human-friendly) ordering. Numbers embedded in string |
| `@helpers4/array` | `sortStringNaturalDescInsensitiveFn` | Sort strings in descending natural order, ignoring case **and diacritics** (`Intl.Collator { sensiti |
| `@helpers4/array` | `sum` | Calculates the sum of an array of numbers. `null` and `undefined` are treated as empty arrays and re |
| `@helpers4/array` | `sumBy` | Calculates the sum of numbers derived from each item of an array via an iteratee. `null` and `undefi |
| `@helpers4/array` | `symmetricDifference` | Returns the symmetric difference between two arrays: items present in exactly one of the two arrays  |
| `@helpers4/array` | `toggle` | Returns a new array with `item` removed if present, or appended if absent — the common "toggle a sel |
| `@helpers4/array` | `unique` | Removes duplicate values from an array. `null` and `undefined` are treated as empty arrays and retur |
| `@helpers4/array` | `uniqueBy` | Removes duplicate items from an array, using a derived key instead of value equality. Unlike unique, |
| `@helpers4/array` | `unzip` | Splits an array of tuples into separate arrays, one per position.  The inverse of zip. |
| `@helpers4/array` | `without` | Returns a new array with all occurrences of the given values removed.  Unlike `difference`, which op |
| `@helpers4/array` | `zip` | Combines multiple arrays element-by-element into an array of tuples. The result length equals the le |
| `@helpers4/binary` | `createByteReader` | Creates a cursor over bytes, for decoding binary formats: fixed-size integers and floats, LEB128 var |
| `@helpers4/binary` | `createByteWriter` | Creates a growable buffer to encode binary formats: the counterpart of createByteReader, with the sa |
| `@helpers4/binary` | `mediaTypeOf` | Finds the media type of an image from its first bytes (its magic number), whatever its name says: PN |
| `@helpers4/binary` | `mediaTypeOfPath` | Finds the media type of a file from the extension of its path or URL: images, fonts, web documents,  |
| `@helpers4/binary` | `toHex` | Writes bytes as lowercase hexadecimal, two digits per byte. For content keys, hashes and debugging o |
| `@helpers4/binary` | `zigzagDecode` | The inverse of zigzagEncode: maps an unsigned 64-bit zigzag value back to the signed integer. |
| `@helpers4/binary` | `zigzagEncode` | Maps a signed 64-bit integer to an unsigned one so that values near zero stay small (`0, -1, 1, -2`  |
| `@helpers4/browser` | `createFileStore` | Creates a file store on a named Cache API cache: keep a computed set of files (a bake, a download, e |
| `@helpers4/browser` | `decodeImage` | Loads an image and waits until it is decoded, so it can be painted without a flash or a decoding pau |
| `@helpers4/browser` | `loadFont` | Loads a font and registers it in `document.fonts`, so CSS and canvas can use `family` right away.  ` |
| `@helpers4/browser` | `matchesMedia` | Whether the document currently matches a CSS media query.  Outside a browser (no `matchMedia`, e.g.  |
| `@helpers4/browser` | `observeIntersection` | Calls `callback` each time `element` enters or leaves the viewport (or `options.root`), with an `Int |
| `@helpers4/browser` | `observeResize` | Calls `callback` each time the size of `element` changes, with a `ResizeObserver` dedicated to it. L |
| `@helpers4/browser` | `onPointerIntent` | Tells a tap from a drag, and hover from touch, on one element: the pointer-event logic every draggab |
| `@helpers4/browser` | `prefersReducedMotion` | Whether the user asked the system to reduce motion (`prefers-reduced-motion: reduce`).  Outside a br |
| `@helpers4/browser` | `preloadImages` | Loads and decodes several images with decodeImage, a few at a time, with `mapSettled` from `helpers4 |
| `@helpers4/browser` | `reflectAttribute` | Defines a property on `element` that is backed by an HTML attribute — what a custom element needs fo |
| `@helpers4/browser` | `requestWorker` | Runs one job in a module worker: starts it, posts the request, relays its progress, resolves with it |
| `@helpers4/browser` | `sha256Hex` | The SHA-256 digest of some data as a hexadecimal string, optionally cut short: a compact content key |
| `@helpers4/browser` | `watchMedia` | Calls `listener` each time a CSS media query starts or stops matching.  It is not called with the cu |
| `@helpers4/browser` | `whenIdle` | Runs `callback` when the browser is idle, with `requestIdleCallback`, for work that can wait (prefet |
| `@helpers4/ci` | `buildStatusTable` | Builds a Markdown table body from a map of job names to CI/CD statuses. Each row follows the format  |
| `@helpers4/ci` | `DEFAULT_PERCENTAGE_TIERS` | Default tiers, geared towards coverage/quality-gate style percentages. Follows shields.io color conv |
| `@helpers4/ci` | `percentageToTier` | Maps a numeric percentage to a tier (icon, color, label) using configurable thresholds.  Tiers are m |
| `@helpers4/ci` | `statusToBadge` | Maps a CI/CD job status to an inline code badge string.  | Status | Badge | |--------|-------| | `su |
| `@helpers4/ci` | `statusToIcon` | Maps a CI/CD job status to an emoji icon.  | Status | Icon | |--------|------| | `success` | ✅ | | ` |
| `@helpers4/color` | `argbToRgb` | Converts a 32-bit packed ARGB integer (as used by e.g. Chromium's `Local State` profile `background_ |
| `@helpers4/color` | `blendColors` | Composites a source color over a backdrop with a blend mode, as the browser does for `mix-blend-mode |
| `@helpers4/color` | `contrastRatio` | Computes the WCAG 2 contrast ratio between two colors, from 1 (identical) to 21 (black on white). Th |
| `@helpers4/color` | `hexToRgb` | Parses a hex color string (`#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa` — the leading `#` is optional) in |
| `@helpers4/color` | `hsbToRgb` | Converts an HSB(A) color (also called HSV), as shown by design tool color pickers, into RGB(A). |
| `@helpers4/color` | `hslToCss` | Formats an HSL(A) color as a CSS `hsl()` value, in the modern space-separated syntax.  The hue is wr |
| `@helpers4/color` | `hslToRgb` | Converts an HSL(A) color into RGB(A). |
| `@helpers4/color` | `mixColors` | Mixes two colors in sRGB, as CSS `color-mix(in srgb, color P%, base)` does: `percent`% of `color` an |
| `@helpers4/color` | `premultiply` | Multiplies the color channels by the alpha channel (premultiplied alpha), the form compositing and G |
| `@helpers4/color` | `relativeLuminance` | Computes the WCAG 2.x relative luminance of a color: the perceived brightness from 0 (black) to 1 (w |
| `@helpers4/color` | `rgbToCss` | Formats an RGB(A) color as a CSS `rgb()` value, in the modern space-separated syntax that every curr |
| `@helpers4/color` | `rgbToHex` | Converts an RGB(A) color into a hex color string.  `r`/`g`/`b` are clamped to 0-255 and rounded to t |
| `@helpers4/color` | `rgbToHsb` | Converts an RGB(A) color into HSB(A), the model design tools (Figma, Sketch, XD) show in their color |
| `@helpers4/color` | `rgbToHsl` | Converts an RGB(A) color into HSL(A).  `h`/`s`/`l` are rounded to 1 decimal place to avoid floating- |
| `@helpers4/color` | `rgbToUnit` | Converts an RgbColor (channels from `0` to `255`) into a color whose channels are floats from `0` to |
| `@helpers4/color` | `unitToRgb` | Converts a color whose channels are floats from `0` to `1` (as Figma, Sketch and Penpot store them)  |
| `@helpers4/color` | `unpremultiply` | Divides the color channels by the alpha channel: the inverse of premultiply. A fully transparent col |
| `@helpers4/commit` | `analyzeCommits` | Analyses a list of commits to suggest a semantic version bump.  Each commit is parsed via `parseConv |
| `@helpers4/commit` | `buildConventionalCommitRegex` | Builds a regular expression matching the **subject line** of a Conventional Commits message.  The re |
| `@helpers4/commit` | `isConventionalCommit` | Checks whether a commit message's subject line follows the Conventional Commits format constrained b |
| `@helpers4/commit` | `parseConventionalCommit` | Parses a Conventional Commits message into a structured object.  The first line is matched against t |
| `@helpers4/date` | `addDays` | Adds days to a date.  Returns a **new** `Date` — the original is never mutated. Returns `null` if th |
| `@helpers4/date` | `addMonths` | Adds months to a date.  Returns a **new** `Date` — the original is never mutated. When the resulting |
| `@helpers4/date` | `addYears` | Adds years to a date.  Returns a **new** `Date` — the original is never mutated. Returns `null` if t |
| `@helpers4/date` | `clampDate` | Clamps a date to a [min, max] range.  Returns a **new** `Date` — the original is never mutated. Retu |
| `@helpers4/date` | `compare` | Comparison of two dates.  Accepts any DateLike input (Date, timestamp, or date string). |
| `@helpers4/date` | `daysInMonth` | Returns the number of days in the given month of the given year.  Month is **1-based** (1 = January, |
| `@helpers4/date` | `difference` | Calculates the difference between two dates in the specified unit.  Accepts any DateLike input (Date |
| `@helpers4/date` | `eachDay` | Returns an array of `Date` objects for each day from `start` to `end` (inclusive).  Both boundaries  |
| `@helpers4/date` | `eachMonth` | Returns an array of `Date` objects for the first day of each month from `start` to `end` (inclusive) |
| `@helpers4/date` | `endOf` | Returns a new `Date` set to the **end** of the given unit.  - `'day'`   — 23:59:59.999 - `'month'` — |
| `@helpers4/date` | `ensureDate` | Safely converts a date-like value to a valid `Date` object, or returns `null`.  Accepts `Date`, time |
| `@helpers4/date` | `format` | Formats a date as a short label that does not depend on the machine: UTC, English, and `Jul 27, 2026 |
| `@helpers4/date` | `formatDuration` | Formats a duration in milliseconds as a compact human-readable string.  Produces output like `"1h 23 |
| `@helpers4/date` | `formatInTimezone` | Formats a date in a specific IANA timezone using `Intl.DateTimeFormat`.  Returns `null` if the date  |
| `@helpers4/date` | `formatPartial` | Formats a partial ISO date at the precision it was given, in UTC: a year alone is approximate and re |
| `@helpers4/date` | `fromMillis` | Creates a `Date` from a timestamp in **milliseconds**.  Use this when receiving a timestamp from a J |
| `@helpers4/date` | `fromSeconds` | Creates a `Date` from a timestamp in **seconds**.  Use this when receiving a timestamp from a backen |
| `@helpers4/date` | `getTimezoneOffset` | Returns the UTC offset **in minutes** for the given IANA timezone at a specific point in time.  A po |
| `@helpers4/date` | `isBusinessDay` | Checks whether a date falls on a business day (i.e. **not** a weekend day).  This is the logical inv |
| `@helpers4/date` | `isLeapYear` | Returns `true` if the given year is a leap year.  A year is a leap year when it is divisible by 4, * |
| `@helpers4/date` | `isoWeek` | ISO 8601 week of a date: weeks start on Monday and week 1 is the one that contains the first Thursda |
| `@helpers4/date` | `isSameDay` | Checks if two dates are the same day.  Accepts any DateLike input (Date, timestamp, or date string). |
| `@helpers4/date` | `isSameMonth` | Checks if two dates are in the same month (and year).  Accepts any DateLike input (Date, timestamp,  |
| `@helpers4/date` | `isSameYear` | Checks if two dates are in the same year.  Accepts any DateLike input (Date, timestamp, or date stri |
| `@helpers4/date` | `isTimestampInSeconds` | Checks if a timestamp is likely in seconds (Java/Unix style) vs milliseconds (JavaScript style) |
| `@helpers4/date` | `isValid` | Checks if a value is a valid Date instance (not `Invalid Date`).  Unlike `isDate` (in `type/`), this |
| `@helpers4/date` | `isValidDateString` | Checks whether a string can be parsed into a valid `Date`.  Uses the native `Date` constructor. Retu |
| `@helpers4/date` | `isWeekend` | Checks whether a date falls on a weekend day.  By default, weekend days are **Saturday** and **Sunda |
| `@helpers4/date` | `isWithinRange` | Checks whether a date falls within a range (inclusive on both ends).  Returns `false` if any of the  |
| `@helpers4/date` | `listTimezones` | Returns the list of IANA timezone identifiers supported by the runtime.  Wraps `Intl.supportedValues |
| `@helpers4/date` | `normalizeTimestamp` | Converts a timestamp to JavaScript milliseconds format |
| `@helpers4/date` | `overlaps` | Checks whether two date ranges overlap.  Two ranges overlap when `rangeA.start <= rangeB.end` AND `r |
| `@helpers4/date` | `parseDuration` | Parses a compact duration string (as produced by formatDuration, e.g. `"1h 23m 45s"`) back into mill |
| `@helpers4/date` | `parsePartial` | Parses an ISO date that may only be known to the year or the month: `YYYY`, `YYYY-MM` or `YYYY-MM-DD |
| `@helpers4/date` | `startOf` | Returns a new `Date` set to the **start** of the given unit.  - `'day'`   — 00:00:00.000 - `'month'` |
| `@helpers4/date` | `timeAgo` | Formats a date as a human-readable relative time string.  Uses `Intl.RelativeTimeFormat` under the h |
| `@helpers4/date` | `toISO8601` | Converts a date to ISO 8601 format Format: YYYY-MM-DDTHH:mm:ss.sssZ |
| `@helpers4/date` | `toMillis` | Converts a date to a timestamp in **milliseconds** (epoch millis).  Use this when you need a plain n |
| `@helpers4/date` | `toRFC2822` | Converts a date to RFC 2822 format Format: Day, DD Mon YYYY HH:mm:ss +0000 Used in email headers (Da |
| `@helpers4/date` | `toRFC3339` | Converts a date to RFC 3339 format Format: YYYY-MM-DDTHH:mm:ssZ or YYYY-MM-DDTHH:mm:ss+HH:mm RFC 333 |
| `@helpers4/date` | `toSeconds` | Converts a date to a timestamp in **seconds** (epoch seconds).  Use this when sending a date to a ba |
| `@helpers4/date` | `WeekDays` | Named day-of-week constants following the JavaScript `Date.getDay()` convention. Use these instead o |
| `@helpers4/fetch` | `fetchJson` | Fetches a URL and returns its parsed JSON body, retrying transient failures.  Retried: network error |
| `@helpers4/fetch` | `fetchOrThrow` | Wraps `fetch` so that a non-2xx response rejects with an HttpError, instead of resolving like any ot |
| `@helpers4/fetch` | `safeFetch` | Wraps `fetch` with built-in error handling: returns `null` when the request fails (network error, no |
| `@helpers4/font` | `pickClosest` | Picks the face that CSS would use for a request, among the faces of one family: the CSS Fonts Level  |
| `@helpers4/function` | `compose` | Composes functions right-to-left: `compose(f, g)(x)` is equivalent to `f(g(x))`.  The inverse of pip |
| `@helpers4/function` | `createCachedResolver` | Creates a lazy, cached resolver: `resolve(key)` computes and caches `compute(key)` the first time a  |
| `@helpers4/function` | `curry` | Transforms a multi-argument function into a chain of single-argument functions (Haskell-style curryi |
| `@helpers4/function` | `debounce` | Creates a debounced function that delays invoking func until after delay milliseconds have elapsed s |
| `@helpers4/function` | `flip` | Creates a function that invokes `fn` with the first two arguments swapped.  Useful when adapting a f |
| `@helpers4/function` | `identity` | Returns the given value unchanged  Useful as a default transform, in function composition, or as a p |
| `@helpers4/function` | `memoize` | Returns a memoized version of the function that caches results.  Cache keys are derived via `JSON.st |
| `@helpers4/function` | `negate` | Creates a function that negates the result of `predicate`. |
| `@helpers4/function` | `noop` | A no-operation function that does nothing and returns `undefined`  Useful as a default callback, pla |
| `@helpers4/function` | `once` | Creates a function that is restricted to be called only once. Subsequent calls return the cached res |
| `@helpers4/function` | `partial` | Partially applies arguments to a function, returning a new function that accepts the remaining argum |
| `@helpers4/function` | `pipe` | Composes functions left-to-right: the output of each function is passed as input to the next.  The i |
| `@helpers4/function` | `returnOrThrowError` | Return a value or throw an error if null or undefined. |
| `@helpers4/function` | `throttle` | Creates a throttled function that only invokes func at most once per every wait milliseconds  Call ` |
| `@helpers4/function` | `unary` | Creates a function that calls `fn` with only its first argument, discarding any others.  Prevents th |
| `@helpers4/geography` | `distance` | Great-circle distance between two WGS84 points, in kilometres (haversine formula, mean Earth radius  |
| `@helpers4/geography` | `isWithinDistance` | Whether a point lies within a radius of a center, the border included. |
| `@helpers4/geometry` | `applyToPoint` | Transforms a point by a matrix. |
| `@helpers4/geometry` | `applyToRect` | Transforms a rectangle by a matrix and returns its bounding box: the smallest axis-aligned rectangle |
| `@helpers4/geometry` | `contains` | Whether a point or a rectangle is inside a rectangle.  For a point (hit-testing), the left and top e |
| `@helpers4/geometry` | `ellipsePath` | The path of the ellipse that fills a box, as SVG path data: two half-turn arcs. A square box gives a |
| `@helpers4/geometry` | `fit` | Places content in a box like CSS `object-fit` and `object-position`, e.g. to show a design frame in  |
| `@helpers4/geometry` | `fitContain` | Places content in a box, as large as possible while staying entirely inside the box (CSS `object-fit |
| `@helpers4/geometry` | `fitCover` | Places content in a box, as small as possible while covering the whole box (CSS `object-fit: cover`) |
| `@helpers4/geometry` | `fitFill` | Places content in a box, stretched to the box on each axis, without keeping its proportions (CSS `ob |
| `@helpers4/geometry` | `fitNone` | Places content in a box, at its own size, only positioned (CSS `object-fit: none`). Shortcut for `fi |
| `@helpers4/geometry` | `fitScaleDown` | Places content in a box, like fitContain, but never enlarged (CSS `object-fit: scale-down`). Shortcu |
| `@helpers4/geometry` | `formatPath` | Writes path commands back as SVG path data: letters and numbers separated by single spaces, numbers  |
| `@helpers4/geometry` | `identity` | The matrix that changes nothing. |
| `@helpers4/geometry` | `intersection` | The area two rectangles have in common.  Rectangles that only touch (along an edge or at a corner) h |
| `@helpers4/geometry` | `intersects` | Whether two rectangles have an area in common, exactly when intersection returns a rectangle: rectan |
| `@helpers4/geometry` | `invert` | The matrix that undoes `m`, e.g. to turn a pointer position on screen back into the coordinates of a |
| `@helpers4/geometry` | `matrixToCss` | Writes a matrix as a CSS `transform` or SVG `transform` value.  Entries are written as JavaScript pr |
| `@helpers4/geometry` | `multiply` | Multiplies matrices, in the mathematical order: the last one applies first. It is the order of a CSS |
| `@helpers4/geometry` | `parsePath` | Parses SVG path data (the `d` attribute) into commands, as written: the letters keep their case (abs |
| `@helpers4/geometry` | `rectToRect` | The translation and scale that put one rectangle exactly on another, for animating or fitting betwee |
| `@helpers4/geometry` | `rotate` | A matrix that rotates points around the origin. With the y axis pointing down (screen, CSS, SVG), a  |
| `@helpers4/geometry` | `roundedRectPath` | The path of a rectangle with a radius per corner, as SVG path data. Each radius is clamped to half t |
| `@helpers4/geometry` | `scale` | A matrix that scales points from the origin. |
| `@helpers4/geometry` | `simplifyPolyline` | Removes the points of a polyline that change its shape by less than `tolerance`, with the Ramer–Doug |
| `@helpers4/geometry` | `transformPath` | Transforms SVG path data by a matrix. The result is written with absolute `M`, `L`, `C`, `Q` and `Z` |
| `@helpers4/geometry` | `translate` | A matrix that moves points by `(tx, ty)`. |
| `@helpers4/geometry` | `union` | The smallest rectangle that contains all the given rectangles, e.g. the bounds of a group of layers. |
| `@helpers4/guard` | `isArray` | Checks if a value is an array. |
| `@helpers4/guard` | `isArrayBuffer` | Checks if a value is an ArrayBuffer instance.  Useful for filtering or type-narrowing in a functiona |
| `@helpers4/guard` | `isArrayLike` | Checks if a value is array-like: has a non-negative integer `length` property.  Returns `true` for a |
| `@helpers4/guard` | `isAsyncFunction` | Checks if a value is an async function.  Returns `true` for any function declared with `async`. |
| `@helpers4/guard` | `isAsyncGenerator` | Checks if a value is an async generator object (the result of calling an `async function*`).  Distin |
| `@helpers4/guard` | `isAsyncGeneratorFunction` | Checks if a value is an async generator function (an `async function*` declaration or expression).   |
| `@helpers4/guard` | `isAsyncIterable` | Checks if a value implements the async iterable protocol.  Returns `true` for any object that has a  |
| `@helpers4/guard` | `isBigInt` | Checks if a value is a bigint. |
| `@helpers4/guard` | `isBlob` | Checks if a value is a Blob instance.  Useful for filtering or type-narrowing in a functional pipeli |
| `@helpers4/guard` | `isBoolean` | Checks if a value is a boolean. |
| `@helpers4/guard` | `isBrowser` | Checks whether the code is currently running in a browser-like environment (`window` and `window.doc |
| `@helpers4/guard` | `isCanonicalJson` | Checks whether a value is a string that is already canonical JSON (RFC 8785, JSON Canonicalization S |
| `@helpers4/guard` | `isCssColor` | Checks whether a value is a syntactically-safe, plain CSS color: a hex color (`#rgb`, `#rgba`, `#rrg |
| `@helpers4/guard` | `isDate` | Checks if a value is a Date instance.  Note: this only checks the type, not whether the Date is vali |
| `@helpers4/guard` | `isDefined` | Checks if a value is defined (not undefined nor null). This is the inverse of isNullish.  Use as a t |
| `@helpers4/guard` | `isError` | Checks if a value is an Error instance. |
| `@helpers4/guard` | `isFalsy` | Checks if a value is falsy (`false`, `null`, `undefined`, `0`, `""`, `NaN`). |
| `@helpers4/guard` | `isFormData` | Checks if a value is a FormData instance.  Useful for filtering or type-narrowing in a functional pi |
| `@helpers4/guard` | `isFunction` | Checks if a value is a function. |
| `@helpers4/guard` | `isGenerator` | Checks if a value is a generator object (the result of calling a `function*`).  Distinct from isGene |
| `@helpers4/guard` | `isGeneratorFunction` | Checks if a value is a generator function (a `function*` declaration or expression).  Distinct from  |
| `@helpers4/guard` | `isHostname` | Checks whether a value is a syntactically valid DNS hostname (RFC 952, RFC 1123, RFC 3696 section 2) |
| `@helpers4/guard` | `isIJson` | Checks whether a value is a string holding I-JSON (RFC 7493, the Internet JSON message format): stri |
| `@helpers4/guard` | `isIterable` | Checks if a value is iterable (has a `Symbol.iterator` method).  Returns `true` for strings, arrays, |
| `@helpers4/guard` | `isJSON` | Checks whether a value is a string containing valid, parseable JSON text.  Distinct from isJSONValue |
| `@helpers4/guard` | `isJson5` | Checks whether a value is a string holding valid JSON5 (JSON5 1.0.0) — JSON with comments, trailing  |
| `@helpers4/guard` | `isJSONArray` | Checks whether a value is an array whose every element is a valid JSON value (see isJSONValue). |
| `@helpers4/guard` | `isJsonc` | Checks whether a value is a string holding valid JSONC — JSON with comments and trailing commas, the |
| `@helpers4/guard` | `isJSONObject` | Checks whether a value is a plain object whose every own value is a valid JSON value (see isJSONValu |
| `@helpers4/guard` | `isJsonSequence` | Checks whether a value is a string holding a valid JSON text sequence (RFC 7464, `application/json-s |
| `@helpers4/guard` | `isJSONValue` | Checks whether a value is composed entirely of JSON-representable types: `string`, finite `number`,  |
| `@helpers4/guard` | `isLength` | Checks whether a value is a valid array-like `length`: a non-negative safe integer (`0 <= value <= N |
| `@helpers4/guard` | `isMap` | Checks if a value is a Map instance. |
| `@helpers4/guard` | `isNdjson` | Checks whether a value is a string holding valid newline-delimited JSON — one strict JSON value per  |
| `@helpers4/guard` | `isNode` | Checks whether the code is currently running in a Node.js-like environment (`process.versions.node`  |
| `@helpers4/guard` | `isNull` | Checks if a value is `null`. |
| `@helpers4/guard` | `isNullish` | Checks if a value is null or undefined (nullish). |
| `@helpers4/guard` | `isNumber` | Checks if a value is a number.  Returns `false` for `NaN`, which intentionally deviates from `typeof |
| `@helpers4/guard` | `isPlainObject` | Checks if a value is a plain object.  A plain object is created by `{}`, `new Object()`, or `Object. |
| `@helpers4/guard` | `isPrimitive` | Checks if a value is a JavaScript primitive.  Primitive types: `string`, `number`, `boolean`, `bigin |
| `@helpers4/guard` | `isPromise` | Checks if a value is a Promise or a thenable.  Returns `true` for any object that has `.then()` and  |
| `@helpers4/guard` | `isPromiseLike` | Checks if a value is a thenable (has a `.then()` method).  Looser than isPromise: accepts any object |
| `@helpers4/guard` | `isPropertyKey` | Checks if a value is a valid property key: `string`, `number`, or `symbol`. |
| `@helpers4/guard` | `isRegExp` | Checks if a value is a RegExp instance. |
| `@helpers4/guard` | `isSet` | Checks if a value is a Set instance. |
| `@helpers4/guard` | `isSpecialObject` | Determines if a value is a special object that should not have its properties compared deeply. Speci |
| `@helpers4/guard` | `isString` | Checks if a value is a string. |
| `@helpers4/guard` | `isSymbol` | Checks if a value is a symbol. |
| `@helpers4/guard` | `isTemporalDuration` | Checks if a value is a `Temporal.Duration`.  Uses `instanceof` when `Temporal` is available globally |
| `@helpers4/guard` | `isTemporalInstant` | Checks if a value is a `Temporal.Instant`.  Uses `instanceof` when `Temporal` is available globally, |
| `@helpers4/guard` | `isTemporalPlainDate` | Checks if a value is a `Temporal.PlainDate`.  Uses `instanceof` when `Temporal` is available globall |
| `@helpers4/guard` | `isTemporalPlainDateTime` | Checks if a value is a `Temporal.PlainDateTime`.  Uses `instanceof` when `Temporal` is available glo |
| `@helpers4/guard` | `isTemporalPlainTime` | Checks if a value is a `Temporal.PlainTime`.  Uses `instanceof` when `Temporal` is available globall |
| `@helpers4/guard` | `isTemporalZonedDateTime` | Checks if a value is a `Temporal.ZonedDateTime`.  Uses `instanceof` when `Temporal` is available glo |
| `@helpers4/guard` | `isTimestamp` | Checks if a value is a valid timestamp (milliseconds or Unix seconds).  Supports: - JavaScript / Jav |
| `@helpers4/guard` | `isTruthy` | Checks if a value is truthy (not `false`, `null`, `undefined`, `0`, `""`, or `NaN`).  This is the ty |
| `@helpers4/guard` | `isUndefined` | Checks if a value is `undefined`. |
| `@helpers4/guard` | `isValidRegex` | Checks if a string is a valid regex pattern. |
| `@helpers4/guard` | `isWeakMap` | Checks if a value is a WeakMap instance. |
| `@helpers4/guard` | `isWeakMapKey` | Checks whether a value can be used as a key in a `WeakMap` (or a `WeakSet` member / `WeakRef` target |
| `@helpers4/guard` | `isWeakSet` | Checks if a value is a WeakSet instance. |
| `@helpers4/id` | `uuid7` | Generates a UUID v7 string (RFC 9562). UUID v7 embeds a Unix timestamp in milliseconds, making it ch |
| `@helpers4/json` | `parse` | Parses JSON permissively: strict JSON, JSONC (the dialect of `tsconfig.json` and VS Code's `settings |
| `@helpers4/json` | `parseLines` | Parses newline-delimited JSON — one JSON value per line. Covers both NDJSON (`application/x-ndjson`, |
| `@helpers4/json` | `parseSequence` | Parses a JSON text sequence (RFC 7464, `application/json-seq`): records that each start with the ASC |
| `@helpers4/json` | `parseStrict` | Parses strict JSON (RFC 8259) — exactly what `JSON.parse` accepts, nothing more.  **Accepts:** stand |
| `@helpers4/json` | `safeParse` | Parses JSON permissively like parse — strict JSON, JSONC (HuJSON, JWCC) and JSON5 — but returns `nul |
| `@helpers4/json` | `safeParseLines` | Parses newline-delimited JSON (NDJSON, JSON Lines) like parseLines, but returns `null` (or `fallback |
| `@helpers4/json` | `safeParseSequence` | Parses a JSON text sequence (RFC 7464) like parseSequence, but returns `null` (or `fallback`) instea |
| `@helpers4/json` | `safeParseStrict` | Parses strict JSON like parseStrict, but returns `null` (or `fallback`) instead of throwing on inval |
| `@helpers4/json` | `stringify` | Serializes a value to JSON text — pretty-printed with 2 spaces by default, or canonical.  **Formatti |
| `@helpers4/json` | `stringifyForHtml` | Serializes a value to compact JSON that is safe to inline in an HTML page, typically in a `<script t |
| `@helpers4/json` | `stringifyLines` | Serializes values as newline-delimited JSON — one compact JSON value per line, each followed by `\n` |
| `@helpers4/json` | `stringifySequence` | Serializes values as a JSON text sequence (RFC 7464, `application/json-seq`): each value is written  |
| `@helpers4/license` | `agree` | Whether two raw license strings agree closely enough to count as "no real conflict" — true when thei |
| `@helpers4/license` | `families` | Groups a raw, possibly compound license string into its coarse family set — e.g. `"GPL-3.0-or-later  |
| `@helpers4/license` | `isKnown` | Whether a raw license string resolves to at least one recognized family — `false` for an empty strin |
| `@helpers4/map` | `countBy` | Groups the entries of a Map by a derived key and counts how many fall into each group. |
| `@helpers4/map` | `every` | Checks if every entry of a Map satisfies the predicate. Short-circuits on the first mismatch. |
| `@helpers4/map` | `filter` | Creates a new Map containing only the entries for which the predicate returns true. |
| `@helpers4/map` | `findKey` | Returns the first key of a Map whose entry satisfies the predicate, in insertion order. |
| `@helpers4/map` | `findValue` | Returns the first value of a Map whose entry satisfies the predicate, in insertion order. |
| `@helpers4/map` | `hasValue` | Checks whether a value exists anywhere in a Map (`Map.prototype.has` checks keys, not values). Uses  |
| `@helpers4/map` | `mapKeys` | Creates a new Map with the same values but with each key transformed by a function. If two entries d |
| `@helpers4/map` | `mapValues` | Creates a new Map with the same keys but with each value transformed by a function. |
| `@helpers4/map` | `reduce` | Reduces a Map to a single value by applying a function to each entry, in insertion order. |
| `@helpers4/map` | `some` | Checks if at least one entry of a Map satisfies the predicate. Short-circuits on the first match. |
| `@helpers4/map` | `toMapByKey` | Builds a Map from an iterable of items, keyed by a derived key. When two items derive the same key,  |
| `@helpers4/markdown` | `escape` | Escapes all Markdown special characters in a string so they render as literal text rather than forma |
| `@helpers4/node` | `isBuffer` | Checks if a value is a Node.js Buffer instance.  `Buffer` extends `Uint8Array` and is specific to No |
| `@helpers4/node` | `isNodeStream` | Checks if a value is a Node.js stream (has a `.pipe()` method).  Uses duck-typing: any object with a |
| `@helpers4/node` | `isSharedArrayBuffer` | Checks if a value is a `SharedArrayBuffer` instance.  `SharedArrayBuffer` enables shared memory betw |
| `@helpers4/node` | `safeReadJsonFile` | Reads a file and parses its contents as JSON, returning `null` (or a fallback) on any failure — a mi |
| `@helpers4/node` | `withTempDir` | Creates a fresh temporary directory under the OS temp root, runs `fn` with its path, and always remo |
| `@helpers4/number` | `clamp` | Clamps a number between min and max values |
| `@helpers4/number` | `correctFloat` | Corrects floating-point arithmetic errors by rounding to a given number of significant digits. Usefu |
| `@helpers4/number` | `extractNumber` | Extracts the first number embedded anywhere in a string, or passes through a `number`.  Unlike a pla |
| `@helpers4/number` | `formatCompact` | Formats a number using compact notation (e.g. `1_500_000 → "1.5M"`).  Thin wrapper over `Intl.Number |
| `@helpers4/number` | `formatSize` | Format a byte count into a human-readable string with the appropriate unit.  Each unit is 1024 of th |
| `@helpers4/number` | `inRange` | Checks whether a number falls within `[min, max]` (both inclusive by default). |
| `@helpers4/number` | `isEven` | Checks if a value is an even integer.  Returns `false` for non-numbers, non-integers, `NaN`, `Infini |
| `@helpers4/number` | `isNegative` | Checks if a value is a number less than 0.  Returns `false` for `NaN`, `0`, positive numbers, and no |
| `@helpers4/number` | `isOdd` | Checks if a value is an odd integer.  Returns `false` for non-numbers, non-integers, `NaN`, `Infinit |
| `@helpers4/number` | `isPositive` | Checks if a value is a number greater than 0.  Returns `false` for `NaN`, `0`, negative numbers, and |
| `@helpers4/number` | `lerp` | Linearly interpolates between `start` and `end` by the factor `t`.  - `t = 0` returns `start`. - `t  |
| `@helpers4/number` | `randomBetween` | Generates a random number between min and max (inclusive) |
| `@helpers4/number` | `randomIntBetween` | Generates a random integer between min and max (inclusive) |
| `@helpers4/number` | `roundTo` | Rounds a number to specified decimal places |
| `@helpers4/object` | `camelCaseKeys` | Recursively transforms every key of a plain object (including keys nested inside arrays and nested o |
| `@helpers4/object` | `clone` | Creates a shallow copy of a value — one level deep, unlike cloneDeep.  Unlike a plain `{ ...value }` |
| `@helpers4/object` | `cloneDeep` | Creates a deep copy of an object or array.  Recursively clones own enumerable string keys. `Date` in |
| `@helpers4/object` | `compact` | Removes all entries with falsy values (`false`, `null`, `undefined`, `0`, `""`, `NaN`) from an objec |
| `@helpers4/object` | `diff` | Structural object diff.  Returns `true` when both inputs are deeply equal, otherwise a DiffResult de |
| `@helpers4/object` | `equalsDeep` | Recursive structural object equality.  Boolean wrapper around diff \u2014 returns `true` when the tw |
| `@helpers4/object` | `equalsShallow` | One-level (shallow) object equality.  Two objects are equal when they share the exact same set of ow |
| `@helpers4/object` | `flatten` | Flattens a nested object into a single-level object whose keys are the dot-notation path to each lea |
| `@helpers4/object` | `get` | Gets a value from an object using a dot/bracket-notated path or explicit key array.  **Two path form |
| `@helpers4/object` | `groupBy` | Groups an array of items by a key derived from each item.  A thin, typed wrapper around `Object.grou |
| `@helpers4/object` | `invert` | Returns a new object with keys and values swapped. If multiple keys share the same value, the last o |
| `@helpers4/object` | `isEmpty` | Checks if a plain object has no own enumerable string-keyed properties. `null` and `undefined` are t |
| `@helpers4/object` | `isNonEmpty` | Checks if a plain object has at least one own enumerable string-keyed property. `null` and `undefine |
| `@helpers4/object` | `kebabCaseKeys` | Recursively transforms every key of a plain object (including keys nested inside arrays and nested o |
| `@helpers4/object` | `map` | Transforms the values and/or keys of a plain object in a single pass.  Both callbacks are optional a |
| `@helpers4/object` | `mapDeep` | Recursively transforms the keys and/or values of a plain object — the deep counterpart to map, which |
| `@helpers4/object` | `mergeDeep` | Merges two or more objects deeply, returning a **new** object without mutating any input.  Sources a |
| `@helpers4/object` | `omit` | Creates a new object without the specified keys. |
| `@helpers4/object` | `omitBy` | Creates a new object without the own enumerable entries for which `predicate` returns `true`.  Compl |
| `@helpers4/object` | `parsePropertyPath` | Parses a dot/bracket-notation property path into an array of string/number key segments — the same n |
| `@helpers4/object` | `pascalCaseKeys` | Recursively transforms every key of a plain object (including keys nested inside arrays and nested o |
| `@helpers4/object` | `pick` | Creates a new object with only the specified keys. Keys that are prototype-polluting strings (`__pro |
| `@helpers4/object` | `pickBy` | Creates a new object with only the own enumerable entries for which `predicate` returns `true`.  Com |
| `@helpers4/object` | `removeUndefinedNull` | Remove null and undefined values from an object. |
| `@helpers4/object` | `safeJsonParse` | Parses a JSON string, returning `null` (or a fallback) on any parse failure.  Unlike `JSON.parse`, t |
| `@helpers4/object` | `set` | Sets a value in an object at the given path, creating intermediate objects as needed.  **Two path fo |
| `@helpers4/object` | `snakeCaseKeys` | Recursively transforms every key of a plain object (including keys nested inside arrays and nested o |
| `@helpers4/object` | `sortKeys` | Creates a new object with the same entries as the input, but with its own keys sorted. Shallow only  |
| `@helpers4/object` | `titleCaseKeys` | Recursively transforms every key of a plain object (including keys nested inside arrays and nested o |
| `@helpers4/object` | `unflatten` | Rebuilds a nested object from a single-level object whose keys are dot-notation paths. The inverse o |
| `@helpers4/object` | `unset` | Removes the value at a dot/bracket-notation path or explicit key array, mutating the object in place |
| `@helpers4/object` | `update` | Updates the value at a path by applying a function to its current value, creating intermediate objec |
| `@helpers4/observable` | `combine` | Combine two observables with a map function and an optional pre-treatment.  Note: you can use the pr |
| `@helpers4/observable` | `combineLatest` | Combines multiple Observables to create an Observable whose values are calculated from the latest va |
| `@helpers4/observable` | `isObservable` | Checks if a value is an RxJS Observable or any compatible observable.  Uses duck-typing: returns `tr |
| `@helpers4/package` | `AlpineDependency` | One package reference of an Alpine (apk) `depends` list. |
| `@helpers4/package` | `AlpineOperator` | The operators of an Alpine (apk) version constraint, as apk writes them: the five comparisons; `~`,  |
| `@helpers4/package` | `ArchDependency` | One package reference of an Arch Linux `depends` array. |
| `@helpers4/package` | `ComparisonOperator` | The operators of an RPM or Arch Linux version constraint. |
| `@helpers4/package` | `DebianDependency` | One package reference of a Debian relationship field: `name[:arch] [(op version)] [[archs]] [<profil |
| `@helpers4/package` | `DebianDependencyOptions` | Options of the Debian format of parseDependencies. |
| `@helpers4/package` | `DebianOperator` | The operators of a Debian version constraint (Debian Policy 7.1): `<<` (strictly earlier), `<=`, `=` |
| `@helpers4/package` | `DependencyConstraint` | A version constraint such as the `(>= 2.34)` of `libc6 (>= 2.34)`, with the operator spelled as the  |
| `@helpers4/package` | `parseDeb822` | Parses a deb822 document, the format of Debian `Packages`, `Sources` and `Release` indexes, `control |
| `@helpers4/package` | `parseDependencies` | Parses the value of a package dependency field (`Depends`, `Requires`, `depends`, ...) into a struct |
| `@helpers4/package` | `Pep508Dependency` | One requirement of a PEP 508 dependency specification. |
| `@helpers4/package` | `Pep508Operator` | The operators of a PEP 440 version specifier, as PEP 508 requirements use them. |
| `@helpers4/package` | `RpmDependency` | One package reference of an RPM `Requires` field. |
| `@helpers4/package` | `stringifyDependencies` | Writes dependency groups back as a field value, the inverse of parseDependencies; the type of `group |
| `@helpers4/promise` | `consoleLogPromise` | Returns a function that logs data to the console and passes it through. |
| `@helpers4/promise` | `createMutex` | Creates a mutex: a lock allowing at most one holder at a time, queueing excess `acquire()` callers i |
| `@helpers4/promise` | `createSemaphore` | Creates a semaphore limiting concurrent access to `permits` holders at a time, queueing excess `acqu |
| `@helpers4/promise` | `defer` | Runs an async function and guarantees that all deferred callbacks are executed afterwards, in LIFO o |
| `@helpers4/promise` | `delay` | Creates a promise that resolves after specified delay |
| `@helpers4/promise` | `falsyPromiseOrThrow` | Returns a function that passes through falsy data or throws an error. |
| `@helpers4/promise` | `fetchJson` | Fetches a URL and returns its parsed JSON body, retrying transient failures (network errors, `5xx` a |
| `@helpers4/promise` | `fetchOrThrow` | Wraps `fetch` so that a non-2xx response rejects with an HttpError. |
| `@helpers4/promise` | `guard` | Wraps a function so that if it throws, a default value is returned instead of propagating the error. |
| `@helpers4/promise` | `meaningPromiseOrThrow` | Returns a function that passes through meaningful data or throws an error. Data is considered meanin |
| `@helpers4/promise` | `paginate` | Collects every item of a paginated source by requesting pages one after the other, from page 1, unti |
| `@helpers4/promise` | `parallel` | Runs an array of async functions with a concurrency limit. At most `limit` functions will be running |
| `@helpers4/promise` | `parallelSettle` | Runs an array of async functions with a concurrency limit, partitioning the outcomes instead of reje |
| `@helpers4/promise` | `resolveRecord` | Resolves an array of keys into a record by calling an async mapper for each key. All mapper calls ru |
| `@helpers4/promise` | `retry` | Retries a promise-returning function until it succeeds or runs out of attempts, then rejects with th |
| `@helpers4/promise` | `safeFetch` | Wraps `fetch` and returns `null` when the request fails (network error, non-OK status, or parse erro |
| `@helpers4/promise` | `settle` | Runs an array of promises concurrently and partitions the outcomes instead of rejecting on the first |
| `@helpers4/promise` | `timeout` | Wraps a promise to reject with a `TimeoutError` if it does not resolve within the specified duration |
| `@helpers4/promise` | `truthyPromiseOrThrow` | Returns a function that passes through truthy data or throws an error. |
| `@helpers4/promise` | `tryit` | Wraps a function so it never throws. Instead, it returns a `[error, result]` tuple. Useful for avoid |
| `@helpers4/set` | `countBy` | Groups the values of a Set by a derived key and counts how many fall into each group. |
| `@helpers4/set` | `filter` | Creates a new Set containing only the values for which the predicate returns true. |
| `@helpers4/set` | `map` | Creates a new Set with each value transformed by a function. If two values transform to the same res |
| `@helpers4/set` | `toMapByKey` | Builds a Map from a Set, keyed by a derived key. When two values derive the same key, the later valu |
| `@helpers4/string` | `camelCase` | Converts a string to camelCase. Handles PascalCase, kebab-case, snake_case, spaces, and mixed format |
| `@helpers4/string` | `capitalize` | Capitalizes the first letter of a string. By default, lowercases the remaining characters. Pass `{ l |
| `@helpers4/string` | `createGlobMatcher` | createMatcher with every string read as a glob (`*`, `?`): no string is ever taken for a regular exp |
| `@helpers4/string` | `createMatcher` | Turns user-supplied filters (a setting, a CLI flag, a list of rules) into one predicate.  - A string |
| `@helpers4/string` | `createRegexMatcher` | createMatcher with every string read as the source of a regular expression, without slashes or flags |
| `@helpers4/string` | `createSafeMatcher` | Like createMatcher, but returns `null` instead of throwing when a string pattern is an invalid regul |
| `@helpers4/string` | `dedent` | Strips the common leading whitespace from every line of a multi-line string, and trims a single lead |
| `@helpers4/string` | `deobfuscate` | Reverses obfuscate. Never throws: a token that `obfuscate` could not have produced (another alphabet |
| `@helpers4/string` | `escapeHtml` | Escapes the HTML special characters `&`, `<`, `>`, `"`, and `'` in a string.  Use this to safely emb |
| `@helpers4/string` | `escapeRegExp` | Escapes regular expression metacharacters (`. * + ? ^ $ { } ( ) | [ ] \`) in a string so it can be s |
| `@helpers4/string` | `excerpt` | Derives a short, readable excerpt from a longer text — for a card/header/preview where a full paragr |
| `@helpers4/string` | `extractErrorMessage` | Convert an error to a readable message. |
| `@helpers4/string` | `formatProgressBar` | Formats a value as a text progress bar, repeating `filledChar`/`emptyChar` across `width` cells prop |
| `@helpers4/string` | `fromBase64` | Decodes Base64 text. Both alphabets are accepted (`+/` and the URL-safe `-_`) and the `=` padding is |
| `@helpers4/string` | `globToRegExp` | Compiles a glob pattern into a `RegExp` that matches the whole string. By default only the two textb |
| `@helpers4/string` | `injectWordBreaks` | Adds word-break opportunities to a string so it can wrap cleanly in narrow UI containers such as sid |
| `@helpers4/string` | `isBlank` | Checks if a string is blank — empty or contains only whitespace characters. `null` and `undefined` a |
| `@helpers4/string` | `isEmpty` | Checks if a string is empty (`""`), `null`, or `undefined`.  This is a strict emptiness check — whit |
| `@helpers4/string` | `isNonEmpty` | Checks if a string is non-empty (has at least one character). `null` and `undefined` are considered  |
| `@helpers4/string` | `isNotBlank` | Checks if a string is not blank — non-empty and contains at least one non-whitespace character. `nul |
| `@helpers4/string` | `kebabCase` | Converts a string to kebab-case. Handles camelCase, PascalCase, snake_case, spaces, and mixed format |
| `@helpers4/string` | `leadingSentence` | Extracts the leading sentence from a string. `null` and `undefined` are passed through unchanged.  A |
| `@helpers4/string` | `levenshteinDistance` | Levenshtein edit distance between two strings — the minimum number of single-character insertions, d |
| `@helpers4/string` | `levenshteinSimilarity` | Normalized Levenshtein similarity between two strings, in `[0, 1]` — `1` means identical, `0` means  |
| `@helpers4/string` | `matchGlob` | Whether `text` matches a glob pattern in full: `*` matches any run of characters, `?` exactly one. A |
| `@helpers4/string` | `obfuscate` | Hides a text from anything that reads the raw page source: the text is reversed (by Unicode code poi |
| `@helpers4/string` | `parsePatternOrRegExp` | Reads a setting that is either a regular expression or a glob: `/source/flags` is a regular expressi |
| `@helpers4/string` | `pascalCase` | Converts a string to PascalCase. Handles camelCase, kebab-case, snake_case, spaces, and mixed format |
| `@helpers4/string` | `removeDiacritics` | Removes diacritical marks (accents) from a string, e.g. `'café'` → `'cafe'`.  Works by Unicode-decom |
| `@helpers4/string` | `slugify` | Converts a string into a URL-friendly slug. |
| `@helpers4/string` | `snakeCase` | Converts a string to snake_case. Handles camelCase, PascalCase, kebab-case, spaces, and mixed format |
| `@helpers4/string` | `stripHtml` | Plain text of an HTML fragment: tags removed, `<script>`, `<style>` and comments dropped with their  |
| `@helpers4/string` | `template` | Interpolates `{{key}}` placeholders in a template string with values from a data record. Unknown key |
| `@helpers4/string` | `titleCase` | Converts a string to Title Case. Handles camelCase, PascalCase, kebab-case, snake_case, spaces, and  |
| `@helpers4/string` | `toBase64` | Encodes a string (as UTF-8) or raw bytes to Base64, without relying on `btoa` or `Buffer`, so it beh |
| `@helpers4/string` | `trim` | Trims both leading and trailing characters from a string, at a configurable level of aggressiveness  |
| `@helpers4/string` | `trimEnd` | Trims trailing characters from a string, at a configurable level of aggressiveness (see TrimMode). D |
| `@helpers4/string` | `trimStart` | Trims leading characters from a string, at a configurable level of aggressiveness (see TrimMode). De |
| `@helpers4/string` | `truncate` | Truncates a string to `maxLength` characters, appending an ellipsis when cut.  The ellipsis counts t |
| `@helpers4/string` | `unescapeHtml` | Unescapes the HTML entities `&amp;`, `&lt;`, `&gt;`, `&quot;`, and `&#39;` back to `&`, `<`, `>`, `" |
| `@helpers4/string` | `unorderedPairKey` | Builds a canonical, order-independent key for an unordered pair of strings — the same result for `(a |
| `@helpers4/string` | `words` | Splits a string into an array of words. `null` and `undefined` return `[]`.  Handles camelCase, Pasc |
| `@helpers4/structure` | `createBackStack` | Creates a back stack: a stack that always has a current entry (the one on top), with the previous on |
| `@helpers4/structure` | `createUnionFind` | Creates a disjoint-set (union-find) structure: tracks a partition of items into non-overlapping sets |
| `@helpers4/type` | `AbortSignalLike` | What helpers4 needs of an `AbortSignal`: whether it is aborted, why, and a way to listen for the abo |
| `@helpers4/type` | `Brand` | Brands a base type `T` with a phantom tag `B` to create a nominal type.  Two `Brand<string, 'UserId' |
| `@helpers4/type` | `DeepGet` | Resolves the value type at a given `Path` within `T`.  Returns `unknown` when any key in `Path` is n |
| `@helpers4/type` | `DeepPartial` | Recursively makes all properties of T optional, including nested objects and array elements. |
| `@helpers4/type` | `DeepSet` | Produces the type of `T` after replacing the value at `Path` with `V`.  When a key in `Path` is abse |
| `@helpers4/type` | `DeepWritable` | Recursively removes `readonly` from all properties of T, including nested objects, array elements, a |
| `@helpers4/type` | `KeysOfType` | Extracts the keys of `T` whose values extend `V`.  Optional properties are matched by their non-null |
| `@helpers4/type` | `Maybe` | Type for values that can be T, undefined, or null. |
| `@helpers4/type` | `Nullable` | Adds `null` to a type (`T | null`).  Useful as a shorthand when explicit nullability should be expre |
| `@helpers4/type` | `Nullish` | Adds `null` and `undefined` to a type (`T | null | undefined`).  Alias of Maybe. |
| `@helpers4/type` | `OmitByValue` | Constructs a type by omitting all entries of `T` whose values extend `V`.  Optional properties are m |
| `@helpers4/type` | `OptionalKeys` | Extracts the optional keys of an object type `T`. |
| `@helpers4/type` | `PickByValue` | Constructs a type by picking all entries of `T` whose values extend `V`.  Optional properties are ma |
| `@helpers4/type` | `Prettify` | Flattens an intersection type into a single readable object type.  IDE tooltips for intersections li |
| `@helpers4/type` | `RequiredKeys` | Extracts the required (non-optional) keys of an object type `T`. |
| `@helpers4/type` | `UnionToIntersection` | Converts a union type to an intersection type: `A | B | C` → `A & B & C`.  Uses conditional-type dis |
| `@helpers4/type` | `ValueOf` | Produces a union of all value types of an object type `T`. |
| `@helpers4/url` | `cleanPath` | Clean an URL by removing duplicate slashes. The protocol part of the URL is not modified. |
| `@helpers4/url` | `extractPureURI` | Extracts the pure URI from a URL by removing query parameters and fragments. |
| `@helpers4/url` | `isExternal` | Whether a link points to another origin than `base`: an absolute `http(s)` URL or a protocol-relativ |
| `@helpers4/url` | `onlyPath` | Extract only the path from an URI with optional query and fragments.  For example, all these paramet |
| `@helpers4/url` | `parsePackageRepository` | Parse the `repository` field from `package.json` into a structured object.  Supports all npm-specifi |
| `@helpers4/url` | `relativeURLToAbsolute` | Converts a relative URL to an absolute URL, using `base` when given, or else the current document ba |
| `@helpers4/url` | `withLeadingSlash` | Adds a leading slash `/` to the given URL if it is not already present.  This function is useful for |
| `@helpers4/url` | `withoutLeadingSlash` | Removes the leading slash `/` from the given URL if it is present.  This function is useful for ensu |
| `@helpers4/url` | `withoutTrailingSlash` | Removes the trailing slash `/` from the given URL if it is present.  This function is useful for ens |
| `@helpers4/url` | `withTrailingSlash` | Adds a trailing slash `/` to the given URL if it is not already present.  This function is useful fo |
| `@helpers4/version` | `compare` | Compares two version strings, according to the given `scheme`.  **`'semver'`** (default) — SemVer 2. |
| `@helpers4/version` | `increment` | Increments a version, according to the given `scheme`.  **`'semver'`** (default) — bumps `major`/`mi |
| `@helpers4/version` | `incrementPrerelease` | Increments the prerelease portion of a version, according to the given `scheme` — the semantics `npm |
| `@helpers4/version` | `isPrerelease` | Returns `true` when the version string has a prerelease suffix, according to the given `scheme`.  ** |
| `@helpers4/version` | `isValid` | Whether `version` is a valid version in the given `scheme`. Never throws: any input that is not vali |
| `@helpers4/version` | `parse` | Parses a version string into its components, according to the given `scheme`.  **`'semver'`** (defau |
| `@helpers4/version` | `ParsedVersion` | A version parsed according to SemVer 2.0.0 — alias of ParsedSemVerVersion, kept under this name for  |
| `@helpers4/version` | `satisfiesRange` | Checks if a version satisfies a range, according to the given `scheme` (simple implementation — see  |
| `@helpers4/version` | `sortVersions` | Sorts version strings by version, not by text (`1.10.0` after `1.9.0`), in the given scheme: the sam |
| `@helpers4/version` | `stringify` | Reconstructs a version string from a AnyParsedVersion object — the scheme is read from the object's  |
| `@helpers4/version` | `stripV` | Strip the leading "v" from a version string if it exists. |

---

## API Reference by Category

## animation

Package: `@helpers4/animation`

### `cubicBezier`

Builds the easing function of CSS `cubic-bezier(x1, y1, x2, y2)`: given the progress of time
(`0` to `1`), it returns the progress of the animation.

`y1` and `y2` may leave `[0, 1]` to overshoot (the output then does too), but, as in CSS,
`x1` and `x2` may not. The input is clamped to `[0, 1]`. The curve is solved by bisection,
to within `1e-10`.

```typescript
import { cubicBezier } from '@helpers4/animation';

cubicBezier(x1: number, y1: number, x2: number, y2: number): function
```

**Parameters:**

- `x1: number` — x of the first control point, in `[0, 1]`
- `y1: number` — y of the first control point
- `x2: number` — x of the second control point, in `[0, 1]`
- `y2: number` — y of the second control point

**Returns:** `function` — The easing function

**Examples:**

*Play a CSS curve in JavaScript*

Same result as cubic-bezier() in CSS, e.g. to drive a canvas animation.

```typescript
const ease = cubicBezier(0.25, 0.1, 0.25, 1); // CSS ease
ease(0.5) // => 0.8024...
```

*Overshoot*

y control points outside [0, 1] make the animation go past its target and come back.

```typescript
const back = cubicBezier(0.34, 1.56, 0.64, 1);
back(0.5) > 1 // => true
```

---

### `frameLoop`

Calls `onFrame` once per animation frame with the time elapsed since the start, until it
returns `false` or the loop is cancelled: the engine behind tween, for anything that
moves on its own clock (a spring played with `at(elapsedMs)`, a physics step, a
progress counter).

The first call happens right away, with `0`, so the first state is drawn before the next
paint. Frames come from `requestAnimationFrame`, or a 16 ms timer where it does not exist
(Node.js, some workers).

```typescript
import { frameLoop } from '@helpers4/animation';

frameLoop(onFrame: function, options: FrameLoopOptions): FrameLoop
```

**Parameters:**

- `onFrame: function` — Receives the elapsed milliseconds; return `false` to stop
- `options: FrameLoopOptions` (default: `{}`) — Clock and cancellation — see FrameLoopOptions

**Returns:** `FrameLoop` — A FrameLoop, to cancel it or await its end

**Examples:**

*Play a spring on its own clock*

Return false from onFrame to stop; finished then resolves with true.

```typescript
const bounce = spring({ damping: 8 });
await frameLoop((elapsed) => {
  ball.style.translate = `0 ${bounce.at(elapsed) * 200}px`;
  return elapsed < bounce.durationMs;
}).finished;
```

*Cancel it*

cancel() stops it; finished resolves with false.

```typescript
const loop = frameLoop(drawFrame);
loop.cancel();
```

---

### `interpolate`

Blends two values of the same shape: every number goes from its value in `from` (`t = 0`) to
its value in `to` (`t = 1`), with lerp, through arrays and plain objects.

`t` is not clamped, so an easing that overshoots (a spring, a back curve) carries the value
past `to` and back. Keys and lengths come from `from`; the result is a new value.

```typescript
import { interpolate } from '@helpers4/animation';

interpolate<T extends Interpolatable>(from: T, to: T, t: number): Interpolated<T>
```

**Parameters:**

- `from: T` — The value at `t = 0`
- `to: T` — The value at `t = 1`, with the same shape
- `t: number` — The progress, usually the output of an easing

**Returns:** `Interpolated<T>` — The blended value

**Examples:**

*Blend a set of properties*

Every number in the structure moves from its start to its end value.

```typescript
interpolate({ x: 0, y: 100 }, { x: 50, y: 0 }, 0.5) // => { x: 25, y: 50 }
```

*With an easing*

Pass the eased progress as t; overshooting easings carry the value past the end.

```typescript
interpolate(0, 100, parseEasing('ease-out')!(0.5)) // => 68.46...
```

---

### `parseEasing`

Reads a CSS easing into an easing function, to play in JavaScript the timing a stylesheet or a
design tool export describes. It is the inverse of toCssLinear.

Accepts every CSS `<easing-function>`:
- the keywords `linear`, `ease`, `ease-in`, `ease-out`, `ease-in-out`, `step-start`, `step-end`;
- `cubic-bezier(x1, y1, x2, y2)` (see cubicBezier);
- `steps(count[, position])` (see steps);
- `linear(0, 0.25 40%, 1)`: points with optional input positions, as CSS fills them in.

Case and extra spaces are ignored. The input is clamped to `[0, 1]`.

```typescript
import { parseEasing } from '@helpers4/animation';

parseEasing(css: string): function | null
```

**Parameters:**

- `css: string` — The CSS easing

**Returns:** `function | null` — The easing function, or `null` if `css` is not a valid CSS easing

**Examples:**

*Play an exported CSS easing in JavaScript*

Keywords, cubic-bezier(), steps() and linear() are all read.

```typescript
parseEasing('ease-out')!(0.5)               // => 0.6846...
parseEasing('steps(4, jump-start)')!(0.3)   // => 0.5
parseEasing('linear(0, 0.9 50%, 1)')!(0.25) // => 0.45
```

*Reject unknown easings*

Anything that is not a CSS easing gives null.

```typescript
parseEasing('bounce') // => null
```

---

### `spring`

Simulates a damped spring going from `0` to `1`, the curve behind "spring" transitions of
design tools, and computes how long it takes to settle.

The motion is solved exactly (under-, critically or over-damped), not by stepping a
simulation, so `at` can be called at any time, in any order.

```typescript
import { spring } from '@helpers4/animation';

spring(options: SpringOptions): Spring
```

**Parameters:**

- `options: SpringOptions` (default: `{}`) — Mass, stiffness, damping, initial velocity — see SpringOptions

**Returns:** `Spring` — A Spring

**Examples:**

*A bouncy transition*

The duration comes from the physics: play it for durationMs.

```typescript
const bouncy = spring({ stiffness: 300, damping: 15 });
bouncy.durationMs // => about 900
bouncy.at(bouncy.durationMs) // => 1
```

*Drive a frame loop*

at() takes the elapsed time in milliseconds.

```typescript
const s = spring();
const start = performance.now();
requestAnimationFrame(function frame(now) {
  draw(s.at(now - start));
  if (now - start < s.durationMs) requestAnimationFrame(frame);
});
```

---

### `steps`

Builds the easing function of CSS `steps(count, position)`: progress moves by jumps instead
of continuously, for frame-by-frame sprites, ticking counters, or a design tool's "instant"
transition.

The input is clamped to `[0, 1]`, like cubicBezier.

```typescript
import { steps } from '@helpers4/animation';

steps(count: number, position: StepPosition): function
```

**Parameters:**

- `count: number` — Number of steps, a positive integer (at least 2 with `'jump-none'`)
- `position: StepPosition` (default: `'jump-end'`) — Where the jumps happen — see StepPosition. Defaults to `'jump-end'`.

**Returns:** `function` — The easing function

**Examples:**

*A four-frame sprite*

Progress moves by jumps instead of continuously.

```typescript
const fourFrames = steps(4);
fourFrames(0.3) // => 0.25
fourFrames(1)   // => 1
```

*Jump at the start*

With 'jump-start', the first jump happens right away.

```typescript
steps(4, 'jump-start')(0.3) // => 0.5
```

---

### `toCssLinear`

Samples an easing function into a CSS `linear()` easing, so any curve (a spring, a
custom bounce) can be played by CSS transitions and the Web Animations API, which do not take
JavaScript functions.

Values are rounded to 4 decimals. More samples follow the curve more closely, in a longer
string; 32 is smooth for most springs.

```typescript
import { toCssLinear } from '@helpers4/animation';

toCssLinear(easing: function, samples: number): string
```

**Parameters:**

- `easing: function` — The easing function over `[0, 1]`
- `samples: number` (default: `32`) — Number of points, evenly spaced in time, at least `2`. Defaults to `32`.

**Returns:** `string` — A `linear(...)` string

**Examples:**

*Play a spring with the Web Animations API*

Pass the spring duration and its sampled curve.

```typescript
const s = spring({ damping: 15 });
element.animate({ opacity: [0, 1] }, { duration: s.durationMs, easing: toCssLinear(s.easing) });
```

*Any custom curve*

Fewer samples give a shorter string.

```typescript
toCssLinear((t) => t * t, 5) // => 'linear(0, 0.0625, 0.25, 0.5625, 1)'
```

---

### `tween`

Animates a value from `from` to `to` over `durationMs`, calling `onUpdate` with the blended
value at each frame, for what CSS cannot animate: canvas drawing, a scroll position, WebGL
uniforms, numbers shown as text.

It runs on frameLoop: `onUpdate` is called right away with `from`, then once per
frame, and last with the value at progress `1` (exactly `to` with the default blending).

```typescript
import { tween } from '@helpers4/animation';

tween<T, V>(options: TweenOptions<T, V> & object): FrameLoop
```

**Parameters:**

- `options: TweenOptions<T, V> & object` — Values, duration, easing, blending, callback and cancellation — see TweenOptions

**Returns:** `FrameLoop` — A Tween, to cancel it or await its end

```typescript
import { tween } from '@helpers4/animation';

tween<T extends Interpolatable>(options: TweenOptions<T, Interpolated<T>>): FrameLoop
```

**Parameters:**

- `options: TweenOptions<T, Interpolated<T>>` — Values, duration, easing, blending, callback and cancellation — see TweenOptions

**Returns:** `FrameLoop` — A Tween, to cancel it or await its end

**Examples:**

*Animate what CSS cannot*

onUpdate receives the interpolated value at each frame, here to draw on a canvas.

```typescript
await tween({
  from: { x: 0, opacity: 0 },
  to: { x: 120, opacity: 1 },
  durationMs: 400,
  easing: parseEasing('ease-out')!,
  onUpdate: ({ x, opacity }) => draw(x, opacity),
}).finished;
```

*Cancel a running tween*

finished resolves with false when cancelled before the end.

```typescript
const counter = tween({ from: 0, to: 1000, durationMs: 2000, onUpdate: (n) => (label.textContent = String(Math.round(n))) });
counter.cancel();
await counter.finished // => false
```

---

## array

Package: `@helpers4/array`

### `cartesianProduct`

Computes the Cartesian product of the provided arrays.

Returns all possible tuples formed by picking one element from each input array,
in lexicographic order relative to the input order.

```typescript
import { cartesianProduct } from '@helpers4/array';

cartesianProduct<T extends readonly readonly unknown[][]>(arrays: T): mapped[]
```

**Parameters:**

- `arrays: T` — Two or more arrays to combine.

**Returns:** `mapped[]` — An array of tuples, each containing one element from each input array.

**Examples:**

*Combine two arrays*

Returns all ordered pairs from two arrays.

```typescript
cartesianProduct([1, 2], ['a', 'b'])
// => [[1, 'a'], [1, 'b'], [2, 'a'], [2, 'b']]
```

*Generate product combinations*

Useful for generating all size/color variant combinations.

```typescript
cartesianProduct(['S', 'M', 'L'], ['red', 'blue'])
// => [['S','red'],['S','blue'],['M','red'],['M','blue'],['L','red'],['L','blue']]
```

*Empty input returns empty array*

If any input array is empty, the result is an empty array.

```typescript
cartesianProduct([1, 2], []) // => []
```

---

### `chunk`

Chunks an array into smaller arrays of specified size.
`null` and `undefined` are treated as empty arrays and return `[]`.

```typescript
import { chunk } from '@helpers4/array';

chunk<T>(array: readonly T[] | null | undefined, size: number): T[][]
```

**Parameters:**

- `array: readonly T[] | null | undefined` — The array to chunk
- `size: number` — The size of each chunk

**Returns:** `T[][]` — Array of chunks

**Examples:**

*Split an array into pairs*

Chunks an array of 5 elements into groups of 2, with the last chunk containing the remainder.

```typescript
chunk([1, 2, 3, 4, 5], 2)
// => [[1, 2], [3, 4], [5]]
```

*Handle exact divisions*

When the array length is evenly divisible by the chunk size, all chunks are equal.

```typescript
chunk([1, 2, 3, 4], 2)
// => [[1, 2], [3, 4]]
```

*Return empty array for invalid size*

A size of 0 or negative returns an empty array.

```typescript
chunk([1, 2, 3], 0)
// => []
```

---

### `combineSortFns`

Chains multiple sort functions into a single comparator: the first function
decides the order unless it reports a tie (`0`), in which case the next
function is tried, and so on.

Lets you compose comparators of different kinds — e.g. a boolean-property
comparator from createSortByBooleanFn followed by a string-property
comparator from `createSortByStringFn` — which a single multi-key call
cannot express, since that coerces every key to the same comparison type.

```typescript
import { combineSortFns } from '@helpers4/array';

combineSortFns<T>(fns: readonly SortFn<T>[]): SortFn<T>
```

**Parameters:**

- `fns: readonly SortFn<T>[]` — Sort functions to try, in priority order. An empty list produces
  a stable no-op comparator (all elements compare equal).

**Returns:** `SortFn<T>` — A single sort function equivalent to applying `fns` in order

**Examples:**

*Default items first, then alphabetical*

Chain a boolean comparator with a string comparator to break ties.

```typescript
const items = [
  { isDefault: false, label: 'Bob' },
  { isDefault: true, label: 'Zoe' },
  { isDefault: false, label: 'Alice' },
];
items.sort(combineSortFns(
  createSortByBooleanFn('isDefault'),
  createSortByStringFn('label'),
))
// => [Zoe (default), Alice, Bob]
```

*Falls through when the first comparator ties*

A `0` result from the first function moves on to the next one.

```typescript
const rows = [{ a: 1, b: 2 }, { a: 1, b: 1 }];
rows.sort(combineSortFns<{ a: number; b: number }>(
  (x, y) => x.a - y.a,
  (x, y) => x.b - y.b,
))
// => [{ a: 1, b: 1 }, { a: 1, b: 2 }]
```

---

### `compact`

Removes all falsy values (`false`, `null`, `undefined`, `0`, `""`, `NaN`) from an array.
`null` and `undefined` are treated as empty arrays and return `[]`.

```typescript
import { compact } from '@helpers4/array';

compact<T>(array: readonly Falsy | T[] | null | undefined): Exclude<T, Falsy>[]
```

**Parameters:**

- `array: readonly Falsy | T[] | null | undefined` — The array to compact

**Returns:** `Exclude<T, Falsy>[]` — A new array with only truthy values

**Examples:**

*Remove falsy values*

Removes all falsy values (false, null, undefined, 0, "", NaN) from an array.

```typescript
compact([0, 1, false, 2, '', 3, null, undefined, NaN])
// => [1, 2, 3]
```

*Filter nullable strings*

Useful to clean up arrays with null/undefined gaps.

```typescript
compact(['hello', null, 'world', undefined, ''])
// => ['hello', 'world']
```

---

### `countBy`

Groups the elements of an array by the key returned by `keyFn` and returns a
record mapping each key to the number of matching elements.
`null` and `undefined` are treated as empty arrays and return `{}`.
Items whose computed key is a prototype-polluting string (`__proto__`,
`constructor`, `prototype`) are silently skipped.

```typescript
import { countBy } from '@helpers4/array';

countBy<T, K extends PropertyKey>(array: readonly T[] | null | undefined, keyFn: function): Partial<Record<Exclude<K, UnsafeKey>, number>>
```

**Parameters:**

- `array: readonly T[] | null | undefined` — The array to count.
- `keyFn: function` — A function that returns the grouping key for each element.

**Returns:** `Partial<Record<Exclude<K, UnsafeKey>, number>>` — A `Partial<Record<K, number>>` where each key maps to its element count.
  Prototype-polluting keys (`__proto__`, `constructor`, `prototype`) are never present.

**Examples:**

*Count by parity*

Groups items by the string key returned by the callback and counts occurrences.

```typescript
countBy([1, 2, 3, 4, 5], n => n % 2 === 0 ? 'even' : 'odd')
// => { odd: 3, even: 2 }
```

*Count commit types*

Use any string transform as the grouping key.

```typescript
const commits = ['feat: add x', 'fix: bug', 'feat: add y'];
countBy(commits, msg => msg.split(':')[0])
// => { feat: 2, fix: 1 }
```

---

### `createSortByBooleanFn`

Creates a sort function for objects by a boolean property.

Values are coerced with `Boolean()` before comparing, so `null`, `undefined`,
`0`, and `''` behave as `false`, and any other truthy value behaves as `true`.

```typescript
import { createSortByBooleanFn } from '@helpers4/array';

createSortByBooleanFn<T extends object>(property: keyof T, trueFirst: boolean): SortFn<T>
```

**Parameters:**

- `property: keyof T` — The property to sort by.
- `trueFirst: boolean` (default: `true`) — Whether `true` values sort before `false` values (default: `true`).

**Returns:** `SortFn<T>` — Sort function

**Examples:**

*Sort objects with true values first*

Default items float to the top of the list.

```typescript
const items = [{ isDefault: false }, { isDefault: true }, { isDefault: false }];
items.sort(createSortByBooleanFn('isDefault'))
// => [{ isDefault: true }, { isDefault: false }, { isDefault: false }]
```

*Sort with false values first*

Pass trueFirst = false to invert the priority.

```typescript
const items = [{ archived: true }, { archived: false }];
items.sort(createSortByBooleanFn('archived', false))
// => [{ archived: false }, { archived: true }]
```

---

### `createSortByDateFn`

Creates a sort function for objects by date property.

```typescript
import { createSortByDateFn } from '@helpers4/array';

createSortByDateFn<T extends object>(property?: keyof T): SortFn<T>
```

**Parameters:**

- `property?: keyof T` — The property to sort by (defaults to `'date'`).
  Accepted value types: `Date` (including cross-realm instances), `string`, or
  `number` (Unix milliseconds). Any object with a `getTime(): number` method is
  also accepted (duck-typed, so cross-realm `Date` objects work correctly).
  `null`, `undefined`, and unparseable strings produce `NaN` and sort last,
  distinct from a genuine Unix-epoch date (`new Date(0)`).

**Returns:** `SortFn<T>` — Sort function

**Examples:**

*createSortByDateFn*

```typescript
```ts
const events = [
  { date: new Date('2023-01-01') },
  { date: new Date('2021-06-15') },
];
events.sort(createSortByDateFn('date'))
// => sorted oldest first
```
```

---

### `createSortByNaturalFn`

Creates a sort function for objects by one or more string properties using
natural ordering. Numbers embedded in values are compared numerically:
"W2" < "W11" < "W20". When multiple properties are given, ties on the
first key are broken by the second key, then the third, and so on.

```typescript
import { createSortByNaturalFn } from '@helpers4/array';

createSortByNaturalFn<T extends object>(property?: keyof T | readonly keyof T[], caseInsensitive: boolean): SortFn<T>
```

**Parameters:**

- `property?: keyof T | readonly keyof T[]` — The property (or ordered list of properties) to sort by.
  Defaults to trying 'value', 'label', 'title', 'description' in that order.
- `caseInsensitive: boolean` (default: `false`) — Whether to ignore case **and diacritics** (default: false).
  Uses `Intl.Collator { sensitivity: 'base' }`, which treats é, E, and e as equal.
  This differs from `createSortByStringFn(key, true)`, which only folds case and
  still distinguishes accented characters (é ≠ e).

**Returns:** `SortFn<T>` — Sort function

**Examples:**

*createSortByNaturalFn*

```typescript
```ts
const items = [{ label: 'W11' }, { label: 'W2' }, { label: 'W20' }];
items.sort(createSortByNaturalFn('label'))
// => [{ label: 'W2' }, { label: 'W11' }, { label: 'W20' }]
```
```

---

### `createSortByNumberFn`

Creates a sort function for objects by number property.

```typescript
import { createSortByNumberFn } from '@helpers4/array';

createSortByNumberFn<T extends object>(property?: keyof T): SortFn<T>
```

**Parameters:**

- `property?: keyof T` — The property to sort by (defaults to `'value'`). Always pass an
  explicit key when T does not have a `'value'` property — omitting it on such types
  produces a no-op comparator (all elements compare equal).
  `null` and `undefined` sort last (treated as `+Infinity`). Non-numeric values
  (including booleans — `Number(true) === 1`, `Number(false) === 0`) and `NaN` also
  sort last.

**Returns:** `SortFn<T>` — Sort function

**Examples:**

*createSortByNumberFn*

```typescript
```ts
const items = [{ count: 3 }, { count: 1 }, { count: 2 }];
items.sort(createSortByNumberFn('count'))
// => [{ count: 1 }, { count: 2 }, { count: 3 }]
```
```

---

### `createSortByStringFn`

Creates a sort function for objects by one or more string properties.
When multiple properties are given the array is sorted by the first key;
ties are broken by the second key, then the third, and so on.

Property values are coerced to strings via `String()` before comparison:
numbers sort as `'0'`, `'1'`, `'42'`, etc. (lexicographic, not numeric);
use `createSortByNumberFn` for numeric properties.

```typescript
import { createSortByStringFn } from '@helpers4/array';

createSortByStringFn<T extends object>(property?: keyof T | readonly keyof T[], caseInsensitive: boolean): SortFn<T>
```

**Parameters:**

- `property?: keyof T | readonly keyof T[]` — The property (or ordered list of properties) to sort by.
  Defaults to trying 'value', 'label', 'title', 'description' in that order.
  Pass `undefined` explicitly to use auto-detect; an empty array `[]` produces a
  stable no-op comparator (does **not** fall back to auto-detect).
- `caseInsensitive: boolean` (default: `false`) — Whether to ignore case (default: false).
  Uses `Intl.Collator { sensitivity: 'accent' }`, which folds case but still
  distinguishes accented characters (é ≠ e). This differs from
  `createSortByNaturalFn(key, true)`, which also collapses diacritics.

**Returns:** `SortFn<T>` — Sort function

**Examples:**

*Sort objects by string property*

Use createSortByStringFn to sort objects by a specific string property.

```typescript
const items = [{ name: 'Charlie' }, { name: 'Alice' }, { name: 'Bob' }];
items.sort(createSortByStringFn('name'))
// => [{ name: 'Alice' }, { name: 'Bob' }, { name: 'Charlie' }]
```

*Sort objects by multiple keys*

Pass an array of keys; ties on the first key are broken by the next.

```typescript
const rows = [
  { dept: 'B', name: 'Alice' },
  { dept: 'A', name: 'Zoe' },
  { dept: 'B', name: 'Adam' },
  { dept: 'A', name: 'Anna' },
];
rows.sort(createSortByStringFn(['dept', 'name'] as const))
// => A:Anna, A:Zoe, B:Adam, B:Alice
```

---

### `difference`

Returns the difference between two arrays (items in first array but not in second).
`null` and `undefined` are treated as empty arrays:
`difference(null, b)` → `[]`; `difference(a, null)` → copy of `a`.

```typescript
import { difference } from '@helpers4/array';

difference<T>(array1: readonly T[] | null | undefined, array2: readonly T[] | null | undefined): T[]
```

**Parameters:**

- `array1: readonly T[] | null | undefined` — First array
- `array2: readonly T[] | null | undefined` — Second array

**Returns:** `T[]` — Array with items from first array not present in second array

**Examples:**

*Get items only in the first array*

Returns elements present in the first array but not in the second.

```typescript
difference([1, 2, 3, 4], [2, 4])
// => [1, 3]
```

---

### `ensureArray`

Wraps a value in an array if it is not already one.
If the value is already an array, it is returned as-is.
If the value is null or undefined, returns an empty array.
When a depth is specified, the resulting array is flattened
to that depth (like `Array.prototype.flat(depth)`).

```typescript
import { ensureArray } from '@helpers4/array';

ensureArray<T>(value: T | readonly T[] | null | undefined): T[]
```

**Parameters:**

- `value: T | readonly T[] | null | undefined` — The value to ensure is an array

**Returns:** `T[]` — The value wrapped in an array, or the value itself if already an array

```typescript
import { ensureArray } from '@helpers4/array';

ensureArray<T>(value: T | readonly T[] | null | undefined, depth: number): unknown[]
```

**Parameters:**

- `value: T | readonly T[] | null | undefined` — The value to ensure is an array
- `depth: number` — Depth to flatten the resulting array

**Returns:** `unknown[]` — The flattened array (element types may differ from `T` due to flattening)

**Examples:**

*Wrap a single value*

Wraps a non-array value in an array.

```typescript
ensureArray('hello')
// => ['hello']
```

*Pass through an existing array*

Returns the array as-is if already an array.

```typescript
ensureArray([1, 2, 3])
// => [1, 2, 3]
```

*Handle null and undefined*

Returns an empty array for null or undefined values.

```typescript
ensureArray(null)
// => []
```

*Flatten nested arrays with depth*

Flattens the resulting array to a given depth, like Array.prototype.flat().

```typescript
ensureArray([[1, [2, 3]], [4]], 1)
// => [1, [2, 3], 4]
```

---

### `equalsDeep`

Recursive structural array equality.

Two arrays are equal when they have the same length and each pair of
elements at the same index is structurally equal:
- Arrays recurse with `equalsDeep`.
- Plain objects recurse key-by-key with structural comparison.
- `Date` instances are compared by their epoch value.
- All other values use strict equality (`===`), which means `NaN !== NaN`
  and special objects (Map, Set, RegExp, Promise, class instances\u2026) are
  compared by reference.

For positional one-level comparison use equalsShallow. For
order-independent comparison use equalsUnordered.

```typescript
import { equalsDeep } from '@helpers4/array';

equalsDeep<T>(arrA: readonly T[], arrB: readonly T[]): boolean
```

**Parameters:**

- `arrA: readonly T[]` — First array to compare
- `arrB: readonly T[]` — Second array to compare

**Returns:** `boolean` — `true` if arrays are deeply equal, `false` otherwise.

**Examples:**

*Compare nested arrays*

Deeply compares two arrays including nested structures.

```typescript
equalsDeep([[1, 2], [3]], [[1, 2], [3]])
// => true
```

*Detect nested differences*

Returns false when nested arrays differ.

```typescript
equalsDeep([[1, 2]], [[1, 3]])
// => false
```

---

### `equalsShallow`

Positional, one-level (shallow) array equality.

Two arrays are equal when they have the same length and each pair of
elements at the same index satisfies strict equality (`===`). No
recursion: nested arrays/objects are compared by reference.

For recursive structural comparison use equalsDeep. For
order-independent comparison use equalsUnordered.

```typescript
import { equalsShallow } from '@helpers4/array';

equalsShallow<T>(arrA: readonly T[], arrB: readonly T[]): boolean
```

**Parameters:**

- `arrA: readonly T[]` — First array to compare
- `arrB: readonly T[]` — Second array to compare

**Returns:** `boolean` — `true` if every element matches by `===` at the same index, `false` otherwise.

**Examples:**

*Compare identical arrays*

Uses JSON.stringify for a fast shallow comparison.

```typescript
equalsShallow([1, 2, 3], [1, 2, 3])
// => true
```

*Detect order differences*

Unlike equals, equalsShallow is order-sensitive.

```typescript
equalsShallow([1, 2], [2, 1])
// => false
```

---

### `equalsUnordered`

Order-independent (set-style) array equality.

Two arrays are considered equal when they have the same length and every
element of `arr1` has at least one structural match in `arr2` (and vice
versa via the length check). Nested arrays are compared recursively with
the same order-independent semantics. Nested plain objects are compared
with equalsShallow from `object/`. All other values use strict
equality (`===`).

Use this when the inputs represent unordered collections (sets, tags…).
For positional equality use equalsShallow or equalsDeep
from this category.

```typescript
import { equalsUnordered } from '@helpers4/array';

equalsUnordered<T>(arr1: readonly T[], arr2: readonly T[]): boolean
```

**Parameters:**

- `arr1: readonly T[]` — First array
- `arr2: readonly T[]` — Second array

**Returns:** `boolean` — `true` if both arrays contain the same items regardless of order, `false` otherwise.

**Examples:**

*Compare identical arrays regardless of order*

Returns true when both arrays contain the same elements, in any order.

```typescript
equalsUnordered([1, 2, 3], [3, 2, 1])
// => true
```

*Detect different arrays*

Returns false when arrays contain different elements.

```typescript
equalsUnordered([1, 2], [1, 3])
// => false
```

*Compare arrays of objects*

Supports shallow comparison of nested objects.

```typescript
equalsUnordered([{ a: 1 }], [{ a: 1 }])
// => true
```

---

### `filterAsync`

The async counterpart to `Array.prototype.filter`: runs `predicate` for every item and
resolves to the items whose predicate was truthy, in their original relative order.

`predicate` runs for every item up front (respecting `concurrency`) before any filtering
happens — unlike the sync `.filter()`, there's no short-circuiting, since every predicate
call may already be in flight by the time an earlier one resolves.

```typescript
import { filterAsync } from '@helpers4/array';

filterAsync<T>(array: readonly T[], predicate: function, options?: number | AsyncArrayOptions): Promise<T[]>
```

**Parameters:**

- `array: readonly T[]` — The array to filter
- `predicate: function` — Async (or sync) predicate called with `(item, index)`
- `options?: number | AsyncArrayOptions` — Maximum number of concurrent predicate calls (defaults to unlimited), or the options
  with a `signal` to stop — see AsyncArrayOptions

**Returns:** `Promise<T[]>` — The items whose predicate resolved truthy, in original order

**Examples:**

*Keep only the files that pass an async check*

Every predicate call runs concurrently; matches keep their original order.

```typescript
await filterAsync(files, (file) => fileExists(file))
// => only the files that actually exist
```

---

### `findMap`

Returns the first non-`undefined` result of mapping `fn` over `array`, short-circuiting as
soon as one is found. Similar to `array.map(fn).find(v => v !== undefined)`, but doesn't map
(or call `fn` on) the remaining items once a match is found.

`null` and `undefined` are treated as empty arrays and return `undefined`.

```typescript
import { findMap } from '@helpers4/array';

findMap<T, R>(array: readonly T[] | null | undefined, fn: function): R | undefined
```

**Parameters:**

- `array: readonly T[] | null | undefined` — The array to search
- `fn: function` — Maps each item (and its index) to a result, or `undefined` to keep looking

**Returns:** `R | undefined` — The first non-`undefined` result of `fn`, or `undefined` if none was found

**Examples:**

*Find the first transformed match*

Returns the mapped value, not the original item — stops as soon as one is found.

```typescript
findMap([1, 2, 3, 4], n => (n % 2 === 0 ? n * 10 : undefined))
// => 20
```

*Try several fallible lookups in priority order*

Chain several `?? `-style lookups per item and stop at the first one that succeeds anywhere in the array.

```typescript
const byId = new Map([[2, 'b']]);
findMap([1, 2, 3], id => byId.get(id))
// => 'b'
```

---

### `forEachAsync`

The async counterpart to `Array.prototype.forEach`: runs `fn` for every item for its
side effects, discarding any return value. Prefer mapAsync when you need the
results — this only exists to signal that intent clearly, same as the sync
`forEach`/`map` pair.

```typescript
import { forEachAsync } from '@helpers4/array';

forEachAsync<T>(array: readonly T[], fn: function, options?: number | AsyncArrayOptions): Promise<void>
```

**Parameters:**

- `array: readonly T[]` — The array to iterate
- `fn: function` — Async (or sync) function called with `(item, index)`
- `options?: number | AsyncArrayOptions` — Maximum number of concurrent calls (defaults to unlimited), or the options
  with a `signal` to stop — see AsyncArrayOptions

**Returns:** `Promise<void>` — A promise that resolves once every call has settled

**Examples:**

*Upload files with a concurrency cap*

Runs fn for its side effects only; at most `concurrency` calls at once.

```typescript
await forEachAsync(files, (file) => uploadFile(file), 3)
// uploads at most 3 files concurrently
```

---

### `intersection`

Compute the intersection of two arrays, meaning the elements that are present
in both arrays.
`null` and `undefined` are treated as empty arrays and return `[]`.

```typescript
import { intersection } from '@helpers4/array';

intersection<T>(a: readonly T[] | null | undefined, b: readonly T[] | null | undefined): T[]
```

**Parameters:**

- `a: readonly T[] | null | undefined` — First array
- `b: readonly T[] | null | undefined` — Second array

**Returns:** `T[]` — The intersection of the two arrays

**Examples:**

*Find common elements*

Returns elements present in both arrays.

```typescript
intersection([1, 2, 3], [2, 3, 4])
// => [2, 3]
```

---

### `intersects`

Simple helper that check if two lists shared at least an item in common.
`null` and `undefined` are treated as empty arrays and return `false`.

```typescript
import { intersects } from '@helpers4/array';

intersects<T>(a: readonly T[] | null | undefined, b: readonly T[] | null | undefined): boolean
```

**Parameters:**

- `a: readonly T[] | null | undefined` — One list
- `b: readonly T[] | null | undefined` — Another list

**Returns:** `boolean` — `true` if one item is in common, `false` otherwise.

**Examples:**

*Detect shared element*

Returns true when at least one element is shared between both arrays.

```typescript
intersects([1, 2, 3], [3, 4, 5])
// => true
```

*No common elements*

Returns false when no elements are shared.

```typescript
intersects([1, 2], [3, 4])
// => false
```

---

### `isEmpty`

Checks if an array is empty (has no elements).
`null` and `undefined` are treated as empty arrays and return `true`.

```typescript
import { isEmpty } from '@helpers4/array';

isEmpty(value: readonly unknown[] | null | undefined): value is readonly never[] | null | undefined
```

**Parameters:**

- `value: readonly unknown[] | null | undefined` — The array to check

**Returns:** `value is readonly never[] | null | undefined` — `true` if the array has no elements, or if `value` is `null`/`undefined`

**Examples:**

*Check if an array is empty*

Returns true only for arrays with no elements.

```typescript
isEmpty([])        // => true
isEmpty([1, 2, 3]) // => false
isEmpty([null])    // => false  (null is still an element)
```

*Guard before accessing first element*

Use isEmpty as an early-return guard for arrays, null, and undefined; the false branch is safely non-empty.

```typescript
function first<T>(arr: T[] | null | undefined): T | undefined {
  if (isEmpty(arr)) return undefined;
  return arr[0];
}
first([])        // => undefined
first(null)      // => undefined
first([1, 2])    // => 1
```

---

### `isNonEmpty`

Checks if an array is non-empty (has at least one element).
`null` and `undefined` are treated as empty arrays and return `false`.

```typescript
import { isNonEmpty } from '@helpers4/array';

isNonEmpty<T>(value: readonly T[] | null | undefined): value is readonly [T, T]
```

**Parameters:**

- `value: readonly T[] | null | undefined` — The array to check

**Returns:** `value is readonly [T, T]` — `true` if the array has at least one element; `false` for empty, `null`, or `undefined`

**Examples:**

*Check if an array has elements*

Returns true for arrays with at least one element, regardless of the element values.

```typescript
isNonEmpty([1, 2, 3]) // => true
isNonEmpty([null])    // => true  (null is still an element)
isNonEmpty([])        // => false
```

*Safe first-element access with type narrowing*

In the true branch, the type narrows to [T, ...T[]], making arr[0] always defined.

```typescript
function first<T>(arr: readonly T[]): T | undefined {
  if (isNonEmpty(arr)) return arr[0]; // arr[0] is T, not T | undefined
  return undefined;
}
first([1, 2]) // => 1
first([])     // => undefined
```

---

### `mapAsync`

The async counterpart to `Array.prototype.map`: applies `fn` to every item and resolves to
an array of the results, in input order — regardless of which call finishes first.

`Array.prototype.map(asyncFn)` alone doesn't do this: it returns an array of *unresolved*
promises (`Promise<R>[]`), not `Promise<R[]>` — you'd still need to wrap it in
`Promise.all(...)` yourself, and there'd be no way to cap concurrency. This does both.

With no `concurrency` given, every call starts immediately (like
`Promise.all(array.map(fn))`). Pass `concurrency` to cap how many run at once — e.g. to
avoid overwhelming an API. Rejects with the first error thrown by `fn`, same as
`Promise.all`; other already-started calls keep running in the background but their
outcome is ignored.

```typescript
import { mapAsync } from '@helpers4/array';

mapAsync<T, R>(array: readonly T[], fn: function, options?: number | AsyncArrayOptions): Promise<R[]>
```

**Parameters:**

- `array: readonly T[]` — The array to map over
- `fn: function` — Async (or sync) function called with `(item, index)`
- `options?: number | AsyncArrayOptions` — Maximum number of concurrent calls (defaults to unlimited), or the options
  with a `signal` to stop — see AsyncArrayOptions

**Returns:** `Promise<R[]>` — The mapped results, in input order

**Examples:**

*Map over an array with an async function*

Every call starts immediately, results come back in input order.

```typescript
await mapAsync([1, 2, 3], async (n) => n * 2)
// => [2, 4, 6]
```

*Cap concurrency to avoid overwhelming an API*

At most `concurrency` calls run at once; the rest queue and wait.

```typescript
await mapAsync(urls, (url) => fetch(url).then(r => r.json()), 2)
// at most 2 concurrent fetch() calls
```

---

### `mapSettled`

Like mapAsync, but never rejects: each item gets its own result, in the shape of
`Promise.allSettled`, so one failure does not stop or hide the others.

`Promise.allSettled(array.map(fn))` does the same without a concurrency cap; `parallelSettle`
caps it but splits the results into two lists and loses which item failed. This keeps both:
the cap, and one result per item in input order.

```typescript
import { mapSettled } from '@helpers4/array';

mapSettled<T, R>(array: readonly T[], fn: function, options?: number | AsyncArrayOptions): Promise<PromiseSettledResult<Awaited<R>>[]>
```

**Parameters:**

- `array: readonly T[]` — The array to map over
- `fn: function` — Async (or sync) function called with `(item, index)`; a throw counts as a rejection
- `options?: number | AsyncArrayOptions` — Maximum number of concurrent calls (defaults to unlimited), or the options
  with a `signal` to stop — see AsyncArrayOptions. An abort is not an outcome: it
  rejects the whole call with the signal's reason.

**Returns:** `Promise<PromiseSettledResult<Awaited<R>>[]>` — One `PromiseSettledResult` per item, in input order

**Examples:**

*Keep going when some calls fail*

Each item gets its own result, like Promise.allSettled.

```typescript
await mapSettled([1, 2, 3], (n) => (n === 2 ? Promise.reject('no') : n * 10))
// => [{ status: 'fulfilled', value: 10 }, { status: 'rejected', reason: 'no' }, { status: 'fulfilled', value: 30 }]
```

*Cap concurrency*

The third argument limits how many calls run at once.

```typescript
const results = await mapSettled(urls, (url) => fetch(url), 4);
```

---

### `max`

Returns the maximum value in an array using a loop instead of spread,
avoiding the call stack overflow that occurs with `Math.max(...array)`
for very large arrays (> ~65 000 elements).
`null` and `undefined` are treated as empty arrays and return `undefined`.

```typescript
import { max } from '@helpers4/array';

max(array: readonly number[] | null | undefined): number | undefined
```

**Parameters:**

- `array: readonly number[] | null | undefined` — Array of numbers

**Returns:** `number | undefined` — Maximum value, `undefined` for empty arrays, `null`, `undefined`, or `NaN` if any element is `NaN`

**Examples:**

*Safe maximum for large arrays*

Unlike Math.max(...array), max() uses a loop and handles arrays of any size without stack overflow.

```typescript
max([3, 1, 4, 1, 5, 9])
// => 9

// Safe for 1 000 000+ elements (Math.max(...arr) would throw):
max(Array.from({ length: 1_000_000 }, (_, i) => i))
// => 999999
```

---

### `maxBy`

Returns the element of an array with the greatest derived key, computed by `keyFn`.
Unlike max, which only compares raw numbers, `maxBy` returns the *item* itself,
not the key. On a tie, the earliest element with that key wins.
`null` and `undefined` are treated as empty arrays and return `undefined`.

```typescript
import { maxBy } from '@helpers4/array';

maxBy<T>(array: readonly T[] | null | undefined, keyFn: function): T | undefined
```

**Parameters:**

- `array: readonly T[] | null | undefined` — Array of items
- `keyFn: function` — Derives the comparable key for an item

**Returns:** `T | undefined` — The element with the greatest key, or `undefined` for empty arrays, `null`, `undefined`

**Examples:**

*Pick the item with the greatest derived value*

Unlike max(), maxBy() returns the whole item, chosen by a key derived from it.

```typescript
maxBy(
  [{ name: 'a', size: 3 }, { name: 'b', size: 9 }, { name: 'c', size: 1 }],
  (item) => item.size,
)
// => { name: 'b', size: 9 }
```

*Empty array returns undefined*

There is no maximum to return for an empty array.

```typescript
maxBy([], (item: { size: number }) => item.size)
// => undefined
```

---

### `mean`

Calculates the arithmetic mean (average) of an array of numbers.
Returns `NaN` for an empty array.

Pairs with sum for aggregate operations.

```typescript
import { mean } from '@helpers4/array';

mean(array: readonly number[]): number
```

**Parameters:**

- `array: readonly number[]` — The array of numbers to average

**Returns:** `number` — The arithmetic mean, or `NaN` if the array is empty

**Examples:**

*Average a list of numbers*

Returns the arithmetic mean of the array; NaN for empty arrays.

```typescript
mean([1, 2, 3, 4])  // => 2.5
mean([10, 20, 30])  // => 20
mean([])            // => NaN
```

---

### `meanBy`

Calculates the arithmetic mean of numbers derived from each item of an array via an iteratee.
Returns `NaN` for an empty array, `null`, or `undefined` — matching sumBy, which
treats `null`/`undefined` as empty rather than throwing.

Pairs with sumBy for aggregate operations.

```typescript
import { meanBy } from '@helpers4/array';

meanBy<T>(array: readonly T[] | null | undefined, accessor: ByAccessor<T>): number
```

**Parameters:**

- `array: readonly T[] | null | undefined` — The array of items to average
- `accessor: ByAccessor<T>` — Function deriving a number from each item, or a property path

**Returns:** `number` — The arithmetic mean of the derived values, or `NaN` if the array is empty, `null`, or `undefined`

**Examples:**

*Average a property across objects*

Averages a derived numeric value instead of the items themselves.

```typescript
meanBy([{ price: 10 }, { price: 20 }], item => item.price)
// => 15
```

*Use a property path instead of a function*

A string (or key array) path is shorthand for a getter function.

```typescript
meanBy([{ price: 10 }, { price: 20 }], 'price')
// => 15
```

---

### `median`

Calculates the median (middle value) of an array of numbers. For an even-length array,
returns the average of the two middle values. Returns `NaN` for an empty array.
Does not mutate the input array.

The median is the 50th percentile — this delegates to it rather than duplicating
its sort/interpolation logic.

```typescript
import { median } from '@helpers4/array';

median(array: readonly number[]): number
```

**Parameters:**

- `array: readonly number[]` — The array of numbers

**Returns:** `number` — The median value, or `NaN` if the array is empty

**Examples:**

*Odd-length array*

Returns the middle value once sorted.

```typescript
median([3, 1, 2])
// => 2
```

*Even-length array*

Averages the two middle values.

```typescript
median([1, 2, 3, 4])
// => 2.5
```

---

### `min`

Returns the minimum value in an array using a loop instead of spread,
avoiding the call stack overflow that occurs with `Math.min(...array)`
for very large arrays (> ~65 000 elements).
`null` and `undefined` are treated as empty arrays and return `undefined`.

```typescript
import { min } from '@helpers4/array';

min(array: readonly number[] | null | undefined): number | undefined
```

**Parameters:**

- `array: readonly number[] | null | undefined` — Array of numbers

**Returns:** `number | undefined` — Minimum value, `undefined` for empty arrays, `null`, `undefined`, or `NaN` if any element is `NaN`

**Examples:**

*Safe minimum for large arrays*

Unlike Math.min(...array), min() uses a loop and handles arrays of any size without stack overflow.

```typescript
min([3, 1, 4, 1, 5, 9])
// => 1

// Safe for 1 000 000+ elements (Math.min(...arr) would throw):
min(Array.from({ length: 1_000_000 }, (_, i) => i))
// => 0
```

---

### `minBy`

Returns the element of an array with the smallest derived key, computed by `keyFn`.
Unlike min, which only compares raw numbers, `minBy` returns the *item* itself,
not the key. On a tie, the earliest element with that key wins.
`null` and `undefined` are treated as empty arrays and return `undefined`.

```typescript
import { minBy } from '@helpers4/array';

minBy<T>(array: readonly T[] | null | undefined, keyFn: function): T | undefined
```

**Parameters:**

- `array: readonly T[] | null | undefined` — Array of items
- `keyFn: function` — Derives the comparable key for an item

**Returns:** `T | undefined` — The element with the smallest key, or `undefined` for empty arrays, `null`, `undefined`

**Examples:**

*Pick the item with the smallest derived value*

Unlike min(), minBy() returns the whole item, chosen by a key derived from it.

```typescript
minBy(
  [{ name: 'a', size: 3 }, { name: 'b', size: 9 }, { name: 'c', size: 1 }],
  (item) => item.size,
)
// => { name: 'c', size: 1 }
```

*Empty array returns undefined*

There is no minimum to return for an empty array.

```typescript
minBy([], (item: { size: number }) => item.size)
// => undefined
```

---

### `partition`

Splits an array into two groups based on a predicate function.
The first group contains elements for which the predicate returns true,
the second group contains the rest.
`null` and `undefined` are treated as empty arrays and return `[[], []]`.

```typescript
import { partition } from '@helpers4/array';

partition<T>(array: readonly T[] | null | undefined, predicate: function): [T[], T[]]
```

**Parameters:**

- `array: readonly T[] | null | undefined` — The array to partition
- `predicate: function` — Function that returns true for elements in the first group

**Returns:** `[T[], T[]]` — A tuple of two arrays: [matching, non-matching]

**Examples:**

*Split numbers by parity*

Splits an array into even and odd numbers using a predicate.

```typescript
partition([1, 2, 3, 4, 5], n => n % 2 === 0)
// => [[2, 4], [1, 3, 5]]
```

*Separate active and inactive users*

Partitions an array of objects based on a boolean property.

```typescript
const users = [
  { name: 'Alice', active: true },
  { name: 'Bob', active: false },
  { name: 'Charlie', active: true },
];
partition(users, u => u.active)
// => [[Alice, Charlie], [Bob]]
```

*Handle empty array*

Returns two empty arrays when the input is empty.

```typescript
partition([], () => true)
// => [[], []]
```

---

### `percentile`

Calculates the p-th percentile of an array of numbers using linear interpolation between
the closest ranks. Returns `NaN` for an empty array. Does not mutate the input array.

```typescript
import { percentile } from '@helpers4/array';

percentile(array: readonly number[], p: number): number
```

**Parameters:**

- `array: readonly number[]` — The array of numbers
- `p: number` — The percentile to compute, from `0` to `100`

**Returns:** `number` — The interpolated value at percentile `p`, or `NaN` if the array is empty

**Examples:**

*Median via the 50th percentile*

The 50th percentile is equivalent to the median.

```typescript
percentile([1, 2, 3, 4], 50)
// => 2.5
```

*Min and max via 0 and 100*

The 0th and 100th percentiles are the min and max.

```typescript
percentile([4, 1, 3, 2], 0)   // => 1
percentile([4, 1, 3, 2], 100) // => 4
```

---

### `range`

Generates an array of sequential numbers from start to end (exclusive).
If only one argument is provided, it generates numbers from 0 to that value.

```typescript
import { range } from '@helpers4/array';

range(startOrEnd: number, end?: number, step?: number): number[]
```

**Parameters:**

- `startOrEnd: number` — The start value (if end is provided) or end value (if end is omitted)
- `end?: number` — The end value (exclusive)
- `step?: number` — The increment between values (default: 1 or -1 depending on direction)

**Returns:** `number[]` — An array of sequential numbers

**Examples:**

*Generate a sequence from 0*

Creates an array of numbers from 0 to n-1 with a single argument.

```typescript
range(5)
// => [0, 1, 2, 3, 4]
```

*Generate a sequence with start and end*

Creates an array from start (inclusive) to end (exclusive).

```typescript
range(1, 5)
// => [1, 2, 3, 4]
```

*Generate a sequence with a custom step*

Creates an array with a specified increment between values.

```typescript
range(0, 10, 2)
// => [0, 2, 4, 6, 8]
```

*Generate a descending sequence*

Automatically produces a descending range when start > end.

```typescript
range(5, 0)
// => [5, 4, 3, 2, 1]
```

---

### `replaceOrAppend`

Returns a new array with the first item matching `predicate` replaced by
`item` — or `item` appended at the end if no match is found. The common
"upsert into a list" pattern.

```typescript
import { replaceOrAppend } from '@helpers4/array';

replaceOrAppend<T>(array: readonly T[] | null | undefined, item: T, predicate: function): T[]
```

**Parameters:**

- `array: readonly T[] | null | undefined` — The source array. `null`/`undefined` are treated as empty.
- `item: T` — The replacement (or new) item
- `predicate: function` — Called with each existing item to find what to replace

**Returns:** `T[]` — A new array with `item` upserted

**Examples:**

*Upsert an item into a list*

Replaces the first match, or appends when nothing matches.

```typescript
const users = [{ id: 1, name: 'a' }, { id: 2, name: 'b' }];
replaceOrAppend(users, { id: 1, name: 'A' }, (u) => u.id === 1)
// => [{ id: 1, name: 'A' }, { id: 2, name: 'b' }]
```

*Appends when no item matches*

A missing id is added at the end rather than silently dropped.

```typescript
replaceOrAppend([{ id: 1 }], { id: 2 }, (u) => u.id === 2)
// => [{ id: 1 }, { id: 2 }]
```

---

### `reverseSortFn`

Reverses the order of a sort function: `reverseSortFn(fn)(a, b)` is `fn(b, a)`.

Gives a descending variant of any comparator, including the ones built by the
`createSortBy*Fn` factories, and composes with combineSortFns for mixed orders.
Ties stay ties, so the sort remains stable.

```typescript
import { reverseSortFn } from '@helpers4/array';

reverseSortFn<T>(fn: SortFn<T>): SortFn<T>
```

**Parameters:**

- `fn: SortFn<T>` — The sort function to reverse

**Returns:** `SortFn<T>` — A sort function with the opposite order

**Examples:**

*Newest first*

Turns an ascending comparator into a descending one.

```typescript
const releases = [{ date: '2026-01-01' }, { date: '2026-03-01' }];
releases.sort(reverseSortFn(createSortByStringFn('date')))
// => [{ date: '2026-03-01' }, { date: '2026-01-01' }]
```

*Mixed order*

Newest first, then name ascending, by combining it with combineSortFns.

```typescript
rows.sort(combineSortFns(
  reverseSortFn(createSortByStringFn('date')),
  createSortByStringFn('name'),
))
```

---

### `sample`

Picks one or more random elements from an array.
When called without a count, returns a single element or `undefined` if the array is empty.
When called with a count, returns an array of up to `count` random elements sampled without replacement.

```typescript
import { sample } from '@helpers4/array';

sample<T>(array: readonly T[] | null | undefined): T | undefined
```

**Parameters:**

- `array: readonly T[] | null | undefined` — The source array to pick from

**Returns:** `T | undefined` — A single random element, or `undefined` if the array is empty

```typescript
import { sample } from '@helpers4/array';

sample<T>(array: readonly T[] | null | undefined, count: number): T[]
```

**Parameters:**

- `array: readonly T[] | null | undefined` — The source array to pick from
- `count: number` — Number of elements to pick

**Returns:** `T[]` — An array of up to `count` random elements

**Examples:**

*Pick a single random element*

Without a count, returns one random element from the array.

```typescript
sample([1, 2, 3, 4, 5])
// => 3 (random element)
```

*Pick multiple random elements*

With a count, returns an array of random elements sampled without replacement.

```typescript
sample([1, 2, 3, 4, 5], 3)
// => [2, 5, 1] (3 random elements, without replacement)
```

*Empty array returns undefined*

Returns undefined when sampling from an empty array.

```typescript
sample([])
// => undefined
```

---

### `select`

Filters and transforms an array in a single pass.

Similar to `.filter(condition).map(mapper)` but iterates the array only once.
**Index semantics differ from `.filter().map()`:** the `index` passed to both
`condition` and `mapper` is the index in the **original** array, not the
post-filter position. Use index-agnostic callbacks when the two must behave
identically.

```typescript
import { select } from '@helpers4/array';

select<T, U>(array: readonly T[] | null | undefined, mapper: function, condition: function): U[]
```

**Parameters:**

- `array: readonly T[] | null | undefined` — The array to process
- `mapper: function` — Transforms each item that passes the condition
- `condition: function` (default: `...`) — Determines which items to include; defaults to keeping all items

**Returns:** `U[]` — Mapped values for items that pass the condition

**Examples:**

*Filter and transform in one pass*

Keeps only items matching the condition and transforms them — equivalent to .filter().map() but with a single iteration.

```typescript
select([1, 2, 3, 4, 5], x => x * 2, x => x % 2 === 0)
// => [4, 8]
```

*Extract a field from matching objects*

Filter on a condition and pluck a specific property in a single readable call.

```typescript
const users = [
  { name: 'Alice', active: true },
  { name: 'Bob',   active: false },
  { name: 'Carol', active: true },
];
select(users, u => u.name, u => u.active)
// => ['Alice', 'Carol']
```

---

### `shuffle`

Randomly reorders elements of an array using the Fisher-Yates algorithm.
Returns a new array without mutating the original.
`null` and `undefined` are treated as empty arrays and return `[]`.

```typescript
import { shuffle } from '@helpers4/array';

shuffle<T>(array: readonly T[] | null | undefined): T[]
```

**Parameters:**

- `array: readonly T[] | null | undefined` — The array to shuffle

**Returns:** `T[]` — A new array with the same elements in random order

**Examples:**

*Shuffle an array of numbers*

Returns a new array with the same elements in random order using the Fisher-Yates algorithm.

```typescript
shuffle([1, 2, 3, 4, 5])
// => [3, 1, 5, 2, 4] (random order)
```

*Original array is not mutated*

The original array remains unchanged.

```typescript
const original = ['a', 'b', 'c'];
const shuffled = shuffle(original);
// original is still ['a', 'b', 'c']
```

---

### `sortNumberAscFn`

Sort numbers in ascending order

**Examples:**

*Sort numbers ascending*

Use sortNumberAscFn as a comparator for Array.sort().

```typescript
[3, 1, 2].sort(sortNumberAscFn)
// => [1, 2, 3]
```

*Sort strings alphabetically*

Use sortStringAscFn for locale-aware string sorting.

```typescript
['banana', 'apple', 'cherry'].sort(sortStringAscFn)
// => ['apple', 'banana', 'cherry']
```

---

### `sortNumberDescFn`

Sort numbers in descending order

---

### `sortStringAscFn`

Sort strings in ascending order

---

### `sortStringAscInsensitiveFn`

Sort strings in ascending order (case insensitive)

---

### `sortStringDescFn`

Sort strings in descending order

---

### `sortStringNaturalAscFn`

Sort strings in ascending order using natural (human-friendly) ordering.
Numbers embedded in strings are compared numerically: "W2" < "W11" < "W20".

**Examples:**

*Natural sort for strings with embedded numbers*

sortStringNaturalAscFn treats numeric parts as numbers: "W2" < "W11" < "W20".

```typescript
['W20', 'W2', 'W11', 'W01'].sort(sortStringNaturalAscFn)
// => ['W01', 'W2', 'W11', 'W20']
```

*Natural sort for object arrays*

createSortByNaturalFn sorts objects with embedded numbers in property values.

```typescript
const items = [{ code: 'W20' }, { code: 'W2' }, { code: 'W11' }, { code: 'W01' }];
items.sort(createSortByNaturalFn('code'))
// => W01, W2, W11, W20
```

---

### `sortStringNaturalAscInsensitiveFn`

Sort strings in ascending natural order, ignoring case **and diacritics**
(`Intl.Collator { sensitivity: 'base' }` — treats é, E, and e as equal).
Numbers embedded in strings are compared numerically: "W2" < "W11" < "W20".

**Examples:**

*sortStringNaturalAscInsensitiveFn*

```typescript
```ts
['W11', 'W2', 'W20'].sort(sortStringNaturalAscInsensitiveFn) // => ['W2', 'W11', 'W20']
```
```

---

### `sortStringNaturalDescFn`

Sort strings in descending order using natural (human-friendly) ordering.
Numbers embedded in strings are compared numerically: "W20" > "W11" > "W2".

**Examples:**

*sortStringNaturalDescFn*

```typescript
```ts
['W11', 'W2', 'W20'].sort(sortStringNaturalDescFn) // => ['W20', 'W11', 'W2']
```
```

---

### `sortStringNaturalDescInsensitiveFn`

Sort strings in descending natural order, ignoring case **and diacritics**
(`Intl.Collator { sensitivity: 'base' }` — treats é, E, and e as equal).
Numbers embedded in strings are compared numerically: "W20" > "W11" > "W2".

**Examples:**

*sortStringNaturalDescInsensitiveFn*

```typescript
```ts
['W11', 'W2', 'W20'].sort(sortStringNaturalDescInsensitiveFn) // => ['W20', 'W11', 'W2']
```
```

---

### `sum`

Calculates the sum of an array of numbers.
`null` and `undefined` are treated as empty arrays and return `0`.

```typescript
import { sum } from '@helpers4/array';

sum(array: readonly number[] | null | undefined): number
```

**Parameters:**

- `array: readonly number[] | null | undefined` — The array of numbers to sum

**Returns:** `number` — The sum of all values, or `0` for an empty array, `null`, or `undefined`

**Examples:**

*Sum numbers*

Calculates the sum of an array of numbers.

```typescript
sum([1, 2, 3, 4])
// => 10
```

*Sum with negative numbers*

Handles negative numbers correctly.

```typescript
sum([10, -3, 5, -2])
// => 10
```

---

### `sumBy`

Calculates the sum of numbers derived from each item of an array via an iteratee.
`null` and `undefined` are treated as empty arrays and return `0`.

```typescript
import { sumBy } from '@helpers4/array';

sumBy<T>(array: readonly T[] | null | undefined, accessor: ByAccessor<T>): number
```

**Parameters:**

- `array: readonly T[] | null | undefined` — The array of items to sum
- `accessor: ByAccessor<T>` — Function deriving a number from each item, or a property path

**Returns:** `number` — The sum of all derived values, or `0` for an empty array, `null`, or `undefined`

**Examples:**

*Sum a property across objects*

Sums a derived numeric value instead of the items themselves.

```typescript
sumBy([{ price: 10 }, { price: 20 }], item => item.price)
// => 30
```

*Use a property path instead of a function*

A string (or key array) path is shorthand for a getter function.

```typescript
sumBy([{ price: 10 }, { price: 20 }], 'price')
// => 30
```

---

### `symmetricDifference`

Returns the symmetric difference between two arrays: items present in
exactly one of the two arrays (in either, but not both).
`null` and `undefined` are treated as empty arrays.

```typescript
import { symmetricDifference } from '@helpers4/array';

symmetricDifference<T>(array1: readonly T[] | null | undefined, array2: readonly T[] | null | undefined): T[]
```

**Parameters:**

- `array1: readonly T[] | null | undefined` — First array
- `array2: readonly T[] | null | undefined` — Second array

**Returns:** `T[]` — Items unique to `array1` (in original order), followed by items unique to `array2`

**Examples:**

*Find items unique to either array*

Complements difference()/intersection() with the "in either, not both" set operation.

```typescript
symmetricDifference([1, 2, 3], [2, 3, 4])
// => [1, 4]
```

*Identical arrays have no symmetric difference*

Items shared by both arrays are excluded entirely.

```typescript
symmetricDifference(['a', 'b'], ['a', 'b'])
// => []
```

---

### `toggle`

Returns a new array with `item` removed if present, or appended if absent —
the common "toggle a selection" pattern.

By default, presence is checked with `SameValueZero` equality (like
`Array.prototype.includes`). Pass `key` to compare by a derived identity
instead — useful for toggling objects by id rather than by reference.

```typescript
import { toggle } from '@helpers4/array';

toggle<T>(array: readonly T[] | null | undefined, item: T, key?: function): T[]
```

**Parameters:**

- `array: readonly T[] | null | undefined` — The source array. `null`/`undefined` are treated as empty.
- `item: T` — The item to add or remove
- `key?: function` — Optional function deriving the identity to compare by

**Returns:** `T[]` — A new array with `item` toggled

**Examples:**

*Toggle a selection*

Common pattern for multi-select UI state — add if absent, remove if present.

```typescript
toggle([1, 2, 3], 2)
// => [1, 3]
toggle([1, 3], 2)
// => [1, 3, 2]
```

*Toggle objects by a derived key*

Pass a key selector to compare by id instead of object reference.

```typescript
const selected = [{ id: 1 }, { id: 2 }];
toggle(selected, { id: 1 }, (x) => x.id)
// => [{ id: 2 }]
```

---

### `unique`

Removes duplicate values from an array.
`null` and `undefined` are treated as empty arrays and return `[]`.

```typescript
import { unique } from '@helpers4/array';

unique<T>(array: readonly T[] | null | undefined): T[]
```

**Parameters:**

- `array: readonly T[] | null | undefined` — The array to remove duplicates from

**Returns:** `T[]` — New array with unique values only

**Examples:**

*Remove duplicates*

Returns a new array with duplicate values removed.

```typescript
unique([1, 2, 2, 3, 3, 3])
// => [1, 2, 3]
```

---

### `uniqueBy`

Removes duplicate items from an array, using a derived key instead of value equality.
Unlike unique, which compares values directly, `uniqueBy` lets two different
objects be considered duplicates if `keyFn` derives the same key for both.
`null` and `undefined` are treated as empty arrays and return `[]`.

```typescript
import { uniqueBy } from '@helpers4/array';

uniqueBy<T, K>(array: readonly T[] | null | undefined, keyFn: function, options: UniqueByOptions): T[]
```

**Parameters:**

- `array: readonly T[] | null | undefined` — The array to remove duplicates from
- `keyFn: function` — Derives the dedup key for an item
- `options: UniqueByOptions` (default: `{}`) — Options

**Returns:** `T[]` — New array with one item per distinct key, in first-occurrence order

**Examples:**

*Deduplicate by a derived key, keeping the first occurrence*

Two different objects are considered duplicates when keyFn derives the same key for both.

```typescript
uniqueBy(
  [{ id: 1, v: 'a' }, { id: 2, v: 'b' }, { id: 1, v: 'c' }],
  (item) => item.id,
)
// => [{ id: 1, v: 'a' }, { id: 2, v: 'b' }]
```

*Keep the last occurrence instead*

Pass { keep: "last" } to keep the last item seen for each key, instead of the first.

```typescript
uniqueBy(
  [{ id: 1, v: 'a' }, { id: 2, v: 'b' }, { id: 1, v: 'c' }],
  (item) => item.id,
  { keep: 'last' },
)
// => [{ id: 1, v: 'c' }, { id: 2, v: 'b' }]
```

---

### `unzip`

Splits an array of tuples into separate arrays, one per position.

The inverse of zip.

```typescript
import { unzip } from '@helpers4/array';

unzip<A, B>(pairs: readonly [A, B][] | null | undefined): [A[], B[]]
```

**Parameters:**

- `pairs: readonly [A, B][] | null | undefined` — Array of 2-tuples to unzip

**Returns:** `[A[], B[]]` — A tuple of two arrays: all first elements and all second elements

```typescript
import { unzip } from '@helpers4/array';

unzip<A, B, C>(pairs: readonly [A, B, C][] | null | undefined): [A[], B[], C[]]
```

**Parameters:**

- `pairs: readonly [A, B, C][] | null | undefined` — Array of 2-tuples to unzip

**Returns:** `[A[], B[], C[]]` — A tuple of two arrays: all first elements and all second elements

```typescript
import { unzip } from '@helpers4/array';

unzip<A, B, C, D>(pairs: readonly [A, B, C, D][] | null | undefined): [A[], B[], C[], D[]]
```

**Parameters:**

- `pairs: readonly [A, B, C, D][] | null | undefined` — Array of 2-tuples to unzip

**Returns:** `[A[], B[], C[], D[]]` — A tuple of two arrays: all first elements and all second elements

**Examples:**

*Split pairs into separate arrays*

The inverse of zip — separate each position into its own array.

```typescript
const pairs: [number, string][] = [[1, 'a'], [2, 'b'], [3, 'c']];
const [nums, letters] = unzip(pairs);

nums;    // => [1, 2, 3]
letters; // => ['a', 'b', 'c']
```

---

### `without`

Returns a new array with all occurrences of the given values removed.

Unlike `difference`, which operates on two arrays as set operands, `without`
uses a variadic API suited for removing known sentinel values inline.
Uses `SameValueZero` equality (same as `Array.prototype.includes`).
`null` and `undefined` are treated as empty arrays and return `[]`.

```typescript
import { without } from '@helpers4/array';

without<T>(array: readonly T[] | null | undefined, values: T[]): T[]
```

**Parameters:**

- `array: readonly T[] | null | undefined` — The source array.
- `values: T[]` — One or more values to exclude from the result.

**Returns:** `T[]` — A new array without the specified values.

**Examples:**

*Remove a single value*

Returns a new array with all occurrences of the given value removed.

```typescript
without([1, 2, 3, 2, 4], 2)
// => [1, 3, 4]
```

*Remove multiple values*

All listed values are excluded from the result.

```typescript
without([1, 2, 3, 2, 4], 2, 3)
// => [1, 4]
```

---

### `zip`

Combines multiple arrays element-by-element into an array of tuples.
The result length equals the length of the shortest input array.

The inverse of unzip.

```typescript
import { zip } from '@helpers4/array';

zip<A, B>(a: readonly A[], b: readonly B[]): [A, B][]
```

**Parameters:**

- `a: readonly A[]` — First array
- `b: readonly B[]` — Second array

**Returns:** `[A, B][]` — Array of `[a, b]` pairs

```typescript
import { zip } from '@helpers4/array';

zip<A, B, C>(a: readonly A[], b: readonly B[], c: readonly C[]): [A, B, C][]
```

**Parameters:**

- `a: readonly A[]` — First array
- `b: readonly B[]` — Second array
- `c: readonly C[]`

**Returns:** `[A, B, C][]` — Array of `[a, b]` pairs

```typescript
import { zip } from '@helpers4/array';

zip<A, B, C, D>(a: readonly A[], b: readonly B[], c: readonly C[], d: readonly D[]): [A, B, C, D][]
```

**Parameters:**

- `a: readonly A[]` — First array
- `b: readonly B[]` — Second array
- `c: readonly C[]`
- `d: readonly D[]`

**Returns:** `[A, B, C, D][]` — Array of `[a, b]` pairs

**Examples:**

*Pair keys with values*

Combine two arrays element-by-element.

```typescript
zip(['a', 'b', 'c'], [1, 2, 3])
// => [['a', 1], ['b', 2], ['c', 3]]
```

*Truncates to the shorter array*

Stops at the end of the shorter array to avoid undefined entries.

```typescript
zip([1, 2, 3], ['x', 'y'])
// => [[1, 'x'], [2, 'y']]
```

---

## binary

Package: `@helpers4/binary`

### `createByteReader`

Creates a cursor over bytes, for decoding binary formats: fixed-size integers and floats,
LEB128 varints (signed ones zigzag-encoded), byte runs and NUL-terminated strings. Mirrors the
Rust `bytes::ByteReader` of helpers4.

A read never throws on bad data: it returns `undefined` and leaves the position untouched,
enough to build a precise error in the caller's own error type.

```typescript
import { createByteReader } from '@helpers4/binary';

createByteReader(data: Uint8Array): ByteReader
```

**Parameters:**

- `data: Uint8Array` — The bytes to decode

**Returns:** `ByteReader` — A ByteReader at position `0`

**Examples:**

*Decode a small binary record*

Each read returns the value and moves on; at the end of the data it returns undefined.

```typescript
const reader = createByteReader(new Uint8Array([0x2a, 0xac, 0x02, 0x68, 0x69, 0]));
reader.readU8();      // => 42
reader.readVarU32();  // => 300
reader.readCString(); // => 'hi'
reader.readU8();      // => undefined
```

*A truncated read does not move the cursor*

position tells where the failed read started, to report a precise error.

```typescript
const reader = createByteReader(new Uint8Array([1, 2, 3]));
reader.readU32(); // => undefined
reader.position;  // => 0
```

---

### `createByteWriter`

Creates a growable buffer to encode binary formats: the counterpart of
createByteReader, with the same types, byte orders and varints.

```typescript
import { createByteWriter } from '@helpers4/binary';

createByteWriter(): ByteWriter
```

**Returns:** `ByteWriter` — An empty ByteWriter

**Examples:**

*Encode a small binary record*

Writes chain, and toBytes returns the result.

```typescript
createByteWriter().writeU8(42).writeVarU32(300).writeCString('hi').toBytes()
// => Uint8Array [0x2a, 0xac, 0x02, 0x68, 0x69, 0]
```

*Choose the byte order*

Multi-byte values are big-endian unless you say little.

```typescript
createByteWriter().writeU16(1).writeU16(1, 'little').toBytes()
// => Uint8Array [0, 1, 1, 0]
```

---

### `mediaTypeOf`

Finds the media type of an image from its first bytes (its magic number), whatever its name
says: PNG, JPEG, GIF, WebP, AVIF and SVG. SVG has no magic number, so it is recognized as text
whose first element is `<svg`, possibly after a byte order mark, whitespace, an XML
declaration, comments or a doctype.

```typescript
import { mediaTypeOf } from '@helpers4/binary';

mediaTypeOf(bytes: Uint8Array): string | undefined
```

**Parameters:**

- `bytes: Uint8Array` — The start of the file: 512 bytes are enough for every type but a long SVG prolog

**Returns:** `string | undefined` — The media type (`'image/png'`, ...), or `undefined` when it is none of these

**Examples:**

*Sniff an image*

The first bytes tell the format, whatever the file is called.

```typescript
mediaTypeOf(new Uint8Array([0xff, 0xd8, 0xff, 0xe0])) // => 'image/jpeg'
```

---

### `mediaTypeOfPath`

Finds the media type of a file from the extension of its path or URL: images, fonts, web
documents, scripts and styles, data, audio and video. Case is ignored, and a query string or
fragment after the path is skipped. Pass it where a server or a `Blob` needs a `Content-Type`.

```typescript
import { mediaTypeOfPath } from '@helpers4/binary';

mediaTypeOfPath(path: string): string | undefined
```

**Parameters:**

- `path: string` — A file path or URL

**Returns:** `string | undefined` — The media type (`'image/webp'`, ...), or `undefined` for an unknown or missing extension

**Examples:**

*Content-Type from a path*

Case and a query string are ignored.

```typescript
mediaTypeOfPath('/fonts/Inter.WOFF2?v=3') // => 'font/woff2'
```

---

### `toHex`

Writes bytes as lowercase hexadecimal, two digits per byte. For content keys, hashes and
debugging output.

```typescript
import { toHex } from '@helpers4/binary';

toHex(bytes: Uint8Array): string
```

**Parameters:**

- `bytes: Uint8Array` — The bytes

**Returns:** `string` — The hex string, twice as long as `bytes`

**Examples:**

*Hex string of bytes*

Two lowercase digits per byte.

```typescript
toHex(new Uint8Array([0, 15, 255])) // => '000fff'
```

---

### `zigzagDecode`

The inverse of zigzagEncode: maps an unsigned 64-bit zigzag value back to the signed
integer.

```typescript
import { zigzagDecode } from '@helpers4/binary';

zigzagDecode(value: bigint): bigint
```

**Parameters:**

- `value: bigint` — An unsigned integer in the 64-bit range

**Returns:** `bigint` — The signed integer

**Examples:**

*Recover the signed value*

The inverse of zigzagEncode.

```typescript
zigzagDecode(1n) // => -1n
zigzagDecode(2n) // => 1n
```

*Decode a varint payload*

Read the unsigned varint first, then undo the zigzag mapping.

```typescript
zigzagDecode(300n) // => 150n
```

---

### `zigzagEncode`

Maps a signed 64-bit integer to an unsigned one so that values near zero stay small (`0, -1, 1,
-2` become `0, 1, 2, 3`): the "zigzag" mapping of Protocol Buffers, used before writing a signed
value as a varint.

```typescript
import { zigzagEncode } from '@helpers4/binary';

zigzagEncode(value: bigint): bigint
```

**Parameters:**

- `value: bigint` — A signed integer in the 64-bit range

**Returns:** `bigint` — The unsigned zigzag value

**Examples:**

*Keep small negative numbers small*

Zigzag interleaves negatives and positives, so a varint stays short for values near zero.

```typescript
zigzagEncode(-1n) // => 1n
zigzagEncode(1n)  // => 2n
```

*Cover the whole signed 64-bit range*

The most negative value maps to the largest unsigned one.

```typescript
zigzagEncode(-(1n << 63n)) // => 18446744073709551615n
```

---

## browser

Package: `@helpers4/browser`

### `createFileStore`

Creates a file store on a named Cache API cache: keep a computed set of files (a bake, a
download, extracted layers) under a key and a version, and read it back later, even offline.
Cache entries are keyed by made-up URLs, so nothing is ever fetched.

Outside a browser (no `caches`), `put` stores nothing and `get` always misses, so a caller
works without a cache, only slower.

```typescript
import { createFileStore } from '@helpers4/browser';

createFileStore(name: string): FileStore
```

**Parameters:**

- `name: string` — The name of the cache, shared by every store with that name

**Returns:** `FileStore` — The FileStore

**Examples:**

*Keep a bake for the next visit*

Files go under a key and a version; a new version is a miss.

```typescript
const store = createFileStore('bakes');
await store.put('design-1', { 'a.png': blob, 'index.json': '{}' }, 'v3');
const files = await store.get('design-1', 'v3'); // => { 'a.png': Blob, 'index.json': Blob }
```

---

### `decodeImage`

Loads an image and waits until it is decoded, so it can be painted without a flash or a
decoding pause (e.g. before swapping screens).

Outside a browser (no `Image`), it rejects with a `TypeError`.

```typescript
import { decodeImage } from '@helpers4/browser';

decodeImage(src: string): Promise<HTMLImageElement>
```

**Parameters:**

- `src: string` — The image URL

**Returns:** `Promise<HTMLImageElement>` — The decoded image element

**Examples:**

*Swap screens without a flash*

Insert the image only once it is decoded.

```typescript
const image = await decodeImage('/screens/home.png');
container.replaceChildren(image);
```

*Handle a broken image*

A missing or corrupt image rejects, so it can be replaced by a placeholder.

```typescript
const image = await decodeImage(url).catch(() => placeholder);
```

---

### `loadFont`

Loads a font and registers it in `document.fonts`, so CSS and canvas can use `family` right
away.

`source` is either a URL (wrapped in `url()` for you) or the font file's bytes. Outside a
browser (no `FontFace`), it rejects with a `TypeError`.

```typescript
import { loadFont } from '@helpers4/browser';

loadFont(family: string, source: string | BufferSource, descriptors?: FontFaceDescriptors): Promise<FontFace>
```

**Parameters:**

- `family: string` — The family name CSS will use, e.g. `'Inter'`
- `source: string | BufferSource` — The font URL, or its bytes
- `descriptors?: FontFaceDescriptors` — `weight`, `style`, `unicodeRange`, ... as in a CSS `@font-face` rule

**Returns:** `Promise<FontFace>` — The loaded `FontFace`

**Examples:**

*Load a web font before drawing text*

The font is registered in document.fonts, so CSS and canvas can use it right away.

```typescript
await loadFont('Inter', '/fonts/Inter-Bold.woff2', { weight: '700' });
context.font = '700 16px Inter';
```

*Load embedded font bytes*

Pass the bytes of a font file extracted from an archive or a design file.

```typescript
await loadFont('Embedded', await file.arrayBuffer());
```

---

### `matchesMedia`

Whether the document currently matches a CSS media query.

Outside a browser (no `matchMedia`, e.g. during server-side rendering), it returns `false`.

```typescript
import { matchesMedia } from '@helpers4/browser';

matchesMedia(query: string): boolean
```

**Parameters:**

- `query: string` — A media query, e.g. `'(min-width: 600px)'`

**Returns:** `boolean` — `true` if the query matches now

**Examples:**

*Read a media query*

Returns whether the document matches the query right now.

```typescript
const dark = matchesMedia('(prefers-color-scheme: dark)');
```

*Safe during server-side rendering*

Without matchMedia (Node.js, a build step), it returns false instead of throwing.

```typescript
// on the server
matchesMedia('(min-width: 600px)') // => false
```

---

### `observeIntersection`

Calls `callback` each time `element` enters or leaves the viewport (or `options.root`), with an
`IntersectionObserver` dedicated to it: lazy loading, starting an animation when it becomes
visible, pausing a video when it scrolls away. Like `IntersectionObserver` itself, it is also
called once soon after it starts observing.

Without `IntersectionObserver`, it does nothing and returns a function that does nothing.

```typescript
import { observeIntersection } from '@helpers4/browser';

observeIntersection(element: Element, callback: function, options: ObserveIntersectionOptions): function
```

**Parameters:**

- `element: Element` — The element to observe
- `callback: function` — Receives the `IntersectionObserverEntry` of `element` (`entry.isIntersecting`, `entry.intersectionRatio`, ...)
- `options: ObserveIntersectionOptions` (default: `{}`) — `root`, `rootMargin` and `threshold`, as for `IntersectionObserver`, and a
  `signal` to stop — see ObserveIntersectionOptions

**Returns:** `function` — A function that stops observing

**Examples:**

*Play a video only while visible*

The callback receives the IntersectionObserverEntry of the element.

```typescript
const stop = observeIntersection(video, (entry) => (entry.isIntersecting ? video.play() : video.pause()));
```

*Lazy-load once*

Stop observing from the callback after the first load; rootMargin starts loading early.

```typescript
const stop = observeIntersection(image, (entry) => {
  if (!entry.isIntersecting) return;
  image.src = image.dataset.src!;
  stop();
}, { rootMargin: '200px' });
```

---

### `observeResize`

Calls `callback` each time the size of `element` changes, with a `ResizeObserver` dedicated to
it. Like `ResizeObserver` itself, it is also called once soon after it starts observing.

To limit how often it runs, wrap the callback with `debounce` or `throttle` from
`helpers4/function`. Without `ResizeObserver`, it does nothing and returns a function that
does nothing.

```typescript
import { observeResize } from '@helpers4/browser';

observeResize(element: Element, callback: function, options: ObserveResizeOptions): function
```

**Parameters:**

- `element: Element` — The element to observe
- `callback: function` — Receives the `ResizeObserverEntry` of `element`
- `options: ObserveResizeOptions` (default: `{}`) — Cancellation — see ObserveResizeOptions

**Returns:** `function` — A function that stops observing

**Examples:**

*Redraw when an element is resized*

The callback receives the ResizeObserverEntry of the element.

```typescript
const stop = observeResize(canvas, (entry) => redraw(entry.contentRect));
```

*Limit how often it runs*

Compose with debounce from helpers4/function instead of an option.

```typescript
const stop = observeResize(frame, debounce(() => fitToViewport(), 100));
```

---

### `onPointerIntent`

Tells a tap from a drag, and hover from touch, on one element: the pointer-event logic every
draggable or clickable widget rewrites. Press, then either release within `threshold` pixels
(`onTap`) or move past it (`onDragStart`, `onDrag`…, `onDragEnd`).

Only the first pointer that presses is followed (multi-touch ignores the others), and it is
captured with `setPointerCapture` so a drag keeps going outside the element — which means the
element receives the `pointerup` even when released elsewhere. Without pointer events (no
`addEventListener` on `target`), it does nothing and returns a function that does nothing.

```typescript
import { onPointerIntent } from '@helpers4/browser';

onPointerIntent(target: Element, handlers: PointerIntentHandlers, options: PointerIntentOptions): function
```

**Parameters:**

- `target: Element` — The element to listen on
- `handlers: PointerIntentHandlers` — What to do for each intent — see PointerIntentHandlers
- `options: PointerIntentOptions` (default: `{}`) — Threshold, button and cancellation — see PointerIntentOptions

**Returns:** `function` — A function that stops listening

**Examples:**

*Tell a tap from a drag*

A press released within the threshold is a tap; moving past it starts a drag.

```typescript
const stop = onPointerIntent(handle, {
  onTap: () => select(),
  onDrag: ({ dx, dy }) => move(dx, dy),
});
stop();
```

*Stop with an AbortSignal*

One abort() removes the listeners, as on unmount.

```typescript
const controller = new AbortController();
onPointerIntent(handle, { onPress }, { signal: controller.signal });
controller.abort();
```

---

### `prefersReducedMotion`

Whether the user asked the system to reduce motion (`prefers-reduced-motion: reduce`).

Outside a browser, it returns `false`. To react to changes, use
`watchMedia('(prefers-reduced-motion: reduce)', listener)`.

```typescript
import { prefersReducedMotion } from '@helpers4/browser';

prefersReducedMotion(): boolean
```

**Returns:** `boolean` — `true` if animations should be reduced or removed

**Examples:**

*Skip an animation*

Use a zero duration when the user asked to reduce motion.

```typescript
const duration = prefersReducedMotion() ? 0 : 300;
```

*React to changes*

Combine with watchMedia to follow the setting while the page is open.

```typescript
watchMedia('(prefers-reduced-motion: reduce)', (reduce) => player.setAnimations(!reduce));
```

---

### `preloadImages`

Loads and decodes several images with decodeImage, a few at a time, with
`mapSettled` from `helpers4/array`.

It never rejects: an image that fails does not stop the others, and its result says why.

```typescript
import { preloadImages } from '@helpers4/browser';

preloadImages(urls: readonly string[], options: PreloadImagesOptions): Promise<PromiseSettledResult<HTMLImageElement>[]>
```

**Parameters:**

- `urls: readonly string[]` — The image URLs
- `options: PreloadImagesOptions` (default: `{}`) — Concurrency — see PreloadImagesOptions

**Returns:** `Promise<PromiseSettledResult<HTMLImageElement>[]>` — One result per URL, in the same order

**Examples:**

*Preload the next screens*

Each URL gets its own result, like Promise.allSettled: a broken image does not stop the others.

```typescript
const results = await preloadImages(['/screens/a.png', '/screens/b.png']);
const failed = results.filter((result) => result.status === 'rejected');
```

*Limit concurrent downloads*

concurrency caps how many images load at the same time (6 by default).

```typescript
await preloadImages(thumbnails, { concurrency: 2 });
```

---

### `reflectAttribute`

Defines a property on `element` that is backed by an HTML attribute — what a custom element
needs for `<my-card heading="…" count="3" selected>`, in one line. Reading parses the attribute
by `type`; writing stores it (a boolean toggles the attribute, `null` or `undefined` removes it).
The attribute stays the single source of truth, so `setAttribute` and the property never disagree.

It defines an own property on the instance, so call it once per element (in a constructor or
`connectedCallback`). Calling it again for the same property replaces the previous definition.

```typescript
import { reflectAttribute } from '@helpers4/browser';

reflectAttribute(element: Element, property: string, options: ReflectAttributeOptions): function
```

**Parameters:**

- `element: Element` — The element that gets the property
- `property: string` — The property name, e.g. `'heading'`
- `options: ReflectAttributeOptions` (default: `{}`) — Type, attribute name and default — see ReflectAttributeOptions

**Returns:** `function` — A function that removes the property again

**Examples:**

*A number property backed by an attribute*

Writing the property sets the attribute, and setAttribute is seen by the property.

```typescript
reflectAttribute(card, 'count', { type: 'number' });
card.count = 3;
card.getAttribute('count') // => '3'
```

*A boolean property is the presence of the attribute*

Like hidden or disabled: true adds the attribute, false removes it.

```typescript
reflectAttribute(card, 'selected', { type: 'boolean' });
card.selected = true;
card.hasAttribute('selected') // => true
```

---

### `requestWorker`

Runs one job in a module worker: starts it, posts the request, relays its progress, resolves
with its result and ends it, whatever the outcome (result, error, `error` event or abort).
The worker answers with WorkerReply messages; a result can carry transferables by
posting them as `postMessage(reply, transferList)`.

Outside a browser (no `Worker`), a URL or a string rejects with a `TypeError`; a factory is
called as it is.

```typescript
import { requestWorker } from '@helpers4/browser';

requestWorker<Request, Result, Progress = never>(worker: string | URL | function, request: Request, options: RequestWorkerOptions<Progress>): Promise<Result>
```

**Parameters:**

- `worker: string | URL | function` — The worker's URL, or a function that creates it (needed for bundlers, which only
  see `new Worker(new URL('./job.js', import.meta.url), { type: 'module' })` written in place)
- `request: Request` — The message to post
- `options: RequestWorkerOptions<Progress>` (default: `{}`) — Transferables, progress and cancellation — see RequestWorkerOptions

**Returns:** `Promise<Result>` — The worker's result

**Examples:**

*Run a job with progress*

The worker replies with progress messages, then a result; it is ended afterwards.

```typescript
const bytes = await requestWorker<string, Uint8Array, number>(
  () => new Worker(new URL('./bake.js', import.meta.url), { type: 'module' }),
  'design.fig',
  { onProgress: (done) => bar.update(done) },
);
```

---

### `sha256Hex`

The SHA-256 digest of some data as a hexadecimal string, optionally cut short: a compact
content key, not a security check (a short prefix is easy to collide).

Outside a runtime with Web Crypto (`crypto.subtle`), it rejects with a `TypeError`.

```typescript
import { sha256Hex } from '@helpers4/browser';

sha256Hex(data: BufferSource, length: number): Promise<string>
```

**Parameters:**

- `data: BufferSource` — The data to hash
- `length: number` (default: `16`) — How many hex digits to keep, from `1` to `64`. Defaults to `16`

**Returns:** `Promise<string>` — The first `length` digits of the digest, in lowercase

**Examples:**

*Content key*

A short prefix of the digest names a piece of content.

```typescript
await sha256Hex(new TextEncoder().encode('abc'), 8) // => 'ba7816bf'
```

---

### `watchMedia`

Calls `listener` each time a CSS media query starts or stops matching.

It is not called with the current value: read it with matchesMedia. Outside a browser
(no `matchMedia`), it does nothing and returns a function that does nothing.

```typescript
import { watchMedia } from '@helpers4/browser';

watchMedia(query: string, listener: function, options: WatchMediaOptions): function
```

**Parameters:**

- `query: string` — A media query, e.g. `'(prefers-reduced-motion: reduce)'`
- `listener: function` — Receives whether the query matches after the change
- `options: WatchMediaOptions` (default: `{}`) — Cancellation — see WatchMediaOptions

**Returns:** `function` — A function that stops watching

**Examples:**

*Follow the color scheme*

The listener runs each time the query starts or stops matching.

```typescript
const stop = watchMedia('(prefers-color-scheme: dark)', (dark) => {
  document.documentElement.dataset.theme = dark ? 'dark' : 'light';
});
```

*Stop watching*

Call the returned function, e.g. when a component is removed.

```typescript
const stop = watchMedia('(min-width: 600px)', relayout);
// later
stop();
```

---

### `whenIdle`

Runs `callback` when the browser is idle, with `requestIdleCallback`, for work that can wait
(prefetching, analytics, warming a cache).

Where `requestIdleCallback` does not exist (Safari, Node.js), it falls back to `setTimeout`,
so the callback still runs, after the current task.

```typescript
import { whenIdle } from '@helpers4/browser';

whenIdle(callback: function, options: WhenIdleOptions): function
```

**Parameters:**

- `callback: function` — The work to run
- `options: WhenIdleOptions` (default: `{}`) — Timeout and cancellation — see WhenIdleOptions

**Returns:** `function` — A function that cancels the callback if it has not run yet

**Examples:**

*Defer non-urgent work*

Runs when the browser is idle, or after the timeout at the latest.

```typescript
whenIdle(() => preloadImages(nextScreens), { timeout: 2000 });
```

*Cancel it*

The returned function cancels the callback if it has not run yet.

```typescript
const cancel = whenIdle(warmCache);
cancel();
```

---

## ci

Package: `@helpers4/ci`

### `buildStatusTable`

Builds a Markdown table body from a map of job names to CI/CD statuses.
Each row follows the format `| icon | **Job Name** | badge |`.

Intended to be embedded in a PR comment template:
```
| | Job | Status |
|:---:|-----|:------:|
${buildStatusTable(jobs)}
```

```typescript
import { buildStatusTable } from '@helpers4/ci';

buildStatusTable(jobs: Record<string, string>): string
```

**Parameters:**

- `jobs: Record<string, string>` — Record mapping job display names to their CI status

**Returns:** `string` — Newline-separated Markdown table rows (no header, no footer)

**Examples:**

*Build a PR comment status table*

Generates the body rows of a Markdown table for a PR validation summary.

```typescript
const rows = buildStatusTable({
  '🧾 Conventional Commits': 'success',
  '🐚 ShellCheck':           'failure',
  '🧪 Tests':                'skipped',
});

// Embed in a comment template:
// | | Job | Status |
// |:---:|-----|:------:|
// ${rows}
```

---

### `DEFAULT_PERCENTAGE_TIERS`

Default tiers, geared towards coverage/quality-gate style percentages.
Follows shields.io color conventions: brightgreen >= 100, green >= 90, yellow >= 80, orange >= 60.

---

### `percentageToTier`

Maps a numeric percentage to a tier (icon, color, label) using configurable thresholds.

Tiers are matched by their highest `min` that is `<= value`; a `value` below every tier's
`min` (e.g. a negative percentage, or custom tiers that don't cover down to 0) falls back to
the tier with the lowest `min` — there's always a match as long as `tiers` is non-empty.

```typescript
import { percentageToTier } from '@helpers4/ci';

percentageToTier(value: number, tiers: readonly PercentageTier[]): PercentageTier
```

**Parameters:**

- `value: number` — The percentage to classify (typically 0-100, but not clamped)
- `tiers: readonly PercentageTier[]` (default: `DEFAULT_PERCENTAGE_TIERS`) — Threshold tiers to match against, in any order (defaults to DEFAULT_PERCENTAGE_TIERS)

**Returns:** `PercentageTier` — The matched tier

**Examples:**

*Coverage report tier*

Maps a coverage percentage to a tier using the built-in default thresholds.

```typescript
percentageToTier(95.2)
// => { min: 90, icon: '🟢', color: 'green', label: 'excellent' }

percentageToTier(42)
// => { min: 0, icon: '🔴', color: 'red', label: 'poor' }
```

*Custom pass/fail tiers*

Supply your own tiers, e.g. a simple two-tier pass/fail gate.

```typescript
const tiers = [
  { min: 50, icon: '🟢', color: 'green', label: 'pass' },
  { min: 0, icon: '🔴', color: 'red', label: 'fail' },
];

percentageToTier(75, tiers)  // => { min: 50, icon: '🟢', color: 'green', label: 'pass' }
percentageToTier(25, tiers)  // => { min: 0, icon: '🔴', color: 'red', label: 'fail' }
```

---

### `statusToBadge`

Maps a CI/CD job status to an inline code badge string.

| Status | Badge |
|--------|-------|
| `success` | `` `passing` `` |
| `failure` | `` `failing` `` |
| `skipped` | `` `skipped` `` |
| *(other)* | `` `unknown` `` |

```typescript
import { statusToBadge } from '@helpers4/ci';

statusToBadge(status: CiStatus): string
```

**Parameters:**

- `status: CiStatus` — The CI/CD job status

**Returns:** `string` — A Markdown inline-code badge

**Examples:**

*Map CI status to a Markdown badge*

Returns a Markdown code-span badge string for the given CI status.

```typescript
statusToBadge('success')  // => '`passing`'
statusToBadge('failure')  // => '`failing`'
statusToBadge('skipped')  // => '`skipped`'
statusToBadge('pending')  // => '`unknown`'
```

---

### `statusToIcon`

Maps a CI/CD job status to an emoji icon.

| Status | Icon |
|--------|------|
| `success` | ✅ |
| `failure` | ❌ |
| `skipped` | ⏭️ |
| *(other)* | ⚠️ |

```typescript
import { statusToIcon } from '@helpers4/ci';

statusToIcon(status: CiStatus): string
```

**Parameters:**

- `status: CiStatus` — The CI/CD job status

**Returns:** `string` — An emoji representing the status

**Examples:**

*Map CI status to icon*

Returns an emoji icon matching the given CI status.

```typescript
statusToIcon('success')  // => '✅'
statusToIcon('failure')  // => '❌'
statusToIcon('skipped')  // => '⏭️'
statusToIcon('pending')  // => '⚠️'
```

---

## color

Package: `@helpers4/color`

### `argbToRgb`

Converts a 32-bit packed ARGB integer (as used by e.g. Chromium's
`Local State` profile `background_color` field) into a CSS `rgb()` string.
The alpha byte (top 8 bits) is read but discarded — the result is always opaque.

```typescript
import { argbToRgb } from '@helpers4/color';

argbToRgb(argb: number): string
```

**Parameters:**

- `argb: number` — A 32-bit integer where bits 24-31 are alpha, 16-23 are red,
  8-15 are green, and 0-7 are blue

**Returns:** `string` — A `rgb(r,g,b)` CSS color string

**Examples:**

*Convert a packed ARGB integer to a CSS color*

The top byte (alpha) is discarded — the result is always opaque.

```typescript
argbToRgb(0xffff0000)
// => 'rgb(255,0,0)'
```

*Alpha byte does not affect the result*

Two ARGB values differing only in the alpha byte produce the same rgb() string.

```typescript
argbToRgb(0x00ff0000) === argbToRgb(0x80ff0000)
// => true
```

---

### `blendColors`

Composites a source color over a backdrop with a blend mode, as the browser does for
`mix-blend-mode` (W3C Compositing and Blending Level 1, source-over). Both colors are straight
(non-premultiplied); the maths run in premultiplied space.

```typescript
import { blendColors } from '@helpers4/color';

blendColors(backdrop: RgbColor, source: RgbColor, mode: BlendMode): RgbColor
```

**Parameters:**

- `backdrop: RgbColor` — The color underneath
- `source: RgbColor` — The color painted over it
- `mode: BlendMode` (default: `'normal'`) — The blend mode. Defaults to `'normal'`, a plain alpha composite.

**Returns:** `RgbColor` — The straight result: channels rounded to integers, alpha to 3 decimals

**Examples:**

*Paint a half-transparent color over another*

The default normal mode is a plain alpha composite.

```typescript
blendColors({ r: 255, g: 0, b: 0 }, { r: 0, g: 0, b: 255, a: 0.5 })
// => { r: 128, g: 0, b: 128, a: 1 }
```

*Use a CSS blend mode*

Same maths as mix-blend-mode, handy to compute what the browser would paint.

```typescript
blendColors({ r: 200, g: 100, b: 50 }, { r: 100, g: 100, b: 100 }, 'multiply')
// => { r: 78, g: 39, b: 20, a: 1 }
```

---

### `contrastRatio`

Computes the WCAG 2 contrast ratio between two colors, from 1 (identical) to 21 (black on
white). The lighter color is always put over the darker one, so the order of the arguments does
not matter. The ratio is not rounded, so it can be compared as it is with the WCAG thresholds:
4.5 (AA, normal text), 3 (AA, large text and UI components), 7 (AAA, normal text) and 4.5 (AAA,
large text). Alpha is ignored: flatten translucent colors first (see blendColors).

```typescript
import { contrastRatio } from '@helpers4/color';

contrastRatio(foreground: RgbColor, background: RgbColor): number
```

**Parameters:**

- `foreground: RgbColor` — The text (or foreground) color
- `background: RgbColor` — The color behind it

**Returns:** `number` — The contrast ratio, between 1 and 21

**Examples:**

*Black on white is the maximum contrast*

The ratio goes from 1 (identical colors) to 21.

```typescript
contrastRatio({ r: 0, g: 0, b: 0 }, { r: 255, g: 255, b: 255 }) // => 21
```

*Check a text color against the WCAG AA threshold*

Normal text needs 4.5; #777777 on white is just under it, #767676 just over.

```typescript
const white = { r: 255, g: 255, b: 255 };
contrastRatio({ r: 0x77, g: 0x77, b: 0x77 }, white) >= 4.5 // => false (4.48)
contrastRatio({ r: 0x76, g: 0x76, b: 0x76 }, white) >= 4.5 // => true (4.54)
```

---

### `hexToRgb`

Parses a hex color string (`#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa` — the
leading `#` is optional) into its RGB(A) channels.

```typescript
import { hexToRgb } from '@helpers4/color';

hexToRgb(hex: string): RgbColor | null
```

**Parameters:**

- `hex: string` — The hex color string to parse

**Returns:** `RgbColor | null` — The parsed color, or `null` if `hex` is not a valid hex color

**Examples:**

*Parse a hex color into RGB channels*

The leading # is optional; shorthand 3/4-digit forms are also supported.

```typescript
hexToRgb('#ff0000')
// => { r: 255, g: 0, b: 0, a: 1 }
```

*Returns null for an invalid color*

Lets you branch on parse failure instead of getting a garbage color.

```typescript
hexToRgb('not-a-color')
// => null
```

---

### `hsbToRgb`

Converts an HSB(A) color (also called HSV), as shown by design tool color pickers, into
RGB(A).

```typescript
import { hsbToRgb } from '@helpers4/color';

hsbToRgb(color: HsbColor): RgbColor
```

**Parameters:**

- `color: HsbColor` — The color to convert: `h` in degrees (any value, wrapped into 0-360), `s`/`b`
  in 0-100, `a` defaults to 1 (opaque) when omitted.

**Returns:** `RgbColor` — The equivalent RGB(A) color, channels rounded to integers in 0-255

**Examples:**

*Convert a design tool color*

From the HSB values of a color picker to RGB.

```typescript
hsbToRgb({ h: 0, s: 100, b: 100 }) // => { r: 255, g: 0, b: 0, a: 1 }
```

*Darker shade*

Lower the brightness to darken without changing the hue.

```typescript
hsbToRgb({ h: 120, s: 100, b: 50 }) // => { r: 0, g: 128, b: 0, a: 1 }
```

---

### `hslToCss`

Formats an HSL(A) color as a CSS `hsl()` value, in the modern space-separated syntax.

The hue is wrapped into 0-360, saturation and lightness are clamped to 0-100, all three rounded
to 1 decimal place; alpha is clamped to 0-1, rounded to 3 decimals, and left out when the color
is opaque.

```typescript
import { hslToCss } from '@helpers4/color';

hslToCss(color: HslColor): string
```

**Parameters:**

- `color: HslColor` — The color to format. `a` defaults to 1 (opaque) when omitted.

**Returns:** `string` — `hsl(h s% l%)`, or `hsl(h s% l% / a)` when translucent

**Examples:**

*Opaque color*

The alpha is left out.

```typescript
hslToCss({ h: 210, s: 100, l: 50 }) // => 'hsl(210 100% 50%)'
```

*Translucent color with a negative hue*

The hue is wrapped into 0-360 and the alpha comes after a slash.

```typescript
hslToCss({ h: -30, s: 80, l: 40, a: 0.25 }) // => 'hsl(330 80% 40% / 0.25)'
```

---

### `hslToRgb`

Converts an HSL(A) color into RGB(A).

```typescript
import { hslToRgb } from '@helpers4/color';

hslToRgb(color: HslColor): RgbColor
```

**Parameters:**

- `color: HslColor` — The color to convert. `h` is normalized modulo 360 (negative
  values wrap around), `s`/`l` are expected in 0-100, `a` defaults to 1
  (opaque) when omitted.

**Returns:** `RgbColor` — The equivalent RGB(A) color, with `r`/`g`/`b` rounded to 0-255

**Examples:**

*Convert an HSL color to RGB*

Useful after generating a hue programmatically (e.g. evenly spaced chart colors).

```typescript
hslToRgb({ h: 120, s: 100, l: 50 })
// => { r: 0, g: 255, b: 0, a: 1 }
```

*Hue wraps around 360 degrees*

Negative or out-of-range hues are normalized before conversion.

```typescript
hslToRgb({ h: -360, s: 100, l: 50 })
// => { r: 255, g: 0, b: 0, a: 1 }  (same as h: 0)
```

---

### `mixColors`

Mixes two colors in sRGB, as CSS `color-mix(in srgb, color P%, base)` does: `percent`% of
`color` and the rest of `base`. Alpha is interpolated in premultiplied space (CSS Color 4), so a
translucent color weighs less in the result. Opaque colors give a plain weighted average of the
channels.

```typescript
import { mixColors } from '@helpers4/color';

mixColors(color: RgbColor, base: RgbColor, percent: number): RgbColor
```

**Parameters:**

- `color: RgbColor` — The color to mix in
- `base: RgbColor` — The color it is mixed into
- `percent: number` (default: `50`) — Share of `color`, from 0 (all `base`) to 100 (all `color`); clamped. Defaults to 50.

**Returns:** `RgbColor` — The straight result: channels rounded to integers, alpha to 3 decimals

**Examples:**

*Tint a color toward another*

The same as color-mix(in srgb, red 25%, blue), usable where there is no CSS engine.

```typescript
mixColors({ r: 255, g: 0, b: 0 }, { r: 0, g: 0, b: 255 }, 25)
// => { r: 64, g: 0, b: 191, a: 1 }
```

*Mix a translucent color*

Alpha is interpolated in premultiplied space, as CSS Color 4 specifies.

```typescript
mixColors({ r: 255, g: 0, b: 0, a: 0.5 }, { r: 0, g: 0, b: 255 })
// => { r: 85, g: 0, b: 170, a: 0.75 }
```

---

### `premultiply`

Multiplies the color channels by the alpha channel (premultiplied alpha), the form compositing
and GPU blending work in. The channels are returned as they are, not rounded, so that
unpremultiply gives the color back.

```typescript
import { premultiply } from '@helpers4/color';

premultiply(color: RgbColor): RgbColor
```

**Parameters:**

- `color: RgbColor` — A straight (non-premultiplied) color; a missing alpha is 1

**Returns:** `RgbColor` — The premultiplied color

**Examples:**

*Premultiply a half-transparent color*

The channels are scaled by the alpha, the form GPU blending and canvas pixels use.

```typescript
premultiply({ r: 255, g: 100, b: 0, a: 0.5 })
// => { r: 127.5, g: 50, b: 0, a: 0.5 }
```

*An opaque color is unchanged*

A missing alpha counts as 1.

```typescript
premultiply({ r: 10, g: 20, b: 30 })
// => { r: 10, g: 20, b: 30, a: 1 }
```

---

### `relativeLuminance`

Computes the WCAG 2.x relative luminance of a color: the perceived brightness from 0 (black) to
1 (white), after linearising the sRGB channels. The alpha channel is ignored: flatten a
translucent color over its background first (see blendColors).

```typescript
import { relativeLuminance } from '@helpers4/color';

relativeLuminance(color: RgbColor): number
```

**Parameters:**

- `color: RgbColor` — An sRGB color, channels 0-255

**Returns:** `number` — The relative luminance, between 0 and 1

**Examples:**

*Measure how bright a color is*

Black is 0, white is 1, and green weighs the most of the three primaries.

```typescript
relativeLuminance({ r: 0, g: 0, b: 0 }) // => 0
relativeLuminance({ r: 0, g: 255, b: 0 }) // => 0.7152
```

*Pick light or dark text for a background*

A background brighter than about 0.18 takes dark text better than white text.

```typescript
relativeLuminance({ r: 255, g: 220, b: 0 }) > 0.18 // => true
```

---

### `rgbToCss`

Formats an RGB(A) color as a CSS `rgb()` value, in the modern space-separated syntax that
every current browser and SVG renderer reads.

Channels are clamped to 0-255 and rounded; alpha is clamped to 0-1, rounded to 3 decimals, and
left out when the color is opaque.

```typescript
import { rgbToCss } from '@helpers4/color';

rgbToCss(color: RgbColor): string
```

**Parameters:**

- `color: RgbColor` — The color to format. `a` defaults to 1 (opaque) when omitted.

**Returns:** `string` — `rgb(r g b)`, or `rgb(r g b / a)` when translucent

**Examples:**

*Opaque color*

The alpha is left out.

```typescript
rgbToCss({ r: 255, g: 128, b: 0 }) // => 'rgb(255 128 0)'
```

*Translucent color*

The alpha comes after a slash.

```typescript
rgbToCss({ r: 255, g: 128, b: 0, a: 0.5 }) // => 'rgb(255 128 0 / 0.5)'
```

---

### `rgbToHex`

Converts an RGB(A) color into a hex color string.

`r`/`g`/`b` are clamped to 0-255 and rounded to the nearest integer before
formatting. The alpha channel is only appended (as `#rrggbbaa`) when it is
below 1 — fully opaque colors format as the plain 6-digit `#rrggbb`.

```typescript
import { rgbToHex } from '@helpers4/color';

rgbToHex(color: RgbColor): string
```

**Parameters:**

- `color: RgbColor` — The color to convert. `a` defaults to 1 (opaque) when omitted.

**Returns:** `string` — A lowercase hex color string

**Examples:**

*Format an opaque color as hex*

Alpha defaults to 1 (opaque) and is omitted from the output.

```typescript
rgbToHex({ r: 255, g: 0, b: 0 })
// => '#ff0000'
```

*Include alpha when the color is translucent*

A non-opaque color formats as an 8-digit #rrggbbaa string.

```typescript
rgbToHex({ r: 0, g: 255, b: 0, a: 0.5 })
// => '#00ff0080'
```

---

### `rgbToHsb`

Converts an RGB(A) color into HSB(A), the model design tools (Figma, Sketch, XD) show in their
color pickers. Unlike HSL lightness, brightness `100` is the pure color, not white.

`h`/`s`/`b` are rounded to 1 decimal place to avoid floating-point noise.

```typescript
import { rgbToHsb } from '@helpers4/color';

rgbToHsb(color: RgbColor): HsbColor
```

**Parameters:**

- `color: RgbColor` — The color to convert. `r`/`g`/`b` are expected in 0-255,
  `a` defaults to 1 (opaque) when omitted.

**Returns:** `HsbColor` — The equivalent HSB(A) color: `h` in 0-360, `s`/`b` in 0-100

**Examples:**

*Show a color like a design tool picker*

Pure colors have a brightness of 100.

```typescript
rgbToHsb({ r: 255, g: 0, b: 0 }) // => { h: 0, s: 100, b: 100, a: 1 }
```

*White versus HSL*

White is saturation 0 and brightness 100 (HSL would say lightness 100).

```typescript
rgbToHsb({ r: 255, g: 255, b: 255 }) // => { h: 0, s: 0, b: 100, a: 1 }
```

---

### `rgbToHsl`

Converts an RGB(A) color into HSL(A).

`h`/`s`/`l` are rounded to 1 decimal place to avoid floating-point noise.

```typescript
import { rgbToHsl } from '@helpers4/color';

rgbToHsl(color: RgbColor): HslColor
```

**Parameters:**

- `color: RgbColor` — The color to convert. `r`/`g`/`b` are expected in 0-255,
  `a` defaults to 1 (opaque) when omitted.

**Returns:** `HslColor` — The equivalent HSL(A) color: `h` in 0-360, `s`/`l` in 0-100

**Examples:**

*Convert an RGB color to HSL*

Useful for generating tints/shades by adjusting lightness.

```typescript
rgbToHsl({ r: 255, g: 0, b: 0 })
// => { h: 0, s: 100, l: 50, a: 1 }
```

*Grayscale colors have no saturation*

When r, g, and b are equal, the color is achromatic (s = 0).

```typescript
rgbToHsl({ r: 128, g: 128, b: 128 })
// => { h: 0, s: 0, l: 50.2, a: 1 }
```

---

### `rgbToUnit`

Converts an RgbColor (channels from `0` to `255`) into a color whose channels are floats
from `0` to `1`, the way Figma, Sketch and Penpot store them. Alpha is kept as it is.

```typescript
import { rgbToUnit } from '@helpers4/color';

rgbToUnit(color: RgbColor): RgbColor
```

**Parameters:**

- `color: RgbColor` — The color. `a` defaults to 1 (opaque)

**Returns:** `RgbColor` — The color with `r`, `g`, `b` from `0` to `1`

**Examples:**

*Write a design tool color*

Channels from 0 to 1, alpha unchanged.

```typescript
rgbToUnit({ r: 255, g: 51, b: 0 }) // => { r: 1, g: 0.2, b: 0, a: 1 }
```

---

### `unitToRgb`

Converts a color whose channels are floats from `0` to `1` (as Figma, Sketch and Penpot store
them) into an RgbColor, with channels from `0` to `255`. Alpha is already `0`–`1` and
is kept as it is. The channels are not rounded: rgbToCss and rgbToHex do it.

```typescript
import { unitToRgb } from '@helpers4/color';

unitToRgb(color: RgbColor): RgbColor
```

**Parameters:**

- `color: RgbColor` — The color, with `r`, `g`, `b` from `0` to `1`. `a` defaults to 1 (opaque)

**Returns:** `RgbColor` — The color with channels from `0` to `255`

**Examples:**

*Read a design tool color*

Figma, Sketch and Penpot store channels from 0 to 1.

```typescript
rgbToHex(unitToRgb({ r: 1, g: 0.5, b: 0, a: 0.5 })) // => '#ff800080'
```

---

### `unpremultiply`

Divides the color channels by the alpha channel: the inverse of premultiply. A fully
transparent color has lost its channels, so it comes back as transparent black.

```typescript
import { unpremultiply } from '@helpers4/color';

unpremultiply(color: RgbColor): RgbColor
```

**Parameters:**

- `color: RgbColor` — A premultiplied color; a missing alpha is 1

**Returns:** `RgbColor` — The straight (non-premultiplied) color

**Examples:**

*Recover the straight color*

Divides the channels by the alpha, the inverse of premultiply.

```typescript
unpremultiply({ r: 127.5, g: 50, b: 0, a: 0.5 })
// => { r: 255, g: 100, b: 0, a: 0.5 }
```

*A transparent color becomes transparent black*

The channels are lost at alpha 0, so there is nothing to recover.

```typescript
unpremultiply({ r: 0, g: 0, b: 0, a: 0 })
// => { r: 0, g: 0, b: 0, a: 0 }
```

---

## commit

Package: `@helpers4/commit`

### `analyzeCommits`

Analyses a list of commits to suggest a semantic version bump.

Each commit is parsed via `parseConventionalCommit`. The body is also
scanned for `BREAKING CHANGE:` / `BREAKING-CHANGE:` markers. The bump rule
is:

- any breaking change → `'major'`
- otherwise any `feat` → `'minor'`
- otherwise any `fix` → `'patch'`
- otherwise (non-empty list of non-conventional commits) → `'patch'`
- empty list → `'patch'` with reason "No commits to analyse"

```typescript
import { analyzeCommits } from '@helpers4/commit';

analyzeCommits(commits: readonly AnalyzableCommit[]): CommitAnalysis
```

**Parameters:**

- `commits: readonly AnalyzableCommit[]` — Iterable of commits to analyse. Only `subject` is required.

**Returns:** `CommitAnalysis` — Aggregated analysis with the suggested bump and reason.

**Examples:**

*Suggest a semver bump from a list of commits*

Walks through commits and suggests `major`, `minor`, or `patch` based on Conventional Commits.

```typescript
analyzeCommits([
  { subject: 'feat: add login' },
  { subject: 'fix: handle null' },
])
// => { suggestedBump: 'minor', hasFeatures: true, hasFixes: true, ... }
```

*Promote to major on breaking change*

A `!` marker or a `BREAKING CHANGE:` footer always promotes the suggestion to `major`.

```typescript
analyzeCommits([{ subject: 'feat!: drop v1 API' }]).suggestedBump
// => 'major'
```

---

### `buildConventionalCommitRegex`

Builds a regular expression matching the **subject line** of a Conventional
Commits message.

The returned regex exposes four capture groups:

1. type
2. scope (or `undefined` when absent)
3. breaking marker (`'!'` or `undefined`)
4. description

```typescript
import { buildConventionalCommitRegex } from '@helpers4/commit';

buildConventionalCommitRegex(options: ConventionalCommitOptions): RegExp
```

**Parameters:**

- `options: ConventionalCommitOptions` (default: `{}`) — Constrain accepted types/scopes and toggle scope requirement.

**Returns:** `RegExp` — Regex anchored on `^...$` matching the subject line only.

**Examples:**

*Match the default Conventional Commits format*

Returns a regex matching `type(scope)?!?: description` on the subject line.

```typescript
const regex = buildConventionalCommitRegex();
regex.test('feat(api): add endpoint') // => true
regex.test('not a commit') // => false
```

*Restrict accepted types and require a scope*

Constrain accepted types and force the scope segment to be present.

```typescript
const regex = buildConventionalCommitRegex({
  types: ['feat', 'fix'],
  requireScope: true,
});
regex.test('feat(api): x') // => true
regex.test('feat: missing scope') // => false
regex.test('chore(api): wrong type') // => false
```

---

### `isConventionalCommit`

Checks whether a commit message's subject line follows the Conventional
Commits format constrained by the given options.

Only the first line is inspected — body and footer are ignored.

```typescript
import { isConventionalCommit } from '@helpers4/commit';

isConventionalCommit(message: string, options?: ConventionalCommitOptions): boolean
```

**Parameters:**

- `message: string` — Full commit message or just its subject line.
- `options?: ConventionalCommitOptions` — Optional constraints (allowed types/scopes, scope requirement).

**Returns:** `boolean` — `true` when the subject line matches; `false` otherwise.

**Examples:**

*Validate a commit subject*

Returns `true` when the first line follows the Conventional Commits format.

```typescript
isConventionalCommit('feat(api): add endpoint') // => true
isConventionalCommit('hello world') // => false
```

*Restrict accepted types*

Reject any commit whose type is not in the supplied allowlist.

```typescript
isConventionalCommit('chore: x', { types: ['feat', 'fix'] }) // => false
isConventionalCommit('feat: x', { types: ['feat', 'fix'] }) // => true
```

---

### `parseConventionalCommit`

Parses a Conventional Commits message into a structured object.

The first line is matched against the regex produced by
`buildConventionalCommitRegex(options)`. The remaining content is split into
a `body` and an optional trailing `footer` block (lines matching
`Token: value` / `Token #value`, including `BREAKING CHANGE: ...`).

```typescript
import { parseConventionalCommit } from '@helpers4/commit';

parseConventionalCommit(message: string, options?: ConventionalCommitOptions): ParsedConventionalCommit | null
```

**Parameters:**

- `message: string` — Full commit message (subject + optional body/footer).
- `options?: ConventionalCommitOptions` — Optional constraints forwarded to the regex builder.

**Returns:** `ParsedConventionalCommit | null` — Parsed commit object, or `null` when the subject is not conventional.

**Examples:**

*Parse a Conventional Commits subject*

Extracts type, scope, breaking flag, and description.

```typescript
parseConventionalCommit('feat(api)!: add v2')
// => { type: 'feat', scope: 'api', breaking: true, description: 'add v2', body: '', footer: '' }
```

*Detect breaking changes from the footer*

A `BREAKING CHANGE:` footer flags the commit as breaking even without the `!` marker.

```typescript
parseConventionalCommit('feat: add option\n\nBREAKING CHANGE: drops old config').breaking
// => true
```

*Returns null on a non-conventional message*

Non-matching subjects return `null` rather than throwing.

```typescript
parseConventionalCommit('hello world') // => null
```

---

## date

Package: `@helpers4/date`

### `addDays`

Adds days to a date.

Returns a **new** `Date` — the original is never mutated.
Returns `null` if the input is invalid.

```typescript
import { addDays } from '@helpers4/date';

addDays(date: DateLike, amount: number): Date | null
```

**Parameters:**

- `date: DateLike` — The base date
- `amount: number` — Number of days to add (negative to subtract)

**Returns:** `Date | null` — A new Date, or `null` if the input is invalid

**Examples:**

*addDays*

```typescript
```ts
addDays('2025-01-19', 10)   // => Date(2025-01-29)
addDays('2025-01-19', -5)   // => Date(2025-01-14)
```
```

---

### `addMonths`

Adds months to a date.

Returns a **new** `Date` — the original is never mutated.
When the resulting month has fewer days, JavaScript clamps to the
next month (e.g. Jan 31 + 1 month → Mar 3). Use with caution.
Returns `null` if the input is invalid.

```typescript
import { addMonths } from '@helpers4/date';

addMonths(date: DateLike, amount: number): Date | null
```

**Parameters:**

- `date: DateLike` — The base date
- `amount: number` — Number of months to add (negative to subtract)

**Returns:** `Date | null` — A new Date, or `null` if the input is invalid

**Examples:**

*addMonths*

```typescript
```ts
addMonths('2025-01-15', 1)    // => Date(2025-02-15)
addMonths('2025-01-31', 1)    // => Date(2025-03-03) — overflow
addMonths('2025-03-15', -1)   // => Date(2025-02-15)
```
```

---

### `addYears`

Adds years to a date.

Returns a **new** `Date` — the original is never mutated.
Returns `null` if the input is invalid.

```typescript
import { addYears } from '@helpers4/date';

addYears(date: DateLike, amount: number): Date | null
```

**Parameters:**

- `date: DateLike` — The base date
- `amount: number` — Number of years to add (negative to subtract)

**Returns:** `Date | null` — A new Date, or `null` if the input is invalid

**Examples:**

*addYears*

```typescript
```ts
addYears('2025-01-19', 1)    // => Date(2026-01-19)
addYears('2024-02-29', 1)    // => Date(2025-03-01) — leap year overflow
addYears('2025-06-15', -2)   // => Date(2023-06-15)
```
```

---

### `clampDate`

Clamps a date to a [min, max] range.

Returns a **new** `Date` — the original is never mutated.
Returns `null` if any of the inputs is invalid.

```typescript
import { clampDate } from '@helpers4/date';

clampDate(date: DateLike, min: DateLike, max: DateLike): Date | null
```

**Parameters:**

- `date: DateLike` — The date to clamp
- `min: DateLike` — The minimum allowed date
- `max: DateLike` — The maximum allowed date

**Returns:** `Date | null` — A new Date clamped to the range, or `null` if any input is invalid

**Examples:**

*clampDate*

```typescript
```ts
clampDate('2025-06-15', '2025-01-01', '2025-03-31')
// => Date(2025-03-31) — clamped to max

clampDate('2025-02-15', '2025-01-01', '2025-03-31')
// => Date(2025-02-15) — within range, unchanged
```
```

---

### `compare`

Comparison of two dates.

Accepts any DateLike input (Date, timestamp, or date string).

```typescript
import { compare } from '@helpers4/date';

compare(dateA: DateLike, dateB: DateLike, options: DateCompareOptions): boolean
```

**Parameters:**

- `dateA: DateLike` — First date to compare
- `dateB: DateLike` — Second date to compare
- `options: DateCompareOptions` (default: `{}`) — Comparison options

**Returns:** `boolean` — `true` if dates are identical according to the specified precision, `false` otherwise

**Examples:**

*Compare dates with millisecond precision*

By default, two identical Date objects are equal.

```typescript
const d = new Date('2025-01-19T12:00:00Z');
compare(d, new Date('2025-01-19T12:00:00Z'))
// => true
```

*Compare only by day*

Using day precision ignores the time part.

```typescript
compare(
  new Date('2025-01-19T08:00:00Z'),
  new Date('2025-01-19T23:59:59Z'),
  { precision: 'days' }
)
// => true
```

---

### `daysInMonth`

Returns the number of days in the given month of the given year.

Month is **1-based** (1 = January, 12 = December) to match human
convention and ISO 8601 (unlike `Date.getMonth()` which is 0-based).

Returns `NaN` if the month is out of range.

```typescript
import { daysInMonth } from '@helpers4/date';

daysInMonth(year: number, month: number): number
```

**Parameters:**

- `year: number` — A full year number (e.g. 2025)
- `month: number` — 1-based month number (1–12)

**Returns:** `number` — Number of days in that month, or `NaN` for invalid month

**Examples:**

*daysInMonth*

```typescript
```ts
daysInMonth(2025, 1)  // => 31 (January)
daysInMonth(2025, 2)  // => 28 (February, non-leap)
daysInMonth(2024, 2)  // => 29 (February, leap)
daysInMonth(2025, 4)  // => 30 (April)
```
```

---

### `difference`

Calculates the difference between two dates in the specified unit.

Accepts any DateLike input (Date, timestamp, or date string).

Unlike the removed `daysDifference`, the default `'days'` unit is **not** rounded —
it returns the exact fractional number of days. Wrap the result in `Math.round`
if you need a whole-number day count.

```typescript
import { difference } from '@helpers4/date';

difference(dateA: DateLike, dateB: DateLike, options: DateDifferenceOptions): number
```

**Parameters:**

- `dateA: DateLike` — First date
- `dateB: DateLike` — Second date
- `options: DateDifferenceOptions` (default: `{}`) — Difference options

**Returns:** `number` — The difference between the two dates, or `NaN` if either date is invalid

**Examples:**

*difference*

```typescript
```ts
difference('2025-01-01', '2025-01-10')
// => 9
difference('2025-01-01T00:00:00Z', '2025-01-01T12:00:00Z')
// => 0.5 (fractional — use Math.round(difference(a, b)) for a whole-day count)
difference('2025-01-01T00:00:00Z', '2025-01-01T02:30:00Z', { unit: 'hours' })
// => 2.5
difference('2025-01-10', '2025-01-01', { absolute: false })
// => -9
```
```

---

### `eachDay`

Returns an array of `Date` objects for each day from `start` to `end` (inclusive).

Both boundaries are included. If `start > end`, an empty array is returned.
Returns an empty array if either input is invalid.

```typescript
import { eachDay } from '@helpers4/date';

eachDay(start: DateLike, end: DateLike): Date[]
```

**Parameters:**

- `start: DateLike` — Start date (inclusive)
- `end: DateLike` — End date (inclusive)

**Returns:** `Date[]` — An array of Date objects, one per day

**Examples:**

*eachDay*

```typescript
```ts
eachDay('2025-01-01', '2025-01-03')
// => [Date(2025-01-01), Date(2025-01-02), Date(2025-01-03)]
```
```

---

### `eachMonth`

Returns an array of `Date` objects for the first day of each month
from `start` to `end` (inclusive).

Each returned Date is normalized to the 1st of the month at 00:00:00.000.
If `start > end`, an empty array is returned.
Returns an empty array if either input is invalid.

```typescript
import { eachMonth } from '@helpers4/date';

eachMonth(start: DateLike, end: DateLike): Date[]
```

**Parameters:**

- `start: DateLike` — Start date (inclusive — the month containing this date is included)
- `end: DateLike` — End date (inclusive — the month containing this date is included)

**Returns:** `Date[]` — An array of Date objects, one per month (each on the 1st)

**Examples:**

*eachMonth*

```typescript
```ts
eachMonth('2025-01-15', '2025-04-10')
// => [Date(2025-01-01), Date(2025-02-01), Date(2025-03-01), Date(2025-04-01)]
```
```

---

### `endOf`

Returns a new `Date` set to the **end** of the given unit.

- `'day'`   — 23:59:59.999
- `'month'` — last day of the month, 23:59:59.999
- `'year'`  — December 31st, 23:59:59.999

Returns `null` if the input is invalid.

```typescript
import { endOf } from '@helpers4/date';

endOf(date: DateLike, unit: DateTruncUnit): Date | null
```

**Parameters:**

- `date: DateLike` — The base date
- `unit: DateTruncUnit` — The unit to round to

**Returns:** `Date | null` — A new Date at the end of the unit, or `null`

**Examples:**

*endOf*

```typescript
```ts
endOf('2025-06-15T14:30:00Z', 'day')    // => 2025-06-15T23:59:59.999Z
endOf('2025-06-15T14:30:00Z', 'month')  // => 2025-06-30T23:59:59.999Z
endOf('2025-06-15T14:30:00Z', 'year')   // => 2025-12-31T23:59:59.999Z
```
```

---

### `ensureDate`

Safely converts a date-like value to a valid `Date` object, or returns `null`.

Accepts `Date`, timestamps (seconds or milliseconds, auto-detected), date strings,
and objects with an `epochMilliseconds` property (e.g. `Temporal.Instant`,
`Temporal.ZonedDateTime`).
Returns `null` for `null`, `undefined`, empty strings, `0`, and any value that
produces an invalid `Date`.

This is the date equivalent of ensureArray — it normalizes flexible
input into a guaranteed type (or a safe fallback).

```typescript
import { ensureDate } from '@helpers4/date';

ensureDate(input: DateLike | null | undefined): Date | null
```

**Parameters:**

- `input: DateLike | null | undefined` — A date-like value to convert

**Returns:** `Date | null` — A valid `Date` object, or `null` if the input is invalid

**Examples:**

*ensureDate*

```typescript
```ts
ensureDate('2025-01-19T12:00:00Z') // => Date
ensureDate(1737290400)             // => Date (from Unix seconds)
ensureDate(1737290400000)          // => Date (from milliseconds)
ensureDate(new Date())             // => Date (same reference)
ensureDate(null)                   // => null
ensureDate('invalid')              // => null
```
```

---

### `format`

Formats a date as a short label that does not depend on the machine: UTC, English, and
`Jul 27, 2026` by default. A shorthand for
`formatInTimezone(date, 'UTC', { locale, formatOptions })`.

`formatOptions` replaces the default format rather than extending it, so
`{ month: 'short', day: 'numeric' }` gives `Jul 27` with no year.

Returns `null` if the date or the locale is invalid.

```typescript
import { format } from '@helpers4/date';

format(date: DateLike, formatOptions: DateTimeFormatOptions, locale: string): string | null
```

**Parameters:**

- `date: DateLike` — The date to format
- `formatOptions: DateTimeFormatOptions` (default: `DEFAULT_FORMAT`) — `Intl.DateTimeFormat` options (default: day, short month, year)
- `locale: string` (default: `'en'`) — BCP 47 locale tag (default: `'en'`)

**Returns:** `string | null` — The formatted date, or `null`

**Examples:**

*format*

```typescript
```ts
format('2026-07-27')                                   // => 'Jul 27, 2026'
format('2026-07-27', { month: 'short', day: 'numeric' }) // => 'Jul 27'
format('2026-07-27', undefined, 'fr')                  // => '27 juil. 2026'
format('nope')                                         // => null
```
```

---

### `formatDuration`

Formats a duration in milliseconds as a compact human-readable string.

Produces output like `"1h 23m 45s"`. Zero-valued leading units are
omitted (e.g. `"23m 45s"` instead of `"0h 23m 45s"`), but trailing
zeros are kept up to the minimum unit (`"1h 0m 0s"` when `minUnit`
is `'seconds'`).

Negative durations are prefixed with `"-"`.
A zero duration returns `"0s"` (or `"0m"` / `"0h"` depending on `minUnit`).

```typescript
import { formatDuration } from '@helpers4/date';

formatDuration(ms: number, options: FormatDurationOptions): string
```

**Parameters:**

- `ms: number` — Duration in milliseconds
- `options: FormatDurationOptions` (default: `{}`) — Optional configuration

**Returns:** `string` — A compact duration string

**Examples:**

*formatDuration*

```typescript
```ts
formatDuration(5025000)           // => "1h 23m 45s"
formatDuration(45000)             // => "45s"
formatDuration(3600000)           // => "1h 0m 0s"
formatDuration(5025000, { minUnit: 'minutes' }) // => "1h 23m"
formatDuration(5025000, { padded: true })       // => "01h 23m 45s"
formatDuration(-5025000)          // => "-1h 23m 45s"
```
```

---

### `formatInTimezone`

Formats a date in a specific IANA timezone using `Intl.DateTimeFormat`.

Returns `null` if the date or timezone is invalid.

```typescript
import { formatInTimezone } from '@helpers4/date';

formatInTimezone(date: DateLike, tz: string, options: FormatInTimezoneOptions): string | null
```

**Parameters:**

- `date: DateLike` — The date to format
- `tz: string` — IANA timezone identifier (e.g. `'Asia/Tokyo'`)
- `options: FormatInTimezoneOptions` (default: `{}`) — Optional locale and format configuration

**Returns:** `string | null` — A formatted date string, or `null`

**Examples:**

*formatInTimezone*

```typescript
```ts
formatInTimezone('2025-01-19T12:00:00Z', 'Asia/Tokyo')
// => "1/19/2025, 9:00:00 PM" (en-US default)

formatInTimezone('2025-01-19T12:00:00Z', 'Europe/Paris', {
  locale: 'fr-FR',
  formatOptions: { dateStyle: 'long', timeStyle: 'short' },
})
// => "19 janvier 2025, 13:00"
```
```

---

### `formatPartial`

Formats a partial ISO date at the precision it was given, in UTC: a year alone is
approximate and reads `c. 2008`, a month `Mar 2008` and a full day `Mar 9, 2008`.

Month names and their order follow `locale`. The marker before a year alone does not: see
FormatPartialOptions.

Returns `null` when parsePartial would, or when the locale is invalid.

```typescript
import { formatPartial } from '@helpers4/date';

formatPartial(input: string, options: FormatPartialOptions): string | null
```

**Parameters:**

- `input: string` — A `YYYY`, `YYYY-MM` or `YYYY-MM-DD` string
- `options: FormatPartialOptions` (default: `{}`) — Locale and approximate-year marker — see FormatPartialOptions

**Returns:** `string | null` — The label, or `null`

**Examples:**

*Label at the known precision*

An approximate year reads "c. 2008", a month "Mar 2008", a day "Mar 9, 2008".

```typescript
formatPartial('2008')       // => 'c. 2008'
formatPartial('2008-03')    // => 'Mar 2008'
formatPartial('2008-03-09') // => 'Mar 9, 2008'
```

*Another language*

The locale sets the month names; the marker for a year alone is a word, so you give it.

```typescript
formatPartial('2008', { locale: 'fr', approximate: 'vers' }) // => 'vers 2008'
formatPartial('2008-03-09', { locale: 'fr' })                // => '9 mars 2008'
```

*Invalid input*

Returns null instead of a wrong label.

```typescript
formatPartial('2008-13') // => null
```

---

### `fromMillis`

Creates a `Date` from a timestamp in **milliseconds**.

Use this when receiving a timestamp from a JS-native source
(e.g. `Date.now()`, `performance.timeOrigin`). No heuristic — the
input is always treated as milliseconds.

```typescript
import { fromMillis } from '@helpers4/date';

fromMillis(ms: number): Date | null
```

**Parameters:**

- `ms: number` — Milliseconds since the Unix epoch

**Returns:** `Date | null` — A valid `Date`, or `null` for `NaN` / non-finite input

**Examples:**

*fromMillis*

```typescript
```ts
fromMillis(1737288000000) // => Date('2025-01-19T12:00:00Z')
fromMillis(0)             // => Date('1970-01-01T00:00:00Z')
fromMillis(NaN)           // => null
```
```

---

### `fromSeconds`

Creates a `Date` from a timestamp in **seconds**.

Use this when receiving a timestamp from a backend that sends seconds
(e.g. Java `Instant.getEpochSecond()`). No heuristic — the input is
always treated as seconds.

```typescript
import { fromSeconds } from '@helpers4/date';

fromSeconds(seconds: number): Date | null
```

**Parameters:**

- `seconds: number` — Seconds since the Unix epoch

**Returns:** `Date | null` — A valid `Date`, or `null` for `NaN` / non-finite input

**Examples:**

*fromSeconds*

```typescript
```ts
fromSeconds(1737288000)  // => Date('2025-01-19T12:00:00Z')
fromSeconds(0)           // => Date('1970-01-01T00:00:00Z')
fromSeconds(NaN)         // => null
```
```

---

### `getTimezoneOffset`

Returns the UTC offset **in minutes** for the given IANA timezone
at a specific point in time.

A positive value means the timezone is **ahead** of UTC (e.g. `+60` for CET).
Returns `null` if the timezone is invalid or the date cannot be parsed.

The implementation uses `Intl.DateTimeFormat` to extract the local
representation in the target timezone, then computes the delta from UTC.

```typescript
import { getTimezoneOffset } from '@helpers4/date';

getTimezoneOffset(tz: string, date: DateLike): number | null
```

**Parameters:**

- `tz: string` — IANA timezone identifier (e.g. `'America/New_York'`)
- `date: DateLike` (default: `...`) — Reference date (defaults to now)

**Returns:** `number | null` — Offset in minutes, or `null` if inputs are invalid

**Examples:**

*getTimezoneOffset*

```typescript
```ts
getTimezoneOffset('America/New_York', '2025-01-19T12:00:00Z') // => -300 (EST)
getTimezoneOffset('Europe/Paris', '2025-07-19T12:00:00Z')     // => 120  (CEST)
```
```

---

### `isBusinessDay`

Checks whether a date falls on a business day (i.e. **not** a weekend day).

This is the logical inverse of isWeekend. By default, business days
are Monday through Friday. Pass a custom `weekendDays` to adapt to other
calendars.

> **Note:** This helper does **not** account for public holidays — those are
> country- and region-specific. Use it in combination with your own holiday
> list if needed.

Returns `false` if the input is invalid.

```typescript
import { isBusinessDay } from '@helpers4/date';

isBusinessDay(date: DateLike, weekendDays: readonly WeekDay[]): boolean
```

**Parameters:**

- `date: DateLike` — The date to check
- `weekendDays: readonly WeekDay[]` (default: `DEFAULT_WEEKEND`) — Override which days count as weekend (default: `[0, 6]`)

**Returns:** `boolean` — `true` if the date is not a weekend day

**Examples:**

*isBusinessDay*

```typescript
```ts
isBusinessDay('2025-01-20') // => true  (Monday)
isBusinessDay('2025-01-18') // => false (Saturday)

// UAE weekend (Friday + Saturday)
const uaeWeekend = [WeekDays.Friday, WeekDays.Saturday] as const;
isBusinessDay('2025-01-19', uaeWeekend) // => true  (Sunday = workday)
isBusinessDay('2025-01-17', uaeWeekend) // => false (Friday = weekend)
```
```

---

### `isLeapYear`

Returns `true` if the given year is a leap year.

A year is a leap year when it is divisible by 4, **except** century
years which must also be divisible by 400.

```typescript
import { isLeapYear } from '@helpers4/date';

isLeapYear(year: number): boolean
```

**Parameters:**

- `year: number` — A full year number (e.g. 2024)

**Returns:** `boolean` — `true` if the year is a leap year

**Examples:**

*isLeapYear*

```typescript
```ts
isLeapYear(2024) // => true
isLeapYear(2025) // => false
isLeapYear(2000) // => true  (divisible by 400)
isLeapYear(1900) // => false (century, not divisible by 400)
```
```

---

### `isoWeek`

ISO 8601 week of a date: weeks start on Monday and week 1 is the one that contains the
first Thursday of the year, so the first days of January can belong to week 52 or 53 of
the previous year (and the last days of December to week 1 of the next).

The calendar day is read in UTC, so the result does not depend on the machine timezone.
Returns `null` if the input is invalid.

```typescript
import { isoWeek } from '@helpers4/date';

isoWeek(date: DateLike): object | null
```

**Parameters:**

- `date: DateLike` — The date to locate

**Returns:** `object | null` — The ISO week-numbering year and the week number (1–53), or `null`

**Examples:**

*Week number of a date*

Weeks start on Monday and week 1 contains the first Thursday of the year.

```typescript
isoWeek('2026-06-15')
// => { year: 2026, week: 25 }
```

*Year boundary*

The first days of January can belong to the last week of the previous year.

```typescript
isoWeek('2027-01-01')
// => { year: 2026, week: 53 }
```

*Invalid date*

Returns null instead of throwing.

```typescript
isoWeek('not a date')
// => null
```

---

### `isSameDay`

Checks if two dates are the same day.

Accepts any DateLike input (Date, timestamp, or date string).

```typescript
import { isSameDay } from '@helpers4/date';

isSameDay(date1: DateLike, date2: DateLike): boolean
```

**Parameters:**

- `date1: DateLike` — First date
- `date2: DateLike` — Second date

**Returns:** `boolean` — True if same day, false otherwise (including when either date is invalid)

**Examples:**

*Same day, different times*

Returns true when both dates are on the same calendar day.

```typescript
isSameDay(new Date('2025-01-19T08:00:00'), new Date('2025-01-19T22:00:00'))
// => true
```

---

### `isSameMonth`

Checks if two dates are in the same month (and year).

Accepts any DateLike input (Date, timestamp, or date string).

```typescript
import { isSameMonth } from '@helpers4/date';

isSameMonth(date1: DateLike, date2: DateLike): boolean
```

**Parameters:**

- `date1: DateLike` — First date
- `date2: DateLike` — Second date

**Returns:** `boolean` — True if same month and year, false otherwise (including when either date is invalid)

**Examples:**

*isSameMonth*

```typescript
```ts
isSameMonth('2025-01-01', '2025-01-31') // => true
isSameMonth('2025-01-31', '2025-02-01') // => false
```
```

---

### `isSameYear`

Checks if two dates are in the same year.

Accepts any DateLike input (Date, timestamp, or date string).

```typescript
import { isSameYear } from '@helpers4/date';

isSameYear(date1: DateLike, date2: DateLike): boolean
```

**Parameters:**

- `date1: DateLike` — First date
- `date2: DateLike` — Second date

**Returns:** `boolean` — True if same year, false otherwise (including when either date is invalid)

**Examples:**

*isSameYear*

```typescript
```ts
isSameYear('2025-01-01', '2025-12-31') // => true
isSameYear('2024-12-31', '2025-01-01') // => false
```
```

---

### `isTimestampInSeconds`

Checks if a timestamp is likely in seconds (Java/Unix style) vs milliseconds (JavaScript style)

```typescript
import { isTimestampInSeconds } from '@helpers4/date';

isTimestampInSeconds(timestamp: number): boolean
```

**Parameters:**

- `timestamp: number` — The timestamp to check

**Returns:** `boolean` — True if timestamp appears to be in seconds

**Examples:**

*Detect a Unix timestamp in seconds*

Returns true for timestamps that are likely in seconds (Java/Unix style).

```typescript
isTimestampInSeconds(1737290400)
// => true
```

*Normalize a Unix timestamp to milliseconds*

Converts a timestamp in seconds to JavaScript milliseconds.

```typescript
normalizeTimestamp(1737290400)
// => 1737290400000
```

---

### `isValid`

Checks if a value is a valid Date instance (not `Invalid Date`).

Unlike `isDate` (in `type/`), this also verifies that the internal timestamp
is not `NaN`.

```typescript
import { isValid } from '@helpers4/date';

isValid(value: unknown): value is Date
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is Date` — True if value is a Date instance with a valid time value

**Examples:**

*isValid*

```typescript
```ts
isValid(new Date())          // => true
isValid(new Date('invalid')) // => false
isValid('2023-01-01')        // => false (not a Date instance)
```
```

---

### `isValidDateString`

Checks whether a string can be parsed into a valid `Date`.

Uses the native `Date` constructor. Returns `false` for empty strings
and any string that produces an Invalid Date.

> **Caveat:** The native parser is lenient and implementation-dependent
> for non-ISO formats. For strict format validation, prefer a dedicated
> library or manual regex checks.

```typescript
import { isValidDateString } from '@helpers4/date';

isValidDateString(input: string): boolean
```

**Parameters:**

- `input: string` — The string to validate

**Returns:** `boolean` — `true` if `new Date(input)` produces a valid date

**Examples:**

*isValidDateString*

```typescript
```ts
isValidDateString('2025-01-19')            // => true
isValidDateString('2025-01-19T12:00:00Z')  // => true
isValidDateString('Jan 19, 2025')          // => true
isValidDateString('not a date')            // => false
isValidDateString('')                      // => false
```
```

---

### `isWeekend`

Checks whether a date falls on a weekend day.

By default, weekend days are **Saturday** and **Sunday** (Western
convention). Pass a custom `weekendDays` tuple to adapt to other
calendars (e.g. `[5, 6]` for Friday/Saturday in many Middle-Eastern
countries).

Returns `false` if the input is invalid.

```typescript
import { isWeekend } from '@helpers4/date';

isWeekend(date: DateLike, weekendDays: readonly WeekDay[]): boolean
```

**Parameters:**

- `date: DateLike` — The date to check
- `weekendDays: readonly WeekDay[]` (default: `DEFAULT_WEEKEND`) — Override which days count as weekend (default: `[0, 6]`)

**Returns:** `boolean` — `true` if the date's day-of-week is in `weekendDays`

**Examples:**

*isWeekend*

```typescript
```ts
isWeekend('2025-01-18') // => true  (Saturday)
isWeekend('2025-01-19') // => true  (Sunday)
isWeekend('2025-01-20') // => false (Monday)

// Middle-Eastern weekend (Friday + Saturday)
isWeekend('2025-01-17', [WeekDays.Friday, WeekDays.Saturday]) // => true
isWeekend('2025-01-19', [WeekDays.Friday, WeekDays.Saturday]) // => false
```
```

---

### `isWithinRange`

Checks whether a date falls within a range (inclusive on both ends).

Returns `false` if any of the inputs is invalid.

```typescript
import { isWithinRange } from '@helpers4/date';

isWithinRange(date: DateLike, start: DateLike, end: DateLike): boolean
```

**Parameters:**

- `date: DateLike` — The date to check
- `start: DateLike` — Start of the range (inclusive)
- `end: DateLike` — End of the range (inclusive)

**Returns:** `boolean` — `true` if `start <= date <= end`

**Examples:**

*isWithinRange*

```typescript
```ts
isWithinRange('2025-06-15', '2025-01-01', '2025-12-31') // => true
isWithinRange('2024-06-15', '2025-01-01', '2025-12-31') // => false
```
```

---

### `listTimezones`

Returns the list of IANA timezone identifiers supported by the runtime.

Wraps `Intl.supportedValuesOf('timeZone')` which is available in
Node 18+, Chrome 93+, Firefox 93+, Safari 15.4+.

```typescript
import { listTimezones } from '@helpers4/date';

listTimezones(): string[]
```

**Returns:** `string[]` — An array of IANA timezone strings (e.g. `['Africa/Abidjan', …, 'US/Pacific']`)

**Examples:**

*listTimezones*

```typescript
```ts
listTimezones() // => ['Africa/Abidjan', 'Africa/Accra', …]
```
```

---

### `normalizeTimestamp`

Converts a timestamp to JavaScript milliseconds format

```typescript
import { normalizeTimestamp } from '@helpers4/date';

normalizeTimestamp(timestamp: number): number
```

**Parameters:**

- `timestamp: number` — The timestamp (in seconds or milliseconds)

**Returns:** `number` — Timestamp in milliseconds

---

### `overlaps`

Checks whether two date ranges overlap.

Two ranges overlap when `rangeA.start <= rangeB.end` AND
`rangeB.start <= rangeA.end` (inclusive on both ends).
Returns `false` if any date is invalid.

```typescript
import { overlaps } from '@helpers4/date';

overlaps(rangeA: DateRange, rangeB: DateRange): boolean
```

**Parameters:**

- `rangeA: DateRange` — First date range
- `rangeB: DateRange` — Second date range

**Returns:** `boolean` — `true` if the ranges share at least one point in time

**Examples:**

*overlaps*

```typescript
```ts
overlaps(
  { start: '2025-01-01', end: '2025-06-30' },
  { start: '2025-03-01', end: '2025-12-31' }
) // => true

overlaps(
  { start: '2025-01-01', end: '2025-02-28' },
  { start: '2025-03-01', end: '2025-12-31' }
) // => false
```
```

---

### `parseDuration`

Parses a compact duration string (as produced by formatDuration,
e.g. `"1h 23m 45s"`) back into milliseconds.

Accepts any combination/order of `h`/`m`/`s` segments, with or without
spaces between them (`"1h30m"` and `"1h 30m"` both work). A single leading
`-` negates the whole duration, matching `formatDuration`'s output.
Returns `null` when no valid segment is found.

```typescript
import { parseDuration } from '@helpers4/date';

parseDuration(str: string): number | null
```

**Parameters:**

- `str: string` — The duration string to parse

**Returns:** `number | null` — The duration in milliseconds, or `null` if unparseable

**Examples:**

*Parse a compact duration string into milliseconds*

The inverse of formatDuration() — accepts the same "1h 23m 45s" style output.

```typescript
parseDuration('1h 23m 45s')
// => 5025000
```

*Returns null for an unparseable string*

Lets you branch on parse failure instead of silently getting 0 or NaN.

```typescript
parseDuration('not a duration')
// => null
```

---

### `parsePartial`

Parses an ISO date that may only be known to the year or the month: `YYYY`, `YYYY-MM` or
`YYYY-MM-DD`. A partial date is anchored in the middle of its period, so it sorts and
charts sensibly next to full dates:

- `YYYY` → July 1st of that year
- `YYYY-MM` → the 15th of that month
- `YYYY-MM-DD` → that day

All dates are at 00:00:00.000 UTC. Returns `null` for anything else, including a month or day
that does not exist (`2025-13`, `2025-02-30`).

```typescript
import { parsePartial } from '@helpers4/date';

parsePartial(input: string): PartialDate | null
```

**Parameters:**

- `input: string` — A `YYYY`, `YYYY-MM` or `YYYY-MM-DD` string

**Returns:** `PartialDate | null` — The anchored date with its precision, or `null`

**Examples:**

*Year and month only*

A partial date is anchored in the middle of its period so it sorts next to full dates.

```typescript
parsePartial('2008')    // => { date: 2008-07-01, precision: 'year' }
parsePartial('2008-03') // => { date: 2008-03-15, precision: 'month' }
```

*Invalid input*

A month or day that does not exist gives null.

```typescript
parsePartial('2008-02-30') // => null
```

---

### `startOf`

Returns a new `Date` set to the **start** of the given unit.

- `'day'`   — 00:00:00.000
- `'month'` — 1st of the month, 00:00:00.000
- `'year'`  — January 1st, 00:00:00.000

Returns `null` if the input is invalid.

```typescript
import { startOf } from '@helpers4/date';

startOf(date: DateLike, unit: DateTruncUnit): Date | null
```

**Parameters:**

- `date: DateLike` — The base date
- `unit: DateTruncUnit` — The unit to truncate to

**Returns:** `Date | null` — A new Date at the start of the unit, or `null`

**Examples:**

*startOf*

```typescript
```ts
startOf('2025-06-15T14:30:00Z', 'day')    // => 2025-06-15T00:00:00.000Z
startOf('2025-06-15T14:30:00Z', 'month')  // => 2025-06-01T00:00:00.000Z
startOf('2025-06-15T14:30:00Z', 'year')   // => 2025-01-01T00:00:00.000Z
```
```

---

### `timeAgo`

Formats a date as a human-readable relative time string.

Uses `Intl.RelativeTimeFormat` under the hood, making the output
locale-aware (e.g. "il y a 3 jours" in French).

Returns `null` if the input date is invalid.

```typescript
import { timeAgo } from '@helpers4/date';

timeAgo(date: DateLike, options: TimeAgoOptions): string | null
```

**Parameters:**

- `date: DateLike` — The date to describe relative to `now`
- `options: TimeAgoOptions` (default: `{}`) — Optional configuration (reference date, locale, numeric style)

**Returns:** `string | null` — A locale-aware relative time string, or `null`

**Examples:**

*timeAgo*

```typescript
```ts
timeAgo('2025-01-17T00:00:00Z', { now: '2025-01-19T00:00:00Z' })
// => "2 days ago"

timeAgo('2025-01-20T00:00:00Z', { now: '2025-01-19T00:00:00Z' })
// => "in 1 day"  (or "tomorrow" with numeric: 'auto')

timeAgo('2025-01-19T00:00:00Z', { now: '2025-01-19T00:00:05Z' })
// => "5 seconds ago"
```
```

---

### `toISO8601`

Converts a date to ISO 8601 format
Format: YYYY-MM-DDTHH:mm:ss.sssZ

```typescript
import { toISO8601 } from '@helpers4/date';

toISO8601(date: DateLike): string | null
```

**Parameters:**

- `date: DateLike` — Date to convert (Date object, timestamp, or date string)

**Returns:** `string | null` — ISO 8601 formatted string or null if invalid date

**Examples:**

*Convert to ISO 8601*

Formats a date as an ISO 8601 string.

```typescript
toISO8601(new Date('2025-01-19T12:30:00Z'))
// => '2025-01-19T12:30:00.000Z'
```

*Convert to RFC 3339 (no ms)*

RFC 3339 format strips milliseconds by default.

```typescript
toRFC3339(new Date('2025-01-19T12:30:45.123Z'))
// => '2025-01-19T12:30:45Z'
```

*Convert to RFC 2822*

RFC 2822 is used in email and HTTP headers.

```typescript
toRFC2822(new Date('2025-01-19T12:30:00Z'))
// => 'Sun, 19 Jan 2025 12:30:00 +0000'
```

*Stable short label*

UTC and English by default, so the label is the same on every machine.

```typescript
format('2026-07-27')
// => 'Jul 27, 2026'
```

*Custom fields and locale*

The options replace the default format; the locale is the third argument.

```typescript
format('2026-07-27', { month: 'short', day: 'numeric' })
// => 'Jul 27'
format('2026-07-27', undefined, 'fr')
// => '27 juil. 2026'
```

---

### `toMillis`

Converts a date to a timestamp in **milliseconds** (epoch millis).

Use this when you need a plain number from a `DateLike` value
(e.g. for `Date.now()` comparisons, localStorage, or JS-native APIs).

```typescript
import { toMillis } from '@helpers4/date';

toMillis(date: DateLike): number | null
```

**Parameters:**

- `date: DateLike` — The date to convert

**Returns:** `number | null` — Milliseconds since the Unix epoch, or `null` for invalid input

**Examples:**

*toMillis*

```typescript
```ts
toMillis('2025-01-19T12:00:00Z') // => 1737288000000
toMillis(null)                    // => null
```
```

---

### `toRFC2822`

Converts a date to RFC 2822 format
Format: Day, DD Mon YYYY HH:mm:ss +0000
Used in email headers (Date field) and HTTP headers

```typescript
import { toRFC2822 } from '@helpers4/date';

toRFC2822(date: DateLike): string | null
```

**Parameters:**

- `date: DateLike` — Date to convert (Date object, timestamp, or date string)

**Returns:** `string | null` — RFC 2822 formatted string or null if invalid date

**Examples:**

*toRFC2822*

```typescript
```ts
toRFC2822(new Date('2025-01-19T12:30:00Z')) // 'Sun, 19 Jan 2025 12:30:00 +0000'
```
```

---

### `toRFC3339`

Converts a date to RFC 3339 format
Format: YYYY-MM-DDTHH:mm:ssZ or YYYY-MM-DDTHH:mm:ss+HH:mm
RFC 3339 is a profile of ISO 8601, but without milliseconds by default

```typescript
import { toRFC3339 } from '@helpers4/date';

toRFC3339(date: DateLike, includeMilliseconds: boolean): string | null
```

**Parameters:**

- `date: DateLike` — Date to convert (Date object, timestamp, or date string)
- `includeMilliseconds: boolean` (default: `false`) — Whether to include milliseconds (default: false)

**Returns:** `string | null` — RFC 3339 formatted string or null if invalid date

**Examples:**

*toRFC3339*

```typescript
```ts
toRFC3339(new Date('2025-01-19T12:30:45.123Z')) // '2025-01-19T12:30:45Z'
toRFC3339(new Date('2025-01-19T12:30:45.123Z'), true) // '2025-01-19T12:30:45.123Z'
```
```

---

### `toSeconds`

Converts a date to a timestamp in **seconds** (epoch seconds).

Use this when sending a date to a backend API that expects seconds
(e.g. Java `Instant.getEpochSecond()`, Python `time.time()`).

```typescript
import { toSeconds } from '@helpers4/date';

toSeconds(date: DateLike): number | null
```

**Parameters:**

- `date: DateLike` — The date to convert

**Returns:** `number | null` — Seconds since the Unix epoch, or `null` for invalid input

**Examples:**

*toSeconds*

```typescript
```ts
toSeconds('2025-01-19T12:00:00Z') // => 1737288000
toSeconds(null)                    // => null
```
```

---

### `WeekDays`

Named day-of-week constants following the JavaScript `Date.getDay()`
convention. Use these instead of raw numbers for readability.

**Examples:**

*WeekDays*

```typescript
```ts
import { WeekDays } from '@helpers4/date';

isWeekend('2025-01-17', [WeekDays.Friday, WeekDays.Saturday])
```
```

---

## fetch

Package: `@helpers4/fetch`

### `fetchJson`

Fetches a URL and returns its parsed JSON body, retrying transient failures.

Retried: network errors, `5xx` and `429` responses. Not retried, and thrown at once: other
`4xx` responses, a body that is not valid JSON (a `SyntaxError`) and an aborted request.
After the last attempt, the last error is thrown: an HttpError (with `status` and
`url`) for a bad status, or whatever `fetch` rejected with.

Pass a URL or a string: a `Request` with a body cannot be sent twice, so it can't be retried.

`init.signal` cancels the whole call: the running request, and the wait before the next one.

```typescript
import { fetchJson } from '@helpers4/fetch';

fetchJson<T>(input: RequestInfo | URL, init?: RequestInit, options: FetchJsonOptions): Promise<T>
```

**Parameters:**

- `input: RequestInfo | URL` — URL or `Request` object passed to `fetch`
- `init?: RequestInit` — Optional `RequestInit` options passed to `fetch`
- `options: FetchJsonOptions` (default: `{}`) — Retry configuration — see FetchJsonOptions

**Returns:** `Promise<T>` — The parsed JSON body

**Examples:**

*Fetch JSON, retrying transient failures*

A 503 is retried; once the server answers, the parsed body is returned.

```typescript
// the server answers 503, then 200 with { "stars": 42 }
await fetchJson<{ stars: number }>('https://api.example.com/repo', undefined, { retry: { delayMs: 0 } })
// => { stars: 42 }
```

*A 404 is not retried*

Client errors fail at once with an HttpError carrying the status.

```typescript
await fetchJson('https://api.example.com/missing')
// throws HttpError { status: 404 } after a single request
```

---

### `fetchOrThrow`

Wraps `fetch` so that a non-2xx response rejects with an HttpError, instead of
resolving like any other response — the throwing counterpart to `safeFetch`, for when a
failed request should fail loud. Network errors reject as `fetch` itself rejects them.

```typescript
import { fetchOrThrow } from '@helpers4/fetch';

fetchOrThrow(input: RequestInfo | URL, init?: RequestInit): Promise<Response>
```

**Parameters:**

- `input: RequestInfo | URL` — URL or `Request` object passed to `fetch`
- `init?: RequestInit` — Optional `RequestInit` options passed to `fetch`

**Returns:** `Promise<Response>` — The response, body unread, when its status is 2xx

**Examples:**

*Fail loud on a non-2xx response*

Resolves with the response on success, rejects with an HttpError otherwise.

```typescript
const response = await fetchOrThrow('https://api.example.com/repo');
const repo = await response.json();
```

*Handle a specific status*

HttpError carries the status, the URL and the response, so a caller can branch on it.

```typescript
try {
  await fetchOrThrow('https://api.example.com/missing');
} catch (error) {
  if (error instanceof HttpError && error.status === 404) {
    // error.message => 'HTTP 404 Not Found: https://api.example.com/missing'
  }
}
```

---

### `safeFetch`

Wraps `fetch` with built-in error handling: returns `null` when the
request fails (network error, non-OK status, or parse error) instead
of throwing.

```typescript
import { safeFetch } from '@helpers4/fetch';

safeFetch<T>(input: RequestInfo | URL, init?: RequestInit, options: SafeFetchOptions): Promise<T | null>
```

**Parameters:**

- `input: RequestInfo | URL` — URL or `Request` object passed to `fetch`
- `init?: RequestInit` — Optional `RequestInit` options passed to `fetch`
- `options: SafeFetchOptions` (default: `{}`) — Parsing options (default: `{ parse: 'json' }`)

**Returns:** `Promise<T | null>` — The parsed response body, or `null` on any failure

**Examples:**

*Fetch JSON safely*

Returns `null` on network error or non-OK status instead of throwing.

```typescript
const repo = await safeFetch<{ stars: number }>(
  'https://api.github.com/repos/helpers4/typescript'
);
if (repo === null) {
  console.warn('Failed to fetch repo data');
} else {
  console.log(repo.stars);
}
```

*Fetch plain text*

Pass { parse: "text" } to get the raw response body as a string.

```typescript
const content = await safeFetch<string>(
  'https://example.com/data.txt',
  undefined,
  { parse: 'text' }
);
```

---

## font

Package: `@helpers4/font`

### `pickClosest`

Picks the face that CSS would use for a request, among the faces of one family: the CSS Fonts
Level 4 matching algorithm (§5.2), as a pure function. The stretch is matched first, then the
style, then the weight; each step keeps only the faces closest to what was asked.

- Stretch: at or below 100, narrower faces first (nearest), then wider ones; above 100, the other way round.
- Style: `normal` prefers normal, then oblique, then italic; `italic` prefers italic, then oblique, then
  normal; `oblique` prefers oblique, then italic, then normal.
- Weight: from 400 to 500, the nearest heavier weight up to 500, then lighter ones, then heavier ones
  above 500; below 400, lighter first then heavier; above 500, heavier first then lighter.

```typescript
import { pickClosest } from '@helpers4/font';

pickClosest<T extends FontFaceDescriptor>(faces: readonly T[], wanted: FontFaceDescriptor): T | undefined
```

**Parameters:**

- `faces: readonly T[]` — The faces of one family, for instance the entries of a font catalogue
- `wanted: FontFaceDescriptor` (default: `{}`) — What was asked; each missing property is its CSS initial value

**Returns:** `T | undefined` — The closest face, the first one when several are equally close, or `undefined` for no face

**Examples:**

*Pick the face for a weight that is not available*

Above 500, CSS goes to the next heavier face before any lighter one.

```typescript
const faces = [{ weight: 300 }, { weight: 400 }, { weight: 700 }];
pickClosest(faces, { weight: 600 })
// => { weight: 700 }
```

*Ask for an italic, with a fallback*

Without an italic face, oblique is tried, then normal, as in a browser.

```typescript
pickClosest([{ weight: 400 }, { weight: 400, style: 'oblique' }], { style: 'italic' })
// => { weight: 400, style: 'oblique' }
```

---

## function

Package: `@helpers4/function`

### `compose`

Composes functions right-to-left: `compose(f, g)(x)` is equivalent to `f(g(x))`.

The inverse of pipe, which applies functions left-to-right.

```typescript
import { compose } from '@helpers4/function';

compose<A, B>(fn1: function): function
```

**Parameters:**

- `fn1: function` — The first function. The overloads accept up to eight functions in all, passed as `fn1, fn2, …`.

**Returns:** `function` — A function that applies `fns` in reverse order

```typescript
import { compose } from '@helpers4/function';

compose<A, B, C>(fn2: function, fn1: function): function
```

**Parameters:**

- `fn2: function`
- `fn1: function` — The first function. The overloads accept up to eight functions in all, passed as `fn1, fn2, …`.

**Returns:** `function` — A function that applies `fns` in reverse order

```typescript
import { compose } from '@helpers4/function';

compose<A, B, C, D>(fn3: function, fn2: function, fn1: function): function
```

**Parameters:**

- `fn3: function`
- `fn2: function`
- `fn1: function` — The first function. The overloads accept up to eight functions in all, passed as `fn1, fn2, …`.

**Returns:** `function` — A function that applies `fns` in reverse order

```typescript
import { compose } from '@helpers4/function';

compose<A, B, C, D, E>(fn4: function, fn3: function, fn2: function, fn1: function): function
```

**Parameters:**

- `fn4: function`
- `fn3: function`
- `fn2: function`
- `fn1: function` — The first function. The overloads accept up to eight functions in all, passed as `fn1, fn2, …`.

**Returns:** `function` — A function that applies `fns` in reverse order

```typescript
import { compose } from '@helpers4/function';

compose<A, B, C, D, E, F>(fn5: function, fn4: function, fn3: function, fn2: function, fn1: function): function
```

**Parameters:**

- `fn5: function`
- `fn4: function`
- `fn3: function`
- `fn2: function`
- `fn1: function` — The first function. The overloads accept up to eight functions in all, passed as `fn1, fn2, …`.

**Returns:** `function` — A function that applies `fns` in reverse order

```typescript
import { compose } from '@helpers4/function';

compose<A, B, C, D, E, F, G>(fn6: function, fn5: function, fn4: function, fn3: function, fn2: function, fn1: function): function
```

**Parameters:**

- `fn6: function`
- `fn5: function`
- `fn4: function`
- `fn3: function`
- `fn2: function`
- `fn1: function` — The first function. The overloads accept up to eight functions in all, passed as `fn1, fn2, …`.

**Returns:** `function` — A function that applies `fns` in reverse order

```typescript
import { compose } from '@helpers4/function';

compose<A, B, C, D, E, F, G, H>(fn7: function, fn6: function, fn5: function, fn4: function, fn3: function, fn2: function, fn1: function): function
```

**Parameters:**

- `fn7: function`
- `fn6: function`
- `fn5: function`
- `fn4: function`
- `fn3: function`
- `fn2: function`
- `fn1: function` — The first function. The overloads accept up to eight functions in all, passed as `fn1, fn2, …`.

**Returns:** `function` — A function that applies `fns` in reverse order

```typescript
import { compose } from '@helpers4/function';

compose<A, B, C, D, E, F, G, H, I>(fn8: function, fn7: function, fn6: function, fn5: function, fn4: function, fn3: function, fn2: function, fn1: function): function
```

**Parameters:**

- `fn8: function`
- `fn7: function`
- `fn6: function`
- `fn5: function`
- `fn4: function`
- `fn3: function`
- `fn2: function`
- `fn1: function` — The first function. The overloads accept up to eight functions in all, passed as `fn1, fn2, …`.

**Returns:** `function` — A function that applies `fns` in reverse order

**Examples:**

*Compose functions right-to-left*

`compose(f, g)(x)` is equivalent to `f(g(x))`. The rightmost function is applied first.

```typescript
const process = compose(
  String,
  (x: number) => x * 2,
  (x: number) => x + 1
);
process(3); // => "8"
```

*Build a validator from small predicates*

Compose small predicate functions into a single validator.

```typescript
const validate = compose(
  (ok: boolean) => ok || (() => { throw new Error('invalid'); })(),
  (s: string) => s.length >= 3
);
validate('ab');  // throws
validate('abc'); // => true
```

---

### `createCachedResolver`

Creates a lazy, cached resolver: `resolve(key)` computes and caches
`compute(key)` the first time a given key is seen, and returns the cached
value on every later call for that same key — until `clear()` wipes the
whole cache.

Backed by a `Map` by default (works with any key type). Pass a factory
that returns a `WeakMap` instead when keys (objects, functions, or
symbols — see isWeakMapKey) should be allowed to be
garbage-collected once nothing else references them anymore — the whole
point of `WeakMap` over `Map`.

A *factory function* is accepted (not a cache instance) so `clear()` can
reliably produce a fresh, empty cache regardless of its kind: `WeakMap`
deliberately has no `.clear()` method (no way to enumerate its entries, by
design), so the only way to empty one is to replace it outright — the same
factory used to create the initial cache is called again to do that.

```typescript
import { createCachedResolver } from '@helpers4/function';

createCachedResolver<K extends WeakKey, V>(compute: function, createCache: function): CachedResolver<K, V>
```

**Parameters:**

- `compute: function` — Computes the value for a key not yet in the cache.
- `createCache: function` — Produces a fresh, empty cache. Defaults to `() => new Map()`.
Its *initial* call must return an instance not already claimed by another
`createCachedResolver()` call sharing the same factory — otherwise the two
would silently share cache state, so this throws instead.

**Returns:** `CachedResolver<K, V>` — A CachedResolver.

```typescript
import { createCachedResolver } from '@helpers4/function';

createCachedResolver<K, V>(compute: function, createCache?: function): CachedResolver<K, V>
```

**Parameters:**

- `compute: function` — Computes the value for a key not yet in the cache.
- `createCache?: function` — Produces a fresh, empty cache. Defaults to `() => new Map()`.
Its *initial* call must return an instance not already claimed by another
`createCachedResolver()` call sharing the same factory — otherwise the two
would silently share cache state, so this throws instead.

**Returns:** `CachedResolver<K, V>` — A CachedResolver.

**Examples:**

*Compute once, reuse on every later call for the same key*

compute() only runs on a cache miss — a repeated call for the same key returns the cached value.

```typescript
let calls = 0;
const { resolve } = createCachedResolver((id: number) => {
  calls++;
  return id * 2;
});
resolve(1); // calls compute, calls === 1
resolve(1); // cache hit, calls still === 1
```

*clear() wipes the cache — the next resolve() recomputes*

Useful for a "refresh" action that must pick up changes since the cache was last filled.

```typescript
let calls = 0;
const { resolve, clear } = createCachedResolver((id: number) => { calls++; return id; });
resolve(1);
clear();
resolve(1); // recomputed, calls === 2
```

*WeakMap-backed cache for object keys*

Pass a factory returning a WeakMap so entries can be garbage-collected once the key object is no longer referenced elsewhere.

```typescript
const resolver = createCachedResolver(
  (config: object) => deriveExpensiveSettings(config),
  () => new WeakMap(),
);
```

---

### `curry`

Transforms a multi-argument function into a chain of single-argument functions
(Haskell-style currying). Supports up to 5 arguments.

The inverse operation of applying all arguments at once:
`curry(fn)(a)(b)` is equivalent to `fn(a, b)`.

```typescript
import { curry } from '@helpers4/function';

curry<A, R>(fn: function): function
```

**Parameters:**

- `fn: function` — The function to curry

**Returns:** `function` — A curried version of `fn`

```typescript
import { curry } from '@helpers4/function';

curry<A, B, R>(fn: function): function
```

**Parameters:**

- `fn: function` — The function to curry

**Returns:** `function` — A curried version of `fn`

```typescript
import { curry } from '@helpers4/function';

curry<A, B, C, R>(fn: function): function
```

**Parameters:**

- `fn: function` — The function to curry

**Returns:** `function` — A curried version of `fn`

```typescript
import { curry } from '@helpers4/function';

curry<A, B, C, D, R>(fn: function): function
```

**Parameters:**

- `fn: function` — The function to curry

**Returns:** `function` — A curried version of `fn`

```typescript
import { curry } from '@helpers4/function';

curry<A, B, C, D, E, R>(fn: function): function
```

**Parameters:**

- `fn: function` — The function to curry

**Returns:** `function` — A curried version of `fn`

**Examples:**

*Create reusable adder*

Curry a 2-argument function to build specialised versions.

```typescript
const add = curry((a: number, b: number) => a + b);
const add5 = add(5);

add5(3);  // => 8
add5(10); // => 15
```

*Pipeline-friendly 3-argument function*

Curry enables point-free style when composing pipelines.

```typescript
const clamp = curry((min: number, max: number, v: number) =>
  Math.min(Math.max(v, min), max)
);
const clamp0to100 = clamp(0)(100);

clamp0to100(42);  // => 42
clamp0to100(-5);  // => 0
clamp0to100(150); // => 100
```

---

### `debounce`

Creates a debounced function that delays invoking func until after delay milliseconds have elapsed since the last time the debounced function was invoked

Call `cancel()`, or abort the `signal`, on teardown: otherwise the pending call still runs
after its owner is gone.

```typescript
import { debounce } from '@helpers4/function';

debounce<A extends unknown[], R>(func: function, delay: number, options: DebounceOptions): Debounced<A>
```

**Parameters:**

- `func: function` — The function to debounce
- `delay: number` — The number of milliseconds to delay
- `options: DebounceOptions` (default: `{}`) — Cancellation — see DebounceOptions

**Returns:** `Debounced<A>` — The debounced function, with a `cancel()` method

**Examples:**

*Debounce a function*

The debounced function is only called once after the delay, even if invoked multiple times.

```typescript
const fn = debounce((x: number) => console.log(x), 100);
fn(1);
fn(2);
fn(3);
// Only logs 3 after 100ms
```

*Cancel on teardown*

An aborted signal, or cancel(), drops the call still waiting, so it never runs after its owner is gone.

```typescript
const controller = new AbortController();
const fn = debounce(() => console.log('late'), 100, { signal: controller.signal });
fn();
fn();
controller.abort();
// nothing is logged after the abort
```

---

### `flip`

Creates a function that invokes `fn` with the first two arguments swapped.

Useful when adapting a function for use in higher-order pipelines where the
argument order is reversed (e.g. passing a binary callback to `reduce`).

```typescript
import { flip } from '@helpers4/function';

flip<A, B, Rest extends unknown[], R>(fn: function): function
```

**Parameters:**

- `fn: function` — The function to wrap.

**Returns:** `function` — A new function with the first two parameters swapped.

**Examples:**

*Swap argument order*

Returns a new function where the first two arguments are swapped.

```typescript
const sub = (a: number, b: number) => a - b;
flip(sub)(3, 10); // => 7  (10 - 3)
```

*Adapt a divide function*

Useful for adapting binary callbacks in higher-order functions.

```typescript
const divide = (a: number, b: number) => a / b;
const divideInto = flip(divide);
divideInto(2, 100); // => 50
```

---

### `identity`

Returns the given value unchanged

Useful as a default transform, in function composition, or as a placeholder mapper.

```typescript
import { identity } from '@helpers4/function';

identity<T>(value: T): T
```

**Parameters:**

- `value: T` — The value to return

**Returns:** `T` — The same value

**Examples:**

*Return a primitive unchanged*

The value is returned as-is with its type preserved.

```typescript
identity(42);       // 42
identity('hello');  // 'hello'
identity(true);     // true
```

*Use as a default mapper*

Pass identity where a transform function is required but no transformation is needed.

```typescript
[1, 2, 3].map(identity); // [1, 2, 3]
```

---

### `memoize`

Returns a memoized version of the function that caches results.

Cache keys are derived via `JSON.stringify`; `undefined` arguments are
correctly distinguished from `null`. Arguments that are not JSON-serializable
(functions, symbols, class instances, circular references) produce a
`null`-equivalent key and are not supported.

```typescript
import { memoize } from '@helpers4/function';

memoize<A extends unknown[], R>(func: function, options?: MemoizeOptions): function
```

**Parameters:**

- `func: function` — The function to memoize
- `options?: MemoizeOptions` — Optional settings (e.g. `maxSize` to cap memory usage)

**Returns:** `function` — The memoized function

**Examples:**

*Cache function results*

The underlying function is only called once for the same arguments.

```typescript
let calls = 0;
const expensive = memoize((n: number) => { calls++; return n * 2; });
expensive(5); // => 10 (computed)
expensive(5); // => 10 (cached)
```

---

### `negate`

Creates a function that negates the result of `predicate`.

```typescript
import { negate } from '@helpers4/function';

negate<T extends unknown[]>(predicate: function): function
```

**Parameters:**

- `predicate: function` — A predicate function returning a boolean.

**Returns:** `function` — A new function that returns the logical negation of `predicate`.

**Examples:**

*Derive isOdd from isEven*

Returns a function that inverts the boolean result of the given predicate.

```typescript
const isEven = (n: number) => n % 2 === 0;
const isOdd = negate(isEven);
isOdd(3); // => true
isOdd(4); // => false
```

*Use as a filter predicate*

negate is ideal for inverting predicates passed to Array.filter.

```typescript
const isEmpty = (arr: unknown[]) => arr.length === 0;
[[], [1], [], [2, 3]].filter(negate(isEmpty))
// => [[1], [2, 3]]
```

---

### `noop`

A no-operation function that does nothing and returns `undefined`

Useful as a default callback, placeholder, or to explicitly ignore a value.

```typescript
import { noop } from '@helpers4/function';

noop(): void
```

**Returns:** `void` — Nothing (`undefined`)

**Examples:**

*Use as a default callback*

Replace an optional callback with noop to avoid null checks.

```typescript
const onComplete = options.callback ?? noop;
onComplete(); // does nothing
```

*Silence an event handler*

Pass noop wherever a function is required but no action is needed.

```typescript
element.addEventListener('click', noop);
```

---

### `once`

Creates a function that is restricted to be called only once.
Subsequent calls return the cached result of the first invocation.

The returned function exposes a `.reset()` method to clear the cache and
allow the original function to be called again.

```typescript
import { once } from '@helpers4/function';

once<A extends unknown[], R>(fn: function): OnceFn<A, R>
```

**Parameters:**

- `fn: function` — The function to wrap

**Returns:** `OnceFn<A, R>` — A function that invokes `fn` at most once, with a `.reset()` method

**Examples:**

*Run expensive setup only once*

The wrapped function executes only on the first call; all subsequent calls return the cached result.

```typescript
const init = once(() => ({ config: 'loaded' }));

const a = init(); // runs the function
const b = init(); // returns cached result
a === b; // => true

init.reset(); // clear cache
const c = init(); // runs the function again
a === c; // => false (new object)
```

*Guard against multiple event-listener registrations*

Ensure a side-effecting setup (e.g. addEventListener) runs at most once.

```typescript
const register = once((el: HTMLElement) => {
  el.addEventListener('click', handler);
});

register(button); // registers handler
register(button); // no-op — handler already registered
```

---

### `partial`

Partially applies arguments to a function, returning a new function that
accepts the remaining arguments.

```typescript
import { partial } from '@helpers4/function';

partial<A, R>(fn: function, a: A): function
```

**Parameters:**

- `fn: function` — The function to partially apply
- `a: A` — The first argument to pre-fill. The overloads accept up to three pre-filled arguments (`a`, `b`, `c`).

**Returns:** `function` — A function waiting for the remaining arguments

```typescript
import { partial } from '@helpers4/function';

partial<A, B, R>(fn: function, a: A): function
```

**Parameters:**

- `fn: function` — The function to partially apply
- `a: A` — The first argument to pre-fill. The overloads accept up to three pre-filled arguments (`a`, `b`, `c`).

**Returns:** `function` — A function waiting for the remaining arguments

```typescript
import { partial } from '@helpers4/function';

partial<A, B, C, R>(fn: function, a: A): function
```

**Parameters:**

- `fn: function` — The function to partially apply
- `a: A` — The first argument to pre-fill. The overloads accept up to three pre-filled arguments (`a`, `b`, `c`).

**Returns:** `function` — A function waiting for the remaining arguments

```typescript
import { partial } from '@helpers4/function';

partial<A, B, C, R>(fn: function, a: A, b: B): function
```

**Parameters:**

- `fn: function` — The function to partially apply
- `a: A` — The first argument to pre-fill. The overloads accept up to three pre-filled arguments (`a`, `b`, `c`).
- `b: B`

**Returns:** `function` — A function waiting for the remaining arguments

```typescript
import { partial } from '@helpers4/function';

partial<A, B, C, D, R>(fn: function, a: A): function
```

**Parameters:**

- `fn: function` — The function to partially apply
- `a: A` — The first argument to pre-fill. The overloads accept up to three pre-filled arguments (`a`, `b`, `c`).

**Returns:** `function` — A function waiting for the remaining arguments

```typescript
import { partial } from '@helpers4/function';

partial<A, B, C, D, R>(fn: function, a: A, b: B): function
```

**Parameters:**

- `fn: function` — The function to partially apply
- `a: A` — The first argument to pre-fill. The overloads accept up to three pre-filled arguments (`a`, `b`, `c`).
- `b: B`

**Returns:** `function` — A function waiting for the remaining arguments

```typescript
import { partial } from '@helpers4/function';

partial<A, B, C, D, R>(fn: function, a: A, b: B, c: C): function
```

**Parameters:**

- `fn: function` — The function to partially apply
- `a: A` — The first argument to pre-fill. The overloads accept up to three pre-filled arguments (`a`, `b`, `c`).
- `b: B`
- `c: C`

**Returns:** `function` — A function waiting for the remaining arguments

**Examples:**

*Create a specialised multiplier*

Pre-fill the first argument to derive a specialised function.

```typescript
const multiply = (a: number, b: number) => a * b;
const double = partial(multiply, 2);
const triple = partial(multiply, 3);

double(5); // => 10
triple(5); // => 15
```

*Pre-fill multiple arguments*

Supply several arguments up front, leaving only the last one open.

```typescript
const format = (prefix: string, sep: string, value: string) =>
  `${prefix}${sep}${value}`;

const withLabel = partial(format, 'Status', ': ');
withLabel('passing'); // => 'Status: passing'
```

---

### `pipe`

Composes functions left-to-right: the output of each function is passed as
input to the next.

The inverse of compose, which applies functions right-to-left.

```typescript
import { pipe } from '@helpers4/function';

pipe<A, B>(fn1: function): function
```

**Parameters:**

- `fn1: function` — The first function. The overloads accept up to eight functions in all, passed as `fn1, fn2, …`.

**Returns:** `function` — A function that applies `fns` in order

```typescript
import { pipe } from '@helpers4/function';

pipe<A, B, C>(fn1: function, fn2: function): function
```

**Parameters:**

- `fn1: function` — The first function. The overloads accept up to eight functions in all, passed as `fn1, fn2, …`.
- `fn2: function`

**Returns:** `function` — A function that applies `fns` in order

```typescript
import { pipe } from '@helpers4/function';

pipe<A, B, C, D>(fn1: function, fn2: function, fn3: function): function
```

**Parameters:**

- `fn1: function` — The first function. The overloads accept up to eight functions in all, passed as `fn1, fn2, …`.
- `fn2: function`
- `fn3: function`

**Returns:** `function` — A function that applies `fns` in order

```typescript
import { pipe } from '@helpers4/function';

pipe<A, B, C, D, E>(fn1: function, fn2: function, fn3: function, fn4: function): function
```

**Parameters:**

- `fn1: function` — The first function. The overloads accept up to eight functions in all, passed as `fn1, fn2, …`.
- `fn2: function`
- `fn3: function`
- `fn4: function`

**Returns:** `function` — A function that applies `fns` in order

```typescript
import { pipe } from '@helpers4/function';

pipe<A, B, C, D, E, F>(fn1: function, fn2: function, fn3: function, fn4: function, fn5: function): function
```

**Parameters:**

- `fn1: function` — The first function. The overloads accept up to eight functions in all, passed as `fn1, fn2, …`.
- `fn2: function`
- `fn3: function`
- `fn4: function`
- `fn5: function`

**Returns:** `function` — A function that applies `fns` in order

```typescript
import { pipe } from '@helpers4/function';

pipe<A, B, C, D, E, F, G>(fn1: function, fn2: function, fn3: function, fn4: function, fn5: function, fn6: function): function
```

**Parameters:**

- `fn1: function` — The first function. The overloads accept up to eight functions in all, passed as `fn1, fn2, …`.
- `fn2: function`
- `fn3: function`
- `fn4: function`
- `fn5: function`
- `fn6: function`

**Returns:** `function` — A function that applies `fns` in order

```typescript
import { pipe } from '@helpers4/function';

pipe<A, B, C, D, E, F, G, H>(fn1: function, fn2: function, fn3: function, fn4: function, fn5: function, fn6: function, fn7: function): function
```

**Parameters:**

- `fn1: function` — The first function. The overloads accept up to eight functions in all, passed as `fn1, fn2, …`.
- `fn2: function`
- `fn3: function`
- `fn4: function`
- `fn5: function`
- `fn6: function`
- `fn7: function`

**Returns:** `function` — A function that applies `fns` in order

```typescript
import { pipe } from '@helpers4/function';

pipe<A, B, C, D, E, F, G, H, I>(fn1: function, fn2: function, fn3: function, fn4: function, fn5: function, fn6: function, fn7: function, fn8: function): function
```

**Parameters:**

- `fn1: function` — The first function. The overloads accept up to eight functions in all, passed as `fn1, fn2, …`.
- `fn2: function`
- `fn3: function`
- `fn4: function`
- `fn5: function`
- `fn6: function`
- `fn7: function`
- `fn8: function`

**Returns:** `function` — A function that applies `fns` in order

**Examples:**

*Transform a value through a pipeline*

Functions are applied left-to-right; the output of each becomes the input of the next.

```typescript
const process = pipe(
  (x: number) => x + 1,
  (x: number) => x * 2,
  String
);
process(3); // => "8"
```

*Sanitise a string*

Chain string transforms left-to-right with pipe.

```typescript
const sanitize = pipe(
  (s: string) => s.trim(),
  (s: string) => s.toLowerCase(),
  (s: string) => s.replace(/\s+/g, '-')
);
sanitize('  Hello World  '); // => "hello-world"
```

---

### `returnOrThrowError`

Return a value or throw an error if null or undefined.

```typescript
import { returnOrThrowError } from '@helpers4/function';

returnOrThrowError<T>(value: T | null | undefined, error: string): T
```

**Parameters:**

- `value: T | null | undefined` — A possible non-defined value.
- `error: string` — The error message to throw.

**Returns:** `T` — A defined value or an error.

**Examples:**

*Return a defined value*

Returns the value when it is defined and not null.

```typescript
returnOrThrowError('hello', 'Value is missing')
// => 'hello'
```

*Throw on null*

Throws an error when the value is null or undefined.

```typescript
returnOrThrowError(null, 'Value is missing')
// throws Error('Value is missing')
```

---

### `throttle`

Creates a throttled function that only invokes func at most once per every wait milliseconds

Call `cancel()`, or abort the `signal`, on teardown: otherwise the trailing call still runs
after its owner is gone.

```typescript
import { throttle } from '@helpers4/function';

throttle<A extends unknown[], R>(func: function, wait: number, options: ThrottleOptions): Throttled<A>
```

**Parameters:**

- `func: function` — The function to throttle
- `wait: number` — The number of milliseconds to throttle invocations to
- `options: ThrottleOptions` (default: `{}`) — Cancellation — see ThrottleOptions

**Returns:** `Throttled<A>` — The throttled function, with a `cancel()` method

**Examples:**

*Throttle rapid calls*

The throttled function is invoked at most once per wait period.

```typescript
const fn = throttle(() => console.log('tick'), 100);
fn(); // executes immediately
fn(); // ignored (within wait period)
```

*Cancel on teardown*

An aborted signal, or cancel(), drops the call still waiting, so it never runs after its owner is gone.

```typescript
const controller = new AbortController();
const fn = throttle(() => console.log('late'), 100, { signal: controller.signal });
fn();
fn();
controller.abort();
// nothing is logged after the abort
```

---

### `unary`

Creates a function that calls `fn` with only its first argument, discarding
any others.

Prevents the classic footgun where a callback expecting extra positional
arguments is passed directly to `Array.prototype.map`:
`['1', '2', '3'].map(parseInt)` silently passes the array index as
`parseInt`'s radix argument, producing `[1, NaN, NaN]`.

```typescript
import { unary } from '@helpers4/function';

unary<F extends function>(fn: F): function
```

**Parameters:**

- `fn: F` — The function to restrict to one argument

**Returns:** `function` — A new function that calls `fn` with only its first argument

**Examples:**

*Fix the classic .map(parseInt) bug*

Array.prototype.map passes (value, index, array) — parseInt reads index as its radix argument.

```typescript
['1', '2', '3'].map(parseInt)
// => [1, NaN, NaN]  (bug: index used as radix)

['1', '2', '3'].map(unary(parseInt))
// => [1, 2, 3]
```

*Restrict any multi-argument function to one argument*

Useful whenever a callback slot passes more arguments than the function should see.

```typescript
const double = unary((n: number, factor?: number) => n * (factor ?? 2));
double(21)
// => 42
```

---

## geography

Package: `@helpers4/geography`

### `distance`

Great-circle distance between two WGS84 points, in kilometres (haversine formula, mean Earth
radius of 6371 km). The Earth is treated as a sphere, so the result can be off by up to about
0.5% compared to an ellipsoidal model — plenty for "how far is it" and radius checks. Near
antipodal points the formula loses a little precision (well under a metre).

```typescript
import { distance } from '@helpers4/geography';

distance(lat1: number, lon1: number, lat2: number, lon2: number): number
```

**Parameters:**

- `lat1: number` — Latitude of the first point, in degrees
- `lon1: number` — Longitude of the first point, in degrees
- `lat2: number` — Latitude of the second point, in degrees
- `lon2: number` — Longitude of the second point, in degrees

**Returns:** `number` — The distance in kilometres

**Examples:**

*Distance between two cities*

Great-circle distance in kilometres between two latitude/longitude points.

```typescript
distance(48.8566, 2.3522, 51.5074, -0.1278)
// => about 343.6 (Paris to London)
```

*Zero for the same point*

A point is at distance 0 from itself.

```typescript
distance(10, 20, 10, 20) // => 0
```

---

### `isWithinDistance`

Whether a point lies within a radius of a center, the border included.

```typescript
import { isWithinDistance } from '@helpers4/geography';

isWithinDistance(centerLat: number, centerLon: number, radius: number, pointLat: number, pointLon: number): boolean
```

**Parameters:**

- `centerLat: number` — Latitude of the center, in degrees
- `centerLon: number` — Longitude of the center, in degrees
- `radius: number` — The radius in kilometres
- `pointLat: number` — Latitude of the point, in degrees
- `pointLon: number` — Longitude of the point, in degrees

**Returns:** `boolean` — `true` when the point is at most `radius` kilometres from the center

**Examples:**

*Is a place near me?*

Radius check in kilometres, border included.

```typescript
isWithinDistance(48.8566, 2.3522, 5, 48.8606, 2.3376)
// => true
```

*Far away*

Paris is not within 5 km of London.

```typescript
isWithinDistance(48.8566, 2.3522, 5, 51.5074, -0.1278)
// => false
```

---

## geometry

Package: `@helpers4/geometry`

### `applyToPoint`

Transforms a point by a matrix.

```typescript
import { applyToPoint } from '@helpers4/geometry';

applyToPoint(m: Matrix, p: Point): Point
```

**Parameters:**

- `m: Matrix` — The matrix
- `p: Point` — The point

**Returns:** `Point` — The transformed point

**Examples:**

*Transform a point*

x' = a·x + c·y + e, y' = b·x + d·y + f.

```typescript
applyToPoint({ a: 1, b: 2, c: 3, d: 4, e: 5, f: 6 }, { x: 1, y: 1 }) // => { x: 9, y: 12 }
```

*With a helper matrix*

Any matrix built by translate, scale, rotate or multiply.

```typescript
applyToPoint(translate(10, 5), { x: 1, y: 1 }) // => { x: 11, y: 6 }
```

---

### `applyToRect`

Transforms a rectangle by a matrix and returns its bounding box: the smallest axis-aligned
rectangle that contains it. After a rotation or a skew, the box is larger than the rectangle.

```typescript
import { applyToRect } from '@helpers4/geometry';

applyToRect(m: Matrix, r: Rect): Rect
```

**Parameters:**

- `m: Matrix` — The matrix
- `r: Rect` — The rectangle

**Returns:** `Rect` — The bounding box of the transformed rectangle

**Examples:**

*Bounds of a scaled layer*

The bounding box of the transformed rectangle.

```typescript
applyToRect(scale(2), { x: 1, y: 1, width: 2, height: 3 }) // => { x: 2, y: 2, width: 4, height: 6 }
```

*Bounds of a rotated layer*

After a rotation, the box is larger than the rectangle.

```typescript
applyToRect(rotate(Math.PI / 4), { x: 0, y: 0, width: 1, height: 1 }).width // => √2
```

---

### `contains`

Whether a point or a rectangle is inside a rectangle.

For a point (hit-testing), the left and top edges are inside and the right and bottom ones are
not, so a point on the edge between two adjacent rectangles hits exactly one of them. A
rectangle is inside when it does not stick out: it may touch any edge.

```typescript
import { contains } from '@helpers4/geometry';

contains(r: Rect, target: Point | Rect): boolean
```

**Parameters:**

- `r: Rect` — The containing rectangle
- `target: Point | Rect` — A point, or a rectangle

**Returns:** `boolean` — `true` if `target` is inside `r`

**Examples:**

*Hit-test a click*

Shared edges hit once: the right and bottom edges are outside.

```typescript
const hit = hotspots.find((zone) => contains(zone, { x: event.offsetX, y: event.offsetY }));
```

*Is a layer fully on screen?*

A rectangle is inside when it does not stick out.

```typescript
contains(viewport, layerBounds)
```

---

### `ellipsePath`

The path of the ellipse that fills a box, as SVG path data: two half-turn arcs. A square box
gives a circle.

```typescript
import { ellipsePath } from '@helpers4/geometry';

ellipsePath(box: Rect): string
```

**Parameters:**

- `box: Rect` — The bounding box of the ellipse

**Returns:** `string` — The path data, closed

**Examples:**

*Fill a box with an ellipse*

Two half-turn arcs; a square box gives a circle.

```typescript
ellipsePath({ x: 0, y: 0, width: 10, height: 6 }) // => 'M0 3 A5 3 0 0 1 10 3 A5 3 0 0 1 0 3 Z'
```

---

### `fit`

Places content in a box like CSS `object-fit` and `object-position`, e.g. to show a design
frame in a viewport of another size.

The result is the matrix from content coordinates to box coordinates: its `a` and `d` are
the scales, `e` and `f` the position of the content's top-left corner. Combine it with
multiply, map points with applyToPoint, or write it with matrixToCss.
Sizes are expected to be positive.

```typescript
import { fit } from '@helpers4/geometry';

fit(content: Size, box: Size, options: FitOptions): Matrix
```

**Parameters:**

- `content: Size` — The size of the content
- `box: Size` — The size of the box
- `options: FitOptions` (default: `{}`) — Mode and alignment — see FitOptions

**Returns:** `Matrix` — The content-to-box matrix

**Examples:**

*Show a frame in a viewport*

contain (the default) keeps the whole frame visible, centered.

```typescript
fit({ width: 200, height: 100 }, { width: 100, height: 100 })
// => { a: 0.5, b: 0, c: 0, d: 0.5, e: 0, f: 25 }
```

*Cover, aligned to the left*

Like object-fit: cover; object-position: left.

```typescript
fit({ width: 200, height: 100 }, { width: 100, height: 100 }, { mode: 'cover', align: { x: 0 } })
// => { a: 1, b: 0, c: 0, d: 1, e: 0, f: 0 }
```

---

### `fitContain`

Places content in a box, as large as possible while staying entirely inside the box (CSS `object-fit: contain`). Shortcut for `fit(content, box, { mode: 'contain', align })`.

```typescript
import { fitContain } from '@helpers4/geometry';

fitContain(content: Size, box: Size, align?: FitAlign): Matrix
```

**Parameters:**

- `content: Size` — The size of the content
- `box: Size` — The size of the box
- `align?: FitAlign` — Where to place it, centered by default — see FitAlign

**Returns:** `Matrix` — The content-to-box matrix (`a`/`d` scales, `e`/`f` position)

**Examples:**

*Centered*

Same as fit(content, box, { mode: 'contain' }).

```typescript
fitContain({ width: 200, height: 100 }, { width: 100, height: 100 })
// => { a: 0.5, b: 0, c: 0, d: 0.5, e: 0, f: 25 }
```

*Aligned to the top-left corner*

The third argument is the alignment, like CSS object-position.

```typescript
fitContain({ width: 200, height: 100 }, { width: 100, height: 100 }, { x: 0, y: 0 })
```

---

### `fitCover`

Places content in a box, as small as possible while covering the whole box (CSS `object-fit: cover`). Shortcut for `fit(content, box, { mode: 'cover', align })`.

```typescript
import { fitCover } from '@helpers4/geometry';

fitCover(content: Size, box: Size, align?: FitAlign): Matrix
```

**Parameters:**

- `content: Size` — The size of the content
- `box: Size` — The size of the box
- `align?: FitAlign` — Where to place it, centered by default — see FitAlign

**Returns:** `Matrix` — The content-to-box matrix (`a`/`d` scales, `e`/`f` position)

**Examples:**

*Centered*

Same as fit(content, box, { mode: 'cover' }).

```typescript
fitCover({ width: 200, height: 100 }, { width: 100, height: 100 })
// => { a: 1, b: 0, c: 0, d: 1, e: -50, f: 0 }
```

*Aligned to the top-left corner*

The third argument is the alignment, like CSS object-position.

```typescript
fitCover({ width: 200, height: 100 }, { width: 100, height: 100 }, { x: 0, y: 0 })
```

---

### `fitFill`

Places content in a box, stretched to the box on each axis, without keeping its proportions (CSS `object-fit: fill`). Shortcut for `fit(content, box, { mode: 'fill', align })`.

```typescript
import { fitFill } from '@helpers4/geometry';

fitFill(content: Size, box: Size, align?: FitAlign): Matrix
```

**Parameters:**

- `content: Size` — The size of the content
- `box: Size` — The size of the box
- `align?: FitAlign` — Where to place it, centered by default — see FitAlign

**Returns:** `Matrix` — The content-to-box matrix (`a`/`d` scales, `e`/`f` position)

**Examples:**

*Centered*

Same as fit(content, box, { mode: 'fill' }).

```typescript
fitFill({ width: 200, height: 100 }, { width: 100, height: 100 })
// => { a: 0.5, b: 0, c: 0, d: 1, e: 0, f: 0 }
```

*Aligned to the top-left corner*

The third argument is the alignment, like CSS object-position.

```typescript
fitFill({ width: 200, height: 100 }, { width: 100, height: 100 }, { x: 0, y: 0 })
```

---

### `fitNone`

Places content in a box, at its own size, only positioned (CSS `object-fit: none`). Shortcut for `fit(content, box, { mode: 'none', align })`.

```typescript
import { fitNone } from '@helpers4/geometry';

fitNone(content: Size, box: Size, align?: FitAlign): Matrix
```

**Parameters:**

- `content: Size` — The size of the content
- `box: Size` — The size of the box
- `align?: FitAlign` — Where to place it, centered by default — see FitAlign

**Returns:** `Matrix` — The content-to-box matrix (`a`/`d` scales, `e`/`f` position)

**Examples:**

*Centered*

Same as fit(content, box, { mode: 'none' }).

```typescript
fitNone({ width: 200, height: 100 }, { width: 100, height: 100 })
// => { a: 1, b: 0, c: 0, d: 1, e: -50, f: 0 }
```

*Aligned to the top-left corner*

The third argument is the alignment, like CSS object-position.

```typescript
fitNone({ width: 200, height: 100 }, { width: 100, height: 100 }, { x: 0, y: 0 })
```

---

### `fitScaleDown`

Places content in a box, like fitContain, but never enlarged (CSS `object-fit: scale-down`). Shortcut for `fit(content, box, { mode: 'scale-down', align })`.

```typescript
import { fitScaleDown } from '@helpers4/geometry';

fitScaleDown(content: Size, box: Size, align?: FitAlign): Matrix
```

**Parameters:**

- `content: Size` — The size of the content
- `box: Size` — The size of the box
- `align?: FitAlign` — Where to place it, centered by default — see FitAlign

**Returns:** `Matrix` — The content-to-box matrix (`a`/`d` scales, `e`/`f` position)

**Examples:**

*Centered*

Same as fit(content, box, { mode: 'scale-down' }).

```typescript
fitScaleDown({ width: 200, height: 100 }, { width: 100, height: 100 })
// => { a: 0.5, b: 0, c: 0, d: 0.5, e: 0, f: 25 }
```

*Aligned to the top-left corner*

The third argument is the alignment, like CSS object-position.

```typescript
fitScaleDown({ width: 200, height: 100 }, { width: 100, height: 100 }, { x: 0, y: 0 })
```

---

### `formatPath`

Writes path commands back as SVG path data: letters and numbers separated by single spaces,
numbers rounded to `precision` decimals with the trailing zeros dropped (`-0` is written `0`).

```typescript
import { formatPath } from '@helpers4/geometry';

formatPath(commands: readonly PathCommand[], precision: number): string
```

**Parameters:**

- `commands: readonly PathCommand[]` — The commands, as parsePath returns them
- `precision: number` (default: `6`) — Decimals kept per number. Defaults to `6`

**Returns:** `string` — The path data

**Examples:**

*Write commands back*

Numbers are rounded and written with single spaces.

```typescript
formatPath([{ type: 'M', values: [0, 0.5] }, { type: 'L', values: [10, 1 / 3] }]) // => 'M0 0.5 L10 0.333333'
```

---

### `identity`

The matrix that changes nothing.

```typescript
import { identity } from '@helpers4/geometry';

identity(): Matrix
```

**Returns:** `Matrix` — `{ a: 1, b: 0, c: 0, d: 1, e: 0, f: 0 }`

**Examples:**

*Start from no transformation*

The identity leaves every point where it is.

```typescript
applyToPoint(identity(), { x: 3, y: 4 }) // => { x: 3, y: 4 }
```

*Neutral element of multiply*

Multiplying by the identity returns the same transformation.

```typescript
multiply(identity(), translate(5, 0)) // => translate(5, 0)
```

---

### `intersection`

The area two rectangles have in common.

Rectangles that only touch (along an edge or at a corner) have no area in common.

```typescript
import { intersection } from '@helpers4/geometry';

intersection(a: Rect, b: Rect): Rect | undefined
```

**Parameters:**

- `a: Rect` — A rectangle
- `b: Rect` — Another rectangle

**Returns:** `Rect | undefined` — The overlapping rectangle, or `undefined` when they do not overlap

**Examples:**

*Visible part of a layer*

Intersect a layer with the viewport.

```typescript
intersection({ x: 0, y: 0, width: 10, height: 10 }, { x: 5, y: 5, width: 10, height: 10 })
// => { x: 5, y: 5, width: 5, height: 5 }
```

*Touching rectangles*

Sharing an edge is not overlapping.

```typescript
intersection({ x: 0, y: 0, width: 10, height: 10 }, { x: 10, y: 0, width: 10, height: 10 }) // => undefined
```

---

### `intersects`

Whether two rectangles have an area in common, exactly when intersection returns
a rectangle: rectangles that only touch do not, and neither does an empty (zero width or
height) rectangle.

```typescript
import { intersects } from '@helpers4/geometry';

intersects(a: Rect, b: Rect): boolean
```

**Parameters:**

- `a: Rect` — A rectangle
- `b: Rect` — Another rectangle

**Returns:** `boolean` — `true` if they have an area in common

**Examples:**

*Is a layer on screen?*

True when the rectangles have an area in common.

```typescript
intersects(layer, viewport)
```

*Touching is not overlapping*

Adjacent rectangles do not intersect.

```typescript
intersects({ x: 0, y: 0, width: 10, height: 10 }, { x: 10, y: 0, width: 10, height: 10 }) // => false
```

---

### `invert`

The matrix that undoes `m`, e.g. to turn a pointer position on screen back into the
coordinates of a transformed layer.

A matrix that flattens the plane onto a line or a point (determinant `0`, like `scale(0)`)
cannot be undone. There is no tolerance: a nearly flat matrix is inverted, with very large
values, as long as they stay finite.

```typescript
import { invert } from '@helpers4/geometry';

invert(m: Matrix): Matrix | undefined
```

**Parameters:**

- `m: Matrix` — The matrix to invert

**Returns:** `Matrix | undefined` — The inverse, or `undefined` when `m` cannot be inverted

**Examples:**

*Pointer position in a layer*

Invert the layer transform to map screen coordinates back into the layer.

```typescript
const layer = multiply(translate(100, 50), scale(2));
applyToPoint(invert(layer)!, { x: 120, y: 70 }) // => { x: 10, y: 10 }
```

*Not invertible*

A matrix that flattens the plane cannot be undone.

```typescript
invert(scale(0)) // => undefined
```

---

### `matrixToCss`

Writes a matrix as a CSS `transform` or SVG `transform` value.

Entries are written as JavaScript prints them, without rounding; non-finite entries give a
value CSS rejects.

```typescript
import { matrixToCss } from '@helpers4/geometry';

matrixToCss(m: Matrix): string
```

**Parameters:**

- `m: Matrix` — The matrix

**Returns:** `string` — `matrix(a, b, c, d, e, f)`

**Examples:**

*Write a CSS transform*

The six entries in CSS and SVG order.

```typescript
matrixToCss({ a: 2, b: 0, c: 0, d: 2, e: 10, f: -5 }) // => 'matrix(2, 0, 0, 2, 10, -5)'
```

*Fit a frame into a viewport*

Combine with fitContain to scale an element with CSS.

```typescript
element.style.transform = matrixToCss(fitContain(frame, viewport));
```

---

### `multiply`

Multiplies matrices, in the mathematical order: the last one applies first. It is the order of
a CSS `transform` list, so `multiply(translate(10, 0), rotate(r))` is
`transform: translate(10px) rotate(r)`: rotate, then translate.

In other words, `applyToPoint(multiply(m1, m2), p)` equals
`applyToPoint(m1, applyToPoint(m2, p))`.

```typescript
import { multiply } from '@helpers4/geometry';

multiply(matrices: readonly Matrix[]): Matrix
```

**Parameters:**

- `matrices: readonly Matrix[]` — The matrices, outermost first

**Returns:** `Matrix` — Their product, or the identity for none

**Examples:**

*Same order as a CSS transform list*

The last matrix applies first: here, scale then translate.

```typescript
// transform: translate(10px, 0) scale(2)
applyToPoint(multiply(translate(10, 0), scale(2)), { x: 1, y: 1 }) // => { x: 12, y: 2 }
```

*Scale around a point*

Move the point to the origin, scale, move it back.

```typescript
const m = multiply(translate(50, 50), scale(2), translate(-50, -50));
applyToPoint(m, { x: 60, y: 50 }) // => { x: 70, y: 50 }
```

---

### `parsePath`

Parses SVG path data (the `d` attribute) into commands, as written: the letters keep their case
(absolute or relative), `H`/`V`/`S`/`T`/`A` stay what they are, and a command repeated without
its letter (`L 1 2 3 4`) becomes one command per set of numbers (`M` repeats as `L`, `m` as `l`).

It follows the SVG grammar: numbers may be glued (`1-2`, `.5.5`, `1e-3`), separators are
optional, and the two arc flags may be written without any separator (`a1 1 0 011 1`).

```typescript
import { parsePath } from '@helpers4/geometry';

parsePath(d: string): PathCommand[]
```

**Parameters:**

- `d: string` — The path data

**Returns:** `PathCommand[]` — The commands, in order. Empty for an empty or blank string

**Examples:**

*Read path data*

Letters keep their case; a repeated command becomes one command per set of numbers.

```typescript
parsePath('M0 0h10v10z').map((c) => c.type) // => ['M', 'h', 'v', 'z']
```

---

### `rectToRect`

The translation and scale that put one rectangle exactly on another, for animating or fitting
between two boxes. An axis where `from` has no extent is only translated (scale `1`).

```typescript
import { rectToRect } from '@helpers4/geometry';

rectToRect(from: Rect, to: Rect): Matrix
```

**Parameters:**

- `from: Rect` — The rectangle to move
- `to: Rect` — The rectangle to reach

**Returns:** `Matrix` — The matrix that maps `from` onto `to`

**Examples:**

*Put one box on another*

The matrix scales and moves the first rectangle exactly onto the second.

```typescript
rectToRect({ x: 0, y: 0, width: 10, height: 10 }, { x: 5, y: 5, width: 20, height: 10 })
// => { a: 2, b: 0, c: 0, d: 1, e: 5, f: 5 }
```

---

### `rotate`

A matrix that rotates points around the origin. With the y axis pointing down (screen, CSS,
SVG), a positive angle turns clockwise, like CSS `rotate()`.

```typescript
import { rotate } from '@helpers4/geometry';

rotate(radians: number): Matrix
```

**Parameters:**

- `radians: number` — The angle, in radians

**Returns:** `Matrix` — The rotation matrix

**Examples:**

*Quarter turn*

With y pointing down, a positive angle turns clockwise, like CSS rotate().

```typescript
applyToPoint(rotate(Math.PI / 2), { x: 1, y: 0 }) // => { x: 0, y: 1 } (rounded)
```

*Degrees*

Convert degrees to radians first.

```typescript
rotate((45 * Math.PI) / 180)
```

---

### `roundedRectPath`

The path of a rectangle with a radius per corner, as SVG path data. Each radius is clamped to
half the smaller side, and a radius of `0` gives a square corner (no arc is written).

```typescript
import { roundedRectPath } from '@helpers4/geometry';

roundedRectPath(rect: Rect, radius: number | readonly [number, number, number, number]): string
```

**Parameters:**

- `rect: Rect` — The rectangle
- `radius: number | readonly [number, number, number, number]` — One radius for the four corners, or `[topLeft, topRight, bottomRight, bottomLeft]` as in CSS `border-radius`. Negative radii count as `0`

**Returns:** `string` — The path data, closed

**Examples:**

*Round one corner*

A radius per corner, in CSS order; zero keeps a square corner.

```typescript
roundedRectPath({ x: 0, y: 0, width: 10, height: 10 }, [5, 0, 0, 0])
```

---

### `scale`

A matrix that scales points from the origin.

```typescript
import { scale } from '@helpers4/geometry';

scale(sx: number, sy: number): Matrix
```

**Parameters:**

- `sx: number` — Horizontal factor
- `sy: number` (default: `sx`) — Vertical factor, `sx` by default

**Returns:** `Matrix` — The scaling matrix

**Examples:**

*Uniform scale*

One factor scales both axes.

```typescript
applyToPoint(scale(2), { x: 3, y: 4 }) // => { x: 6, y: 8 }
```

*Flip vertically*

A negative factor mirrors the axis.

```typescript
applyToPoint(scale(1, -1), { x: 3, y: 4 }) // => { x: 3, y: -4 }
```

---

### `simplifyPolyline`

Removes the points of a polyline that change its shape by less than `tolerance`, with the
Ramer–Douglas–Peucker algorithm: each removed point is at most `tolerance` away from the
simplified line. It shrinks map outlines or traced paths by orders of magnitude while keeping
their look.

The first and last points are always kept. With a `tolerance` of `0`, only points exactly on a
straight line are removed. It is iterative, so very long polylines do not overflow the stack.

```typescript
import { simplifyPolyline } from '@helpers4/geometry';

simplifyPolyline(points: readonly Point[], tolerance: number): Point[]
```

**Parameters:**

- `points: readonly Point[]` — The polyline
- `tolerance: number` — The maximum distance between a removed point and the result, in the units of the points

**Returns:** `Point[]` — The kept points, in their original order

**Examples:**

*Drop a nearly straight point*

A point closer than the tolerance to the simplified line is removed.

```typescript
simplifyPolyline([{ x: 0, y: 0 }, { x: 1, y: 0.1 }, { x: 2, y: 0 }], 0.5)
// => [{ x: 0, y: 0 }, { x: 2, y: 0 }]
```

*Shrink a map outline*

Pick the tolerance in the units of the points, e.g. a fraction of a pixel at the final scale.

```typescript
const outline = simplifyPolyline(border, 0.5);
```

---

### `transformPath`

Transforms SVG path data by a matrix. The result is written with absolute `M`, `L`, `C`, `Q`
and `Z` only: relative commands are made absolute, `H`/`V`/`S`/`T` are expanded, and arcs
become cubic curves (so any matrix works, skews included). Moving a path is the common case.

```typescript
import { transformPath } from '@helpers4/geometry';

transformPath(d: string, m: Matrix, precision: number): string
```

**Parameters:**

- `d: string` — The path data
- `m: Matrix` — The matrix, in the CSS/SVG layout
- `precision: number` (default: `6`) — Decimals kept per number. Defaults to `6`

**Returns:** `string` — The transformed path data

**Examples:**

*Move a path*

Relative commands are made absolute, then every point is transformed.

```typescript
transformPath('M0 0 h10 v10 z', translate(5, 5)) // => 'M5 5 L15 5 L15 15 Z'
```

---

### `translate`

A matrix that moves points by `(tx, ty)`.

```typescript
import { translate } from '@helpers4/geometry';

translate(tx: number, ty: number): Matrix
```

**Parameters:**

- `tx: number` — Horizontal offset
- `ty: number` — Vertical offset

**Returns:** `Matrix` — The translation matrix

**Examples:**

*Move a point*

e and f hold the offset.

```typescript
applyToPoint(translate(10, 5), { x: 1, y: 1 }) // => { x: 11, y: 6 }
```

*Negative offsets*

Move up and to the left.

```typescript
applyToPoint(translate(-1, -1), { x: 0, y: 0 }) // => { x: -1, y: -1 }
```

---

### `union`

The smallest rectangle that contains all the given rectangles, e.g. the bounds of a group of
layers.

```typescript
import { union } from '@helpers4/geometry';

union(rects: readonly Rect[]): Rect | undefined
```

**Parameters:**

- `rects: readonly Rect[]` — The rectangles

**Returns:** `Rect | undefined` — Their bounding rectangle, or `undefined` for none

**Examples:**

*Bounds of a group*

The smallest rectangle containing every layer.

```typescript
union([{ x: 0, y: 0, width: 10, height: 10 }, { x: 20, y: 5, width: 10, height: 10 }])
// => { x: 0, y: 0, width: 30, height: 15 }
```

*Empty group*

No rectangle, no bounds.

```typescript
union([]) // => undefined
```

---

## guard

Package: `@helpers4/guard`

### `isArray`

Checks if a value is an array.

```typescript
import { isArray } from '@helpers4/guard';

isArray(value: unknown): value is unknown[]
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is unknown[]` — True if value is an array

**Examples:**

*isArray*

```typescript
```ts
isArray([1, 2, 3]) // => true
isArray('hello')   // => false
isArray({})        // => false
```
```

---

### `isArrayBuffer`

Checks if a value is an ArrayBuffer instance.

Useful for filtering or type-narrowing in a functional pipeline:
`values.filter(isArrayBuffer)`

```typescript
import { isArrayBuffer } from '@helpers4/guard';

isArrayBuffer(value: unknown): value is ArrayBuffer
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is ArrayBuffer` — True if value is an ArrayBuffer

**Examples:**

*Detect an ArrayBuffer*

Returns true only for ArrayBuffer instances, not TypedArray views.

```typescript
isArrayBuffer(new ArrayBuffer(8)) // => true
isArrayBuffer(new Uint8Array(8))  // => false
isArrayBuffer('hello')            // => false
```

*Filter ArrayBuffers from a mixed array*

Use as a predicate in .filter() to extract ArrayBuffer values.

```typescript
const values = [new ArrayBuffer(4), 'text', new ArrayBuffer(8), 42];
values.filter(isArrayBuffer)
// => [ArrayBuffer(4), ArrayBuffer(8)]
```

---

### `isArrayLike`

Checks if a value is array-like: has a non-negative integer `length` property.

Returns `true` for arrays, strings, `arguments` objects, `NodeList`, typed
arrays, and any object with a valid `length`. Functions are excluded even though
they have a `length` (arity), as they are not considered array-like in practice.

```typescript
import { isArrayLike } from '@helpers4/guard';

isArrayLike(value: unknown): value is ArrayLike<unknown>
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is ArrayLike<unknown>` — `true` if value is array-like

**Examples:**

*Detect array-like values*

Arrays, strings, and objects with a non-negative integer length are array-like.

```typescript
isArrayLike([1, 2, 3])       // => true
isArrayLike('hello')         // => true
isArrayLike({ length: 3 })   // => true
isArrayLike({ length: -1 })  // => false
isArrayLike(() => {})        // => false  (functions excluded)
isArrayLike(null)            // => false
```

*Convert an array-like value to an array*

Use as a guard before Array.from().

```typescript
function toArray(value: unknown): unknown[] {
  if (isArrayLike(value)) return Array.from(value);
  return [value];
}
toArray([1, 2])       // => [1, 2]
toArray('abc')        // => ['a', 'b', 'c']
toArray(42)           // => [42]
```

---

### `isAsyncFunction`

Checks if a value is an async function.

Returns `true` for any function declared with `async`.

```typescript
import { isAsyncFunction } from '@helpers4/guard';

isAsyncFunction(value: unknown): value is function
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is function` — True if value is an async function

**Examples:**

*isAsyncFunction*

```typescript
```ts
isAsyncFunction(async () => {})      // => true
isAsyncFunction(async function() {}) // => true
isAsyncFunction(() => {})            // => false
isAsyncFunction(42)                  // => false
```
```

---

### `isAsyncGenerator`

Checks if a value is an async generator object (the result of calling an `async function*`).

Distinct from isAsyncGeneratorFunction: this predicate targets the
*instance* produced by calling an async generator function, not the function itself.

```typescript
import { isAsyncGenerator } from '@helpers4/guard';

isAsyncGenerator(value: unknown): value is AsyncGenerator<unknown, unknown, unknown>
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is AsyncGenerator<unknown, unknown, unknown>` — `true` if value is an AsyncGenerator instance

**Examples:**

*Detect an async generator instance*

Returns true only for the object produced by calling an async function*.

```typescript
async function* gen() { yield 1; }
isAsyncGenerator(gen())  // => true   (instance)
isAsyncGenerator(gen)    // => false  (function)
isAsyncGenerator([])     // => false
```

*Distinguish async from sync generators*

isAsyncGenerator is false for sync generator instances.

```typescript
function* sync() { yield 1; }
async function* async_() { yield 1; }
isAsyncGenerator(sync())   // => false
isAsyncGenerator(async_()) // => true
```

---

### `isAsyncGeneratorFunction`

Checks if a value is an async generator function (an `async function*` declaration or expression).

Distinct from isAsyncGenerator: this predicate targets the *function* itself,
not the async iterator it produces when called.

```typescript
import { isAsyncGeneratorFunction } from '@helpers4/guard';

isAsyncGeneratorFunction(value: unknown): value is AsyncGeneratorFunction
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is AsyncGeneratorFunction` — `true` if value is an AsyncGeneratorFunction

**Examples:**

*Detect an async generator function*

Returns true for async function* declarations and expressions.

```typescript
async function* gen() { yield 1; }
isAsyncGeneratorFunction(gen)         // => true
isAsyncGeneratorFunction(gen())       // => false  (instance)
isAsyncGeneratorFunction(async () => {}) // => false
```

*Distinguish async generator functions from sync generator functions*

isAsyncGeneratorFunction is false for sync function*.

```typescript
function* sync() { yield 1; }
async function* async_() { yield 1; }
isAsyncGeneratorFunction(sync)   // => false
isAsyncGeneratorFunction(async_) // => true
```

---

### `isAsyncIterable`

Checks if a value implements the async iterable protocol.

Returns `true` for any object that has a `[Symbol.asyncIterator]()` method,
including async generators. Note that regular iterables (arrays, strings, etc.)
are **not** async iterables.

```typescript
import { isAsyncIterable } from '@helpers4/guard';

isAsyncIterable(value: unknown): value is AsyncIterable<unknown, any, any>
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is AsyncIterable<unknown, any, any>` — `true` if value is async iterable

**Examples:**

*Detect an async generator*

Async generators implement the async iterable protocol.

```typescript
async function* stream() { yield 1; yield 2; }
isAsyncIterable(stream())   // => true
isAsyncIterable([1, 2, 3])  // => false  (Iterable, not AsyncIterable)
isAsyncIterable('hello')    // => false
```

*Guard before for-await-of*

Use to type-narrow before consuming a value with for-await-of.

```typescript
async function consume(source: unknown) {
  if (isAsyncIterable(source)) {
    for await (const item of source) {
      console.log(item);
    }
  }
}
```

---

### `isBigInt`

Checks if a value is a bigint.

```typescript
import { isBigInt } from '@helpers4/guard';

isBigInt(value: unknown): value is bigint
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is bigint` — True if value is a bigint

**Examples:**

*isBigInt*

```typescript
```ts
isBigInt(42n)  // => true
isBigInt(42)   // => false
isBigInt('42') // => false
```
```

---

### `isBlob`

Checks if a value is a Blob instance.

Useful for filtering or type-narrowing in a functional pipeline:
`values.filter(isBlob)`

**Known limitation:** the declared type is the DOM `Blob`, so a project compiled without the DOM
lib (GJS, for example) gets `Cannot find name 'Blob'` from this package's `index.d.ts`. At
runtime it is safe everywhere: it returns `false` where `Blob` does not exist. The alternatives
are not clearly better, so it is left as is: a structural `BlobLike` type would narrow to that
type instead of `Blob` for callers that have the DOM, moving it to `browser` would break
existing imports (and `Blob` also exists in Node.js, Deno and Bun), and a polyfill would not fix
the compile error. To be reconsidered for v4.

```typescript
import { isBlob } from '@helpers4/guard';

isBlob(value: unknown): value is Blob
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is Blob` — True if value is a Blob

**Examples:**

*Detect a Blob*

Returns true only for Blob instances.

```typescript
isBlob(new Blob(['hello'])) // => true
isBlob(new Blob([], { type: 'application/json' })) // => true
isBlob('hello')             // => false
```

*Filter Blobs from a mixed array*

Use as a predicate in .filter() to extract Blob values.

```typescript
const values = [new Blob(['a']), 'text', new Blob(['b']), 42];
values.filter(isBlob)
// => [Blob, Blob]
```

---

### `isBoolean`

Checks if a value is a boolean.

```typescript
import { isBoolean } from '@helpers4/guard';

isBoolean(value: unknown): value is boolean
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is boolean` — True if value is a boolean

**Examples:**

*isBoolean*

```typescript
```ts
isBoolean(true)  // => true
isBoolean(false) // => true
isBoolean(1)     // => false
```
```

---

### `isBrowser`

Checks whether the code is currently running in a browser-like environment
(`window` and `window.document` both defined).

Note: some hybrid test environments (e.g. happy-dom, jsdom) define both `window` and Node's
`process` at the same time — this only reports on `window`'s presence, it does not imply
`isNode` is false. Use both together if you need to distinguish a real browser from a
DOM-emulating Node test environment.

```typescript
import { isBrowser } from '@helpers4/guard';

isBrowser(): boolean
```

**Returns:** `boolean` — `true` if `window` and `window.document` are both defined

**Examples:**

*Branch on the runtime environment*

Useful for isomorphic code that behaves differently in the browser vs. Node.js.

```typescript
if (isBrowser()) {
  localStorage.setItem('key', 'value')
} else {
  // Node.js / server-side fallback
}
```

---

### `isCanonicalJson`

Checks whether a value is a string that is already canonical JSON (RFC 8785, JSON
Canonicalization Scheme) — byte for byte what `stringify(value, 'canonical')` from
`@helpers4/json` would write for the value it holds.

That means: no whitespace outside strings, object keys sorted by UTF-16 code units, no
duplicate keys, numbers in their shortest ECMAScript form (`1`, not `1.0` or `1e0`), strings
with only the escapes `JSON.stringify` uses, and no number beyond what a double holds exactly.

```typescript
import { isCanonicalJson } from '@helpers4/guard';

isCanonicalJson(value: unknown): value is string
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is string` — `true` if `value` is a string in canonical JSON form

**Examples:**

*Check canonical JSON*

Sorted keys, no whitespace, shortest numbers (RFC 8785).

```typescript
isCanonicalJson('{"a":1,"b":2}') // => true
```

*Valid JSON is not always canonical*

Unsorted keys, whitespace or 1.0 instead of 1 all fail.

```typescript
isCanonicalJson('{"b":2,"a":1}') // => false
isCanonicalJson('1.0')           // => false
```

---

### `isCssColor`

Checks whether a value is a syntactically-safe, plain CSS color: a hex color
(`#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`), a functional notation (`rgb()`,
`rgba()`, `hsl()`, `hsla()`), or a single-word named color (`red`,
`rebeccapurple`).

Intended to sanitize a color value before interpolating it into inline
`style`/`cssText` — it does not implement the full CSS color grammar or
validate named colors against the real keyword list, it only rejects
characters (`{`, `}`, `;`, ``) or shapes that could smuggle extra CSS
declarations into the surrounding rule.

```typescript
import { isCssColor } from '@helpers4/guard';

isCssColor(value: unknown): value is string
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is string` — `true` if value is a string that looks like a safe, plain CSS color

**Examples:**

*Validate a color before writing it to inline style*

Accepts hex, functional (rgb/rgba/hsl/hsla), and named colors.

```typescript
isCssColor('#ff0000')            // => true
isCssColor('rgba(0, 0, 0, 0.5)') // => true
isCssColor('rebeccapurple')      // => true
isCssColor(42)                   // => false
```

*Reject values that could inject extra CSS declarations*

Guards against untrusted data smuggling a second declaration into a style attribute.

```typescript
isCssColor('red; background: url(evil)') // => false
isCssColor('red}body{color:blue')        // => false
```

---

### `isDate`

Checks if a value is a Date instance.

Note: this only checks the type, not whether the Date is valid.
Use `date/isValid` to also validate that the Date is not `Invalid Date`.

```typescript
import { isDate } from '@helpers4/guard';

isDate(value: unknown): value is Date
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is Date` — True if value is a Date instance

**Examples:**

*isDate*

```typescript
```ts
isDate(new Date())          // => true
isDate(new Date('invalid')) // => true (still a Date instance)
isDate('2023-01-01')       // => false
isDate(1609459200000)      // => false
```
```

---

### `isDefined`

Checks if a value is defined (not undefined nor null).
This is the inverse of isNullish.

Use as a type-safe filter callback to remove `null`/`undefined` from arrays.

```typescript
import { isDefined } from '@helpers4/guard';

isDefined<T>(value: Maybe<T>): value is T
```

**Parameters:**

- `value: Maybe<T>` — The value to check

**Returns:** `value is T` — True if value is not undefined nor null

**Examples:**

*isDefined*

```typescript
```ts
isDefined(42)        // => true
isDefined('')        // => true (empty string is defined)
isDefined(null)      // => false
isDefined(undefined) // => false
```
```

*isDefined*

```typescript
```ts
// Type-safe alternative to filter out null/undefined
const items: (string | null | undefined)[] = ['a', null, 'b', undefined];
const result = items.filter(isDefined);
// => ['a', 'b'] with type string[]
```
```

---

### `isError`

Checks if a value is an Error instance.

```typescript
import { isError } from '@helpers4/guard';

isError(value: unknown): value is Error
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is Error` — True if value is an Error (or subclass like TypeError, RangeError, etc.)

**Examples:**

*isError*

```typescript
```ts
isError(new Error('oops'))     // => true
isError(new TypeError('bad'))  // => true
isError({ message: 'fake' })  // => false
```
```

---

### `isFalsy`

Checks if a value is falsy (`false`, `null`, `undefined`, `0`, `""`, `NaN`).

```typescript
import { isFalsy } from '@helpers4/guard';

isFalsy(value: unknown): value is Falsy
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is Falsy` — True if the value is falsy

**Examples:**

*Check falsy values*

Returns true for all falsy values: false, null, undefined, 0, "", NaN.

```typescript
isFalsy(0)         // => true
isFalsy('')        // => true
isFalsy(null)      // => true
isFalsy('hello')   // => false
```

---

### `isFormData`

Checks if a value is a FormData instance.

Useful for filtering or type-narrowing in a functional pipeline:
`values.filter(isFormData)`

**Known limitation:** the declared type is the DOM `FormData`, so a project compiled without the DOM
lib (GJS, for example) gets `Cannot find name 'FormData'` from this package's `index.d.ts`. At
runtime it is safe everywhere: it returns `false` where `FormData` does not exist. The alternatives
are not clearly better, so it is left as is: a structural `FormDataLike` type would narrow to that
type instead of `FormData` for callers that have the DOM, moving it to `browser` would break
existing imports (and `FormData` also exists in Node.js, Deno and Bun), and a polyfill would not fix
the compile error. To be reconsidered for v4.

```typescript
import { isFormData } from '@helpers4/guard';

isFormData(value: unknown): value is FormData
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is FormData` — True if value is a FormData

**Examples:**

*Detect a FormData*

Returns true only for FormData instances.

```typescript
isFormData(new FormData()) // => true
isFormData({})             // => false
isFormData(null)           // => false
```

*Filter FormData from a mixed array*

Use as a predicate in .filter() to extract FormData values.

```typescript
const fd = new FormData();
fd.append('name', 'Alice');
const values = [fd, {}, new FormData(), 'text'];
values.filter(isFormData)
// => [FormData, FormData]
```

---

### `isFunction`

Checks if a value is a function.

```typescript
import { isFunction } from '@helpers4/guard';

isFunction(value: unknown): value is Function
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is Function` — True if value is a function

**Examples:**

*isFunction*

```typescript
```ts
isFunction(() => {})       // => true
isFunction(function() {})  // => true
isFunction('function')     // => false
```
```

---

### `isGenerator`

Checks if a value is a generator object (the result of calling a `function*`).

Distinct from isGeneratorFunction: this predicate targets the
*instance* produced by calling a generator function, not the function itself.

```typescript
import { isGenerator } from '@helpers4/guard';

isGenerator(value: unknown): value is Generator<unknown, unknown, unknown>
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is Generator<unknown, unknown, unknown>` — `true` if value is a Generator instance

**Examples:**

*Distinguish a generator instance from its function*

isGenerator targets the object returned by calling a function*, not the function itself.

```typescript
function* counter() { yield 1; yield 2; }
isGenerator(counter())  // => true   (instance)
isGenerator(counter)    // => false  (function)
isGenerator([1, 2])     // => false
```

*Type-narrow to safely call .next()*

Narrows the type to Generator so you can call .next() and .return().

```typescript
function* gen() { yield 1; yield 2; }
const value: unknown = gen();
if (isGenerator(value)) {
  const { value: v, done } = value.next();
  // v: unknown, done: boolean | undefined
}
```

---

### `isGeneratorFunction`

Checks if a value is a generator function (a `function*` declaration or expression).

Distinct from isGenerator: this predicate targets the *function* itself,
not the iterator it produces when called.

```typescript
import { isGeneratorFunction } from '@helpers4/guard';

isGeneratorFunction(value: unknown): value is GeneratorFunction
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is GeneratorFunction` — `true` if value is a GeneratorFunction

**Examples:**

*Detect a generator function*

Returns true for function* declarations and expressions.

```typescript
function* gen() { yield 1; }
isGeneratorFunction(gen)      // => true
isGeneratorFunction(gen())    // => false  (instance, not function)
isGeneratorFunction(() => {}) // => false
```

*Filter generator factories from a mixed array*

Use as a predicate to select only generator functions.

```typescript
const fns = [() => {}, function* () { yield 1; }, async () => {}];
fns.filter(isGeneratorFunction)
// => [function* () { yield 1; }]
```

---

### `isHostname`

Checks whether a value is a syntactically valid DNS hostname (RFC 952, RFC 1123, RFC 3696 section 2).

Rules:
- ASCII only: letters, digits and hyphens, case-insensitive.
- Labels are separated by dots and are 1 to 63 characters long. A label never starts or ends with a hyphen.
- The whole name is at most 253 characters (not counting an optional trailing dot).
- A single label is valid (`localhost`).
- The last label (the TLD) is never all digits (RFC 3696), so `192.168.0.1` and `123` are not hostnames.
  Other labels may be all digits.
- A trailing dot is refused unless `allowTrailingDot` is `true`.
- `_` is refused unless `allowUnderscore` is `true`; then it is accepted anywhere in a label, including
  at the start (`_dmarc`) and the end. The hyphen rules still apply.
- Unicode labels are refused. Punycode (`xn--...`) is ASCII and accepted. To check an internationalised
  name, convert it first with `new URL('https://' + name).hostname`.
- Whitespace, a port, a path or a scheme (`example.com:80`, `a/b`, `http://x`) make it invalid.

It only checks the syntax: it does not resolve the name and does not check that the TLD exists.
It never throws and runs in linear time.

```typescript
import { isHostname } from '@helpers4/guard';

isHostname(value: unknown, options: IsHostnameOptions): value is string
```

**Parameters:**

- `value: unknown` — The value to check
- `options: IsHostnameOptions` (default: `{}`) — Optional switches for the trailing dot and the underscore

**Returns:** `value is string` — `true` if value is a string that is a valid hostname

**Examples:**

*Validate a hostname typed by a user*

Accepts DNS hostnames and single labels; refuses IPv4 addresses, ports and schemes.

```typescript
isHostname('example.com')        // => true
isHostname('localhost')          // => true
isHostname('192.168.0.1')        // => false (numeric TLD)
isHostname('example.com:80')     // => false
isHostname('http://example.com') // => false
```

*Accept a trailing dot or an underscore on demand*

Fully qualified names and service names such as _dmarc are refused unless the option is set.

```typescript
isHostname('example.com.')                                  // => false
isHostname('example.com.', { allowTrailingDot: true })      // => true
isHostname('_dmarc.example.com')                            // => false
isHostname('_dmarc.example.com', { allowUnderscore: true }) // => true
```

*Check an internationalised name*

Unicode labels are refused; convert them to punycode with URL first.

```typescript
isHostname('bücher.example')                           // => false
isHostname(new URL('https://bücher.example').hostname) // => true
```

---

### `isIJson`

Checks whether a value is a string holding I-JSON (RFC 7493, the Internet JSON message
format): strict JSON that every JSON implementation reads the same way.

On top of strict JSON (see isJSON), I-JSON rejects what `JSON.parse` silently accepts
but loses or reads inconsistently:
- duplicate keys in an object (`JSON.parse` keeps the last one; other parsers don't)
- a string or key holding a lone surrogate (`"\uD800"`) or a Unicode noncharacter (`"\uFFFF"`)
- a number beyond the range of a double (`1e400`), more precise than a double holds (more than
  17 significant digits, or a non-zero value that rounds to `0`), or an integer outside
  +/-(2^53 - 1)

RFC 7493 also recommends (but doesn't require) an object or an array at the top level — this
guard accepts any value there.

```typescript
import { isIJson } from '@helpers4/guard';

isIJson(value: unknown): value is string
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is string` — `true` if `value` is a string holding I-JSON

**Examples:**

*Check an I-JSON message*

Strict JSON that every implementation reads the same way.

```typescript
isIJson('{"id":1,"name":"app"}') // => true
```

*Catch what JSON.parse silently loses*

JSON.parse keeps the last duplicate key and rounds big integers; I-JSON rejects both.

```typescript
isIJson('{"id":1,"id":2}')  // => false
isIJson('9007199254740993') // => false
```

---

### `isIterable`

Checks if a value is iterable (has a `Symbol.iterator` method).

Returns `true` for strings, arrays, Maps, Sets, generators, and any object
implementing the iterable protocol.

```typescript
import { isIterable } from '@helpers4/guard';

isIterable(value: unknown): value is Iterable<unknown, any, any>
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is Iterable<unknown, any, any>` — True if value is iterable

**Examples:**

*isIterable*

```typescript
```ts
isIterable([1, 2, 3])      // => true
isIterable('hello')        // => true
isIterable(new Map())      // => true
isIterable(new Set())      // => true
isIterable({})             // => false
isIterable(42)             // => false
```
```

---

### `isJSON`

Checks whether a value is a string containing valid, parseable JSON text.

Distinct from isJSONValue, which checks an already-parsed runtime value's *shape*
— this checks a *string* before you parse it. Pairs naturally with `@helpers4/json`'s
`safeParseStrict`, which is the safe-parse counterpart once you know the string is valid —
this helper reuses it internally rather than re-implementing the parse/catch itself.
For JSON with comments, see isJsonc; for one value per line, isNdjson; for
canonical JSON, isCanonicalJson.

```typescript
import { isJSON } from '@helpers4/guard';

isJSON(value: unknown): value is string
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is string` — `true` if value is a string and `JSON.parse` succeeds on it

**Examples:**

*Check a string before parsing it*

Validates that a string is parseable JSON before calling JSON.parse.

```typescript
isJSON('{"a":1}')
// => true
isJSON('not json')
// => false
```

---

### `isJson5`

Checks whether a value is a string holding valid JSON5 (JSON5 1.0.0) — JSON with comments,
trailing commas, unquoted keys, single-quoted strings, hexadecimal numbers, `Infinity`/`NaN`
and more.

JSON5 is a superset of JSONC, itself a superset of JSON, so this is `true` for everything
isJSON and isJsonc accept. It accepts exactly what `parse` from
`@helpers4/json` accepts — see there for the full list.

```typescript
import { isJson5 } from '@helpers4/guard';

isJson5(value: unknown): value is string
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is string` — `true` if `value` is a string holding JSON5

**Examples:**

*Check a JSON5 string*

Unquoted keys, single quotes, hexadecimal numbers and trailing commas are JSON5.

```typescript
isJson5("{ name: 'app', retries: 0x3, }") // => true
```

*Keys that are not identifiers need quotes*

A dash is not allowed in an unquoted key.

```typescript
isJson5('{ my-key: 1 }')   // => false
isJson5('{ "my-key": 1 }') // => true
```

---

### `isJSONArray`

Checks whether a value is an array whose every element is a valid JSON value
(see isJSONValue).

```typescript
import { isJSONArray } from '@helpers4/guard';

isJSONArray(value: unknown): value is unknown[]
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is unknown[]` — `true` if value is an array of JSON values

**Examples:**

*Validate a JSON array*

Checks that a value is an array whose every element is JSON-representable.

```typescript
isJSONArray([1, 'two', null])
// => true
isJSONArray([1, undefined])
// => false
```

---

### `isJsonc`

Checks whether a value is a string holding valid JSONC — JSON with comments and trailing
commas, the dialect of `tsconfig.json` and VS Code's `settings.json`, also known as HuJSON or
JWCC (JSON With Commas and Comments).

Strict JSON is valid JSONC too, so this is `true` for everything isJSON accepts, plus
line and block comments, trailing commas before `}` and `]`, and a leading byte order mark.
JSON5 syntax isn't JSONC — use isJson5 for that (`parse` from `@helpers4/json` reads
both).

```typescript
import { isJsonc } from '@helpers4/guard';

isJsonc(value: unknown): value is string
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is string` — `true` if `value` is a string holding JSON or JSONC

**Examples:**

*Check a JSONC string*

Comments and trailing commas are fine; strict JSON is too.

```typescript
isJsonc('{"a": 1, // note\n}') // => true
isJsonc('{"a": 1}')             // => true
```

*JSON5 is not JSONC*

Single quotes and unquoted keys are rejected.

```typescript
isJsonc("{'a': 1}") // => false
```

---

### `isJSONObject`

Checks whether a value is a plain object whose every own value is a valid JSON value
(see isJSONValue).

```typescript
import { isJSONObject } from '@helpers4/guard';

isJSONObject(value: unknown): value is Record<string, unknown>
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is Record<string, unknown>` — `true` if value is a plain object of JSON values

**Examples:**

*Validate a JSON object*

Checks that a value is a plain object whose every value is JSON-representable.

```typescript
isJSONObject({ a: 1, b: 'two' })
// => true
isJSONObject({ a: undefined })
// => false
```

---

### `isJsonSequence`

Checks whether a value is a string holding a valid JSON text sequence (RFC 7464,
`application/json-seq`): records that each start with the record separator (U+001E) and hold
one complete, strict JSON text.

It accepts exactly what `@helpers4/json`'s `parseSequence` accepts with its default options —
every record must be valid, including the RFC's check that a top-level number, `true`, `false`
or `null` is followed by whitespace. An empty string is valid: it holds zero records.

```typescript
import { isJsonSequence } from '@helpers4/guard';

isJsonSequence(value: unknown): value is string
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is string` — `true` if `value` is a string that `parseSequence` from `@helpers4/json` reads without error

**Examples:**

*Check a JSON text sequence*

Records framed by the record separator U+001E.

```typescript
isJsonSequence('\u001E{"id":1}\n') // => true
```

*Detect a truncated number*

RFC 7464 treats a top-level number without trailing whitespace as possibly truncated.

```typescript
isJsonSequence('\u001E12') // => false
```

---

### `isJSONValue`

Checks whether a value is composed entirely of JSON-representable types: `string`, finite
`number`, `boolean`, `null`, arrays of JSON values, or plain objects of JSON values.
`undefined`, functions, symbols, `NaN`/`Infinity`, and non-plain objects (`Date`, `Map`,
`Set`, class instances...) all return `false`, since none survive a real `JSON.stringify` /
`JSON.parse` round-trip unchanged. Circular references also return `false` for the same
reason, instead of recursing forever.

```typescript
import { isJSONValue } from '@helpers4/guard';

isJSONValue(value: unknown): boolean
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `boolean` — `true` if the value is a valid JSON value

**Examples:**

*Validate a value before sending it as JSON*

Recursively checks that a value only contains JSON-representable types.

```typescript
isJSONValue({ a: [1, 'two', null, { b: true }] })
// => true
isJSONValue({ a: new Date() })
// => false
```

---

### `isLength`

Checks whether a value is a valid array-like `length`: a non-negative safe integer
(`0 <= value <= Number.MAX_SAFE_INTEGER`).

```typescript
import { isLength } from '@helpers4/guard';

isLength(value: unknown): value is number
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is number` — `true` if value is a valid length

**Examples:**

*Validate an array-like length before indexing*

Guards against negative, fractional, or unsafe length values.

```typescript
isLength(3)   // => true
isLength(-1)  // => false
isLength(1.5) // => false
```

---

### `isMap`

Checks if a value is a Map instance.

```typescript
import { isMap } from '@helpers4/guard';

isMap(value: unknown): value is Map<unknown, unknown>
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is Map<unknown, unknown>` — True if value is a Map

**Examples:**

*isMap*

```typescript
```ts
isMap(new Map())           // => true
isMap(new Map([['a', 1]])) // => true
isMap({})                  // => false
```
```

---

### `isNdjson`

Checks whether a value is a string holding valid newline-delimited JSON — one strict JSON
value per line, as NDJSON and JSON Lines (`.jsonl`) both define it.

It accepts exactly what `@helpers4/json`'s `parseLines` accepts with its default options: blank
lines are tolerated (NDJSON allows them; JSON Lines doesn't), and an empty string is valid — it
holds zero values.

```typescript
import { isNdjson } from '@helpers4/guard';

isNdjson(value: unknown): value is string
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is string` — `true` if `value` is a string that `parseLines` from `@helpers4/json` reads without error

**Examples:**

*Check newline-delimited JSON*

One strict JSON value per line.

```typescript
isNdjson('{"id":1}\n{"id":2}\n') // => true
```

*A value cannot span lines*

Pretty-printed JSON is not NDJSON.

```typescript
isNdjson('{\n  "id": 1\n}') // => false
```

---

### `isNode`

Checks whether the code is currently running in a Node.js-like environment
(`process.versions.node` is defined — also true in Electron's Node context).

Note: some hybrid test environments (e.g. happy-dom, jsdom) define both `window` and Node's
`process` at the same time — this only reports on `process.versions.node`'s presence, it does
not imply `isBrowser` is false. Use both together if you need to distinguish plain Node.js
from a DOM-emulating Node test environment.

```typescript
import { isNode } from '@helpers4/guard';

isNode(): boolean
```

**Returns:** `boolean` — `true` if `process.versions.node` is defined

**Examples:**

*Branch on the runtime environment*

Useful for isomorphic code that behaves differently on the server vs. the browser.

```typescript
if (isNode()) {
  const fs = await import('node:fs')
  // server-side file access
}
```

---

### `isNull`

Checks if a value is `null`.

```typescript
import { isNull } from '@helpers4/guard';

isNull(value: unknown): value is null
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is null` — True if value is null

**Examples:**

*isNull*

```typescript
```ts
isNull(null)      // => true
isNull(undefined) // => false
isNull(0)         // => false
```
```

---

### `isNullish`

Checks if a value is null or undefined (nullish).

```typescript
import { isNullish } from '@helpers4/guard';

isNullish(value: unknown): value is null | undefined
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is null | undefined` — True if value is null or undefined

**Examples:**

*Check for null or undefined*

Returns true only for null and undefined, not other falsy values.

```typescript
isNullish(null)      // => true
isNullish(undefined) // => true
isNullish(0)         // => false
isNullish('')        // => false
```

*Guard before accessing properties*

Use as a type guard to safely narrow types.

```typescript
function greet(name: string | null | undefined): string {
  if (isNullish(name)) return 'Hello, stranger!';
  return `Hello, ${name}!`;
}
greet(null) // => 'Hello, stranger!'
```

---

### `isNumber`

Checks if a value is a number.

Returns `false` for `NaN`, which intentionally deviates from `typeof` behavior
to increase user-friendliness.

```typescript
import { isNumber } from '@helpers4/guard';

isNumber(value: unknown): value is number
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is number` — True if value is a number (excludes NaN)

**Examples:**

*isNumber*

```typescript
```ts
isNumber(42)    // => true
isNumber(0)     // => true
isNumber(NaN)   // => false
isNumber('123') // => false
```
```

---

### `isPlainObject`

Checks if a value is a plain object.

A plain object is created by `{}`, `new Object()`, or `Object.create(null)`.
Returns `false` for arrays, Date, Map, Set, RegExp, class instances, etc.

```typescript
import { isPlainObject } from '@helpers4/guard';

isPlainObject(value: unknown): value is Record<string, unknown>
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is Record<string, unknown>` — True if value is a plain object

**Examples:**

*isPlainObject*

```typescript
```ts
isPlainObject({})           // => true
isPlainObject({ a: 1 })    // => true
isPlainObject(new Date())  // => false
isPlainObject([])          // => false
isPlainObject(null)        // => false
```
```

---

### `isPrimitive`

Checks if a value is a JavaScript primitive.

Primitive types: `string`, `number`, `boolean`, `bigint`, `symbol`, `null`, `undefined`.

```typescript
import { isPrimitive } from '@helpers4/guard';

isPrimitive(value: unknown): value is Primitive
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is Primitive` — True if value is a primitive

**Examples:**

*isPrimitive*

```typescript
```ts
isPrimitive('hello')  // => true
isPrimitive(42)       // => true
isPrimitive(null)     // => true
isPrimitive({})       // => false
isPrimitive([])       // => false
```
```

---

### `isPromise`

Checks if a value is a Promise or a thenable.

Returns `true` for any object that has `.then()` and `.catch()` methods,
including native Promises and userland implementations.

```typescript
import { isPromise } from '@helpers4/guard';

isPromise(value: unknown): value is PromiseLike<unknown>
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is PromiseLike<unknown>` — True if value is a Promise-like object

**Examples:**

*isPromise*

```typescript
```ts
isPromise(Promise.resolve(42))     // => true
isPromise(new Promise(() => {}))   // => true
isPromise({ then: () => {} })      // => false (no .catch)
isPromise(42)                      // => false
```
```

---

### `isPromiseLike`

Checks if a value is a thenable (has a `.then()` method).

Looser than isPromise: accepts any object or function with a `then`
method, including non-standard Promise implementations without `.catch()`.
Follows the Promise/A+ specification for thenables.

```typescript
import { isPromiseLike } from '@helpers4/guard';

isPromiseLike(value: unknown): value is PromiseLike<unknown>
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is PromiseLike<unknown>` — `true` if value is a PromiseLike (thenable)

**Examples:**

*Detect any thenable*

Returns true for native Promises and any object with a .then() method.

```typescript
isPromiseLike(Promise.resolve(1))    // => true
isPromiseLike({ then: () => {} })    // => true   (thenable)
isPromiseLike(42)                    // => false
isPromiseLike(null)                  // => false
isPromiseLike({ then: 'not-a-fn' }) // => false
```

*Handle both Promises and thenables in a utility*

Use isPromiseLike to accept any thenable, not just native Promises.

```typescript
function toPromise<T>(value: T | PromiseLike<T>): Promise<T> {
  if (isPromiseLike(value)) return Promise.resolve(value);
  return Promise.resolve(value);
}
```

---

### `isPropertyKey`

Checks if a value is a valid property key: `string`, `number`, or `symbol`.

```typescript
import { isPropertyKey } from '@helpers4/guard';

isPropertyKey(value: unknown): value is PropertyKey
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is PropertyKey` — `true` if value can be used as an object property key

**Examples:**

*Detect valid property keys*

Strings, numbers, and symbols are valid property keys.

```typescript
isPropertyKey('name')        // => true
isPropertyKey(42)            // => true
isPropertyKey(Symbol('id'))  // => true
isPropertyKey(null)          // => false
isPropertyKey(true)          // => false
```

*Safe dynamic property access*

Use as a guard before indexing an object with an unknown key.

```typescript
function get(obj: Record<PropertyKey, unknown>, key: unknown): unknown {
  if (isPropertyKey(key)) return obj[key];
  return undefined;
}
get({ a: 1 }, 'a')    // => 1
get({ a: 1 }, null)   // => undefined
```

---

### `isRegExp`

Checks if a value is a RegExp instance.

```typescript
import { isRegExp } from '@helpers4/guard';

isRegExp(value: unknown): value is RegExp
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is RegExp` — True if value is a RegExp

**Examples:**

*isRegExp*

```typescript
```ts
isRegExp(/abc/)          // => true
isRegExp(new RegExp('a')) // => true
isRegExp('abc')          // => false
```
```

---

### `isSet`

Checks if a value is a Set instance.

```typescript
import { isSet } from '@helpers4/guard';

isSet(value: unknown): value is Set<unknown>
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is Set<unknown>` — True if value is a Set

**Examples:**

*Check whether a value is a Set*

Returns true only for real Set instances.

```typescript
isSet(new Set([1, 2, 3])) // => true
isSet([1, 2, 3])          // => false
```

*Type-safe narrowing in a conditional*

Inside the `if` branch, the value is narrowed to Set<unknown>.

```typescript
const value: unknown = new Set(['a', 'b']);
if (isSet(value)) {
  value.size // => 2, type-safe access
}
```

---

### `isSpecialObject`

Determines if a value is a special object that should not have its properties compared deeply.
Special objects include: Date, Function, Promise, Observable, RegExp, Error, Map, Set, WeakMap, WeakSet, etc.

```typescript
import { isSpecialObject } from '@helpers4/guard';

isSpecialObject(value: unknown): boolean
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `boolean` — `true` if the value is a special object, `false` otherwise

**Examples:**

*Detect special objects*

Returns true for built-in objects like Date, Map, Set, RegExp, etc.

```typescript
isSpecialObject(new Date())     // => true
isSpecialObject(new Map())      // => true
isSpecialObject(/regex/)        // => true
```

*Plain objects are not special*

Returns false for plain objects and arrays.

```typescript
isSpecialObject({ a: 1 })  // => false
isSpecialObject([1, 2])    // => false
```

---

### `isString`

Checks if a value is a string.

```typescript
import { isString } from '@helpers4/guard';

isString(value: unknown): value is string
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is string` — True if value is a string

**Examples:**

*isString*

```typescript
```ts
isString('hello') // => true
isString(123)     // => false
```
```

---

### `isSymbol`

Checks if a value is a symbol.

```typescript
import { isSymbol } from '@helpers4/guard';

isSymbol(value: unknown): value is symbol
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is symbol` — True if value is a symbol

**Examples:**

*isSymbol*

```typescript
```ts
isSymbol(Symbol('test')) // => true
isSymbol(Symbol.iterator) // => true
isSymbol('symbol')       // => false
```
```

---

### `isTemporalDuration`

Checks if a value is a `Temporal.Duration`.

Uses `instanceof` when `Temporal` is available globally, and falls back
to `Symbol.toStringTag` for environments without Temporal (e.g. browsers).

```typescript
import { isTemporalDuration } from '@helpers4/guard';

isTemporalDuration(value: unknown): value is Duration
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is Duration` — True if value is a `Temporal.Duration`

**Examples:**

*isTemporalDuration*

```typescript
```ts
isTemporalDuration(Temporal.Duration.from({ hours: 1 }))  // => true
isTemporalDuration(Temporal.Now.instant())                 // => false
isTemporalDuration(1000)                                   // => false
```
```

---

### `isTemporalInstant`

Checks if a value is a `Temporal.Instant`.

Uses `instanceof` when `Temporal` is available globally, and falls back
to `Symbol.toStringTag` for environments without Temporal (e.g. browsers).

```typescript
import { isTemporalInstant } from '@helpers4/guard';

isTemporalInstant(value: unknown): value is Instant
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is Instant` — True if value is a `Temporal.Instant`

**Examples:**

*isTemporalInstant*

```typescript
```ts
isTemporalInstant(Temporal.Now.instant())      // => true
isTemporalInstant(Temporal.Now.plainDateISO())  // => false
isTemporalInstant(new Date())                   // => false
```
```

---

### `isTemporalPlainDate`

Checks if a value is a `Temporal.PlainDate`.

Uses `instanceof` when `Temporal` is available globally, and falls back
to `Symbol.toStringTag` for environments without Temporal (e.g. browsers).

```typescript
import { isTemporalPlainDate } from '@helpers4/guard';

isTemporalPlainDate(value: unknown): value is PlainDate
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is PlainDate` — True if value is a `Temporal.PlainDate`

**Examples:**

*isTemporalPlainDate*

```typescript
```ts
isTemporalPlainDate(Temporal.PlainDate.from('2025-01-19'))  // => true
isTemporalPlainDate(Temporal.Now.instant())                 // => false
isTemporalPlainDate(new Date())                             // => false
```
```

---

### `isTemporalPlainDateTime`

Checks if a value is a `Temporal.PlainDateTime`.

Uses `instanceof` when `Temporal` is available globally, and falls back
to `Symbol.toStringTag` for environments without Temporal (e.g. browsers).

```typescript
import { isTemporalPlainDateTime } from '@helpers4/guard';

isTemporalPlainDateTime(value: unknown): value is PlainDateTime
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is PlainDateTime` — True if value is a `Temporal.PlainDateTime`

**Examples:**

*isTemporalPlainDateTime*

```typescript
```ts
isTemporalPlainDateTime(Temporal.PlainDateTime.from('2025-01-19T12:00'))  // => true
isTemporalPlainDateTime(Temporal.Now.instant())                           // => false
isTemporalPlainDateTime(new Date())                                       // => false
```
```

---

### `isTemporalPlainTime`

Checks if a value is a `Temporal.PlainTime`.

Uses `instanceof` when `Temporal` is available globally, and falls back
to `Symbol.toStringTag` for environments without Temporal (e.g. browsers).

```typescript
import { isTemporalPlainTime } from '@helpers4/guard';

isTemporalPlainTime(value: unknown): value is PlainTime
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is PlainTime` — True if value is a `Temporal.PlainTime`

**Examples:**

*isTemporalPlainTime*

```typescript
```ts
isTemporalPlainTime(Temporal.PlainTime.from('12:30:00'))  // => true
isTemporalPlainTime(Temporal.Now.instant())               // => false
isTemporalPlainTime(new Date())                           // => false
```
```

---

### `isTemporalZonedDateTime`

Checks if a value is a `Temporal.ZonedDateTime`.

Uses `instanceof` when `Temporal` is available globally, and falls back
to `Symbol.toStringTag` for environments without Temporal (e.g. browsers).

```typescript
import { isTemporalZonedDateTime } from '@helpers4/guard';

isTemporalZonedDateTime(value: unknown): value is ZonedDateTime
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is ZonedDateTime` — True if value is a `Temporal.ZonedDateTime`

**Examples:**

*isTemporalZonedDateTime*

```typescript
```ts
isTemporalZonedDateTime(Temporal.Now.zonedDateTimeISO())  // => true
isTemporalZonedDateTime(Temporal.Now.instant())           // => false
isTemporalZonedDateTime(new Date())                       // => false
```
```

---

### `isTimestamp`

Checks if a value is a valid timestamp (milliseconds or Unix seconds).

Supports:
- JavaScript / Java timestamps (milliseconds since epoch)
- Unix timestamps (seconds since epoch)

The function uses a heuristic to distinguish between the two:
numbers ≤ ~7.26 billion are treated as seconds, larger as milliseconds.

```typescript
import { isTimestamp } from '@helpers4/guard';

isTimestamp(value: unknown): value is number
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is number` — True if value is a number that represents a valid timestamp

**Examples:**

*isTimestamp*

```typescript
```ts
isTimestamp(1609459200000) // => true (JS ms — 2021-01-01)
isTimestamp(1609459200)    // => true (Unix seconds — 2021-01-01)
isTimestamp(Date.now())    // => true
isTimestamp(NaN)           // => false
isTimestamp('1609459200')  // => false (not a number)
```
```

---

### `isTruthy`

Checks if a value is truthy (not `false`, `null`, `undefined`, `0`, `""`, or `NaN`).

This is the type-safe alternative to `Boolean()` as a filter callback.
Unlike `filter(Boolean)`, using `filter(isTruthy)` correctly narrows the
resulting array type by excluding falsy values.

```typescript
import { isTruthy } from '@helpers4/guard';

isTruthy<T>(value: Falsy | T): value is T
```

**Parameters:**

- `value: Falsy | T` — The value to check

**Returns:** `value is T` — True if the value is truthy

**Examples:**

*Check truthy values*

Returns true for all truthy values, false for falsy ones.

```typescript
isTruthy(1)         // => true
isTruthy('hello')   // => true
isTruthy(0)         // => false
isTruthy(null)      // => false
```

*Type-safe filter alternative to Boolean*

Use isTruthy with Array.filter to get correct TypeScript narrowing.

```typescript
const items = ['a', '', null, 'b', undefined];
const result = items.filter(isTruthy);
// => ['a', 'b'] with type string[]
```

---

### `isUndefined`

Checks if a value is `undefined`.

```typescript
import { isUndefined } from '@helpers4/guard';

isUndefined(value: unknown): value is undefined
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is undefined` — True if value is undefined

**Examples:**

*isUndefined*

```typescript
```ts
isUndefined(undefined) // => true
isUndefined(null)      // => false
isUndefined(0)         // => false
```
```

---

### `isValidRegex`

Checks if a string is a valid regex pattern.

```typescript
import { isValidRegex } from '@helpers4/guard';

isValidRegex(value: string): boolean
```

**Parameters:**

- `value: string` — The string to check

**Returns:** `boolean` — True if the string is a valid regex pattern

**Examples:**

*isValidRegex*

```typescript
```ts
isValidRegex('[a-z]+') // => true
isValidRegex('.*')     // => true
isValidRegex('[')      // => false
```
```

---

### `isWeakMap`

Checks if a value is a WeakMap instance.

```typescript
import { isWeakMap } from '@helpers4/guard';

isWeakMap(value: unknown): value is WeakMap<object, unknown>
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is WeakMap<object, unknown>` — True if value is a WeakMap

**Examples:**

*Check whether a value is a WeakMap*

Distinguishes WeakMap from the regular (iterable) Map.

```typescript
isWeakMap(new WeakMap()) // => true
isWeakMap(new Map())     // => false
```

*Plain objects are not WeakMaps*

Only real WeakMap instances pass, not objects that merely look like one.

```typescript
isWeakMap({ get: () => undefined, set: () => {} })
// => false
```

---

### `isWeakMapKey`

Checks whether a value can be used as a key in a `WeakMap` (or a `WeakSet` member / `WeakRef`
target) — an object, a function (despite `typeof` reporting `'function'`, functions are
objects), or an *unregistered* symbol (a plain `Symbol(...)` or a well-known symbol like
`Symbol.iterator`).

Symbols registered via `Symbol.for(...)` are excluded: since they live forever in the global
symbol registry, the language disallows them as weak references (ES2023's "Symbols as
WeakMap keys"). This is the part of the check easy to get wrong — `typeof value === 'symbol'`
alone accepts registered symbols too, which actually throw at `WeakMap.prototype.set`.

```typescript
import { isWeakMapKey } from '@helpers4/guard';

isWeakMapKey(value: unknown): value is symbol | object
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is symbol | object` — `true` if `value` is a valid `WeakMap`/`WeakSet` key or `WeakRef` target

**Examples:**

*Objects and functions are valid WeakMap keys*

Functions pass despite typeof reporting "function" — they are objects.

```typescript
isWeakMapKey({})       // => true
isWeakMapKey(() => {}) // => true
isWeakMapKey(42)       // => false
```

*Unregistered symbols pass, registered ones do not*

Symbol.for(...) symbols live forever in the global registry, so the language disallows them as weak references.

```typescript
isWeakMapKey(Symbol('x'))     // => true
isWeakMapKey(Symbol.for('x')) // => false
```

---

### `isWeakSet`

Checks if a value is a WeakSet instance.

```typescript
import { isWeakSet } from '@helpers4/guard';

isWeakSet(value: unknown): value is WeakSet<object>
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is WeakSet<object>` — True if value is a WeakSet

**Examples:**

*Check whether a value is a WeakSet*

Distinguishes WeakSet from the regular (iterable) Set.

```typescript
isWeakSet(new WeakSet()) // => true
isWeakSet(new Set())     // => false
```

*Arrays are not WeakSets*

Only real WeakSet instances pass.

```typescript
isWeakSet([1, 2, 3])
// => false
```

---

## id

Package: `@helpers4/id`

### `uuid7`

Generates a UUID v7 string (RFC 9562).
UUID v7 embeds a Unix timestamp in milliseconds, making it
chronologically sortable while retaining randomness.

```typescript
import { uuid7 } from '@helpers4/id';

uuid7(): string
```

**Returns:** `string` — A UUID v7 string in the format `xxxxxxxx-xxxx-7xxx-yxxx-xxxxxxxxxxxx`

**Examples:**

*Generate a UUID v7*

Produces a RFC 9562 UUID v7 string with an embedded millisecond timestamp.

```typescript
uuid7()
// => "019077e0-5c70-7b3a-8a1f-3e4d5b6c7d8e"
```

*UUIDs are chronologically sortable*

UUID v7 values generated later are lexicographically greater, making them ideal for database primary keys.

```typescript
const id1 = uuid7();
// ... later ...
const id2 = uuid7();
id1 < id2 // => true
```

*Each UUID is unique*

No two calls produce the same value.

```typescript
uuid7() !== uuid7() // => true
```

---

## json

Package: `@helpers4/json`

### `parse`

Parses JSON permissively: strict JSON, JSONC (the dialect of `tsconfig.json` and VS Code's
`settings.json`, also known as HuJSON or JWCC) and JSON5 — each a superset of the one before.

**Accepts:**
- everything parseStrict accepts (strict JSON, RFC 8259)
- comments: `// …` to the end of the line, and `/* … */`
- one trailing comma after the last item of an object or array
- object keys without quotes, when they are ECMAScript identifiers (`{ name: 1 }`, `{ $id: 1 }`)
- strings in single quotes, and in either quote: the escapes `\'`, `\v`, `\0` and `\xHH`, any
  other escaped character standing for itself, and a backslash before a line break to continue
  the string on the next line
- numbers with a leading `+`, a leading or trailing dot (`.5`, `5.`), in hexadecimal (`0x1F`),
  and `Infinity`, `-Infinity` and `NaN`
- any Unicode whitespace between tokens, including a leading byte order mark (U+FEFF)

**Rejects:** more than one trailing comma in a row, leading zeros (`01`), octal or binary
numbers, unquoted keys that aren't identifiers (`{ my-key: 1 }`), raw line breaks inside a
string, an unterminated comment or string, `undefined`, and more than one value.

**On invalid input:** throws a `SyntaxError` naming the line and column of the first problem.

Strict JSON goes straight to the native `JSON.parse`, and JSONC to `JSON.parse` after its
comments are blanked out; only text that is neither goes through the JSON5 reader (written for
helpers4 from the JSON5 1.0.0 specification), so the common cases cost nothing extra.

Values are built as `JSON.parse` builds them: the last of duplicate keys wins, and a
`__proto__` key is an own property, never the prototype. `NaN` and `Infinity` have no JSON
representation — stringify writes them as `null`.

```typescript
import { parse } from '@helpers4/json';

parse<T = unknown>(text: string): T
```

**Parameters:**

- `text: string` — The JSON, JSONC or JSON5 text to parse

**Returns:** `T` — The parsed value, typed as `T`

**Examples:**

*Parse a config file with comments*

Reads JSONC — the tsconfig.json / settings.json dialect — as well as strict JSON.

```typescript
parse(`{
  // where the build goes
  "outDir": "dist",
}`)
// => { outDir: 'dist' }
```

*Invalid input throws*

The SyntaxError names the line and column of the problem.

```typescript
parse('{ my-key: 1 }')
// throws SyntaxError: a key with a dash needs quotes
```

*Parse JSON5*

Unquoted keys, single quotes, hexadecimal and leading-dot numbers, trailing commas.

```typescript
parse("{ name: 'app', retries: 0x3, ratio: .5, }")
// => { name: 'app', retries: 3, ratio: 0.5 }
```

---

### `parseLines`

Parses newline-delimited JSON — one JSON value per line. Covers both NDJSON
(`application/x-ndjson`, `.ndjson`) and JSON Lines (`.jsonl`), which are the same format.

**Accepts:**
- one strict JSON value per line (each line is read like parseStrict)
- `\n` and `\r\n` line endings
- a trailing line break after the last value, or none
- blank lines, skipped by default (see ParseLinesOptions.blankLines)
- an empty text, which holds zero values

**Rejects:** comments, trailing commas and any other non-strict JSON on a line, a value spread
over several lines, and a leading byte order mark (JSON Lines forbids it).

**On invalid input:** throws a `SyntaxError` naming the 1-based line number, with the
original parse error as its `cause` — unless `invalidLines`/`blankLines` say to skip it.

```typescript
import { parseLines } from '@helpers4/json';

parseLines<T = unknown>(text: string, options: ParseLinesOptions): T[]
```

**Parameters:**

- `text: string` — The newline-delimited JSON text
- `options: ParseLinesOptions` (default: `{}`) — How to handle blank and invalid lines — see ParseLinesOptions

**Returns:** `T[]` — The parsed values, in line order, typed as `T[]`

**Examples:**

*Read NDJSON / JSON Lines*

One JSON value per line; a trailing line break is optional.

```typescript
parseLines('{"id":1}\n{"id":2}\n')
// => [{ id: 1 }, { id: 2 }]
```

*Skip a truncated last line*

With invalidLines: "skip", a line cut by a crash is dropped instead of failing the whole parse.

```typescript
parseLines('{"id":1}\n{"id":', { invalidLines: 'skip' })
// => [{ id: 1 }]
```

*Fail on an invalid line by default*

The SyntaxError names the line.

```typescript
parseLines('1\n{\n3')
// throws SyntaxError: parseLines: line 2: ...
```

---

### `parseSequence`

Parses a JSON text sequence (RFC 7464, `application/json-seq`): records that each start with
the ASCII record separator (RS, U+001E) and hold one JSON text, as written by `jq --seq`.

**Accepts:**
- one strict JSON value per record (each record is read like parseStrict)
- JSON values spread over several lines inside a record — unlike parseLines
- several RS in a row (empty records are ignored, as the RFC's grammar allows)
- an empty text, which holds zero records

**Rejects (as invalid records):**
- anything before the first RS
- a record that isn't strict JSON, or holds only whitespace
- a top-level number, `true`, `false` or `null` not followed by whitespace — RFC 7464 §2.4
  requires dropping it, since it may have been truncated

**On invalid input:** throws a `SyntaxError` naming the 1-based record number, with the
original parse error (if any) as its `cause` — unless `invalidRecords: 'skip'` says to drop it.

```typescript
import { parseSequence } from '@helpers4/json';

parseSequence<T = unknown>(text: string, options: ParseSequenceOptions): T[]
```

**Parameters:**

- `text: string` — The JSON text sequence
- `options: ParseSequenceOptions` (default: `{}`) — How to handle invalid records — see ParseSequenceOptions

**Returns:** `T[]` — The parsed values, in record order, typed as `T[]`

**Examples:**

*Read a JSON text sequence*

Each record starts with the record separator U+001E, as jq --seq writes it.

```typescript
parseSequence('\u001E{"id":1}\n\u001E{"id":2}\n')
// => [{ id: 1 }, { id: 2 }]
```

*Recover from a truncated log*

RFC 7464 recommends skipping invalid records; ask for it with invalidRecords: "skip".

```typescript
parseSequence('\u001E{"id":1}\n\u001E{"id', { invalidRecords: 'skip' })
// => [{ id: 1 }]
```

---

### `parseStrict`

Parses strict JSON (RFC 8259) — exactly what `JSON.parse` accepts, nothing more.

**Accepts:** standard JSON only — double-quoted strings and keys, finite decimal numbers,
`true`/`false`/`null`, objects and arrays, surrounding whitespace.

**Rejects:** comments, trailing commas, single quotes, unquoted keys, hexadecimal numbers,
`NaN`/`Infinity`, a leading byte order mark (U+FEFF), and anything else that isn't strict JSON.

**On invalid input:** throws the native `SyntaxError` from `JSON.parse`.

Use it to validate input that must be strict JSON, e.g. an API payload. To also read config
files with comments or JSON5, use parse. To never throw, use safeParseStrict.

```typescript
import { parseStrict } from '@helpers4/json';

parseStrict<T = unknown>(text: string): T
```

**Parameters:**

- `text: string` — The JSON text to parse

**Returns:** `T` — The parsed value, typed as `T`

**Examples:**

*Parse strict JSON*

Exactly what JSON.parse accepts, typed with a generic.

```typescript
parseStrict<{ id: number }>('{"id":1}')
// => { id: 1 }
```

*Reject anything that is not strict JSON*

Comments and trailing commas throw a SyntaxError: use it to validate an API payload.

```typescript
parseStrict('{"id":1,}')
// throws SyntaxError
```

---

### `safeParse`

Parses JSON permissively like parse — strict JSON, JSONC (HuJSON, JWCC) and JSON5 —
but returns `null` (or `fallback`) instead of throwing on invalid input.

**Accepts / rejects:** exactly what parse does — see there for the full list.

**On invalid input:** returns `fallback` when one is given — even `undefined`, which is told
apart from an omitted argument — and `null` otherwise. Never throws.

```typescript
import { safeParse } from '@helpers4/json';

safeParse<T = unknown>(text: string): T | null
```

**Parameters:**

- `text: string` — The JSON, JSONC or JSON5 text to parse

**Returns:** `T | null` — The parsed value typed as `T`, or `null` on invalid input (pass a `fallback` to get it instead)

```typescript
import { safeParse } from '@helpers4/json';

safeParse<T = unknown, F = T>(text: string, fallback: F): T | F
```

**Parameters:**

- `text: string` — The JSON, JSONC or JSON5 text to parse
- `fallback: F` — Value returned on invalid input

**Returns:** `T | F` — The parsed value typed as `T`, or `fallback` on invalid input

**Examples:**

*Read JSONC or JSON5 without throwing*

Same parsing as parse, but returns null on invalid input.

```typescript
safeParse('{"a": 1, /* note */}') // => { a: 1 }
safeParse('{a: }')                // => null
```

*Fall back to defaults*

Pass a fallback to get a usable value even when the file is broken.

```typescript
safeParse('{ broken', {})
// => {}
```

---

### `safeParseLines`

Parses newline-delimited JSON (NDJSON, JSON Lines) like parseLines, but returns `null`
(or `fallback`) instead of throwing on invalid input.

**Accepts / rejects:** exactly what parseLines does, with the same
ParseLinesOptions.

**On invalid input:** returns `fallback` when one is given — even `undefined`, which is told
apart from an omitted argument — and `null` otherwise. Never throws. To pass `options` without
a fallback, pass `null` as the fallback.

```typescript
import { safeParseLines } from '@helpers4/json';

safeParseLines<T = unknown>(text: string): T[] | null
```

**Parameters:**

- `text: string` — The newline-delimited JSON text

**Returns:** `T[] | null` — The parsed values typed as `T[]`, or `null` on invalid input (pass a `fallback` to get it instead)

```typescript
import { safeParseLines } from '@helpers4/json';

safeParseLines<T = unknown, F = T[]>(text: string, fallback: F, options?: ParseLinesOptions): F | T[]
```

**Parameters:**

- `text: string` — The newline-delimited JSON text
- `fallback: F` — Value returned on invalid input
- `options?: ParseLinesOptions` — How to handle blank and invalid lines — see ParseLinesOptions

**Returns:** `F | T[]` — The parsed values typed as `T[]`, or `fallback` on invalid input

**Examples:**

*Read NDJSON without throwing*

Returns null if any line is invalid.

```typescript
safeParseLines('1\n2\n') // => [1, 2]
safeParseLines('1\n{')   // => null
```

*Options without a fallback*

Pass null as the fallback to give options.

```typescript
safeParseLines('1\n\n2', null, { blankLines: 'fail' })
// => null (JSON Lines forbids blank lines)
```

---

### `safeParseSequence`

Parses a JSON text sequence (RFC 7464) like parseSequence, but returns `null` (or
`fallback`) instead of throwing on invalid input.

**Accepts / rejects:** exactly what parseSequence does, with the same
ParseSequenceOptions.

**On invalid input:** returns `fallback` when one is given — even `undefined`, which is told
apart from an omitted argument — and `null` otherwise. Never throws. To pass `options` without
a fallback, pass `null` as the fallback.

```typescript
import { safeParseSequence } from '@helpers4/json';

safeParseSequence<T = unknown>(text: string): T[] | null
```

**Parameters:**

- `text: string` — The JSON text sequence

**Returns:** `T[] | null` — The parsed values typed as `T[]`, or `null` on invalid input (pass a `fallback` to get it instead)

```typescript
import { safeParseSequence } from '@helpers4/json';

safeParseSequence<T = unknown, F = T[]>(text: string, fallback: F, options?: ParseSequenceOptions): F | T[]
```

**Parameters:**

- `text: string` — The JSON text sequence
- `fallback: F` — Value returned on invalid input
- `options?: ParseSequenceOptions` — How to handle invalid records — see ParseSequenceOptions

**Returns:** `F | T[]` — The parsed values typed as `T[]`, or `fallback` on invalid input

**Examples:**

*Read a sequence without throwing*

Returns null if any record is invalid.

```typescript
safeParseSequence('\u001E1\n') // => [1]
safeParseSequence('\u001E{\n') // => null
```

*Provide a fallback*

The fallback is returned on invalid input.

```typescript
safeParseSequence('\u001E{\n', [])
// => []
```

---

### `safeParseStrict`

Parses strict JSON like parseStrict, but returns `null` (or `fallback`) instead of
throwing on invalid input.

**Accepts / rejects:** exactly what parseStrict does — standard JSON only, no comments,
no trailing commas, no JSON5 syntax, no leading byte order mark.

**On invalid input:** returns `fallback` when one is given — even `undefined`, which is told
apart from an omitted argument — and `null` otherwise. Never throws.

```typescript
import { safeParseStrict } from '@helpers4/json';

safeParseStrict<T = unknown>(text: string): T | null
```

**Parameters:**

- `text: string` — The JSON text to parse

**Returns:** `T | null` — The parsed value typed as `T`, or `null` on invalid input (pass a `fallback` to get it instead)

```typescript
import { safeParseStrict } from '@helpers4/json';

safeParseStrict<T = unknown, F = T>(text: string, fallback: F): T | F
```

**Parameters:**

- `text: string` — The JSON text to parse
- `fallback: F` — Value returned on invalid input

**Returns:** `T | F` — The parsed value typed as `T`, or `fallback` on invalid input

**Examples:**

*Parse without throwing*

Returns null instead of throwing on invalid input.

```typescript
safeParseStrict('{"id":1}')  // => { id: 1 }
safeParseStrict('{"id":1,}') // => null
```

*Provide a fallback*

The fallback is returned on invalid input, so the result is never null.

```typescript
safeParseStrict('oops', { id: 0 })
// => { id: 0 }
```

---

### `stringify`

Serializes a value to JSON text — pretty-printed with 2 spaces by default, or canonical.

**Formatting:**
- default — indented with 2 spaces, like a hand-written config file
- `{ indent: n }` — indented with `n` spaces (an integer from 0 to 10); `{ indent: 0 }` gives a
  compact single line, the same as `JSON.stringify(value)`
- `'canonical'` — canonical JSON (RFC 8785, JSON Canonicalization Scheme): object keys sorted
  by UTF-16 code units, no whitespace at all, numbers in their shortest ECMAScript form. Two
  equal values always give the same bytes, so the output can be hashed, signed or compared.
  Canonical output can't be indented — the RFC fixes every byte.

**Same as `JSON.stringify`:** `toJSON()` is called (a `Date` becomes its ISO string),
`undefined`, functions and symbols are dropped from objects and become `null` in arrays, and
`Number`/`String`/`Boolean` objects are unwrapped. Outside `'canonical'`, `NaN` and `±Infinity`
silently become `null`, as there.

**Throws** instead of returning `undefined` or dropping data silently:
- a `TypeError` when `value` itself is `undefined`, a function or a symbol
- a `TypeError` on a circular structure or a `BigInt` (like `JSON.stringify`)
- with `'canonical'`, a `RangeError` on `NaN`, `±Infinity` or a string with a lone surrogate,
  which canonical JSON can't hold
- a `RangeError` when `indent` isn't an integer from 0 to 10

The output is strict JSON, so it is also valid JSONC and JSON5.

```typescript
import { stringify } from '@helpers4/json';

stringify(value: unknown, formatting: StringifyFormatting): string
```

**Parameters:**

- `value: unknown` — The value to serialize
- `formatting: StringifyFormatting` (default: `{}`) — `{ indent }` (default `{ indent: 2 }`) or `'canonical'` — see StringifyFormatting

**Returns:** `string` — The JSON text

**Examples:**

*Pretty-print by default*

Indented with 2 spaces, like a hand-written config file.

```typescript
stringify({ name: 'app', tags: ['a'] })
// => '{\n  "name": "app",\n  "tags": [\n    "a"\n  ]\n}'
```

*Compact output*

indent: 0 gives a single line, like JSON.stringify(value).

```typescript
stringify({ b: 1, a: 2 }, { indent: 0 })
// => '{"b":1,"a":2}'
```

*Canonical JSON (RFC 8785)*

Sorted keys and no whitespace: equal values always give the same bytes, ready to hash or sign.

```typescript
stringify({ b: 1, a: 2 }, 'canonical')
// => '{"a":2,"b":1}'
```

---

### `stringifyForHtml`

Serializes a value to compact JSON that is safe to inline in an HTML page, typically in a
`<script type="application/json">` block or a script assignment.

`<`, `>` and `&` are written as `\u003c`, `\u003e` and `\u0026`, so the text can never close
the script element (`</script>`), open a comment (`<!--`) or be read as an entity. U+2028 and
U+2029, valid in JSON but line terminators in some script contexts, are escaped too. These
characters can only appear inside JSON strings, so the escaped text parses back to exactly the
same value with `JSON.parse`.

It throws like stringify does (a `TypeError` for `undefined`, a function, a symbol, a
`BigInt` or a circular structure).

```typescript
import { stringifyForHtml } from '@helpers4/json';

stringifyForHtml(value: unknown): string
```

**Parameters:**

- `value: unknown` — The value to serialize

**Returns:** `string` — Compact JSON text with no raw `<`, `>`, `&`, U+2028 or U+2029

**Examples:**

*Inline data in a script block*

A value containing </script> can no longer close the element it is embedded in.

```typescript
stringifyForHtml({ note: '</script><b>' })
// => '{"note":"\\u003c/script\\u003e\\u003cb\\u003e"}'
```

*Same value after parsing*

The escapes are plain JSON escapes: JSON.parse gives back the original value.

```typescript
JSON.parse(stringifyForHtml({ a: '<&>' })).a
// => '<&>'
```

---

### `stringifyLines`

Serializes values as newline-delimited JSON — one compact JSON value per line, each followed
by `\n`. The output is both NDJSON and JSON Lines (`.jsonl`), which are the same format.

**Formatting:**
- default — each value compact, like `JSON.stringify(value)`
- `'canonical'` — each value as canonical JSON (RFC 8785): sorted keys, reproducible bytes, for
  hashing or diffing logs line by line

Indentation isn't available: a line break inside a value would split it across lines. String
values can't break a line either — `JSON.stringify` escapes `\n` and `\r` inside them.

**Output:** every value is followed by `\n`, including the last one (NDJSON requires it, and
JSON Lines recommends it, so files can be concatenated). An empty array gives `''`.

**Throws** a `TypeError` when `values` isn't an array, or when one of them has no JSON
representation (`undefined`, a function, a symbol, a `BigInt`, a circular structure) — rather
than writing a line that would read back as something else. With `'canonical'`, also a
`RangeError` on `NaN`, `±Infinity` or a lone surrogate (see stringify).

```typescript
import { stringifyLines } from '@helpers4/json';

stringifyLines(values: readonly unknown[], formatting?: "canonical"): string
```

**Parameters:**

- `values: readonly unknown[]` — The values to write, one per line
- `formatting?: "canonical"` — `'canonical'` for canonical JSON lines; compact JSON by default

**Returns:** `string` — The newline-delimited JSON text

**Examples:**

*Write NDJSON / JSON Lines*

One compact value per line, each followed by a line break.

```typescript
stringifyLines([{ id: 1 }, { id: 2 }])
// => '{"id":1}\n{"id":2}\n'
```

*Canonical lines*

Each line in canonical form, so a log can be hashed or diffed line by line.

```typescript
stringifyLines([{ b: 1, a: 2 }], 'canonical')
// => '{"a":2,"b":1}\n'
```

---

### `stringifySequence`

Serializes values as a JSON text sequence (RFC 7464, `application/json-seq`): each value is
written as the ASCII record separator (RS, U+001E), the compact JSON text, then `\n` — the
exact framing the RFC requires of encoders, as `jq --seq` writes it.

**Formatting:**
- default — each value compact, like `JSON.stringify(value)`
- `'canonical'` — each value as canonical JSON (RFC 8785): sorted keys, reproducible bytes

Indentation isn't offered, for symmetry with stringifyLines: the trailing `\n` is what
lets a reader detect a truncated top-level number, `true`, `false` or `null` (RFC 7464 §2.4).

**Output:** an empty array gives `''`.

**Throws** a `TypeError` when `values` isn't an array, or when one of them has no JSON
representation (`undefined`, a function, a symbol, a `BigInt`, a circular structure). With
`'canonical'`, also a `RangeError` on `NaN`, `±Infinity` or a lone surrogate (see
stringify).

```typescript
import { stringifySequence } from '@helpers4/json';

stringifySequence(values: readonly unknown[], formatting?: "canonical"): string
```

**Parameters:**

- `values: readonly unknown[]` — The values to write, one per record
- `formatting?: "canonical"` — `'canonical'` for canonical JSON records; compact JSON by default

**Returns:** `string` — The JSON text sequence

**Examples:**

*Write a JSON text sequence*

Each value is framed as RS, JSON text, line feed (RFC 7464).

```typescript
stringifySequence([{ id: 1 }, 2])
// => '\u001E{"id":1}\n\u001E2\n'
```

*Canonical records*

Each record in canonical form.

```typescript
stringifySequence([{ b: 1, a: 2 }], 'canonical')
// => '\u001E{"a":2,"b":1}\n'
```

---

## license

Package: `@helpers4/license`

### `agree`

Whether two raw license strings agree closely enough to count as "no real conflict" — true
when their family sets share at least one real (known) family, or when either side is entirely
unknown (e.g. `"custom"`/`"unknown"`) — a vague claim is never itself evidence of disagreement.
Only two *different*, both-known family sets (e.g. `bsd` vs `apache`) count as a real conflict.

```typescript
import { agree } from '@helpers4/license';

agree(a: string, b: string): boolean
```

**Parameters:**

- `a: string` — The first raw license string
- `b: string` — The second raw license string

**Returns:** `boolean` — `true` when the two strings can be treated as the same license (or too vague to tell), `false` on a real family conflict

**Examples:**

*Reconcile notation drift across sources*

Two package sources reporting the same real license under different notation.

```typescript
agree('GPL3', 'GPL-3.0-or-later')
// => true
```

*Flag a real license conflict*

Two sources genuinely disagreeing on the license family — a real data-quality signal.

```typescript
agree('BSD-2-Clause', 'Apache-2.0')
// => false
```

*A vague claim is never itself a conflict*

When either side is non-informative ("custom", "unknown", ...), there is nothing real to disagree with.

```typescript
agree('custom', 'MIT')
// => true
```

---

### `families`

Groups a raw, possibly compound license string into its coarse family set — e.g.
`"GPL-3.0-or-later AND LGPL-3.0-or-later"` yields `{"gpl", "lgpl"}`. Two sources reporting the
same real license under different notation (`"GPL3"` vs `"GPL-3.0-or-later"`, `"GPL"` vs
`"GPL2"`) yield the same family, so they read as agreeing rather than conflicting.

Proprietary/custom/unknown tokens all collapse to a single shared unknown-family sentinel
rather than each becoming their own one-off family, so a batch of otherwise-identical
`"custom:<vendor>"` strings don't look like dozens of distinct disagreeing licenses. Use
isKnown to check whether any real (non-sentinel) family was found.

```typescript
import { families } from '@helpers4/license';

families(raw: string): Set<string>
```

**Parameters:**

- `raw: string` — A raw license string, single (`"MIT"`) or compound (`"GPL-3.0+ AND LGPL-3.0+"`)

**Returns:** `Set<string>` — The set of families found; empty only when `raw` has no tokens at all (e.g. an empty string)

**Examples:**

*Collapse notation drift into one family*

"GPL3" and "GPL-3.0-or-later" are the same real license, reported differently by two sources.

```typescript
families('GPL3')
// => Set(1) { 'gpl' }
```

*Split a compound SPDX expression*

"AND"/"OR" (any case) separate multiple license claims; "WITH" exception clauses are dropped.

```typescript
families('GPL-3.0-or-later AND LGPL-3.0-or-later')
// => Set(2) { 'gpl', 'lgpl' }
```

*Non-informative claims collapse to one shared "unknown" family*

A batch of different custom:<vendor> strings all read the same way — none of them is real evidence either way.

```typescript
families('custom:Acme End User License')
// => Set(1) { 'unknown' }
```

---

### `isKnown`

Whether a raw license string resolves to at least one recognized family — `false` for an
empty string, a purely non-informative claim (`"custom"`, `"unknown"`, `"LicenseRef-EULA"`,
...), or a compound expression where every token is non-informative.

```typescript
import { isKnown } from '@helpers4/license';

isKnown(raw: string): boolean
```

**Parameters:**

- `raw: string` — The raw license string to check

**Returns:** `boolean` — `true` if at least one token in `raw` resolves to a real family

**Examples:**

*Filter out entries with no real license information*

Handy for flagging catalog entries whose license field is not actually usable.

```typescript
['MIT', 'custom:Acme EULA', 'unknown'].filter(isKnown)
// => ['MIT']
```

*A vendor-specific EULA is not a recognized family*

"custom:<vendor>" names the vendor's own license text, not a known open-source family.

```typescript
isKnown('custom:Acme End User License')
// => false
```

---

## map

Package: `@helpers4/map`

### `countBy`

Groups the entries of a Map by a derived key and counts how many fall into each group.

```typescript
import { countBy } from '@helpers4/map';

countBy<K, V, R>(map: ReadonlyMap<K, V>, fn: function): Map<R, number>
```

**Parameters:**

- `map: ReadonlyMap<K, V>` — The Map to summarize
- `fn: function` — Function deriving the grouping key from (value, key)

**Returns:** `Map<R, number>` — A Map from derived key to the number of entries in that group

**Examples:**

*Count entries by parity*

Groups values by a derived key and counts how many fall into each group.

```typescript
countBy(new Map([['a', 1], ['b', 2], ['c', 3], ['d', 4]]), v => v % 2 === 0 ? 'even' : 'odd')
// => Map(2) { 'odd' => 2, 'even' => 2 }
```

---

### `every`

Checks if every entry of a Map satisfies the predicate. Short-circuits on the first mismatch.

```typescript
import { every } from '@helpers4/map';

every<K, V>(map: ReadonlyMap<K, V>, predicate: function): boolean
```

**Parameters:**

- `map: ReadonlyMap<K, V>` — The Map to check
- `predicate: function` — Function invoked with (value, key)

**Returns:** `boolean` — `true` if all entries match (vacuously `true` for an empty map), `false` otherwise

**Examples:**

*Check that all values are positive*

Returns false as soon as one entry fails the predicate.

```typescript
every(new Map([['a', 1], ['b', 2]]), value => value > 0)
// => true
```

*Empty map*

Vacuously true for an empty map.

```typescript
every(new Map(), () => false)
// => true
```

---

### `filter`

Creates a new Map containing only the entries for which the predicate returns true.

```typescript
import { filter } from '@helpers4/map';

filter<K, V>(map: ReadonlyMap<K, V>, predicate: function): Map<K, V>
```

**Parameters:**

- `map: ReadonlyMap<K, V>` — The Map to filter
- `predicate: function` — Function invoked with (value, key) — return true to keep the entry

**Returns:** `Map<K, V>` — A new Map with only the matching entries

**Examples:**

*Keep only even values*

Creates a new Map with only the entries whose value satisfies the predicate.

```typescript
filter(new Map([['a', 1], ['b', 2], ['c', 3]]), value => value % 2 === 0)
// => Map(1) { 'b' => 2 }
```

*No matches*

Returns an empty Map when nothing matches.

```typescript
filter(new Map([['a', 1]]), () => false)
// => Map(0) {}
```

---

### `findKey`

Returns the first key of a Map whose entry satisfies the predicate, in insertion order.

```typescript
import { findKey } from '@helpers4/map';

findKey<K, V>(map: ReadonlyMap<K, V>, predicate: function): K | undefined
```

**Parameters:**

- `map: ReadonlyMap<K, V>` — The Map to search
- `predicate: function` — Function invoked with (value, key)

**Returns:** `K | undefined` — The matching key, or `undefined` if none matches

**Examples:**

*Find the key of the first matching entry*

Searches in insertion order and returns the key of the first match.

```typescript
findKey(new Map([['a', 1], ['b', 2]]), value => value > 1)
// => 'b'
```

*No match*

Returns undefined when nothing satisfies the predicate.

```typescript
findKey(new Map([['a', 1]]), value => value > 10)
// => undefined
```

---

### `findValue`

Returns the first value of a Map whose entry satisfies the predicate, in insertion order.

```typescript
import { findValue } from '@helpers4/map';

findValue<K, V>(map: ReadonlyMap<K, V>, predicate: function): V | undefined
```

**Parameters:**

- `map: ReadonlyMap<K, V>` — The Map to search
- `predicate: function` — Function invoked with (value, key)

**Returns:** `V | undefined` — The matching value, or `undefined` if none matches

**Examples:**

*Find the first matching value*

Searches in insertion order and returns the value of the first match.

```typescript
findValue(new Map([['a', 1], ['b', 2]]), value => value > 1)
// => 2
```

*No match*

Returns undefined when nothing satisfies the predicate.

```typescript
findValue(new Map([['a', 1]]), value => value > 10)
// => undefined
```

---

### `hasValue`

Checks whether a value exists anywhere in a Map (`Map.prototype.has` checks keys, not values).
Uses `Object.is`-style equality (via `===`, with `NaN` matching `NaN`).

```typescript
import { hasValue } from '@helpers4/map';

hasValue<K, V>(map: ReadonlyMap<K, V>, value: V): boolean
```

**Parameters:**

- `map: ReadonlyMap<K, V>` — The Map to search
- `value: V` — The value to look for

**Returns:** `boolean` — `true` if the value is found in at least one entry

**Examples:**

*Check whether a value exists in a Map*

Unlike Map.prototype.has (which checks keys), this checks values.

```typescript
hasValue(new Map([['a', 1], ['b', 2]]), 2)
// => true
```

*Value absent*

Returns false when no entry has that value.

```typescript
hasValue(new Map([['a', 1]]), 99)
// => false
```

---

### `mapKeys`

Creates a new Map with the same values but with each key transformed by a function.
If two entries derive the same new key, the later one (in insertion order) wins.

```typescript
import { mapKeys } from '@helpers4/map';

mapKeys<K, V, R>(map: ReadonlyMap<K, V>, fn: function): Map<R, V>
```

**Parameters:**

- `map: ReadonlyMap<K, V>` — The Map to transform
- `fn: function` — Function invoked with (key, value) that returns the new key

**Returns:** `Map<R, V>` — A new Map with transformed keys

**Examples:**

*Uppercase every key*

Creates a new Map with transformed keys and unchanged values.

```typescript
mapKeys(new Map([['a', 1], ['b', 2]]), key => key.toUpperCase())
// => Map(2) { 'A' => 1, 'B' => 2 }
```

---

### `mapValues`

Creates a new Map with the same keys but with each value transformed by a function.

```typescript
import { mapValues } from '@helpers4/map';

mapValues<K, V, R>(map: ReadonlyMap<K, V>, fn: function): Map<K, R>
```

**Parameters:**

- `map: ReadonlyMap<K, V>` — The Map to transform
- `fn: function` — Function invoked with (value, key) that returns the new value

**Returns:** `Map<K, R>` — A new Map with transformed values

**Examples:**

*Scale every value*

Creates a new Map with transformed values and unchanged keys.

```typescript
mapValues(new Map([['a', 1], ['b', 2]]), value => value * 10)
// => Map(2) { 'a' => 10, 'b' => 20 }
```

---

### `reduce`

Reduces a Map to a single value by applying a function to each entry, in insertion order.

```typescript
import { reduce } from '@helpers4/map';

reduce<K, V, R>(map: ReadonlyMap<K, V>, fn: function, initial: R): R
```

**Parameters:**

- `map: ReadonlyMap<K, V>` — The Map to reduce
- `fn: function` — Function invoked with (accumulator, value, key)
- `initial: R` — Initial accumulator value

**Returns:** `R` — The final accumulator value

**Examples:**

*Sum all values*

Reduces a Map of numbers to their total.

```typescript
reduce(new Map([['a', 1], ['b', 2], ['c', 3]]), (acc, value) => acc + value, 0)
// => 6
```

*Build an array of keys*

Reduce can produce a completely different shape than the map values.

```typescript
reduce(new Map([['a', 1], ['b', 2]]), (acc: string[], _v, key) => [...acc, key], [])
// => ['a', 'b']
```

---

### `some`

Checks if at least one entry of a Map satisfies the predicate. Short-circuits on the first match.

```typescript
import { some } from '@helpers4/map';

some<K, V>(map: ReadonlyMap<K, V>, predicate: function): boolean
```

**Parameters:**

- `map: ReadonlyMap<K, V>` — The Map to check
- `predicate: function` — Function invoked with (value, key)

**Returns:** `boolean` — `true` if at least one entry matches, `false` otherwise (including for an empty map)

**Examples:**

*Check if any value exceeds a threshold*

Returns true as soon as one entry satisfies the predicate.

```typescript
some(new Map([['a', 1], ['b', 2]]), value => value > 1)
// => true
```

*Empty map*

Always returns false for an empty map.

```typescript
some(new Map(), () => true)
// => false
```

---

### `toMapByKey`

Builds a Map from an iterable of items, keyed by a derived key. When two items derive the
same key, the later item wins (last-write-wins, matching `Map.prototype.set` semantics).

Named `toMapByKey`, not `keyBy` (lodash's name for the same idea) — lodash's `_.keyBy`
returns a plain object, not a `Map`; the `to<Type>` prefix (matching `toSorted`/`toReversed`)
makes the actual return type unambiguous.

```typescript
import { toMapByKey } from '@helpers4/map';

toMapByKey<T, K>(items: Iterable<T>, fn: function): Map<K, T>
```

**Parameters:**

- `items: Iterable<T>` — The items to index
- `fn: function` — Function deriving the key for each item

**Returns:** `Map<K, T>` — A Map from derived key to item

**Examples:**

*Index an array of records by id*

Builds a Map keyed by a derived value, for O(1) lookup by that key.

```typescript
toMapByKey([{ id: 'a', n: 1 }, { id: 'b', n: 2 }], item => item.id)
// => Map(2) { 'a' => {...}, 'b' => {...} }
```

*Last item wins on collision*

When two items derive the same key, the later one overwrites the earlier one.

```typescript
toMapByKey([{ id: 'a', n: 1 }, { id: 'a', n: 2 }], item => item.id).get('a')
// => { id: 'a', n: 2 }
```

---

## markdown

Package: `@helpers4/markdown`

### `escape`

Escapes all Markdown special characters in a string so they render as
literal text rather than formatting syntax.

Escaped characters: `\ \` * _ { } [ ] ( ) # + - . !`

Pass `{ cell: true }` to also escape pipe characters and replace newlines
with spaces, making the result safe for embedding in a Markdown table cell.

```typescript
import { escape } from '@helpers4/markdown';

escape(str: string, options?: EscapeOptions): string
```

**Parameters:**

- `str: string` — The raw string to escape
- `options?: EscapeOptions` — Optional escaping options

**Returns:** `string` — The escaped string

**Examples:**

*Escape special Markdown characters*

Prefixes every Markdown special character with a backslash.

```typescript
escape('**bold** and _italic_')
// => '\\*\\*bold\\*\\* and \\_italic\\_'
```

*Safely render user input inside Markdown*

Prevents user-supplied strings from breaking Markdown formatting.

```typescript
const userInput = '(C) [helpers4]';
const safe = escape(userInput);
// => '\\(C\\) \\[helpers4\\]'
```

---

## node

Package: `@helpers4/node`

### `isBuffer`

Checks if a value is a Node.js Buffer instance.

`Buffer` extends `Uint8Array` and is specific to Node.js, Bun, and Deno.
In browser-only environments where `Buffer` is not defined, this function
always returns `false`.

Useful for filtering or type-narrowing in a functional pipeline:
`values.filter(isBuffer)`

```typescript
import { isBuffer } from '@helpers4/node';

isBuffer(value: unknown): value is Buffer<ArrayBufferLike>
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is Buffer<ArrayBufferLike>` — True if value is a Buffer

**Examples:**

*Detect a Node.js Buffer*

Returns true only for Buffer instances. Uint8Array is not a Buffer.

```typescript
isBuffer(Buffer.from('hello')) // => true
isBuffer(new Uint8Array(8))    // => false
isBuffer('hello')              // => false
```

*Filter Buffers from a mixed array*

Use as a predicate in .filter() to extract Buffer values.

```typescript
const values = [Buffer.from('a'), 'text', Buffer.alloc(4), 42];
values.filter(isBuffer)
// => [Buffer, Buffer]
```

---

### `isNodeStream`

Checks if a value is a Node.js stream (has a `.pipe()` method).

Uses duck-typing: any object with a `pipe` function qualifies, covering
`Readable`, `Writable`, `Duplex`, `Transform`, and custom stream-compatible
objects without importing from `node:stream`.

```typescript
import { isNodeStream } from '@helpers4/node';

isNodeStream(value: unknown): value is object
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is object` — `true` if value is a Node.js stream

**Examples:**

*Detect a Node.js stream*

Returns true for any object with a .pipe() method (Readable, Writable, Transform, etc.).

```typescript
import { Readable } from 'node:stream';
isNodeStream(new Readable({ read() {} })) // => true
isNodeStream({})                          // => false
isNodeStream(null)                        // => false
```

*Guard before piping an unknown value*

Use isNodeStream to safely pipe only known streams.

```typescript
import { Writable } from 'node:stream';
function pipeToOutput(source: unknown, dest: Writable): void {
  if (isNodeStream(source)) {
    source.pipe(dest);
  }
}
```

---

### `isSharedArrayBuffer`

Checks if a value is a `SharedArrayBuffer` instance.

`SharedArrayBuffer` enables shared memory between the main thread and worker
threads. In browsers without COOP/COEP headers, `SharedArrayBuffer` may be
unavailable; this function returns `false` in that case.

```typescript
import { isSharedArrayBuffer } from '@helpers4/node';

isSharedArrayBuffer(value: unknown): value is SharedArrayBuffer
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is SharedArrayBuffer` — `true` if value is a SharedArrayBuffer

**Examples:**

*Distinguish SharedArrayBuffer from ArrayBuffer*

Returns true only for SharedArrayBuffer instances, not plain ArrayBuffers.

```typescript
isSharedArrayBuffer(new SharedArrayBuffer(8)) // => true
isSharedArrayBuffer(new ArrayBuffer(8))       // => false
isSharedArrayBuffer(null)                     // => false
```

*Safe shared memory check before worker communication*

Use as a guard to ensure a buffer can be transferred to a Worker.

```typescript
function sendToWorker(buffer: unknown): void {
  if (isSharedArrayBuffer(buffer)) {
    // buffer is SharedArrayBuffer — can be shared directly
    // worker.postMessage({ buffer });
  } else {
    // must transfer or copy
  }
}
```

---

### `safeReadJsonFile`

Reads a file and parses its contents as JSON, returning `null` (or a
fallback) on any failure — a missing/unreadable file and invalid content
are both treated the same way.

Also tolerates JSONC (line/block comments and trailing commas — the
dialect used by `tsconfig.json`, VS Code's `settings.json`, etc.): strict
`JSON.parse` is tried first, and only on failure is the content re-parsed
with comments/trailing commas stripped, so plain JSON pays no extra cost.

Unlike `readFileSync` + `JSON.parse`, this never throws.

```typescript
import { safeReadJsonFile } from '@helpers4/node';

safeReadJsonFile<T>(filePath: string): T | null
```

**Parameters:**

- `filePath: string` — Path to the JSON (or JSONC) file to read.

**Returns:** `T | null` — The parsed value typed as `T`, or `null` on failure (pass a `fallback` to get it instead)

```typescript
import { safeReadJsonFile } from '@helpers4/node';

safeReadJsonFile<T>(filePath: string, fallback: T): T
```

**Parameters:**

- `filePath: string` — Path to the JSON (or JSONC) file to read
- `fallback: T` — Value returned on failure

**Returns:** `T` — The parsed value typed as `T`, or `fallback` on failure

**Examples:**

*Read and parse a JSON file*

Returns the parsed value when the file exists and contains valid JSON.

```typescript
safeReadJsonFile<{ name: string }>('./package.json')
// => { name: 'my-package', ... }
```

*Return null when the file is missing*

Returns null instead of throwing when the file does not exist.

```typescript
safeReadJsonFile('./does-not-exist.json')
// => null
```

*Use a fallback value*

Returns the provided fallback when the file is missing or invalid.

```typescript
safeReadJsonFile('./does-not-exist.json', {})
// => {}
```

*Also reads JSONC (comments + trailing commas)*

tsconfig.json/settings.json-style content — line/block comments and a trailing comma — parses too.

```typescript
safeReadJsonFile('./tsconfig.json')
// {
//   // enable strict type-checking
//   "compilerOptions": { "strict": true },
// }
// => { compilerOptions: { strict: true } }
```

---

### `withTempDir`

Creates a fresh temporary directory under the OS temp root, runs `fn` with its path, and
always removes it (recursively) afterward — including when `fn` throws.

```typescript
import { withTempDir } from '@helpers4/node';

withTempDir<T>(prefix: string, fn: function): Promise<T>
```

**Parameters:**

- `prefix: string` — Prepended to the generated directory name, to make it identifiable
- `fn: function` — Receives the temp directory's absolute path; its (possibly synchronous) return
value is returned

**Returns:** `Promise<T>` — Whatever `fn` returns or resolves to

**Examples:**

*Do work in a scratch directory that always gets cleaned up*

The directory is removed once fn resolves, even if fn throws.

```typescript
await withTempDir('my-tool', async (dir) => {
  await writeFile(`${dir}/output.txt`, 'data');
  return readFile(`${dir}/output.txt`, 'utf-8');
});
// => 'data' (the directory no longer exists once this resolves)
```

---

## number

Package: `@helpers4/number`

### `clamp`

Clamps a number between min and max values

```typescript
import { clamp } from '@helpers4/number';

clamp(value: number, min: number, max: number): number
```

**Parameters:**

- `value: number` — The value to clamp
- `min: number` — Minimum value
- `max: number` — Maximum value

**Returns:** `number` — Clamped value

**Examples:**

*Clamp a value within range*

Restricts a number to be within a min/max range.

```typescript
clamp(15, 0, 10)  // => 10
clamp(-5, 0, 10)  // => 0
clamp(5, 0, 10)   // => 5
```

---

### `correctFloat`

Corrects floating-point arithmetic errors by rounding to a given number
of significant digits. Useful after calculations that accumulate binary
floating-point drift (e.g. `0.1 + 0.2 === 0.30000000000000004`).

The default precision of 14 significant digits eliminates typical
rounding noise for values in the range used by most applications.
Note: for values whose integer part already consumes 14 or more digits
(i.e. |value| ≥ 1e13), toPrecision(14) has no room left for decimal
digits and will silently truncate them. Increase `precision` if you
need to correct drift in very large numbers.

Note: IEEE-754 doubles carry at most ~17 significant decimal digits.
Precision values above 17 pad with digits that reflect the underlying
binary representation rather than correcting drift.

```typescript
import { correctFloat } from '@helpers4/number';

correctFloat(value: number, precision: number): number
```

**Parameters:**

- `value: number` — The floating-point value to correct
- `precision: number` (default: `14`) — Integer number of significant digits between 1 and 100
  (default: 14). Values above 17 are valid but expose binary noise beyond
  IEEE-754's meaningful range.

**Returns:** `number` — The corrected value

**Examples:**

*Fix floating-point drift*

Corrects the classic 0.1 + 0.2 floating-point arithmetic error.

```typescript
0.1 + 0.2              // => 0.30000000000000004
correctFloat(0.1 + 0.2)  // => 0.3
```

*Custom significant-digit precision*

Pass a second argument to control how many significant digits to keep.

```typescript
correctFloat(1.23456789, 4)  // => 1.235
correctFloat(1.23456789, 6)  // => 1.23457
```

---

### `extractNumber`

Extracts the first number embedded anywhere in a string, or passes through a `number`.

Unlike a plain `parseFloat`/`parseInt`, the number does not need to be at the start of
the string: digits are searched for anywhere, so leading/trailing text (units, labels, ...)
is ignored. A `-` before the digits and a scientific-notation suffix (`e`/`E`) are
disambiguated with ExtractNumberOptions.sign and ExtractNumberOptions.exponent.

Returns `undefined` if no number can be found.

```typescript
import { extractNumber } from '@helpers4/number';

extractNumber(value: unknown, options: ExtractNumberOptions): number | undefined
```

**Parameters:**

- `value: unknown` — The value to extract a number from
- `options: ExtractNumberOptions` (default: `{}`) — Options controlling sign and exponent disambiguation

**Returns:** `number | undefined` — The extracted number, or `undefined` if none was found

**Examples:**

*extractNumber*

```typescript
```ts
extractNumber('16.5px')        // => 16.5
extractNumber('.5rem')         // => 0.5   (leading-dot decimal)
extractNumber('-.5')           // => -0.5  (leading-dot with sign)
extractNumber('Wafer 10')      // => 10
extractNumber('xxx-111')       // => 111   ('-' glued to text → separator)
extractNumber('xxx -111')      // => -111  ('-' preceded by a space → sign)
extractNumber('x-.5')          // => 0.5   ('-' glued to 'x' → separator; leading-dot decimal follows)
extractNumber('-111')          // => -111  ('-' at the start of the string → sign)
extractNumber('1e5 mol')       // => 100000
extractNumber('1e5kg')         // => 1     ('e5' glued to text → mantissa only)
extractNumber('no number')     // => undefined
extractNumber(42)              // => 42
```
```

---

### `formatCompact`

Formats a number using compact notation (e.g. `1_500_000 → "1.5M"`).

Thin wrapper over `Intl.NumberFormat` with `notation: 'compact'`. Companion
of `formatSize` in the same `format*` family.

```typescript
import { formatCompact } from '@helpers4/number';

formatCompact(value: number, locale?: string): string
```

**Parameters:**

- `value: number` — The number to format.
- `locale?: string` — BCP 47 locale tag. Defaults to the runtime locale.

**Returns:** `string` — A compact string representation of the number.

**Examples:**

*Compact large numbers*

Formats a number using K / M suffixes for readability.

```typescript
formatCompact(1_500_000, 'en') // => '1.5M'
formatCompact(1_000, 'en')     // => '1K'
formatCompact(999, 'en')       // => '999'
```

*Locale-aware formatting*

Uses the provided locale for the decimal separator and suffix.

```typescript
formatCompact(1_500_000, 'fr') // => '1,5 M'
```

---

### `formatSize`

Format a byte count into a human-readable string with the appropriate unit.

Each unit is 1024 of the previous (binary prefix). The result is formatted
with one decimal place, unless `integerBelowFirstUnit` is set.

```typescript
import { formatSize } from '@helpers4/number';

formatSize(bytes: number, options: FormatSizeOptions): string
```

**Parameters:**

- `bytes: number` — A non-negative integer representing a byte count.
- `options: FormatSizeOptions` (default: `{}`) — Options.

**Returns:** `string` — A human-readable string such as `'0.0B'`, `'1.5KB'`, `'3.2MB'`.

**Examples:**

*Format bytes to human-readable size*

Converts a raw byte count to a human-readable string using binary prefixes.

```typescript
formatSize(0)             // '0.0B'
formatSize(512)           // '512.0B'
formatSize(1024)          // '1.0KB'
formatSize(1_048_576)     // '1.0MB'
formatSize(1_073_741_824) // '1.0GB'
```

*Space before the unit, and a bare integer below the first unit*

unitSeparator inserts a separator before the unit; integerBelowFirstUnit drops the decimal for byte counts under 1024.

```typescript
formatSize(1536, { unitSeparator: ' ' })                            // '1.5 KB'
formatSize(512, { integerBelowFirstUnit: true })                    // '512B'
formatSize(512, { unitSeparator: ' ', integerBelowFirstUnit: true }) // '512 B'
```

---

### `inRange`

Checks whether a number falls within `[min, max]` (both inclusive by default).

```typescript
import { inRange } from '@helpers4/number';

inRange(value: number, min: number, max: number, options: InRangeOptions): boolean
```

**Parameters:**

- `value: number` — The number to test
- `min: number` — Lower bound
- `max: number` — Upper bound
- `options: InRangeOptions` (default: `{}`) — Boundary inclusion mode (default: `'both'`)

**Returns:** `boolean` — `true` if `value` is within the specified range

**Examples:**

*Check if a value is within bounds (inclusive)*

Both min and max are included by default.

```typescript
inRange(5, 1, 10)   // => true
inRange(0, 1, 10)   // => false
inRange(1, 1, 10)   // => true  (min included)
inRange(10, 1, 10)  // => true  (max included)
```

*Exclusive range*

Use { inclusive: "none" } for open interval (min, max).

```typescript
inRange(5, 1, 10, { inclusive: 'none' })  // => true
inRange(1, 1, 10, { inclusive: 'none' })  // => false
inRange(10, 1, 10, { inclusive: 'none' }) // => false
```

---

### `isEven`

Checks if a value is an even integer.

Returns `false` for non-numbers, non-integers, `NaN`, `Infinity`, and odd integers.

```typescript
import { isEven } from '@helpers4/number';

isEven(value: unknown): value is number
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is number` — `true` if value is an integer divisible by 2

**Examples:**

*Check if a number is even*

Returns true for integers divisible by 2, false otherwise.

```typescript
isEven(4)   // => true
isEven(0)   // => true
isEven(3)   // => false
isEven(1.5) // => false  (not an integer)
```

*Filter even numbers from an array*

Use as a predicate in .filter() to extract even integers.

```typescript
const nums = [1, 2, 3, 4, 5, 6];
nums.filter(isEven)
// => [2, 4, 6]
```

---

### `isNegative`

Checks if a value is a number less than 0.

Returns `false` for `NaN`, `0`, positive numbers, and non-number types.

```typescript
import { isNegative } from '@helpers4/number';

isNegative(value: unknown): value is number
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is number` — True if value is a negative number

**Examples:**

*isNegative*

```typescript
```ts
isNegative(-1)        // => true
isNegative(-0.5)      // => true
isNegative(-Infinity) // => true
isNegative(0)         // => false
isNegative(1)         // => false
isNegative(NaN)       // => false
```
```

---

### `isOdd`

Checks if a value is an odd integer.

Returns `false` for non-numbers, non-integers, `NaN`, `Infinity`, and even integers.

```typescript
import { isOdd } from '@helpers4/number';

isOdd(value: unknown): value is number
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is number` — `true` if value is an integer not divisible by 2

**Examples:**

*Check if a number is odd*

Returns true for integers not divisible by 2, false otherwise.

```typescript
isOdd(3)   // => true
isOdd(1)   // => true
isOdd(2)   // => false
isOdd(0)   // => false
isOdd(1.5) // => false  (not an integer)
```

*Filter odd numbers from an array*

Use as a predicate in .filter() to extract odd integers.

```typescript
const nums = [1, 2, 3, 4, 5, 6];
nums.filter(isOdd)
// => [1, 3, 5]
```

---

### `isPositive`

Checks if a value is a number greater than 0.

Returns `false` for `NaN`, `0`, negative numbers, and non-number types.

```typescript
import { isPositive } from '@helpers4/number';

isPositive(value: unknown): value is number
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is number` — True if value is a positive number

**Examples:**

*isPositive*

```typescript
```ts
isPositive(42)       // => true
isPositive(0.1)      // => true
isPositive(Infinity) // => true
isPositive(0)        // => false
isPositive(-1)       // => false
isPositive(NaN)      // => false
```
```

---

### `lerp`

Linearly interpolates between `start` and `end` by the factor `t`.

- `t = 0` returns `start`.
- `t = 1` returns `end`.
- Values of `t` outside `[0, 1]` extrapolate beyond the range.

```typescript
import { lerp } from '@helpers4/number';

lerp(start: number, end: number, t: number): number
```

**Parameters:**

- `start: number` — The start value.
- `end: number` — The end value.
- `t: number` — The interpolation factor.

**Returns:** `number` — The interpolated value.

**Examples:**

*Interpolate between two values*

Returns the value between start and end at position t (0 = start, 1 = end).

```typescript
lerp(0, 100, 0)    // => 0
lerp(0, 100, 0.5)  // => 50
lerp(0, 100, 1)    // => 100
```

*Animate a colour channel*

t outside [0, 1] extrapolates beyond the range.

```typescript
lerp(0, 255, 0.5) // => 127.5
lerp(0, 10, 2)    // => 20  (extrapolation)
```

---

### `randomBetween`

Generates a random number between min and max (inclusive)

```typescript
import { randomBetween } from '@helpers4/number';

randomBetween(min: number, max: number): number
```

**Parameters:**

- `min: number` — Minimum value
- `max: number` — Maximum value

**Returns:** `number` — Random number between min and max

**Examples:**

*Generate a random float in range*

Returns a random number between min and max (inclusive).

```typescript
randomBetween(1, 10)
// => e.g. 5.327...
```

*Generate a random integer in range*

Returns a random integer between min and max (inclusive).

```typescript
randomIntBetween(1, 6)
// => e.g. 4
```

---

### `randomIntBetween`

Generates a random integer between min and max (inclusive)

```typescript
import { randomIntBetween } from '@helpers4/number';

randomIntBetween(min: number, max: number): number
```

**Parameters:**

- `min: number` — Minimum value
- `max: number` — Maximum value

**Returns:** `number` — Random integer between min and max

---

### `roundTo`

Rounds a number to specified decimal places

```typescript
import { roundTo } from '@helpers4/number';

roundTo(value: number, decimals: number): number
```

**Parameters:**

- `value: number` — The number to round
- `decimals: number` — Number of decimal places

**Returns:** `number` — Rounded number

**Examples:**

*Round to 2 decimal places*

Rounds a floating-point number to the specified number of decimals.

```typescript
roundTo(3.14159, 2)
// => 3.14
```

*Round to 0 decimal places*

Effectively rounds to the nearest integer.

```typescript
roundTo(3.7, 0)
// => 4
```

---

## object

Package: `@helpers4/object`

### `camelCaseKeys`

Recursively transforms every key of a plain object (including keys nested inside arrays and
nested objects) to camelCase. Handles snake_case, kebab-case, PascalCase, and space-separated
keys. Non-plain-object values (arrays' items aside) — `Date`, `Map`, `Set`, class instances,
primitives — are left untouched, only their position is walked into. An entry whose
transformed key is a prototype-polluting string (`__proto__`, `constructor`, `prototype`) is
silently skipped, same as the rest of `@helpers4/object`.

```typescript
import { camelCaseKeys } from '@helpers4/object';

camelCaseKeys<T>(value: T): T
```

**Parameters:**

- `value: T` — The object (or array of objects) to transform

**Returns:** `T` — A new value with every plain-object key converted to camelCase

**Examples:**

*Convert a snake_case API response*

Recursively converts every key, including nested objects, to camelCase.

```typescript
camelCaseKeys({ user_name: 'Alice', home_address: { zip_code: '12345' } })
// => { userName: 'Alice', homeAddress: { zipCode: '12345' } }
```

*Arrays of objects are walked too*

Each object inside an array gets its keys converted.

```typescript
camelCaseKeys({ user_list: [{ first_name: 'A' }] })
// => { userList: [{ firstName: 'A' }] }
```

---

### `clone`

Creates a shallow copy of a value — one level deep, unlike cloneDeep.

Unlike a plain `{ ...value }` spread, this correctly reconstructs `Date`,
`Map`, `Set`, and arrays instead of producing an empty (or wrong-shaped)
plain object for them. Primitives are returned as-is. Any other object
(including class instances not listed above) has its own enumerable string
keys shallow-copied into a plain object — the same fallback `cloneDeep`
uses, so the two stay consistent for types neither one special-cases.

```typescript
import { clone } from '@helpers4/object';

clone<T>(value: T): T
```

**Parameters:**

- `value: T` — The value to shallow-clone

**Returns:** `T` — A shallow copy of `value`

**Examples:**

*Shallow-copy a plain object*

Top-level keys are copied; nested values still share references (shallow).

```typescript
const obj = { a: 1, b: { c: 2 } };
const copy = clone(obj);
copy.b === obj.b // => true (same nested reference)
```

*Correctly clones Date/Map/Set, unlike a spread*

{ ...new Date() } produces {} — clone() doesn't have that problem.

```typescript
clone(new Map([['a', 1]]))
// => new Map with the same entries, not {}
```

---

### `cloneDeep`

Creates a deep copy of an object or array.

Recursively clones own enumerable string keys. `Date` instances are
reconstructed with the same epoch value. Prototype-polluting keys
(`__proto__`, `constructor`, `prototype`) are silently skipped.
Does **not** handle circular references.

**Limitation:** symbol-keyed own properties are **not** copied — only string
keys are processed. Use `structuredClone` if symbol propagation is required.

```typescript
import { cloneDeep } from '@helpers4/object';

cloneDeep<T>(obj: T): T
```

**Parameters:**

- `obj: T` — The value to clone

**Returns:** `T` — A deep copy of `obj`

**Examples:**

*Clone a nested object*

Creates a deep copy — modifying the clone does not affect the original.

```typescript
const original = { a: { b: 1 } };
const cloned = cloneDeep(original);
cloned.a.b = 2;
// original.a.b is still 1
```

---

### `compact`

Removes all entries with falsy values (`false`, `null`, `undefined`, `0`, `""`, `NaN`) from an object.
Own keys that are prototype-polluting strings (`__proto__`, `constructor`, `prototype`) are
silently skipped.

```typescript
import { compact } from '@helpers4/object';

compact<T extends Record<string, unknown>>(obj: T): Partial<T>
```

**Parameters:**

- `obj: T` — The source object

**Returns:** `Partial<T>` — A new object containing only entries with truthy values

```typescript
import { compact } from '@helpers4/object';

compact(obj: undefined): undefined
```

**Parameters:**

- `obj: undefined` — The source object

**Returns:** `undefined` — A new object containing only entries with truthy values

```typescript
import { compact } from '@helpers4/object';

compact(obj: null): null
```

**Parameters:**

- `obj: null` — The source object

**Returns:** `null` — A new object containing only entries with truthy values

**Examples:**

*Remove falsy values from object*

Removes all entries with falsy values (false, null, undefined, 0, "", NaN).

```typescript
compact({ a: 1, b: null, c: '', d: 0, e: 'hello' })
// => { a: 1, e: 'hello' }
```

*Clean up API response*

Useful to strip empty or missing fields before sending data.

```typescript
compact({ name: 'Alice', email: '', age: 0, role: 'admin' })
// => { name: 'Alice', role: 'admin' }
```

---

### `diff`

Structural object diff.

Returns `true` when both inputs are deeply equal, otherwise a
DiffResult describing the differences key by key.

Comparison rules:
- Same reference \u2192 `true`.
- Either side is `null`/`undefined` (and not both) \u2192 `false`.
- Both `Date` \u2192 epoch comparison.
- Both arrays \u2192 compared with `array/equalsDeep` (leaf, no diff drill-down).
- Special objects (Map, Set, RegExp, Promise, class instances\u2026) \u2192 reference equality.
- Plain objects \u2192 key-by-key, recursing up to `options.depth` levels.
- Mixed types (e.g. array vs object, Date vs object) \u2192 `false`.

For a boolean wrapper see equalsDeep from this category.
For a one-level boolean check see equalsShallow from this category.

```typescript
import { diff } from '@helpers4/object';

diff(objA: object | null | undefined, objB: object | null | undefined, options: DiffOptions): boolean | DiffResult
```

**Parameters:**

- `objA: object | null | undefined` — First value (object, `null`, or `undefined`).
- `objB: object | null | undefined` — Second value (object, `null`, or `undefined`).
- `options: DiffOptions` (default: `{}`) — See DiffOptions.

**Returns:** `boolean | DiffResult` — `true` when equal, otherwise a DiffResult, or `false` for incompatible types.

**Examples:**

*Compare nested objects*

Deeply compares two objects, returning true when they are structurally equal.

```typescript
diff({ a: { b: 1 } }, { a: { b: 1 } })
// => true
```

*Detect deep differences*

Returns a detailed diff object when nested values differ.

```typescript
diff({ a: { b: 1 } }, { a: { b: 2 } })
// => { a: { b: false } }
```

---

### `equalsDeep`

Recursive structural object equality.

Boolean wrapper around diff \u2014 returns `true` when the two values
are deeply equal according to the same rules. Use this when you only
need a yes/no answer; use diff when you also need to know
*what* differs.

For a one-level boolean check use equalsShallow.

```typescript
import { equalsDeep } from '@helpers4/object';

equalsDeep(objA: object | null | undefined, objB: object | null | undefined): boolean
```

**Parameters:**

- `objA: object | null | undefined` — First value (object, `null`, or `undefined`).
- `objB: object | null | undefined` — Second value (object, `null`, or `undefined`).

**Returns:** `boolean` — `true` if both inputs are deeply equal, `false` otherwise.

**Examples:**

*Compare nested objects*

Recursive structural equality. Returns true when the two values are deeply equal.

```typescript
equalsDeep({ a: { b: 1 } }, { a: { b: 1 } })
// => true
```

*Detect deep differences*

Returns false when nested values differ.

```typescript
equalsDeep({ a: { b: 1 } }, { a: { b: 2 } })
// => false
```

---

### `equalsShallow`

One-level (shallow) object equality.

Two objects are equal when they share the exact same set of own
enumerable string keys and each pair of values satisfies strict equality
(`===`). No recursion: nested objects/arrays are compared by reference.

Falls back to strict equality when either input is `null`, `undefined`
or not an object \u2014 so primitives match if and only if they are `===`.
Arrays are not supported; they always return `false` (unless identical
references). Use `array/equalsShallow` instead.

For recursive structural comparison use equalsDeep. For a diff
structure use diff.

```typescript
import { equalsShallow } from '@helpers4/object';

equalsShallow(objA: unknown, objB: unknown): boolean
```

**Parameters:**

- `objA: unknown` — First value to compare
- `objB: unknown` — Second value to compare

**Returns:** `boolean` — `true` if values are shallowly equal, `false` otherwise.

**Examples:**

*Compare two equal objects*

Uses JSON.stringify for a fast comparison.

```typescript
equalsShallow({ a: 1, b: 2 }, { a: 1, b: 2 })
// => true
```

---

### `flatten`

Flattens a nested object into a single-level object whose keys are the
dot-notation path to each leaf value. The inverse of unflatten.

Only **plain objects** are recursed into — arrays, `Date`, `Map`, `RegExp`,
class instances, and empty plain objects `{}` are kept as opaque leaf
values. This keeps `flatten`/`unflatten` a clean, invertible pair: arrays
can't be losslessly told apart from plain objects once reduced to dotted
keys, so this implementation doesn't attempt it.

Caveat shared by every dotted-path flattening scheme: a key that itself
contains a literal `.` is indistinguishable from real nesting once
flattened (`{ 'a.b': 1 }` and `{ a: { b: 1 } }` both produce `{ 'a.b': 1 }`).

```typescript
import { flatten } from '@helpers4/object';

flatten(obj: Record<string, unknown>): Record<string, unknown>
```

**Parameters:**

- `obj: Record<string, unknown>` — The object to flatten

**Returns:** `Record<string, unknown>` — A single-level object with dot-notation keys

**Examples:**

*Flatten a nested config object*

Each key in the result is the full dot-notation path to a leaf value.

```typescript
flatten({ server: { host: 'localhost', port: 8080 } })
// => { 'server.host': 'localhost', 'server.port': 8080 }
```

*Arrays and special objects are kept as leaves*

Only plain objects are recursed into — arrays stay intact.

```typescript
flatten({ tags: ['a', 'b'], meta: { owner: 'x' } })
// => { tags: ['a', 'b'], 'meta.owner': 'x' }
```

---

### `get`

Gets a value from an object using a dot/bracket-notated path or explicit key array.

**Two path forms are supported:**

1. **String path** — dot notation (`'a.b.c'`) and bracket notation (`'layers[1].name'`)
   are both accepted and mixed freely.
   - Dot segments are always string keys: `'a.1'` → key `'1'` (string).
   - Bracket segments are always number keys: `'a[1]'` → key `1` (number).
   - String literal paths give **full compile-time type inference** on the return type.
   - Dynamic (non-literal) strings return `unknown`.

2. **Key array** (`PropertyKey[]`) — explicit array of `string | number | symbol` keys,
   no parsing performed. Enables symbol-keyed traversal and compile-time type inference:
   `get(obj, ['a', 'b'] as const)` infers the return type from the path.

Both forms support **all objects** (plain objects, arrays, class instances).
Symbol keys are only reachable via the key-array form.

```typescript
import { get } from '@helpers4/object';

get<D>(obj: null | undefined, path: string | readonly PropertyKey[], defaultValue: D): D
```

**Parameters:**

- `obj: null | undefined` — The object to read from
- `path: string | readonly PropertyKey[]` — Dot/bracket-notation string literal or explicit `PropertyKey[]`
- `defaultValue: D` — Returned when the path is absent or resolves to `undefined`

**Returns:** `D` — The value at the path, or `defaultValue`

```typescript
import { get } from '@helpers4/object';

get(obj: null | undefined, path: string | readonly PropertyKey[]): undefined
```

**Parameters:**

- `obj: null | undefined` — The object to read from
- `path: string | readonly PropertyKey[]` — Dot/bracket-notation string literal or explicit `PropertyKey[]`

**Returns:** `undefined` — The value at the path, or `defaultValue`

```typescript
import { get } from '@helpers4/object';

get<T extends object, P extends string | readonly PropertyKey[]>(obj: T | null | undefined, path: P, defaultValue?: DeepGet<T, ParsePath<P>>): DeepGet<T, ParsePath<P>> | undefined
```

**Parameters:**

- `obj: T | null | undefined` — The object to read from
- `path: P` — Dot/bracket-notation string literal or explicit `PropertyKey[]`
- `defaultValue?: DeepGet<T, ParsePath<P>>` — Returned when the path is absent or resolves to `undefined`

**Returns:** `DeepGet<T, ParsePath<P>> | undefined` — The value at the path, or `defaultValue`

**Examples:**

*Access a nested property*

Uses a dot-notated path to retrieve a deeply nested value.

```typescript
get({ a: { b: { c: 42 } } }, 'a.b.c')
// => 42
```

*Return default for missing path*

Returns the default value when the path does not exist.

```typescript
get({ a: 1 }, 'b.c', 'default')
// => 'default'
```

*Get via key array (supports symbols)*

Pass an explicit PropertyKey[] to bypass parsing. Supports string, number, and symbol keys.

```typescript
const id = Symbol('id')
get({ [id]: 'alice' }, [id])
// => 'alice'
```

---

### `groupBy`

Groups an array of items by a key derived from each item.

A thin, typed wrapper around `Object.groupBy` (ES2024) that works on
older targets and provides stricter return-type inference.
`null` and `undefined` are treated as empty arrays and return `{}`.
Items whose computed key is a prototype-polluting string (`__proto__`,
`constructor`, `prototype`) are silently skipped.

```typescript
import { groupBy } from '@helpers4/object';

groupBy<T, K extends PropertyKey>(items: readonly T[] | null | undefined, keyFn: function): Partial<Record<K, T[]>>
```

**Parameters:**

- `items: readonly T[] | null | undefined` — The array to group
- `keyFn: function` — Function that returns the group key for each item

**Returns:** `Partial<Record<K, T[]>>` — A record mapping each key to the array of items with that key

**Examples:**

*Group numbers by parity*

Groups elements by the string key returned by the callback.

```typescript
groupBy([1, 2, 3, 4], n => n % 2 === 0 ? 'even' : 'odd')
// => { odd: [1, 3], even: [2, 4] }
```

*Group objects by a property*

Use a property accessor as the grouping key.

```typescript
const users = [
  { name: 'Alice', role: 'admin' },
  { name: 'Bob',   role: 'user'  },
  { name: 'Carol', role: 'admin' },
];
groupBy(users, u => u.role)
// => { admin: [{...Alice}, {...Carol}], user: [{...Bob}] }
```

---

### `invert`

Returns a new object with keys and values swapped.
If multiple keys share the same value, the last one wins.
`null` and `undefined` are treated as empty objects and return `{}`.
Entries whose source key **or** value is a prototype-polluting string
(`__proto__`, `constructor`, `prototype`) are silently skipped.

```typescript
import { invert } from '@helpers4/object';

invert<K extends string, V extends PropertyKey>(obj: Record<K, V> | null | undefined): Record<V, K>
```

**Parameters:**

- `obj: Record<K, V> | null | undefined` — The object whose keys and values are to be swapped

**Returns:** `Record<V, K>` — A new object with values as keys and original keys as values

**Examples:**

*Swap keys and values*

Returns a new object with keys and values swapped.

```typescript
invert({ a: 'x', b: 'y', c: 'z' })
// => { x: 'a', y: 'b', z: 'c' }
```

*Build a reverse lookup map*

Useful when you have a code-to-label map and need label-to-code.

```typescript
const STATUS_LABELS = { 200: 'OK', 404: 'Not Found', 500: 'Internal Server Error' };
const LABEL_TO_CODE = invert(STATUS_LABELS);

LABEL_TO_CODE['OK']; // => '200'
```

---

### `isEmpty`

Checks if a plain object has no own enumerable string-keyed properties.
`null` and `undefined` are treated as empty objects and return `true`.

Symbol-keyed properties are not counted. Use `Object.getOwnPropertySymbols`
separately if symbol keys matter for your use case.

```typescript
import { isEmpty } from '@helpers4/object';

isEmpty(value: Record<PropertyKey, unknown> | null | undefined): boolean
```

**Parameters:**

- `value: Record<PropertyKey, unknown> | null | undefined` — The object to check

**Returns:** `boolean` — `true` if the object has no own enumerable string-keyed properties, or if `value` is `null`/`undefined`

**Examples:**

*Check if an object has no own string-keyed properties*

Returns true for `{}`. Symbol-keyed properties are not counted.

```typescript
isEmpty({})              // => true
isEmpty({ a: 1 })        // => false
isEmpty({ a: undefined }) // => false  (key exists even if value is undefined)
```

*Symbol keys are not counted*

An object with only symbol-keyed properties is considered empty.

```typescript
const sym = Symbol('x');
const obj = { [sym]: 1 };
isEmpty(obj) // => true  (only string keys are counted)
```

---

### `isNonEmpty`

Checks if a plain object has at least one own enumerable string-keyed property.
`null` and `undefined` are treated as empty objects and return `false`.

Symbol-keyed properties are not counted. Use `Object.getOwnPropertySymbols`
separately if symbol keys matter for your use case.

```typescript
import { isNonEmpty } from '@helpers4/object';

isNonEmpty(value: Record<PropertyKey, unknown> | null | undefined): value is Record<PropertyKey, unknown>
```

**Parameters:**

- `value: Record<PropertyKey, unknown> | null | undefined` — The object to check

**Returns:** `value is Record<PropertyKey, unknown>` — `true` if the object has at least one own enumerable string-keyed property; `false` for empty, `null`, or `undefined`.
Acts as a type guard: the `if` branch narrows `Record<PropertyKey, unknown> | null | undefined` to `Record<PropertyKey, unknown>`.

**Examples:**

*Check if an object has own string-keyed properties*

Returns true when at least one own enumerable string key is present.

```typescript
isNonEmpty({ a: 1 })        // => true
isNonEmpty({ a: undefined }) // => true  (key exists)
isNonEmpty({})              // => false
```

*Guard before iterating object keys*

Use isNonEmpty before looping to avoid processing empty objects.

```typescript
function processConfig(config: Record<string, unknown>): void {
  if (!isNonEmpty(config)) {
    console.warn('Config is empty');
    return;
  }
  for (const key of Object.keys(config)) {
    // process each key
  }
}
```

---

### `kebabCaseKeys`

Recursively transforms every key of a plain object (including keys nested inside arrays and
nested objects) to kebab-case. Handles snake_case, camelCase, PascalCase, and space-separated
keys. Non-plain-object values — `Date`, `Map`, `Set`, class instances, primitives — are left
untouched, only their position is walked into. An entry whose transformed key is a
prototype-polluting string (`__proto__`, `constructor`, `prototype`) is silently skipped,
same as the rest of `@helpers4/object`.

```typescript
import { kebabCaseKeys } from '@helpers4/object';

kebabCaseKeys<T>(value: T): T
```

**Parameters:**

- `value: T` — The object (or array of objects) to transform

**Returns:** `T` — A new value with every plain-object key converted to kebab-case

**Examples:**

*Convert object keys for a kebab-case config format*

Recursively converts every key, including nested objects, to kebab-case.

```typescript
kebabCaseKeys({ userName: 'Alice', homeAddress: { zipCode: '12345' } })
// => { 'user-name': 'Alice', 'home-address': { 'zip-code': '12345' } }
```

---

### `map`

Transforms the values and/or keys of a plain object in a single pass.

Both callbacks are optional and default to identity (no transformation).
When `mapValue` is omitted the original values are preserved;
when `mapKey` is omitted the original keys are preserved.

Note: if two different keys map to the same output key the last one wins
(insertion order). Entries whose mapped key is a prototype-polluting string
(`__proto__`, `constructor`, `prototype`) are silently skipped.

```typescript
import { map } from '@helpers4/object';

map<TObj extends Record<string, unknown>, TVal = indexedAccess, TKey extends PropertyKey = keyof TObj>(obj: TObj | null | undefined, mapValue?: function, mapKey?: function): Record<TKey, TVal>
```

**Parameters:**

- `obj: TObj | null | undefined` — The source object
- `mapValue?: function` — Callback called with `(value, key)` for each entry.
  Defaults to identity.
- `mapKey?: function` — Callback called with `(key, value)` for each entry.
  Defaults to identity.

**Returns:** `Record<TKey, TVal>` — A new object with transformed keys and/or values

**Examples:**

*Transform values*

Maps each value of an object through a transform function.

```typescript
map({ a: 1, b: 2 }, v => v * 10)
// => { a: 10, b: 20 }
```

*Transform keys*

Maps each key of an object through a transform function.

```typescript
map({ a: 1, b: 2 }, undefined, k => k.toUpperCase())
// => { A: 1, B: 2 }
```

*Transform both keys and values in a single pass*

Provide both a value mapper and a key mapper to rewrite the whole object.

```typescript
map(
  { price: 100, discount: 20 },
  v => v / 100,
  k => `${k}Ratio`
)
// => { priceRatio: 1, discountRatio: 0.2 }
```

---

### `mapDeep`

Recursively transforms the keys and/or values of a plain object — the deep counterpart to
map, which only transforms the top level. Descends into nested plain objects and
arrays of them; `Date`, `Map`, `Set`, class instances, and primitives are left untouched
(only their position is walked into, matching cloneDeep's notion of what counts
as a plain-data node worth recursing into).

Both callbacks are optional and default to identity (no transformation). `mapKey` is called
with the *original* key and value (before any recursive value transform); `mapValue` receives
the already-recursed value. Entries whose mapped key is a prototype-polluting string
(`__proto__`, `constructor`, `prototype`) are silently skipped, same as map.

Array elements also go through `mapValue` (with their stringified index as `key`, since
arrays have no property keys of their own) — so values inside a plain array, not just object
properties, get transformed too. `mapKey` is never called for array elements, since there is
no key to rename.

```typescript
import { mapDeep } from '@helpers4/object';

mapDeep<T>(obj: T, mapValue?: function, mapKey?: function): T
```

**Parameters:**

- `obj: T` — The value to transform (typically an object, or an array of objects)
- `mapValue?: function` — Callback called with `(value, key)` for each entry's (already-recursed) value.
  For array elements, `key` is the element's index as a string. Defaults to identity.
- `mapKey?: function` — Callback called with `(key, value)` for each object entry. Defaults to identity.

**Returns:** `T` — A new value with every plain-object key/value transformed

**Examples:**

*Transform every key, recursively*

Unlike map(), mapDeep() walks into nested objects and arrays of objects.

```typescript
mapDeep({ a: { b: 1 } }, undefined, key => key.toUpperCase())
// => { A: { B: 1 } }
```

*Transform every value, recursively*

Values are visited after their own nested content has already been transformed.

```typescript
mapDeep({ a: { b: 1, c: 2 } }, v => typeof v === 'number' ? v * 10 : v)
// => { a: { b: 10, c: 20 } }
```

*Transform values inside arrays too*

Array elements are visited by mapValue as well, keyed by their stringified index.

```typescript
mapDeep({ tags: [1, 2, 3] }, v => typeof v === 'number' ? v * 10 : v)
// => { tags: [10, 20, 30] }
```

---

### `mergeDeep`

Merges two or more objects deeply, returning a **new** object without mutating any input.

Sources are applied left to right. For each key:
- If both sides are plain objects → merged recursively into a new object.
- Otherwise → **later source wins** (the earlier value is overwritten).
- `undefined` in a source **never overwrites** an existing value.
- `null` in a source **does overwrite** and prevents a later source from
  deep-merging into that key: `mergeDeep({ a: { x: 1 } }, { a: null }, { a: { y: 2 } })`
  → `{ a: { y: 2 } }` — `x: 1` is permanently lost.
- Arrays, class instances, and all non-plain-object values are **replaced**, not merged.

Own enumerable string and symbol keys of each source are processed at the top level;
inherited and non-enumerable properties are skipped. Prototype-polluting keys
(`__proto__`, `constructor`, `prototype`) are silently ignored.
**Note:** symbol keys inside nested plain-object values are not preserved — they are
lost when those values are deep-cloned. Only top-level symbol keys survive.

**TypeScript return type — intersection semantics**

The return type is `A & B & C …` (intersection of all source types). This is accurate
when keys are disjoint or share the same type:
```ts
mergeDeep({ a: 1 }, { b: 'x' })           // { a: number } & { b: string }  ✓
mergeDeep({ a: { b: 1 } }, { a: { c: 2 } }) // { a: { b: number } & { c: number } }  ✓
```
When the same key carries **incompatible types** across sources, the intersection
resolves to `never` for that key — TypeScript surfaces the conflict rather than
silently picking a type:
```ts
mergeDeep({ a: 1 }, { a: 'x' })  // { a: never }  ← type conflict detected
```
At runtime the later source always wins (`'x'`), but the `never` type signals that
the caller should align their source types. If intentional, cast the result.

```typescript
import { mergeDeep } from '@helpers4/object';

mergeDeep<T extends [object, rest]>(sources: [rest]): MergeResult<T>
```

**Parameters:**

- `sources: [rest]` — Two or more objects to merge (none are mutated)

**Returns:** `MergeResult<T>` — A new object that is the deep merge of all sources

**Examples:**

*Merge two objects deeply*

Returns a new object — neither input is mutated.

```typescript
mergeDeep({ a: 1, b: { c: 2 } }, { b: { d: 3 }, e: 4 })
// => { a: 1, b: { c: 2, d: 3 }, e: 4 }
```

---

### `omit`

Creates a new object without the specified keys.

```typescript
import { omit } from '@helpers4/object';

omit<T extends object, K extends string | number | symbol>(obj: T, keys: readonly K[]): Omit<T, K>
```

**Parameters:**

- `obj: T` — The source object
- `keys: readonly K[]` — The keys to omit

**Returns:** `Omit<T, K>` — A new object without the omitted keys

```typescript
import { omit } from '@helpers4/object';

omit(obj: undefined, keys: readonly string[]): undefined
```

**Parameters:**

- `obj: undefined` — The source object
- `keys: readonly string[]` — The keys to omit

**Returns:** `undefined` — A new object without the omitted keys

```typescript
import { omit } from '@helpers4/object';

omit(obj: null, keys: readonly string[]): null
```

**Parameters:**

- `obj: null` — The source object
- `keys: readonly string[]` — The keys to omit

**Returns:** `null` — A new object without the omitted keys

**Examples:**

*Omit specific keys*

Creates a new object without the specified keys.

```typescript
omit({ a: 1, b: 2, c: 3 }, ['b'])
// => { a: 1, c: 3 }
```

*Remove sensitive fields*

Useful to strip sensitive data before sending to client.

```typescript
const user = { id: 1, name: 'Alice', password: 'secret', token: 'abc123' };
omit(user, ['password', 'token'])
// => { id: 1, name: 'Alice' }
```

---

### `omitBy`

Creates a new object without the own enumerable entries for which
`predicate` returns `true`.

Complements omit for when the keys to remove aren't known ahead of
time — `omit` takes an explicit key list, `omitBy` takes a predicate.

```typescript
import { omitBy } from '@helpers4/object';

omitBy<T extends Record<string, unknown>>(obj: T | null | undefined, predicate: function): Partial<T> | null | undefined
```

**Parameters:**

- `obj: T | null | undefined` — The source object. `null`/`undefined` pass through unchanged.
- `predicate: function` — Called with `(value, key)` for each own enumerable entry

**Returns:** `Partial<T> | null | undefined` — A new object without the matching entries

**Examples:**

*Drop entries matching a predicate*

Unlike omit(), the keys to drop don’t need to be known ahead of time.

```typescript
omitBy({ a: 1, b: undefined, c: 2 }, (value) => value === undefined)
// => { a: 1, c: 2 }
```

*Drop entries by key name*

The predicate also receives the key, so filtering by name works too.

```typescript
omitBy({ id: 1, name: 'x', _internal: true }, (_v, key) => key.startsWith('_'))
// => { id: 1, name: 'x' }
```

---

### `parsePropertyPath`

Parses a dot/bracket-notation property path into an array of string/number
key segments — the same notation accepted by get and set.

- Dot separators (`.`) split segments; each segment becomes a string key.
- Bracket indices (`[n]`) become number keys.
- A leading `.` is treated as "current level" and stripped before parsing,
  so `.[0]` ≡ `[0]` and `.a.b` ≡ `a.b`.
- Empty string (or a bare `.`) returns `['']` (addresses the `''` key on the root object).
- Consecutive dots (`a..b`) produce an empty-string segment: `['a', '', 'b']`.

Results are cached (up to 500 distinct path strings, oldest evicted first)
since real-world callers tend to reuse a small, fixed set of literal paths.

```typescript
import { parsePropertyPath } from '@helpers4/object';

parsePropertyPath(path: string): readonly string | number[]
```

**Parameters:**

- `path: string` — The dot/bracket-notation path string to parse

**Returns:** `readonly string | number[]` — The parsed key segments

**Examples:**

*Parse a dot/bracket-notation path into key segments*

The same notation accepted by get() and set() — bracket indices become numbers.

```typescript
parsePropertyPath('layers[1].name')
// => ['layers', 1, 'name']
```

*Malformed paths throw instead of silently misparsing*

Text trailing a closing bracket within a segment is ambiguous — use 'a[0].b' instead.

```typescript
parsePropertyPath('a[0]b')
// => throws RangeError
```

---

### `pascalCaseKeys`

Recursively transforms every key of a plain object (including keys nested inside arrays and
nested objects) to PascalCase. Handles camelCase, snake_case, kebab-case, and space-separated
keys. Non-plain-object values — `Date`, `Map`, `Set`, class instances, primitives — are left
untouched, only their position is walked into. An entry whose transformed key is a
prototype-polluting string (`__proto__`, `constructor`, `prototype`) is silently skipped,
same as the rest of `@helpers4/object`.

```typescript
import { pascalCaseKeys } from '@helpers4/object';

pascalCaseKeys<T>(value: T): T
```

**Parameters:**

- `value: T` — The object (or array of objects) to transform

**Returns:** `T` — A new value with every plain-object key converted to PascalCase

**Examples:**

*Convert object keys to PascalCase (e.g. for a C#/JSON.NET consumer)*

Recursively converts every key, including nested objects, to PascalCase.

```typescript
pascalCaseKeys({ user_name: 'Alice', home_address: { zip_code: '12345' } })
// => { UserName: 'Alice', HomeAddress: { ZipCode: '12345' } }
```

---

### `pick`

Creates a new object with only the specified keys.
Keys that are prototype-polluting strings (`__proto__`, `constructor`, `prototype`) are
silently skipped.

```typescript
import { pick } from '@helpers4/object';

pick<T extends object, K extends string | number | symbol>(obj: T, keys: readonly K[]): Pick<T, K>
```

**Parameters:**

- `obj: T` — The source object
- `keys: readonly K[]` — The keys to pick

**Returns:** `Pick<T, K>` — A new object with only the picked keys

```typescript
import { pick } from '@helpers4/object';

pick(obj: undefined, keys: readonly string[]): undefined
```

**Parameters:**

- `obj: undefined` — The source object
- `keys: readonly string[]` — The keys to pick

**Returns:** `undefined` — A new object with only the picked keys

```typescript
import { pick } from '@helpers4/object';

pick(obj: null, keys: readonly string[]): null
```

**Parameters:**

- `obj: null` — The source object
- `keys: readonly string[]` — The keys to pick

**Returns:** `null` — A new object with only the picked keys

**Examples:**

*Pick specific keys*

Creates a new object with only the specified keys.

```typescript
pick({ a: 1, b: 2, c: 3 }, ['a', 'c'])
// => { a: 1, c: 3 }
```

*Extract user fields*

Useful to select only the fields you need from an object.

```typescript
const user = { id: 1, name: 'Alice', email: 'alice@example.com', password: 'secret' };
pick(user, ['id', 'name', 'email'])
// => { id: 1, name: 'Alice', email: 'alice@example.com' }
```

---

### `pickBy`

Creates a new object with only the own enumerable entries for which
`predicate` returns `true`.

Complements pick for when the keys to keep aren't known ahead of
time — `pick` takes an explicit key list, `pickBy` takes a predicate.

```typescript
import { pickBy } from '@helpers4/object';

pickBy<T extends Record<string, unknown>>(obj: T | null | undefined, predicate: function): Partial<T> | null | undefined
```

**Parameters:**

- `obj: T | null | undefined` — The source object. `null`/`undefined` pass through unchanged.
- `predicate: function` — Called with `(value, key)` for each own enumerable entry

**Returns:** `Partial<T> | null | undefined` — A new object with only the matching entries

**Examples:**

*Keep only entries matching a predicate*

Unlike pick(), the keys to keep don’t need to be known ahead of time.

```typescript
pickBy({ a: 1, b: 0, c: 2 }, (value) => value > 0)
// => { a: 1, c: 2 }
```

*Keep entries by key name*

The predicate also receives the key, so filtering by name works too.

```typescript
pickBy({ _id: 1, name: 'x', _internal: true }, (_v, key) => !key.startsWith('_'))
// => { name: 'x' }
```

---

### `removeUndefinedNull`

Remove null and undefined values from an object.

```typescript
import { removeUndefinedNull } from '@helpers4/object';

removeUndefinedNull<T extends Record<string, string | number | boolean | null | undefined>>(obj: T): Partial<T>
```

**Parameters:**

- `obj: T` — an object

**Returns:** `Partial<T>` — A shallow copy of the object without null or undefined values

```typescript
import { removeUndefinedNull } from '@helpers4/object';

removeUndefinedNull(obj: null): null
```

**Parameters:**

- `obj: null` — a null object

**Returns:** `null` — null

```typescript
import { removeUndefinedNull } from '@helpers4/object';

removeUndefinedNull(obj: undefined): undefined
```

**Parameters:**

- `obj: undefined` — an undefined object

**Returns:** `undefined` — undefined

**Examples:**

*Strip null and undefined values*

Returns a shallow copy of the object without null or undefined properties.

```typescript
removeUndefinedNull({ a: 1, b: null, c: undefined, d: 'ok' })
// => { a: 1, d: 'ok' }
```

---

### `safeJsonParse`

Parses a JSON string, returning `null` (or a fallback) on any parse failure.

Unlike `JSON.parse`, this never throws. Invalid JSON strings and other
parsing edge-cases resolve to `null` or the provided `fallback`.

```typescript
import { safeJsonParse } from '@helpers4/object';

safeJsonParse<T>(input: string): T | null
```

**Parameters:**

- `input: string` — The JSON string to parse.

**Returns:** `T | null` — The parsed value typed as `T`, or `null` on failure (pass a `fallback` to get it instead).

```typescript
import { safeJsonParse } from '@helpers4/object';

safeJsonParse<T>(input: string, fallback: T): T
```

**Parameters:**

- `input: string` — The JSON string to parse.
- `fallback: T` — Value returned on failure.

**Returns:** `T` — The parsed value typed as `T`, or `fallback` on failure.

**Examples:**

*Parse valid JSON*

Returns the parsed value when the input is valid JSON.

```typescript
safeJsonParse<{ a: number }>('{"a":1}')
// => { a: 1 }
```

*Return null on invalid input*

Returns null instead of throwing when JSON is malformed.

```typescript
safeJsonParse('invalid')
// => null
```

*Use a fallback value*

Returns the provided fallback when parsing fails.

```typescript
safeJsonParse('invalid', [])
// => []
```

---

### `set`

Sets a value in an object at the given path, creating intermediate objects as needed.

**Two path forms are supported:**

1. **String path** — dot notation and bracket notation, mixed freely.
   - Dot segments are always string keys: `'layers.1.name'` → keys `['layers', '1', 'name']`.
   - Bracket segments are always number keys: `'layers[1].name'` → keys `['layers', 1, 'name']`.
   - String literal paths give **full compile-time type inference** on the return type.
   - Dynamic (non-literal) strings return `T` (same object type).

2. **Key array** (`PropertyKey[]`) — explicit array of `string | number | symbol` keys,
   no parsing performed. Enables symbol-keyed access and precise return-type inference.

Both forms support **all objects** (plain objects, arrays, class instances).
Symbol keys are only reachable via the key-array form.

Intermediate nodes that are absent, `null`, or not an object are replaced with `{}`.
Any path containing a string segment equal to `__proto__`, `constructor`, or `prototype`
is rejected and the original object is returned unchanged (prototype-pollution guard).

```typescript
import { set } from '@helpers4/object';

set<T extends object, P extends string | readonly PropertyKey[], V extends unknown>(obj: T, path: P, value: V): conditional
```

**Parameters:**

- `obj: T` — The object to mutate
- `path: P` — Dot/bracket-notation string literal or explicit `PropertyKey[]`
- `value: V` — Value to assign at the path

**Returns:** `conditional` — The mutated object (same reference, narrowed type)

**Examples:**

*Set a nested property (dot notation)*

Creates intermediate objects as needed. All segments are string keys — including numeric-looking ones like "1".

```typescript
set({}, 'a.b.c', 42)
// => { a: { b: { c: 42 } } }

set({}, 'layers.1.name', 'bg')
// => { layers: { '1': { name: 'bg' } } }   // '1' is a string key
```

*Set via bracket notation*

Square-bracket indices become numeric keys. Useful when the path targets an array element.

```typescript
const obj = { layers: [{}, { name: 'old' }] }
set(obj, 'layers[1].name', 'new')
// => { layers: [{}, { name: 'new' }] }
```

*Set via key array (supports symbols)*

Pass an explicit PropertyKey[] to bypass parsing. Supports string, number, and symbol keys.

```typescript
const id = Symbol('id')
set({}, ['user', id], 'alice')
// => { user: { [id]: 'alice' } }
```

---

### `snakeCaseKeys`

Recursively transforms every key of a plain object (including keys nested inside arrays and
nested objects) to snake_case. Handles camelCase, PascalCase, kebab-case, and space-separated
keys. Non-plain-object values — `Date`, `Map`, `Set`, class instances, primitives — are left
untouched, only their position is walked into. An entry whose transformed key is a
prototype-polluting string (`__proto__`, `constructor`, `prototype`) is silently skipped,
same as the rest of `@helpers4/object`.

```typescript
import { snakeCaseKeys } from '@helpers4/object';

snakeCaseKeys<T>(value: T): T
```

**Parameters:**

- `value: T` — The object (or array of objects) to transform

**Returns:** `T` — A new value with every plain-object key converted to snake_case

**Examples:**

*Convert a camelCase object for a snake_case API*

Recursively converts every key, including nested objects, to snake_case.

```typescript
snakeCaseKeys({ userName: 'Alice', homeAddress: { zipCode: '12345' } })
// => { user_name: 'Alice', home_address: { zip_code: '12345' } }
```

---

### `sortKeys`

Creates a new object with the same entries as the input, but with its own keys sorted.
Shallow only — nested objects are copied as-is, their keys are not re-sorted.
Key order matters for things like `JSON.stringify` diffs and snapshot stability; this does
not change equality (`{a:1,b:2}` and `{b:2,a:1}` are already equal), just iteration/serialization order.
Note: integer-index-like keys (`"0"`, `"1"`, `"42"`...) are always iterated first, in numeric
order, by the JS engine itself — no object key ordering can override that language behavior.
A prototype-polluting key (`__proto__`, `constructor`, `prototype`) is silently skipped,
same as the rest of `@helpers4/object`.

```typescript
import { sortKeys } from '@helpers4/object';

sortKeys<T extends Record<string, unknown>>(obj: T, compareFn?: function): T
```

**Parameters:**

- `obj: T` — The object whose keys to sort
- `compareFn?: function` — Optional custom comparator, passed directly to `Array.prototype.sort`

**Returns:** `T` — A new object with the same entries, own keys in sorted order

**Examples:**

*Sort object keys alphabetically*

Useful for stable JSON.stringify output or predictable snapshot tests.

```typescript
sortKeys({ b: 2, a: 1, c: 3 })
// => { a: 1, b: 2, c: 3 }
```

---

### `titleCaseKeys`

Recursively transforms every key of a plain object (including keys nested inside arrays and
nested objects) to Title Case. Handles camelCase, snake_case, kebab-case, and space-separated
keys. Non-plain-object values — `Date`, `Map`, `Set`, class instances, primitives — are left
untouched, only their position is walked into. An entry whose transformed key is a
prototype-polluting string (`__proto__`, `constructor`, `prototype`) is silently skipped,
same as the rest of `@helpers4/object`.

Note: unlike the other `*CaseKeys` variants, `titleCase` joins words with spaces (e.g.
`'User Name'`) — those keys are only usable via bracket access (`obj['User Name']`), not dot
notation. Useful for display-facing structures (form labels, table headers), not wire formats.

```typescript
import { titleCaseKeys } from '@helpers4/object';

titleCaseKeys<T>(value: T): T
```

**Parameters:**

- `value: T` — The object (or array of objects) to transform

**Returns:** `T` — A new value with every plain-object key converted to Title Case

**Examples:**

*Convert object keys into display-friendly labels*

Recursively converts every key to Title Case — useful for form labels or table headers.

```typescript
titleCaseKeys({ user_name: 'Alice', home_address: { zip_code: '12345' } })
// => { 'User Name': 'Alice', 'Home Address': { 'Zip Code': '12345' } }
```

---

### `unflatten`

Rebuilds a nested object from a single-level object whose keys are
dot-notation paths. The inverse of flatten.

Uses set internally, so intermediate nodes are always created as
plain objects (never arrays — see flatten's doc for why), and any
key segment equal to `__proto__`, `constructor`, or `prototype` is silently
rejected (same prototype-pollution guard as `set`).

```typescript
import { unflatten } from '@helpers4/object';

unflatten(obj: Record<string, unknown>): Record<string, unknown>
```

**Parameters:**

- `obj: Record<string, unknown>` — A single-level object with dot-notation keys

**Returns:** `Record<string, unknown>` — The rebuilt nested object

**Examples:**

*Rebuild a nested object from dotted keys*

The inverse of flatten() — useful for parsing flat config sources (env vars, .ini files).

```typescript
unflatten({ 'server.host': 'localhost', 'server.port': 8080 })
// => { server: { host: 'localhost', port: 8080 } }
```

*Multiple keys under the same parent are merged*

Every dotted key contributes to the same nested structure.

```typescript
unflatten({ 'a.x': 1, 'a.y': 2 })
// => { a: { x: 1, y: 2 } }
```

---

### `unset`

Removes the value at a dot/bracket-notation path or explicit key array,
mutating the object in place. Uses the same path syntax as get/set.

A missing intermediate segment is a no-op (nothing to remove), not an error.
As with `set`, any path containing a string segment equal to `__proto__`,
`constructor`, or `prototype` is rejected and the object is returned unchanged.

The removed key stops appearing in `Object.keys`/`for...in` — unlike setting
it to `undefined`, which would keep the key present.

```typescript
import { unset } from '@helpers4/object';

unset<T extends object>(obj: T, path: string | readonly PropertyKey[]): T
```

**Parameters:**

- `obj: T` — The object to mutate
- `path: string | readonly PropertyKey[]` — Dot/bracket-notation string, or explicit `PropertyKey[]`

**Returns:** `T` — The same object reference, with the key removed if it existed

**Examples:**

*Remove a nested value by path*

Uses the same dot/bracket path syntax as get() and set().

```typescript
const config = { server: { host: 'localhost', debug: true } };
unset(config, 'server.debug')
// => { server: { host: 'localhost' } }
```

*Missing paths are a safe no-op*

Unlike set(), unset() never creates intermediate objects — there is nothing to remove.

```typescript
unset({ a: 1 }, 'x.y.z')
// => { a: 1 }  (unchanged)
```

---

### `update`

Updates the value at a path by applying a function to its current value,
creating intermediate objects as needed. Equivalent to
`set(obj, path, updater(get(obj, path)))` in a single call.

Uses the same path syntax and type-inference rules as get and
set — see those for the full behavior (string vs. `PropertyKey[]`
paths, prototype-pollution guarding, etc.).

```typescript
import { update } from '@helpers4/object';

update<T extends object, P extends string | readonly PropertyKey[], V extends unknown>(obj: T, path: P, updater: function): conditional
```

**Parameters:**

- `obj: T` — The object to mutate
- `path: P` — Dot/bracket-notation string literal or explicit `PropertyKey[]`
- `updater: function` — Called with the current value (`undefined` if the path is
  absent); its return value is written back at the path

**Returns:** `conditional` — The mutated object (same reference, narrowed type)

**Examples:**

*Increment a counter in one call*

Equivalent to set(obj, path, updater(get(obj, path))), without repeating the path.

```typescript
const state = { count: 1 };
update(state, 'count', (n) => (n ?? 0) + 1)
// => { count: 2 }
```

*Missing paths create intermediate objects, like set()*

The updater receives undefined when the path does not exist yet.

```typescript
const stats: Record<string, unknown> = {};
update(stats, 'hits.total', (n: number | undefined) => (n ?? 0) + 1)
// => { hits: { total: 1 } }
```

---

## observable

Package: `@helpers4/observable`

### `combine`

Combine two observables with a map function and an optional pre-treatment.

Note: you can use the pre-treatment to add a filter, a distinctUntilChanged,
any other operator that can be used in a pipe, or even an `UntilDestroy`
operator.

```typescript
import { combine } from '@helpers4/observable';

combine<T, U, R>(source1: Observable<T>, source2: Observable<U>, map: function, options?: combineOptions<T, U>): Observable<R>
```

**Parameters:**

- `source1: Observable<T>` — first source of data
- `source2: Observable<U>` — second source of data
- `map: function` — way to combine data
- `options?: combineOptions<T, U>` — options for the combineLatest operator

**Returns:** `Observable<R>` — an observable that emits the result of the map function

**Examples:**

*Combine two observables with a map*

Combines the latest values of two observables using a mapping function.

```typescript
combine(of(1), of(2), ([a, b]) => a + b)
// emits 3
```

---

### `combineLatest`

Combines multiple Observables to create an Observable whose values are
calculated from the latest values of each of its input Observables.

This method relies on combineLatestOperator of rxjs.

The main difference with combineLatestOperator is in case of empty parameters.
If the parameter is empty (empty array or empty object), the result will be
also empty.

ATTENTION: this version doesn't support `scheduler` nor `mapper` as last
argument like in combineLatestOperator.

```typescript
import { combineLatest } from '@helpers4/observable';

combineLatest<A extends readonly unknown[]>(sources: readonly [ObservableInputTuple<A>]): Observable<A>
```

**Parameters:**

- `sources: readonly [ObservableInputTuple<A>]`

```typescript
import { combineLatest } from '@helpers4/observable';

combineLatest<T extends Record<string, ObservableInput<unknown>>>(sourcesObject: T): Observable<mapped>
```

**Parameters:**

- `sourcesObject: T`

**Examples:**

*Combine array of observables*

Combines an array of observables into one that emits arrays of their latest values.

```typescript
combineLatest([of(1), of(2), of(3)])
// emits [1, 2, 3]
```

*Handle empty array*

Returns an observable that emits an empty array when given no sources.

```typescript
combineLatest([])
// emits []
```

---

### `isObservable`

Checks if a value is an RxJS Observable or any compatible observable.

Uses duck-typing: returns `true` for any object with both `.subscribe()` and
`.pipe()` methods, covering `Observable`, `Subject`, `BehaviorSubject`,
`ReplaySubject`, and any RxJS-compatible observable implementation.

```typescript
import { isObservable } from '@helpers4/observable';

isObservable(value: unknown): value is Observable<unknown>
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is Observable<unknown>` — `true` if value is observable-like

**Examples:**

*Detect an RxJS Observable or Subject*

Returns true for Observable, Subject, BehaviorSubject, and any duck-typed observable.

```typescript
import { Observable, Subject } from 'rxjs';
isObservable(new Observable())  // => true
isObservable(new Subject())     // => true
isObservable(Promise.resolve()) // => false
isObservable({})                // => false
```

*Accept either an Observable or a plain value*

Use as a guard to normalize inputs that may be Observables or raw values.

```typescript
import { Observable, of } from 'rxjs';
function toObservable<T>(value: T | Observable<T>): Observable<T> {
  return isObservable(value) ? value : of(value);
}
```

---

## package

Package: `@helpers4/package`

### `AlpineDependency`

One package reference of an Alpine (apk) `depends` list.

---

### `AlpineOperator`

The operators of an Alpine (apk) version constraint, as apk writes them: the five comparisons;
`~`, a fuzzy match (`foo~1.2` accepts `1.2.5`), and its ordered variants `<~` and `>~`; and `><`,
a checksum comparison used by package indexes.

---

### `ArchDependency`

One package reference of an Arch Linux `depends` array.

---

### `ComparisonOperator`

The operators of an RPM or Arch Linux version constraint.

---

### `DebianDependency`

One package reference of a Debian relationship field: `name[:arch] [(op version)] [[archs]] [<profiles>]`.

---

### `DebianDependencyOptions`

Options of the Debian format of parseDependencies.

---

### `DebianOperator`

The operators of a Debian version constraint (Debian Policy 7.1): `<<` (strictly earlier), `<=`,
`=`, `>=` and `>>` (strictly later).

---

### `DependencyConstraint`

A version constraint such as the `(>= 2.34)` of `libc6 (>= 2.34)`, with the operator spelled as
the format spells it.

---

### `parseDeb822`

Parses a deb822 document, the format of Debian `Packages`, `Sources` and `Release` indexes,
`control` and `.dsc` and `.changes` files, DEP-5 `copyright` files and apt `.sources` files, as
described in the Debian Policy Manual, chapter 5.1 "Syntax of control files".

- Stanzas are separated by one or more blank lines (lines holding only whitespace).
- A field is `Name: value`. The value has its surrounding whitespace removed. Names are
  case-insensitive in Debian: the original spelling is kept in `entries`, and `fields` is keyed
  by the lower-cased name.
- A line starting with a space or a tab continues the previous field. Exactly one leading
  space or tab is removed, the line breaks are kept (joined with `\n`), and a continuation line
  that is just `.` stands for an empty line. A field whose first line is empty (`Files:`) keeps
  that empty first line, so its value starts with `\n`.
- Lines starting with `#` are comments and are ignored anywhere, without ending a stanza or a
  multi-line value. `\r\n` line endings are accepted. Trailing whitespace is dropped.
- A repeated field name inside one stanza: all occurrences stay in `entries`, and the last one
  wins in `fields`.
- A line that is not a comment, a field or a continuation (no colon, a continuation before any
  field, a name with a space before the colon) never throws by default: it is collected in the
  stanza's `unparsed`, so nothing is lost silently. With `{ strict: true }` it throws a
  `SyntaxError` naming the line number and its text instead. A stanza made only of such lines
  is still returned.
- PGP clearsigning armor (`Release`, `.dsc`, `.changes` can be signed) is not interpreted.

To compare the version strings found in `Version` fields, use `compare(a, b, 'debian')` from
`@helpers4/version`; to read `Depends`-like fields, use `parseDependencies`.

```typescript
import { parseDeb822 } from '@helpers4/package';

parseDeb822(text: string, options: Deb822Options): Deb822Stanza[]
```

**Parameters:**

- `text: string` — The document, with `\n` or `\r\n` line endings
- `options: Deb822Options` (default: `{}`) — `{ strict }`, see Deb822Options

**Returns:** `Deb822Stanza[]` — The stanzas in source order; `[]` for an empty or comment-only document

**Examples:**

*Read the stanzas of a Packages index*

A blank line separates the stanzas; field names are looked up in lower case.

```typescript
const stanzas = parseDeb822(packagesText);
stanzas.map((stanza) => stanza.fields.package)
// => ['zlib1g', 'zlib1g-dev']
```

*Keep a multi-line description*

Continuation lines are joined with line breaks, and a lone " ." is a blank line.

```typescript
const [zlib] = parseDeb822(packagesText);
zlib.fields.description
// => 'compression library - runtime\nzlib is a library implementing the deflate compression method.\n\nThis package includes the shared library.'
```

*Keep the original spelling and the duplicates*

`entries` is the ordered record of the stanza, whatever the case of the names.

```typescript
parseDeb822('SHA256: abc\nTag: a\nTAG: b')[0].entries
// => [{ name: 'SHA256', value: 'abc' }, { name: 'Tag', value: 'a' }, { name: 'TAG', value: 'b' }]
```

---

### `parseDependencies`

Parses the value of a package dependency field (`Depends`, `Requires`, `depends`, ...) into a
structure: groups of alternatives, each alternative a name with an optional version constraint.
`format` says how the text is written, and decides the exact shape of each dependency and the
operator spellings (see DependencyFormats); the options are those of that format only.

**`'debian'`** — a relationship field of the Debian Policy Manual, chapter 7.1 (`Depends`,
`Pre-Depends`, `Recommends`, `Suggests`, `Enhances`, `Breaks`, `Conflicts`, `Provides`,
`Replaces`, `Build-Depends`, ...). Commas separate the entries that must all hold (AND), `|`
separates the alternatives inside an entry (OR). Each alternative is
`name[:arch] [(op version)] [[archs]] [<profiles>]`, in that order, with any whitespace (line
breaks included, as in a multi-line `Depends`) between the parts. The operators are Debian's
`<<`, `<=`, `=`, `>=` and `>>`, kept as written; the obsolete `<` and `>` throw unless
`options.compat` is set, in which case they are read as `<=` and `>=` like dpkg does.
Whitespace-only entries (a trailing comma, `a,, b`) are skipped, as dpkg does. The
`${substvars}` of source `debian/control` files are not supported.

**`'rpm'`** — an RPM `Requires` value: capabilities separated by commas and/or whitespace, each
`name [op version]` with `<`, `<=`, `=`, `>=` or `>`; boolean dependencies `(a or b)` give the
alternatives of a group.

**`'arch'`** — an Arch Linux `depends` array or `.PKGINFO` list: entries separated by whitespace
(quotes and surrounding parentheses of a PKGBUILD array are accepted), each `name[op version]`.

**`'alpine'`** — an Alpine `depends` list: entries separated by whitespace, each
`[!]name[op version]` (`!` is a conflict).

**`'pep508'`** — PEP 508 requirements, one per line (as in `requirements.txt` or the
`dependencies` of a `pyproject.toml`): `name[extras] specifiers ; marker`, or `name @ url`.

Every entry that is not valid throws a `SyntaxError` quoting the offending text. Parsing is
linear in the input.

```typescript
import { parseDependencies } from '@helpers4/package';

parseDependencies<Format extends keyof DependencyFormats>(field: string, format: Format, options: ParseDependenciesOptions<Format>): DependencyGroup<DependencyOf<Format>>[]
```

**Parameters:**

- `field: string` — The value of a dependency field
- `format: Format` — How the field is written
- `options: ParseDependenciesOptions<Format>` — The options of `format`, if it has any

**Returns:** `DependencyGroup<DependencyOf<Format>>[]` — One group of alternatives per entry

**Examples:**

*Read a Depends field*

Commas are AND, `|` is OR inside an entry; each alternative carries its qualifier, version and restrictions.

```typescript
parseDependencies('libc6 (>= 2.34), python3:any | python3 (>= 3.8) [amd64], foo <!nocheck>', 'debian')
// => [
//   [{ name: 'libc6', version: { operator: '>=', version: '2.34' } }],
//   [
//     { name: 'python3', arch: 'any' },
//     { name: 'python3', version: { operator: '>=', version: '3.8' }, architectures: ['amd64'] },
//   ],
//   [{ name: 'foo', profiles: [['!nocheck']] }],
// ]
```

*Read a multi-line field and list the package names*

Line breaks are plain whitespace, and a trailing comma is tolerated.

```typescript
parseDependencies('debhelper-compat (= 13),\n dh-python,\n pkg-config,\n', 'debian').map((group) => group[0].name)
// => ['debhelper-compat', 'dh-python', 'pkg-config']
```

*Reject an invalid field*

A fragment that is not valid throws a SyntaxError that quotes it.

```typescript
parseDependencies('libc6 (>= 2.34', 'debian')
// => throws SyntaxError: parseDependencies: unexpected "(>= 2.34" in "libc6 (>= 2.34" ...
```

*Read the obsolete < and > of old packages*

They are refused by default; compat mode reads them as dpkg does, <= and >=.

```typescript
parseDependencies('libfoo (< 2)', 'debian', { compat: true })
// => [[{ name: 'libfoo', version: { operator: '<=', version: '2' } }]]
```

*Read an RPM Requires, with an alternative*

Boolean dependencies (a or b) become the alternatives of a group.

```typescript
parseDependencies('glibc >= 2.28, (nginx or httpd)', 'rpm')
// => [[{ name: 'glibc', version: { operator: '>=', version: '2.28' } }], [{ name: 'nginx' }, { name: 'httpd' }]]
```

*Read a PKGBUILD depends array*

Quotes and the surrounding parentheses of the array are accepted.

```typescript
parseDependencies("('glibc>=2.38' bash)", 'arch')
// => [[{ name: 'glibc', version: { operator: '>=', version: '2.38' } }], [{ name: 'bash' }]]
```

*Read an Alpine depends list, with a conflict*

A leading ! marks a package that must not be installed.

```typescript
parseDependencies('musl>=1.2 !openrc', 'alpine')
// => [[{ name: 'musl', version: { operator: '>=', version: '1.2' } }], [{ name: 'openrc', conflict: true }]]
```

*Read Python requirements*

Extras, specifiers and the environment marker are separated; the marker is kept as written.

```typescript
parseDependencies('requests[security]>=2.8,<3 ; python_version < "3.12"', 'pep508')
// => [[{ name: 'requests', extras: ['security'], specifiers: [{ operator: '>=', version: '2.8' }, { operator: '<', version: '3' }], marker: 'python_version < "3.12"' }]]
```

---

### `Pep508Dependency`

One requirement of a PEP 508 dependency specification.

---

### `Pep508Operator`

The operators of a PEP 440 version specifier, as PEP 508 requirements use them.

---

### `RpmDependency`

One package reference of an RPM `Requires` field.

---

### `stringifyDependencies`

Writes dependency groups back as a field value, the inverse of parseDependencies; the
type of `groups` is that of `format`.

**`'debian'`** — the canonical spacing of the Debian Policy Manual 7.1: `, ` between entries,
` | ` between alternatives, a space before each `(op version)`, `[archs]` and `<profiles>`.
**`'rpm'`** — `, ` between entries, `name op version`, and `(a or b)` for alternatives.
**`'arch'`** — entries separated by a space, `name>=version`. **`'alpine'`** — the same, with a
leading `!` for a conflict. **`'pep508'`** — one requirement per line,
`name[extras]>=1,<2 ; marker`. The formats without alternatives (`'arch'`, `'alpine'`,
`'pep508'`) throw a `RangeError` for a group of several.

`parseDependencies(stringifyDependencies(groups, f), f)` gives `groups` back, and stringifying a
parsed field normalises its whitespace. An empty group writes nothing, so it does not survive a
round trip.

```typescript
import { stringifyDependencies } from '@helpers4/package';

stringifyDependencies<Format extends keyof DependencyFormats>(groups: readonly DependencyGroup<DependencyOf<NoInfer<Format>>>[], format: Format): string
```

**Parameters:**

- `groups: readonly DependencyGroup<DependencyOf<NoInfer<Format>>>[]` — The groups of alternatives, as returned by `parseDependencies`
- `format: Format` — How to write the field

**Returns:** `string` — The field value; `''` for `[]`

**Examples:**

*Write relationships as a field value*

Entries are joined with ", " and alternatives with " | ".

```typescript
stringifyDependencies([
  [{ name: 'libc6', version: { operator: '>=', version: '2.34' } }],
  [{ name: 'python3', arch: 'any' }, { name: 'python3' }],
], 'debian')
// => 'libc6 (>= 2.34), python3:any | python3'
```

*Normalise a field after editing it*

Parse, change the groups, write them back in canonical spacing.

```typescript
const groups = parseDependencies('libc6 (>=2.34) ,\n  foo [ amd64 ]', 'debian');
groups.push([{ name: 'bar', profiles: [['!nocheck']] }]);
stringifyDependencies(groups, 'debian')
// => 'libc6 (>= 2.34), foo [amd64], bar <!nocheck>'
```

*Write another format*

The same function writes RPM, Arch, Alpine and PEP 508 fields, each from its own dependency type.

```typescript
stringifyDependencies([[{ name: 'musl', version: { operator: '>=', version: '1.2' } }], [{ name: 'openrc', conflict: true }]], 'alpine')
// => 'musl>=1.2 !openrc'
```

---

## promise

Package: `@helpers4/promise`

### `consoleLogPromise`

Returns a function that logs data to the console and passes it through.

```typescript
import { consoleLogPromise } from '@helpers4/promise';

consoleLogPromise<T>(prefix?: string): function
```

**Parameters:**

- `prefix?: string` — Optional prefix for the console log

**Returns:** `function` — A function that logs and returns the data

**Examples:**

*Log and pass-through in a promise chain*

Creates a function that logs data with an optional prefix and returns it unchanged.

```typescript
Promise.resolve(42).then(consoleLogPromise('value:'))
// logs "value: 42" and resolves with 42
```

---

### `createMutex`

Creates a mutex: a lock allowing at most one holder at a time, queueing excess `acquire()`
callers in FIFO order. A createSemaphore with a single permit.

A factory function rather than a class, matching this package's other stateful helpers
(`debounce`, `throttle`): the returned object closes over an internal semaphore.

Typical use: deduplicating concurrent callers of a non-reentrant operation, e.g. making
sure only one in-flight token-refresh call happens at a time while others wait for it.

```typescript
import { createMutex } from '@helpers4/promise';

createMutex(): Mutex
```

**Returns:** `Mutex` — A Mutex

**Examples:**

*Deduplicate concurrent token refreshes*

Only one caller actually refreshes; the rest wait and reuse its result.

```typescript
const mutex = createMutex();
let cached: string | undefined;

async function getToken() {
  return mutex.run(async () => {
    if (cached) return cached;
    cached = await refreshToken(); // only ever runs once per cache miss
    return cached;
  });
}

await Promise.all([getToken(), getToken(), getToken()]);
// refreshToken() was called exactly once
```

*isLocked() reports whether the lock is currently held*

Useful for diagnostics or conditionally skipping work while locked.

```typescript
const mutex = createMutex();
mutex.isLocked() // => false
const release = await mutex.acquire();
mutex.isLocked() // => true
release();
mutex.isLocked() // => false
```

---

### `createSemaphore`

Creates a semaphore limiting concurrent access to `permits` holders at a time, queueing
excess `acquire()` callers in FIFO order (first to call `acquire` is first granted a
permit when one frees up).

A factory function rather than a class, matching this package's other stateful helpers
(`debounce`, `throttle`): the returned object closes over its internal queue/counter.

Use for concurrency limiting, e.g. rate-limiting calls to an external API. For
mutual-exclusion (at most one holder), see createMutex, which is a semaphore
with one permit.

```typescript
import { createSemaphore } from '@helpers4/promise';

createSemaphore(permits: number): Semaphore
```

**Parameters:**

- `permits: number` — Maximum number of concurrent holders. Must be `>= 1` (`Infinity` is
  accepted, for an effectively uncapped semaphore); a non-integer is floored (`2.9`
  behaves as `2`).

**Returns:** `Semaphore` — A Semaphore

**Examples:**

*Limit concurrent calls to an external API*

At most `permits` calls run at once; the rest queue and wait their turn.

```typescript
const semaphore = createSemaphore(2);
const results = await Promise.all(
  urls.map((url) => semaphore.run(() => fetch(url)))
);
// at most 2 fetch() calls in flight at any time
```

*run() releases the permit even on error*

Prefer run() over manual acquire()/release() — it cannot leak a permit.

```typescript
const semaphore = createSemaphore(1);
await semaphore.run(() => {
  throw new Error('oops');
}).catch(() => {});
semaphore.availablePermits() // => 1, the permit was released
```

*Manual acquire() returns a one-shot release function*

Calling the same release function twice throws — always caught, even under contention.

```typescript
const semaphore = createSemaphore(1);
const release = await semaphore.acquire();
release();
release(); // throws RangeError: this permit was already released
```

---

### `defer`

Runs an async function and guarantees that all deferred callbacks are
executed afterwards, in LIFO order (last registered = first executed),
regardless of whether the main work succeeds or throws.

Inspired by Radashi's `defer`. Useful for resource cleanup, temporary file
removal, or any "undo" logic that must run even on failure.

```typescript
import { defer } from '@helpers4/promise';

defer<T>(fn: function): Promise<T>
```

**Parameters:**

- `fn: function` — An async function that receives a `defer` registration function.

**Returns:** `Promise<T>` — The resolved value of `fn`.

**Examples:**

*Cleanup always runs*

Registered callbacks execute after the main function, even on success.

```typescript
const result = await defer(async (d) => {
  d(() => console.log('cleanup'));
  return 42;
});
// logs: 'cleanup' — result is 42
```

*LIFO order*

Multiple callbacks are called in reverse registration order.

```typescript
await defer(async (d) => {
  d(() => console.log('step 1'));
  d(() => console.log('step 2'));
  d(() => console.log('step 3'));
});
// logs: 'step 3', 'step 2', 'step 1'
```

*Cleanup runs even on failure*

Callbacks still execute when the main function throws; the error is re-thrown after.

```typescript
const releaseLock = () => console.log('lock released');
await defer(async (d) => {
  d(releaseLock);
  throw new Error('something failed');
}).catch(() => {});
// logs: 'lock released'
```

---

### `delay`

Creates a promise that resolves after specified delay

```typescript
import { delay } from '@helpers4/promise';

delay<T = void>(ms: number, value?: T, options: DelayOptions): Promise<T>
```

**Parameters:**

- `ms: number` — Milliseconds to delay
- `value?: T` — Optional value to resolve with
- `options: DelayOptions` (default: `{}`) — Cancellation — see DelayOptions

**Returns:** `Promise<T>` — Promise that resolves after delay, or rejects with the signal's reason if aborted first

**Examples:**

*Wait a specified duration*

Creates a promise that resolves after the given milliseconds.

```typescript
await delay(100)
// resolves after 100ms
```

*Resolve with a value*

Optionally resolves with a provided value.

```typescript
const result = await delay(100, 'done')
// => 'done'
```

*Cancel the wait*

An aborted signal clears the timer and rejects with its reason, so nothing is left running on teardown.

```typescript
const controller = new AbortController()
const wait = delay(5000, undefined, { signal: controller.signal })
controller.abort('disabled')
await wait
// rejects with 'disabled', at once
```

---

### `falsyPromiseOrThrow`

Returns a function that passes through falsy data or throws an error.

```typescript
import { falsyPromiseOrThrow } from '@helpers4/promise';

falsyPromiseOrThrow<T>(error: string): function
```

**Parameters:**

- `error: string` — The error message to throw if data is truthy

**Returns:** `function` — A function that returns the data if falsy, or throws

**Examples:**

*Pass through falsy values*

Returns the value if falsy, throws otherwise.

```typescript
Promise.resolve(null).then(falsyPromiseOrThrow('Expected falsy'))
// => null
```

*Throw on truthy values*

Throws an error when the value is truthy.

```typescript
Promise.resolve('oops').then(falsyPromiseOrThrow('Should be empty'))
// throws Error('Should be empty')
```

---

### `fetchJson`

Fetches a URL and returns its parsed JSON body, retrying transient failures (network errors,
`5xx` and `429`).

```typescript
import { fetchJson } from '@helpers4/promise';

fetchJson<T>(input: RequestInfo | URL, init?: RequestInit, options: FetchJsonOptions): Promise<T>
```

**Parameters:**

- `input: RequestInfo | URL` — URL or `Request` object passed to `fetch`
- `init?: RequestInit` — Optional `RequestInit` options passed to `fetch`
- `options: FetchJsonOptions` (default: `{}`) — Retry configuration — see FetchJsonOptions

**Returns:** `Promise<T>` — The parsed JSON body

**Examples:**

*fetchJson*

```typescript
```ts
const repo = await fetchJson<{ stars: number }>('https://api.example.com/repo');
```
```

---

### `fetchOrThrow`

Wraps `fetch` so that a non-2xx response rejects with an HttpError.

```typescript
import { fetchOrThrow } from '@helpers4/promise';

fetchOrThrow(input: RequestInfo | URL, init?: RequestInit): Promise<Response>
```

**Parameters:**

- `input: RequestInfo | URL` — URL or `Request` object passed to `fetch`
- `init?: RequestInit` — Optional `RequestInit` options passed to `fetch`

**Returns:** `Promise<Response>` — The response, body unread, when its status is 2xx

**Examples:**

*fetchOrThrow*

```typescript
```ts
const response = await fetchOrThrow('https://api.example.com/repo');
```
```

---

### `guard`

Wraps a function so that if it throws, a default value is returned instead of propagating the error.
Works with both synchronous and asynchronous functions.

```typescript
import { guard } from '@helpers4/promise';

guard<T>(fn: function, defaultValue: T): Promise<T>
```

**Parameters:**

- `fn: function` — The function to guard
- `defaultValue: T` — The value to return if the function throws

**Returns:** `Promise<T>` — The result of the function, or the default value on error

```typescript
import { guard } from '@helpers4/promise';

guard<T>(fn: function, defaultValue: T): T
```

**Parameters:**

- `fn: function` — The function to guard
- `defaultValue: T` — The value to return if the function throws

**Returns:** `T` — The result of the function, or the default value on error

**Examples:**

*Fallback on parse error*

Returns a default value when the function throws.

```typescript
const result = guard(() => JSON.parse('invalid'), {})
// => {}
```

*Pass-through on success*

Returns the function result when it does not throw.

```typescript
const result = guard(() => JSON.parse('{"a":1}'), {})
// => { a: 1 }
```

---

### `meaningPromiseOrThrow`

Returns a function that passes through meaningful data or throws an error.
Data is considered meaningless if it is null, undefined, empty string, empty object, or empty array.

```typescript
import { meaningPromiseOrThrow } from '@helpers4/promise';

meaningPromiseOrThrow<T>(error: string): function
```

**Parameters:**

- `error: string` — The error message to throw if data is meaningless

**Returns:** `function` — A function that returns the data if meaningful, or throws

**Examples:**

*Pass through meaningful values*

Returns the value if it is not empty (null, undefined, empty string, empty object, empty array).

```typescript
Promise.resolve({ key: 'value' }).then(meaningPromiseOrThrow('No data'))
// => { key: 'value' }
```

*Throw on empty values*

Throws when the value is null, undefined, empty string, empty object, or empty array.

```typescript
Promise.resolve({}).then(meaningPromiseOrThrow('Empty!'))
// throws Error('Empty!')
```

---

### `paginate`

Collects every item of a paginated source by requesting pages one after the other, from
page 1, until the source runs out.

It stops after a page that is `null`, empty, or shorter than `pageSize`, or once `maxPages`
pages were requested. A `null` page is not added to the result. A rejection from
`fetchPage` rejects the whole call, and the items already collected are lost.

Without `maxPages`, a source that never returns a short or empty page is requested forever,
so set one for an API you do not control, or a `signal` to stop it.

```typescript
import { paginate } from '@helpers4/promise';

paginate<T>(fetchPage: function, options: PaginateOptions): Promise<T[]>
```

**Parameters:**

- `fetchPage: function` — Returns the items of a page, given its 1-based number, or `null` for no data
- `options: PaginateOptions` (default: `{}`) — Page size, page limit and cancellation — see PaginateOptions

**Returns:** `Promise<T[]>` — All the items, in page order

**Examples:**

*Collect every page*

Pages are requested in order until one is shorter than pageSize.

```typescript
const all = [1, 2, 3, 4, 5];
await paginate((page) => Promise.resolve(all.slice((page - 1) * 2, page * 2)), { pageSize: 2 })
// => [1, 2, 3, 4, 5] (3 requests)
```

*Cap the number of pages*

maxPages protects against a source that never runs out.

```typescript
await paginate((page) => Promise.resolve([page]), { maxPages: 3 })
// => [1, 2, 3]
```

---

### `parallel`

Runs an array of async functions with a concurrency limit.
At most `limit` functions will be running at any time. `Infinity` means no cap (every
function starts immediately); any other non-finite or non-positive value (`NaN`, `0`,
negative) is clamped to `1` (fully sequential) rather than rejected.

```typescript
import { parallel } from '@helpers4/promise';

parallel<T>(functions: readonly function[], limit: number, options: ParallelOptions): Promise<T[]>
```

**Parameters:**

- `functions: readonly function[]` — Array of functions that return promises
- `limit: number` — Maximum number of concurrent executions
- `options: ParallelOptions` (default: `{}`) — Cancellation — see ParallelOptions

**Returns:** `Promise<T[]>` — Promise that resolves with an array of results in the same order as the input, or
  rejects with the signal's reason if aborted first

**Examples:**

*Run tasks with concurrency limit*

Executes async functions with at most N running concurrently.

```typescript
const results = await parallel(
  [() => fetch('/a'), () => fetch('/b'), () => fetch('/c')],
  2
)
// At most 2 requests run at a time; results are in order
```

*Sequential execution with limit of 1*

Setting limit to 1 runs functions one at a time.

```typescript
await parallel([fnA, fnB, fnC], 1)
// Runs fnA, then fnB, then fnC
```

---

### `parallelSettle`

Runs an array of async functions with a concurrency limit, partitioning the outcomes
instead of rejecting on the first failure — parallel with settle's
fulfilled/rejected split.

Takes functions (not already-created promises, unlike settle) so it controls
*when* each one starts: that's what makes the concurrency limit meaningful. At most
`concurrency` functions run at any time; as soon as one settles, the next queued
function starts.

```typescript
import { parallelSettle } from '@helpers4/promise';

parallelSettle<T>(functions: readonly function[], concurrency: number, options: ParallelOptions): Promise<object>
```

**Parameters:**

- `functions: readonly function[]` — Array of functions that return promises
- `concurrency: number` — Maximum number of concurrent executions. `Infinity` means no cap; any
  other non-finite or non-positive value (`NaN`, `0`, negative) is clamped to `1` (fully
  sequential) rather than rejected.
- `options: ParallelOptions` (default: `{}`) — Cancellation — see ParallelOptions. An abort is not an outcome: it
  rejects the whole call with the signal's reason.

**Returns:** `Promise<object>` — An object with `fulfilled` values and `rejected` reasons, each in input order

**Examples:**

*Limit concurrency without one failure stopping the rest*

Runs at most `concurrency` functions at a time and partitions outcomes instead of rejecting on the first failure.

```typescript
const { fulfilled, rejected } = await parallelSettle(
  [() => fetch('/a'), () => fetch('/b'), () => fetch('/c')],
  2
)
// At most 2 requests run at a time; a failing request doesn't stop the others
```

*All functions succeed*

Returns an empty rejected array when nothing fails.

```typescript
const { fulfilled, rejected } = await parallelSettle(
  [() => Promise.resolve('a'), () => Promise.resolve('b')],
  2
)
// => { fulfilled: ['a', 'b'], rejected: [] }
```

---

### `resolveRecord`

Resolves an array of keys into a record by calling an async mapper for each key.
All mapper calls run concurrently via `Promise.all`.

Unlike parallel, which returns an array, `resolveRecord` preserves the
key-to-value relationship in the result.

```typescript
import { resolveRecord } from '@helpers4/promise';

resolveRecord<K extends PropertyKey, V>(keys: readonly K[], mapper: function): Promise<Record<K, V>>
```

**Parameters:**

- `keys: readonly K[]` — The keys to resolve
- `mapper: function` — Async function called for each key, returning the associated value

**Returns:** `Promise<Record<K, V>>` — A record mapping each key to its resolved value

**Examples:**

*Fetch data for multiple keys concurrently*

All mapper calls run in parallel via Promise.all.

```typescript
const stars = await resolveRecord(
  ['helpers4/typescript', 'helpers4/devcontainer'],
  async (repo) => fetchRepoStars(repo)
);
// => { 'helpers4/typescript': 42, 'helpers4/devcontainer': 17 }
```

---

### `retry`

Retries a promise-returning function until it succeeds or runs out of attempts, then rejects
with the last error, waiting a fixed delay between attempts.

For a delay that grows or for retrying only some errors, pass a RetryOptions object instead.

```typescript
import { retry } from '@helpers4/promise';

retry<T>(fn: function, maxAttempts?: number, delayMs?: number): Promise<T>
```

**Parameters:**

- `fn: function` — The function to retry, called with the 1-based number of the attempt
- `maxAttempts?: number` — Maximum number of attempts, the first one included (default `3`)
- `delayMs?: number` — Delay between attempts in milliseconds (default `1000`)

**Returns:** `Promise<T>` — Promise that resolves with the result or rejects with the last error

```typescript
import { retry } from '@helpers4/promise';

retry<T>(fn: function, options: RetryOptions): Promise<T>
```

**Parameters:**

- `fn: function` — The function to retry, called with the 1-based number of the attempt
- `options: RetryOptions` — Attempts, delay and retry predicate

**Returns:** `Promise<T>` — Promise that resolves with the result or rejects with the last error

**Examples:**

*Retry a failing function*

Retries the function up to maxAttempts times before giving up.

```typescript
let attempt = 0;
await retry(() => {
  attempt++;
  if (attempt < 3) throw new Error('not yet');
  return Promise.resolve('success');
}, 3, 10)
// => 'success' (after 2 failures)
```

*Exponential backoff*

Pass a function as delayMs to make the wait grow after each failed attempt.

```typescript
const waits: number[] = [];
await retry(() => Promise.reject(new Error('down')), {
  attempts: 4,
  delayMs: (attempt) => {
    const ms = 2 ** (attempt - 1); // 1, 2, 4
    waits.push(ms);
    return ms;
  },
}).catch(() => {});
// waits => [1, 2, 4]
```

*Only retry some errors*

shouldRetry rethrows anything it rejects at once, without waiting or retrying.

```typescript
let attempt = 0;
await retry(() => {
  attempt++;
  return Promise.reject(new Error('invalid input'));
}, { attempts: 5, delayMs: 10, shouldRetry: (error) => /timeout/.test(String(error)) })
// => rejects with 'invalid input' after a single attempt
```

*Rotate through mirrors*

fn receives the 1-based attempt number, so each retry can target the next server.

```typescript
const mirrors = ['a', 'b', 'c'];
await retry((attempt) => {
  const mirror = mirrors[(attempt - 1) % mirrors.length];
  return mirror === 'c' ? Promise.resolve(mirror) : Promise.reject(new Error('down'));
}, { attempts: 3, delayMs: 0 })
// => 'c' (after 'a' and 'b' failed)
```

*Stop retrying*

An aborted signal clears the wait between attempts and starts no new one.

```typescript
const controller = new AbortController();
const result = retry(() => fetchData(), { delayMs: 5000, signal: controller.signal });
controller.abort('disabled');
await result
// rejects with 'disabled', without waiting the 5 s
```

---

### `safeFetch`

Wraps `fetch` and returns `null` when the request fails (network error, non-OK status, or parse
error) instead of throwing.

```typescript
import { safeFetch } from '@helpers4/promise';

safeFetch<T>(input: RequestInfo | URL, init?: RequestInit, options: SafeFetchOptions): Promise<T | null>
```

**Parameters:**

- `input: RequestInfo | URL` — URL or `Request` object passed to `fetch`
- `init?: RequestInit` — Optional `RequestInit` options passed to `fetch`
- `options: SafeFetchOptions` (default: `{}`) — Parsing options (default: `{ parse: 'json' }`)

**Returns:** `Promise<T | null>` — The parsed response body, or `null` on any failure

**Examples:**

*safeFetch*

```typescript
```ts
const data = await safeFetch<{ stars: number }>('https://api.example.com/repo');
```
```

---

### `settle`

Runs an array of promises concurrently and partitions the outcomes instead of
rejecting on the first failure, unlike `Promise.all`.
Built on top of `Promise.allSettled`, but returns fulfilled values and rejection
reasons already split apart so callers don't need to inspect `status` themselves.

No concurrency limit, and none is possible here: `promises` are already-constructed
`Promise` objects, and a promise starts running the moment it's created — by the time
`settle` receives the array, every promise in it is already in flight. There is
nothing left to throttle. If you need to cap how many run at once (e.g. many file
reads or requests), use parallelSettle instead, which takes functions
(`() => Promise<T>`) so it controls *when* each one starts.

```typescript
import { settle } from '@helpers4/promise';

settle<T>(promises: readonly Promise<T>[]): Promise<object>
```

**Parameters:**

- `promises: readonly Promise<T>[]` — Promises to run concurrently

**Returns:** `Promise<object>` — An object with `fulfilled` values and `rejected` reasons, each in input order

**Examples:**

*Partition fulfilled and rejected outcomes*

Runs promises concurrently and splits results instead of rejecting on the first failure.

```typescript
const { fulfilled, rejected } = await settle([
  Promise.resolve(1),
  Promise.reject(new Error('boom')),
  Promise.resolve(3),
])
// => { fulfilled: [1, 3], rejected: [Error('boom')] }
```

*All promises succeed*

Returns an empty rejected array when nothing fails.

```typescript
const { fulfilled, rejected } = await settle([Promise.resolve('a'), Promise.resolve('b')])
// => { fulfilled: ['a', 'b'], rejected: [] }
```

---

### `timeout`

Wraps a promise to reject with a `TimeoutError` if it does not resolve within the specified duration.

The timer is cleared as soon as `promise` settles. If it may never settle, pass a `signal` so
the timer can be cleared on teardown too.

```typescript
import { timeout } from '@helpers4/promise';

timeout<T>(promise: Promise<T>, ms: number, options: TimeoutOptions): Promise<T>
```

**Parameters:**

- `promise: Promise<T>` — The promise to wrap
- `ms: number` — Timeout duration in milliseconds
- `options: TimeoutOptions` (default: `{}`) — Cancellation — see TimeoutOptions

**Returns:** `Promise<T>` — A promise that rejects with `TimeoutError` if the timeout is exceeded, or with the
  signal's reason if aborted first

**Examples:**

*Reject a slow promise*

Throws a TimeoutError if the promise does not resolve in time.

```typescript
await timeout(fetch('/api/data'), 5000)
// Rejects with TimeoutError if fetch takes longer than 5s
```

*Resolve fast promise normally*

Returns the value if the promise resolves before the timeout.

```typescript
const result = await timeout(Promise.resolve('fast'), 1000)
// => 'fast'
```

*Cancel the timeout*

An aborted signal clears the timer even if the promise never settles.

```typescript
const controller = new AbortController()
const result = timeout(new Promise(() => {}), 5000, { signal: controller.signal })
controller.abort('disabled')
await result
// rejects with 'disabled', at once
```

---

### `truthyPromiseOrThrow`

Returns a function that passes through truthy data or throws an error.

```typescript
import { truthyPromiseOrThrow } from '@helpers4/promise';

truthyPromiseOrThrow<T>(error: string): function
```

**Parameters:**

- `error: string` — The error message to throw if data is falsy

**Returns:** `function` — A function that returns the data if truthy, or throws

**Examples:**

*Pass through truthy values*

Returns the value if truthy, throws otherwise.

```typescript
Promise.resolve('data').then(truthyPromiseOrThrow('No data'))
// => 'data'
```

*Throw on falsy values*

Throws an error when the value is falsy.

```typescript
Promise.resolve('').then(truthyPromiseOrThrow('Empty!'))
// throws Error('Empty!')
```

---

### `tryit`

Wraps a function so it never throws. Instead, it returns a `[error, result]` tuple.
Useful for avoiding try/catch blocks and handling errors in a functional style.

```typescript
import { tryit } from '@helpers4/promise';

tryit<TArgs extends readonly unknown[], TReturn>(fn: function): function
```

**Parameters:**

- `fn: function` — The function to wrap (sync or async)

**Returns:** `function` — A new function that returns a `Result` tuple

**Examples:**

*Safe JSON parsing*

Wraps JSON.parse to return a tuple instead of throwing.

```typescript
const safeParse = tryit(JSON.parse);
const [error, data] = safeParse('{"a":1}');
// error === undefined, data === { a: 1 }
```

*Catching errors without try/catch*

On error, the first element of the tuple is the Error.

```typescript
const safeParse = tryit(JSON.parse);
const [error, data] = safeParse('invalid');
// error instanceof SyntaxError, data === undefined
```

---

## set

Package: `@helpers4/set`

### `countBy`

Groups the values of a Set by a derived key and counts how many fall into each group.

```typescript
import { countBy } from '@helpers4/set';

countBy<T, R>(set: ReadonlySet<T>, fn: function): Map<R, number>
```

**Parameters:**

- `set: ReadonlySet<T>` — The Set to summarize
- `fn: function` — Function deriving the grouping key from each value

**Returns:** `Map<R, number>` — A Map from derived key to the number of values in that group

**Examples:**

*Count values by parity*

Groups values by a derived key and counts how many fall into each group.

```typescript
countBy(new Set([1, 2, 3, 4]), v => v % 2 === 0 ? 'even' : 'odd')
// => Map(2) { 'odd' => 2, 'even' => 2 }
```

---

### `filter`

Creates a new Set containing only the values for which the predicate returns true.

```typescript
import { filter } from '@helpers4/set';

filter<T>(set: ReadonlySet<T>, predicate: function): Set<T>
```

**Parameters:**

- `set: ReadonlySet<T>` — The Set to filter
- `predicate: function` — Function invoked with each value — return true to keep it

**Returns:** `Set<T>` — A new Set with only the matching values

**Examples:**

*Keep only even values*

Creates a new Set with only the values that satisfy the predicate.

```typescript
filter(new Set([1, 2, 3, 4]), value => value % 2 === 0)
// => Set(2) { 2, 4 }
```

---

### `map`

Creates a new Set with each value transformed by a function. If two values transform to the
same result, duplicates collapse — the returned Set may be smaller than the input.

```typescript
import { map } from '@helpers4/set';

map<T, R>(set: ReadonlySet<T>, fn: function): Set<R>
```

**Parameters:**

- `set: ReadonlySet<T>` — The Set to transform
- `fn: function` — Function invoked with each value, returning the new value

**Returns:** `Set<R>` — A new Set of transformed values

**Examples:**

*Transform every value*

Creates a new Set with each value transformed by a function.

```typescript
map(new Set([1, 2, 3]), value => value * 10)
// => Set(3) { 10, 20, 30 }
```

*Duplicates collapse*

If two values transform to the same result, the Set naturally deduplicates.

```typescript
map(new Set([1, 2, 3]), () => 'same')
// => Set(1) { 'same' }
```

---

### `toMapByKey`

Builds a Map from a Set, keyed by a derived key. When two values derive the same key,
the later value (in iteration order) wins (last-write-wins, matching `Map.prototype.set`).

Named `toMapByKey`, not `keyBy` (lodash's name for the same idea) — lodash's `_.keyBy`
returns a plain object, not a `Map`; the `to<Type>` prefix (matching `toSorted`/`toReversed`)
makes the actual return type unambiguous.

```typescript
import { toMapByKey } from '@helpers4/set';

toMapByKey<T, K>(set: ReadonlySet<T>, fn: function): Map<K, T>
```

**Parameters:**

- `set: ReadonlySet<T>` — The Set to index
- `fn: function` — Function deriving the key for each value

**Returns:** `Map<K, T>` — A Map from derived key to value

**Examples:**

*Turn a Set into a lookup Map*

Builds a Map keyed by a derived value, for O(1) lookup by that key.

```typescript
toMapByKey(new Set([{ id: 'a' }, { id: 'b' }]), item => item.id)
// => Map(2) { 'a' => {...}, 'b' => {...} }
```

---

## string

Package: `@helpers4/string`

### `camelCase`

Converts a string to camelCase.
Handles PascalCase, kebab-case, snake_case, spaces, and mixed formats.

An embedded run of capitals is treated as an acronym boundary: only its last letter starts
the next word, the rest are lowercased (matching lodash's `camelCase` convention) — so an
already-camelCase identifier containing an acronym is not left untouched.

```typescript
import { camelCase } from '@helpers4/string';

camelCase(str: string): string
```

**Parameters:**

- `str: string` — The string to convert

**Returns:** `string` — String in camelCase

```typescript
import { camelCase } from '@helpers4/string';

camelCase(str: undefined): undefined
```

**Parameters:**

- `str: undefined` — The string to convert

**Returns:** `undefined` — String in camelCase

```typescript
import { camelCase } from '@helpers4/string';

camelCase(str: null): null
```

**Parameters:**

- `str: null` — The string to convert

**Returns:** `null` — String in camelCase

**Examples:**

*Convert kebab-case to camelCase*

Converts a kebab-case string to camelCase.

```typescript
camelCase('my-component-name')
// => 'myComponentName'
```

---

### `capitalize`

Capitalizes the first letter of a string.
By default, lowercases the remaining characters.
Pass `{ lowercaseRest: false }` to only uppercase the first character.

```typescript
import { capitalize } from '@helpers4/string';

capitalize(str: string, options?: CapitalizeOptions): string
```

**Parameters:**

- `str: string` — The string to capitalize
- `options?: CapitalizeOptions` — Options

**Returns:** `string` — String with first letter uppercased

```typescript
import { capitalize } from '@helpers4/string';

capitalize(str: undefined, options?: CapitalizeOptions): undefined
```

**Parameters:**

- `str: undefined` — The string to capitalize
- `options?: CapitalizeOptions` — Options

**Returns:** `undefined` — String with first letter uppercased

```typescript
import { capitalize } from '@helpers4/string';

capitalize(str: null, options?: CapitalizeOptions): null
```

**Parameters:**

- `str: null` — The string to capitalize
- `options?: CapitalizeOptions` — Options

**Returns:** `null` — String with first letter uppercased

**Examples:**

*Capitalize a word*

Uppercases the first letter and lowercases the rest.

```typescript
capitalize('hello')
// => 'Hello'
```

*Handle mixed case*

Lowercases all letters except the first one (default behaviour).

```typescript
capitalize('hELLO')
// => 'Hello'
```

*Uppercase first only — leave rest untouched*

Use { lowercaseRest: false } to preserve the original casing of the remaining characters.

```typescript
capitalize('hELLO', { lowercaseRest: false })
// => 'HELLO'
```

---

### `createGlobMatcher`

createMatcher with every string read as a glob (`*`, `?`): no string is ever taken
for a regular expression, so it never throws. The right choice for paths and file names.

```typescript
import { createGlobMatcher } from '@helpers4/string';

createGlobMatcher(pattern: MatcherPattern | readonly MatcherPattern[], options: Omit<MatcherOptions, "syntax">): function
```

**Parameters:**

- `pattern: MatcherPattern | readonly MatcherPattern[]` — A pattern, or an array of patterns and `!` exclusions
- `options: Omit<MatcherOptions, "syntax">` (default: `{}`) — Case sensitivity

**Returns:** `function` — A function telling whether a string matches

**Examples:**

*Filter paths*

Strings are always globs, so a path is never taken for a regular expression.

```typescript
const isSource = createGlobMatcher(['/src/*.ts', '!*.test.ts']);
isSource('/src/index.ts')      // => true
isSource('/src/index.test.ts') // => false
```

*Ignore case*

caseSensitive: false matches letters of any case.

```typescript
createGlobMatcher('*.FIG', { caseSensitive: false })('a.fig') // => true
```

---

### `createMatcher`

Turns user-supplied filters (a setting, a CLI flag, a list of rules) into one predicate.

- A string is a glob, or a regular expression — see MatcherOptions.syntax. A `re:` or
  `glob:` prefix (`'re:^v\\d+$'`, `'glob:*.ts'`) fixes the reading of that one pattern when the
  syntax is `'auto'` (the default); with an explicit `'glob'` or `'regex'` syntax the prefixes
  are plain text, so createGlobMatcher never reads a regular expression. To match a
  string that really starts with one of them under `'auto'`, spell it `'glob:re:…'`.
- A `RegExp` is used as is, except that its `g` and `y` flags are dropped: they make
  `test()` depend on the previous call.
- A function is called as is.
- An array matches when one of its patterns matches and none of its exclusions does. An
  exclusion is a string starting with `!` (`'!draft-*'`); write `'\\!'` for a pattern that really
  starts with `!`. The order does not matter. An array with only exclusions matches everything
  else, and an empty array matches everything (no filter).

```typescript
import { createMatcher } from '@helpers4/string';

createMatcher(pattern: MatcherPattern | readonly MatcherPattern[], options: MatcherOptions): function
```

**Parameters:**

- `pattern: MatcherPattern | readonly MatcherPattern[]` — A pattern, or an array of patterns and exclusions
- `options: MatcherOptions` (default: `{}`) — Syntax of string patterns and case sensitivity — see MatcherOptions

**Returns:** `function` — A function telling whether a string matches

**Examples:**

*Filter names with globs, regular expressions and exclusions*

An array matches when one pattern matches and no ! exclusion does.

```typescript
const isScreen = createMatcher(['Screen *', '/^(Home|Login)$/', '!* (old)']);
isScreen('Screen 2')       // => true
isScreen('Login')          // => true
isScreen('Screen 2 (old)') // => false
```

*Paths only*

With syntax 'glob', a pattern like /usr/lib/img is never read as a regular expression.

```typescript
createMatcher('/usr/lib/*', { syntax: 'glob' })('/usr/lib/img') // => true
```

*Fix the reading of one pattern with re: or glob:*

A prefix overrides the syntax option for that pattern only, so globs and regular expressions mix freely.

```typescript
const matches = createMatcher(['glob:src/*', 're:\\.tsx?$', '!re:test']);
matches('lib/b.ts')      // => true
matches('lib/b.test.ts') // => false
```

---

### `createRegexMatcher`

createMatcher with every string read as the source of a regular expression, without
slashes or flags (`'^(Home|Login)$'`): for a setting documented as "a regular expression".

```typescript
import { createRegexMatcher } from '@helpers4/string';

createRegexMatcher(pattern: MatcherPattern | readonly MatcherPattern[], options: Omit<MatcherOptions, "syntax">): function
```

**Parameters:**

- `pattern: MatcherPattern | readonly MatcherPattern[]` — A pattern, or an array of patterns and `!` exclusions
- `options: Omit<MatcherOptions, "syntax">` (default: `{}`) — Case sensitivity (adds the `i` flag when `false`)

**Returns:** `function` — A function telling whether a string matches

**Examples:**

*A setting documented as a regular expression*

The string is the source, without slashes.

```typescript
createRegexMatcher('^(Home|Login)$')('Login') // => true
```

*Ignore case*

caseSensitive: false adds the i flag.

```typescript
createRegexMatcher('^icon-\\d+$', { caseSensitive: false })('Icon-42') // => true
```

---

### `createSafeMatcher`

Like createMatcher, but returns `null` instead of throwing when a string pattern is an
invalid regular expression, to report bad user input without a `try`.

```typescript
import { createSafeMatcher } from '@helpers4/string';

createSafeMatcher(pattern: MatcherPattern | readonly MatcherPattern[], options?: MatcherOptions): function | null
```

**Parameters:**

- `pattern: MatcherPattern | readonly MatcherPattern[]` — A pattern, or an array of patterns and exclusions
- `options?: MatcherOptions` — Syntax of string patterns and case sensitivity — see MatcherOptions

**Returns:** `function | null` — A function telling whether a string matches, or `null` for an invalid regular expression

**Examples:**

*Validate a user filter*

An invalid regular expression gives null, to report it without a try.

```typescript
const matches = createSafeMatcher(input);
if (!matches) console.error('Invalid filter');
```

*Use it like createMatcher*

For valid patterns, the result is the same predicate.

```typescript
createSafeMatcher('*.fig')?.('a.fig') // => true
```

---

### `dedent`

Strips the common leading whitespace from every line of a multi-line
string, and trims a single leading/trailing blank line if present.

Lets you write readable, indented multi-line strings in source code
(typically template literals) without that indentation leaking into
the output.

```typescript
import { dedent } from '@helpers4/string';

dedent(str: string): string
```

**Parameters:**

- `str: string` — The string to dedent

**Returns:** `string` — The dedented string

**Examples:**

*Write readable multi-line strings without leaking source indentation*

Strips the common leading whitespace and the wrapping blank lines.

```typescript
dedent(`
  Hello
    World
`)
// => 'Hello\n  World'
```

*The minimum indentation across all lines is what gets removed*

Lines with more indentation than the minimum keep their relative indent.

```typescript
dedent('    a\n  b\n      c')
// => '  a\nb\n    c'
```

---

### `deobfuscate`

Reverses obfuscate. Never throws: a token that `obfuscate` could not have produced
(another alphabet, padding, broken length, bytes that are not UTF-8, not a string) gives `null`.

```typescript
import { deobfuscate } from '@helpers4/string';

deobfuscate(token: string): string | null
```

**Parameters:**

- `token: string` — A token returned by obfuscate

**Returns:** `string | null` — The original text, or `null` for an invalid token

**Examples:**

*Rebuild the address in the browser*

Reverses obfuscate, in Node.js and in browsers alike.

```typescript
deobfuscate('bW9jLmVscG1heGVAZW0')
// => 'me@example.com'
```

*A bad token gives null*

It never throws, so the caller just checks for null.

```typescript
deobfuscate('not a token!')
// => null
```

---

### `escapeHtml`

Escapes the HTML special characters `&`, `<`, `>`, `"`, and `'` in a string.

Use this to safely embed untrusted content into HTML attribute values or
text nodes without risk of XSS injection.

```typescript
import { escapeHtml } from '@helpers4/string';

escapeHtml(str: string): string
```

**Parameters:**

- `str: string` — The string to escape.

**Returns:** `string` — The escaped string.

**Examples:**

*Escape script tags*

Converts < > " ' & to their HTML entities to prevent XSS.

```typescript
escapeHtml('<script>alert("xss")</script>')
// => '&lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;'
```

*Safe interpolation in templates*

Safe for inserting untrusted strings into HTML.

```typescript
const userInput = '<b>bold</b>';
escapeHtml(userInput) // => '&lt;b&gt;bold&lt;/b&gt;'
```

---

### `escapeRegExp`

Escapes regular expression metacharacters (`. * + ? ^ $ { } ( ) | [ ] \`)
in a string so it can be safely embedded in a `RegExp` pattern.

Use this before building a `RegExp` from untrusted or dynamic input — without
it, characters like `.` or `(` change the pattern's meaning instead of being
matched literally.

```typescript
import { escapeRegExp } from '@helpers4/string';

escapeRegExp(str: string): string
```

**Parameters:**

- `str: string` — The string to escape

**Returns:** `string` — The escaped string, safe to embed in a `RegExp` pattern

**Examples:**

*Escape metacharacters before building a RegExp*

Without escaping, "." and "?" would change the pattern's meaning.

```typescript
escapeRegExp('1 + 1 = 2?')
// => '1 \\+ 1 = 2\\?'
```

*Safely search for untrusted user input*

Escaping lets user-provided text be matched literally instead of as a pattern.

```typescript
const userInput = 'a.b';
new RegExp(escapeRegExp(userInput)).test('a.b')   // => true
new RegExp(escapeRegExp(userInput)).test('axb')   // => false (literal '.', not "any char")
```

---

### `excerpt`

Derives a short, readable excerpt from a longer text — for a card/header/preview where a full
paragraph doesn't fit. Unlike truncate (a mechanical cut at exactly `maxLength`), this
prefers to cut at the end of a whole sentence (`.`, `!`, or `?`) when one fits within
`maxLength`, even if that leaves the result shorter than the limit. Only when no sentence fits
does it fall back to the last whole word before the limit — it never returns partial-word text.

Known limitation: the sentence-boundary check is a simple heuristic (punctuation followed by
whitespace or the end of the text) — it doesn't special-case abbreviations ("Mr.") or decimal
numbers ("3.14"), which can be misread as a sentence end.

```typescript
import { excerpt } from '@helpers4/string';

excerpt(text: string, maxLength: number, ellipsis: string): string
```

**Parameters:**

- `text: string` — The text to excerpt. Internal whitespace (line breaks, repeated spaces) is
collapsed to single spaces before measuring length.
- `maxLength: number` — Maximum length of the result, including `ellipsis` when one is appended.
- `ellipsis: string` (default: `'…'`) — Appended only when falling back to a word-boundary cut (a sentence-boundary
cut never needs one). Defaults to `'…'`.

**Returns:** `string` — The original text unchanged if already within `maxLength`, otherwise a shortened version

**Examples:**

*Cut at the end of a whole sentence*

Prefers a clean sentence break over a hard character cutoff, even if the result ends up shorter than maxLength.

```typescript
excerpt(
  'Build the biggest, best theme park rides ever seen. Can you make money in this business?',
  60,
)
// => 'Build the biggest, best theme park rides ever seen.'
```

*Fall back to the last whole word*

No sentence boundary fits, so it cuts at the last complete word and appends an ellipsis — never a partial word.

```typescript
excerpt('This description has no punctuation at all so it must cut on a word', 30)
// => 'This description has no…'
```

*Already short enough — returned unchanged*

Only whitespace is normalized; nothing is cut when the text already fits.

```typescript
excerpt('A short game about ducks.', 200)
// => 'A short game about ducks.'
```

---

### `extractErrorMessage`

Convert an error to a readable message.

```typescript
import { extractErrorMessage } from '@helpers4/string';

extractErrorMessage(error: unknown, stringify: string | true): string
```

**Parameters:**

- `error: unknown` — an error
- `stringify: string | true` — stringifies the error if no extractable message is found

**Returns:** `string` — a readable message or a stringified error if stringify is true, otherwise undefined

```typescript
import { extractErrorMessage } from '@helpers4/string';

extractErrorMessage(error?: unknown, stringify?: string | boolean): string | undefined
```

**Parameters:**

- `error?: unknown` — an error
- `stringify?: string | boolean` — stringifies the error if no extractable message is found

**Returns:** `string | undefined` — a readable message or a stringified error if stringify is true, otherwise undefined

**Examples:**

*Extract message from Error object*

Returns the stringified Error, including the class prefix.

```typescript
extractErrorMessage(new Error('Something went wrong'))
// => 'Error: Something went wrong'
```

*Handle string errors*

Returns the string directly when the error is a plain string.

```typescript
extractErrorMessage('plain error')
// => 'plain error'
```

*Stringify unknown errors*

When stringify is true, falls back to JSON.stringify for unrecognized errors.

```typescript
extractErrorMessage(42, true)
// => '42'
```

---

### `formatProgressBar`

Formats a value as a text progress bar, repeating `filledChar`/`emptyChar` across `width`
cells proportional to `value / max`.

`value` is clamped to `[0, max]` before computing the ratio — out-of-range values (negative,
above `max`) produce an empty or fully-filled bar instead of throwing. Non-finite `max`
(`NaN`, `Infinity`) is treated as `0`, yielding an empty bar.

```typescript
import { formatProgressBar } from '@helpers4/string';

formatProgressBar(value: number, options: ProgressBarOptions): string
```

**Parameters:**

- `value: number` — The current value
- `options: ProgressBarOptions` (default: `{}`) — Bar rendering options

**Returns:** `string` — A string of `width` repeated filled/empty characters

**Examples:**

*Default 20-cell bar*

Renders a percentage as a filled/empty block bar using the default width and characters.

```typescript
formatProgressBar(65)
// => '▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░░'
```

*Custom width, characters, and scale*

Renders a value against a custom max, width, and fill characters — useful for anything scored out of a different total than 100.

```typescript
formatProgressBar(3, { width: 10, max: 5, filledChar: '#', emptyChar: '-' })
// => '######----'
```

---

### `fromBase64`

Decodes Base64 text. Both alphabets are accepted (`+/` and the URL-safe `-_`) and the `=`
padding is optional, so it reads whatever toBase64 wrote, and most Base64 found in the wild.

```typescript
import { fromBase64 } from '@helpers4/string';

fromBase64(text: string, options: FromBase64Options & object): Uint8Array
```

**Parameters:**

- `text: string` — The Base64 text, without whitespace
- `options: FromBase64Options & object` — `{ output: 'bytes' }` to get a `Uint8Array` instead of a string

**Returns:** `Uint8Array` — The decoded text (UTF-8), or the bytes

```typescript
import { fromBase64 } from '@helpers4/string';

fromBase64(text: string, options?: FromBase64Options): string
```

**Parameters:**

- `text: string` — The Base64 text, without whitespace
- `options?: FromBase64Options` — `{ output: 'bytes' }` to get a `Uint8Array` instead of a string

**Returns:** `string` — The decoded text (UTF-8), or the bytes

**Examples:**

*Decode Base64 to text*

Either alphabet is accepted and the padding is optional.

```typescript
fromBase64('aMOpbGxv')
// => 'héllo'
```

*Decode to raw bytes*

Use output: bytes when the payload is not text.

```typescript
fromBase64('-_8', { output: 'bytes' })
// => Uint8Array [251, 255]
```

---

### `globToRegExp`

Compiles a glob pattern into a `RegExp` that matches the whole string. By default only the two
textbook wildcards are special: `*` matches any sequence of UTF-16 code units (including
none), `?` matches exactly one UTF-16 code unit, and everything else is matched literally.
Pass `{ extended: true }` for path globs: `{a,b}`, `[abc]` and a `**` that crosses `/` while
`*` and `?` do not — see GlobOptions.

Like the rest of this library, lengths are counted in UTF-16 code units: `?` matches one code
unit, not one Unicode code point, so it matches only half of a surrogate pair (e.g. an emoji
outside the Basic Multilingual Plane).

```typescript
import { globToRegExp } from '@helpers4/string';

globToRegExp(pattern: string, options: boolean | GlobOptions): RegExp
```

**Parameters:**

- `pattern: string` — The glob pattern to compile
- `options: boolean | GlobOptions` (default: `true`) — Case sensitivity, or GlobOptions. A boolean is the case sensitivity (defaults to `true`).

**Returns:** `RegExp` — A `RegExp` matching strings that satisfy `pattern` in full

**Examples:**

*Match a file extension pattern*

"*" matches any sequence of characters.

```typescript
globToRegExp('*.test.ts').test('helper.test.ts')
// => true
```

*Match a fixed-width placeholder with "?"*

"?" matches exactly one character — handy for fixed-width codes.

```typescript
globToRegExp('report-????.csv').test('report-2026.csv')
// => true
```

*Path globs with braces and ***

extended: true turns on {a,b}, [abc] and a ** that crosses directories while * stays in one segment.

```typescript
const isSource = globToRegExp('src/**/*.{ts,tsx}', { extended: true });
isSource.test('src/ui/App.tsx')
// => true
```

*Reuse the same pattern for many strings efficiently*

Compile the RegExp once and reuse it for every check instead of recompiling per candidate. If you also need to cache across many different call sites, wrap globToRegExp itself with memoize() from @helpers4/function.

```typescript
const isTestFile = globToRegExp('*.test.ts');
['a.test.ts', 'a.spec.ts'].filter(name => isTestFile.test(name))
// => ['a.test.ts']
```

---

### `injectWordBreaks`

Adds word-break opportunities to a string so it can wrap cleanly in narrow
UI containers such as side panels or table cells.

Invisible zero-width spaces (`\u200B`) are inserted at meaningful
boundaries — camelCase splits, path separators, token edges — while
protected spans (URLs, emails, HTML) and atomic numeric values (`-0.1%`,
`12ms`, `1e-3`) are never broken. The visible text content is unchanged.

```typescript
import { injectWordBreaks } from '@helpers4/string';

injectWordBreaks(str: string): string
```

**Parameters:**

- `str: string` — The string to process.

**Returns:** `string` — The string with word-break opportunities injected at meaningful
boundaries.

```typescript
import { injectWordBreaks } from '@helpers4/string';

injectWordBreaks(str: undefined): undefined
```

**Parameters:**

- `str: undefined` — The string to process.

**Returns:** `undefined` — The string with word-break opportunities injected at meaningful
boundaries.

```typescript
import { injectWordBreaks } from '@helpers4/string';

injectWordBreaks(str: null): null
```

**Parameters:**

- `str: null` — The string to process.

**Returns:** `null` — The string with word-break opportunities injected at meaningful
boundaries.

**Examples:**

*camelCase identifier*

Inserts ZWS at each camelCase boundary so a long identifier can wrap in a narrow column.

```typescript
injectWordBreaks('getUserProfileData')
// => 'get\u200BUser\u200BProfile\u200BData'
```

*Comma-separated tokens*

The comma attaches to the left token so a line never starts with a comma.

```typescript
injectWordBreaks('foo,bar')
// => 'foo,\u200Bbar'
```

*Atomic numeric value*

Signed decimals and numbers with units (-0.1%, 12ms, -2.4E+6) are never split.

```typescript
injectWordBreaks('-0.1%')
// => '-0.1%'   (unchanged — atomic value)
```

*File path*

Slashes become wrap points so a long path can break at each component.

```typescript
injectWordBreaks('path/to/my_file')
// => 'path\u200B/\u200Bto\u200B/\u200Bmy_file'
```

*URL is preserved intact*

URLs are D0-protected spans — no ZWS is inserted inside or adjacent to them.

```typescript
injectWordBreaks('https://example.com/foo/bar')
// => 'https://example.com/foo/bar'   (unchanged)
```

---

### `isBlank`

Checks if a string is blank — empty or contains only whitespace characters.
`null` and `undefined` are considered blank and return `true`.

Uses `String.prototype.trim()` internally, which covers all ECMAScript
whitespace: standard ASCII whitespace (`\t`, `\n`, `\r`, `\f`, `\v`),
non-breaking space (U+00A0), BOM (U+FEFF), and all Unicode "Space_Separator"
category characters (en space, em space, thin space, ideographic space, etc.).

**Zero-width characters** (U+200B zero-width space, U+200C, U+200D, U+2060)
are **not** treated as whitespace — they are Unicode "Format" (Cf) characters,
not spaces. Strip them explicitly if needed:
`isBlank(value.replace(/[\u200B-\u200D\u2060]/g, ''))`

```typescript
import { isBlank } from '@helpers4/string';

isBlank(value: string | null | undefined): boolean
```

**Parameters:**

- `value: string | null | undefined` — The string to check

**Returns:** `boolean` — `true` if the string is empty, contains only whitespace, or is `null`/`undefined`

**Examples:**

*Detect empty or whitespace-only strings*

Returns true for "" and for any string made entirely of whitespace — including non-breaking space (U+00A0), en/em spaces, ideographic space, and BOM.

```typescript
isBlank('')      // => true
isBlank('   ')   // => true
isBlank('\t\n')  // => true
isBlank(' ')     // => true   (non-breaking space U+00A0)
isBlank('foo')   // => false
isBlank(' x ')   // => false
```

*Form validation — reject blank input*

Use isBlank to reject fields that contain only whitespace.

```typescript
function validateName(name: string): string | null {
  if (isBlank(name)) return 'Name is required';
  return null;
}
validateName('')    // => 'Name is required'
validateName('   ') // => 'Name is required'
validateName('Ada') // => null
```

---

### `isEmpty`

Checks if a string is empty (`""`), `null`, or `undefined`.

This is a strict emptiness check — whitespace-only strings are **not** considered
empty. Use `isEmpty(value?.trim())` if you need to treat blank strings as empty.

```typescript
import { isEmpty } from '@helpers4/string';

isEmpty(value: string | null | undefined): value is "" | null | undefined
```

**Parameters:**

- `value: string | null | undefined` — The string to check

**Returns:** `value is "" | null | undefined` — `true` if the string is `""`, `null`, or `undefined`

**Examples:**

*Check if a string is empty*

Returns true only for `""`. Whitespace-only strings are not considered empty.

```typescript
isEmpty('')    // => true
isEmpty(' ')   // => false  (whitespace is content)
isEmpty('foo') // => false
```

*Treat blank strings as empty by trimming first*

Compose with .trim() when whitespace-only should also be considered empty.

```typescript
isEmpty(''.trim())   // => true
isEmpty('   '.trim()) // => true
isEmpty('hi'.trim())  // => false
```

---

### `isNonEmpty`

Checks if a string is non-empty (has at least one character).
`null` and `undefined` are considered empty and return `false`.

Whitespace-only strings are considered non-empty.
Use `isNonEmpty(value?.trim())` if you need to exclude blank strings.

```typescript
import { isNonEmpty } from '@helpers4/string';

isNonEmpty(value: string | null | undefined): value is string
```

**Parameters:**

- `value: string | null | undefined` — The string to check

**Returns:** `value is string` — `true` if the string has at least one character; `false` for `""`, `null`, or `undefined`.
Acts as a type guard: the `if` branch narrows `string | null | undefined` to `string`.

**Examples:**

*Check if a string has content*

Returns true for any string with at least one character, including whitespace.

```typescript
isNonEmpty('hello') // => true
isNonEmpty(' ')     // => true  (whitespace is content)
isNonEmpty('')      // => false
```

*Exclude blank strings by trimming first*

Compose with .trim() when whitespace-only strings should be treated as empty.

```typescript
isNonEmpty('hello'.trim()) // => true
isNonEmpty('   '.trim())   // => false
isNonEmpty(''.trim())      // => false
```

---

### `isNotBlank`

Checks if a string is not blank — non-empty and contains at least one
non-whitespace character.
`null` and `undefined` are considered blank and return `false`.

Uses `String.prototype.trim()` internally. See `isBlank` for the full list
of characters considered whitespace (includes non-breaking space, en/em space,
ideographic space, etc.).

```typescript
import { isNotBlank } from '@helpers4/string';

isNotBlank(value: string | null | undefined): boolean
```

**Parameters:**

- `value: string | null | undefined` — The string to check

**Returns:** `boolean` — `true` if the string has at least one non-whitespace character; `false` for blank, `null`, or `undefined`

**Examples:**

*Check that a string has real content*

Returns true only when the string contains at least one non-whitespace character.

```typescript
isNotBlank('foo')  // => true
isNotBlank(' x ')  // => true
isNotBlank('')     // => false
isNotBlank('   ')  // => false
isNotBlank('\t')   // => false
```

*Filter out blank strings from an array*

Use as a predicate in .filter() to keep only strings with real content.

```typescript
const tags = ['typescript', '  ', '', 'helpers'];
tags.filter(isNotBlank)
// => ['typescript', 'helpers']
```

---

### `kebabCase`

Converts a string to kebab-case.
Handles camelCase, PascalCase, snake_case, spaces, and mixed formats.

```typescript
import { kebabCase } from '@helpers4/string';

kebabCase(str: string): string
```

**Parameters:**

- `str: string` — The string to convert

**Returns:** `string` — String in kebab-case

```typescript
import { kebabCase } from '@helpers4/string';

kebabCase(str: undefined): undefined
```

**Parameters:**

- `str: undefined` — The string to convert

**Returns:** `undefined` — String in kebab-case

```typescript
import { kebabCase } from '@helpers4/string';

kebabCase(str: null): null
```

**Parameters:**

- `str: null` — The string to convert

**Returns:** `null` — String in kebab-case

**Examples:**

*Convert camelCase to kebab-case*

Converts a camelCase string to kebab-case.

```typescript
kebabCase('myComponentName')
// => 'my-component-name'
```

---

### `leadingSentence`

Extracts the leading sentence from a string.
`null` and `undefined` are passed through unchanged.

A sentence boundary is detected at the first occurrence of `.`, `?`, `!`,
`…`, or `;` followed by whitespace or end of string. Newlines are collapsed
to spaces before matching.

If no boundary is found the entire (cleaned) string is returned.

To cap the result at a maximum length, combine with truncate:
```ts
truncate(leadingSentence(input), 120)
```

```typescript
import { leadingSentence } from '@helpers4/string';

leadingSentence(input: string): string
```

**Parameters:**

- `input: string` — The source string

**Returns:** `string` — The first sentence, including its terminal character; or `null`/`undefined` if input is nullish

```typescript
import { leadingSentence } from '@helpers4/string';

leadingSentence(input: null): null
```

**Parameters:**

- `input: null` — The source string

**Returns:** `null` — The first sentence, including its terminal character; or `null`/`undefined` if input is nullish

```typescript
import { leadingSentence } from '@helpers4/string';

leadingSentence(input: undefined): undefined
```

**Parameters:**

- `input: undefined` — The source string

**Returns:** `undefined` — The first sentence, including its terminal character; or `null`/`undefined` if input is nullish

```typescript
import { leadingSentence } from '@helpers4/string';

leadingSentence(input: string | null | undefined): string | null | undefined
```

**Parameters:**

- `input: string | null | undefined` — The source string

**Returns:** `string | null | undefined` — The first sentence, including its terminal character; or `null`/`undefined` if input is nullish

**Examples:**

*Extract the leading sentence*

Returns the first sentence, terminated by . ? or !.

```typescript
leadingSentence('Returns the sum of an array. Works with any numbers.')
// => 'Returns the sum of an array.'
```

*Works with ? and !*

Recognises question marks and exclamation marks as sentence terminators.

```typescript
leadingSentence('Is it done? Yes it is!')
// => 'Is it done?'
```

*Cap length by combining with truncate*

Use truncate to limit the result to a fixed number of characters.

```typescript
truncate(leadingSentence(input), 120)
```

---

### `levenshteinDistance`

Levenshtein edit distance between two strings — the minimum number of single-character
insertions, deletions, or substitutions needed to turn `a` into `b`.

```typescript
import { levenshteinDistance } from '@helpers4/string';

levenshteinDistance(a: string, b: string, caseSensitive: boolean): number
```

**Parameters:**

- `a: string` — The first string
- `b: string` — The second string
- `caseSensitive: boolean` (default: `true`) — Whether the comparison is case-sensitive. Defaults to `true`.

**Returns:** `number` — The edit distance; `0` when `a` and `b` are equal (after case-folding when
`caseSensitive` is `false`)

**Examples:**

*Classic edit-distance example*

"kitten" becomes "sitting" with 3 single-character edits.

```typescript
levenshteinDistance('kitten', 'sitting')
// => 3
```

*Case-insensitive comparison*

Pass `false` to ignore letter case when comparing.

```typescript
levenshteinDistance('Kitten', 'kitten', false)
// => 0
```

---

### `levenshteinSimilarity`

Normalized Levenshtein similarity between two strings, in `[0, 1]` — `1` means identical,
`0` means completely dissimilar relative to the longer string's length. A convenience wrapper
around levenshteinDistance for scoring/ranking use cases.

```typescript
import { levenshteinSimilarity } from '@helpers4/string';

levenshteinSimilarity(a: string, b: string, caseSensitive: boolean): number
```

**Parameters:**

- `a: string` — The first string
- `b: string` — The second string
- `caseSensitive: boolean` (default: `true`) — Whether the comparison is case-sensitive. Defaults to `true`.

**Returns:** `number` — A similarity score between `0` and `1`; `1` when both strings are empty

**Examples:**

*Score how close two strings are*

A normalized [0, 1] score, handy for fuzzy-matching/ranking.

```typescript
levenshteinSimilarity('kitten', 'sitting')
// => 0.5714285714285714
```

*Identical strings score 1*

Useful as a fuzzy-matching threshold cutoff.

```typescript
levenshteinSimilarity('same', 'same')
// => 1
```

---

### `matchGlob`

Whether `text` matches a glob pattern in full: `*` matches any run of characters, `?` exactly
one. A one-shot shortcut for `globToRegExp(pattern).test(text)`; to test many strings with the
same pattern, build the `RegExp` once with globToRegExp or createGlobMatcher.

```typescript
import { matchGlob } from '@helpers4/string';

matchGlob(pattern: string, text: string, options: MatchGlobOptions): boolean
```

**Parameters:**

- `pattern: string` — The glob pattern
- `text: string` — The string to test
- `options: MatchGlobOptions` (default: `{}`) — Case insensitivity and path globs — see MatchGlobOptions

**Returns:** `boolean` — `true` if `text` matches `pattern`

**Examples:**

*Test a name against a glob*

One call, with an option to ignore case.

```typescript
matchGlob('screen *', 'Screen 2', { caseInsensitive: true }) // => true
```

---

### `obfuscate`

Hides a text from anything that reads the raw page source: the text is reversed (by Unicode
code point, so emoji stay whole) and written as unpadded base64url. Typical use: an e-mail
address rebuilt on click, so naive scrapers do not find it. deobfuscate reverses it.

It works the same in Node.js and in browsers (no `Buffer`, no `btoa`), for any text, non-ASCII
included. A lone surrogate, which is not valid text, comes back as U+FFFD.

**This is not security.** It only stops scrapers that look at the HTML as it is; anyone can undo
it. Never use it for secrets.

```typescript
import { obfuscate } from '@helpers4/string';

obfuscate(text: string): string
```

**Parameters:**

- `text: string` — The text to hide

**Returns:** `string` — A base64url token, with no `=` padding

**Examples:**

*Hide an address from scrapers*

Done at build time; the page holds the token, and the link is rebuilt on click. Not security.

```typescript
obfuscate('me@example.com')
// => 'bW9jLmVscG1heGVAZW0'
```

---

### `parsePatternOrRegExp`

Reads a setting that is either a regular expression or a glob: `/source/flags` is a regular
expression when every flag is valid (`d`, `g`, `i`, `m`, `s`, `u`, `v`, `y`), anything else is
a glob. For font substitution rules, ignore lists, filters. Note that `/usr/lib/img` is the
regular expression `usr/lib` with the flags `img`: for paths, use globToRegExp.

```typescript
import { parsePatternOrRegExp } from '@helpers4/string';

parsePatternOrRegExp(pattern: string, options: MatchGlobOptions): RegExp
```

**Parameters:**

- `pattern: string` — A `/source/flags` regular expression or a glob
- `options: MatchGlobOptions` (default: `{}`) — How to read a glob — see MatchGlobOptions. A regular expression keeps its own flags

**Returns:** `RegExp` — The `RegExp`

**Examples:**

*Glob or regular expression*

A /source/flags string is a regular expression; anything else is a glob.

```typescript
parsePatternOrRegExp('SF Pro*').test('SF Pro Display') // => true
parsePatternOrRegExp('/^SF Pro/i').test('sf pro text') // => true
```

---

### `pascalCase`

Converts a string to PascalCase.
Handles camelCase, kebab-case, snake_case, spaces, and mixed formats.

```typescript
import { pascalCase } from '@helpers4/string';

pascalCase(str: string): string
```

**Parameters:**

- `str: string` — The string to convert

**Returns:** `string` — String in PascalCase

```typescript
import { pascalCase } from '@helpers4/string';

pascalCase(str: undefined): undefined
```

**Parameters:**

- `str: undefined` — The string to convert

**Returns:** `undefined` — String in PascalCase

```typescript
import { pascalCase } from '@helpers4/string';

pascalCase(str: null): null
```

**Parameters:**

- `str: null` — The string to convert

**Returns:** `null` — String in PascalCase

**Examples:**

*Convert kebab-case to PascalCase*

Converts a kebab-case string to PascalCase.

```typescript
pascalCase('my-component')
// => 'MyComponent'
```

*Convert snake_case to PascalCase*

Also handles snake_case and other formats.

```typescript
pascalCase('user_first_name')
// => 'UserFirstName'
```

---

### `removeDiacritics`

Removes diacritical marks (accents) from a string, e.g. `'café'` → `'cafe'`.

Works by Unicode-decomposing each character into its base letter plus
combining marks (`'é'` → `'e'` + a combining acute accent), then
stripping the marks. Same technique already used internally by `slugify`.

```typescript
import { removeDiacritics } from '@helpers4/string';

removeDiacritics(str: string): string
```

**Parameters:**

- `str: string` — The string to strip diacritics from

**Returns:** `string` — The string with diacritics removed

**Examples:**

*Strip accents from a string*

Useful for accent-insensitive search or generating ASCII-safe identifiers.

```typescript
removeDiacritics('café')
// => 'cafe'
```

*Plain ASCII text is left unchanged*

Only characters with combining diacritical marks are affected.

```typescript
removeDiacritics('hello world')
// => 'hello world'
```

---

### `slugify`

Converts a string into a URL-friendly slug.

```typescript
import { slugify } from '@helpers4/string';

slugify(str: string): string
```

**Parameters:**

- `str: string` — The string to convert into a slug.

**Returns:** `string` — A lowercase, hyphen-separated slug safe for URLs.

```typescript
import { slugify } from '@helpers4/string';

slugify(str: undefined): undefined
```

**Parameters:**

- `str: undefined` — The string to convert into a slug.

**Returns:** `undefined` — A lowercase, hyphen-separated slug safe for URLs.

```typescript
import { slugify } from '@helpers4/string';

slugify(str: null): null
```

**Parameters:**

- `str: null` — The string to convert into a slug.

**Returns:** `null` — A lowercase, hyphen-separated slug safe for URLs.

**Examples:**

*Create a URL-safe slug*

Converts a string into a lowercase, hyphen-separated slug.

```typescript
slugify('Hello World!')
// => 'hello-world'
```

*Handle accented characters*

Normalizes Unicode characters and strips diacritics.

```typescript
slugify('Crème brûlée')
// => 'creme-brulee'
```

---

### `snakeCase`

Converts a string to snake_case.
Handles camelCase, PascalCase, kebab-case, spaces, and mixed formats.

```typescript
import { snakeCase } from '@helpers4/string';

snakeCase(str: string): string
```

**Parameters:**

- `str: string` — The string to convert

**Returns:** `string` — String in snake_case

```typescript
import { snakeCase } from '@helpers4/string';

snakeCase(str: undefined): undefined
```

**Parameters:**

- `str: undefined` — The string to convert

**Returns:** `undefined` — String in snake_case

```typescript
import { snakeCase } from '@helpers4/string';

snakeCase(str: null): null
```

**Parameters:**

- `str: null` — The string to convert

**Returns:** `null` — String in snake_case

**Examples:**

*Convert camelCase to snake_case*

Converts a camelCase string to snake_case.

```typescript
snakeCase('myVariableName')
// => 'my_variable_name'
```

*Convert kebab-case to snake_case*

Also handles kebab-case and other formats.

```typescript
snakeCase('my-component-name')
// => 'my_component_name'
```

---

### `stripHtml`

Plain text of an HTML fragment: tags removed, `<script>`, `<style>` and comments dropped
with their content, entities decoded (a common named subset, plus decimal and hex
numeric ones) and whitespace collapsed and trimmed. Block-level tags and `<br>` count as
a space, so `<p>a</p><p>b</p>` gives `a b`.

**Not a sanitizer**: this is for text extraction. Never use its output to make HTML safe,
use escapeHtml for that.

```typescript
import { stripHtml } from '@helpers4/string';

stripHtml(html: string): string
```

**Parameters:**

- `html: string` — The HTML fragment

**Returns:** `string` — The plain text

**Examples:**

*Plain text from HTML*

Removes tags and decodes entities, including &nbsp; and numeric ones.

```typescript
stripHtml('<p>Hello&nbsp;<b>world</b> &amp; co</p>')
// => 'Hello world & co'
```

*Block tags separate words*

Paragraphs, list items and line breaks become a space so words do not stick together.

```typescript
stripHtml('<ul><li>one</li><li>two</li></ul>')
// => 'one two'
```

---

### `template`

Interpolates `{{key}}` placeholders in a template string with values from
a data record. Unknown keys are replaced with an empty string.

No `eval` or `Function` constructor is used — substitution is purely
regex-based. Nested expressions and logic are intentionally out of scope.

```typescript
import { template } from '@helpers4/string';

template(str: string, data: Record<string, unknown>): string
```

**Parameters:**

- `str: string` — The template string containing `{{key}}` placeholders.
- `data: Record<string, unknown>` — A record mapping placeholder names to replacement values.

**Returns:** `string` — The template string with all placeholders replaced.

**Examples:**

*Simple interpolation*

Replaces {{key}} placeholders with values from the data object.

```typescript
template('Hello, {{name}}!', { name: 'Alice' })
// => 'Hello, Alice!'
```

*Multiple placeholders*

All matching placeholders are replaced in a single pass.

```typescript
template('{{greeting}}, {{name}}!', { greeting: 'Hi', name: 'Bob' })
// => 'Hi, Bob!'
```

*Missing keys become empty string*

Unknown placeholders are replaced with an empty string.

```typescript
template('Hello, {{name}}!', {})
// => 'Hello, !'
```

---

### `titleCase`

Converts a string to Title Case.
Handles camelCase, PascalCase, kebab-case, snake_case, spaces, and mixed formats.

```typescript
import { titleCase } from '@helpers4/string';

titleCase(str: string): string
```

**Parameters:**

- `str: string` — The string to convert

**Returns:** `string` — String in Title Case

```typescript
import { titleCase } from '@helpers4/string';

titleCase(str: undefined): undefined
```

**Parameters:**

- `str: undefined` — The string to convert

**Returns:** `undefined` — String in Title Case

```typescript
import { titleCase } from '@helpers4/string';

titleCase(str: null): null
```

**Parameters:**

- `str: null` — The string to convert

**Returns:** `null` — String in Title Case

**Examples:**

*Convert kebab-case to Title Case*

Transforms a delimited string into Title Case.

```typescript
titleCase('my-component-name')
// => 'My Component Name'
```

*Convert camelCase to Title Case*

Also handles camelCase by splitting on uppercase transitions.

```typescript
titleCase('queryItems')
// => 'Query Items'
```

---

### `toBase64`

Encodes a string (as UTF-8) or raw bytes to Base64, without relying on `btoa` or `Buffer`, so it
behaves the same in a browser, Node.js and GJS.

```typescript
import { toBase64 } from '@helpers4/string';

toBase64(input: string | Uint8Array<ArrayBufferLike>, options: ToBase64Options): string
```

**Parameters:**

- `input: string | Uint8Array<ArrayBufferLike>` — The text to encode as UTF-8, or the bytes to encode as they are
- `options: ToBase64Options` (default: `{}`) — The URL-safe alphabet and the padding — see ToBase64Options

**Returns:** `string` — The Base64 text

**Examples:**

*Encode text as UTF-8 Base64*

Non-ASCII text is encoded as UTF-8 first, so it round-trips with fromBase64.

```typescript
toBase64('héllo')
// => 'aMOpbGxv'
```

*URL-safe variant for tokens and URLs*

Uses - and _ and drops the padding, ready for a query string or a JWT-like token.

```typescript
toBase64(new Uint8Array([251, 255]), { urlSafe: true })
// => '-_8'
```

---

### `trim`

Trims both leading and trailing characters from a string, at a
configurable level of aggressiveness (see TrimMode). Defaults to
`'whitespace'`, which behaves exactly like `String.prototype.trim`.

Unlike the native `trim`, non-breaking spaces (NBSP, FIGURE SPACE, NARROW
NO-BREAK SPACE) are only stripped for `'separator'` mode and above - pass
`'wrappable'` to preserve them, since their whole purpose is to resist
being treated as a break point.

```typescript
import { trim } from '@helpers4/string';

trim(input: string, mode?: TrimMode): string
```

**Parameters:**

- `input: string` — The string to trim.
- `mode?: TrimMode` — How aggressively to trim. Defaults to `'whitespace'`.

**Returns:** `string` — The trimmed string, or the input itself when `null`/`undefined`.

```typescript
import { trim } from '@helpers4/string';

trim(input: undefined, mode?: TrimMode): undefined
```

**Parameters:**

- `input: undefined` — The string to trim.
- `mode?: TrimMode` — How aggressively to trim. Defaults to `'whitespace'`.

**Returns:** `undefined` — The trimmed string, or the input itself when `null`/`undefined`.

```typescript
import { trim } from '@helpers4/string';

trim(input: null, mode?: TrimMode): null
```

**Parameters:**

- `input: null` — The string to trim.
- `mode?: TrimMode` — How aggressively to trim. Defaults to `'whitespace'`.

**Returns:** `null` — The trimmed string, or the input itself when `null`/`undefined`.

**Examples:**

*Default mode matches String.prototype.trim*

With no mode argument, behaves exactly like the native trim.

```typescript
trim('   Hello   ')
// => 'Hello'
```

*Preserve non-breaking spaces on both ends with 'wrappable' mode*

Non-breaking spaces (NBSP) at either end are kept, since their purpose is to resist trimming.

```typescript
const NBSP = String.fromCharCode(160);
trim(NBSP + 'Hello' + NBSP, 'wrappable')
// => NBSP + 'Hello' + NBSP (unchanged)
```

*Strip zero-width characters on both ends with 'unicode' mode*

The widest mode removes zero-width joiners/spaces String.prototype.trim leaves alone.

```typescript
const ZWSP = String.fromCharCode(0x200b);
trim(ZWSP + 'Hello' + ZWSP, 'unicode')
// => 'Hello'
```

---

### `trimEnd`

Trims trailing characters from a string, at a configurable level of
aggressiveness (see TrimMode). Defaults to `'whitespace'`, which
behaves exactly like `String.prototype.trimEnd`.

Unlike the native `trimEnd`, non-breaking spaces (NBSP, FIGURE SPACE,
NARROW NO-BREAK SPACE) are only stripped for `'separator'` mode and above -
pass `'wrappable'` to preserve them, since their whole purpose is to resist
being treated as a break point (e.g. gluing a number to its unit).

```typescript
import { trimEnd } from '@helpers4/string';

trimEnd(input: string, mode?: TrimMode): string
```

**Parameters:**

- `input: string` — The string to trim.
- `mode?: TrimMode` — How aggressively to trim. Defaults to `'whitespace'`.

**Returns:** `string` — The trimmed string, or the input itself when `null`/`undefined`.

```typescript
import { trimEnd } from '@helpers4/string';

trimEnd(input: undefined, mode?: TrimMode): undefined
```

**Parameters:**

- `input: undefined` — The string to trim.
- `mode?: TrimMode` — How aggressively to trim. Defaults to `'whitespace'`.

**Returns:** `undefined` — The trimmed string, or the input itself when `null`/`undefined`.

```typescript
import { trimEnd } from '@helpers4/string';

trimEnd(input: null, mode?: TrimMode): null
```

**Parameters:**

- `input: null` — The string to trim.
- `mode?: TrimMode` — How aggressively to trim. Defaults to `'whitespace'`.

**Returns:** `null` — The trimmed string, or the input itself when `null`/`undefined`.

**Examples:**

*Default mode matches String.prototype.trimEnd*

With no mode argument, behaves exactly like the native trimEnd.

```typescript
trimEnd('Hello   ')
// => 'Hello'
```

*Preserve non-breaking spaces with 'wrappable' mode*

A non-breaking space (NBSP) is kept, since its purpose is to resist being trimmed.

```typescript
const NBSP = String.fromCharCode(160);
trimEnd('Hello,' + NBSP, 'wrappable')
// => 'Hello,' + NBSP (unchanged)
```

*Strip everything, including zero-width characters, with 'unicode' mode*

The widest mode also removes zero-width joiners/spaces that String.prototype.trimEnd leaves alone.

```typescript
const ZWSP = String.fromCharCode(0x200b);
trimEnd('Hello' + ZWSP, 'unicode')
// => 'Hello'
```

---

### `trimStart`

Trims leading characters from a string, at a configurable level of
aggressiveness (see TrimMode). Defaults to `'whitespace'`, which
behaves exactly like `String.prototype.trimStart`.

Unlike the native `trimStart`, non-breaking spaces (NBSP, FIGURE SPACE,
NARROW NO-BREAK SPACE) are only stripped for `'separator'` mode and above -
pass `'wrappable'` to preserve them, since their whole purpose is to resist
being treated as a break point.

```typescript
import { trimStart } from '@helpers4/string';

trimStart(input: string, mode?: TrimMode): string
```

**Parameters:**

- `input: string` — The string to trim.
- `mode?: TrimMode` — How aggressively to trim. Defaults to `'whitespace'`.

**Returns:** `string` — The trimmed string, or the input itself when `null`/`undefined`.

```typescript
import { trimStart } from '@helpers4/string';

trimStart(input: undefined, mode?: TrimMode): undefined
```

**Parameters:**

- `input: undefined` — The string to trim.
- `mode?: TrimMode` — How aggressively to trim. Defaults to `'whitespace'`.

**Returns:** `undefined` — The trimmed string, or the input itself when `null`/`undefined`.

```typescript
import { trimStart } from '@helpers4/string';

trimStart(input: null, mode?: TrimMode): null
```

**Parameters:**

- `input: null` — The string to trim.
- `mode?: TrimMode` — How aggressively to trim. Defaults to `'whitespace'`.

**Returns:** `null` — The trimmed string, or the input itself when `null`/`undefined`.

**Examples:**

*Default mode matches String.prototype.trimStart*

With no mode argument, behaves exactly like the native trimStart.

```typescript
trimStart('   Hello')
// => 'Hello'
```

*Preserve non-breaking spaces with 'wrappable' mode*

A leading non-breaking space (NBSP) is kept, since its purpose is to resist being trimmed.

```typescript
const NBSP = String.fromCharCode(160);
trimStart(NBSP + 'Hello', 'wrappable')
// => NBSP + 'Hello' (unchanged)
```

*Strip non-breaking spaces too with 'separator' mode*

A wider mode than the default (whitespace) is not needed for NBSP — separator already covers it.

```typescript
const NBSP = String.fromCharCode(160);
trimStart(NBSP + 'Hello', 'separator')
// => 'Hello'
```

---

### `truncate`

Truncates a string to `maxLength` characters, appending an ellipsis when cut.

The ellipsis counts toward `maxLength`, so the result is always at most
`maxLength` characters long. The cut point is snapped back to the nearest
grapheme-cluster boundary and trailing breakable whitespace is trimmed, so
a cut never leaves a dangling space (`'Hello,…'`, not `'Hello, …'`) or a
split multi-code-unit character (a lone surrogate, an orphaned combining
mark, a family emoji cut mid-sequence, …) in front of the ellipsis — this
means the result can be shorter than `maxLength` when the cut point falls
on whitespace or inside such a cluster. Non-breaking spaces (U+00A0) and
other "no-break" Unicode separators are deliberately left untouched, since
their whole purpose is to resist being treated as a break point. If the
string is already within the limit, it is returned unchanged (no ellipsis
appended, no trimming). `null` and `undefined` inputs are returned as-is to
align with other string helpers.

This is a mechanical cut at exactly `maxLength` — it doesn't know or care about sentence
structure. For a card/header-sized summary that prefers to end on a whole sentence when one
fits, see excerpt instead.

```typescript
import { truncate } from '@helpers4/string';

truncate(input: undefined, maxLength: number, ellipsis?: string): undefined
```

**Parameters:**

- `input: undefined` — The string to truncate.
- `maxLength: number` — Maximum number of characters in the output (including ellipsis).
- `ellipsis?: string` — Appended when the string is cut. Defaults to `'…'`.

**Returns:** `undefined` — The (possibly truncated) string, or the input itself when `null`/`undefined`.

```typescript
import { truncate } from '@helpers4/string';

truncate(input: null, maxLength: number, ellipsis?: string): null
```

**Parameters:**

- `input: null` — The string to truncate.
- `maxLength: number` — Maximum number of characters in the output (including ellipsis).
- `ellipsis?: string` — Appended when the string is cut. Defaults to `'…'`.

**Returns:** `null` — The (possibly truncated) string, or the input itself when `null`/`undefined`.

```typescript
import { truncate } from '@helpers4/string';

truncate(input: string, maxLength: number, ellipsis?: string): string
```

**Parameters:**

- `input: string` — The string to truncate.
- `maxLength: number` — Maximum number of characters in the output (including ellipsis).
- `ellipsis?: string` — Appended when the string is cut. Defaults to `'…'`.

**Returns:** `string` — The (possibly truncated) string, or the input itself when `null`/`undefined`.

**Examples:**

*Truncate with default ellipsis*

Appends … when the string exceeds the limit, trimming a trailing space at the cut point.

```typescript
truncate('Hello, world!', 8)
// => 'Hello,…'
```

*Truncate with custom ellipsis*

The ellipsis counts toward the maxLength.

```typescript
truncate('Hello, world!', 8, '...')
// => 'Hello...'
```

*String within limit*

Returned unchanged when already short enough.

```typescript
truncate('Hi', 10)
// => 'Hi'
```

---

### `unescapeHtml`

Unescapes the HTML entities `&amp;`, `&lt;`, `&gt;`, `&quot;`, and `&#39;`
back to `&`, `<`, `>`, `"`, and `'`.

This is the exact inverse of escapeHtml — it only recognizes the
five entities that function produces, not the full HTML entity set (no
`&nbsp;`, no numeric code points beyond `&#39;`, etc.).

```typescript
import { unescapeHtml } from '@helpers4/string';

unescapeHtml(str: string): string
```

**Parameters:**

- `str: string` — The string to unescape

**Returns:** `string` — The unescaped string

**Examples:**

*Unescape HTML entities back to their original characters*

Inverse of escapeHtml — turns &lt;, &gt;, &amp;, &quot;, &#39; back into < > & " '.

```typescript
unescapeHtml('&lt;b&gt;bold&lt;/b&gt;')
// => '<b>bold</b>'
```

*Unrecognized entities are left untouched*

Only the five entities escapeHtml produces are unescaped — not the full HTML entity set.

```typescript
unescapeHtml('a&nbsp;b')
// => 'a&nbsp;b'  (unchanged)
```

---

### `unorderedPairKey`

Builds a canonical, order-independent key for an unordered pair of strings — the same result
for `(a, b)` and `(b, a)`. Useful for deduplicating unordered relationships (edges, matched
pairs, ...) using a `Set`/`Map` keyed by string.

```typescript
import { unorderedPairKey } from '@helpers4/string';

unorderedPairKey(a: string, b: string, separator: string): string
```

**Parameters:**

- `a: string` — The first string
- `b: string` — The second string
- `separator: string` (default: `'|'`) — Joins the two strings in the key. Defaults to `'|'` — pick a separator that
cannot appear inside `a`/`b` themselves, or two distinct pairs could collide on the same key.

**Returns:** `string` — `a` and `b` joined by `separator`, in whichever of the two lexicographic orders sorts first

**Examples:**

*Deduplicate unordered relationships in a Set*

The same key is produced regardless of which side is passed first.

```typescript
const seen = new Set<string>();
seen.add(unorderedPairKey('alice', 'bob'));
seen.has(unorderedPairKey('bob', 'alice'))
// => true
```

*Custom separator*

Pick a separator that cannot appear inside the inputs to avoid collisions.

```typescript
unorderedPairKey('bob', 'alice', ':')
// => 'alice:bob'
```

---

### `words`

Splits a string into an array of words.
`null` and `undefined` return `[]`.

Handles camelCase, PascalCase, SCREAMING_SNAKE_CASE, kebab-case,
snake_case, and regular whitespace-separated text. Numbers are
treated as word tokens.

```typescript
import { words } from '@helpers4/string';

words(str: string | null | undefined): string[]
```

**Parameters:**

- `str: string | null | undefined` — The string to split into words.

**Returns:** `string[]` — An array of word tokens.

**Examples:**

*Split common string formats*

Splits camelCase, PascalCase, snake_case, kebab-case and space-separated words.

```typescript
words('camelCaseString') // => ['camel', 'Case', 'String']
words('snake_case')       // => ['snake', 'case']
words('kebab-case')       // => ['kebab', 'case']
words('hello world')      // => ['hello', 'world']
```

*Build camelCase from any input*

Combine with a map to convert from any naming convention.

```typescript
const toCamel = (str: string) =>
  words(str)
    .map((w, i) => i === 0 ? w.toLowerCase() : w[0].toUpperCase() + w.slice(1).toLowerCase())
    .join('');
toCamel('hello-world'); // => 'helloWorld'
```

---

## structure

Package: `@helpers4/structure`

### `createBackStack`

Creates a back stack: a stack that always has a current entry (the one on top), with the
previous ones underneath to go `back` to. The bottom entry is never removed, so there is always
something to show: screens of a prototype, overlays stacked over a screen (with `null` as the
initial entry), wizard steps, undo levels.

It does not decide what the next entry is: compute it (with a state machine, a router, ...)
and `push` it.

```typescript
import { createBackStack } from '@helpers4/structure';

createBackStack<T>(initial: T, options: BackStackOptions): BackStack<T>
```

**Parameters:**

- `initial: T` — The first current entry, also the default of BackStack.reset
- `options: BackStackOptions` (default: `{}`) — Depth limit — see BackStackOptions

**Returns:** `BackStack<T>` — A BackStack

**Examples:**

*Navigate and go back*

push() moves to a new entry; back() returns the entry it left and restores the previous one.

```typescript
const screens = createBackStack('home');
screens.push('settings');
screens.back();  // => 'settings'
screens.current; // => 'home'
```

*Change the current entry without a step to undo*

replace() swaps the current entry and keeps the ones underneath; previous is where back() would go.

```typescript
const screens = createBackStack('home');
screens.push('menu');
screens.replace('menu-closed');
screens.previous; // => 'home'
screens.back();   // => 'menu-closed'
```

*Bound the stack*

limit caps how many past entries are kept; the oldest are dropped first.

```typescript
const stack = createBackStack('', { limit: 1 });
stack.push('a');
stack.push('ab');
stack.back(); // => 'ab'
stack.back(); // => undefined — '' was dropped
```

---

### `createUnionFind`

Creates a disjoint-set (union-find) structure: tracks a partition of items into
non-overlapping sets, merging two sets in near-constant time via `union`, and answering
"are these in the same set?" via `connected` — the classic tool for clustering items by
an equivalence relation built up incrementally (e.g. grouping records that pairwise match
on some criterion into connected components), without recomputing the whole partition
from scratch after every new match.

Uses union-by-rank and path compression internally, so `find`/`union`/`connected` are all
near-O(1) amortized regardless of how many items or unions have been performed.

Items are compared by `Map` key semantics (`SameValueZero`, like `Set`/`Map` themselves) —
so object identity for objects, value equality for primitives.

```typescript
import { createUnionFind } from '@helpers4/structure';

createUnionFind<T>(): UnionFind<T>
```

**Returns:** `UnionFind<T>` — A UnionFind.

**Examples:**

*Group items by a pairwise match built up incrementally*

union() merges two items into the same set; connected() checks whether two items ended up in the same set, even through a chain of intermediate matches.

```typescript
const uf = createUnionFind<string>();
uf.union('a', 'b');
uf.union('b', 'c');
uf.connected('a', 'c'); // true — merged transitively through 'b'
uf.connected('a', 'd'); // false — 'd' was never unioned with anything
```

*find() returns the shared representative of a set*

Every item in the same set resolves to the same representative via find() — useful to bucket items by their final group afterwards.

```typescript
const uf = createUnionFind<number>();
uf.union(1, 2);
uf.union(2, 3);
uf.find(1) === uf.find(3) // true
```

---

## type

Package: `@helpers4/type`

### `AbortSignalLike`

What helpers4 needs of an `AbortSignal`: whether it is aborted, why, and a way to listen for
the abort. A real `AbortSignal` is assignable to it, and so is an object of your own in a
runtime that has no `AbortController` (GJS, embedded engines) or no DOM typings: the type
names nothing but itself, so it compiles without the DOM lib.

Every `signal` option of the library takes this type.

**Examples:**

*AbortSignalLike*

```typescript
```ts
// A signal for a runtime without AbortController
const listeners = new Set<() => void>();
const signal: AbortSignalLike = {
  aborted: false,
  addEventListener: (_type, listener) => listeners.add(listener),
  removeEventListener: (_type, listener) => listeners.delete(listener),
};
await delay(1000, { signal });
```
```

---

### `Brand`

Brands a base type `T` with a phantom tag `B` to create a nominal type.

Two `Brand<string, 'UserId'>` and `Brand<string, 'Email'>` are structurally
identical strings at runtime, but TypeScript treats them as distinct types
at the call site — preventing accidental mix-ups.

Use a const-assertion cast at the creation boundary:
```ts
type UserId = Brand<string, 'UserId'>;
const toUserId = (s: string): UserId => s as UserId;
```

**Examples:**

*Brand*

```typescript
```ts
type Meter = Brand<number, 'Meter'>;
type Second = Brand<number, 'Second'>;

declare function speed(distance: Meter, time: Second): number;
const d = 100 as Meter;
const t = 5 as Second;
speed(d, t);   // ✅
speed(t, d);   // ✗ Type error — args swapped
```
```

---

### `DeepGet`

Resolves the value type at a given `Path` within `T`.

Returns `unknown` when any key in `Path` is not present in the corresponding
level of `T`. An empty path resolves to `T` itself. A path segment that goes
through an optional property keeps the result nullable (`V | undefined`)
instead of degrading to `unknown`.

**Examples:**

*DeepGet*

```typescript
```ts
type Obj = { a: { b: { c: number } } };

DeepGet<Obj, ['a', 'b', 'c']> // => number
DeepGet<Obj, ['a', 'b']>      // => { c: number }
DeepGet<Obj, ['a', 'x']>      // => unknown
DeepGet<Obj, []>              // => Obj

type WithOptional = { a?: { b: number } };
DeepGet<WithOptional, ['a', 'b']> // => number | undefined
```
```

---

### `DeepPartial`

Recursively makes all properties of T optional, including nested objects
and array elements.

**Examples:**

*DeepPartial*

```typescript
```ts
type Config = { server: { host: string; port: number }; debug: boolean };
type PartialConfig = DeepPartial<Config>;
// => { server?: { host?: string; port?: number }; debug?: boolean }
```
```

---

### `DeepSet`

Produces the type of `T` after replacing the value at `Path` with `V`.

When a key in `Path` is absent from the corresponding level of `T`, that level
(and everything below it) is added as a new field instead of resolving to
`never` — mirroring how `set()` creates intermediate objects at runtime.

**Examples:**

*DeepSet*

```typescript
```ts
type Obj = { a: { b: number; c: string } };

DeepSet<Obj, ['a', 'b'], string>
// => { a: { b: string; c: string } }

DeepSet<Obj, ['a', 'x'], boolean>
// => { a: { b: number; c: string } & { x: boolean } }
```
```

---

### `DeepWritable`

Recursively removes `readonly` from all properties of T, including nested
objects, array elements, and tuple positions.

**Examples:**

*DeepWritable*

```typescript
```ts
type Config = { readonly server: { readonly host: string }; readonly tags: readonly string[] };
type MutableConfig = DeepWritable<Config>;
// => { server: { host: string }; tags: string[] }
```
```

*DeepWritable*

```typescript
```ts
type Point = readonly [x: number, y: number];
type MutablePoint = DeepWritable<Point>;
// => [x: number, y: number]

Note: `Date`, `Map`, `Set`, `Promise`, and `RegExp` are treated as opaque and passed
through unchanged. In particular, `DeepWritable<Map<K, V>>` does **not** strip `readonly`
from the value type `V` — use a manual mapped type if you need that.
```
```

---

### `KeysOfType`

Extracts the keys of `T` whose values extend `V`.

Optional properties are matched by their non-nullable value type, so an
optional `string` property still counts as a `string` key.

**Examples:**

*KeysOfType*

```typescript
```ts
type User = { id: number; name: string; email: string; active: boolean };
type StringKeys = KeysOfType<User, string>; // 'name' | 'email'
type NumberKeys = KeysOfType<User, number>; // 'id'
```
```

---

### `Maybe`

Type for values that can be T, undefined, or null.

---

### `Nullable`

Adds `null` to a type (`T | null`).

Useful as a shorthand when explicit nullability should be expressed
in function signatures or generic constraints.

**Examples:**

*Nullable*

```typescript
```ts
type MaybeUser = Nullable<User>; // User | null

function findUser(id: string): Nullable<User> { ... }
```
```

---

### `Nullish`

Adds `null` and `undefined` to a type (`T | null | undefined`).

Alias of Maybe.

**Examples:**

*Nullish*

```typescript
```ts
type OptionalUser = Nullish<User>; // User | null | undefined
```
```

---

### `OmitByValue`

Constructs a type by omitting all entries of `T` whose values extend `V`.

Optional properties are matched by their non-nullable value type, so an
optional `string` property is omitted the same as a required one.

**Examples:**

*OmitByValue*

```typescript
```ts
type Form = { name: string; age: number; email: string; active: boolean };
type NonStringFields = OmitByValue<Form, string>; // { age: number; active: boolean }
```
```

---

### `OptionalKeys`

Extracts the optional keys of an object type `T`.

**Examples:**

*OptionalKeys*

```typescript
```ts
type User = { id: number; name: string; email?: string };
type Opts = OptionalKeys<User>; // 'email'
```
```

---

### `PickByValue`

Constructs a type by picking all entries of `T` whose values extend `V`.

Optional properties are matched by their non-nullable value type, so an
optional `string` property is picked the same as a required one.

**Examples:**

*PickByValue*

```typescript
```ts
type Form = { name: string; age: number; email: string; active: boolean };
type StringFields = PickByValue<Form, string>; // { name: string; email: string }
```
```

---

### `Prettify`

Flattens an intersection type into a single readable object type.

IDE tooltips for intersections like `A & B & C` often show the raw
intersection instead of the resolved shape. Wrapping with `Prettify`
forces TypeScript to expand and display the fully-resolved type.

Distributes over unions, so each member is prettified independently
instead of collapsing to their shared keys.

**Examples:**

*Prettify*

```typescript
```ts
type A = { a: number };
type B = { b: string };
type Merged = A & B;        // shown as "A & B" in IDE
type Pretty = Prettify<Merged>; // shown as "{ a: number; b: string }"
```
```

---

### `RequiredKeys`

Extracts the required (non-optional) keys of an object type `T`.

**Examples:**

*RequiredKeys*

```typescript
```ts
type User = { id: number; name: string; email?: string };
type Required = RequiredKeys<User>; // 'id' | 'name'
```
```

---

### `UnionToIntersection`

Converts a union type to an intersection type: `A | B | C` → `A & B & C`.

Uses conditional-type distribution and the contravariant position of a
function parameter to collapse the union into an intersection.

**Examples:**

*UnionToIntersection*

```typescript
```ts
type Union = { a: number } | { b: string } | { c: boolean };
type Intersection = UnionToIntersection<Union>;
// { a: number } & { b: string } & { c: boolean }

type Keys = UnionToIntersection<'a' | 'b'>;
// 'a' & 'b'  (resolves to never for disjoint literals)
```
```

---

### `ValueOf`

Produces a union of all value types of an object type `T`.

**Examples:**

*ValueOf*

```typescript
```ts
type Config = { host: string; port: number; secure: boolean };
type ConfigValue = ValueOf<Config>; // string | number | boolean

const STATUS = { OK: 200, NOT_FOUND: 404, ERROR: 500 } as const;
type StatusCode = ValueOf<typeof STATUS>; // 200 | 404 | 500
```
```

---

## url

Package: `@helpers4/url`

### `cleanPath`

Clean an URL by removing duplicate slashes.
The protocol part of the URL is not modified.

```typescript
import { cleanPath } from '@helpers4/url';

cleanPath(url: string | null | undefined): string | null | undefined
```

**Parameters:**

- `url: string | null | undefined` — The URL string to be processed. Can be `string`, `undefined`, or `null`.

**Returns:** `string | null | undefined` — The cleaned URL string, or `undefined` if the input is `undefined`, or `null` if the input is `null`.

**Examples:**

*Remove duplicate slashes*

Cleans an URL by removing duplicate slashes while preserving the protocol.

```typescript
cleanPath('/path//to///resource')
// => '/path/to/resource'
```

*Preserve protocol*

The double slash after the protocol (http://) is not modified.

```typescript
cleanPath('http://example.com//path')
// => 'http://example.com/path'
```

*Handle null and undefined*

Returns null for null input and undefined for undefined input.

```typescript
cleanPath(null)      // => null
cleanPath(undefined) // => undefined
```

---

### `extractPureURI`

Extracts the pure URI from a URL by removing query parameters and fragments.

```typescript
import { extractPureURI } from '@helpers4/url';

extractPureURI(url: string): string
```

**Parameters:**

- `url: string` — The URL string to process

**Returns:** `string` — The URI without query parameters and fragments, or the original value if undefined/null

```typescript
import { extractPureURI } from '@helpers4/url';

extractPureURI(url: undefined): undefined
```

**Parameters:**

- `url: undefined` — The URL string to process

**Returns:** `undefined` — The URI without query parameters and fragments, or the original value if undefined/null

```typescript
import { extractPureURI } from '@helpers4/url';

extractPureURI(url: null): null
```

**Parameters:**

- `url: null` — The URL string to process

**Returns:** `null` — The URI without query parameters and fragments, or the original value if undefined/null

**Examples:**

*Remove query parameters and fragments*

Strips everything after ? or # from the URL.

```typescript
extractPureURI('https://example.com/path?query=1#section')
// => 'https://example.com/path'
```

---

### `isExternal`

Whether a link points to another origin than `base`: an absolute `http(s)` URL or a
protocol-relative one (`//host/path`). Paths, anchors, query strings and non-HTTP schemes
(`mailto:`, `tel:`) are never external.

Without `base`, any absolute or protocol-relative URL counts as external. With a `base`,
a link to the same origin is internal: same scheme, host and port, the default port of the
scheme (80 for `http`, 443 for `https`) being the same as no port. A `base` with no scheme and
host, or a link with no host, gives `false`.

It reads the origin from the text and uses no `URL` global, so it runs on every runtime. A real
`URL` is accepted as `base`, as is any object with an `href`.

```typescript
import { isExternal } from '@helpers4/url';

isExternal(url: string, base?: string | object): boolean
```

**Parameters:**

- `url: string` — The link to check
- `base?: string | object` — The current origin or page URL to compare with (optional)

**Returns:** `boolean` — `true` if the link leaves the origin, `false` otherwise

**Examples:**

*Open external links in a new tab*

Compares the link with the current origin: same-origin absolute links stay internal.

```typescript
isExternal('https://github.com/helpers4', 'https://helpers4.dev')
// => true
isExternal('https://helpers4.dev/docs', 'https://helpers4.dev')
// => false
```

*Paths and non-HTTP schemes*

Relative paths, anchors, mailto: and tel: are never external; protocol-relative URLs are.

```typescript
isExternal('/docs')                 // => false
isExternal('mailto:hi@example.com') // => false
isExternal('//cdn.example.com/a.js') // => true
```

---

### `onlyPath`

Extract only the path from an URI with optional query and fragments.

For example, all these parameters will return `/path`:
 - `/path`
 - `/path?query=thing`
 - `/path#fragment`
 - `/path?query=thing#fragment`

```typescript
import { onlyPath } from '@helpers4/url';

onlyPath(url: string): string
```

**Parameters:**

- `url: string` — The URL string to be processed. Can be `string`, `undefined`, or `null`.

**Returns:** `string` — The URL string without query and fragment, or `undefined` if the input is `undefined`, or `null` if the input is `null`.

```typescript
import { onlyPath } from '@helpers4/url';

onlyPath(url: null): null
```

**Parameters:**

- `url: null` — The URL string to be processed. Can be `string`, `undefined`, or `null`.

**Returns:** `null` — The URL string without query and fragment, or `undefined` if the input is `undefined`, or `null` if the input is `null`.

```typescript
import { onlyPath } from '@helpers4/url';

onlyPath(url: undefined): undefined
```

**Parameters:**

- `url: undefined` — The URL string to be processed. Can be `string`, `undefined`, or `null`.

**Returns:** `undefined` — The URL string without query and fragment, or `undefined` if the input is `undefined`, or `null` if the input is `null`.

**Examples:**

*Extract the path from a URL*

Strips query parameters and fragments from a URL path.

```typescript
onlyPath('/path?query=thing#fragment')
// => '/path'
```

---

### `parsePackageRepository`

Parse the `repository` field from `package.json` into a structured object.

Supports all npm-specified formats:
- **Object form**: `{ "type": "git", "url": "...", "directory": "..." }`
- **GitHub shorthand**: `"owner/repo"` or `"github:owner/repo"`
- **Platform shorthands**: `"gitlab:owner/repo"`, `"bitbucket:owner/repo"`
- **Gist shorthand**: `"gist:<id>"`
- **URL forms**: `git+https://`, `https://`, `git://`, `git@` SSH, `git+ssh://`

Returns `undefined` for `null`, `undefined`, arrays, or values that cannot
be matched to any recognised format.

```typescript
import { parsePackageRepository } from '@helpers4/url';

parsePackageRepository(repository: unknown): PackageRepository | undefined
```

**Parameters:**

- `repository: unknown` — The `repository` field value from `package.json`.

**Returns:** `PackageRepository | undefined` — A parsed PackageRepository object, or `undefined` if the
  input cannot be parsed.

**Examples:**

*Parse the npm canonical object form*

Parses the full object form written by npm publish.

```typescript
parsePackageRepository({ type: 'git', url: 'git+https://github.com/helpers4/typescript.git' })
// => { type: 'git', host: 'github', slug: 'helpers4/typescript',
//      owner: 'helpers4', repo: 'typescript', gistId: undefined, directory: undefined }
```

*Parse npm shorthand forms*

npm accepts "owner/repo", "github:owner/repo", "gitlab:owner/repo" etc. as shorthand.

```typescript
parsePackageRepository('helpers4/typescript')
// => { host: 'github', slug: 'helpers4/typescript', owner: 'helpers4', repo: 'typescript', ... }

parsePackageRepository('gitlab:myorg/myproject')
// => { host: 'gitlab', slug: 'myorg/myproject', owner: 'myorg', repo: 'myproject', ... }

parsePackageRepository('gist:11081aaa281')
// => { host: 'gist', gistId: '11081aaa281', slug: undefined, owner: undefined, ... }
```

---

### `relativeURLToAbsolute`

Converts a relative URL to an absolute URL, using `base` when given, or else the current
document base URI (and the window origin when the document has none).

Works outside a browser as long as `base` is passed; without `base` and without a document it
throws a `TypeError`, since there is nothing to resolve against.

```typescript
import { relativeURLToAbsolute } from '@helpers4/url';

relativeURLToAbsolute(relativeUrl: string, base?: string): string
```

**Parameters:**

- `relativeUrl: string` — The relative URL to convert
- `base?: string` — The URL to resolve against. Defaults to the document base URI.

**Returns:** `string` — The absolute URL

**Examples:**

*Convert a relative URL to absolute*

Prepends the base URI to a relative path, cleaning duplicate slashes.

```typescript
relativeURLToAbsolute('/api/data')
// => 'http://localhost/api/data' (depends on document.baseURI)
```

*Resolve against an explicit base, with no browser*

Pass a base to use it in Node.js or during server-side rendering.

```typescript
relativeURLToAbsolute('/api/data', 'https://example.com')
// => 'https://example.com/api/data'
```

---

### `withLeadingSlash`

Adds a leading slash `/` to the given URL if it is not already present.

This function is useful for ensuring that URLs are properly formatted
with a leading slash, which is often required in web development for
consistency and to avoid issues with relative paths.

```typescript
import { withLeadingSlash } from '@helpers4/url';

withLeadingSlash(url: string): string
```

**Parameters:**

- `url: string` — The URL string to be processed. Can be `string`, `undefined`, or `null`.

**Returns:** `string` — The URL string with a leading slash, or `undefined` if the input is `undefined`, or `null` if the input is `null`.

```typescript
import { withLeadingSlash } from '@helpers4/url';

withLeadingSlash(url: undefined): undefined
```

**Parameters:**

- `url: undefined` — The URL string to be processed. Can be `string`, `undefined`, or `null`.

**Returns:** `undefined` — The URL string with a leading slash, or `undefined` if the input is `undefined`, or `null` if the input is `null`.

```typescript
import { withLeadingSlash } from '@helpers4/url';

withLeadingSlash(url: null): null
```

**Parameters:**

- `url: null` — The URL string to be processed. Can be `string`, `undefined`, or `null`.

**Returns:** `null` — The URL string with a leading slash, or `undefined` if the input is `undefined`, or `null` if the input is `null`.

**Examples:**

*Add a leading slash*

Ensures the URL starts with a forward slash.

```typescript
withLeadingSlash('path/to/resource')
// => '/path/to/resource'
```

*Already has leading slash*

Does not add a duplicate slash.

```typescript
withLeadingSlash('/already/has/slash')
// => '/already/has/slash'
```

---

### `withoutLeadingSlash`

Removes the leading slash `/` from the given URL if it is present.

This function is useful for ensuring that URLs are properly formatted
without a leading slash, which is often required in web development for
consistency and to avoid issues with relative paths.

```typescript
import { withoutLeadingSlash } from '@helpers4/url';

withoutLeadingSlash(url: string): string
```

**Parameters:**

- `url: string` — The URL string to be processed. Can be `string`, `undefined`, or `null`.

**Returns:** `string` — The URL string without a leading slash, or `undefined` if the input is `undefined`, or `null` if the input is `null`.

```typescript
import { withoutLeadingSlash } from '@helpers4/url';

withoutLeadingSlash(url: undefined): undefined
```

**Parameters:**

- `url: undefined` — The URL string to be processed. Can be `string`, `undefined`, or `null`.

**Returns:** `undefined` — The URL string without a leading slash, or `undefined` if the input is `undefined`, or `null` if the input is `null`.

```typescript
import { withoutLeadingSlash } from '@helpers4/url';

withoutLeadingSlash(url: null): null
```

**Parameters:**

- `url: null` — The URL string to be processed. Can be `string`, `undefined`, or `null`.

**Returns:** `null` — The URL string without a leading slash, or `undefined` if the input is `undefined`, or `null` if the input is `null`.

**Examples:**

*Remove leading slash*

Strips the leading slash from a URL path.

```typescript
withoutLeadingSlash('/path/to/resource')
// => 'path/to/resource'
```

---

### `withoutTrailingSlash`

Removes the trailing slash `/` from the given URL if it is present.

This function is useful for ensuring that URLs are properly formatted
without a trailing slash, which is often required in web development for
consistency and to avoid issues with relative paths.

```typescript
import { withoutTrailingSlash } from '@helpers4/url';

withoutTrailingSlash(url: string): string
```

**Parameters:**

- `url: string` — The URL string to be processed. Can be `string`, `undefined`, or `null`.

**Returns:** `string` — The URL string without a trailing slash, or `undefined` if the input is `undefined`, or `null` if the input is `null`.

```typescript
import { withoutTrailingSlash } from '@helpers4/url';

withoutTrailingSlash(url: undefined): undefined
```

**Parameters:**

- `url: undefined` — The URL string to be processed. Can be `string`, `undefined`, or `null`.

**Returns:** `undefined` — The URL string without a trailing slash, or `undefined` if the input is `undefined`, or `null` if the input is `null`.

```typescript
import { withoutTrailingSlash } from '@helpers4/url';

withoutTrailingSlash(url: null): null
```

**Parameters:**

- `url: null` — The URL string to be processed. Can be `string`, `undefined`, or `null`.

**Returns:** `null` — The URL string without a trailing slash, or `undefined` if the input is `undefined`, or `null` if the input is `null`.

**Examples:**

*Remove trailing slash*

Strips the trailing slash from a URL path.

```typescript
withoutTrailingSlash('path/to/resource/')
// => 'path/to/resource'
```

---

### `withTrailingSlash`

Adds a trailing slash `/` to the given URL if it is not already present.

This function is useful for ensuring that URLs are properly formatted
with a trailing slash, which is often required in web development for
consistency and to avoid issues with relative paths.

```typescript
import { withTrailingSlash } from '@helpers4/url';

withTrailingSlash(url: string): string
```

**Parameters:**

- `url: string` — The URL string to be processed. Can be `string`, `undefined`, or `null`.

**Returns:** `string` — The URL string with a trailing slash, or `undefined` if the input is `undefined`, or `null` if the input is `null`.

```typescript
import { withTrailingSlash } from '@helpers4/url';

withTrailingSlash(url: undefined): undefined
```

**Parameters:**

- `url: undefined` — The URL string to be processed. Can be `string`, `undefined`, or `null`.

**Returns:** `undefined` — The URL string with a trailing slash, or `undefined` if the input is `undefined`, or `null` if the input is `null`.

```typescript
import { withTrailingSlash } from '@helpers4/url';

withTrailingSlash(url: null): null
```

**Parameters:**

- `url: null` — The URL string to be processed. Can be `string`, `undefined`, or `null`.

**Returns:** `null` — The URL string with a trailing slash, or `undefined` if the input is `undefined`, or `null` if the input is `null`.

**Examples:**

*Add a trailing slash*

Ensures the URL ends with a forward slash.

```typescript
withTrailingSlash('path/to/resource')
// => 'path/to/resource/'
```

---

## version

Package: `@helpers4/version`

### `compare`

Compares two version strings, according to the given `scheme`.

**`'semver'`** (default) — SemVer 2.0.0 precedence rules:
- Core version: MAJOR.MINOR.PATCH
- Pre-release: -alpha, -beta.1, -rc.1, etc. (sorts below the plain release)
- Build metadata: +build, +sha.abc123 (ignored in comparison per spec)
- Optional 'v' prefix

**`'gentoo'`** — Gentoo/Portage ebuild version ordering (see ParsedGentooVersion):
numeric components, then letter suffix, then suffix segment (`alpha`/`beta`/`pre`/`rc` sort
below the plain release, `p` sorts above it), then `-r` revision. Note the key difference
from SemVer: a `-r` revision is *not* a prerelease and sorts *above* the base version.

**`'debian'`** — dpkg/apt ordering (see ParsedDebianVersion): epoch first, then the
upstream version, then the Debian revision, each compared like dpkg's `verrevcmp` — digit runs
numerically, everything else character by character with `~` sorting before everything,
even the end of the string (`1.0~rc1` < `1.0`). Throws a `SyntaxError` on an invalid version.

**`'rpm'`** — RPM ordering (see ParsedRpmVersion): epoch, then version, then release (when
both have one), each compared like `rpmvercmp` — numeric and alphabetic segments in turn, a number
newer than letters, `~` sorting before everything and `^` after the end of the string.

**`'pacman'`** — Arch Linux `vercmp` ordering (see ParsedPacmanVersion): like RPM's, but
longer separators win and a trailing letter segment sorts below the same version without it.

**`'pep440'`** — PEP 440 ordering (see ParsedPep440Version): epoch, release (`1.0` equals
`1`), then `dev` < `a` < `b` < `rc` < final < post-release, and local labels last. Every spelling
PEP 440 accepts is understood. Throws a `SyntaxError` on an invalid version.

**`'maven'`** — Apache Maven's `ComparableVersion` ordering (see ParsedMavenVersion): `.`,
`-` and every digit/letter switch split the version; `alpha` < `beta` < `milestone` < `rc` <
`snapshot` < release < `sp`, then unknown qualifiers in lexical order, all after the release;
`1`, `1.0` and `1-ga` are equal.

```typescript
import { compare } from '@helpers4/version';

compare(version1: string, version2: string, scheme: VersionScheme): number
```

**Parameters:**

- `version1: string` — First version string
- `version2: string` — Second version string
- `scheme: VersionScheme` (default: `'semver'`) — Which version scheme to compare `version1`/`version2` as. Defaults to `'semver'`.

**Returns:** `number` — -1 if version1 < version2, 0 if equal, 1 if version1 > version2

**Examples:**

*Compare two semver versions*

Returns -1, 0, or 1 based on SemVer ordering.

```typescript
compare('1.0.0', '2.0.0') // => -1
compare('1.0.0', '1.0.0') // => 0
compare('2.0.0', '1.0.0') // => 1
```

*Prerelease is lower than release*

A prerelease version is always less than the release.

```typescript
compare('1.0.0-alpha', '1.0.0')
// => -1
```

*Gentoo: a revision sorts above its base version*

Unlike SemVer's '-' (prerelease, sorts below release), Gentoo's '-r' revision sorts above it.

```typescript
compare('1.2.3', '1.2.3-r1', 'gentoo')
// => -1
```

*Debian: ~ sorts before the release*

dpkg ordering: a '~' sorts before everything, even the end of the string, and the epoch before ':' wins over the rest.

```typescript
compare('1.0~rc1-1', '1.0-1', 'debian')
// => -1
compare('1:0.9', '2.0', 'debian')
// => 1
```

---

### `increment`

Increments a version, according to the given `scheme`.

**`'semver'`** (default) — bumps `major`/`minor`/`patch` per SemVer, resetting the
finer-grained components (bumping `major` resets `minor` and `patch` to `0`, etc.) and
dropping any prerelease/build metadata.

**`'gentoo'`** — bumps the component at `type`'s position (`major` → 1st, `minor` → 2nd,
`patch` → 3rd — Gentoo's `components` array can be any length, but the first three follow
the same positional convention as SemVer), zeroing everything after it and dropping the
letter/suffixes/revision.

**`'debian'`** — throws: a Debian upstream version is free-form, with no major/minor/patch
structure to bump.

**`'rpm'`**, **`'pacman'`** — throw: the version is free-form, with no major/minor/patch
structure to bump.

**`'pep440'`** — bumps the release component at `type`'s position (padding it with zeros up to
there), zeroing everything after it and dropping the pre/post/dev/local parts; the epoch is kept.

**`'maven'`** — bumps the leading number at `type`'s position (padding with zeros), zeroing the
numbers after it and dropping every qualifier.

```typescript
import { increment } from '@helpers4/version';

increment(version: string, type: IncrementType, scheme?: VersionScheme): string
```

**Parameters:**

- `version: string` — The version to increment
- `type: IncrementType` — The increment type ('major', 'minor', 'patch')
- `scheme?: VersionScheme` — Which version scheme to interpret `version` as. Defaults to `'semver'`.

**Returns:** `string` — Incremented version string

```typescript
import { increment } from '@helpers4/version';

increment(version: undefined, type: IncrementType, scheme?: VersionScheme): undefined
```

**Parameters:**

- `version: undefined` — The version to increment
- `type: IncrementType` — The increment type ('major', 'minor', 'patch')
- `scheme?: VersionScheme` — Which version scheme to interpret `version` as. Defaults to `'semver'`.

**Returns:** `undefined` — Incremented version string

```typescript
import { increment } from '@helpers4/version';

increment(version: null, type: IncrementType, scheme?: VersionScheme): null
```

**Parameters:**

- `version: null` — The version to increment
- `type: IncrementType` — The increment type ('major', 'minor', 'patch')
- `scheme?: VersionScheme` — Which version scheme to interpret `version` as. Defaults to `'semver'`.

**Returns:** `null` — Incremented version string

**Examples:**

*Increment the patch version*

Bumps the patch number while keeping major and minor.

```typescript
increment('1.2.3', 'patch')
// => '1.2.4'
```

*Increment the minor version*

Bumps the minor number and resets patch to 0.

```typescript
increment('1.2.3', 'minor')
// => '1.3.0'
```

*Preserve the v prefix*

The v prefix is preserved if present in the input.

```typescript
increment('v1.0.0', 'major')
// => 'v2.0.0'
```

*Increment a Gentoo/Portage version*

Drops any letter/suffix/revision and resets components after the bumped one, same as the SemVer scheme.

```typescript
increment('1.2.3_rc1', 'patch', 'gentoo')
// => '1.2.4'
```

---

### `incrementPrerelease`

Increments the prerelease portion of a version, according to the given `scheme` — the
semantics `npm version prerelease --preid <id>` uses, not covered by increment (which
only handles `'major' | 'minor' | 'patch'`).

**`'semver'`** (default):
- No current prerelease (a release version) → bumps `patch` and starts a new prerelease line
  at `<prereleaseId>.0` (a prerelease of the version itself, e.g. `1.2.3`, would already be
  released).
- Same prerelease type as the current version → increments its counter.
- Different prerelease type (e.g. `alpha` → `beta`) → resets the counter to `0`.

Input prerelease can be any shape, but only the first two parts are considered;
output is always normalized to `<prereleaseId>.<number>`. Build metadata, if any, is
dropped — it's tied to the specific build that produced the input version, not the new one.
A leading `v` is preserved if present, matching increment's behavior (`parse`/
`stringify` alone would strip it — see their docs).

**`'gentoo'`** — the same rules, but `prereleaseId` must be one of the five real Gentoo
suffix types (`alpha`/`beta`/`pre`/`rc`/`p`), not a free-form string — Portage's suffix
vocabulary is fixed by spec, unlike SemVer's arbitrary prerelease identifiers. No current
prerelease suffix bumps the last numeric component instead of specifically `patch`, since
Gentoo's `components` array can be any length.

**`'debian'`** — throws: a Debian upstream version is free-form, with no prerelease counter
to bump.

**`'rpm'`**, **`'pacman'`**, **`'maven'`** — throw: the version is free-form, with no prerelease counter to bump.

**`'pep440'`** — `prereleaseId` is `a`, `b` or `rc` (or their spellings `alpha`, `beta`, `c`, `pre`,
`preview`). A version that is not a pre-release gets its patch bumped and starts at `<id>0`
(`1.2.3` → `1.2.4a0`); the same marker increments its number, another one restarts at `0`.

```typescript
import { incrementPrerelease } from '@helpers4/version';

incrementPrerelease(version: string, prereleaseId: string, scheme?: VersionScheme): string
```

**Parameters:**

- `version: string` — The version to increment
- `prereleaseId: string` — The prerelease type/identifier (e.g. `'alpha'`, `'beta'`, `'rc'`)
- `scheme?: VersionScheme` — Which version scheme to interpret `version` as. Defaults to `'semver'`.

**Returns:** `string` — The version with an incremented or newly-started prerelease

```typescript
import { incrementPrerelease } from '@helpers4/version';

incrementPrerelease(version: undefined, prereleaseId: string, scheme?: VersionScheme): undefined
```

**Parameters:**

- `version: undefined` — The version to increment
- `prereleaseId: string` — The prerelease type/identifier (e.g. `'alpha'`, `'beta'`, `'rc'`)
- `scheme?: VersionScheme` — Which version scheme to interpret `version` as. Defaults to `'semver'`.

**Returns:** `undefined` — The version with an incremented or newly-started prerelease

```typescript
import { incrementPrerelease } from '@helpers4/version';

incrementPrerelease(version: null, prereleaseId: string, scheme?: VersionScheme): null
```

**Parameters:**

- `version: null` — The version to increment
- `prereleaseId: string` — The prerelease type/identifier (e.g. `'alpha'`, `'beta'`, `'rc'`)
- `scheme?: VersionScheme` — Which version scheme to interpret `version` as. Defaults to `'semver'`.

**Returns:** `null` — The version with an incremented or newly-started prerelease

**Examples:**

*Start a new alpha line*

Bumping a release version starts a fresh prerelease at .0, one patch ahead.

```typescript
incrementPrerelease('1.2.3', 'alpha')
// => '1.2.4-alpha.0'
```

*Increment the same prerelease type*

Bumping with the same prereleaseId increments its counter.

```typescript
incrementPrerelease('1.2.4-alpha.0', 'alpha')
// => '1.2.4-alpha.1'
```

*Switch prerelease type*

Switching to a different prereleaseId resets the counter to 0, e.g. graduating from alpha to beta.

```typescript
incrementPrerelease('1.2.4-alpha.3', 'beta')
// => '1.2.4-beta.0'
```

*Increment a Gentoo/Portage prerelease*

prereleaseId must be one of Gentoo's fixed suffix types (alpha/beta/pre/rc/p), not a free-form string.

```typescript
incrementPrerelease('1.2.3', 'alpha', 'gentoo')
// => '1.2.4_alpha'
```

---

### `isPrerelease`

Returns `true` when the version string has a prerelease suffix, according to the given
`scheme`.

**`'semver'`** (default) — `true` when there's a `-` after the core `MAJOR.MINOR.PATCH`.

**`'gentoo'`** — `true` when the last suffix segment is `alpha`/`beta`/`pre`/`rc` (these sort
below the plain release). A `p` suffix or a `-r` revision don't count — `p` sorts *above* the
release, and a revision isn't a prerelease of anything, it's a rebuild of the same version.

**`'debian'`** — `true` when the upstream part contains `~`, the Debian convention for a
version that must sort before the final release (`1.0~rc1`). A `~` in the revision doesn't
count — `1.0-1~bpo12+1` is a backport of the `1.0` release, not a prerelease of it.

**`'rpm'`** — `true` when the version contains `~`, the RPM convention for a version that sorts
before the final release (`1.0~rc1`).

**`'pacman'`** — `true` when the version has an alphabetic segment after its first number, which
pacman sorts below the same version without it (`1.0rc1`).

**`'pep440'`** — `true` for an `a`/`b`/`rc` pre-release or a `dev` release, as Python's `packaging` does.

**`'maven'`** — `true` when there is an `alpha`, `beta`, `milestone`, `rc`/`cr` or `snapshot`
qualifier, all of which sort below the plain release.

```typescript
import { isPrerelease } from '@helpers4/version';

isPrerelease(version: string, scheme?: VersionScheme): boolean
```

**Parameters:**

- `version: string` — A version string (e.g. `'2.0.0-alpha.1'`, `'1.0.0'`, `'1.2.3_rc1'`).
- `scheme?: VersionScheme` — Which version scheme to interpret `version` as. Defaults to `'semver'`.

**Returns:** `boolean` — `true` if the version is a prerelease, `false` otherwise.

```typescript
import { isPrerelease } from '@helpers4/version';

isPrerelease(version: AnyParsedVersion): boolean
```

**Parameters:**

- `version: AnyParsedVersion` — A AnyParsedVersion object, as returned by parse.

**Returns:** `boolean` — `true` if `version` is a prerelease, `false` otherwise.

```typescript
import { isPrerelease } from '@helpers4/version';

isPrerelease(version: undefined): undefined
```

**Parameters:**

- `version: undefined` — A version string (e.g. `'2.0.0-alpha.1'`, `'1.0.0'`, `'1.2.3_rc1'`).

**Returns:** `undefined` — `true` if the version is a prerelease, `false` otherwise.

```typescript
import { isPrerelease } from '@helpers4/version';

isPrerelease(version: null): null
```

**Parameters:**

- `version: null` — A version string (e.g. `'2.0.0-alpha.1'`, `'1.0.0'`, `'1.2.3_rc1'`).

**Returns:** `null` — `true` if the version is a prerelease, `false` otherwise.

**Examples:**

*Detect a prerelease version*

Returns true for any version string that contains a prerelease suffix.

```typescript
isPrerelease('2.0.0-alpha.1') // true
isPrerelease('1.0.0-rc.0')   // true
```

*Stable versions return false*

Returns false when the version has no prerelease suffix.

```typescript
isPrerelease('1.0.0') // false
isPrerelease('2.1.3') // false
```

*Accept a ParsedVersion object*

Works with the result of parse() — checks the prerelease array instead of string matching.

```typescript
isPrerelease(parse('2.0.0-alpha.1')) // true
isPrerelease(parse('1.0.0'))         // false
```

---

### `isValid`

Whether `version` is a valid version in the given `scheme`. Never throws: any input that is
not valid, a non-string included, gives `false`.

**`'semver'`** (default) — SemVer 2.0.0, strictly: `MAJOR.MINOR.PATCH` with no leading zeros, an
optional `-prerelease` (numeric identifiers without leading zeros) and an optional `+build`.
Unlike parse, which reads anything, and unlike compare, a leading `v` is refused
by default (`v1.2.3` is a git tag, not a version; see IsValidOptions.prefix to accept or
require it), and so are `1.2` and `1.2.3.4`.

**`'gentoo'`**, **`'debian'`**, **`'rpm'`**, **`'pacman'`**, **`'pep440'`** — whether parse
accepts it (these schemes throw on invalid input, so their grammar is the one `parse` documents).

**`'maven'`** — any non-empty string: Maven reads every text as a version.

```typescript
import { isValid } from '@helpers4/version';

isValid(version: unknown, scheme: VersionScheme, options: IsValidOptions): boolean
```

**Parameters:**

- `version: unknown` — The value to check
- `scheme: VersionScheme` (default: `'semver'`) — Which version scheme to validate against. Defaults to `'semver'`.
- `options: IsValidOptions` (default: `{}`) — The treatment of a leading `v` — see IsValidOptions

**Returns:** `boolean` — `true` if `version` is a valid version

**Examples:**

*Validate a release version strictly*

Unlike parse, which reads anything, isValid refuses a v prefix, missing parts and leading zeros.

```typescript
isValid('1.2.3')    // => true
isValid('v1.2.3')   // => false
isValid('garbage')  // => false
```

*Check a git tag*

prefix: 'require' demands the v of a tag; 'allow' accepts both spellings.

```typescript
isValid('v1.2.3', 'semver', { prefix: 'require' }) // => true
isValid('1.2.3', 'semver', { prefix: 'require' })  // => false
```

*Validate in another scheme*

Debian versions are checked against dpkg's grammar.

```typescript
isValid('1:2.30~rc1-3', 'debian') // => true
isValid('1.0_1', 'debian')        // => false
```

---

### `parse`

Parses a version string into its components, according to the given `scheme`.

**`'semver'`** (default) — SemVer 2.0.0. Supports:
- Core version: MAJOR.MINOR.PATCH
- Pre-release: -alpha, -beta.1, -rc.1, -0.3.7, -x.7.z.92
- Build metadata: +build, +sha.abc123, +20130313144700
- Optional 'v' prefix (commonly used in git tags)

**`'gentoo'`** — Gentoo/Portage ebuild versions (see ParsedGentooVersion). Throws a
`SyntaxError` if `version` doesn't match the grammar (unlike `'semver'`, which never throws).

**`'debian'`** — Debian/dpkg versions, `[epoch:]upstream[-revision]` (see
ParsedDebianVersion). Throws a `SyntaxError` on whitespace, a non-numeric epoch, an
empty upstream or revision, or a character Debian Policy doesn't allow.

**`'rpm'`** — RPM versions, `[epoch:]version[-release]` (see ParsedRpmVersion). Throws a
`SyntaxError` on whitespace, a non-numeric epoch, an empty version or release, or a character RPM
does not allow.

**`'pacman'`** — Arch Linux package versions, `[epoch:]pkgver[-pkgrel]` (see
ParsedPacmanVersion). Throws a `SyntaxError` like `'rpm'`.

**`'pep440'`** — Python PEP 440 versions (see ParsedPep440Version); every spelling is
normalized (`1.0-ALPHA.2` → `pre: { type: 'a', number: 2 }`). Throws a `SyntaxError` if `version`
is not a valid PEP 440 version.

**`'maven'`** — Maven versions as `ComparableVersion` reads them (see ParsedMavenVersion).
Never throws: Maven accepts any text.

```typescript
import { parse } from '@helpers4/version';

parse(version: string, scheme?: "semver"): ParsedSemVerVersion
```

**Parameters:**

- `version: string` — Version string to parse
- `scheme?: "semver"` — Which version scheme to parse `version` as. Defaults to `'semver'`.

**Returns:** `ParsedSemVerVersion` — The parsed version, shaped per `scheme` — ParsedSemVerVersion for `'semver'`,
ParsedGentooVersion for `'gentoo'`, ParsedDebianVersion for `'debian'`, ParsedRpmVersion for `'rpm'`,
ParsedPacmanVersion for `'pacman'`, ParsedPep440Version for `'pep440'`, ParsedMavenVersion for `'maven'`.

```typescript
import { parse } from '@helpers4/version';

parse(version: string, scheme: "gentoo"): ParsedGentooVersion
```

**Parameters:**

- `version: string` — Version string to parse
- `scheme: "gentoo"` — Which version scheme to parse `version` as. Defaults to `'semver'`.

**Returns:** `ParsedGentooVersion` — The parsed version, shaped per `scheme` — ParsedSemVerVersion for `'semver'`,
ParsedGentooVersion for `'gentoo'`, ParsedDebianVersion for `'debian'`, ParsedRpmVersion for `'rpm'`,
ParsedPacmanVersion for `'pacman'`, ParsedPep440Version for `'pep440'`, ParsedMavenVersion for `'maven'`.

```typescript
import { parse } from '@helpers4/version';

parse(version: string, scheme: "debian"): ParsedDebianVersion
```

**Parameters:**

- `version: string` — Version string to parse
- `scheme: "debian"` — Which version scheme to parse `version` as. Defaults to `'semver'`.

**Returns:** `ParsedDebianVersion` — The parsed version, shaped per `scheme` — ParsedSemVerVersion for `'semver'`,
ParsedGentooVersion for `'gentoo'`, ParsedDebianVersion for `'debian'`, ParsedRpmVersion for `'rpm'`,
ParsedPacmanVersion for `'pacman'`, ParsedPep440Version for `'pep440'`, ParsedMavenVersion for `'maven'`.

```typescript
import { parse } from '@helpers4/version';

parse(version: string, scheme: "rpm"): ParsedRpmVersion
```

**Parameters:**

- `version: string` — Version string to parse
- `scheme: "rpm"` — Which version scheme to parse `version` as. Defaults to `'semver'`.

**Returns:** `ParsedRpmVersion` — The parsed version, shaped per `scheme` — ParsedSemVerVersion for `'semver'`,
ParsedGentooVersion for `'gentoo'`, ParsedDebianVersion for `'debian'`, ParsedRpmVersion for `'rpm'`,
ParsedPacmanVersion for `'pacman'`, ParsedPep440Version for `'pep440'`, ParsedMavenVersion for `'maven'`.

```typescript
import { parse } from '@helpers4/version';

parse(version: string, scheme: "pacman"): ParsedPacmanVersion
```

**Parameters:**

- `version: string` — Version string to parse
- `scheme: "pacman"` — Which version scheme to parse `version` as. Defaults to `'semver'`.

**Returns:** `ParsedPacmanVersion` — The parsed version, shaped per `scheme` — ParsedSemVerVersion for `'semver'`,
ParsedGentooVersion for `'gentoo'`, ParsedDebianVersion for `'debian'`, ParsedRpmVersion for `'rpm'`,
ParsedPacmanVersion for `'pacman'`, ParsedPep440Version for `'pep440'`, ParsedMavenVersion for `'maven'`.

```typescript
import { parse } from '@helpers4/version';

parse(version: string, scheme: "pep440"): ParsedPep440Version
```

**Parameters:**

- `version: string` — Version string to parse
- `scheme: "pep440"` — Which version scheme to parse `version` as. Defaults to `'semver'`.

**Returns:** `ParsedPep440Version` — The parsed version, shaped per `scheme` — ParsedSemVerVersion for `'semver'`,
ParsedGentooVersion for `'gentoo'`, ParsedDebianVersion for `'debian'`, ParsedRpmVersion for `'rpm'`,
ParsedPacmanVersion for `'pacman'`, ParsedPep440Version for `'pep440'`, ParsedMavenVersion for `'maven'`.

```typescript
import { parse } from '@helpers4/version';

parse(version: string, scheme: "maven"): ParsedMavenVersion
```

**Parameters:**

- `version: string` — Version string to parse
- `scheme: "maven"` — Which version scheme to parse `version` as. Defaults to `'semver'`.

**Returns:** `ParsedMavenVersion` — The parsed version, shaped per `scheme` — ParsedSemVerVersion for `'semver'`,
ParsedGentooVersion for `'gentoo'`, ParsedDebianVersion for `'debian'`, ParsedRpmVersion for `'rpm'`,
ParsedPacmanVersion for `'pacman'`, ParsedPep440Version for `'pep440'`, ParsedMavenVersion for `'maven'`.

```typescript
import { parse } from '@helpers4/version';

parse(version: string, scheme: VersionScheme): AnyParsedVersion
```

**Parameters:**

- `version: string` — Version string to parse
- `scheme: VersionScheme` — Which version scheme to parse `version` as. Defaults to `'semver'`.

**Returns:** `AnyParsedVersion` — The parsed version, shaped per `scheme` — ParsedSemVerVersion for `'semver'`,
ParsedGentooVersion for `'gentoo'`, ParsedDebianVersion for `'debian'`, ParsedRpmVersion for `'rpm'`,
ParsedPacmanVersion for `'pacman'`, ParsedPep440Version for `'pep440'`, ParsedMavenVersion for `'maven'`.

```typescript
import { parse } from '@helpers4/version';

parse(version: undefined, scheme?: VersionScheme): undefined
```

**Parameters:**

- `version: undefined` — Version string to parse
- `scheme?: VersionScheme` — Which version scheme to parse `version` as. Defaults to `'semver'`.

**Returns:** `undefined` — The parsed version, shaped per `scheme` — ParsedSemVerVersion for `'semver'`,
ParsedGentooVersion for `'gentoo'`, ParsedDebianVersion for `'debian'`, ParsedRpmVersion for `'rpm'`,
ParsedPacmanVersion for `'pacman'`, ParsedPep440Version for `'pep440'`, ParsedMavenVersion for `'maven'`.

```typescript
import { parse } from '@helpers4/version';

parse(version: null, scheme?: VersionScheme): null
```

**Parameters:**

- `version: null` — Version string to parse
- `scheme?: VersionScheme` — Which version scheme to parse `version` as. Defaults to `'semver'`.

**Returns:** `null` — The parsed version, shaped per `scheme` — ParsedSemVerVersion for `'semver'`,
ParsedGentooVersion for `'gentoo'`, ParsedDebianVersion for `'debian'`, ParsedRpmVersion for `'rpm'`,
ParsedPacmanVersion for `'pacman'`, ParsedPep440Version for `'pep440'`, ParsedMavenVersion for `'maven'`.

**Examples:**

*Parse a semver string*

Breaks a semantic version string into its components.

```typescript
parse('1.2.3')
// => { scheme: 'semver', major: 1, minor: 2, patch: 3, prerelease: [], build: [] }
```

*Parse a prerelease version*

Handles prerelease identifiers and optional v prefix.

```typescript
parse('v2.0.0-alpha.1')
// => { scheme: 'semver', major: 2, minor: 0, patch: 0, prerelease: ['alpha', '1'], build: [] }
```

*Parse a Gentoo/Portage ebuild version*

Pass 'gentoo' as the scheme to parse Gentoo's own version format instead of SemVer.

```typescript
parse('1.2.3b_rc1-r2', 'gentoo')
// => { scheme: 'gentoo', components: [1, 2, 3], letter: 'b', suffixes: [{ type: 'rc', number: 1 }], revision: 2 }
```

*Parse a Debian version*

Splits epoch, upstream version and Debian revision the way dpkg does.

```typescript
parse('1:2.30~rc1-3ubuntu2', 'debian')
// => { scheme: 'debian', epoch: 1, upstream: '2.30~rc1', revision: '3ubuntu2' }
```

---

### `ParsedVersion`

A version parsed according to SemVer 2.0.0 — alias of ParsedSemVerVersion, kept under
this name for backward compatibility (public API since 2.0.0, well before Gentoo/Portage
support existed). Use AnyParsedVersion to accept a parsed version in any supported
scheme, e.g. when writing scheme-agnostic code like stringify or isPrerelease.

---

### `satisfiesRange`

Checks if a version satisfies a range, according to the given `scheme` (simple
implementation — see each scheme's own doc for exactly which operators are supported).

**`'semver'`** (default) — `>=`, `>`, `<=`, `<`, `^` (caret, patch+minor updates within the
same major), `~` (tilde, patch updates within the same major.minor), or an exact match.

**`'gentoo'`** — `>=`, `>`, `<=`, `<`, or an exact match, compared per Gentoo/Portage
ordering (see compare). `^`/`~` throw: Portage's own atom syntax gives those
characters different, unrelated meanings, so silently reusing SemVer's semantics for them
would be actively misleading rather than merely unsupported.

**`'debian'`** — dpkg relation operators, as written in `Depends:` fields: `<<` (strictly
earlier), `<=`, `=`, `>=`, `>>` (strictly later), or an exact match, compared per dpkg ordering
(see compare); whitespace after the operator is allowed (`>= 1.0`). The obsolete
single-character `<`/`>` throw — dpkg reads them as `<=`/`>=`, the opposite of what they look
like — and so do `^`/`~`.

**`'rpm'`**, **`'pacman'`** — dependency relations: `<`, `<=`, `=` (or `==`), `>=`, `>` followed by a
version, or a bare version for an exact match; whitespace after the operator is allowed. Compared
per RPM / pacman ordering (see compare).

**`'pep440'`** — a PEP 440 specifier set, as in `requirements.txt`: comma-separated clauses that
must all hold, each one of `==` / `!=` (also with a `.*` prefix, e.g. `==1.2.*`), `<`, `<=`, `>`,
`>=`, `~=` (compatible release: `~=1.4.5` is `>=1.4.5, ==1.4.*`) or `===` (exact string). Follows
`packaging`'s rules: `<2.0` does not admit `2.0rc1`, `>2.0` does not admit `2.0.post1`. Pre-releases
are not excluded otherwise.

**`'maven'`** — a Maven version range: `[1.0,2.0)` (`[`/`]` include a bound, `(`/`)` exclude it, a
missing bound is open), `[1.5]` for exactly 1.5, several joined by commas for a union
(`(,1.0],[1.2,)`). A bare version is an exact match (in a POM it would be a soft preference).
Throws a `SyntaxError` on a malformed range.

```typescript
import { satisfiesRange } from '@helpers4/version';

satisfiesRange(version: string, range: string, scheme: VersionScheme): boolean
```

**Parameters:**

- `version: string` — Version to check
- `range: string` — Range pattern (e.g., ">=1.0.0", "~1.2.0", "^1.0.0")
- `scheme: VersionScheme` (default: `'semver'`) — Which version scheme to interpret `version`/`range` as. Defaults to `'semver'`.

**Returns:** `boolean` — True if version satisfies the range

**Examples:**

*Check caret range*

Caret (^) allows patch and minor updates within the same major.

```typescript
satisfiesRange('1.2.3', '^1.0.0')
// => true
```

*Check greater-than-or-equal range*

The >= operator checks if the version is at least the specified value.

```typescript
satisfiesRange('2.0.0', '>=1.5.0')
// => true
```

*Out of range*

Returns false when the version does not satisfy the range.

```typescript
satisfiesRange('0.9.0', '>=1.0.0')
// => false
```

*Check a Gentoo/Portage range*

Supports >=, >, <=, <, and exact match — ^ and ~ throw, since Portage gives those characters different, unrelated meanings.

```typescript
satisfiesRange('1.2.3', '>=1.2.0', 'gentoo')
// => true
```

*Debian relation operators*

Uses dpkg's '<<', '<=', '=', '>=' and '>>', as written in a Depends: field.

```typescript
satisfiesRange('1.0~rc1-1', '<< 1.0', 'debian')
// => true
```

---

### `sortVersions`

Sorts version strings by version, not by text (`1.10.0` after `1.9.0`), in the given scheme: the
same as `versions.sort((a, b) => compare(a, b, scheme))`, without mutating the input. Versions
that compare as equal keep their order. Strings are returned as they were written (a `v` prefix
stays).

Every version is compared with compare, so in the schemes that throw on invalid input
(`'gentoo'`, `'debian'`, …) a bad version throws a `SyntaxError`: filter with isValid first.

```typescript
import { sortVersions } from '@helpers4/version';

sortVersions<T extends string>(versions: readonly T[], options: SortVersionsOptions): T[]
```

**Parameters:**

- `versions: readonly T[]` — The versions to sort
- `options: SortVersionsOptions` (default: `{}`) — Order and scheme — see SortVersionsOptions

**Returns:** `T[]` — A new sorted array

**Examples:**

*Sort versions, not strings*

1.10.0 comes after 1.9.0, which a plain sort() gets wrong.

```typescript
sortVersions(['1.10.0', '1.2.0', '1.9.0'])
// => ['1.2.0', '1.9.0', '1.10.0']
```

*Find the latest tag*

Newest first; the v prefix of git tags is kept.

```typescript
sortVersions(['v1.0.0', 'v2.0.0-rc.1', 'v1.5.0'], { order: 'desc' })[0]
// => 'v2.0.0-rc.1'
```

---

### `stringify`

Reconstructs a version string from a AnyParsedVersion object — the scheme is read from
the object's own `scheme` field, not passed separately (a `ParsedGentooVersion` can only ever
stringify as Gentoo, so there's nothing to disambiguate).

This is the inverse of parse:
`stringify(parse(v)) === stripV(v)` for any valid version string `v`, in any scheme — up to
canonicalization (a Debian `0:` epoch is dropped, a Gentoo `_beta0` becomes `_beta`, a PEP 440
`1.0-ALPHA` becomes `1.0a0`, a Maven `1.0.0` becomes `1`).

```typescript
import { stringify } from '@helpers4/version';

stringify(parsed: AnyParsedVersion): string
```

**Parameters:**

- `parsed: AnyParsedVersion` — A parsed version object, as returned by parse.

**Returns:** `string` — The reconstructed version string (without leading `v`).

```typescript
import { stringify } from '@helpers4/version';

stringify(parsed: undefined): undefined
```

**Parameters:**

- `parsed: undefined` — A parsed version object, as returned by parse.

**Returns:** `undefined` — The reconstructed version string (without leading `v`).

```typescript
import { stringify } from '@helpers4/version';

stringify(parsed: null): null
```

**Parameters:**

- `parsed: null` — A parsed version object, as returned by parse.

**Returns:** `null` — The reconstructed version string (without leading `v`).

**Examples:**

*Reconstruct a stable version*

Converts a ParsedVersion object back to a version string.

```typescript
stringify({ scheme: 'semver', major: 1, minor: 2, patch: 3, prerelease: [], build: [] })
// => '1.2.3'
```

*Round-trip with parse*

stringify(parse(v)) returns the original version string (without leading v).

```typescript
stringify(parse('2.0.0-alpha.1'))
// => '2.0.0-alpha.1'

stringify(parse('1.0.0-beta+exp.sha.5114f85'))
// => '1.0.0-beta+exp.sha.5114f85'
```

*Reconstruct a Gentoo/Portage version*

The scheme is read from the parsed object itself, not passed separately.

```typescript
stringify({ scheme: 'gentoo', components: [1, 2, 3], letter: 'b', suffixes: [{ type: 'rc', number: 1 }], revision: 2 })
// => '1.2.3b_rc1-r2'
```

---

### `stripV`

Strip the leading "v" from a version string if it exists.

```typescript
import { stripV } from '@helpers4/version';

stripV(version: string): string
```

**Parameters:**

- `version: string` — The version string to process

**Returns:** `string` — The version string without leading "v", or the original value if it's not a string or doesn't start with "v"

```typescript
import { stripV } from '@helpers4/version';

stripV(version: null): null
```

**Parameters:**

- `version: null` — The version string to process

**Returns:** `null` — The version string without leading "v", or the original value if it's not a string or doesn't start with "v"

```typescript
import { stripV } from '@helpers4/version';

stripV(version: undefined): undefined
```

**Parameters:**

- `version: undefined` — The version string to process

**Returns:** `undefined` — The version string without leading "v", or the original value if it's not a string or doesn't start with "v"

**Examples:**

*Remove v prefix from a version string*

Strips the leading "v" from a git tag-style version string.

```typescript
stripV('v1.2.3')
// => '1.2.3'
```

*No-op when there is no v prefix*

Returns the string unchanged when it does not start with "v".

```typescript
stripV('1.2.3')
// => '1.2.3'
```

---