@rtorcato/js-common 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,32 @@
+# [1.2.0](https://github.com/rtorcato/js-common/compare/v1.1.0...v1.2.0) (2025-10-24)
+
+
+### Bug Fixes
+
+* remove commitlint dependency from release job ([dbf2795](https://github.com/rtorcato/js-common/commit/dbf27956698b40d68c29dcaba62c5498b8bb7f52))
+
+
+### Features
+
+* modernize CI/CD workflow with js-tooling structure ([a46b6bf](https://github.com/rtorcato/js-common/commit/a46b6bf73696def0be74136d872ece3a0447ce2d))
+
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2025-10-24
+
+### Added
+- Initial public release on GitHub and npm
+- Comprehensive JavaScript/TypeScript utilities library
+- Support for arrays, strings, dates, validation, crypto, and more
+- Full TypeScript support with type definitions
+- Modular imports for tree-shaking optimization
+
+### Changed
+- Migrated from GitLab to GitHub
+- Changed from private to public package
+- Updated to MIT license

package/CONTRIBUTORS.md

@@ -0,0 +1,97 @@
+# Contributors
+
+Thank you to all the people who have contributed to this project! 🎉
+
+## Core Contributors
+
+- **Richard Torcato** ([@rtorcato](https://github.com/rtorcato)) - Creator and maintainer
+
+## How to Contribute
+
+We welcome contributions from everyone! Here's how you can help:
+
+### 🐛 Bug Reports
+- Check if the issue already exists in [GitHub Issues](https://github.com/rtorcato/js-common/issues)
+- Create a new issue with a clear description and reproduction steps
+- Include relevant code examples and error messages
+
+### 💡 Feature Requests
+- Open an issue to discuss new features before implementing
+- Explain the use case and benefits
+- Consider backward compatibility
+
+### 🔧 Code Contributions
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes following our coding standards
+4. Add tests for new functionality
+5. Ensure all tests pass (`pnpm test`)
+6. Run linting and formatting (`pnpm run check:fix`)
+7. Commit your changes (`git commit -m 'feat: add amazing feature'`)
+8. Push to your branch (`git push origin feature/amazing-feature`)
+9. Open a Pull Request
+
+### 📝 Documentation
+- Improve README.md, code comments, or JSDoc
+- Add examples for existing functions
+- Fix typos or clarify explanations
+
+### 🧪 Testing
+- Add test cases for existing functions
+- Improve test coverage
+- Report test failures
+
+## Development Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/rtorcato/js-common.git
+cd js-common
+
+# Install dependencies
+pnpm install
+
+# Run tests
+pnpm test
+
+# Build the project
+pnpm run build-prod
+
+# Run linting and formatting
+pnpm run check:fix
+```
+
+## Code Style
+
+This project uses:
+- **Biome** for linting and formatting
+- **TypeScript** for type safety
+- **Vitest** for testing
+- **Conventional Commits** for commit messages
+
+## Commit Message Convention
+
+We follow [Conventional Commits](https://conventionalcommits.org/):
+
+- `feat:` - New features
+- `fix:` - Bug fixes
+- `docs:` - Documentation changes
+- `style:` - Code style changes (formatting, etc.)
+- `refactor:` - Code refactoring
+- `test:` - Adding or updating tests
+- `chore:` - Maintenance tasks
+
+## Recognition
+
+All contributors will be:
+- Listed in this file
+- Mentioned in release notes for their contributions
+- Given credit in the project's acknowledgments
+
+## Questions?
+
+Feel free to open an issue or reach out to the maintainers if you have any questions about contributing!
+
+---
+
+*This project follows the [Contributor Covenant](https://www.contributor-covenant.org/) Code of Conduct.*

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Richard Torcato
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,199 @@
+# js-common
+
+[![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/)
+
+A comprehensive set of common JavaScript and TypeScript utilities for Node.js projects.
+
+## ✨ 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
+- ⚡ **Zero dependencies** - Core library has no external deps
+- 🧪 **Well tested** - Comprehensive test coverage
+
+## Installation
+
+```bash
+npm install @rtorcato/js-common
+```
+
+## CLI Usage
+
+This package includes a command-line interface for many utilities:
+
+```bash
+# Install globally to use the CLI
+npm install -g @rtorcato/js-common
+
+# Or use with npx
+npx @rtorcato/js-common --help
+
+# Examples
+npx @rtorcato/js-common date today
+npx @rtorcato/js-common math sum 1 2 3 4 5
+npx @rtorcato/js-common text capitalize "hello world"
+npx @rtorcato/js-common security token
+```
+
+See [CLI.md](./CLI.md) for complete CLI documentation.
+
+## Library Usage
+
+```typescript
+// 🎯 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(sum([1, 2, 3, 4, 5])) // 15
+console.log(capitalize('hello world')) // "Hello world"
+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'
+```
+
+## Available Modules
+
+### 📅 **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'
+```
+
+### 🔢 **Numbers & Math**
+```typescript
+import { sum, average, roundTo, clamp, getRandomInt } from '@rtorcato/js-common/numbers'
+import { add, subtract, multiply, divide } from '@rtorcato/js-common/math'
+```
+
+### 📝 **Text & Strings**
+```typescript
+import { capitalize, toTitleCase, padZero } from '@rtorcato/js-common/formatting'
+import { slugify, truncate, removeEmojis } from '@rtorcato/js-common/strings'
+```
+
+### 🔐 **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'
+```
+
+### 🗂️ **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'
+```
+
+### 🔄 **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'
+```
+
+### 🌈 **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)
+
+## 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
+
+### 📦 **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
+- **Zero dependencies** in core library
+- Comprehensive **test coverage**
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Run tests
+pnpm test
+
+# Run tests in watch mode
+pnpm test:watch
+
+# Build the project
+pnpm run build-prod
+
+# Build development version
+pnpm run build-dev
+
+# Lint and format
+pnpm run check:fix
+
+# Type checking
+pnpm run typecheck
+```
+
+## Contributing
+
+Contributions are welcome! Please read [CONTRIBUTORS.md](./CONTRIBUTORS.md) for guidelines.
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature-name`
+3. Make your changes with tests
+4. Run the test suite: `pnpm test`
+5. Submit a pull request
+
+## License
+
+MIT © [Richard Torcato](https://github.com/rtorcato)
+
+

package/dist/abortController/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Creates a new AbortController and returns its controller and signal.
+ * @returns {{ controller: AbortController, signal: AbortSignal }}
+ */
+export declare function createAbortController(): {
+    controller: AbortController;
+    signal: AbortSignal;
+};
+/**
+ * Returns a promise that rejects when the given AbortSignal is aborted.
+ * @param signal The AbortSignal to listen to.
+ * @returns {Promise<never>}
+ */
+export declare function abortPromise(signal: AbortSignal): Promise<never>;
+/**
+ * Wraps a promise and rejects it if the signal is aborted.
+ * @param promise The promise to wrap.
+ * @param signal The AbortSignal.
+ * @returns {Promise<T>}
+ */
+export declare function withAbort<T>(promise: Promise<T>, signal: AbortSignal): Promise<T>;
+/**
+ * Aborts the given controller after a timeout (ms).
+ * @param controller The AbortController.
+ * @param ms Timeout in milliseconds.
+ * @returns {NodeJS.Timeout | number} The timeout ID.
+ */
+export declare function abortAfter(controller: AbortController, ms: number): ReturnType<typeof setTimeout>;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/abortController/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,qBAAqB;;;EAGpC;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,KAAK,CAAC,CAchE;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC,CAEjF;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,UAAU,EAAE,eAAe,EAAE,EAAE,EAAE,MAAM,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC,CAEjG"}

package/dist/abortController/index.js

@@ -0,0 +1 @@
+import"../chunks/chunk-ANN5UYCF.js";function n(){let r=new AbortController;return{controller:r,signal:r.signal}}function t(r){return new Promise((e,o)=>{r.aborted?o(new DOMException("Aborted","AbortError")):r.addEventListener("abort",()=>{o(new DOMException("Aborted","AbortError"))},{once:!0})})}function i(r,e){return Promise.race([r,t(e)])}function b(r,e){return setTimeout(()=>r.abort(),e)}export{b as abortAfter,t as abortPromise,n as createAbortController,i as withAbort};

package/dist/arrays/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Returns the first element of an array, or undefined if the array is empty.
+ * @param arr The array.
+ * @returns The first element or undefined.
+ */
+export declare function first<T>(arr: T[]): T | undefined;
+/**
+ * Returns the last element of an array, or undefined if the array is empty.
+ * @param arr The array.
+ * @returns The last element or undefined.
+ */
+export declare function last<T>(arr: T[]): T | undefined;
+/**
+ * Removes duplicate values from an array.
+ * @param arr The array.
+ * @returns A new array with unique values.
+ */
+export declare function unique<T>(arr: T[]): T[];
+/**
+ * Flattens an array one level deep.
+ * @param arr The array to flatten.
+ * @returns A new flattened array.
+ */
+export declare function flatten<T>(arr: any[]): T[];
+/**
+ * Chunks an array into smaller arrays of a specified size.
+ * @param arr The array to chunk.
+ * @param size The chunk size.
+ * @returns An array of chunks.
+ */
+export declare function chunk<T>(arr: T[], size: number): T[][];
+/**
+ * Removes all falsy values from an array.
+ * @param arr The array.
+ * @returns A new array with only truthy values.
+ */
+export declare function compact<T>(arr: T[]): T[];
+/**
+ * Shuffles an array in place using the Fisher-Yates algorithm.
+ * @param arr The array to shuffle.
+ * @returns The shuffled array.
+ */
+export declare function shuffle<T>(arr: T[]): T[];
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/arrays/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,CAAC,GAAG,SAAS,CAEhD;AAED;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,CAAC,GAAG,SAAS,CAE/C;AAED;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,CAEvC;AAED;;;;GAIG;AAEH,wBAAgB,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,CAE1C;AAED;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,EAAE,EAAE,CAMtD;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,CAExC;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,CAOxC"}

package/dist/arrays/index.js

@@ -0,0 +1 @@
+import"../chunks/chunk-ANN5UYCF.js";function r(n){return n[0]}function u(n){return n.length?n[n.length-1]:void 0}function T(n){return Array.from(new Set(n))}function f(n){return n.flat()}function i(n,t){let e=[];for(let o=0;o<n.length;o+=t)e.push(n.slice(o,o+t));return e}function l(n){return n.filter(Boolean)}function c(n){let t=n.slice();for(let e=t.length-1;e>0;e--){let o=Math.floor(Math.random()*(e+1));[t[e],t[o]]=[t[o],t[e]]}return t}export{i as chunk,l as compact,r as first,f as flatten,u as last,c as shuffle,T as unique};

package/dist/boolean/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Converts a value to a boolean.
+ * Accepts 'true', '1', 1 as true; 'false', '0', 0 as false.
+ * @param value The value to convert.
+ * @returns The boolean representation.
+ */
+export declare function toBoolean(value: any): boolean;
+/**
+ * Checks if a value is a boolean.
+ * @param value The value to check.
+ * @returns True if the value is a boolean, false otherwise.
+ */
+export declare function isBoolean(value: any): value is boolean;
+/**
+ * Returns the logical exclusive OR (XOR) of two booleans.
+ * @param a First boolean.
+ * @param b Second boolean.
+ * @returns True if exactly one of a or b is true.
+ */
+export declare function xor(a: boolean, b: boolean): boolean;
+/**
+ * Logical AND for two booleans.
+ * @param a First boolean.
+ * @param b Second boolean.
+ * @returns True if both a and b are true.
+ */
+export declare function and(a: boolean, b: boolean): boolean;
+/**
+ * Logical OR for two booleans.
+ * @param a First boolean.
+ * @param b Second boolean.
+ * @returns True if either a or b is true.
+ */
+export declare function or(a: boolean, b: boolean): boolean;
+/**
+ * Logical NOT for a boolean.
+ * @param a The boolean to negate.
+ * @returns The negated boolean.
+ */
+export declare function not(a: boolean): boolean;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/boolean/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,wBAAgB,SAAS,CAAC,KAAK,EAAE,GAAG,GAAG,OAAO,CAW7C;AAED;;;;GAIG;AAEH,wBAAgB,SAAS,CAAC,KAAK,EAAE,GAAG,GAAG,KAAK,IAAI,OAAO,CAEtD;AAED;;;;;GAKG;AACH,wBAAgB,GAAG,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CAEnD;AAED;;;;;GAKG;AACH,wBAAgB,GAAG,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CAEnD;AAED;;;;;GAKG;AACH,wBAAgB,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CAElD;AAED;;;;GAIG;AACH,wBAAgB,GAAG,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAEvC"}

package/dist/boolean/index.js

@@ -0,0 +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};

package/dist/chunks/chunk-7MXMG6WN.js

@@ -0,0 +1 @@
+var R=["CAD","USD","AUD","EUR","GBP","JPY","CHF","CNY","NZD","SGD","SEK","NOK","DKK","MXN","HKD","KRW","TRY","RUB","INR","BRL","ZAR","ILS","MYR","PHP","PLN","THB","TWD","CZK","HUF","IDR","BGN","RON","HRK","BRL","COP","CRC","XCD","XDR","XAG","XAU","XPT","XPD","XTS","XXX"],D=R;export{R as a,D as b};

package/dist/chunks/chunk-ANN5UYCF.js

@@ -0,0 +1 @@
+var d=(a=>typeof require<"u"?require:typeof Proxy<"u"?new Proxy(a,{get:(b,c)=>(typeof require<"u"?require:b)[c]}):a)(function(a){if(typeof require<"u")return require.apply(this,arguments);throw Error('Dynamic require of "'+a+'" is not supported')});export{d as a};

package/dist/chunks/chunk-DCFILRIS.js

@@ -0,0 +1 @@
+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};