@rtorcato/js-common 2.8.2 → 4.0.0

package/dist/crypto/index.d.ts

@@ -1,5 +1,13 @@
 /**
  * Hashes a string using the specified algorithm.
+ *
+ * @example
+ * ```typescript
+ * hashString('hello')
+ * // '2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824'
+ * hashString('hello', 'md5') // '5d41402abc4b2a76b9719d911017c592'
+ * ```
+ *
  * @param str The string to hash.
  * @param algorithm The hash algorithm (default: 'sha256').
  * @returns The hex-encoded hash.
@@ -7,12 +15,27 @@
 export declare function hashString(str: string, algorithm?: string): string;
 /**
  * Generates a random hex string of the specified length (in bytes).
+ *
+ * @example
+ * ```typescript
+ * randomHex(4) // '9f3c1ab7' (8 hex chars)
+ * randomHex() // 32 hex chars (16 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.
+ *
+ * @example
+ * ```typescript
+ * hmacHash('payload', 's3cret')
+ * // 'd1d0f5b6...' (64 hex chars, stable for the same input + secret)
+ * hmacHash('payload', 's3cret', 'sha1') // 40 hex chars
+ * ```
+ *
  * @param str The string to hash.
  * @param secret The secret key.
  * @param algorithm The hash algorithm (default: 'sha256').

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

@@ -1 +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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/crypto/index.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,SAAW,GAAG,MAAM,CAEpE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,MAAM,SAAK,GAAG,MAAM,CAE7C;AAED;;;;;;;;;;;;;;GAcG;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

@@ -11,6 +11,6 @@
  *
  * @see {@link https://www.iso.org/iso-4217-currency-codes.html ISO 4217 Currency Codes}
  */
-export declare const currencies: string[];
+declare const currencies: string[];
 export default currencies;
 //# sourceMappingURL=currencies.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"currencies.d.ts","sourceRoot":"","sources":["../../src/currency/currencies.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,QAAA,MAAM,UAAU,UA4Cf,CAAA;AAED,eAAe,UAAU,CAAA"}

package/dist/currency/currencies.js

@@ -1 +1 @@
-import"../chunks/chunk-ANN5UYCF.js";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","COP","CRC","XCD","XDR","XAG","XAU","XPT","XPD","XTS","XXX"],D=R;export{R as currencies,D as default};
+import"../chunks/chunk-ANN5UYCF.js";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","COP","CRC","XCD","XDR","XAG","XAU","XPT","XPD","XTS","XXX"],D=R;export{D as default};

package/dist/currency/index.d.ts

@@ -153,18 +153,4 @@ export declare function isValidCurrencyCode(code: string): Promise<boolean>;
  * ```
  */
 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

@@ -1 +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"}
+{"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,CAevD;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"}

package/dist/currency/index.js

@@ -1 +1 @@
-import"../chunks/chunk-ANN5UYCF.js";var o=null;async function a(){if(o)return o;let{default:r}=await import("./currencies.js");return o=r,r}var l=r=>{try{let n=new Intl.NumberFormat("en",{currency:r,style:"currency"}).formatToParts(0).find(e=>e.type==="currency");return n?.value==="\xA4"?void 0:n?.value}catch{return}};function m(r,n="en"){try{return new Intl.DisplayNames([n],{type:"currency"}).of(r.toUpperCase())}catch{return}}function i(r){return{USD:"en-US",EUR:"de-DE",GBP:"en-GB",JPY:"ja-JP",CNY:"zh-CN",CAD:"en-CA",AUD:"en-AU",CHF:"de-CH",NZD:"en-NZ",SGD:"en-SG",HKD:"zh-HK",KRW:"ko-KR",INR:"en-IN",BRL:"pt-BR",MXN:"es-MX",RUB:"ru-RU",ZAR:"en-ZA",SEK:"sv-SE",NOK:"nb-NO",DKK:"da-DK",PLN:"pl-PL",TRY:"tr-TR",THB:"th-TH",MYR:"ms-MY",PHP:"en-PH",IDR:"id-ID",CZK:"cs-CZ",HUF:"hu-HU",ILS:"he-IL",TWD:"zh-TW"}[r.toUpperCase()]??"en"}function p(r,n="USD",e){let t=e??i(n);return new Intl.NumberFormat(t,{style:"currency",currency:n}).format(Number(r))}function d(r,n="USD",e){let t=e??i(n);return new Intl.NumberFormat(t,{style:"currency",currency:n,notation:"compact",compactDisplay:"short"}).format(Number(r))}function s(r){let n=/\d+\.\d{3},\d{2}$/.test(r),e=r;n&&(e=r.replace(/\./g,"").replace(",","."));let t=e.replace(/[^0-9.-]+/g,""),c=Number.parseFloat(t);return Number.isNaN(c)?null:c}function f(r){let n={$:"USD","\u20AC":"EUR","\xA3":"GBP","\xA5":"JPY","\u20B9":"INR","\u20BD":"RUB",R$:"BRL","\u20A9":"KRW","\u0E3F":"THB","\u20AA":"ILS","\u20B1":"PHP","\u20AB":"VND",kr:"SEK",CHF:"CHF",C$:"CAD",A$:"AUD",NZ$:"NZD",HK$:"HKD",S$:"SGD"},e=r.match(/\b([A-Z]{3})\b/);if(e?.[1]){let t=s(r);if(t!==null)return{amount:t,currency:e[1]}}for(let[t,c]of Object.entries(n))if(r.includes(t)){let u=s(r);if(u!==null)return{amount:u,currency:c}}return null}function y(r,n,e=2){return Number.parseFloat((r*n).toFixed(e))}async function g(r){return(await a()).includes(r.toUpperCase())}function b(r){try{return new Intl.NumberFormat("en",{style:"currency",currency:r}),!0}catch{return!1}}function C(r,n=2){let e=10**n;return Math.round(r*e)/e}export{y as convertCurrency,p as formatPrice,d as formatPriceCompact,i as getCurrencyLocale,m as getCurrencyName,l as getCurrencySymbol,b as isValidCurrency,g as isValidCurrencyCode,f as parseCurrencyString,s as parsePrice,C as roundTo};
+import"../chunks/chunk-ANN5UYCF.js";var o=null;async function a(){if(o)return o;let{default:r}=await import("./currencies.js");return o=r,r}var l=r=>{try{let e=new Intl.NumberFormat("en",{currency:r,style:"currency"}).formatToParts(0).find(n=>n.type==="currency");return e?.value==="\xA4"?void 0:e?.value}catch{return}};function m(r,e="en"){try{return new Intl.DisplayNames([e],{type:"currency"}).of(r.toUpperCase())}catch{return}}function i(r){return{USD:"en-US",EUR:"de-DE",GBP:"en-GB",JPY:"ja-JP",CNY:"zh-CN",CAD:"en-CA",AUD:"en-AU",CHF:"de-CH",NZD:"en-NZ",SGD:"en-SG",HKD:"zh-HK",KRW:"ko-KR",INR:"en-IN",BRL:"pt-BR",MXN:"es-MX",RUB:"ru-RU",ZAR:"en-ZA",SEK:"sv-SE",NOK:"nb-NO",DKK:"da-DK",PLN:"pl-PL",TRY:"tr-TR",THB:"th-TH",MYR:"ms-MY",PHP:"en-PH",IDR:"id-ID",CZK:"cs-CZ",HUF:"hu-HU",ILS:"he-IL",TWD:"zh-TW"}[r.toUpperCase()]??"en"}function p(r,e="USD",n){let t=n??i(e);return new Intl.NumberFormat(t,{style:"currency",currency:e}).format(Number(r))}function y(r,e="USD",n){let t=n??i(e);return new Intl.NumberFormat(t,{style:"currency",currency:e,notation:"compact",compactDisplay:"short"}).format(Number(r))}function s(r){let e=/\d\.\d{3},\d{2}$/.test(r),n=r;e&&(n=r.replace(/\./g,"").replace(",","."));let t=n.replace(/[^0-9.-]+/g,""),c=Number.parseFloat(t);return Number.isNaN(c)?null:c}function d(r){let e={$:"USD","\u20AC":"EUR","\xA3":"GBP","\xA5":"JPY","\u20B9":"INR","\u20BD":"RUB",R$:"BRL","\u20A9":"KRW","\u0E3F":"THB","\u20AA":"ILS","\u20B1":"PHP","\u20AB":"VND",kr:"SEK",CHF:"CHF",C$:"CAD",A$:"AUD",NZ$:"NZD",HK$:"HKD",S$:"SGD"},n=r.match(/\b([A-Z]{3})\b/);if(n?.[1]){let t=s(r);if(t!==null)return{amount:t,currency:n[1]}}for(let[t,c]of Object.entries(e))if(r.includes(t)){let u=s(r);if(u!==null)return{amount:u,currency:c}}return null}function f(r,e,n=2){return Number.parseFloat((r*e).toFixed(n))}async function g(r){return(await a()).includes(r.toUpperCase())}function C(r){try{return new Intl.NumberFormat("en",{style:"currency",currency:r}),!0}catch{return!1}}export{f as convertCurrency,p as formatPrice,y as formatPriceCompact,i as getCurrencyLocale,m as getCurrencyName,l as getCurrencySymbol,C as isValidCurrency,g as isValidCurrencyCode,d as parseCurrencyString,s as parsePrice};

package/dist/date/index.d.ts

@@ -1,13 +1,29 @@
 /**
  * Returns today's date as a YYYY-MM-DD string.
+ *
+ * @example
+ * ```typescript
+ * today() // '2026-08-11'
+ * ```
  */
 export declare function today(): string;
 /**
  * Returns a Date object from a YYYY-MM-DD string (parsed as local time).
+ *
+ * @example
+ * ```typescript
+ * parseDate('2026-08-11') // Date for 2026-08-11 00:00:00 local time
+ * parseDate('2026-08-11').getFullYear() // 2026
+ * ```
  */
 export declare function parseDate(dateStr: string): Date;
 /**
  * Formats a Date object as YYYY-MM-DD (UTC).
+ *
+ * @example
+ * ```typescript
+ * formatDate(new Date('2026-08-11T23:30:00Z')) // '2026-08-11'
+ * ```
  */
 export declare function formatDate(date: Date): string;
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/date/index.ts"],"names":[],"mappings":"AASA;;GAEG;AACH,wBAAgB,KAAK,IAAI,MAAM,CAE9B;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE/C;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAE7C;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAE9E;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAE9E;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAEhF;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAGvD;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAI/D;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAE/D;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAInE;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAExD;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAIpD;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAIlD;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAGtD;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAQ7E;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAEpD;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,GAAG,GAAE,IAAiB,GAAG,MAAM,CAQlF"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/date/index.ts"],"names":[],"mappings":"AASA;;;;;;;GAOG;AACH,wBAAgB,KAAK,IAAI,MAAM,CAE9B;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE/C;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAE7C;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAE9E;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAE9E;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAEhF;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAGvD;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAI/D;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAE/D;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAInE;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAExD;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAIpD;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAIlD;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAGtD;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAQ7E;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAEpD;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,GAAG,GAAE,IAAiB,GAAG,MAAM,CAQlF"}

package/dist/datetime/index.d.ts

@@ -1,19 +1,37 @@
 /**
- * Returns the current date and time as an ISO string (YYYY-MM-DDTHH:mm:ss.sssZ).
+ * Returns the current date and time as an ISO string (`YYYY-MM-DDTHH:mm:ss.sssZ`).
+ *
+ * @example
+ * ```typescript
+ * nowIso() // '2026-08-11T14:03:27.913Z'
+ * ```
  */
 export declare function nowIso(): string;
 /**
  * Parses an ISO date-time string to a Date object. Returns null if invalid.
+ *
+ * @example
+ * ```typescript
+ * parseIsoDateTime('2026-08-11T14:03:27Z')?.getUTCHours() // 14
+ * parseIsoDateTime('not-a-date') // null
+ * ```
+ *
  * @param iso The ISO string.
  */
 export declare function parseIsoDateTime(iso: string): Date | null;
 /**
- * Formats a Date as YYYY-MM-DD HH:mm:ss (local time).
+ * Formats a Date as `YYYY-MM-DD HH:mm:ss` (local time).
+ *
+ * @example
+ * ```typescript
+ * formatDateTimeLocal(new Date(2026, 7, 11, 9, 5, 3)) // '2026-08-11 09:05:03'
+ * ```
+ *
  * @param date The Date object.
  */
 export declare function formatDateTimeLocal(date: Date): string;
 /**
- * Returns the timezone offset in minutes for a given date (local - UTC).
+ * Returns the timezone offset in minutes for a given date (local − UTC).
  * @param date The Date object.
  */
 export declare function getTimezoneOffset(date?: Date): number;
@@ -30,12 +48,6 @@ export declare function unixTimestamp(): number;
  * Returns the number of milliseconds since the Unix epoch.
  */
 export declare function unixMillis(): number;
-/**
- * Returns the difference in seconds between two Date objects.
- * @param a First date.
- * @param b Second date.
- */
-export declare function secondsBetween(a: Date, b: Date): number;
 /**
  * Returns the ISO week number (1–53) of a given date using UTC.
  * @param date A JavaScript Date object.

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/datetime/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,wBAAgB,MAAM,IAAI,MAAM,CAE/B;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAGzD;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAMtD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,GAAE,IAAiB,GAAG,MAAM,CAEjE;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAY1C;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED;;GAEG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,GAAG,MAAM,CAEvD;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAoB7C;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAmBzE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/datetime/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,wBAAgB,MAAM,IAAI,MAAM,CAE/B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAGzD;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAMtD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,GAAE,IAAiB,GAAG,MAAM,CAEjE;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAY1C;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED;;GAEG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAoB7C;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAmBzE"}

package/dist/datetime/index.js

@@ -1 +1 @@
-import"../chunks/chunk-ANN5UYCF.js";function i(){return new Date().toISOString()}function c(e){let t=new Date(e);return Number.isNaN(t.getTime())?null:t}function T(e){let t=n=>n.toString().padStart(2,"0");return`${e.getFullYear()}-${t(e.getMonth()+1)}-${t(e.getDate())} ${t(e.getHours())}:${t(e.getMinutes())}:${t(e.getSeconds())}`}function l(e=new Date){return e.getTimezoneOffset()}function f(e){return new Date(Date.UTC(e.getFullYear(),e.getMonth(),e.getDate(),e.getHours(),e.getMinutes(),e.getSeconds(),e.getMilliseconds()))}function m(){return Math.floor(Date.now()/1e3)}function w(){return Date.now()}function U(e,t){return Math.floor((t.getTime()-e.getTime())/1e3)}function C(e){let t=new Date(Date.UTC(e.getFullYear(),e.getMonth(),e.getDate())),n=t.getUTCDay(),s=n===0?7:n;t.setUTCDate(t.getUTCDate()+4-s);let o=new Date(Date.UTC(t.getUTCFullYear(),0,1)).getUTCDay(),a=o===0?7:o,D=new Date(Date.UTC(t.getUTCFullYear(),0,1+(4-a))),u=t.getTime()-D.getTime();return 1+Math.round(u/(10080*60*1e3))}function y(e){let t=new Date(Date.UTC(e.getFullYear(),e.getMonth(),e.getDate()));t.setUTCDate(t.getUTCDate()+4-(t.getUTCDay()||7));let n=t.getUTCFullYear(),r=new Date(Date.UTC(n,0,1)).getUTCDay()||7,o=new Date(Date.UTC(n,0,1-r+1+(r>4?7:0))),a=t.getTime()-o.getTime();return{week:Math.floor(a/(10080*60*1e3))+1,year:n}}export{T as formatDateTimeLocal,C as getIsoWeek,y as getIsoWeekInfo,l as getTimezoneOffset,i as nowIso,c as parseIsoDateTime,U as secondsBetween,f as toUtcDate,w as unixMillis,m as unixTimestamp};
+import"../chunks/chunk-ANN5UYCF.js";function i(){return new Date().toISOString()}function c(e){let t=new Date(e);return Number.isNaN(t.getTime())?null:t}function T(e){let t=n=>n.toString().padStart(2,"0");return`${e.getFullYear()}-${t(e.getMonth()+1)}-${t(e.getDate())} ${t(e.getHours())}:${t(e.getMinutes())}:${t(e.getSeconds())}`}function l(e=new Date){return e.getTimezoneOffset()}function f(e){return new Date(Date.UTC(e.getFullYear(),e.getMonth(),e.getDate(),e.getHours(),e.getMinutes(),e.getSeconds(),e.getMilliseconds()))}function m(){return Math.floor(Date.now()/1e3)}function U(){return Date.now()}function w(e){let t=new Date(Date.UTC(e.getFullYear(),e.getMonth(),e.getDate())),n=t.getUTCDay(),s=n===0?7:n;t.setUTCDate(t.getUTCDate()+4-s);let o=new Date(Date.UTC(t.getUTCFullYear(),0,1)).getUTCDay(),a=o===0?7:o,D=new Date(Date.UTC(t.getUTCFullYear(),0,1+(4-a))),u=t.getTime()-D.getTime();return 1+Math.round(u/(10080*60*1e3))}function C(e){let t=new Date(Date.UTC(e.getFullYear(),e.getMonth(),e.getDate()));t.setUTCDate(t.getUTCDate()+4-(t.getUTCDay()||7));let n=t.getUTCFullYear(),r=new Date(Date.UTC(n,0,1)).getUTCDay()||7,o=new Date(Date.UTC(n,0,1-r+1+(r>4?7:0))),a=t.getTime()-o.getTime();return{week:Math.floor(a/(10080*60*1e3))+1,year:n}}export{T as formatDateTimeLocal,w as getIsoWeek,C as getIsoWeekInfo,l as getTimezoneOffset,i as nowIso,c as parseIsoDateTime,f as toUtcDate,U as unixMillis,m as unixTimestamp};

package/dist/emails/index.d.ts

@@ -1,17 +1,39 @@
 /**
  * Validates if a string is a valid email address (simple regex).
+ *
+ * @example
+ * ```typescript
+ * isValidEmail('user@example.com') // true
+ * isValidEmail('user@example') // false
+ * isValidEmail('not an email') // false
+ * ```
+ *
  * @param email The email address to validate.
  * @returns True if valid, false otherwise.
  */
 export declare function isValidEmail(email: string): boolean;
 /**
  * Normalizes an email address by trimming and converting to lowercase.
+ *
+ * @example
+ * ```typescript
+ * normalizeEmail('  User@Example.COM ') // 'user@example.com'
+ * ```
+ *
  * @param email The email address to normalize.
  * @returns The normalized email address.
  */
 export declare function normalizeEmail(email: string): string;
 /**
  * Masks an email address for privacy (e.g., j***@domain.com).
+ *
+ * @example
+ * ```typescript
+ * maskEmail('jane@example.com') // 'j***@example.com'
+ * maskEmail('a@example.com') // '*@example.com'
+ * maskEmail('nope') // 'nope'
+ * ```
+ *
  * @param email The email address to mask.
  * @returns The masked email address.
  */

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/emails/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAK/C;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGpD;AAaD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE1D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/emails/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAInD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAK/C;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGpD;AAaD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE1D"}

package/dist/emails/index.js

@@ -1 +1 @@
-import"../chunks/chunk-ANN5UYCF.js";function e(t){return/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(t)}function s(t){return t.trim().toLowerCase()}function a(t){let[o,r]=t.split("@");return!o||!r?t:o.length<=1?`*@${r}`:`${o[0]}${"*".repeat(Math.max(1,o.length-1))}@${r}`}function n(t){let o=t.split("@");return o.length===2?o[1]??"":""}var i=["gmail.com","yahoo.com","outlook.com","hotmail.com","icloud.com","aol.com","zoho.com","mail.com"];function m(t){return i.includes(n(t))}export{n as getEmailDomain,m as isFreeEmailProvider,e as isValidEmail,a as maskEmail,s as normalizeEmail};
+import"../chunks/chunk-ANN5UYCF.js";function e(t){return/^[^\s@]+@[^\s@.]+(?:\.[^\s@.]+)+$/.test(t)}function s(t){return t.trim().toLowerCase()}function a(t){let[o,r]=t.split("@");return!o||!r?t:o.length<=1?`*@${r}`:`${o[0]}${"*".repeat(Math.max(1,o.length-1))}@${r}`}function n(t){let o=t.split("@");return o.length===2?o[1]??"":""}var i=["gmail.com","yahoo.com","outlook.com","hotmail.com","icloud.com","aol.com","zoho.com","mail.com"];function m(t){return i.includes(n(t))}export{n as getEmailDomain,m as isFreeEmailProvider,e as isValidEmail,a as maskEmail,s as normalizeEmail};

package/dist/env/index.d.ts

@@ -2,6 +2,14 @@ import { z } from 'zod';
 /**
  * Retrieves the value of an environment variable by its key.
  *
+ * @example
+ * ```typescript
+ * process.env.API_URL = 'https://api.example.com'
+ * getENV('API_URL') // 'https://api.example.com'
+ * getENV('MISSING', 'fallback') // 'fallback'
+ * getENV('MISSING') // throws Error: Undefined ENV variable - MISSING
+ * ```
+ *
  * @param key - The name of the environment variable to retrieve.
  * @param defaultValue - An optional default value to return if the environment variable is not defined.
  * @returns The value of the environment variable if it exists, otherwise the default value if provided.
@@ -11,12 +19,28 @@ export declare const getENV: (key: string, defaultValue?: string) => string;
 /**
  * Determines if the current environment is set to development.
  *
+ * @example
+ * ```typescript
+ * process.env.NODE_ENV = 'development'
+ * isDev() // true
+ * process.env.NODE_ENV = 'production'
+ * isDev() // false
+ * ```
+ *
  * @returns {boolean} `true` if `process.env.NODE_ENV` is `'development'`, otherwise `false`.
  */
 export declare const isDev: () => boolean;
 /**
  * Determines if the current environment is set to production.
  *
+ * @example
+ * ```typescript
+ * process.env.NODE_ENV = 'production'
+ * isProd() // true
+ * process.env.NODE_ENV = 'test'
+ * isProd() // false
+ * ```
+ *
  * @returns {boolean} `true` if `process.env.NODE_ENV` is `'production'`, otherwise `false`.
  */
 export declare const isProd: () => boolean;

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/env/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB;;;;;;;GAOG;AACH,eAAO,MAAM,MAAM,GAAI,KAAK,MAAM,EAAE,eAAe,MAAM,WAUxD,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,KAAK,QAAO,OAExB,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,MAAM,QAAO,OAEzB,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,MAAM,QAAO,OAEzB,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,UAAU,QAAO,MAE7B,CAAA;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,CAAC,CAAC,WAAW,EAC/C,SAAS,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EACzB,QAAQ,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,oCAc1D;AAED;;;GAGG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;iBAI3B,CAAA;AAEF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/env/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,MAAM,GAAI,KAAK,MAAM,EAAE,eAAe,MAAM,WAUxD,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,KAAK,QAAO,OAExB,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,MAAM,QAAO,OAEzB,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,MAAM,QAAO,OAEzB,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,UAAU,QAAO,MAE7B,CAAA;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,CAAC,CAAC,WAAW,EAC/C,SAAS,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EACzB,QAAQ,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,oCAc1D;AAED;;;GAGG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;iBAI3B,CAAA;AAEF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAA"}

package/dist/errors/index.d.ts

@@ -1,5 +1,14 @@
 /**
  * Creates a new Error with a custom name and message.
+ *
+ * @example
+ * ```typescript
+ * const err = createCustomError('NotFoundError', 'user 42 is missing')
+ * err.name // 'NotFoundError'
+ * err.message // 'user 42 is missing'
+ * err instanceof Error // true
+ * ```
+ *
  * @param name The error name.
  * @param message The error message.
  * @returns The custom Error object.
@@ -7,6 +16,15 @@
 export declare function createCustomError(name: string, message: string): Error;
 /**
  * Checks if an error is an instance of a specific error name.
+ *
+ * @example
+ * ```typescript
+ * const err = createCustomError('NotFoundError', 'missing')
+ * isErrorName(err, 'NotFoundError') // true
+ * isErrorName(err, 'TypeError') // false
+ * isErrorName('oops', 'TypeError') // false
+ * ```
+ *
  * @param error The error to check.
  * @param name The error name to match.
  * @returns True if the error matches the name, false otherwise.
@@ -14,6 +32,14 @@ export declare function createCustomError(name: string, message: string): Error;
 export declare function isErrorName(error: unknown, name: string): boolean;
 /**
  * Gets the error message from an unknown error value.
+ *
+ * @example
+ * ```typescript
+ * getErrorMessage(new Error('boom')) // 'boom'
+ * getErrorMessage('boom') // 'boom'
+ * getErrorMessage({ code: 500 }) // '{"code":500}'
+ * ```
+ *
  * @param error The error value.
  * @returns The error message, or a stringified version if not an Error.
  */
@@ -32,8 +58,10 @@ export declare function assert(condition: unknown, message: string): asserts con
  * @param fallback The fallback value to return on error.
  *
  * @example
- * const result = await tryWithFallback(async () => fetchData(), [])
- * // result will be [] if fetchData throws
+ * ```typescript
+ * await tryWithFallback(async () => fetchData(), []) // the data, or [] if it throws
+ * await tryWithFallback(() => JSON.parse('{'), {}) // {}
+ * ```
  */
 export declare function tryWithFallback<T>(fn: () => Promise<T> | T, fallback: T): Promise<T>;
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,KAAK,CAItE;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAEjE;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAQtD;AAED;;;;GAIG;AAEH,wBAAgB,MAAM,CAAC,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAI7E;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,eAAe,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAM1F"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,KAAK,CAItE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAEjE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAQtD;AAED;;;;GAIG;AAEH,wBAAgB,MAAM,CAAC,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAI7E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,eAAe,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAM1F"}

package/dist/events/index.d.ts

@@ -1,5 +1,12 @@
 /**
  * Adds an event listener and returns a function to remove it.
+ *
+ * @example
+ * ```typescript
+ * const off = on(button, 'click', (event) => console.log(event.clientX))
+ * off() // listener removed
+ * ```
+ *
  * @param target The event target.
  * @param type The event type.
  * @param handler The event handler.
@@ -9,6 +16,13 @@
 export declare function on<K extends keyof HTMLElementEventMap>(target: EventTarget, type: K, handler: (event: HTMLElementEventMap[K]) => void, options?: boolean | AddEventListenerOptions): () => void;
 /**
  * Dispatches a custom event on the target.
+ *
+ * @example
+ * ```typescript
+ * on(window, 'click', () => {})
+ * emit(window, 'cart:add', { sku: 'A1' }) // true (nothing called preventDefault)
+ * ```
+ *
  * @param target The event target.
  * @param type The event type.
  * @param detail Optional detail data.
@@ -17,11 +31,21 @@ export declare function on<K extends keyof HTMLElementEventMap>(target: EventTar
 export declare function emit(target: EventTarget, type: string, detail?: unknown): boolean;
 /**
  * Waits for a single event to occur and resolves a promise.
+ *
+ * Named `onceEvent` rather than `once` so it cannot be confused with
+ * `functions.once`, which memoises a call rather than awaiting an event.
+ *
+ * @example
+ * ```typescript
+ * const event = await onceEvent(button, 'click')
+ * event.type // 'click'
+ * ```
+ *
  * @param target The event target.
  * @param type The event type.
  * @returns {Promise<Event>} Resolves with the event object.
  */
-export declare function once<K extends keyof HTMLElementEventMap>(target: EventTarget, type: K): Promise<HTMLElementEventMap[K]>;
+export declare function onceEvent<K extends keyof HTMLElementEventMap>(target: EventTarget, type: K): Promise<HTMLElementEventMap[K]>;
 /**
  * Prevents the default action for an event.
  * @param event The event object.

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/events/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,wBAAgB,EAAE,CAAC,CAAC,SAAS,MAAM,mBAAmB,EACrD,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,CAAC,EACP,OAAO,EAAE,CAAC,KAAK,EAAE,mBAAmB,CAAC,CAAC,CAAC,KAAK,IAAI,EAChD,OAAO,CAAC,EAAE,OAAO,GAAG,uBAAuB,GACzC,MAAM,IAAI,CAGZ;AAED;;;;;;GAMG;AAEH,wBAAgB,IAAI,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,CAEjF;AAED;;;;;GAKG;AACH,wBAAgB,IAAI,CAAC,CAAC,SAAS,MAAM,mBAAmB,EACvD,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,CAAC,GACL,OAAO,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAQjC;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAEjD;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAElD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/events/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,EAAE,CAAC,CAAC,SAAS,MAAM,mBAAmB,EACrD,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,CAAC,EACP,OAAO,EAAE,CAAC,KAAK,EAAE,mBAAmB,CAAC,CAAC,CAAC,KAAK,IAAI,EAChD,OAAO,CAAC,EAAE,OAAO,GAAG,uBAAuB,GACzC,MAAM,IAAI,CAGZ;AAED;;;;;;;;;;;;;GAaG;AAEH,wBAAgB,IAAI,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,CAEjF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,mBAAmB,EAC5D,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,CAAC,GACL,OAAO,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAQjC;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAEjD;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAElD"}

package/dist/events/index.js

@@ -1 +1 @@
-import"../chunks/chunk-ANN5UYCF.js";function r(e,n,t,o){return e.addEventListener(n,t,o),()=>e.removeEventListener(n,t,o)}function E(e,n,t){return e.dispatchEvent(new CustomEvent(n,{detail:t}))}function i(e,n){return new Promise(t=>{let o=v=>{e.removeEventListener(n,o),t(v)};e.addEventListener(n,o)})}function a(e){e.preventDefault()}function s(e){e.stopPropagation()}export{E as emit,r as on,i as once,a as preventDefault,s as stopPropagation};
+import"../chunks/chunk-ANN5UYCF.js";function r(e,n,t,o){return e.addEventListener(n,t,o),()=>e.removeEventListener(n,t,o)}function E(e,n,t){return e.dispatchEvent(new CustomEvent(n,{detail:t}))}function i(e,n){return new Promise(t=>{let o=v=>{e.removeEventListener(n,o),t(v)};e.addEventListener(n,o)})}function a(e){e.preventDefault()}function s(e){e.stopPropagation()}export{E as emit,r as on,i as onceEvent,a as preventDefault,s as stopPropagation};

package/dist/fetch/index.d.ts

@@ -1,5 +1,13 @@
 /**
  * Fetches a resource with a timeout.
+ *
+ * @example
+ * ```typescript
+ * await fetchWithTimeout('https://api.example.com/health') // { status: 'ok' }
+ * await fetchWithTimeout('https://slow.example.com', {}, 500)
+ * // rejects with AbortError after 500ms
+ * ```
+ *
  * @param url The URL to fetch.
  * @param options Fetch options.
  * @param timeout Timeout in milliseconds (default: 8000).
@@ -8,6 +16,16 @@
 export declare function fetchWithTimeout(url: string, options?: RequestInit, timeout?: number): Promise<unknown>;
 /**
  * Sends a POST request with a JSON body.
+ *
+ * @example
+ * ```typescript
+ * const user = await postJson<{ name: string }, { id: number }>(
+ * 	'https://api.example.com/users',
+ * 	{ name: 'Ada' }
+ * )
+ * user.id // 42
+ * ```
+ *
  * @param url The URL to post to.
  * @param body The body to send.
  * @param options Additional fetch options.
@@ -16,6 +34,13 @@ export declare function fetchWithTimeout(url: string, options?: RequestInit, tim
 export declare function postJson<T = unknown, R = unknown>(url: string, body: T, options?: RequestInit): Promise<R>;
 /**
  * Sends a GET request and returns JSON.
+ *
+ * @example
+ * ```typescript
+ * const user = await getJson<{ id: number }>('https://api.example.com/users/42')
+ * user.id // 42
+ * ```
+ *
  * @param url The URL to fetch.
  * @param options Additional fetch options.
  * @returns The parsed JSON response.

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/fetch/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACrC,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,WAAgB,EACzB,OAAO,SAAO,GACZ,OAAO,CAAC,OAAO,CAAC,CAUlB;AAED;;;;;;GAMG;AACH,wBAAsB,QAAQ,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,EACtD,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,CAAC,EACP,OAAO,GAAE,WAAgB,GACvB,OAAO,CAAC,CAAC,CAAC,CAQZ;AAED;;;;;GAKG;AACH,wBAAsB,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,CAAC,CAAC,CAG7F;AAED;;;;;GAKG;AACH,wBAAsB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,CAGvF;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAOrF"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/fetch/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,gBAAgB,CACrC,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,WAAgB,EACzB,OAAO,SAAO,GACZ,OAAO,CAAC,OAAO,CAAC,CAUlB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,QAAQ,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,EACtD,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,CAAC,EACP,OAAO,GAAE,WAAgB,GACvB,OAAO,CAAC,CAAC,CAAC,CAQZ;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,CAAC,CAAC,CAG7F;AAED;;;;;GAKG;AACH,wBAAsB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,CAGvF;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAOrF"}

package/dist/file/index.d.ts

@@ -1,11 +1,24 @@
 /**
  * Reads a file as a string (UTF-8).
+ *
+ * @example
+ * ```typescript
+ * await readFileAsString('./package.json') // '{\n  "name": "@rtorcato/js-common",\n ...'
+ * ```
+ *
  * @param {string} filePath - The path to the file.
  * @returns {Promise<string>} The file contents as a string.
  */
 export declare function readFileAsString(filePath: string): Promise<string>;
 /**
  * Writes a string to a file (UTF-8).
+ *
+ * @example
+ * ```typescript
+ * await writeFileAsString('./out.txt', 'hello')
+ * await readFileAsString('./out.txt') // 'hello'
+ * ```
+ *
  * @param {string} filePath - The path to the file.
  * @param {string} data - The string data to write.
  * @returns {Promise<void>}
@@ -13,6 +26,13 @@ export declare function readFileAsString(filePath: string): Promise<string>;
 export declare function writeFileAsString(filePath: string, data: string): Promise<void>;
 /**
  * Checks if a file exists.
+ *
+ * @example
+ * ```typescript
+ * await fileExists('./package.json') // true
+ * await fileExists('./nope.txt') // false
+ * ```
+ *
  * @param {string} filePath - The path to the file.
  * @returns {Promise<boolean>} True if the file exists, false otherwise.
  */

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/file/index.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAExE;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAErF;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOnE;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEhE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEzD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/file/index.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAExE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAErF;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOnE;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEhE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEzD"}

package/dist/functions/functions.test-d.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=functions.test-d.d.ts.map

package/dist/functions/functions.test-d.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"functions.test-d.d.ts","sourceRoot":"","sources":["../../src/functions/functions.test-d.ts"],"names":[],"mappings":""}

package/dist/functions/functions.test-d.js

@@ -0,0 +1 @@
+import{a as s,b as n,c as u}from"../chunks/chunk-RBXTRLWB.js";import"../chunks/chunk-ANN5UYCF.js";import{describe as f,expectTypeOf as t,it as o}from"vitest";f("functions \u2014 types",()=>{o("once preserves the wrapped function signature",()=>{let e=s((a,p)=>({id:a,label:p}));t(e).toEqualTypeOf(),t(e).parameters.toEqualTypeOf(),t(e).returns.toEqualTypeOf(),e("1","a")}),o("debounce preserves the wrapped function parameters",()=>{let e=n((a,p)=>{},100);t(e).parameters.toEqualTypeOf(),t(e).returns.toEqualTypeOf(),e(1,"a")}),o("throttle preserves the wrapped function parameters",()=>{let e=u(a=>{},100);t(e).parameters.toEqualTypeOf(),t(e).returns.toEqualTypeOf(),e({y:1})}),o("debounce/throttle return void even when the wrapped function returns a value",()=>{let r=e=>e*2;t(n(r,10)).returns.toEqualTypeOf(),t(u(r,10)).returns.toEqualTypeOf(),t(n(r,10)).parameters.toEqualTypeOf()})});

package/dist/functions/index.d.ts

@@ -1,23 +1,53 @@
 /**
  * Returns a function that only calls the original function once.
+ *
+ * @example
+ * ```typescript
+ * let calls = 0
+ * const init = once(() => ++calls)
+ * init() // 1
+ * init() // 1 (cached, not called again)
+ * calls // 1
+ * ```
+ *
  * @param fn The function to wrap.
  * @returns {Function}
  */
 export declare function once<T extends (...args: any[]) => any>(fn: T): T;
 /**
  * Returns a debounced version of a function.
+ * The wrapper defers the call, so it always returns `undefined` — never `fn`'s return value.
+ *
+ * @example
+ * ```typescript
+ * const search = debounce((term: string) => console.log(term), 300)
+ * search('a')
+ * search('ab')
+ * search('abc') // only 'abc' is logged, 300ms after the last call
+ * ```
+ *
  * @param fn The function to debounce.
  * @param wait Milliseconds to wait.
  * @returns {Function}
  */
-export declare function debounce<T extends (...args: any[]) => void>(fn: T, wait: number): T;
+export declare function debounce<T extends (...args: any[]) => void>(fn: T, wait: number): (...args: Parameters<T>) => void;
 /**
  * Returns a throttled version of a function.
+ * The wrapper drops calls inside the window, so it always returns `undefined` — never `fn`'s
+ * return value.
+ *
+ * @example
+ * ```typescript
+ * const onScroll = throttle(() => console.log(window.scrollY), 100)
+ * window.addEventListener('scroll', onScroll)
+ * // fires at most once every 100ms, leading edge first
+ * ```
+ *
  * @param fn The function to throttle.
  * @param wait Milliseconds to wait between calls.
  * @returns {Function}
  */
-export declare function throttle<T extends (...args: any[]) => void>(fn: T, wait: number): T;
+export declare function throttle<T extends (...args: any[]) => void>(fn: T, wait: number): (...args: Parameters<T>) => void;
 /**
  * Composes functions from right to left.
  * @param fns Functions to compose.

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/functions/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,wBAAgB,IAAI,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EAAE,EAAE,EAAE,CAAC,GAAG,CAAC,CAUhE;AAED;;;;;GAKG;AAEH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,EAAE,EAAE,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,CAMnF;AAED;;;;;GAKG;AAEH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,EAAE,EAAE,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,CASnF;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,GAAG,GAAG,EAAE,KAAK,CAAC,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,CAEtE;AAED;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,GAAG,GAAG,EAAE,KAAK,CAAC,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,CAEnE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/functions/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,wBAAgB,IAAI,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EAAE,EAAE,EAAE,CAAC,GAAG,CAAC,CAUhE;AAED;;;;;;;;;;;;;;;GAeG;AAEH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,EAC1D,EAAE,EAAE,CAAC,EACL,IAAI,EAAE,MAAM,GACV,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,KAAK,IAAI,CAMlC;AAED;;;;;;;;;;;;;;;GAeG;AAEH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,EAC1D,EAAE,EAAE,CAAC,EACL,IAAI,EAAE,MAAM,GACV,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,KAAK,IAAI,CASlC;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,GAAG,GAAG,EAAE,KAAK,CAAC,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,CAEtE;AAED;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,GAAG,GAAG,EAAE,KAAK,CAAC,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,CAEnE"}