js-common

A focused set of TypeScript utilities for the everyday JavaScript/Node.js work almost every project repeats — date math, string formatting, array/object helpers, validation, UUIDs, retries, sleeps, currency, and so on. Each module ships as a separate subpath so your bundler only includes what you actually import.

Browser APIs live in browser-common

js-common is runtime-agnostic JavaScript plus Node.js helpers. Wrappers around browser Web APIs, such as clipboard, storage, observers, geolocation, the DOM and user-agent detection, live in @rtorcato/browser-common. The two packages don't overlap: a helper belongs to exactly one of them.

• Ultra-lightweight — individual modules ~50–200 B.
• Tree-shakeable — named subpath exports; there is no package root export.
• TypeScript-first — strict types, generics preserved, JSDoc-rich in your IDE.
• CLI included — npx @rtorcato/js-common@latest --help for terminal use.

Install

$npm install @rtorcato/js-common

Requirements: Node.js ≥ 22. TypeScript ≥ 5.0 is optional but recommended — every public API ships with strict types and JSDoc.

Use globally (CLI)

npm install -g @rtorcato/js-common
# or run ad-hoc without installing
npx @rtorcato/js-common@latest --help

See the CLI guide for available commands.

Quick start

Import named functions from a subpath export to keep your bundle tiny:

import { today, daysBetween } from '@rtorcato/js-common/date'
import { sum, average } from '@rtorcato/js-common/numbers'
import { capitalize } from '@rtorcato/js-common/strings'
import { getUUIDv7 } from '@rtorcato/js-common/uuid'

today()                                  // "2026-06-12"
daysBetween('2026-01-01', '2026-06-12')  // 162
sum([1, 2, 3, 4, 5])                     // 15
average([10, 20, 30])                    // 20
capitalize('hello world')                // "Hello world"
getUUIDv7()                              // "018e5e2c-7c0a-7000-8000-0e02b2c3d479"

Always import from a subpath — never from the package root:

// ✅ Adds ~50–200 bytes
import { today } from '@rtorcato/js-common/date'

// ❌ No root export — throws ERR_PACKAGE_PATH_NOT_EXPORTED at resolve time
import { today } from '@rtorcato/js-common'

See Tree-shaking & imports for the full explanation.

What's in the box

• 42 subpath modules, one concern per module — see the Module overview.
• Strict TypeScript — generics preserved end-to-end; any avoided in public APIs.
• JSDoc on every public function — hover docs in VS Code, JetBrains, and Cursor.
• Minimal runtime deps — only pino, uuid, short-uuid, zod. CLI-only packages live in optionalDependencies.
• Tested — Vitest with coverage; CI runs on every commit.

Highlights

Area	Subpath	Example helpers
Dates & time	date, datetime, time	today, daysBetween, formatRelative, nowIso, unixTimestamp
Numbers & math	numbers, geometry, currency	sum, average, roundTo, clamp, formatPrice
Strings	strings, html, regex	slugify, truncate, capitalize, escapeHtml
Collections	arrays, objects, maps	unique, chunk, mergeMaps, deepMerge, pick, omit
Async	promises, sleep, abortController, functions	withTimeout, sleep, sleepRandom, debounce, throttle
Validation	validation, emails, url, uuid	isValidEmail, isValidUrl, getUUIDv7
System	env, os, node, process, system	environment, platform, runtime info
Other	json, fetch, file, logger, security, i18n, html	safeJsonParse, isStrongPassword, …

See the full module overview for the complete list.

Design principles

• Small surface, no kitchen sink. Each module covers one concern. If something needs a heavyweight dependency (locale-aware date formatting, IANA timezones, schema validation across HTTP boundaries), reach for a dedicated library (date-fns, luxon, zod).
• Subpath imports are the contract. The package root re-exports nothing — you always import from @rtorcato/js-common/<module> so tree-shaking is automatic.
• Strict TS, no implicit any in public APIs. Generic helpers preserve narrow types through the call.

Next steps

• Recipes — task-oriented walkthroughs that combine several modules.
• Tree-shaking & imports — how the subpath exports work and how to verify.
• CLI — run utilities from your terminal.
• Module overview — every subpath with examples.
• API reference — auto-generated from the source.
• Migrating — every breaking change, newest first.

Project

• Source: github.com/rtorcato/js-common
• npm: @rtorcato/js-common
• License: MIT
• Issues: GitHub Issues