@rtorcato/js-common 2.8.1 → 3.0.0

package/AGENTS.md

@@ -0,0 +1,116 @@
+<!-- Generated from skills/js-common/SKILL.md by scripts/sync-agents.mjs — do not edit by hand; run `pnpm sync:agents`. -->
+
+# 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.
+
+## 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.
+
+   ```ts
+   // ✅ do
+   import { slugify } from '@rtorcato/js-common/strings'
+   // ❌ don't — the root export is empty by design
+   import { slugify } from '@rtorcato/js-common'
+   ```
+
+2. **Every export name has exactly one home.** No name is exported from two modules, so the module → exports table below is the only lookup you need. These pairs still read alike — check which one you want:
+
+   | Looks like | Actually |
+   |---|---|
+   | `functions.once` vs `events.onceEvent` | `once(fn)` memoises a call; `onceEvent(target, type)` awaits a DOM 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.
+
+3. **Three different error idioms — don't mix them up.**
+
+   ```ts
+   // Result object — preferred for new code
+   import { tryCatch } from '@rtorcato/js-common/try'
+   const { data, error } = await tryCatch(() => fetchData())
+
+   // Go-style tuple: [error, data] — error FIRST
+   import { to } from '@rtorcato/js-common/promises'
+   const [err, value] = await to(fetchData())
+
+   // Swallows the error and returns a fallback — only when the fallback is genuinely safe
+   import { tryWithFallback } from '@rtorcato/js-common/errors'
+   const rows = await tryWithFallback(() => fetchRows(), [])
+   ```
+
+   `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.
+
+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.
+
+6. **Some helpers need a peer input you must supply.** `convertCurrency(amount, rate)` takes the rate — the library does no FX lookup. `checkEnv(schema)` needs a Zod object schema and throws with the list of missing keys.
+
+## Module → exports
+
+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 |
+| 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 |
+| datetime | nowIso, parseIsoDateTime, formatDateTimeLocal, getTimezoneOffset, toUtcDate, unixTimestamp, unixMillis, getIsoWeek, getIsoWeekInfo |
+| emails | isValidEmail, normalizeEmail, maskEmail, getEmailDomain, isFreeEmailProvider |
+| env | getENV, isDev, isProd, isTest, getNodeEnv, checkEnv, RootApiEnvSchema |
+| errors | createCustomError, isErrorName, getErrorMessage, assert, tryWithFallback |
+| events | on, emit, onceEvent, preventDefault, stopPropagation |
+| fetch | fetchWithTimeout, postJson, getJson, fetchText, handleApiError |
+| file | readFileAsString, writeFileAsString, fileExists, deleteFile, getFileExtension |
+| functions | once, debounce, throttle, compose, pipe |
+| 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 |
+| 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 |
+| 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 |
+| process | getProcessId, getProcessUptime, getCwd, getProcessPlatform, exitProcess, isCI |
+| promises | delay, to, withTimeout, all, allSettled, race |
+| random | randomInt, randomFloat, randomBool, randomElement, randomString |
+| regex | escapeRegExp, testRegex, matchAll, replaceAllRegex, splitByRegex |
+| security | stripScriptish, isStrongPassword, generateSecureToken |
+| sets | union, intersection, difference, isSubset, isSuperset, setToArray, arrayToSet |
+| sleep | sleep, sleepSync, sleepRandom, sleepWithAbort |
+| strings | titleCase, capitalize, camelCase, kebabCase, snakeCase, truncate, padStart, padEnd, replaceString, 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 |
+| 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 |
+
+## CLI
+
+The package also ships a binary for shell use:
+
+```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"
+```
+
+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/>.

package/CHANGELOG.md

@@ -1,3 +1,33 @@
+# Changelog — frozen at 2.8.2
+
+**This file stops at 2.8.2 and will not be updated again. It is not the place to
+look for what shipped.**
+
+[**GitHub Releases**](https://github.com/rtorcato/js-common/releases) is the
+canonical record, and the [changelog page on the docs
+site](https://rtorcato.github.io/js-common/docs/changelog) is built from it.
+
+Why: `@semantic-release/git` is dropped from this repo's plugin list because the
+`code-scanning-main` ruleset rejects the release commit with `GH013` — a commit
+created seconds earlier can never have CodeQL results (see
+[#153](https://github.com/rtorcato/js-common/issues/153) and
+[#211](https://github.com/rtorcato/js-common/issues/211)). Nothing commits this
+file back to `main`, so it holds whatever the last release with that plugin
+wrote. The same applies to the `version` field in `package.json`.
+
+Kept in the repo rather than deleted because GitHub Releases only go back to
+v1.2.0 — the hand-written `1.0.0` section at the bottom is the only record of
+that release, which is also why this file carries two formats.
+
+---
+
+## [2.8.2](https://github.com/rtorcato/js-common/compare/v2.8.1...v2.8.2) (2026-07-23)
+
+
+### Bug Fixes
+
+* **release:** upgrade npm for OIDC trusted publishing ([#110](https://github.com/rtorcato/js-common/issues/110)) ([93db8b5](https://github.com/rtorcato/js-common/commit/93db8b56041e916c63c1e250312e8527df931cc4))
+
 ## [2.8.1](https://github.com/rtorcato/js-common/compare/v2.8.0...v2.8.1) (2026-06-12)
 
 

package/CONTRIBUTORS.md

@@ -31,6 +31,11 @@ We welcome contributions from everyone! Here's how you can help:
 8. Push to your branch (`git push origin feature/amazing-feature`)
 9. Open a Pull Request
 
+Adding a helper? Check [MODULE-BOUNDARIES.md](MODULE-BOUNDARIES.md) first. It
+records which module owns what, and the rule that no name is exported from two
+modules — module paths are frozen, so a helper in the wrong place is expensive
+to move later.
+
 ### 📝 Documentation
 - Improve README.md, code comments, or JSDoc
 - Add examples for existing functions

package/README.md

@@ -1,8 +1,16 @@
 # js-common
 
-![js-common banner](./banner.png)
-
+<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>
+
+[![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)
+[![npm downloads](https://img.shields.io/npm/dm/@rtorcato/js-common.svg)](https://www.npmjs.com/package/@rtorcato/js-common)
+[![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/)
@@ -18,7 +26,7 @@ A comprehensive set of common JavaScript and TypeScript utilities for Node.js pr
 - **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, 46 subpaths
+- **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.
 
 ## Installation
@@ -27,11 +35,41 @@ A comprehensive set of common JavaScript and TypeScript utilities for Node.js pr
 npm install @rtorcato/js-common
 ```
 
-## Migrating from 1.x to 2.x
+Pre-release builds are published to the `beta` dist-tag, so they never reach a plain `npm install`:
+
+```bash
+npm install @rtorcato/js-common@beta
+```
+
+## Use with AI
+
+An agent skill lives in [`skills/js-common`](./skills/js-common/SKILL.md) — it teaches an AI coding agent the subpath-import rules, which same-named helper belongs to which module, the three error idioms, which modules are Node-only, and the full module → exports map.
+
+**Claude Code** — this repo is its own plugin marketplace:
+
+```
+/plugin marketplace add rtorcato/js-common
+/plugin install js-common@js-common
+```
+
+**Cursor, Copilot, Codex and other tools** — read [`AGENTS.md`](./AGENTS.md), the cross-tool convention file. It carries the same guidance and also ships in the npm tarball, so tools that scan `node_modules` find it at `node_modules/@rtorcato/js-common/AGENTS.md`.
 
-The only breaking change in 2.0 is a rename in the `errors` module:
+**Any tool the [`skills`](https://www.npmjs.com/package/skills) CLI supports:**
+
+```bash
+npx skills add https://github.com/rtorcato/js-common --skill js-common
+```
+
+`AGENTS.md` is generated from `SKILL.md` by `pnpm sync:agents`; CI fails if they drift. Edit `SKILL.md`, never `AGENTS.md`.
+
+## 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).
+
+**1.x → 2.x** — the only breaking change in 2.0 is a rename in the `errors` module:
 
 ```ts
+// boundary-check: ignore — quotes the pre-2.0 API on purpose
 // 1.x — swallow errors and fall back to a default value
 import { tryCatch } from '@rtorcato/js-common/errors'
 const data = await tryCatch(() => fetchData(), [])
@@ -76,16 +114,16 @@ See [CLI.md](./CLI.md) for complete CLI documentation.
 ```typescript
 // Import specific modules (recommended for tree-shaking)
 import { formatDate, today, daysBetween } from '@rtorcato/js-common/date'
-import { validateEmail, isValidEmail } from '@rtorcato/js-common/emails'
-import { generateUUID, isValidUUID } from '@rtorcato/js-common/uuid'
+import { isValidEmail, normalizeEmail } from '@rtorcato/js-common/emails'
+import { getUUID, isUUID } from '@rtorcato/js-common/uuid'
 import { sum, average, roundTo } from '@rtorcato/js-common/numbers'
-import { capitalize, toTitleCase } from '@rtorcato/js-common/formatting'
+import { capitalize, titleCase } from '@rtorcato/js-common/strings'
 
 // Example usage
 console.log(today()) // "2026-05-29"
 console.log(sum([1, 2, 3, 4, 5])) // 15
 console.log(capitalize('hello world')) // "Hello world"
-console.log(generateUUID()) // "f47ac10b-58cc-4372-a567-0e02b2c3d479"
+console.log(getUUID()) // "f47ac10b-58cc-4372-a567-0e02b2c3d479"
 ```
 
 ### Bundle Size Impact
@@ -94,6 +132,10 @@ Each module is shipped as its own subpath export so bundlers only include what y
 
 ## Available Modules
 
+Which module a helper belongs to — and why no helper is exported from two of
+them — is recorded in [MODULE-BOUNDARIES.md](MODULE-BOUNDARIES.md). These paths
+are frozen as of that record.
+
 ### Date & Time
 ```typescript
 import { today, formatDate, daysBetween, isLeapYear } from '@rtorcato/js-common/date'
@@ -102,29 +144,27 @@ import { nowTime, parseTime, secondsBetween } from '@rtorcato/js-common/time'
 import { runInterval, clearIntervalById } from '@rtorcato/js-common/interval'
 ```
 
-### Numbers & Math
+### Numbers
 ```typescript
-import { sum, average, roundTo, clamp, getRandomInt } from '@rtorcato/js-common/numbers'
-import { add, subtract, multiply, divide } from '@rtorcato/js-common/math'
+import { sum, average, roundTo, clamp, formatPercent } from '@rtorcato/js-common/numbers'
 import { randomInt, randomFloat, randomBool, randomElement } from '@rtorcato/js-common/random'
 ```
 
 ### Text & Strings
 ```typescript
-import { capitalize, toTitleCase, padZero } from '@rtorcato/js-common/formatting'
-import { slugify, truncate, removeEmojis } from '@rtorcato/js-common/strings'
+import { slugify, truncate, capitalize, titleCase, pluralize } from '@rtorcato/js-common/strings'
 import { escapeHtml, unescapeHtml, stripHtmlTags } from '@rtorcato/js-common/html'
 import { escapeRegExp, matchAll, replaceAllRegex } from '@rtorcato/js-common/regex'
-import { detectLanguage, formatNumber, t, pluralize } from '@rtorcato/js-common/i18n'
+import { detectLanguage, formatNumber, formatDateI18n, t } from '@rtorcato/js-common/i18n'
 ```
 
 ### Security & Validation
 ```typescript
 import { isStrongPassword, generateSecureToken } from '@rtorcato/js-common/security'
-import { isValidEmail, validateEmail } from '@rtorcato/js-common/emails'
+import { isValidEmail, maskEmail } from '@rtorcato/js-common/emails'
 import { isValidUrl } from '@rtorcato/js-common/url'
-import { isString, isNumber, isArray, isObject } from '@rtorcato/js-common/validation'
-import { toBoolean, isBoolean, xor } from '@rtorcato/js-common/boolean'
+import { isString, isNumber, isBoolean, isArray, isObject } from '@rtorcato/js-common/validation'
+import { toBoolean, and, or, not, xor } from '@rtorcato/js-common/boolean'
 ```
 
 ### Data Structures
@@ -138,7 +178,7 @@ import { union, intersection, difference, isSubset } from '@rtorcato/js-common/s
 
 ### Async & Control Flow
 ```typescript
-import { delay, timeout, retry } from '@rtorcato/js-common/promises'
+import { delay, withTimeout, allSettled } 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'
@@ -166,7 +206,7 @@ import { info, warn, error, captureConsole } from '@rtorcato/js-common/logging'
 - `colors` — color manipulation and conversion
 - `crypto` — cryptographic helpers
 - `currency` — currency formatting and conversion
-- `events` — event emitter utilities
+- `events` — DOM event helpers (`on`, `emit`, `onceEvent`)
 - `fetch` — HTTP request helpers
 - `file` — file system helpers
 - `geometry` — 2D geometry calculations
@@ -209,10 +249,10 @@ pnpm run benchmark
 
 ## Documentation site
 
-The full documentation site lives in [`apps/doc`](./apps/doc) and is built with [Astro Starlight](https://starlight.astro.build/). It auto-deploys to GitHub Pages on every push to `main` that touches `apps/doc/**`.
+The full documentation site lives in [`apps/docs`](./apps/docs) and is built with [Docusaurus](https://docusaurus.io/). It auto-deploys to GitHub Pages on every push to `main` that touches `apps/docs/**`.
 
 ```bash
-# Run the docs locally (http://localhost:4321/js-common)
+# Run the docs locally (http://localhost:3000/js-common/)
 pnpm --filter @rtorcato/js-common-docs dev
 
 # Build the static site
@@ -221,6 +261,10 @@ pnpm --filter @rtorcato/js-common-docs build
 
 Live site: <https://rtorcato.github.io/js-common/>
 
+## Roadmap
+
+Direction and progress are tracked entirely on GitHub — see the [milestones](https://github.com/rtorcato/js-common/milestones) for the stages (shipped 2.x modules, the beta npm preview, the v1.0 stable API) and the [open issues](https://github.com/rtorcato/js-common/issues) for day-to-day work.
+
 ## Contributing
 
 Contributions are welcome! Please read [CONTRIBUTORS.md](./CONTRIBUTORS.md) for guidelines.
@@ -231,6 +275,11 @@ Contributions are welcome! Please read [CONTRIBUTORS.md](./CONTRIBUTORS.md) for
 4. Run the test suite: `pnpm test`
 5. Submit a pull request
 
+## Related packages
+
+- [@rtorcato/browser-common](https://github.com/rtorcato/browser-common) — Browser Web API wrappers (clipboard, observers, storage, etc.)
+- [@rtorcato/repo-tooling](https://github.com/rtorcato/repo-tooling) — Project scaffolding for TypeScript libraries (Biome, Vitest, Husky, semantic-release)
+
 ## License
 
 MIT © [Richard Torcato](https://github.com/rtorcato)

package/dist/abortController/index.d.ts

@@ -1,5 +1,14 @@
 /**
  * Creates a new AbortController and returns its controller and signal.
+ *
+ * @example
+ * ```typescript
+ * const { controller, signal } = createAbortController()
+ * signal.aborted // false
+ * controller.abort()
+ * signal.aborted // true
+ * ```
+ *
  * @returns {{ controller: AbortController, signal: AbortSignal }}
  */
 export declare function createAbortController(): {
@@ -8,12 +17,33 @@ export declare function createAbortController(): {
 };
 /**
  * Returns a promise that rejects when the given AbortSignal is aborted.
+ *
+ * @example
+ * ```typescript
+ * const { controller, signal } = createAbortController()
+ * const pending = abortPromise(signal)
+ * controller.abort()
+ * await pending.catch((err) => err.name) // 'AbortError'
+ * ```
+ *
  * @param signal The AbortSignal to listen to.
  * @returns {Promise<never>}
  */
 export declare function abortPromise(signal: AbortSignal): Promise<never>;
 /**
  * Wraps a promise and rejects it if the signal is aborted.
+ *
+ * @example
+ * ```typescript
+ * const { controller, signal } = createAbortController()
+ * const slow = new Promise<string>((resolve) => setTimeout(() => resolve('done'), 50))
+ *
+ * await withAbort(slow, signal) // 'done'
+ *
+ * controller.abort()
+ * await withAbort(slow, signal).catch((err) => err.name) // 'AbortError'
+ * ```
+ *
  * @param promise The promise to wrap.
  * @param signal The AbortSignal.
  * @returns {Promise<T>}

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/abortController/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,qBAAqB;;;EAGpC;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,KAAK,CAAC,CAchE;AAED;;;;;GAKG;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,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"}

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=arrays.test-d.d.ts.map

package/dist/arrays/arrays.test-d.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"arrays.test-d.d.ts","sourceRoot":"","sources":["../../src/arrays/arrays.test-d.ts"],"names":[],"mappings":""}

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

@@ -0,0 +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()})});

package/dist/arrays/index.js

@@ -1 +1 @@
-import"../chunks/chunk-ANN5UYCF.js";function u(n){return n[0]}function T(n){return n.length?n[n.length-1]:void 0}function f(n){return Array.from(new Set(n))}function i(n){return n.flat()}function l(n,e){if(e<1)throw new Error("Chunk size must be at least 1");let t=[];for(let r=0;r<n.length;r+=e)t.push(n.slice(r,r+e));return t}function s(n){return n.filter(Boolean)}function c(n){let e=n.slice();for(let t=e.length-1;t>0;t--){let r=Math.floor(Math.random()*(t+1));[e[t],e[r]]=[e[r],e[t]]}return e}function h(n,e){return n.reduce((t,r)=>{let o=e(r);return t[o]||(t[o]=[]),t[o].push(r),t},{})}export{l as chunk,s as compact,u as first,i as flatten,h as groupBy,T as last,c as shuffle,f as unique};
+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};

package/dist/boolean/index.d.ts

@@ -1,18 +1,30 @@
 /**
  * Converts a value to a boolean.
  * Accepts 'true', '1', 1 as true; 'false', '0', 0 as false.
+ *
+ * @example
+ * ```typescript
+ * toBoolean('true') // true
+ * toBoolean('0') // false
+ * toBoolean(1) // true
+ * toBoolean(2) // false
+ * toBoolean(null) // false
+ * ```
+ *
  * @param value The value to convert.
  * @returns The boolean representation.
  */
 export declare function toBoolean(value: unknown): boolean;
-/**
- * Checks if a value is a boolean.
- * @param value The value to check.
- * @returns True if the value is a boolean, false otherwise.
- */
-export declare function isBoolean(value: unknown): value is 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.

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/boolean/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAWjD;AAED;;;;GAIG;AAEH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,OAAO,CAE1D;AAED;;;;;GAKG;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;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"}

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){return typeof o=="boolean"}function t(o,n){return!!(o?!n:n)}function a(o,n){return o&&n}function f(o,n){return o||n}function u(o){return!o}export{a as and,r as isBoolean,u as not,f as or,e as toBoolean,t as xor};
+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};

package/dist/chunks/chunk-5IA77ERW.js

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

package/dist/chunks/chunk-7JQSIREC.js

@@ -0,0 +1 @@
+function i(e){return new Promise(r=>setTimeout(r,e))}async function u(e){try{return[null,await e]}catch(r){return[r,void 0]}}function s(e,r,t=new Error("Timeout")){return Promise.race([e,new Promise((n,o)=>setTimeout(()=>o(t),r))])}function m(e){return Promise.all(e)}function T(e){return Promise.allSettled(e)}function P(e){return Promise.race(e)}export{i as a,u as b,s as c,m as d,T as e,P as f};

package/dist/chunks/chunk-ARW46OJS.js

@@ -0,0 +1 @@
+function r(n){return Object.prototype.toString.call(n)==="[object Object]"}function s(n,o){let t={...n};for(let e in o)r(o[e])&&r(t[e])?t[e]=s(t[e],o[e]):t[e]=o[e];return t}function c(n,o){let t={...n};for(let e of o)delete t[e];return t}function i(n,o){let t={};for(let e of o)e in n&&(t[e]=n[e]);return t}function T(n){return structuredClone(n)}export{r as a,s as b,c,i as d,T as e};

package/dist/chunks/chunk-MFJ5XPUX.js

@@ -0,0 +1 @@
+import{b as e}from"./chunk-FBDKWWIQ.js";import{createRequire as t}from"node:module";import r from"pino";function o(){try{return t(import.meta.url).resolve("pino-pretty"),!0}catch{return!1}}var s=e()&&o()?r({level:"debug",transport:{target:"pino-pretty",options:{colorize:!0,ignore:"pid,hostname,time",levelFirst:!1,singleLine:!0,customColors:"err:red,info:blue",translateTime:"HH:MM:ss"}}}):r({level:"info"});export{s as a};

package/dist/chunks/chunk-RBXTRLWB.js

@@ -0,0 +1 @@
+function o(n){let t=!1,e;return function(...r){return t||(t=!0,e=n.apply(this,r)),e}}function i(n,t){let e;return function(...r){clearTimeout(e),e=setTimeout(()=>n.apply(this,r),t)}}function u(n,t){let e=0;return function(...r){let a=Date.now();a-e>=t&&(e=a,n.apply(this,r))}}function T(...n){return t=>n.reduceRight((e,r)=>r(e),t)}function s(...n){return t=>n.reduce((e,r)=>r(e),t)}export{o as a,i as b,u as c,T as d,s as e};

package/dist/cli/catalog.js

@@ -0,0 +1,131 @@
+// Catalog of the functions the CLI advertises, used by `list`, `interactive`
+// and `add`.
+//
+// Three names per entry, and they are deliberately different things:
+//   - `name`       the CLI verb (`js-common math avg`) — part of the CLI surface
+//   - `exportName` the real library export (`average`) — what `add` must print
+//   - `subpath`    the published module the export lives in (`numbers`)
+//
+// `subpath` is per entry, not per category: the CLI groups by task ('math',
+// 'system') while the library groups by module — 'math' spans `numbers` and
+// `random`, 'system' spans `process` and `node`.
+//
+// `src/cli/catalog.test.ts` asserts both halves, so this cannot drift back into
+// fiction: every `exportName` really is exported by `src/<subpath>/index.ts`,
+// and every `name` really is a command registered in `src/cli/cli.ts`. The
+// second check exists because it wasn't there — `file`, `security`, `validate`,
+// `text pad` and `system ci` were advertised here for long enough that `list`
+// printed commands that errored when run.
+export const functionCategories = {
+    date: {
+        name: '📅 Date & Time',
+        functions: [
+            {
+                name: 'today',
+                description: "Get today's date (YYYY-MM-DD)",
+                exportName: 'today',
+                subpath: 'date',
+                example: `const date = today() // '${new Date().toISOString().slice(0, 10)}'`,
+            },
+            {
+                name: 'now',
+                description: 'Get current timestamp',
+                exportName: 'nowIso',
+                subpath: 'datetime',
+                example: `const timestamp = nowIso() // '${new Date().toISOString()}'`,
+            },
+            {
+                name: 'between',
+                description: 'Calculate days between dates',
+                exportName: 'daysBetween',
+                subpath: 'date',
+                example: `const days = daysBetween('2023-01-01', '2023-12-31') // 364`,
+            },
+        ],
+    },
+    math: {
+        name: '🔢 Mathematical',
+        functions: [
+            {
+                name: 'sum',
+                description: 'Calculate sum of numbers',
+                exportName: 'sum',
+                subpath: 'numbers',
+                example: `const total = sum([1, 2, 3, 4, 5]) // 15`,
+            },
+            {
+                name: 'avg',
+                description: 'Calculate average of numbers',
+                exportName: 'average',
+                subpath: 'numbers',
+                example: `const mean = average([10, 20, 30]) // 20`,
+            },
+            {
+                name: 'random',
+                description: 'Generate random number',
+                exportName: 'randomInt',
+                subpath: 'random',
+                example: `const num = randomInt(1, 100) // 42`,
+            },
+            {
+                name: 'round',
+                description: 'Round to decimal places',
+                exportName: 'roundTo',
+                subpath: 'numbers',
+                example: `const rounded = roundTo(3.14159, 2) // 3.14`,
+            },
+            {
+                name: 'clamp',
+                description: 'Clamp between min/max',
+                exportName: 'clamp',
+                subpath: 'numbers',
+                example: `const clamped = clamp(150, 0, 100) // 100`,
+            },
+        ],
+    },
+    text: {
+        name: '📝 Text Formatting',
+        functions: [
+            {
+                name: 'capitalize',
+                description: 'Capitalize first letter',
+                exportName: 'capitalize',
+                subpath: 'strings',
+                example: `const text = capitalize('hello world') // 'Hello world'`,
+            },
+            {
+                name: 'title',
+                description: 'Convert to title case',
+                exportName: 'titleCase',
+                subpath: 'strings',
+                example: `const heading = titleCase('hello world') // 'Hello World'`,
+            },
+        ],
+    },
+    system: {
+        name: '💻 System Info',
+        functions: [
+            {
+                name: 'pid',
+                description: 'Get process ID',
+                exportName: 'getProcessId',
+                subpath: 'process',
+                example: `const processId = getProcessId() // 12345`,
+            },
+            {
+                name: 'uptime',
+                description: 'Get process uptime',
+                exportName: 'getProcessUptime',
+                subpath: 'process',
+                example: `const uptime = getProcessUptime() // 123.45`,
+            },
+            {
+                name: 'node-version',
+                description: 'Get Node.js version',
+                exportName: 'getNodeMajorVersion',
+                subpath: 'node',
+                example: `const major = getNodeMajorVersion() // 22`,
+            },
+        ],
+    },
+};