@rtorcato/js-common 1.8.0 → 2.0.0

package/CHANGELOG.md

@@ -1,3 +1,28 @@
+# [2.0.0](https://github.com/rtorcato/js-common/compare/v1.8.1...v2.0.0) (2026-06-01)
+
+
+* refactor!: maintenance sweep + rename errors.tryCatch ([#47](https://github.com/rtorcato/js-common/issues/47)) ([9bd28a6](https://github.com/rtorcato/js-common/commit/9bd28a68b7566806169812ffed5ccb649d30e6c3))
+
+
+### Bug Fixes
+
+* **ci:** env-var commit message in check-skip ([#48](https://github.com/rtorcato/js-common/issues/48)) ([1037b0c](https://github.com/rtorcato/js-common/commit/1037b0c31c377bbc80eda57cbe3e411579437685)), closes [#47](https://github.com/rtorcato/js-common/issues/47)
+
+
+### BREAKING CHANGES
+
+* `tryCatch` from `@rtorcato/js-common/errors` is
+renamed to `tryWithFallback`. For Result-pattern error handling,
+import `tryCatch` from `@rtorcato/js-common/try` instead.
+
+## [1.8.1](https://github.com/rtorcato/js-common/compare/v1.8.0...v1.8.1) (2026-05-29)
+
+
+### Bug Fixes
+
+* **deps:** move CLI deps to optionalDependencies ([52d1e9f](https://github.com/rtorcato/js-common/commit/52d1e9feda9ae86dc705f103678024cfb9772c68))
+* publishing bugs and dead-code cleanup ([30b8d69](https://github.com/rtorcato/js-common/commit/30b8d693d6dfcdc4b6044438318f7d5cbaca0e86))
+
 # [1.8.0](https://github.com/rtorcato/js-common/compare/v1.7.1...v1.8.0) (2026-05-29)
 
 

package/README.md

@@ -5,23 +5,21 @@
 [![npm version](https://badge.fury.io/js/%40rtorcato%2Fjs-common.svg)](https://badge.fury.io/js/%40rtorcato%2Fjs-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/)
-[![Bundle Size](https://img.shields.io/badge/Bundle%20Size-277%20bytes-green.svg)](https://bundlejs.com/?q=@rtorcato/js-common)
-[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.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/)
 
 A comprehensive set of common JavaScript and TypeScript utilities for Node.js projects.
 
 📘 **Documentation:** <https://rtorcato.github.io/js-common/>
 
-## ✨ Features
+## Features
 
-- 🚀 **Ultra-lightweight** - Only 277 bytes main bundle
-- 📦 **Tree-shakeable** - Import only what you need
-- 🔧 **TypeScript** - Full type safety and IntelliSense
-- 🖥️ **CLI included** - Use utilities from command line
-- 📚 **Modular** - Import individual modules
-- ⚡ **Utility modules have no dependencies** - CLI features use optional packages isolated to the `cli` subpath
-- 🧪 **Well tested** - Comprehensive test coverage
+- **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
+- **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
 
@@ -52,18 +50,15 @@ See [CLI.md](./CLI.md) for complete CLI documentation.
 ## Library Usage
 
 ```typescript
-// 🎯 Import specific modules (recommended for tree-shaking)
+// 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 { sum, average, roundTo } from '@rtorcato/js-common/numbers'
 import { capitalize, toTitleCase } from '@rtorcato/js-common/formatting'
 
-// 📦 Or import everything (larger bundle)
-import * as jsCommon from '@rtorcato/js-common'
-
 // Example usage
-console.log(today()) // "2025-10-24"
+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"
@@ -71,118 +66,94 @@ console.log(generateUUID()) // "f47ac10b-58cc-4372-a567-0e02b2c3d479"
 
 ### Bundle Size Impact
 
-The main library bundle is only **277 bytes**! Individual module imports are even smaller:
-
-```typescript
-// This adds ~50 bytes to your bundle
-import { today } from '@rtorcato/js-common/date'
-
-// This adds ~100 bytes to your bundle  
-import { sum, average } from '@rtorcato/js-common/numbers'
-```
-
-### 🎯 **TypeScript Support**
-
-This package is built with TypeScript and includes complete type definitions out of the box:
-
-- ✅ **Full type safety** - All functions have accurate TypeScript types
-- ✅ **Generic support** - Functions like `unique<T>()` preserve your data types  
-- ✅ **JSDoc integration** - Rich documentation in your IDE
-- ✅ **Tree-shakable** - Import only what you need with perfect type inference
-
-```typescript
-// TypeScript automatically infers types
-const numbers = [1, 2, 3, 4, 5]
-const result: number = sum(numbers)  // ✅ Type: number
-
-const users = [{ name: 'John' }, { name: 'Jane' }]
-const uniqueUsers = unique(users)    // ✅ Type: { name: string }[]
-
-// IDE shows full documentation and type hints
-import { today } from '@rtorcato/js-common/date'
-//      ^ JSDoc: Returns today's date as YYYY-MM-DD string
-```
+Each module is shipped as its own subpath export so bundlers only include what you import. Individual modules range from ~100 bytes (e.g. `sleep`) to ~2 KB (e.g. `currency`) when minified. Measure against your own bundle with [bundlejs.com](https://bundlejs.com/?q=@rtorcato/js-common/numbers).
 
 ## Available Modules
 
-### 📅 **Date & Time**
+### Date & Time
 ```typescript
 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 & Math**
+### Numbers & Math
 ```typescript
 import { sum, average, roundTo, clamp, getRandomInt } from '@rtorcato/js-common/numbers'
 import { add, subtract, multiply, divide } from '@rtorcato/js-common/math'
+import { randomInt, randomFloat, randomBool, randomElement } from '@rtorcato/js-common/random'
 ```
 
-### 📝 **Text & Strings**
+### Text & Strings
 ```typescript
 import { capitalize, toTitleCase, padZero } from '@rtorcato/js-common/formatting'
 import { slugify, truncate, removeEmojis } 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'
 ```
 
-### 🔐 **Security & Validation**
+### Security & Validation
 ```typescript
 import { isStrongPassword, generateSecureToken } from '@rtorcato/js-common/security'
 import { isValidEmail, validateEmail } 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'
 ```
 
-### 🗂️ **Data Structures**
+### Data Structures
 ```typescript
 import { flatten, unique, chunk, groupBy } from '@rtorcato/js-common/arrays'
 import { deepMerge, pick, omit, deepClone } 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**
+### Async & Control Flow
 ```typescript
 import { delay, timeout, retry } 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'
+import { createAbortController, withAbort, abortAfter } from '@rtorcato/js-common/abortController'
+import { createCustomError, getErrorMessage, assert } from '@rtorcato/js-common/errors'
 ```
 
-### 🌈 **And More...**
-- **Colors** - Color manipulation and conversion
-- **Console** - Enhanced console utilities  
-- **Crypto** - Cryptographic functions
-- **Currency** - Currency formatting and conversion
-- **Events** - Event handling utilities
-- **Fetch** - HTTP request utilities
-- **File** - File system utilities
-- **UUID** - UUID generation and validation
-- **Process** - Process and environment utilities
-- **Geometry** - 2D geometry calculations
-
-## Requirements
-
-- **Node.js** >= 18.0.0
-- **TypeScript** >= 5.0.0 (for TypeScript projects)
+### System & Process
+```typescript
+import { getENV, isDev, isProd, getNodeEnv, checkEnv } from '@rtorcato/js-common/env'
+import { getOsPlatform, getOsArch, 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 { isMacOs, isWindows, isLinux, getPlatform } from '@rtorcato/js-common/system'
+import { disableConsole, clearConsole } from '@rtorcato/js-common/console'
+```
 
-## Why This Library?
+### Logging
+```typescript
+import { logger } from '@rtorcato/js-common/logger'                   // pino-based
+import { info, warn, error, captureConsole } from '@rtorcato/js-common/logging'
+```
 
-### 🎯 **Focused & Lightweight**
-Unlike larger utility libraries, js-common is designed for modern applications:
-- **Tiny bundle size** - Won't bloat your application
-- **Tree-shakeable** - Only import what you use
-- **CLI included** - Use utilities in scripts and terminal
+### Other
+- `colors` — color manipulation and conversion
+- `crypto` — cryptographic helpers
+- `currency` — currency formatting and conversion
+- `events` — event emitter utilities
+- `fetch` — HTTP request helpers
+- `file` — file system helpers
+- `geometry` — 2D geometry calculations
+- `mime-types` — MIME-type lookup
+- `uuid` — UUID generation and validation
+- `types` — shared TypeScript type definitions (types-only export)
 
-### 📦 **Bundle Size Comparison**
-```
-lodash: ~70KB (full) / ~25KB (common functions)
-ramda: ~60KB (full) / ~15KB (common functions)
-js-common: 277 bytes (full) / ~50-200 bytes (individual modules)
-```
+## Requirements
 
-### 🛠️ **Modern Development**
-- Built with **TypeScript** for excellent DX
-- **ESM-first** with CommonJS compatibility
-- **No dependencies in utility modules** — CLI packages (chalk, commander, etc.) are isolated to the `cli` subpath
-- Comprehensive **test coverage**
+- **Node.js** >= 22.0.0 (enforced via the `engines` field)
+- **TypeScript** >= 5.0.0 (for TypeScript projects)
 
 ## Development
 
@@ -207,6 +178,9 @@ pnpm run check:fix
 
 # Type checking
 pnpm run typecheck
+
+# Run micro-benchmarks (scripts/benchmark.mjs)
+pnpm run benchmark
 ```
 
 ## Documentation site

package/dist/arrays/index.js

@@ -1 +1 @@
-import"../chunks/chunk-ANN5UYCF.js";function o(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 u=e(r);return t[u]||(t[u]=[]),t[u].push(r),t},{})}export{l as chunk,s as compact,o as first,i as flatten,h as groupBy,T as last,c as shuffle,f as unique};
+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};

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 b(o){return!o}export{a as and,r as isBoolean,b 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){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};

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

@@ -0,0 +1 @@
+import{b as e}from"./chunk-FBDKWWIQ.js";import o from"pino";var i=e()?o({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"}}}):o({level:"info"});export{i as a};

package/dist/chunks/chunk-FBDKWWIQ.js

@@ -0,0 +1,3 @@
+import{z as n}from"zod";var c=(r,o)=>{let e=process.env[r.toString()];if(e===void 0&&o!==void 0)return o;if(e===void 0){let t=`Undefined ENV variable - ${r.toString()}`;throw new Error(t)}return e},d=()=>process.env.NODE_ENV==="development",p=()=>process.env.NODE_ENV==="production",E=()=>process.env.NODE_ENV==="test",u=()=>process.env.NODE_ENV||"development";function a(r,o=process.env){try{return r.parse(o)}catch(e){if(e instanceof n.ZodError){let t=`Missing required values in .env:
+`;t+=Object.keys(e.flatten().fieldErrors).join(`
+`);let s=new Error(t);throw s.stack="",s}throw e}}var f=n.object({NODE_ENV:n.enum(["development","test","production"]).default("development"),LOG_LEVEL:n.enum(["debug","info","warn","error"]).default("info"),PORT:n.coerce.number().default(3e3)});export{c as a,d as b,p as c,E as d,u as e,a as f,f as g};