@rtorcato/js-common 3.0.0 → 5.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 >= 22 (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 | first, last, unique, flatten, chunk, compact, shuffle, groupBy |
-| boolean | toBoolean, xor, and, or, not |
+| 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 |
@@ -75,31 +75,29 @@ Import from `@rtorcato/js-common/<module>`.
 | geometry | distance2D, midpoint2D, angle2D, pointInRect, rectsOverlap, polygonArea |
 | html | escapeHtml, unescapeHtml, stripHtmlTags, textToHtml, containsHtml |
 | i18n | detectLanguage, formatNumber, formatDateI18n, t |
-| interval | runInterval, clearIntervalById |
-| json | safeJsonParse, safeJsonStringify, isValidJson, deepCloneJson |
+| json | safeJsonParse, safeJsonStringify, isValidJson |
 | 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, isFiniteNumber, isInteger, between, sum, average, mod, min, max |
-| objects | isPlainObject, deepMerge, omit, pick, deepClone |
-| os | getOsPlatform, getOsRelease, getOsArch, getHomeDir, getTmpDir |
+| numbers | clamp, roundTo, formatPercent, FormatPercentOptions, between, sum, average, mod, variance, stdDev, median, percentile |
+| objects | isPlainObject, deepMerge, omit, pick |
+| os | getOsRelease, getOsArch, getHomeDir, getTmpDir |
 | process | getProcessId, getProcessUptime, getCwd, getProcessPlatform, exitProcess, isCI |
-| promises | delay, to, withTimeout, all, allSettled, race |
+| promises | to, withTimeout, mapLimit, retry, RetryOptions |
 | random | randomInt, randomFloat, randomBool, randomElement, randomString |
 | regex | escapeRegExp, testRegex, matchAll, replaceAllRegex, splitByRegex |
-| security | stripScriptish, isStrongPassword, generateSecureToken |
-| sets | union, intersection, difference, isSubset, isSuperset, setToArray, arrayToSet |
+| security | stripScriptish, isStrongPassword |
 | sleep | sleep, sleepSync, sleepRandom, sleepWithAbort |
-| strings | titleCase, capitalize, camelCase, kebabCase, snakeCase, truncate, padStart, padEnd, replaceString, reverse, slugify, words, wordCount, pluralize, ordinalize, isBlank, mask, template |
+| 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 | getUUID, getUUIDv7, getShortUUID, toShortUUID, fromShortUUID, isUUID, isUUIDv4, isNilUUID, getUUIDVersion, getNilUUID, uuidToBytes, bytesToUUID |
-| validation | isDefined, isString, isNumber, isBoolean, isArray, isObject, isEmail, isUrl |
+| uuid | getUUIDv7, getShortUUID, toShortUUID, fromShortUUID, isUUID, isUUIDv4, isNilUUID, getUUIDVersion, getNilUUID, uuidToBytes, bytesToUUID |
+| validation | isDefined, isString, isNumber, isBoolean, isArray, isObject |
 
 ## CLI
 
@@ -113,4 +111,4 @@ npx @rtorcato/js-common@latest 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

@@ -15,19 +15,21 @@
 [![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/)
+[![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
 
 - **Tree-shakeable** — import only what you need via subpath exports
 - **TypeScript** — full type definitions, JSDoc on every public API
 - **CLI included** — optional binary for use in scripts and terminals
-- **Modular** — one module per concern, 44 subpaths
-- **Minimal runtime deps** — only `date-fns`, `date-fns-tz`, `luxon`, `pino`, `uuid`, `short-uuid`, `zod`. CLI packages (`chalk`, `commander`, `figlet`, …) are `optionalDependencies` and only needed for the CLI.
+- **Modular** — one module per concern, 42 subpaths
+- **No required runtime deps** — `zod` (`./env`), `pino` (`./logger`) and `uuid` + `short-uuid` (`./uuid`) are optional peers: install one only if you import its module. CLI packages (`chalk`, `commander`, `figlet`, …) are `optionalDependencies` and only needed for the CLI.
 
 ## Installation
 
@@ -35,6 +37,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` |
+| `./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,7 +74,11 @@ npx skills add https://github.com/rtorcato/js-common --skill js-common
 
 ## Migrating
 
-**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).
+**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).
+
+**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:
 
@@ -115,7 +129,7 @@ See [CLI.md](./CLI.md) for complete CLI documentation.
 // Import specific modules (recommended for tree-shaking)
 import { formatDate, today, daysBetween } from '@rtorcato/js-common/date'
 import { isValidEmail, normalizeEmail } from '@rtorcato/js-common/emails'
-import { getUUID, isUUID } from '@rtorcato/js-common/uuid'
+import { getUUIDv7, isUUID } from '@rtorcato/js-common/uuid'
 import { sum, average, roundTo } from '@rtorcato/js-common/numbers'
 import { capitalize, titleCase } from '@rtorcato/js-common/strings'
 
@@ -123,7 +137,7 @@ import { capitalize, titleCase } from '@rtorcato/js-common/strings'
 console.log(today()) // "2026-05-29"
 console.log(sum([1, 2, 3, 4, 5])) // 15
 console.log(capitalize('hello world')) // "Hello world"
-console.log(getUUID()) // "f47ac10b-58cc-4372-a567-0e02b2c3d479"
+console.log(getUUIDv7()) // "018e5e2c-7c0a-7000-8000-0e02b2c3d479"
 ```
 
 ### Bundle Size Impact
@@ -141,12 +155,12 @@ are frozen as of that record.
 import { today, formatDate, daysBetween, isLeapYear } from '@rtorcato/js-common/date'
 import { nowIso, formatDateTimeLocal, unixTimestamp } from '@rtorcato/js-common/datetime'
 import { nowTime, parseTime, secondsBetween } from '@rtorcato/js-common/time'
-import { runInterval, clearIntervalById } from '@rtorcato/js-common/interval'
 ```
 
 ### 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'
 ```
 
@@ -160,25 +174,25 @@ 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'
-import { toBoolean, and, or, not, xor } from '@rtorcato/js-common/boolean'
+import { toBoolean } from '@rtorcato/js-common/boolean'
 ```
 
 ### Data Structures
 ```typescript
-import { flatten, unique, chunk, groupBy } from '@rtorcato/js-common/arrays'
-import { deepMerge, pick, omit, deepClone } from '@rtorcato/js-common/objects'
+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'
-import { union, intersection, difference, isSubset } from '@rtorcato/js-common/sets'
 ```
 
 ### Async & Control Flow
 ```typescript
-import { delay, withTimeout, allSettled } 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 +203,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'
 ```
@@ -242,9 +256,6 @@ pnpm run check:fix
 
 # Type checking
 pnpm run typecheck
-
-# Run micro-benchmarks (scripts/benchmark.mjs)
-pnpm run benchmark
 ```
 
 ## Documentation site
@@ -259,7 +270,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 n,b as a,c as t,e as u,h as s}from"../chunks/chunk-5IA77ERW.js";import"../chunks/chunk-ANN5UYCF.js";import{describe as o,expectTypeOf as e,it as r}from"vitest";o("arrays \u2014 types",()=>{r("first/last preserve element type and add undefined",()=>{e(n([1,2,3])).toEqualTypeOf(),e(n(["a","b"])).toEqualTypeOf(),e(a([{id:1}])).toEqualTypeOf()}),r("unique preserves element type",()=>{e(t([1,2,3])).toEqualTypeOf(),e(t(["a"])).toEqualTypeOf()}),r("chunk returns array of arrays of the element type",()=>{e(u([1,2,3],2)).toEqualTypeOf(),e(u(["a","b"],1)).toEqualTypeOf()}),r("groupBy preserves element type in the grouped arrays",()=>{let i=s([{kind:"a",n:1}],p=>p.kind);e(i).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

@@ -1,33 +1,3 @@
-/**
- * Returns the first element of an array, or undefined if the array is empty.
- *
- * @example
- * ```typescript
- * first([1, 2, 3]) // 1
- * first([]) // undefined
- * first(['a', 'b']) // 'a'
- * ```
- *
- * @param arr The array to get the first element from
- * @returns The first element or undefined if array is empty
- * @category Array Utilities
- */
-export declare function first<T>(arr: T[]): T | undefined;
-/**
- * Returns the last element of an array, or undefined if the array is empty.
- *
- * @example
- * ```typescript
- * last([1, 2, 3]) // 3
- * last([]) // undefined
- * last(['a', 'b']) // 'b'
- * ```
- *
- * @param arr The array to get the last element from
- * @returns The last element or undefined if array is empty
- * @category Array Utilities
- */
-export declare function last<T>(arr: T[]): T | undefined;
 /**
  * Removes duplicate values from an array while preserving order.
  * Uses Set for O(n) performance with primitive values.
@@ -44,21 +14,6 @@ export declare function last<T>(arr: T[]): T | undefined;
  * @category Array Utilities
  */
 export declare function unique<T>(arr: T[]): T[];
-/**
- * Flattens an array one level deep.
- *
- * @example
- * ```typescript
- * flatten([[1, 2], [3, 4]]) // [1, 2, 3, 4]
- * flatten([1, [2, 3], 4]) // [1, 2, 3, 4]
- * flatten([[1, [2]], [3]]) // [1, [2], 3] (only one level deep)
- * ```
- *
- * @param arr The array to flatten
- * @returns A new flattened array
- * @category Array Utilities
- */
-export declare function flatten<T>(arr: readonly (T | T[])[]): T[];
 /**
  * Chunks an array into smaller arrays of a specified size.
  * The last chunk may be smaller if the array length is not evenly divisible.
@@ -114,21 +69,55 @@ export declare function compact<T>(arr: T[]): T[];
  */
 export declare function shuffle<T>(arr: T[]): T[];
 /**
- * Groups array elements by a key derived from each element.
+ * 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
- * groupBy([1, 2, 3, 4], n => n % 2 === 0 ? 'even' : 'odd')
- * // { odd: [1, 3], even: [2, 4] }
+ * partition([1, 2, 3, 4], (n) => n % 2 === 0) // [[2, 4], [1, 3]]
+ * partition(['a', 'bb'], (s) => s.length > 1) // [['bb'], ['a']]
+ * ```
  *
- * groupBy([{ type: 'a' }, { type: 'b' }, { type: 'a' }], x => x.type)
- * // { a: [{ type: 'a' }, { type: 'a' }], b: [{ type: 'b' }] }
+ * @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 arr The array to group
- * @param fn Function that returns the group key for each element
- * @returns An object mapping keys to arrays of elements
+ * @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 groupBy<T>(arr: T[], fn: (item: T) => string | number): Record<string | number, T[]>;
+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;;;;;;;;;;;;;GAaG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,CAAC,GAAG,SAAS,CAEhD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,CAAC,GAAG,SAAS,CAE/C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,CAEvC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,SAAS,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,CAEzD;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;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,OAAO,CAAC,CAAC,EACxB,GAAG,EAAE,CAAC,EAAE,EACR,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,GAAG,MAAM,GAC9B,MAAM,CAAC,MAAM,GAAG,MAAM,EAAE,CAAC,EAAE,CAAC,CAO9B"}
+{"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,e,f,g,h}from"../chunks/chunk-5IA77ERW.js";import"../chunks/chunk-ANN5UYCF.js";export{e as chunk,f as compact,a as first,d as flatten,h as groupBy,b as last,g as shuffle,c 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/boolean/index.d.ts

@@ -15,39 +15,4 @@
  * @returns The boolean representation.
  */
 export declare function toBoolean(value: unknown): boolean;
-/**
- * Returns the logical exclusive OR (XOR) of two booleans.
- *
- * @example
- * ```typescript
- * xor(true, false) // true
- * xor(true, true) // false
- * xor(false, false) // false
- * ```
- *
- * @param a First boolean.
- * @param b Second boolean.
- * @returns True if exactly one of a or b is true.
- */
-export declare function xor(a: boolean, b: boolean): boolean;
-/**
- * Logical AND for two booleans.
- * @param a First boolean.
- * @param b Second boolean.
- * @returns True if both a and b are true.
- */
-export declare function and(a: boolean, b: boolean): boolean;
-/**
- * Logical OR for two booleans.
- * @param a First boolean.
- * @param b Second boolean.
- * @returns True if either a or b is true.
- */
-export declare function or(a: boolean, b: boolean): boolean;
-/**
- * Logical NOT for a boolean.
- * @param a The boolean to negate.
- * @returns The negated boolean.
- */
-export declare function not(a: boolean): boolean;
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/boolean/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAWjD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,GAAG,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CAEnD;AAED;;;;;GAKG;AACH,wBAAgB,GAAG,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CAEnD;AAED;;;;;GAKG;AACH,wBAAgB,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CAElD;AAED;;;;GAIG;AACH,wBAAgB,GAAG,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAEvC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/boolean/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAWjD"}

package/dist/boolean/index.js

@@ -1 +1 @@
-import"../chunks/chunk-ANN5UYCF.js";function e(o){if(typeof o=="boolean")return o;if(typeof o=="string"){let n=o.trim().toLowerCase();if(n==="true"||n==="1")return!0;if(n==="false"||n==="0")return!1}return typeof o=="number"?o===1:!!o}function r(o,n){return!!(o?!n:n)}function t(o,n){return o&&n}function f(o,n){return o||n}function a(o){return!o}export{t as and,a as not,f as or,e as toBoolean,r as xor};
+import"../chunks/chunk-ANN5UYCF.js";function r(o){if(typeof o=="boolean")return o;if(typeof o=="string"){let n=o.trim().toLowerCase();if(n==="true"||n==="1")return!0;if(n==="false"||n==="0")return!1}return typeof o=="number"?o===1:!!o}export{r as toBoolean};

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};