@rtorcato/js-common 1.8.1 → 2.0.0

package/CHANGELOG.md

@@ -1,3 +1,20 @@
+# [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)
 
 

package/README.md

@@ -6,20 +6,20 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
 [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D22.0.0-brightgreen.svg)](https://nodejs.org/)
+[![codecov](https://codecov.io/gh/rtorcato/js-common/branch/main/graph/badge.svg)](https://codecov.io/gh/rtorcato/js-common)
 [![Docs](https://img.shields.io/badge/docs-rtorcato.github.io%2Fjs--common-blue.svg)](https://rtorcato.github.io/js-common/)
 
 A comprehensive set of common JavaScript and TypeScript utilities for Node.js projects.
 
 📘 **Documentation:** <https://rtorcato.github.io/js-common/>
 
-## ✨ Features
+## Features
 
-- 📦 **Tree-shakeable** - Import only what you need via subpath exports
-- 🔧 **TypeScript** - Full type safety and IntelliSense
-- 🖥️ **CLI included** - Optional binary for use in scripts and terminals
-- 📚 **Modular** - One module per concern, ~40 subpaths
-- ⚡ **Minimal runtime deps** - Only `date-fns`, `luxon`, `pino`, `uuid`, `short-uuid`, `zod`. CLI packages (`chalk`, `commander`, `figlet`, …) are `optionalDependencies` and only needed for the CLI.
-- 🧪 **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
 
@@ -50,7 +50,7 @@ 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'
@@ -58,7 +58,7 @@ import { sum, average, roundTo } from '@rtorcato/js-common/numbers'
 import { capitalize, toTitleCase } from '@rtorcato/js-common/formatting'
 
 // 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"
@@ -68,102 +68,93 @@ console.log(generateUUID()) // "f47ac10b-58cc-4372-a567-0e02b2c3d479"
 
 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).
 
-### 🎯 **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
-```
-
 ## 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
+### 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'
+```
+
+### Logging
+```typescript
+import { logger } from '@rtorcato/js-common/logger'                   // pino-based
+import { info, warn, error, captureConsole } from '@rtorcato/js-common/logging'
+```
+
+### 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)
 
 ## Requirements
 
 - **Node.js** >= 22.0.0 (enforced via the `engines` field)
 - **TypeScript** >= 5.0.0 (for TypeScript projects)
 
-## Why This Library?
-
-### 🎯 **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
-
-### 🛠️ **Modern Development**
-- Built with **TypeScript** for excellent DX
-- **ESM-only**, native subpath exports
-- **Minimal runtime deps** — CLI packages (`chalk`, `commander`, `figlet`, …) are `optionalDependencies` and only fetched when you opt in to the CLI
-- Comprehensive **test coverage**
-
 ## Development
 
 ```bash

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/errors/index.js

@@ -1 +1 @@
-import"../chunks/chunk-ANN5UYCF.js";function e(n,r){let t=new Error(r);return t.name=n,t}function o(n,r){return n instanceof Error&&n.name===r}function i(n){if(n instanceof Error)return n.message;if(typeof n=="string")return n;try{return JSON.stringify(n)}catch{return String(n)}}function s(n,r){if(!n)throw new Error(r)}async function a(n,r){try{return await n()}catch{return r}}export{s as assert,e as createCustomError,i as getErrorMessage,o as isErrorName,a as tryCatch};
+import"../chunks/chunk-ANN5UYCF.js";function e(n,r){let t=new Error(r);return t.name=n,t}function o(n,r){return n instanceof Error&&n.name===r}function i(n){if(n instanceof Error)return n.message;if(typeof n=="string")return n;try{return JSON.stringify(n)}catch{return String(n)}}function s(n,r){if(!n)throw new Error(r)}async function a(n,r){try{return await n()}catch{return r}}export{s as assert,e as createCustomError,i as getErrorMessage,o as isErrorName,a as tryWithFallback};

package/dist/logging/index.js

@@ -1 +1 @@
-import"../chunks/chunk-ANN5UYCF.js";function e(o,r="info"){let n=new Date().toISOString();console[r](`[${n}] ${o}`)}function t(o){console.warn(`[WARN] ${o}`)}function s(o){console.error(`[ERROR] ${o}`)}function c(o){console.info(`[INFO] ${o}`)}function l(o){let r={log:console.log,info:console.info,warn:console.warn,error:console.error};return["log","info","warn","error"].forEach(n=>{console[n]=(...i)=>{o(n,...i),r[n](...i)}}),()=>{Object.assign(console,r)}}export{l as captureConsole,s as error,c as info,e as logWithTimestamp,t as warn};
+import"../chunks/chunk-ANN5UYCF.js";function i(o,r="info"){let n=new Date().toISOString();console[r](`[${n}] ${o}`)}function t(o){console.warn(`[WARN] ${o}`)}function s(o){console.error(`[ERROR] ${o}`)}function c(o){console.info(`[INFO] ${o}`)}function l(o){let r={log:console.log,info:console.info,warn:console.warn,error:console.error};return["log","info","warn","error"].forEach(n=>{console[n]=(...e)=>{o(n,...e),r[n](...e)}}),()=>{Object.assign(console,r)}}export{l as captureConsole,s as error,c as info,i as logWithTimestamp,t as warn};

package/dist/math/index.js

@@ -1 +1 @@
-import{a as d,b as t,c as i,d as r}from"../chunks/chunk-DCFILRIS.js";import"../chunks/chunk-ANN5UYCF.js";export{d as add,r as divide,i as multiply,t as subtract};
+import"../chunks/chunk-ANN5UYCF.js";var n=(e,r)=>e+r,u=(e,r)=>e-r,b=(e,r)=>e*r,m=(e,r)=>e/r;export{n as add,m as divide,b as multiply,u as subtract};

package/dist/validation/index.js

@@ -1 +1 @@
-import"../chunks/chunk-ANN5UYCF.js";function r(n){return n!=null}function e(n){return typeof n=="string"}function t(n){return typeof n=="number"&&!Number.isNaN(n)}function i(n){return typeof n=="boolean"}function o(n){return Array.isArray(n)}function u(n){return typeof n=="object"&&n!==null&&!Array.isArray(n)}function s(n){return/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(n)}function a(n){try{return new URL(n),!0}catch{return!1}}export{o as isArray,i as isBoolean,r as isDefined,s as isEmail,t as isNumber,u as isObject,e as isString,a as isUrl};
+import"../chunks/chunk-ANN5UYCF.js";function r(n){return n!=null}function e(n){return typeof n=="string"}function t(n){return typeof n=="number"&&!Number.isNaN(n)}function o(n){return typeof n=="boolean"}function u(n){return Array.isArray(n)}function i(n){return typeof n=="object"&&n!==null&&!Array.isArray(n)}function s(n){return/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(n)}function a(n){try{return new URL(n),!0}catch{return!1}}export{u as isArray,o as isBoolean,r as isDefined,s as isEmail,t as isNumber,i as isObject,e as isString,a as isUrl};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rtorcato/js-common",
-  "version": "1.8.1",
+  "version": "2.0.0",
   "description": "JavaScript and TypeScript common code",
   "type": "module",
   "main": "dist/index.js",
@@ -261,7 +261,6 @@
     "husky": "^9.1.7",
     "jsdom": "^29.0.1",
     "knip": "^6.14.2",
-    "lint-staged": "^16.2.6",
     "rimraf": "^6.0.1",
     "semantic-release": "^25.0.1",
     "typescript": "^6.0.2",
@@ -289,18 +288,6 @@
       "path": "cz-conventional-changelog"
     }
   },
-  "lint-staged": {
-    "*.{js,ts,json,md}": [
-      "pnpm exec biome lint",
-      "pnpm exec biome format",
-      "git add"
-    ]
-  },
-  "husky": {
-    "hooks": {
-      "pre-commit": "lint-staged"
-    }
-  },
   "publishConfig": {
     "access": "public"
   },

package/dist/chunks/chunk-DCFILRIS.js

@@ -1 +0,0 @@
-var n=(e,r)=>e+r,u=(e,r)=>e-r,b=(e,r)=>e*r,m=(e,r)=>e/r;export{n as a,u as b,b as c,m as d};

package/dist/math/math.js

@@ -1 +0,0 @@
-import{a,b,c,d}from"../chunks/chunk-DCFILRIS.js";import"../chunks/chunk-ANN5UYCF.js";export{a as add,d as divide,c as multiply,b as subtract};