@rtorcato/js-common 1.7.1 → 1.8.1

package/CHANGELOG.md

@@ -1,3 +1,18 @@
+## [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)
+
+
+### Features
+
+* **docs:** Astro Starlight site on GitHub Pages ([5139f6d](https://github.com/rtorcato/js-common/commit/5139f6d0d6652e54b3e6daa5ed77dcd67d7e59dc))
+
 ## [1.7.1](https://github.com/rtorcato/js-common/compare/v1.7.0...v1.7.1) (2026-05-29)
 
 

package/README.md

@@ -5,19 +5,20 @@
 [![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/)
+[![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
 
-- 🚀 **Ultra-lightweight** - Only 277 bytes main bundle
-- 📦 **Tree-shakeable** - Import only what you need
+- 📦 **Tree-shakeable** - Import only what you need via subpath exports
 - 🔧 **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
+- 🖥️ **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
 
 ## Installation
@@ -56,9 +57,6 @@ 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(sum([1, 2, 3, 4, 5])) // 15
@@ -68,15 +66,7 @@ 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'
-```
+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**
 
@@ -157,7 +147,7 @@ import { sleep } from '@rtorcato/js-common/sleep'
 
 ## Requirements
 
-- **Node.js** >= 18.0.0
+- **Node.js** >= 22.0.0 (enforced via the `engines` field)
 - **TypeScript** >= 5.0.0 (for TypeScript projects)
 
 ## Why This Library?
@@ -168,17 +158,10 @@ Unlike larger utility libraries, js-common is designed for modern applications:
 - **Tree-shakeable** - Only import what you use
 - **CLI included** - Use utilities in scripts and terminal
 
-### 📦 **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)
-```
-
 ### 🛠️ **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
+- **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
@@ -204,8 +187,25 @@ pnpm run check:fix
 
 # Type checking
 pnpm run typecheck
+
+# Run micro-benchmarks (scripts/benchmark.mjs)
+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/**`.
+
+```bash
+# Run the docs locally (http://localhost:4321/js-common)
+pnpm --filter @rtorcato/js-common-docs dev
+
+# Build the static site
+pnpm --filter @rtorcato/js-common-docs build
+```
+
+Live site: <https://rtorcato.github.io/js-common/>
+
 ## Contributing
 
 Contributions are welcome! Please read [CONTRIBUTORS.md](./CONTRIBUTORS.md) for guidelines.

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};

package/dist/cli/cli.mjs

@@ -0,0 +1,439 @@
+import { Separator, checkbox, select } from '@inquirer/prompts';
+import chalk from 'chalk';
+import chalkAnimation from 'chalk-animation';
+import { program } from 'commander';
+import figlet from 'figlet';
+import gradient from 'gradient-string';
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+// Get current directory
+const currentDir = dirname(fileURLToPath(import.meta.url));
+// Get package version
+const packageJson = JSON.parse(readFileSync(resolve(currentDir, '../../package.json'), 'utf-8'));
+program
+    .name('js-common')
+    .description(chalk.cyan('✨ CLI utilities from @rtorcato/js-common'))
+    .version(packageJson.version);
+// Function categories for list and interactive mode
+const functionCategories = {
+    date: {
+        name: '📅 Date & Time',
+        functions: [
+            { name: 'today', description: "Get today's date (YYYY-MM-DD)" },
+            { name: 'now', description: 'Get current timestamp' },
+            { name: 'between', description: 'Calculate days between dates' },
+        ],
+    },
+    math: {
+        name: '🔢 Mathematical',
+        functions: [
+            { name: 'sum', description: 'Calculate sum of numbers' },
+            { name: 'avg', description: 'Calculate average of numbers' },
+            { name: 'random', description: 'Generate random number' },
+            { name: 'round', description: 'Round to decimal places' },
+            { name: 'clamp', description: 'Clamp between min/max' },
+        ],
+    },
+    text: {
+        name: '📝 Text Formatting',
+        functions: [
+            { name: 'capitalize', description: 'Capitalize first letter' },
+            { name: 'title', description: 'Convert to title case' },
+            { name: 'pad', description: 'Pad with leading zeros' },
+        ],
+    },
+    file: {
+        name: '📁 File Operations',
+        functions: [
+            { name: 'exists', description: 'Check if file exists' },
+            { name: 'ext', description: 'Get file extension' },
+        ],
+    },
+    security: {
+        name: '🔒 Security',
+        functions: [
+            { name: 'password', description: 'Check password strength' },
+            { name: 'token', description: 'Generate secure token' },
+        ],
+    },
+    validate: {
+        name: '✅ Validation',
+        functions: [{ name: 'url', description: 'Validate URL format' }],
+    },
+    system: {
+        name: '💻 System Info',
+        functions: [
+            { name: 'pid', description: 'Get process ID' },
+            { name: 'uptime', description: 'Get process uptime' },
+            { name: 'ci', description: 'Check CI environment' },
+            { name: 'node-version', description: 'Get Node.js version' },
+        ],
+    },
+};
+// List all functions - add as a separate command
+program
+    .command('list')
+    .alias('ls')
+    .description('📋 List all available functions')
+    .action(() => {
+    console.log(chalk.cyan('\n✨ Available Functions:\n'));
+    Object.entries(functionCategories).forEach(([key, category]) => {
+        console.log(chalk.bold(category.name));
+        console.log(); // Add space after category header
+        category.functions.forEach((func) => {
+            console.log(chalk.gray(`    js-common ${key} ${func.name}`) + chalk.dim(` - ${func.description}`));
+        });
+        console.log(); // Add space after function list
+    });
+    console.log(chalk.yellow('💡 Use ') +
+        chalk.green('js-common add') +
+        chalk.yellow(' to integrate functions into your project'));
+    console.log(chalk.yellow('💡 Use ') +
+        chalk.green('js-common interactive') +
+        chalk.yellow(' for interactive mode'));
+    console.log(chalk.yellow('💡 Use ') +
+        chalk.green('js-common <command> --help') +
+        chalk.yellow(' for detailed help\n'));
+});
+// Also add as an option for compatibility
+program.option('-l, --list', 'List all available functions');
+// Interactive mode
+program
+    .command('interactive')
+    .alias('i')
+    .description('🎮 Interactive mode with guided prompts')
+    .action(async () => {
+    // Welcome animation
+    const title = figlet.textSync('JS Common', { font: 'Small' });
+    console.log(gradient.pastel.multiline(title));
+    const rainbow = chalkAnimation.rainbow('\n✨ Welcome to JS Common Interactive Mode! ✨\n');
+    await new Promise((resolve) => setTimeout(resolve, 1000));
+    rainbow.stop();
+    try {
+        // Main interactive loop
+        while (true) {
+            const category = await select({
+                message: chalk.cyan('What would you like to do?'),
+                choices: Object.entries(functionCategories)
+                    .reduce((acc, [key, cat], index) => {
+                    acc.push({ name: cat.name, value: key });
+                    if (index < Object.entries(functionCategories).length - 1) {
+                        acc.push(new Separator(' '));
+                    }
+                    return acc;
+                }, [])
+                    .concat([new Separator(' '), { name: chalk.red('❌ Exit'), value: 'exit' }]),
+                pageSize: 17,
+                loop: false,
+            });
+            // Handle exit selection
+            if (category === 'exit') {
+                console.log(chalk.yellow('\n👋 Goodbye!\n'));
+                return;
+            }
+            const selectedCategory = functionCategories[category];
+            // Function selection loop
+            while (true) {
+                const functionName = await select({
+                    message: chalk.cyan(`Choose a ${selectedCategory.name} function:`),
+                    choices: selectedCategory.functions
+                        .reduce((acc, func, index) => {
+                        acc.push({ name: `${func.name} - ${func.description}`, value: func.name });
+                        if (index < selectedCategory.functions.length - 1) {
+                            acc.push(new Separator(' '));
+                        }
+                        return acc;
+                    }, [])
+                        .concat([
+                        new Separator(' '),
+                        { name: chalk.gray('⬅️  Back to categories'), value: 'back' },
+                        { name: chalk.red('❌ Exit'), value: 'exit' },
+                    ]),
+                    pageSize: 12,
+                    loop: false,
+                });
+                // Handle navigation options
+                if (functionName === 'exit') {
+                    console.log(chalk.yellow('\n👋 Goodbye!\n'));
+                    return;
+                }
+                if (functionName === 'back') {
+                    break; // Break out of function selection loop, go back to categories
+                }
+                // Show the command
+                console.log(chalk.green(`\n🚀 You can run this command:`));
+                console.log(chalk.yellow(`js-common ${category} ${functionName} [arguments]`));
+                console.log(chalk.gray(`\nFor detailed usage, run: js-common ${category} ${functionName} --help\n`));
+                return; // Exit after showing the command
+            }
+        }
+    }
+    catch (error) {
+        if (error && typeof error === 'object' && 'isTtyError' in error) {
+            console.log(chalk.red('\n❌ Interactive mode requires a TTY terminal'));
+        }
+        else {
+            console.log(chalk.red('\n❌ Something went wrong in interactive mode'));
+        }
+        process.exit(1);
+    }
+});
+// Add command - help developers integrate functions into their projects
+program
+    .command('add')
+    .alias('a')
+    .description('🔧 Add utility functions to your project')
+    .action(async () => {
+    // Welcome message
+    console.log(gradient.pastel('\n🔧 Function Integration Helper\n'));
+    try {
+        const category = await select({
+            message: chalk.cyan('Which category of utilities do you need?'),
+            choices: Object.entries(functionCategories)
+                .reduce((acc, [key, cat], index) => {
+                acc.push({ name: cat.name, value: key });
+                if (index < Object.entries(functionCategories).length - 1) {
+                    acc.push(new Separator(' '));
+                }
+                return acc;
+            }, [])
+                .concat([new Separator(' '), { name: chalk.red('❌ Exit'), value: 'exit' }]),
+            pageSize: 17,
+            loop: false,
+        });
+        // Handle exit selection
+        if (category === 'exit') {
+            console.log(chalk.yellow('\n👋 Goodbye!\n'));
+            return;
+        }
+        const selectedCategory = functionCategories[category];
+        const functions = await checkbox({
+            message: chalk.cyan(`Select ${selectedCategory.name} functions to add:`),
+            choices: selectedCategory.functions.map((func) => ({
+                name: `${func.name} - ${func.description}`,
+                value: func.name,
+                checked: false,
+            })),
+            pageSize: 10,
+            loop: false,
+        });
+        if (functions.length === 0) {
+            console.log(chalk.yellow('\n📝 No functions selected. Exiting...\n'));
+            return;
+        }
+        console.log(chalk.green('\n📦 Import Statement:'));
+        console.log(chalk.white(`import { ${functions.join(', ')} } from '@rtorcato/js-common/${category}'`));
+        console.log(chalk.green('\n📝 Usage Examples:'));
+        functions.forEach((func) => {
+            const funcInfo = selectedCategory.functions.find((f) => f.name === func);
+            if (funcInfo) {
+                console.log(chalk.gray(`\n// ${funcInfo.description}`));
+                generateUsageExample(category, func);
+            }
+        });
+        console.log(chalk.green('\n📚 Documentation:'));
+        console.log(chalk.blue(`https://github.com/rtorcato/js-common#${category}-utilities`));
+        console.log(chalk.yellow('\n💡 Tip: Run ') +
+            chalk.green(`js-common ${category} ${functions[0]} --help`) +
+            chalk.yellow(' for detailed CLI usage\n'));
+    }
+    catch (error) {
+        if (error && typeof error === 'object' && 'isTtyError' in error) {
+            console.log(chalk.red('\n❌ Interactive mode requires a TTY terminal'));
+        }
+        else {
+            console.log(chalk.red('\n❌ Something went wrong'));
+        }
+        process.exit(1);
+    }
+});
+// Helper function to generate usage examples
+function generateUsageExample(category, functionName) {
+    const examples = {
+        date: {
+            today: `const today = today(); // "${new Date().toISOString().split('T')[0]}"`,
+            now: `const timestamp = now(); // ${Date.now()}`,
+            between: `const days = daysBetween('2023-01-01', '2023-12-31'); // 364`,
+        },
+        math: {
+            sum: `const total = sum([1, 2, 3, 4, 5]); // 15`,
+            avg: `const average = avg([10, 20, 30]); // 20`,
+            random: `const num = randomBetween(1, 100); // 42`,
+            round: `const rounded = roundTo(3.14159, 2); // 3.14`,
+            clamp: `const clamped = clamp(150, 0, 100); // 100`,
+        },
+        text: {
+            capitalize: `const text = capitalize('hello world'); // "Hello world"`,
+            title: `const title = toTitleCase('hello world'); // "Hello World"`,
+            pad: `const padded = padWithZeros(42, 5); // "00042"`,
+        },
+        file: {
+            exists: `const exists = await fileExists('package.json'); // true`,
+            ext: `const extension = getFileExtension('file.txt'); // "txt"`,
+        },
+        security: {
+            password: `const isStrong = checkPasswordStrength('MyPass123!'); // true`,
+            token: `const token = generateSecureToken(32); // "abc123..."`,
+        },
+        validate: {
+            url: `const isValid = isValidUrl('https://example.com'); // true`,
+        },
+        system: {
+            pid: `const processId = getProcessId(); // 12345`,
+            uptime: `const uptime = getProcessUptime(); // 123.45`,
+            ci: `const isCI = isCiEnvironment(); // false`,
+            'node-version': `const version = getNodeVersion(); // "18.17.0"`,
+        },
+    };
+    const example = examples[category]?.[functionName];
+    if (example) {
+        console.log(chalk.white(example));
+    }
+}
+// Date commands
+const dateCmd = program.command('date').description('📅 Date and time utilities');
+dateCmd
+    .command('today')
+    .description("Get today's date (YYYY-MM-DD)")
+    .action(() => {
+    console.log(new Date().toISOString().split('T')[0]);
+});
+dateCmd
+    .command('now')
+    .description('Get current timestamp')
+    .option('-i, --iso', 'ISO format')
+    .option('-t, --time', 'Time only')
+    .action((options) => {
+    if (options.iso) {
+        console.log(new Date().toISOString());
+    }
+    else if (options.time) {
+        console.log(new Date().toTimeString());
+    }
+    else {
+        console.log(Date.now());
+    }
+});
+dateCmd
+    .command('between')
+    .description('Calculate days between dates')
+    .argument('<date1>', 'First date (YYYY-MM-DD)')
+    .argument('<date2>', 'Second date (YYYY-MM-DD)')
+    .action((date1, date2) => {
+    const d1 = new Date(date1);
+    const d2 = new Date(date2);
+    const timeDiff = Math.abs(d2.getTime() - d1.getTime());
+    const daysDiff = Math.ceil(timeDiff / (1000 * 3600 * 24));
+    console.log(`${daysDiff} days`);
+});
+// Math commands
+const mathCmd = program.command('math').description('🔢 Mathematical utilities');
+mathCmd
+    .command('sum')
+    .description('Calculate sum of numbers')
+    .argument('<numbers...>', 'Numbers to sum')
+    .action((numbers) => {
+    const nums = numbers.map(Number).filter((n) => !Number.isNaN(n));
+    console.log(nums.reduce((a, b) => a + b, 0));
+});
+mathCmd
+    .command('avg')
+    .description('Calculate average of numbers')
+    .argument('<numbers...>', 'Numbers to average')
+    .action((numbers) => {
+    const nums = numbers.map(Number).filter((n) => !Number.isNaN(n));
+    console.log(nums.reduce((a, b) => a + b, 0) / nums.length);
+});
+mathCmd
+    .command('random')
+    .description('Generate random number')
+    .argument('<min>', 'Minimum value')
+    .argument('<max>', 'Maximum value')
+    .action((min, max) => {
+    const minNum = Number(min);
+    const maxNum = Number(max);
+    console.log(Math.floor(Math.random() * (maxNum - minNum + 1)) + minNum);
+});
+mathCmd
+    .command('round')
+    .description('Round to decimal places')
+    .argument('<number>', 'Number to round')
+    .argument('<decimals>', 'Decimal places')
+    .action((number, decimals) => {
+    const num = Number(number);
+    const dec = Number(decimals);
+    console.log(Number(num.toFixed(dec)));
+});
+mathCmd
+    .command('clamp')
+    .description('Clamp between min/max')
+    .argument('<number>', 'Number to clamp')
+    .argument('<min>', 'Minimum value')
+    .argument('<max>', 'Maximum value')
+    .action((number, min, max) => {
+    const num = Number(number);
+    const minVal = Number(min);
+    const maxVal = Number(max);
+    console.log(Math.min(Math.max(num, minVal), maxVal));
+});
+// Simple implementations for other commands
+const textCmd = program.command('text').description('📝 Text formatting utilities');
+textCmd
+    .command('capitalize')
+    .description('Capitalize first letter')
+    .argument('<text>', 'Text to capitalize')
+    .action((text) => {
+    console.log(text.charAt(0).toUpperCase() + text.slice(1));
+});
+textCmd
+    .command('title')
+    .description('Convert to title case')
+    .argument('<text>', 'Text to convert')
+    .action((text) => {
+    console.log(text.replace(/\w\S*/g, (txt) => txt.charAt(0).toUpperCase() + txt.substring(1).toLowerCase()));
+});
+// System commands
+const systemCmd = program.command('system').description('💻 System information utilities');
+systemCmd
+    .command('pid')
+    .description('Get process ID')
+    .action(() => {
+    console.log(process.pid);
+});
+systemCmd
+    .command('uptime')
+    .description('Get process uptime')
+    .action(() => {
+    console.log(`${Math.floor(process.uptime())} seconds`);
+});
+systemCmd
+    .command('node-version')
+    .description('Get Node.js version')
+    .action(() => {
+    console.log(process.version);
+});
+// Handle --list option before parsing
+if (process.argv.includes('--list') || process.argv.includes('-l')) {
+    console.log(chalk.cyan('\n✨ Available Functions:\n'));
+    Object.entries(functionCategories).forEach(([key, category]) => {
+        console.log(chalk.bold(category.name));
+        console.log(); // Add space after category header
+        category.functions.forEach((func) => {
+            console.log(chalk.gray(`    js-common ${key} ${func.name}`) + chalk.dim(` - ${func.description}`));
+        });
+        console.log(); // Add space after function list
+    });
+    console.log(chalk.yellow('💡 Use ') +
+        chalk.green('js-common add') +
+        chalk.yellow(' to integrate functions into your project'));
+    console.log(chalk.yellow('💡 Use ') +
+        chalk.green('js-common interactive') +
+        chalk.yellow(' for interactive mode'));
+    console.log(chalk.yellow('💡 Use ') +
+        chalk.green('js-common <command> --help') +
+        chalk.yellow(' for detailed help\n'));
+    process.exit(0);
+}
+// Parse command line arguments
+program.parse();

package/dist/cli/index.mjs

@@ -1,440 +1,26 @@
 #!/usr/bin/env node
-import { Separator, checkbox, select } from '@inquirer/prompts';
-import chalk from 'chalk';
-import chalkAnimation from 'chalk-animation';
-import { program } from 'commander';
-import figlet from 'figlet';
-import gradient from 'gradient-string';
-import { readFileSync } from 'node:fs';
-import { dirname, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-// Get current directory
-const currentDir = dirname(fileURLToPath(import.meta.url));
-// Get package version
-const packageJson = JSON.parse(readFileSync(resolve(currentDir, '../../package.json'), 'utf-8'));
-program
-    .name('js-common')
-    .description(chalk.cyan('✨ CLI utilities from @rtorcato/js-common'))
-    .version(packageJson.version);
-// Function categories for list and interactive mode
-const functionCategories = {
-    date: {
-        name: '📅 Date & Time',
-        functions: [
-            { name: 'today', description: "Get today's date (YYYY-MM-DD)" },
-            { name: 'now', description: 'Get current timestamp' },
-            { name: 'between', description: 'Calculate days between dates' },
-        ],
-    },
-    math: {
-        name: '🔢 Mathematical',
-        functions: [
-            { name: 'sum', description: 'Calculate sum of numbers' },
-            { name: 'avg', description: 'Calculate average of numbers' },
-            { name: 'random', description: 'Generate random number' },
-            { name: 'round', description: 'Round to decimal places' },
-            { name: 'clamp', description: 'Clamp between min/max' },
-        ],
-    },
-    text: {
-        name: '📝 Text Formatting',
-        functions: [
-            { name: 'capitalize', description: 'Capitalize first letter' },
-            { name: 'title', description: 'Convert to title case' },
-            { name: 'pad', description: 'Pad with leading zeros' },
-        ],
-    },
-    file: {
-        name: '📁 File Operations',
-        functions: [
-            { name: 'exists', description: 'Check if file exists' },
-            { name: 'ext', description: 'Get file extension' },
-        ],
-    },
-    security: {
-        name: '🔒 Security',
-        functions: [
-            { name: 'password', description: 'Check password strength' },
-            { name: 'token', description: 'Generate secure token' },
-        ],
-    },
-    validate: {
-        name: '✅ Validation',
-        functions: [{ name: 'url', description: 'Validate URL format' }],
-    },
-    system: {
-        name: '💻 System Info',
-        functions: [
-            { name: 'pid', description: 'Get process ID' },
-            { name: 'uptime', description: 'Get process uptime' },
-            { name: 'ci', description: 'Check CI environment' },
-            { name: 'node-version', description: 'Get Node.js version' },
-        ],
-    },
-};
-// List all functions - add as a separate command
-program
-    .command('list')
-    .alias('ls')
-    .description('📋 List all available functions')
-    .action(() => {
-    console.log(chalk.cyan('\n✨ Available Functions:\n'));
-    Object.entries(functionCategories).forEach(([key, category]) => {
-        console.log(chalk.bold(category.name));
-        console.log(); // Add space after category header
-        category.functions.forEach((func) => {
-            console.log(chalk.gray(`    js-common ${key} ${func.name}`) + chalk.dim(` - ${func.description}`));
-        });
-        console.log(); // Add space after function list
-    });
-    console.log(chalk.yellow('💡 Use ') +
-        chalk.green('js-common add') +
-        chalk.yellow(' to integrate functions into your project'));
-    console.log(chalk.yellow('💡 Use ') +
-        chalk.green('js-common interactive') +
-        chalk.yellow(' for interactive mode'));
-    console.log(chalk.yellow('💡 Use ') +
-        chalk.green('js-common <command> --help') +
-        chalk.yellow(' for detailed help\n'));
-});
-// Also add as an option for compatibility
-program.option('-l, --list', 'List all available functions');
-// Interactive mode
-program
-    .command('interactive')
-    .alias('i')
-    .description('🎮 Interactive mode with guided prompts')
-    .action(async () => {
-    // Welcome animation
-    const title = figlet.textSync('JS Common', { font: 'Small' });
-    console.log(gradient.pastel.multiline(title));
-    const rainbow = chalkAnimation.rainbow('\n✨ Welcome to JS Common Interactive Mode! ✨\n');
-    await new Promise((resolve) => setTimeout(resolve, 1000));
-    rainbow.stop();
-    try {
-        // Main interactive loop
-        while (true) {
-            const category = await select({
-                message: chalk.cyan('What would you like to do?'),
-                choices: Object.entries(functionCategories)
-                    .reduce((acc, [key, cat], index) => {
-                    acc.push({ name: cat.name, value: key });
-                    if (index < Object.entries(functionCategories).length - 1) {
-                        acc.push(new Separator(' '));
-                    }
-                    return acc;
-                }, [])
-                    .concat([new Separator(' '), { name: chalk.red('❌ Exit'), value: 'exit' }]),
-                pageSize: 17,
-                loop: false,
-            });
-            // Handle exit selection
-            if (category === 'exit') {
-                console.log(chalk.yellow('\n👋 Goodbye!\n'));
-                return;
-            }
-            const selectedCategory = functionCategories[category];
-            // Function selection loop
-            while (true) {
-                const functionName = await select({
-                    message: chalk.cyan(`Choose a ${selectedCategory.name} function:`),
-                    choices: selectedCategory.functions
-                        .reduce((acc, func, index) => {
-                        acc.push({ name: `${func.name} - ${func.description}`, value: func.name });
-                        if (index < selectedCategory.functions.length - 1) {
-                            acc.push(new Separator(' '));
-                        }
-                        return acc;
-                    }, [])
-                        .concat([
-                        new Separator(' '),
-                        { name: chalk.gray('⬅️  Back to categories'), value: 'back' },
-                        { name: chalk.red('❌ Exit'), value: 'exit' },
-                    ]),
-                    pageSize: 12,
-                    loop: false,
-                });
-                // Handle navigation options
-                if (functionName === 'exit') {
-                    console.log(chalk.yellow('\n👋 Goodbye!\n'));
-                    return;
-                }
-                if (functionName === 'back') {
-                    break; // Break out of function selection loop, go back to categories
-                }
-                // Show the command
-                console.log(chalk.green(`\n🚀 You can run this command:`));
-                console.log(chalk.yellow(`js-common ${category} ${functionName} [arguments]`));
-                console.log(chalk.gray(`\nFor detailed usage, run: js-common ${category} ${functionName} --help\n`));
-                return; // Exit after showing the command
-            }
-        }
-    }
-    catch (error) {
-        if (error && typeof error === 'object' && 'isTtyError' in error) {
-            console.log(chalk.red('\n❌ Interactive mode requires a TTY terminal'));
-        }
-        else {
-            console.log(chalk.red('\n❌ Something went wrong in interactive mode'));
-        }
-        process.exit(1);
-    }
-});
-// Add command - help developers integrate functions into their projects
-program
-    .command('add')
-    .alias('a')
-    .description('🔧 Add utility functions to your project')
-    .action(async () => {
-    // Welcome message
-    console.log(gradient.pastel('\n🔧 Function Integration Helper\n'));
-    try {
-        const category = await select({
-            message: chalk.cyan('Which category of utilities do you need?'),
-            choices: Object.entries(functionCategories)
-                .reduce((acc, [key, cat], index) => {
-                acc.push({ name: cat.name, value: key });
-                if (index < Object.entries(functionCategories).length - 1) {
-                    acc.push(new Separator(' '));
-                }
-                return acc;
-            }, [])
-                .concat([new Separator(' '), { name: chalk.red('❌ Exit'), value: 'exit' }]),
-            pageSize: 17,
-            loop: false,
-        });
-        // Handle exit selection
-        if (category === 'exit') {
-            console.log(chalk.yellow('\n👋 Goodbye!\n'));
-            return;
-        }
-        const selectedCategory = functionCategories[category];
-        const functions = await checkbox({
-            message: chalk.cyan(`Select ${selectedCategory.name} functions to add:`),
-            choices: selectedCategory.functions.map((func) => ({
-                name: `${func.name} - ${func.description}`,
-                value: func.name,
-                checked: false,
-            })),
-            pageSize: 10,
-            loop: false,
-        });
-        if (functions.length === 0) {
-            console.log(chalk.yellow('\n📝 No functions selected. Exiting...\n'));
-            return;
-        }
-        console.log(chalk.green('\n📦 Import Statement:'));
-        console.log(chalk.white(`import { ${functions.join(', ')} } from '@rtorcato/js-common/${category}'`));
-        console.log(chalk.green('\n📝 Usage Examples:'));
-        functions.forEach((func) => {
-            const funcInfo = selectedCategory.functions.find((f) => f.name === func);
-            if (funcInfo) {
-                console.log(chalk.gray(`\n// ${funcInfo.description}`));
-                generateUsageExample(category, func);
-            }
-        });
-        console.log(chalk.green('\n📚 Documentation:'));
-        console.log(chalk.blue(`https://github.com/rtorcato/js-common#${category}-utilities`));
-        console.log(chalk.yellow('\n💡 Tip: Run ') +
-            chalk.green(`js-common ${category} ${functions[0]} --help`) +
-            chalk.yellow(' for detailed CLI usage\n'));
-    }
-    catch (error) {
-        if (error && typeof error === 'object' && 'isTtyError' in error) {
-            console.log(chalk.red('\n❌ Interactive mode requires a TTY terminal'));
-        }
-        else {
-            console.log(chalk.red('\n❌ Something went wrong'));
-        }
-        process.exit(1);
-    }
-});
-// Helper function to generate usage examples
-function generateUsageExample(category, functionName) {
-    const examples = {
-        date: {
-            today: `const today = today(); // "${new Date().toISOString().split('T')[0]}"`,
-            now: `const timestamp = now(); // ${Date.now()}`,
-            between: `const days = daysBetween('2023-01-01', '2023-12-31'); // 364`,
-        },
-        math: {
-            sum: `const total = sum([1, 2, 3, 4, 5]); // 15`,
-            avg: `const average = avg([10, 20, 30]); // 20`,
-            random: `const num = randomBetween(1, 100); // 42`,
-            round: `const rounded = roundTo(3.14159, 2); // 3.14`,
-            clamp: `const clamped = clamp(150, 0, 100); // 100`,
-        },
-        text: {
-            capitalize: `const text = capitalize('hello world'); // "Hello world"`,
-            title: `const title = toTitleCase('hello world'); // "Hello World"`,
-            pad: `const padded = padWithZeros(42, 5); // "00042"`,
-        },
-        file: {
-            exists: `const exists = await fileExists('package.json'); // true`,
-            ext: `const extension = getFileExtension('file.txt'); // "txt"`,
-        },
-        security: {
-            password: `const isStrong = checkPasswordStrength('MyPass123!'); // true`,
-            token: `const token = generateSecureToken(32); // "abc123..."`,
-        },
-        validate: {
-            url: `const isValid = isValidUrl('https://example.com'); // true`,
-        },
-        system: {
-            pid: `const processId = getProcessId(); // 12345`,
-            uptime: `const uptime = getProcessUptime(); // 123.45`,
-            ci: `const isCI = isCiEnvironment(); // false`,
-            'node-version': `const version = getNodeVersion(); // "18.17.0"`,
-        },
-    };
-    const example = examples[category]?.[functionName];
-    if (example) {
-        console.log(chalk.white(example));
-    }
+// 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.
+try {
+    await import('./cli.mjs');
 }
-// Date commands
-const dateCmd = program.command('date').description('📅 Date and time utilities');
-dateCmd
-    .command('today')
-    .description("Get today's date (YYYY-MM-DD)")
-    .action(() => {
-    console.log(new Date().toISOString().split('T')[0]);
-});
-dateCmd
-    .command('now')
-    .description('Get current timestamp')
-    .option('-i, --iso', 'ISO format')
-    .option('-t, --time', 'Time only')
-    .action((options) => {
-    if (options.iso) {
-        console.log(new Date().toISOString());
-    }
-    else if (options.time) {
-        console.log(new Date().toTimeString());
-    }
-    else {
-        console.log(Date.now());
+catch (err) {
+    const isMissingModule = err !== null &&
+        typeof err === 'object' &&
+        '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.exit(1);
     }
-});
-dateCmd
-    .command('between')
-    .description('Calculate days between dates')
-    .argument('<date1>', 'First date (YYYY-MM-DD)')
-    .argument('<date2>', 'Second date (YYYY-MM-DD)')
-    .action((date1, date2) => {
-    const d1 = new Date(date1);
-    const d2 = new Date(date2);
-    const timeDiff = Math.abs(d2.getTime() - d1.getTime());
-    const daysDiff = Math.ceil(timeDiff / (1000 * 3600 * 24));
-    console.log(`${daysDiff} days`);
-});
-// Math commands
-const mathCmd = program.command('math').description('🔢 Mathematical utilities');
-mathCmd
-    .command('sum')
-    .description('Calculate sum of numbers')
-    .argument('<numbers...>', 'Numbers to sum')
-    .action((numbers) => {
-    const nums = numbers.map(Number).filter((n) => !Number.isNaN(n));
-    console.log(nums.reduce((a, b) => a + b, 0));
-});
-mathCmd
-    .command('avg')
-    .description('Calculate average of numbers')
-    .argument('<numbers...>', 'Numbers to average')
-    .action((numbers) => {
-    const nums = numbers.map(Number).filter((n) => !Number.isNaN(n));
-    console.log(nums.reduce((a, b) => a + b, 0) / nums.length);
-});
-mathCmd
-    .command('random')
-    .description('Generate random number')
-    .argument('<min>', 'Minimum value')
-    .argument('<max>', 'Maximum value')
-    .action((min, max) => {
-    const minNum = Number(min);
-    const maxNum = Number(max);
-    console.log(Math.floor(Math.random() * (maxNum - minNum + 1)) + minNum);
-});
-mathCmd
-    .command('round')
-    .description('Round to decimal places')
-    .argument('<number>', 'Number to round')
-    .argument('<decimals>', 'Decimal places')
-    .action((number, decimals) => {
-    const num = Number(number);
-    const dec = Number(decimals);
-    console.log(Number(num.toFixed(dec)));
-});
-mathCmd
-    .command('clamp')
-    .description('Clamp between min/max')
-    .argument('<number>', 'Number to clamp')
-    .argument('<min>', 'Minimum value')
-    .argument('<max>', 'Maximum value')
-    .action((number, min, max) => {
-    const num = Number(number);
-    const minVal = Number(min);
-    const maxVal = Number(max);
-    console.log(Math.min(Math.max(num, minVal), maxVal));
-});
-// Simple implementations for other commands
-const textCmd = program.command('text').description('📝 Text formatting utilities');
-textCmd
-    .command('capitalize')
-    .description('Capitalize first letter')
-    .argument('<text>', 'Text to capitalize')
-    .action((text) => {
-    console.log(text.charAt(0).toUpperCase() + text.slice(1));
-});
-textCmd
-    .command('title')
-    .description('Convert to title case')
-    .argument('<text>', 'Text to convert')
-    .action((text) => {
-    console.log(text.replace(/\w\S*/g, (txt) => txt.charAt(0).toUpperCase() + txt.substring(1).toLowerCase()));
-});
-// System commands
-const systemCmd = program.command('system').description('💻 System information utilities');
-systemCmd
-    .command('pid')
-    .description('Get process ID')
-    .action(() => {
-    console.log(process.pid);
-});
-systemCmd
-    .command('uptime')
-    .description('Get process uptime')
-    .action(() => {
-    console.log(`${Math.floor(process.uptime())} seconds`);
-});
-systemCmd
-    .command('node-version')
-    .description('Get Node.js version')
-    .action(() => {
-    console.log(process.version);
-});
-// Handle --list option before parsing
-if (process.argv.includes('--list') || process.argv.includes('-l')) {
-    console.log(chalk.cyan('\n✨ Available Functions:\n'));
-    Object.entries(functionCategories).forEach(([key, category]) => {
-        console.log(chalk.bold(category.name));
-        console.log(); // Add space after category header
-        category.functions.forEach((func) => {
-            console.log(chalk.gray(`    js-common ${key} ${func.name}`) + chalk.dim(` - ${func.description}`));
-        });
-        console.log(); // Add space after function list
-    });
-    console.log(chalk.yellow('💡 Use ') +
-        chalk.green('js-common add') +
-        chalk.yellow(' to integrate functions into your project'));
-    console.log(chalk.yellow('💡 Use ') +
-        chalk.green('js-common interactive') +
-        chalk.yellow(' for interactive mode'));
-    console.log(chalk.yellow('💡 Use ') +
-        chalk.green('js-common <command> --help') +
-        chalk.yellow(' for detailed help\n'));
-    process.exit(0);
+    throw err;
 }
-// Parse command line arguments
-program.parse();
+export {};

package/dist/env/index.js

@@ -1,3 +1 @@
-import"../chunks/chunk-ANN5UYCF.js";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{f as RootApiEnvSchema,a as checkEnv,c as getENV,u as getNodeEnv,d as isDev,p as isProd,E as isTest};
+import{a,b,c,d,e,f,g}from"../chunks/chunk-FBDKWWIQ.js";import"../chunks/chunk-ANN5UYCF.js";export{g as RootApiEnvSchema,f as checkEnv,a as getENV,e as getNodeEnv,b as isDev,c as isProd,d as isTest};

package/dist/index.js

@@ -1 +0,0 @@
-import"./chunks/chunk-ANN5UYCF.js";var t=()=>(console.log("test"),"testPackage");export{t as testPackage};

package/dist/logger/index.js

@@ -0,0 +1 @@
+import{a as o}from"../chunks/chunk-6J7HIWG6.js";import"../chunks/chunk-FBDKWWIQ.js";import"../chunks/chunk-ANN5UYCF.js";export{o as logger};

package/dist/logger/logger.js

@@ -0,0 +1 @@
+import{a}from"../chunks/chunk-6J7HIWG6.js";import"../chunks/chunk-FBDKWWIQ.js";import"../chunks/chunk-ANN5UYCF.js";export{a as logger};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rtorcato/js-common",
-  "version": "1.7.1",
+  "version": "1.8.1",
   "description": "JavaScript and TypeScript common code",
   "type": "module",
   "main": "dist/index.js",
@@ -28,7 +28,7 @@
   "scripts": {
     "build-dev": "rimraf ./dist && cross-env NODE_ENV=development node build.mjs && tsc --emitDeclarationOnly --project tsconfig.build.json && npm run build-cli",
     "build-prod": "rimraf ./dist && cross-env NODE_ENV=production node build.mjs && tsc --emitDeclarationOnly --project tsconfig.build.json && npm run build-cli",
-    "build-cli": "tsc src/cli/cli.ts --ignoreConfig --types node --outDir dist/cli --target ES2022 --module ES2022 --moduleResolution bundler --allowImportingTsExtensions false --esModuleInterop --skipLibCheck && mv dist/cli/cli.js dist/cli/temp.mjs && echo '#!/usr/bin/env node' > dist/cli/index.mjs && cat dist/cli/temp.mjs >> dist/cli/index.mjs && rm dist/cli/temp.mjs && chmod +x dist/cli/index.mjs",
+    "build-cli": "tsc src/cli/bootstrap.ts src/cli/cli.ts --ignoreConfig --types node --outDir dist/cli --target ES2022 --module ES2022 --moduleResolution bundler --allowImportingTsExtensions false --esModuleInterop --skipLibCheck && echo '#!/usr/bin/env node' > dist/cli/index.mjs && cat dist/cli/bootstrap.js >> dist/cli/index.mjs && rm dist/cli/bootstrap.js && mv dist/cli/cli.js dist/cli/cli.mjs && sed -i.bak \"s|'./cli.js'|'./cli.mjs'|g\" dist/cli/index.mjs && rm dist/cli/index.mjs.bak && chmod +x dist/cli/index.mjs",
     "prepublishOnly": "npm run build-prod",
     "==================== Common ====================": "",
     "lint": "pnpm exec biome lint .",
@@ -116,6 +116,10 @@
       "import": "./dist/file/index.js",
       "types": "./dist/file/index.d.ts"
     },
+    "./formatting": {
+      "import": "./dist/formatting/index.js",
+      "types": "./dist/formatting/index.d.ts"
+    },
     "./functions": {
       "import": "./dist/functions/index.js",
       "types": "./dist/functions/index.d.ts"
@@ -249,7 +253,6 @@
     "@semantic-release/release-notes-generator": "^14.1.0",
     "@types/chalk-animation": "^1.6.3",
     "@types/figlet": "^1.7.0",
-    "@types/inquirer": "^9.0.9",
     "@types/luxon": "^3.7.1",
     "@types/node": "^24.9.1",
     "@vitest/coverage-istanbul": "^4.0.17",
@@ -257,6 +260,7 @@
     "esbuild": "^0.27.4",
     "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",
@@ -264,22 +268,22 @@
     "vitest": "^4.0.17"
   },
   "dependencies": {
-    "@inquirer/prompts": "^8.5.0",
-    "chalk": "^5.6.2",
-    "chalk-animation": "^2.0.3",
-    "commander": "^14.0.1",
     "date-fns": "^4.1.0",
     "date-fns-tz": "^3.2.0",
-    "figlet": "^1.9.3",
-    "gradient-string": "^3.0.0",
-    "inquirer": "^13.3.2",
     "luxon": "^3.7.2",
-    "nanospinner": "^1.2.2",
     "pino": "^10.1.0",
     "short-uuid": "^6.0.3",
     "uuid": "^13.0.0",
     "zod": "^4.1.12"
   },
+  "optionalDependencies": {
+    "@inquirer/prompts": "^8.5.0",
+    "chalk": "^5.6.2",
+    "chalk-animation": "^2.0.3",
+    "commander": "^14.0.1",
+    "figlet": "^1.9.3",
+    "gradient-string": "^3.0.0"
+  },
   "config": {
     "commitizen": {
       "path": "cz-conventional-changelog"
@@ -299,5 +303,8 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
   }
 }

package/dist/helloworld/index.js

@@ -1 +0,0 @@
-import"../chunks/chunk-ANN5UYCF.js";function l(){return"Hello, World!"}export{l as helloWorld};

package/dist/logging/index1.js

@@ -1 +0,0 @@
-import"../chunks/chunk-ANN5UYCF.js";var t=(...o)=>{let n=new Date().toISOString();console.log(`[${n}]`,...o)},e=(...o)=>{console.warn("\x1B[33m%s\x1B[0m",...o)},s=(...o)=>{console.error("\x1B[31m%s\x1B[0m",...o)},r=(...o)=>{console.info("\x1B[34m%s\x1B[0m",...o)};export{s as error,r as info,t as logWithTimestamp,e as warn};