@rtorcato/js-common 2.0.0 → 2.1.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [2.1.0](https://github.com/rtorcato/js-common/compare/v2.0.1...v2.1.0) (2026-06-11)
+
+
+### Features
+
+* **docs:** full API reference via TypeDoc ([337eb2c](https://github.com/rtorcato/js-common/commit/337eb2c43122685a5fa8321865112800e67c404c))
+
+## [2.0.1](https://github.com/rtorcato/js-common/compare/v2.0.0...v2.0.1) (2026-06-10)
+
+
+### Bug Fixes
+
+* **build:** ship .d.ts files in published tarball ([946cd8a](https://github.com/rtorcato/js-common/commit/946cd8a27ba52923cbcf857d996f52590d9008d5))
+
 # [2.0.0](https://github.com/rtorcato/js-common/compare/v1.8.1...v2.0.0) (2026-06-01)
 
 

package/README.md

@@ -27,6 +27,30 @@ A comprehensive set of common JavaScript and TypeScript utilities for Node.js pr
 npm install @rtorcato/js-common
 ```
 
+## Migrating from 1.x to 2.x
+
+The only breaking change in 2.0 is a rename in the `errors` module:
+
+```ts
+// 1.x — swallow errors and fall back to a default value
+import { tryCatch } from '@rtorcato/js-common/errors'
+const data = await tryCatch(() => fetchData(), [])
+
+// 2.x — same function, renamed for clarity
+import { tryWithFallback } from '@rtorcato/js-common/errors'
+const data = await tryWithFallback(() => fetchData(), [])
+```
+
+The name `tryCatch` is now reserved for the Result-pattern helper in `@rtorcato/js-common/try`, which returns `{ data, error }` instead of swallowing:
+
+```ts
+import { tryCatch } from '@rtorcato/js-common/try'
+const { data, error } = await tryCatch(() => fetchData())
+if (error) { /* handle */ }
+```
+
+Prefer the Result-style `tryCatch` for new code; reserve `tryWithFallback` for cases where the fallback is genuinely safe.
+
 ## CLI Usage
 
 This package includes a command-line interface for many utilities:

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/arrays/index.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Returns the first element of an array, or undefined if the array is empty.
+ *
+ * @example
+ * ```typescript
+ * first([1, 2, 3]) // 1
+ * first([]) // undefined
+ * first(['a', 'b']) // 'a'
+ * ```
+ *
+ * @param arr The array to get the first element from
+ * @returns The first element or undefined if array is empty
+ * @category Array Utilities
+ */
+export declare function first<T>(arr: T[]): T | undefined;
+/**
+ * Returns the last element of an array, or undefined if the array is empty.
+ *
+ * @example
+ * ```typescript
+ * last([1, 2, 3]) // 3
+ * last([]) // undefined
+ * last(['a', 'b']) // 'b'
+ * ```
+ *
+ * @param arr The array to get the last element from
+ * @returns The last element or undefined if array is empty
+ * @category Array Utilities
+ */
+export declare function last<T>(arr: T[]): T | undefined;
+/**
+ * Removes duplicate values from an array while preserving order.
+ * Uses Set for O(n) performance with primitive values.
+ *
+ * @example
+ * ```typescript
+ * unique([1, 2, 2, 3, 1]) // [1, 2, 3]
+ * unique(['a', 'b', 'a']) // ['a', 'b']
+ * unique([{id: 1}, {id: 2}, {id: 1}]) // [{id: 1}, {id: 2}, {id: 1}] (objects by reference)
+ * ```
+ *
+ * @param arr The array to remove duplicates from
+ * @returns A new array with unique values
+ * @category Array Utilities
+ */
+export declare function unique<T>(arr: T[]): T[];
+/**
+ * Flattens an array one level deep.
+ *
+ * @example
+ * ```typescript
+ * flatten([[1, 2], [3, 4]]) // [1, 2, 3, 4]
+ * flatten([1, [2, 3], 4]) // [1, 2, 3, 4]
+ * flatten([[1, [2]], [3]]) // [1, [2], 3] (only one level deep)
+ * ```
+ *
+ * @param arr The array to flatten
+ * @returns A new flattened array
+ * @category Array Utilities
+ */
+export declare function flatten<T>(arr: readonly (T | T[])[]): T[];
+/**
+ * Chunks an array into smaller arrays of a specified size.
+ * The last chunk may be smaller if the array length is not evenly divisible.
+ *
+ * @example
+ * ```typescript
+ * chunk([1, 2, 3, 4, 5], 2) // [[1, 2], [3, 4], [5]]
+ * chunk(['a', 'b', 'c'], 2) // [['a', 'b'], ['c']]
+ * chunk([1, 2, 3], 5) // [[1, 2, 3]]
+ * ```
+ *
+ * @param arr The array to chunk
+ * @param size The size of each chunk (must be positive)
+ * @returns An array of chunks
+ * @throws {Error} When size is less than 1
+ * @category Array Utilities
+ */
+export declare function chunk<T>(arr: T[], size: number): T[][];
+/**
+ * Removes all falsy values from an array.
+ * Falsy values: false, 0, -0, 0n, "", null, undefined, NaN
+ *
+ * @example
+ * ```typescript
+ * compact([0, 1, false, 2, '', 3, null, undefined, NaN]) // [1, 2, 3]
+ * compact(['', 'hello', 0, 'world']) // ['hello', 'world']
+ * compact([true, false, 1, 0]) // [true, 1]
+ * ```
+ *
+ * @param arr The array to filter
+ * @returns A new array with only truthy values
+ * @category Array Utilities
+ */
+export declare function compact<T>(arr: T[]): T[];
+/**
+ * Shuffles an array using the Fisher-Yates algorithm.
+ * Returns a new array without modifying the original.
+ *
+ * @example
+ * ```typescript
+ * shuffle([1, 2, 3, 4, 5]) // [3, 1, 5, 2, 4] (random order)
+ * shuffle(['a', 'b', 'c']) // ['c', 'a', 'b'] (random order)
+ *
+ * // Original array is unchanged
+ * const original = [1, 2, 3]
+ * const shuffled = shuffle(original)
+ * console.log(original) // [1, 2, 3]
+ * ```
+ *
+ * @param arr The array to shuffle
+ * @returns A new shuffled array
+ * @category Array Utilities
+ */
+export declare function shuffle<T>(arr: T[]): T[];
+/**
+ * Groups array elements by a key derived from each element.
+ *
+ * @example
+ * ```typescript
+ * groupBy([1, 2, 3, 4], n => n % 2 === 0 ? 'even' : 'odd')
+ * // { odd: [1, 3], even: [2, 4] }
+ *
+ * groupBy([{ type: 'a' }, { type: 'b' }, { type: 'a' }], x => x.type)
+ * // { a: [{ type: 'a' }, { type: 'a' }], b: [{ type: 'b' }] }
+ * ```
+ *
+ * @param arr The array to group
+ * @param fn Function that returns the group key for each element
+ * @returns An object mapping keys to arrays of elements
+ * @category Array Utilities
+ */
+export declare function groupBy<T>(arr: T[], fn: (item: T) => string | number): Record<string | number, 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;;;;;;;;;;;;;GAaG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,CAAC,GAAG,SAAS,CAEhD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,CAAC,GAAG,SAAS,CAE/C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,CAEvC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,SAAS,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,CAEzD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,EAAE,EAAE,CAOtD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,CAExC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,CAOxC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,OAAO,CAAC,CAAC,EACxB,GAAG,EAAE,CAAC,EAAE,EACR,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,GAAG,MAAM,GAC9B,MAAM,CAAC,MAAM,GAAG,MAAM,EAAE,CAAC,EAAE,CAAC,CAO9B"}

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: unknown): 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: unknown): 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,OAAO,GAAG,OAAO,CAWjD;AAED;;;;GAIG;AAEH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,OAAO,CAE1D;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/colors/index.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Generates a random hex color string.
+ *
+ * @returns {string} A string representing a random color in hexadecimal format (e.g., `#a1b2c3`).
+ */
+export declare function randomColor(): string;
+/**
+ * Generates a random color with a given alpha value.
+ *
+ * @export
+ * @param {string} color
+ * @return {*}
+ */
+export declare function matchingTextColor(color: string): "#000" | "#fff";
+/**
+ * Converts a hex color string to an RGB object.
+ *
+ * @export
+ * @param {string} hex
+ * @return {*}  {({ r: number; g: number; b: number } | null)}
+ */
+export declare function hexToRgb(hex: string): {
+    r: number;
+    g: number;
+    b: number;
+} | null;
+/**
+ * Converts RGB values to a hex color string.
+ *
+ * @export
+ * @param {number} r
+ * @param {number} g
+ * @param {number} b
+ * @return {*}  {string}
+ */
+export declare function rgbToHex(r: number, g: number, b: number): string;
+/**
+ * Converts a hex color string to an HSL object.
+ *
+ * @export
+ * @param {string} hex
+ * @return {*}  {({ h: number; s: number; l: number } | null)}
+ */
+export declare function isValidHex(hex: string): boolean;
+/**
+ * Darkens a hex color by a given percentage.
+ *
+ * @export
+ * @param {string} hex
+ * @param {number} percent
+ * @return {*}  {string}
+ */
+export declare function darken(hex: string, percent: number): string;
+/**
+ * Lightens a hex color by a given percentage.
+ *
+ * @export
+ * @param {string} hex
+ * @param {number} percent
+ * @return {*}  {string}
+ */
+export declare function lighten(hex: string, percent: number): string;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/colors/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAKpC;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,mBAO9C;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAQhF;AAED;;;;;;;;GAQG;AAEH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAOhE;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE/C;AAED;;;;;;;GAOG;AACH,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAO3D;AAED;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAO5D"}

package/dist/console/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @fileoverview Console utility functions for logging and disabling console output in production.
+ * @module console
+ */
+/**
+ * Disables console output in production environment.
+ */
+export declare const disableConsole: () => void;
+/**
+ * Clears the console.
+ *
+ * @export
+ * @return {*}  {void}
+ */
+export declare const clearConsole: () => void;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/console/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,eAAO,MAAM,cAAc,YAK1B,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,YAAY,QAAO,IAE/B,CAAA"}

package/dist/crypto/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Hashes a string using the specified algorithm.
+ * @param str The string to hash.
+ * @param algorithm The hash algorithm (default: 'sha256').
+ * @returns The hex-encoded hash.
+ */
+export declare function hashString(str: string, algorithm?: string): string;
+/**
+ * Generates a random hex string of the specified length (in bytes).
+ * @param length The number of bytes (not hex chars).
+ * @returns A random hex string.
+ */
+export declare function randomHex(length?: number): string;
+/**
+ * Creates an HMAC hash of a string using a secret and algorithm.
+ * @param str The string to hash.
+ * @param secret The secret key.
+ * @param algorithm The hash algorithm (default: 'sha256').
+ * @returns The hex-encoded HMAC.
+ */
+export declare function hmacHash(str: string, secret: string, algorithm?: string): string;
+/**
+ * Encodes a string to base64.
+ * @param str The string to encode.
+ * @returns The base64-encoded string.
+ */
+export declare function base64Encode(str: string): string;
+/**
+ * Decodes a base64 string.
+ * @param b64 The base64 string to decode.
+ * @returns The decoded string.
+ */
+export declare function base64Decode(b64: string): string;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/crypto/index.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,SAAW,GAAG,MAAM,CAEpE;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,MAAM,SAAK,GAAG,MAAM,CAE7C;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,SAAW,GAAG,MAAM,CAElF;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEhD"}

package/dist/currency/currencies.d.ts

@@ -0,0 +1,16 @@
+/**
+ * List of supported currency codes.
+ *
+ * This array contains ISO 4217 currency codes and some special codes
+ * (such as precious metals and testing codes) used in financial applications.
+ *
+ * @remarks
+ * - Some codes represent fiat currencies (e.g., 'USD', 'EUR').
+ * - Some codes represent precious metals (e.g., 'XAU' for gold).
+ * - Some codes are reserved for testing or special purposes (e.g., 'XTS', 'XXX').
+ *
+ * @see {@link https://www.iso.org/iso-4217-currency-codes.html ISO 4217 Currency Codes}
+ */
+export declare const currencies: string[];
+export default currencies;
+//# sourceMappingURL=currencies.d.ts.map

package/dist/currency/currencies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"currencies.d.ts","sourceRoot":"","sources":["../../src/currency/currencies.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,UAAU,UA4CtB,CAAA;AAED,eAAe,UAAU,CAAA"}

package/dist/currency/index.d.ts

@@ -0,0 +1,170 @@
+/**
+ * Returns the currency symbol for a given ISO 4217 currency code.
+ *
+ * Utilizes the `Intl.NumberFormat` API to format a number as currency and extract the symbol.
+ *
+ * @param currency - The ISO 4217 currency code (e.g., 'USD', 'EUR', 'JPY').
+ * @returns The currency symbol as a string (e.g., '$', '€', '¥'), or `undefined` if the symbol cannot be determined.
+ *
+ * @example
+ * ```typescript
+ * getCurrencySymbol('USD') // '$'
+ * getCurrencySymbol('EUR') // '€'
+ * getCurrencySymbol('JPY') // '¥'
+ * ```
+ */
+export declare const getCurrencySymbol: (currency: string) => string | undefined;
+/**
+ * Returns the full display name of a currency.
+ *
+ * @param currency - The ISO 4217 currency code (e.g., 'USD', 'EUR').
+ * @param locale - The locale to use for the display name. Defaults to 'en'.
+ * @returns The full currency name (e.g., 'US Dollar'), or `undefined` if invalid.
+ *
+ * @example
+ * ```typescript
+ * getCurrencyName('USD') // 'US Dollar'
+ * getCurrencyName('EUR') // 'Euro'
+ * getCurrencyName('JPY', 'ja') // '日本円'
+ * ```
+ */
+export declare function getCurrencyName(currency: string, locale?: string): string | undefined;
+/**
+ * Returns the default locale typically associated with a currency.
+ *
+ * @param currency - The ISO 4217 currency code.
+ * @returns The locale string (e.g., 'en-US' for USD), or 'en' as fallback.
+ *
+ * @example
+ * ```typescript
+ * getCurrencyLocale('USD') // 'en-US'
+ * getCurrencyLocale('EUR') // 'de-DE'
+ * getCurrencyLocale('JPY') // 'ja-JP'
+ * ```
+ */
+export declare function getCurrencyLocale(currency: string): string;
+/**
+ * Formats a given price value into a localized currency string.
+ *
+ * @param price - The numeric value or string representation of the price to format.
+ * @param currency - The ISO 4217 currency code. Defaults to 'USD'.
+ * @param locale - The locale to use for formatting. If not provided, uses the currency's default locale.
+ * @returns The formatted currency string.
+ *
+ * @example
+ * ```typescript
+ * formatPrice(1234.56, 'USD') // '$1,234.56'
+ * formatPrice(1234.56, 'EUR') // '1.234,56 €'
+ * formatPrice(1234.56, 'JPY') // '¥1,235'
+ * ```
+ */
+export declare function formatPrice(price: number | string, currency?: string, locale?: string): string;
+/**
+ * Formats a price in compact notation (e.g., $1.2K, $1.5M).
+ *
+ * @param price - The numeric value to format.
+ * @param currency - The ISO 4217 currency code. Defaults to 'USD'.
+ * @param locale - The locale to use for formatting.
+ * @returns The formatted compact currency string.
+ *
+ * @example
+ * ```typescript
+ * formatPriceCompact(1234) // '$1.2K'
+ * formatPriceCompact(1234567) // '$1.2M'
+ * formatPriceCompact(1234567890) // '$1.2B'
+ * formatPriceCompact(1500, 'EUR') // '1,5 Tsd. €'
+ * ```
+ */
+export declare function formatPriceCompact(price: number | string, currency?: string, locale?: string): string;
+/**
+ * Parses a given price string and returns its numeric value.
+ *
+ * @param value - The price string to parse.
+ * @returns The numeric value of the price, or `null` if the value cannot be parsed.
+ *
+ * @example
+ * ```typescript
+ * parsePrice('$1,234.56') // 1234.56
+ * parsePrice('€1.234,56') // 1234.56
+ * parsePrice('invalid') // null
+ * ```
+ */
+export declare function parsePrice(value: string): number | null;
+/**
+ * Parses a currency string and extracts both the amount and currency code.
+ *
+ * @param value - The currency string to parse (e.g., '$1,234.56', 'EUR 100').
+ * @returns An object with `amount` and `currency`, or `null` if parsing fails.
+ *
+ * @example
+ * ```typescript
+ * parseCurrencyString('$1,234.56') // { amount: 1234.56, currency: 'USD' }
+ * parseCurrencyString('€100') // { amount: 100, currency: 'EUR' }
+ * parseCurrencyString('1000 JPY') // { amount: 1000, currency: 'JPY' }
+ * parseCurrencyString('invalid') // null
+ * ```
+ */
+export declare function parseCurrencyString(value: string): {
+    amount: number;
+    currency: string;
+} | null;
+/**
+ * Converts a given amount from one currency to another using the provided exchange rate.
+ *
+ * @param amount - The amount of money to convert.
+ * @param rate - The exchange rate to use for the conversion.
+ * @param decimals - The number of decimal places to include in the result. Defaults to 2.
+ * @returns The converted amount as a number.
+ *
+ * @example
+ * ```typescript
+ * convertCurrency(100, 0.85) // 85 (e.g., USD to EUR)
+ * convertCurrency(100, 110.5, 0) // 11050 (e.g., USD to JPY)
+ * ```
+ */
+export declare function convertCurrency(amount: number, rate: number, decimals?: number): number;
+/**
+ * Checks if the provided currency code is valid.
+ *
+ * This function lazily loads the currencies list to minimize bundle size impact.
+ *
+ * @param code - The currency code to validate (e.g., 'USD', 'eur').
+ * @returns Promise resolving to `true` if the currency code is valid; otherwise, `false`.
+ *
+ * @example
+ * ```typescript
+ * await isValidCurrencyCode('USD') // true
+ * await isValidCurrencyCode('INVALID') // false
+ * ```
+ */
+export declare function isValidCurrencyCode(code: string): Promise<boolean>;
+/**
+ * Synchronously checks if a currency code is valid using the Intl API.
+ *
+ * This does not require loading the currencies list and has zero bundle size impact.
+ *
+ * @param code - The currency code to validate.
+ * @returns `true` if the currency code is valid; otherwise, `false`.
+ *
+ * @example
+ * ```typescript
+ * isValidCurrency('USD') // true
+ * isValidCurrency('INVALID') // false
+ * ```
+ */
+export declare function isValidCurrency(code: string): boolean;
+/**
+ * Rounds a given number to a specified number of decimal places.
+ *
+ * @param value - The number to be rounded.
+ * @param decimals - The number of decimal places to round to. Defaults to 2.
+ * @returns The rounded number.
+ *
+ * @example
+ * ```typescript
+ * roundTo(3.14159, 2) // 3.14
+ * roundTo(10.5, 0) // 11
+ * ```
+ */
+export declare function roundTo(value: number, decimals?: number): number;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/currency/index.ts"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,iBAAiB,GAAI,UAAU,MAAM,KAAG,MAAM,GAAG,SAY7D,CAAA;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,SAAO,GAAG,MAAM,GAAG,SAAS,CAMnF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAkC1D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,QAAQ,SAAQ,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAM7F;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CACjC,KAAK,EAAE,MAAM,GAAG,MAAM,EACtB,QAAQ,SAAQ,EAChB,MAAM,CAAC,EAAE,MAAM,GACb,MAAM,CAQR;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAavD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CA2C9F;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,SAAI,GAAG,MAAM,CAElF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAGxE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAOrD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,SAAI,GAAG,MAAM,CAG3D"}

package/dist/date/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Returns today's date as a YYYY-MM-DD string.
+ * @returns {string}
+ */
+export declare function today(): string;
+/**
+ * Returns a Date object from a YYYY-MM-DD string.
+ * @param dateStr The date string.
+ * @returns {Date}
+ */
+export declare function parseDate(dateStr: string): Date;
+/**
+ * Formats a Date object as YYYY-MM-DD.
+ * @param date The Date object.
+ * @returns {string}
+ */
+export declare function formatDate(date: Date): string;
+/**
+ * Returns the difference in days between two dates (date2 - date1).
+ * @param date1 The first date (string or Date).
+ * @param date2 The second date (string or Date).
+ * @returns {number}
+ */
+export declare function daysBetween(date1: string | Date, date2: string | Date): number;
+/**
+ * Checks if a year is a leap year.
+ * @param year The year (number or Date).
+ * @returns {boolean}
+ */
+export declare function isLeapYear(year: number | Date): boolean;
+/**
+ * Adds days to a date and returns a new Date object.
+ * @param date The date (string or Date).
+ * @param days Number of days to add.
+ * @returns {Date}
+ */
+export declare function addDays(date: string | Date, days: number): Date;
+/**
+ * Returns the day of the week for a date (0=Sunday, 6=Saturday).
+ * @param date The date (string or Date).
+ * @returns {number}
+ */
+export declare function getDayOfWeek(date: string | Date): number;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/date/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,KAAK,IAAI,MAAM,CAG9B;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE/C;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAE7C;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAI9E;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAGvD;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAI/D;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAGxD"}