@rtorcato/js-common 4.0.0 → 6.0.0

package/AGENTS.md

@@ -2,16 +2,16 @@
 
 # Using @rtorcato/js-common
 
-`@rtorcato/js-common` is a tree-shakeable, ESM-only utility library for Node.js >= 22 (TypeScript-first, JSDoc on every public API). One subpath export per concern — 44 of them. The package root is intentionally empty.
+`@rtorcato/js-common` is a tree-shakeable, ESM-only utility library for Node.js >= 24 (TypeScript-first, JSDoc on every public API). One subpath export per concern — 42 of them. There is no package root export.
 
 ## Rules
 
-1. **Import from the subpath, never the package root.** The root export has no runtime code at all, so a root import gets you nothing.
+1. **Import from the subpath, never the package root.** The root has no `exports` entry at all, so a root import fails at resolve time (`ERR_PACKAGE_PATH_NOT_EXPORTED`) instead of silently binding nothing.
 
    ```ts
    // ✅ do
    import { slugify } from '@rtorcato/js-common/strings'
-   // ❌ don't — the root export is empty by design
+   // ❌ don't — there is no root export; this throws at resolve time
    import { slugify } from '@rtorcato/js-common'
    ```
 
@@ -19,12 +19,12 @@
 
    | Looks like | Actually |
    |---|---|
-   | `functions.once` vs `events.onceEvent` | `once(fn)` memoises a call; `onceEvent(target, type)` awaits a DOM event |
+   | `functions.once` vs `events.onceEvent` | `once(fn)` memoises a call; `onceEvent(target, type)` awaits an `EventTarget` event |
    | `logger` vs `logging` | `logger` is one configured pino instance; `logging` is `console` helpers with no runtime deps |
    | `try.tryCatch` vs `errors.tryWithFallback` | Result object vs swallow-and-fall-back — see rule 3 |
    | `date.formatDate` vs `datetime.formatDateTimeLocal` | a UTC calendar day vs a local instant |
 
-   Where two modules used to ship the same name, the loser was deleted rather than aliased — [MODULE-BOUNDARIES.md](https://github.com/rtorcato/js-common/blob/main/MODULE-BOUNDARIES.md) records which side won and why.
+   Where two modules used to ship the same name, the loser was deleted — use `emails.isValidEmail`, `url.isValidUrl` and `process.getProcessPlatform` (not `validation.isEmail`, `validation.isUrl` or `os.getOsPlatform`). [MODULE-BOUNDARIES.md](https://github.com/rtorcato/js-common/blob/main/MODULE-BOUNDARIES.md) records which side won and why.
 
 3. **Three different error idioms — don't mix them up.**
 
@@ -44,7 +44,7 @@
 
    `tryCatch` in `errors` was renamed to `tryWithFallback` in 2.0; `tryCatch` now means the Result helper in `try`.
 
-4. **Node-only modules.** `crypto`, `security`, and `file` import `node:crypto` / `node:fs`; `logger` uses pino. Don't ship these to a browser bundle. `events` is the opposite — it wraps DOM `EventTarget` and is browser-only. `os`, `process`, `node`, and `system` probe for `process` / `window` and degrade rather than throw.
+4. **Node-only modules.** `file` imports `node:fs`; `logger` uses pino. `crypto` is Web Crypto (`globalThis.crypto`), so it runs anywhere — `hashString` and `hmacHash` return promises. Don't ship `file` or `logger` to a browser bundle. `events` wraps `EventTarget` / `CustomEvent`, which are globals in browsers and Node ≥ 22, so it runs in both. `os`, `process`, `node`, `system`, and `i18n` probe for `process` / `window` / `navigator` and degrade rather than throw. `console` and `env` read `process` unguarded, so a browser bundle needs the bundler to define it. Everything else runs anywhere. `src/runtime-boundaries.test.ts` enforces this paragraph and the `Runtime:` line on each docs module page.
 
 5. **`./types` is types-only.** It has a `types` field and no `import` field on purpose — use it for `import type { Prettify, Merge } from '@rtorcato/js-common/types'` only.
 
@@ -57,13 +57,13 @@ Import from `@rtorcato/js-common/<module>`.
 | Module | Exports |
 |---|---|
 | abortController | createAbortController, abortPromise, withAbort, abortAfter |
-| arrays | unique, chunk, compact, shuffle |
+| arrays | unique, chunk, compact, shuffle, partition, sortBy, zip |
 | boolean | toBoolean |
 | colors | randomColor, matchingTextColor, hexToRgb, rgbToHex, isValidHex, darken, lighten |
 | console | disableConsole, clearConsole |
 | crypto | hashString, randomHex, hmacHash, base64Encode, base64Decode |
 | currency | getCurrencySymbol, getCurrencyName, getCurrencyLocale, formatPrice, formatPriceCompact, parsePrice, parseCurrencyString, convertCurrency, isValidCurrencyCode, isValidCurrency |
-| date | today, parseDate, formatDate, daysBetween, diffInHours, diffInMinutes, isLeapYear, addDays, subDays, addMonths, getDayOfWeek, startOfDay, endOfDay, isWeekend, isSameDay, isToday, formatRelative |
+| date | today, parseDate, formatDate, daysBetween, diffInHours, diffInMinutes, isLeapYear, addDays, subDays, addMonths, getDayOfWeek, startOfDay, endOfDay, isWeekend, isWeekday, isSameDay, isToday, formatRelative |
 | datetime | nowIso, parseIsoDateTime, formatDateTimeLocal, getTimezoneOffset, toUtcDate, unixTimestamp, unixMillis, getIsoWeek, getIsoWeekInfo |
 | emails | isValidEmail, normalizeEmail, maskEmail, getEmailDomain, isFreeEmailProvider |
 | env | getENV, isDev, isProd, isTest, getNodeEnv, checkEnv, RootApiEnvSchema |
@@ -79,36 +79,37 @@ Import from `@rtorcato/js-common/<module>`.
 | logger | logger (pino instance — pretty in dev, JSON in prod) |
 | logging | logWithTimestamp, info, warn, error, captureConsole, ConsoleLevel |
 | maps | invertMap, mapValues, mergeMaps, objectToMap, mapToObject |
-| mime-types | lookup, types, extensions, mimeTypes |
+| mime-types | lookup, types, extensions, mimeTypes, FileExtension, MimeType, MimeValue |
 | node | nodeVersionCheck, getNodeMajorVersion, isNode, requireOptional |
-| numbers | clamp, roundTo, formatPercent, between, sum, average, mod |
+| numbers | clamp, roundTo, formatPercent, FormatPercentOptions, between, sum, average, mod, variance, stdDev, median, percentile |
 | objects | isPlainObject, deepMerge, omit, pick |
-| os | getOsPlatform, getOsRelease, getOsArch, getHomeDir, getTmpDir |
+| os | getOsRelease, getOsArch, getHomeDir, getTmpDir |
 | process | getProcessId, getProcessUptime, getCwd, getProcessPlatform, exitProcess, isCI |
-| promises | to, withTimeout |
+| promises | to, withTimeout, mapLimit, retry, RetryOptions |
 | random | randomInt, randomFloat, randomBool, randomElement, randomString |
 | regex | escapeRegExp, testRegex, matchAll, replaceAllRegex, splitByRegex |
-| security | stripScriptish, isStrongPassword, generateSecureToken |
+| security | stripScriptish, isStrongPassword |
 | sleep | sleep, sleepSync, sleepRandom, sleepWithAbort |
 | strings | titleCase, capitalize, camelCase, kebabCase, snakeCase, truncate, reverse, slugify, words, wordCount, pluralize, ordinalize, isBlank, mask, template |
 | system | isMacOs, isWindows, isLinux, isIOS, isAndroid, getPlatform, isTouchDevice |
 | time | nowTime, nowTimeShort, parseTime, formatTime, secondsBetween, pad2 |
-| try | tryCatch, isSuccess, Result, Success, Failure |
+| try | tryCatch, tryCatchSync, isSuccess, Result, Success, Failure |
 | types | Prettify, Merge (types only) |
 | url | isValidUrl, getQueryParams, setQueryParam, removeQueryParam, joinUrl, getHostname |
 | uuid | getUUIDv7, getShortUUID, toShortUUID, fromShortUUID, isUUID, isUUIDv4, isNilUUID, getUUIDVersion, getNilUUID, uuidToBytes, bytesToUUID |
-| validation | isDefined, isString, isNumber, isBoolean, isArray, isObject, isEmail, isUrl |
+| validation | isDefined, isString, isNumber, isBoolean, isArray, isObject |
 
 ## CLI
 
-The package also ships a binary for shell use:
+The package also ships a binary for shell use. Its UI packages are optional peers, so install them first
+(`npm install -g @rtorcato/js-common @inquirer/prompts chalk chalk-animation commander figlet gradient-string`):
 
 ```bash
-npx @rtorcato/js-common@latest date today
-npx @rtorcato/js-common@latest math sum 1 2 3
-npx @rtorcato/js-common@latest text capitalize "hello world"
+js-common date today
+js-common math sum 1 2 3
+js-common text capitalize "hello world"
 ```
 
 See [CLI.md](https://github.com/rtorcato/js-common/blob/main/CLI.md) for the full command list.
 
-For full signatures and examples, see <https://rtorcato.github.io/js-common/>.
+For full signatures and examples, see <https://docs.torcato.dev/js-common/>.

package/README.md

@@ -1,11 +1,11 @@
 # js-common
 
-<p align="center">
-  <picture>
-    <source media="(max-width: 600px)" srcset="./brand/banner-mobile.png">
-    <img src="./brand/banner.png" alt="js-common — Tree-shakeable TypeScript utilities: tiny bundles, full type safety, CLI included." width="100%">
-  </picture>
-</p>
+<!-- brand-kit:banner:start -->
+<picture>
+  <source media="(max-width: 640px)" srcset="./brand/banner-mobile.png">
+  <img src="./brand/banner.png" alt="js-common banner" width="1600">
+</picture>
+<!-- brand-kit:banner:end -->
 
 [![CI](https://github.com/rtorcato/js-common/actions/workflows/ci.yml/badge.svg)](https://github.com/rtorcato/js-common/actions/workflows/ci.yml)
 [![npm version](https://badge.fury.io/js/%40rtorcato%2Fjs-common.svg)](https://badge.fury.io/js/%40rtorcato%2Fjs-common)
@@ -13,13 +13,14 @@
 [![Bundle size](https://img.shields.io/bundlephobia/minzip/@rtorcato/js-common)](https://bundlephobia.com/package/@rtorcato/js-common)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
-[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D22.0.0-brightgreen.svg)](https://nodejs.org/)
-[![codecov](https://codecov.io/gh/rtorcato/js-common/branch/main/graph/badge.svg)](https://codecov.io/gh/rtorcato/js-common)
-[![Docs](https://img.shields.io/badge/docs-rtorcato.github.io%2Fjs--common-blue.svg)](https://rtorcato.github.io/js-common/)
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D24.0.0-brightgreen.svg)](https://nodejs.org/)
+[![Docs](https://img.shields.io/badge/docs-docs.torcato.dev%2Fjs--common-blue.svg)](https://docs.torcato.dev/js-common/)
 
 A comprehensive set of common JavaScript and TypeScript utilities for Node.js projects.
 
-📘 **Documentation:** <https://rtorcato.github.io/js-common/>
+> **Browser APIs live in [`@rtorcato/browser-common`](https://github.com/rtorcato/browser-common).** js-common covers runtime-agnostic JavaScript and Node.js. Wrappers around browser Web APIs, such as clipboard, storage, observers, geolocation, the DOM and user-agent detection, belong to browser-common. The two packages don't overlap.
+
+📘 **Documentation:** <https://docs.torcato.dev/js-common/>
 
 ## Features
 
@@ -27,7 +28,7 @@ A comprehensive set of common JavaScript and TypeScript utilities for Node.js pr
 - **TypeScript** — full type definitions, JSDoc on every public API
 - **CLI included** — optional binary for use in scripts and terminals
 - **Modular** — one module per concern, 42 subpaths
-- **Minimal runtime deps** — only `pino`, `uuid`, `short-uuid`, `zod`. CLI packages (`chalk`, `commander`, `figlet`, …) are `optionalDependencies` and only needed for the CLI.
+- **No required runtime deps** — `zod` (`./env`), `pino` (`./logger`, plus `pino-pretty` for pretty dev logs) and `uuid` + `short-uuid` (`./uuid`) are optional peers: install one only if you import its module. The CLI packages (`chalk`, `commander`, `figlet`, …) are optional peers too, needed only to run the `js-common` binary — see [CLI.md](CLI.md).
 
 ## Installation
 
@@ -35,6 +36,14 @@ A comprehensive set of common JavaScript and TypeScript utilities for Node.js pr
 npm install @rtorcato/js-common
 ```
 
+Three modules need an optional peer you install yourself:
+
+| Module | Peer |
+|---|---|
+| `./env` | `npm install zod` |
+| `./logger` | `npm install pino` (add `pino-pretty` for pretty dev logs) |
+| `./uuid` | `npm install uuid short-uuid` |
+
 Pre-release builds are published to the `beta` dist-tag, so they never reach a plain `npm install`:
 
 ```bash
@@ -64,9 +73,13 @@ npx skills add https://github.com/rtorcato/js-common --skill js-common
 
 ## Migrating
 
-**3.x → 4.x** — everything the runtime already does was removed. `./sets` and `./interval` are gone as modules, and the pass-through wrappers inside surviving modules went with them: `promises.all`/`allSettled`/`race`/`delay`, `boolean.and`/`or`/`not`/`xor`, `strings.padStart`/`padEnd`/`replaceString`, `arrays.first`/`last`/`flatten`/`groupBy`, `numbers.isInteger`/`isFiniteNumber`/`min`/`max`, `objects.deepClone`, `json.deepCloneJson` and `uuid.getUUID`. Nothing moved to another module — the replacement is a JavaScript built-in in every case, which the Node 22 floor guarantees. Two are **not** drop-ins: `Object.groupBy` returns a null-prototype object with optional values, and `structuredClone` keeps `Date`s where the JSON round trip flattened them. The full before/after table is in the [migration guide](https://rtorcato.github.io/js-common/docs/guides/migration).
+**5.x → 6.x** — the Node floor is now 24 (`engines.node >=24`). The CLI packages (`@inquirer/prompts`, `chalk`, `chalk-animation`, `commander`, `figlet`, `gradient-string`) and `pino-pretty` moved from `optionalDependencies` to optional `peerDependencies`, so a plain install no longer downloads them. To run the CLI, install them alongside the package; for pretty `./logger` output in dev, add `pino-pretty`. Details in the [migration guide](https://docs.torcato.dev/js-common/docs/guides/migration).
+
+**4.x → 5.x** — `zod`, `pino`, `uuid` and `short-uuid` moved from `dependencies` to optional `peerDependencies`. If you import `./env`, add `zod`; `./logger`, add `pino`; `./uuid`, add `uuid` and `short-uuid`. Every other module is unaffected. Details in the [migration guide](https://docs.torcato.dev/js-common/docs/guides/migration).
 
-**2.x → 3.x** — every helper now has exactly one home. `./formatting` and `./math` are gone, and where two modules shipped the same name the loser was deleted rather than aliased, so you get a build error naming the fix. One helper was also renamed rather than moved: `sanitizeString` is now `stripScriptish`, because the old name promised sanitising it never did — it removes `<script>` blocks and inline `on*` handlers and nothing else. The full before/after map is in the [migration guide](https://rtorcato.github.io/js-common/docs/guides/migration); the reasoning is in [MODULE-BOUNDARIES.md](MODULE-BOUNDARIES.md).
+**3.x → 4.x** — everything the runtime already does was removed. `./sets` and `./interval` are gone as modules, and the pass-through wrappers inside surviving modules went with them: `promises.all`/`allSettled`/`race`/`delay`, `boolean.and`/`or`/`not`/`xor`, `strings.padStart`/`padEnd`/`replaceString`, `arrays.first`/`last`/`flatten`/`groupBy`, `numbers.isInteger`/`isFiniteNumber`/`min`/`max`, `objects.deepClone`, `json.deepCloneJson` and `uuid.getUUID`. Nothing moved to another module — the replacement is a JavaScript built-in in every case, which the Node 22 floor guarantees. Two are **not** drop-ins: `Object.groupBy` returns a null-prototype object with optional values, and `structuredClone` keeps `Date`s where the JSON round trip flattened them. The full before/after table is in the [migration guide](https://docs.torcato.dev/js-common/docs/guides/migration).
+
+**2.x → 3.x** — every helper now has exactly one home. `./formatting` and `./math` are gone, and where two modules shipped the same name the loser was deleted rather than aliased, so you get a build error naming the fix. One helper was also renamed rather than moved: `sanitizeString` is now `stripScriptish`, because the old name promised sanitising it never did — it removes `<script>` blocks and inline `on*` handlers and nothing else. The full before/after map is in the [migration guide](https://docs.torcato.dev/js-common/docs/guides/migration); the reasoning is in [MODULE-BOUNDARIES.md](MODULE-BOUNDARIES.md).
 
 **1.x → 2.x** — the only breaking change in 2.0 is a rename in the `errors` module:
 
@@ -93,20 +106,18 @@ Prefer the Result-style `tryCatch` for new code; reserve `tryWithFallback` for c
 
 ## CLI Usage
 
-This package includes a command-line interface for many utilities:
+This package includes a command-line interface for many utilities. Its UI packages are optional peers, so install them alongside it:
 
 ```bash
 # Install globally to use the CLI
-npm install -g @rtorcato/js-common
-
-# Or use with npx
-npx @rtorcato/js-common@latest --help
+npm install -g @rtorcato/js-common @inquirer/prompts chalk chalk-animation commander figlet gradient-string
+js-common --help
 
 # Examples
-npx @rtorcato/js-common@latest date today
-npx @rtorcato/js-common@latest math sum 1 2 3 4 5
-npx @rtorcato/js-common@latest text capitalize "hello world"
-npx @rtorcato/js-common@latest system node-version
+js-common date today
+js-common math sum 1 2 3 4 5
+js-common text capitalize "hello world"
+js-common system node-version
 ```
 
 See [CLI.md](./CLI.md) for complete CLI documentation.
@@ -148,6 +159,7 @@ import { nowTime, parseTime, secondsBetween } from '@rtorcato/js-common/time'
 ### Numbers
 ```typescript
 import { sum, average, roundTo, clamp, formatPercent } from '@rtorcato/js-common/numbers'
+import { variance, stdDev, median, percentile } from '@rtorcato/js-common/numbers' // dispersion
 import { randomInt, randomFloat, randomBool, randomElement } from '@rtorcato/js-common/random'
 ```
 
@@ -161,7 +173,8 @@ import { detectLanguage, formatNumber, formatDateI18n, t } from '@rtorcato/js-co
 
 ### Security & Validation
 ```typescript
-import { isStrongPassword, generateSecureToken } from '@rtorcato/js-common/security'
+import { isStrongPassword, stripScriptish } from '@rtorcato/js-common/security'
+import { randomHex, hashString, hmacHash } from '@rtorcato/js-common/crypto'
 import { isValidEmail, maskEmail } from '@rtorcato/js-common/emails'
 import { isValidUrl } from '@rtorcato/js-common/url'
 import { isString, isNumber, isBoolean, isArray, isObject } from '@rtorcato/js-common/validation'
@@ -170,7 +183,7 @@ import { toBoolean } from '@rtorcato/js-common/boolean'
 
 ### Data Structures
 ```typescript
-import { unique, chunk, compact, shuffle } from '@rtorcato/js-common/arrays'
+import { unique, chunk, compact, shuffle, partition, sortBy, zip } from '@rtorcato/js-common/arrays'
 import { deepMerge, pick, omit, isPlainObject } from '@rtorcato/js-common/objects'
 import { safeJsonParse, safeJsonStringify } from '@rtorcato/js-common/json'
 import { invertMap, mapValues, objectToMap, mapToObject } from '@rtorcato/js-common/maps'
@@ -178,7 +191,7 @@ import { invertMap, mapValues, objectToMap, mapToObject } from '@rtorcato/js-com
 
 ### Async & Control Flow
 ```typescript
-import { to, withTimeout } from '@rtorcato/js-common/promises'
+import { retry, to, withTimeout } from '@rtorcato/js-common/promises'
 import { debounce, throttle, once } from '@rtorcato/js-common/functions'
 import { sleep } from '@rtorcato/js-common/sleep'
 import { tryCatch } from '@rtorcato/js-common/try'
@@ -189,9 +202,9 @@ import { createCustomError, getErrorMessage, assert } from '@rtorcato/js-common/
 ### System & Process
 ```typescript
 import { getENV, isDev, isProd, getNodeEnv, checkEnv } from '@rtorcato/js-common/env'
-import { getOsPlatform, getOsArch, getHomeDir } from '@rtorcato/js-common/os'
+import { getOsArch, getOsRelease, getHomeDir } from '@rtorcato/js-common/os'
 import { getNodeMajorVersion, isNode, requireOptional } from '@rtorcato/js-common/node'
-import { getProcessId, getCwd, exitProcess, isCI } from '@rtorcato/js-common/process'
+import { getProcessPlatform, getCwd, exitProcess, isCI } from '@rtorcato/js-common/process'
 import { isMacOs, isWindows, isLinux, getPlatform } from '@rtorcato/js-common/system'
 import { disableConsole, clearConsole } from '@rtorcato/js-common/console'
 ```
@@ -216,7 +229,7 @@ import { info, warn, error, captureConsole } from '@rtorcato/js-common/logging'
 
 ## Requirements
 
-- **Node.js** >= 22.0.0 (enforced via the `engines` field)
+- **Node.js** >= 24.0.0 (enforced via the `engines` field)
 - **TypeScript** >= 5.0.0 (for TypeScript projects)
 
 ## Development
@@ -242,9 +255,6 @@ pnpm run check:fix
 
 # Type checking
 pnpm run typecheck
-
-# Run micro-benchmarks (scripts/benchmark.mjs)
-pnpm run benchmark
 ```
 
 ## Documentation site
@@ -259,7 +269,7 @@ pnpm --filter @rtorcato/js-common-docs dev
 pnpm --filter @rtorcato/js-common-docs build
 ```
 
-Live site: <https://rtorcato.github.io/js-common/>
+Live site: <https://docs.torcato.dev/js-common/>
 
 ## Roadmap
 

package/dist/abortController/index.d.ts

@@ -16,7 +16,7 @@ export declare function createAbortController(): {
     signal: AbortSignal;
 };
 /**
- * Returns a promise that rejects when the given AbortSignal is aborted.
+ * Returns a promise that rejects with `signal.reason` when the given AbortSignal is aborted.
  *
  * @example
  * ```typescript
@@ -31,7 +31,8 @@ export declare function createAbortController(): {
  */
 export declare function abortPromise(signal: AbortSignal): Promise<never>;
 /**
- * Wraps a promise and rejects it if the signal is aborted.
+ * Wraps a promise and rejects it with `signal.reason` if the signal is aborted.
+ * The abort listener is removed once the promise settles.
  *
  * @example
  * ```typescript

package/dist/abortController/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/abortController/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB;;;EAGpC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,KAAK,CAAC,CAchE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC,CAEjF;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,UAAU,EAAE,eAAe,EAAE,EAAE,EAAE,MAAM,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC,CAEjG"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/abortController/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB;;;EAGpC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,KAAK,CAAC,CAKhE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC,CAiBjF;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,UAAU,EAAE,eAAe,EAAE,EAAE,EAAE,MAAM,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC,CAEjG"}

package/dist/abortController/index.js

@@ -1 +1 @@
-import"../chunks/chunk-ANN5UYCF.js";function n(){let r=new AbortController;return{controller:r,signal:r.signal}}function t(r){return new Promise((e,o)=>{r.aborted?o(new DOMException("Aborted","AbortError")):r.addEventListener("abort",()=>{o(new DOMException("Aborted","AbortError"))},{once:!0})})}function i(r,e){return Promise.race([r,t(e)])}function b(r,e){return setTimeout(()=>r.abort(),e)}export{b as abortAfter,t as abortPromise,n as createAbortController,i as withAbort};
+import"../chunks/chunk-ANN5UYCF.js";function u(){let e=new AbortController;return{controller:e,signal:e.signal}}function s(e){return new Promise((r,o)=>{e.aborted?o(e.reason):e.addEventListener("abort",()=>o(e.reason),{once:!0})})}function a(e,r){return r.aborted?Promise.reject(r.reason):new Promise((o,n)=>{let b=()=>n(r.reason);r.addEventListener("abort",b,{once:!0});let i=()=>r.removeEventListener("abort",b);e.then(t=>{i(),o(t)},t=>{i(),n(t)})})}function c(e,r){return setTimeout(()=>e.abort(),r)}export{c as abortAfter,s as abortPromise,u as createAbortController,a as withAbort};

package/dist/arrays/arrays.test-d.js

@@ -1 +1 @@
-import{a as r,b as t}from"../chunks/chunk-UQBVI52L.js";import"../chunks/chunk-ANN5UYCF.js";import{describe as a,expectTypeOf as e,it as u}from"vitest";a("arrays \u2014 types",()=>{u("unique preserves element type",()=>{e(r([1,2,3])).toEqualTypeOf(),e(r(["a"])).toEqualTypeOf()}),u("chunk returns array of arrays of the element type",()=>{e(t([1,2,3],2)).toEqualTypeOf(),e(t(["a","b"],1)).toEqualTypeOf()})});
+import{a as p,b as a,e as n,f as u,g as y}from"../chunks/chunk-U2F5TMN2.js";import"../chunks/chunk-ANN5UYCF.js";import{describe as o,expectTypeOf as e,it as r}from"vitest";o("arrays \u2014 types",()=>{r("unique preserves element type",()=>{e(p([1,2,3])).toEqualTypeOf(),e(p(["a"])).toEqualTypeOf()}),r("chunk returns array of arrays of the element type",()=>{e(a([1,2,3],2)).toEqualTypeOf(),e(a(["a","b"],1)).toEqualTypeOf()})});o("arrays \u2014 grouping helper types",()=>{r("partition returns a tuple of element arrays",()=>{e(n([1,2],t=>t>1)).toEqualTypeOf()}),r("sortBy preserves the element type",()=>{e(u([1,2],t=>t)).toEqualTypeOf()}),r("zip pairs both element types",()=>{e(y([1],["a"])).toEqualTypeOf()})});

package/dist/arrays/index.d.ts

@@ -68,4 +68,56 @@ export declare function compact<T>(arr: T[]): T[];
  * @category Array Utilities
  */
 export declare function shuffle<T>(arr: T[]): T[];
+/**
+ * Splits an array into two arrays: the elements that satisfy the predicate and
+ * the ones that do not. Order is preserved within each half.
+ *
+ * @example
+ * ```typescript
+ * partition([1, 2, 3, 4], (n) => n % 2 === 0) // [[2, 4], [1, 3]]
+ * partition(['a', 'bb'], (s) => s.length > 1) // [['bb'], ['a']]
+ * ```
+ *
+ * @param arr The array to split
+ * @param predicate Called with each element and its index; truthy sends the element to the first half
+ * @returns A `[pass, fail]` tuple of new arrays
+ * @category Array Utilities
+ */
+export declare function partition<T>(arr: T[], predicate: (value: T, index: number) => boolean): [T[], T[]];
+/**
+ * Sorts an array by a derived key, without mutating the input.
+ * Keys are compared with `<` / `>`, so strings sort lexicographically and
+ * numbers numerically — unlike `Array#sort`, which stringifies everything.
+ * The sort is stable, so equal keys keep their original order.
+ *
+ * @example
+ * ```typescript
+ * sortBy([{ n: 2 }, { n: 1 }], (o) => o.n) // [{ n: 1 }, { n: 2 }]
+ * sortBy([10, 9, 100], (n) => n) // [9, 10, 100] — not [10, 100, 9]
+ * sortBy(users, (u) => u.name, 'desc')
+ * ```
+ *
+ * @param arr The array to sort
+ * @param keyFn Maps an element to the value to sort by
+ * @param direction `'asc'` (default) or `'desc'`
+ * @returns A new sorted array
+ * @category Array Utilities
+ */
+export declare function sortBy<T>(arr: T[], keyFn: (value: T) => number | string | bigint | Date, direction?: 'asc' | 'desc'): T[];
+/**
+ * Pairs up two arrays element by element. The result is as long as the shorter
+ * input — surplus elements are dropped.
+ *
+ * @example
+ * ```typescript
+ * zip([1, 2, 3], ['a', 'b', 'c']) // [[1, 'a'], [2, 'b'], [3, 'c']]
+ * zip([1, 2, 3], ['a']) // [[1, 'a']]
+ * ```
+ *
+ * @param a The first array
+ * @param b The second array
+ * @returns An array of `[a[i], b[i]]` pairs
+ * @category Array Utilities
+ */
+export declare function zip<A, B>(a: A[], b: B[]): [A, B][];
 //# sourceMappingURL=index.d.ts.map

package/dist/arrays/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/arrays/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,CAEvC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,EAAE,EAAE,CAOtD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,CAExC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,CAOxC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/arrays/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,CAEvC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,EAAE,EAAE,CAOtD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,CAExC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,CAOxC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAC1B,GAAG,EAAE,CAAC,EAAE,EACR,SAAS,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,GAC7C,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAOZ;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,MAAM,CAAC,CAAC,EACvB,GAAG,EAAE,CAAC,EAAE,EACR,KAAK,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,EACpD,SAAS,GAAE,KAAK,GAAG,MAAc,GAC/B,CAAC,EAAE,CAWL;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAKlD"}

package/dist/arrays/index.js

@@ -1 +1 @@
-import{a,b,c,d}from"../chunks/chunk-UQBVI52L.js";import"../chunks/chunk-ANN5UYCF.js";export{b as chunk,c as compact,d as shuffle,a as unique};
+import{a,b,c,d,e,f,g}from"../chunks/chunk-U2F5TMN2.js";import"../chunks/chunk-ANN5UYCF.js";export{b as chunk,c as compact,e as partition,d as shuffle,f as sortBy,a as unique,g as zip};

package/dist/chunks/chunk-6FGK7LS2.js

@@ -0,0 +1 @@
+function e(r){return r.error===null}async function u(r){try{return{data:await r(),error:null}}catch(t){return{data:null,error:t}}}function a(r){try{return{data:r(),error:null}}catch(t){return{data:null,error:t}}}export{e as a,u as b,a as c};

package/dist/chunks/chunk-NEODDZIS.js

@@ -0,0 +1 @@
+import{d as c}from"./chunk-VSTXGIC3.js";async function h(t){try{return[null,await t]}catch(e){return[e,void 0]}}function w(t,e,a=new Error("Timeout")){return Promise.race([t,new Promise((n,i)=>setTimeout(()=>i(a),e))])}async function b(t,e={}){let{retries:a=3,minDelay:n=100,maxDelay:i=1e4,jitter:s=!0,shouldRetry:m=()=>!0,signal:o}=e;for(let r=1;;r++){o?.throwIfAborted();try{return await t(r,o)}catch(l){if(o?.aborted)throw o.reason;if(r>a||!m(l,r))throw l}let u=Math.min(i,n*2**(r-1));await c(s?Math.random()*u:u,o)}}async function f(t,e,a){if(!Number.isInteger(e)||e<1)throw new RangeError(`limit must be a positive integer, got ${e}`);let n=Array.from(t),i=new Array(n.length),s=0,m=!1;async function o(){for(;!m&&s<n.length;){let r=s++;try{i[r]=await a(n[r],r)}catch(u){throw m=!0,u}}}return await Promise.all(Array.from({length:Math.min(e,n.length)},o)),i}export{h as a,w as b,b as c,f as d};

package/dist/chunks/chunk-U2F5TMN2.js

@@ -0,0 +1 @@
+function s(o){return Array.from(new Set(o))}function i(o,t){if(t<1)throw new Error("Chunk size must be at least 1");let e=[];for(let r=0;r<o.length;r+=t)e.push(o.slice(r,r+t));return e}function T(o){return o.filter(Boolean)}function c(o){let t=o.slice();for(let e=t.length-1;e>0;e--){let r=Math.floor(Math.random()*(e+1));[t[e],t[r]]=[t[r],t[e]]}return t}function a(o,t){let e=[],r=[];return o.forEach((n,u)=>{(t(n,u)?e:r).push(n)}),[e,r]}function f(o,t,e="asc"){let r=e==="desc"?-1:1;return o.map((n,u)=>({value:n,index:u,key:t(n)})).sort((n,u)=>n.key<u.key?-r:n.key>u.key?r:n.index-u.index).map(n=>n.value)}function l(o,t){let e=Math.min(o.length,t.length),r=new Array(e);for(let n=0;n<e;n++)r[n]=[o[n],t[n]];return r}export{s as a,i as b,T as c,c as d,a as e,f,l as g};

package/dist/chunks/chunk-VSTXGIC3.js

@@ -0,0 +1 @@
+var m=o=>new Promise(e=>setTimeout(e,o));function s(o){let e=Date.now()+o;for(;Date.now()<e;);}function u(o,e){let r=Math.floor(Math.random()*(e-o+1))+o;return new Promise(t=>setTimeout(t,r))}function b(o,e){return new Promise((r,t)=>{if(e?.aborted){t(e.reason);return}let n=()=>{clearTimeout(i),t(e?.reason)},i=setTimeout(()=>{e?.removeEventListener("abort",n),r()},o);e?.addEventListener("abort",n,{once:!0})})}export{m as a,s as b,u as c,b as d};

package/dist/cli/index.mjs

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
 // Entry point for the js-common CLI binary.
-// CLI-only npm deps (chalk, commander, figlet, …) live under
-// `optionalDependencies` to keep the install footprint small for
-// library-only consumers. If any of them is missing at runtime we
-// catch the resolution error and print install instructions instead
-// of letting Node emit an opaque ERR_MODULE_NOT_FOUND trace.
+// CLI-only npm deps (chalk, commander, figlet, …) are optional
+// `peerDependencies`, so library-only consumers never install them. If any
+// of them is missing at runtime we catch the resolution error and print one
+// install line instead of letting Node emit an opaque ERR_MODULE_NOT_FOUND
+// trace. cli.test.ts fails if this list misses a package cli.ts imports.
+const CLI_PEERS = '@inquirer/prompts chalk chalk-animation commander figlet gradient-string';
 try {
     await import('./cli.mjs');
 }
@@ -14,11 +15,7 @@ catch (err) {
         'code' in err &&
         err.code === 'ERR_MODULE_NOT_FOUND';
     if (isMissingModule) {
-        process.stderr.write('The js-common CLI requires optional dependencies that are not installed.\n' +
-            'Install them globally to use the CLI:\n\n' +
-            '  npm install -g @rtorcato/js-common\n\n' +
-            'Or run it ad-hoc with npx, which installs them on demand:\n\n' +
-            '  npx @rtorcato/js-common@latest --help\n');
+        process.stderr.write(`js-common CLI: missing peer dependencies. Install them with: npm i -D ${CLI_PEERS}\n`);
         process.exit(1);
     }
     throw err;

package/dist/crypto/index.d.ts

@@ -1,25 +1,29 @@
 /**
  * Hashes a string using the specified algorithm.
  *
+ * Web Crypto supports SHA-1/256/384/512 only — there is no md5. An unsupported
+ * algorithm rejects.
+ *
  * @example
  * ```typescript
- * hashString('hello')
+ * await hashString('hello')
  * // '2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824'
- * hashString('hello', 'md5') // '5d41402abc4b2a76b9719d911017c592'
+ * await hashString('hello', 'sha1') // 'aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d'
  * ```
  *
  * @param str The string to hash.
  * @param algorithm The hash algorithm (default: 'sha256').
  * @returns The hex-encoded hash.
  */
-export declare function hashString(str: string, algorithm?: string): string;
+export declare function hashString(str: string, algorithm?: 'sha1' | 'sha256' | 'sha384' | 'sha512'): Promise<string>;
 /**
- * Generates a random hex string of the specified length (in bytes).
+ * Generates a cryptographically secure random hex string of the specified length (in bytes).
  *
  * @example
  * ```typescript
  * randomHex(4) // '9f3c1ab7' (8 hex chars)
  * randomHex() // 32 hex chars (16 bytes)
+ * randomHex(32) // 64 hex chars — a password-reset token
  * ```
  *
  * @param length The number of bytes (not hex chars).
@@ -31,9 +35,9 @@ export declare function randomHex(length?: number): string;
  *
  * @example
  * ```typescript
- * hmacHash('payload', 's3cret')
+ * await hmacHash('payload', 's3cret')
  * // 'd1d0f5b6...' (64 hex chars, stable for the same input + secret)
- * hmacHash('payload', 's3cret', 'sha1') // 40 hex chars
+ * await hmacHash('payload', 's3cret', 'sha1') // 40 hex chars
  * ```
  *
  * @param str The string to hash.
@@ -41,17 +45,18 @@ export declare function randomHex(length?: number): string;
  * @param algorithm The hash algorithm (default: 'sha256').
  * @returns The hex-encoded HMAC.
  */
-export declare function hmacHash(str: string, secret: string, algorithm?: string): string;
+export declare function hmacHash(str: string, secret: string, algorithm?: 'sha1' | 'sha256' | 'sha384' | 'sha512'): Promise<string>;
 /**
- * Encodes a string to base64.
+ * Encodes a string (as UTF-8) to base64.
  * @param str The string to encode.
  * @returns The base64-encoded string.
  */
 export declare function base64Encode(str: string): string;
 /**
- * Decodes a base64 string.
- * @param b64 The base64 string to decode.
+ * Decodes a base64 string to a UTF-8 string.
+ * @param b64 The base64 string to decode (standard alphabet; padding optional).
  * @returns The decoded string.
+ * @throws {DOMException} When `b64` is not valid base64 (including the URL-safe `-`/`_` alphabet).
  */
 export declare function base64Decode(b64: string): string;
 //# sourceMappingURL=index.d.ts.map

package/dist/crypto/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/crypto/index.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,SAAW,GAAG,MAAM,CAEpE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,MAAM,SAAK,GAAG,MAAM,CAE7C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,SAAW,GAAG,MAAM,CAElF;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEhD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/crypto/index.ts"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,UAAU,CAC/B,GAAG,EAAE,MAAM,EACX,SAAS,GAAE,MAAM,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAmB,GAC3D,OAAO,CAAC,MAAM,CAAC,CAGjB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CAAC,MAAM,SAAK,GAAG,MAAM,CAE7C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,QAAQ,CAC7B,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EACd,SAAS,GAAE,MAAM,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAmB,GAC3D,OAAO,CAAC,MAAM,CAAC,CAUjB;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEhD"}

package/dist/crypto/index.js

@@ -1 +1 @@
-import"../chunks/chunk-ANN5UYCF.js";import{createHash as n,createHmac as i,randomBytes as s}from"node:crypto";function a(t,r="sha256"){return n(r).update(t).digest("hex")}function g(t=16){return s(t).toString("hex")}function u(t,r,e="sha256"){return i(e,r).update(t).digest("hex")}function f(t){return Buffer.from(t,"utf-8").toString("base64")}function c(t){return Buffer.from(t,"base64").toString("utf-8")}export{c as base64Decode,f as base64Encode,a as hashString,u as hmacHash,g as randomHex};
+import"../chunks/chunk-ANN5UYCF.js";function e(r){return Array.from(new Uint8Array(r),n=>n.toString(16).padStart(2,"0")).join("")}function a(r){return`SHA-${r.replace(/^sha-?/i,"")}`}async function i(r,n="sha256"){let t=await crypto.subtle.digest(a(n),new TextEncoder().encode(r));return e(t)}function c(r=16){return e(crypto.getRandomValues(new Uint8Array(r)))}async function g(r,n,t="sha256"){let o=new TextEncoder,s=await crypto.subtle.importKey("raw",o.encode(n),{name:"HMAC",hash:a(t)},!1,["sign"]);return e(await crypto.subtle.sign("HMAC",s,o.encode(r)))}function d(r){return btoa(Array.from(new TextEncoder().encode(r),n=>String.fromCharCode(n)).join(""))}function h(r){return new TextDecoder().decode(Uint8Array.from(atob(r),n=>n.charCodeAt(0)))}export{h as base64Decode,d as base64Encode,i as hashString,g as hmacHash,c as randomHex};

package/dist/currency/currencies.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"currencies.d.ts","sourceRoot":"","sources":["../../src/currency/currencies.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,QAAA,MAAM,UAAU,UA4Cf,CAAA;AAED,eAAe,UAAU,CAAA"}
+{"version":3,"file":"currencies.d.ts","sourceRoot":"","sources":["../../src/currency/currencies.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,QAAA,MAAM,UAAU,UA4Cf,CAAA;eAEc,UAAU"}

package/dist/currency/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/currency/index.ts"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,iBAAiB,GAAI,UAAU,MAAM,KAAG,MAAM,GAAG,SAY7D,CAAA;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,SAAO,GAAG,MAAM,GAAG,SAAS,CAMnF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAkC1D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,QAAQ,SAAQ,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAM7F;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CACjC,KAAK,EAAE,MAAM,GAAG,MAAM,EACtB,QAAQ,SAAQ,EAChB,MAAM,CAAC,EAAE,MAAM,GACb,MAAM,CAQR;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAevD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CA2C9F;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,SAAI,GAAG,MAAM,CAElF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAGxE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAOrD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/currency/index.ts"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,iBAAiB,aAAc,MAAM,KAAG,MAAM,GAAG,SAY7D,CAAA;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,SAAO,GAAG,MAAM,GAAG,SAAS,CAMnF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAkC1D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,QAAQ,SAAQ,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAM7F;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CACjC,KAAK,EAAE,MAAM,GAAG,MAAM,EACtB,QAAQ,SAAQ,EAChB,MAAM,CAAC,EAAE,MAAM,GACb,MAAM,CAQR;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAevD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CA2C9F;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,SAAI,GAAG,MAAM,CAElF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAGxE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAOrD"}

package/dist/date/index.d.ts

@@ -27,7 +27,8 @@ export declare function parseDate(dateStr: string): Date;
  */
 export declare function formatDate(date: Date): string;
 /**
- * Returns the difference in days between two dates (date2 - date1).
+ * Returns the difference in days between two dates (date2 - date1), measured in
+ * local wall-clock time so a DST change doesn't cost or gain a day.
  */
 export declare function daysBetween(date1: string | Date, date2: string | Date): number;
 /**
@@ -52,6 +53,15 @@ export declare function addDays(date: string | Date, days: number): Date;
 export declare function subDays(date: string | Date, days: number): Date;
 /**
  * Adds months to a date and returns a new Date object.
+ *
+ * When the source day does not exist in the target month, the result clamps to that
+ * month's last day (as Temporal and date-fns do) instead of rolling into the next month.
+ *
+ * @example
+ * ```typescript
+ * addMonths('2026-01-31', 1) // Date — Feb 28, not Mar 3
+ * addMonths('2024-01-31', 1) // Date — Feb 29 (leap year)
+ * ```
  */
 export declare function addMonths(date: string | Date, months: number): Date;
 /**
@@ -67,9 +77,19 @@ export declare function startOfDay(date: string | Date): Date;
  */
 export declare function endOfDay(date: string | Date): Date;
 /**
- * Returns true if the date falls on Saturday or Sunday.
+ * Returns true if the date falls on Saturday or Sunday (local time).
  */
 export declare function isWeekend(date: string | Date): boolean;
+/**
+ * Returns true if the date falls on Monday through Friday (local time).
+ *
+ * @example
+ * ```typescript
+ * isWeekday('2026-06-12') // true (Friday)
+ * isWeekday('2026-06-13') // false (Saturday)
+ * ```
+ */
+export declare function isWeekday(date: string | Date): boolean;
 /**
  * Returns true if the two dates fall on the same calendar day (local time).
  */

package/dist/date/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/date/index.ts"],"names":[],"mappings":"AASA;;;;;;;GAOG;AACH,wBAAgB,KAAK,IAAI,MAAM,CAE9B;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE/C;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAE7C;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAE9E;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAE9E;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAEhF;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAGvD;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAI/D;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAE/D;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAInE;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAExD;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAIpD;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAIlD;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAGtD;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAQ7E;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAEpD;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,GAAG,GAAE,IAAiB,GAAG,MAAM,CAQlF"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/date/index.ts"],"names":[],"mappings":"AASA;;;;;;;GAOG;AACH,wBAAgB,KAAK,IAAI,MAAM,CAE9B;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE/C;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAE7C;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAI9E;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAE9E;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAEhF;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAGvD;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAI/D;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAE/D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CASnE;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAExD;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAIpD;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAIlD;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAGtD;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAEtD;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAQ7E;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAEpD;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,GAAG,GAAE,IAAiB,GAAG,MAAM,CAQlF"}