@rtorcato/js-common 5.0.0 → 6.0.0

package/AGENTS.md

@@ -2,7 +2,7 @@
 
 # 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 — 42 of them. There is no package root export.
+`@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
 
@@ -101,12 +101,13 @@ Import from `@rtorcato/js-common/<module>`.
 
 ## 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.

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,8 +13,7 @@
 [![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)
+[![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.
@@ -29,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
-- **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.
+- **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
 
@@ -42,7 +41,7 @@ Three modules need an optional peer you install yourself:
 | Module | Peer |
 |---|---|
 | `./env` | `npm install zod` |
-| `./logger` | `npm install pino` |
+| `./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`:
@@ -74,6 +73,8 @@ npx skills add https://github.com/rtorcato/js-common --skill js-common
 
 ## Migrating
 
+**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).
 
 **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).
@@ -105,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.
@@ -230,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

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/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/env/index.d.ts

@@ -77,9 +77,9 @@ export declare const RootApiEnvSchema: z.ZodObject<{
     }>>;
     LOG_LEVEL: z.ZodDefault<z.ZodEnum<{
         debug: "debug";
+        error: "error";
         info: "info";
         warn: "warn";
-        error: "error";
     }>>;
     PORT: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
 }, z.core.$strip>;

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/env/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,MAAM,GAAI,KAAK,MAAM,EAAE,eAAe,MAAM,WAUxD,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,KAAK,QAAO,OAExB,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,MAAM,QAAO,OAEzB,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,MAAM,QAAO,OAEzB,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,UAAU,QAAO,MAE7B,CAAA;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,CAAC,CAAC,WAAW,EAC/C,SAAS,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EACzB,QAAQ,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,oCAc1D;AAED;;;GAGG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;iBAI3B,CAAA;AAEF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/env/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,MAAM,QAAS,MAAM,iBAAiB,MAAM,WAUxD,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,KAAK,QAAO,OAExB,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,MAAM,QAAO,OAEzB,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,MAAM,QAAO,OAEzB,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,UAAU,QAAO,MAE7B,CAAA;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,CAAC,CAAC,WAAW,EAC/C,SAAS,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EACzB,QAAQ,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,oCAc1D;AAED;;;GAGG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;iBAI3B,CAAA;AAEF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAA"}

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/logger/index.ts"],"names":[],"mappings":"AACA,OAAO,IAAI,MAAM,MAAM,CAAA;AAevB;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,MAAM,6BA4BQ,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/logger/index.ts"],"names":[],"mappings":"AACA,OAAO,IAAI,MAAM,MAAM,CAAA;AAcvB;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,MAAM,6BA4BQ,CAAA"}