@rtorcato/js-common 2.8.1 → 3.0.0

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

package/dist/functions/index.js

@@ -1 +1 @@
-import"../chunks/chunk-ANN5UYCF.js";function o(n){let t=!1,e;return function(...r){return t||(t=!0,e=n.apply(this,r)),e}}function T(n,t){let e;return function(...r){clearTimeout(e),e=setTimeout(()=>n.apply(this,r),t)}}function u(n,t){let e=0;return function(...r){let a=Date.now();a-e>=t&&(e=a,n.apply(this,r))}}function i(...n){return t=>n.reduceRight((e,r)=>r(e),t)}function s(...n){return t=>n.reduce((e,r)=>r(e),t)}export{i as compose,T as debounce,o as once,s as pipe,u as throttle};
+import{a,b,c,d,e}from"../chunks/chunk-RBXTRLWB.js";import"../chunks/chunk-ANN5UYCF.js";export{d as compose,b as debounce,a as once,e as pipe,c as throttle};

package/dist/geometry/index.d.ts

@@ -1,5 +1,12 @@
 /**
  * Calculates the distance between two points in 2D space.
+ *
+ * @example
+ * ```typescript
+ * distance2D(0, 0, 3, 4) // 5
+ * distance2D(1, 1, 1, 1) // 0
+ * ```
+ *
  * @param x1 X coordinate of first point.
  * @param y1 Y coordinate of first point.
  * @param x2 X coordinate of second point.
@@ -9,6 +16,13 @@
 export declare function distance2D(x1: number, y1: number, x2: number, y2: number): number;
 /**
  * Calculates the midpoint between two points in 2D space.
+ *
+ * @example
+ * ```typescript
+ * midpoint2D(0, 0, 4, 6) // [2, 3]
+ * midpoint2D(-2, 5, 2, 5) // [0, 5]
+ * ```
+ *
  * @param x1 X coordinate of first point.
  * @param y1 Y coordinate of first point.
  * @param x2 X coordinate of second point.
@@ -18,6 +32,13 @@ export declare function distance2D(x1: number, y1: number, x2: number, y2: numbe
 export declare function midpoint2D(x1: number, y1: number, x2: number, y2: number): [number, number];
 /**
  * Calculates the angle (in radians) between two points in 2D space.
+ *
+ * @example
+ * ```typescript
+ * angle2D(0, 0, 1, 0) // 0
+ * angle2D(0, 0, 0, 1) // 1.5707963267948966 (Math.PI / 2)
+ * ```
+ *
  * @param x1 X coordinate of first point.
  * @param y1 Y coordinate of first point.
  * @param x2 X coordinate of second point.

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/geometry/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAEjF;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAE3F;AAED;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAE9E;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAC1B,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,GACR,OAAO,CAET;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAC3B,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,GACR,OAAO,CAET;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,MAAM,CAY9D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/geometry/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAEjF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAE3F;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAE9E;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAC1B,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,GACR,OAAO,CAET;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAC3B,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,GACR,OAAO,CAET;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,MAAM,CAY9D"}

package/dist/html/index.d.ts

@@ -1,17 +1,50 @@
 /**
  * Escapes special HTML characters in a string to prevent XSS attacks.
+ *
+ * @example
+ * ```typescript
+ * escapeHtml('<script>alert("x")</script>')
+ * // '&lt;script&gt;alert(&quot;x&quot;)&lt;/script&gt;'
+ * escapeHtml("Tom & Jerry's") // 'Tom &amp; Jerry&#39;s'
+ * ```
+ *
  * @param str The string to escape.
  * @returns The escaped string.
  */
 export declare function escapeHtml(str: string): string;
 /**
  * Unescapes HTML entities in a string.
+ *
+ * @example
+ * ```typescript
+ * unescapeHtml('&lt;b&gt;hi&lt;/b&gt;') // '<b>hi</b>'
+ * unescapeHtml('Tom &amp; Jerry') // 'Tom & Jerry'
+ * unescapeHtml('a&#x2F;b&nbsp;c') // 'a/b c'
+ * ```
+ *
  * @param str The string to unescape.
  * @returns The unescaped string.
  */
 export declare function unescapeHtml(str: string): string;
 /**
  * Strips all HTML tags from a string.
+ *
+ * @example
+ * ```typescript
+ * stripHtmlTags('<p>Hello <b>world</b></p>') // 'Hello world'
+ * stripHtmlTags('plain text') // 'plain text'
+ *
+ * // Strips `<…>` spans, so ragged input leaves residue — not a sanitizer.
+ * stripHtmlTags('<<a>script>') // 'script>'
+ * stripHtmlTags('<scr<x>ipt>') // 'ipt>'
+ * ```
+ *
+ * Removes `<…>` spans and nothing else: it does not decode entities and does
+ * not understand attributes or quoting, so ragged or nested markup leaves
+ * attacker-controlled residue behind rather than a safe string. Not a
+ * substitute for a real sanitizer such as DOMPurify when rendering untrusted
+ * HTML — this produces display text, it does not make untrusted markup safe.
+ *
  * @param str The string to strip tags from.
  * @returns The plain text string.
  */
@@ -24,6 +57,11 @@ export declare function stripHtmlTags(str: string): string;
 export declare function textToHtml(str: string): string;
 /**
  * Checks if a string contains any HTML tags.
+ *
+ * A heuristic for "does this look like markup", not a security gate: it only
+ * looks for a non-empty `<…>` span, so `'a<b'` and `'<>'` are both false. Do
+ * not use it to decide whether untrusted input is safe to render.
+ *
  * @param str The string to check.
  * @returns True if the string contains HTML tags, false otherwise.
  */

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/html/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAO9C;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAOhD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEjD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/html/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAO9C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAehD;AAkBD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAQjD;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAMjD"}

package/dist/html/index.js

@@ -1 +1 @@
-import"../chunks/chunk-ANN5UYCF.js";function t(e){return e.replace(/&/g,"&amp;").replace(/</g,"&lt;").replace(/>/g,"&gt;").replace(/"/g,"&quot;").replace(/'/g,"&#39;")}function r(e){return e.replace(/&lt;/g,"<").replace(/&gt;/g,">").replace(/&quot;/g,'"').replace(/&#39;/g,"'").replace(/&amp;/g,"&")}function n(e){return e.replace(/<[^>]*>/g,"")}function g(e){return e.replace(/\n/g,"<br>")}function p(e){return/<[^>]+>/.test(e)}export{p as containsHtml,t as escapeHtml,n as stripHtmlTags,g as textToHtml,r as unescapeHtml};
+import"../chunks/chunk-ANN5UYCF.js";function o(e){return e.replace(/&/g,"&amp;").replace(/</g,"&lt;").replace(/>/g,"&gt;").replace(/"/g,"&quot;").replace(/'/g,"&#39;")}function c(e){let n={"&amp;":"&","&lt;":"<","&gt;":">","&quot;":'"',"&#39;":"'","&#x27;":"'","&#x2F;":"/","&nbsp;":" "};return e.replace(/&(?:amp|lt|gt|quot|#39|#x27|#x2F|nbsp);/g,t=>n[t]??t)}function l(e,n){let t=e.indexOf("<",n);if(t===-1)return null;let r=e.indexOf(">",t+1);return r===-1?null:{open:t,close:r}}function i(e){let n="",t=0;for(let r=l(e,t);r;r=l(e,t))n+=e.slice(t,r.open),t=r.close+1;return n+e.slice(t)}function s(e){return e.replace(/\n/g,"<br>")}function g(e){for(let n=l(e,0);n;n=l(e,n.close+1))if(n.close>n.open+1)return!0;return!1}export{g as containsHtml,o as escapeHtml,i as stripHtmlTags,s as textToHtml,c as unescapeHtml};

package/dist/i18n/index.d.ts

@@ -1,10 +1,25 @@
 /**
  * Detects the user's preferred language from the browser or Node.js environment.
+ *
+ * @example
+ * ```typescript
+ * detectLanguage() // 'en' (from navigator.language 'en-GB' or LANG 'en_US.UTF-8')
+ * detectLanguage('fr') // 'fr' when nothing can be detected
+ * ```
+ *
  * @returns {string} The language code (e.g., 'en', 'fr').
  */
 export declare function detectLanguage(defaultLang?: string): string;
 /**
  * Formats a number as a localized string.
+ *
+ * @example
+ * ```typescript
+ * formatNumber(1234.5, 'en-US') // '1,234.5'
+ * formatNumber(1234.5, 'de-DE') // '1.234,5'
+ * formatNumber(0.42, 'en-US', { style: 'percent' }) // '42%'
+ * ```
+ *
  * @param value The number to format.
  * @param locale The locale code (e.g., 'en-US').
  * @param options Intl.NumberFormat options.
@@ -13,6 +28,14 @@ export declare function detectLanguage(defaultLang?: string): string;
 export declare function formatNumber(value: number, locale?: string, options?: Intl.NumberFormatOptions): string;
 /**
  * Formats a date as a localized string.
+ *
+ * @example
+ * ```typescript
+ * const d = new Date('2026-08-11T12:00:00Z')
+ * formatDateI18n(d, 'en-US', { timeZone: 'UTC' }) // '8/11/2026'
+ * formatDateI18n(d, 'en-GB', { timeZone: 'UTC' }) // '11/08/2026'
+ * ```
+ *
  * @param date The date to format.
  * @param locale The locale code (e.g., 'en-US').
  * @param options Intl.DateTimeFormat options.
@@ -27,11 +50,4 @@ export declare function formatDateI18n(date: Date, locale?: string, options?: In
  * @returns {string}
  */
 export declare function t(key: string, dict: Record<string, Record<string, string>>, lang?: string): string;
-/**
- * Pluralizes a word based on a count (basic English only).
- * @param word The word to pluralize.
- * @param count The count.
- * @returns {string}
- */
-export declare function pluralize(word: string, count: number): string;
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/i18n/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,cAAc,CAAC,WAAW,GAAE,MAAa,GAAG,MAAM,CAQjE;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC3B,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,IAAI,CAAC,mBAAmB,GAChC,MAAM,CAER;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC7B,IAAI,EAAE,IAAI,EACV,MAAM,CAAC,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,IAAI,CAAC,qBAAqB,GAClC,MAAM,CAER;AAED;;;;;;GAMG;AACH,wBAAgB,CAAC,CAChB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAC5C,IAAI,CAAC,EAAE,MAAM,GACX,MAAM,CAGR;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAE7D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/i18n/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,WAAW,GAAE,MAAa,GAAG,MAAM,CAQjE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAC3B,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,IAAI,CAAC,mBAAmB,GAChC,MAAM,CAER;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAC7B,IAAI,EAAE,IAAI,EACV,MAAM,CAAC,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,IAAI,CAAC,qBAAqB,GAClC,MAAM,CAER;AAED;;;;;;GAMG;AACH,wBAAgB,CAAC,CAChB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAC5C,IAAI,CAAC,EAAE,MAAM,GACX,MAAM,CAGR"}

package/dist/i18n/index.js

@@ -1 +1 @@
-import"../chunks/chunk-ANN5UYCF.js";function i(n="en"){return typeof navigator<"u"&&navigator.language?navigator.language.split("-")[0]||n:typeof process<"u"&&process.env.LANG&&(process.env.LANG??"en").split("_")[0]||n}function o(n,t,r){return new Intl.NumberFormat(t,r).format(n)}function s(n,t,r){return new Intl.DateTimeFormat(t,r).format(n)}function a(n,t,r){let e=r||i();return t[e]?.[n]||t.en?.[n]||n}function g(n,t){return t===1?n:`${n}s`}export{i as detectLanguage,s as formatDateI18n,o as formatNumber,g as pluralize,a as t};
+import"../chunks/chunk-ANN5UYCF.js";function i(n="en"){return typeof navigator<"u"&&navigator.language?navigator.language.split("-")[0]||n:typeof process<"u"&&process.env.LANG&&(process.env.LANG??"en").split("_")[0]||n}function o(n,t,r){return new Intl.NumberFormat(t,r).format(n)}function s(n,t,r){return new Intl.DateTimeFormat(t,r).format(n)}function a(n,t,r){let e=r||i();return t[e]?.[n]||t.en?.[n]||n}export{i as detectLanguage,s as formatDateI18n,o as formatNumber,a as t};

package/dist/interval/index.d.ts

@@ -1,5 +1,13 @@
 /**
  * Runs a function repeatedly at a specified interval (cross-platform).
+ *
+ * @example
+ * ```typescript
+ * const id = runInterval(() => console.log('tick'), 1000)
+ * // logs 'tick' once a second until cleared
+ * clearIntervalById(id)
+ * ```
+ *
  * @param fn The function to run.
  * @param ms The interval in milliseconds.
  * @returns The interval ID (NodeJS.Timeout or number).
@@ -7,6 +15,13 @@
 export declare function runInterval(fn: () => void, ms: number): ReturnType<typeof setInterval>;
 /**
  * Cancels an interval by its ID (cross-platform).
+ *
+ * @example
+ * ```typescript
+ * const id = runInterval(() => console.log('tick'), 1000)
+ * clearIntervalById(id) // no more ticks
+ * ```
+ *
  * @param id The interval ID (NodeJS.Timeout or number).
  */
 export declare function clearIntervalById(id: ReturnType<typeof setInterval>): void;

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/interval/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,UAAU,CAAC,OAAO,WAAW,CAAC,CAEtF;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,UAAU,CAAC,OAAO,WAAW,CAAC,GAAG,IAAI,CAE1E"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/interval/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,UAAU,CAAC,OAAO,WAAW,CAAC,CAEtF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,UAAU,CAAC,OAAO,WAAW,CAAC,GAAG,IAAI,CAE1E"}

package/dist/json/index.d.ts

@@ -1,5 +1,13 @@
 /**
  * Safely parses a JSON string, returning a fallback value if parsing fails.
+ *
+ * @example
+ * ```typescript
+ * safeJsonParse('{"a":1}') // { a: 1 }
+ * safeJsonParse('{oops') // null
+ * safeJsonParse('{oops', {}) // {}
+ * ```
+ *
  * @param {string} str - The JSON string to parse.
  * @param {any} [fallback=null] - The value to return if parsing fails.
  * @returns The parsed object or the fallback value.
@@ -7,6 +15,17 @@
 export declare function safeJsonParse<T = any>(str: string, fallback?: T | null): T | null;
 /**
  * Safely stringifies a value to JSON, returning a fallback value if stringification fails.
+ *
+ * @example
+ * ```typescript
+ * safeJsonStringify({ a: 1 }) // '{"a":1}'
+ *
+ * const circular: any = {}
+ * circular.self = circular
+ * safeJsonStringify(circular) // null
+ * safeJsonStringify(circular, '{}') // '{}'
+ * ```
+ *
  * @param {any} value - The value to stringify.
  * @param {string} [fallback=null] - The value to return if stringification fails.
  * @returns The JSON string or the fallback value.
@@ -14,6 +33,14 @@ export declare function safeJsonParse<T = any>(str: string, fallback?: T | null)
 export declare function safeJsonStringify(value: any, fallback?: string | null): string | null;
 /**
  * Checks if a string is valid JSON.
+ *
+ * @example
+ * ```typescript
+ * isValidJson('{"a":1}') // true
+ * isValidJson('[1,2]') // true
+ * isValidJson('{oops') // false
+ * ```
+ *
  * @param {string} str - The string to check.
  * @returns {boolean} True if the string is valid JSON, false otherwise.
  */

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/json/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,wBAAgB,aAAa,CAAC,CAAC,GAAG,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,GAAE,CAAC,GAAG,IAAW,GAAG,CAAC,GAAG,IAAI,CAMvF;AAED;;;;;GAKG;AAEH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,GAAG,EAAE,QAAQ,GAAE,MAAM,GAAG,IAAW,GAAG,MAAM,GAAG,IAAI,CAM3F;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAOhD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAE5C"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/json/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,wBAAgB,aAAa,CAAC,CAAC,GAAG,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,GAAE,CAAC,GAAG,IAAW,GAAG,CAAC,GAAG,IAAI,CAMvF;AAED;;;;;;;;;;;;;;;;GAgBG;AAEH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,GAAG,EAAE,QAAQ,GAAE,MAAM,GAAG,IAAW,GAAG,MAAM,GAAG,IAAI,CAM3F;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAOhD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAE5C"}

package/dist/logger/index.js

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

package/dist/logger/logger.d.ts

@@ -1,7 +1,17 @@
 import pino from 'pino';
 /**
- * Pre-configured Pino logger — pretty-printed with colors in development, plain JSON
- * at `info` level in production.
+ * Pre-configured Pino logger — pretty-printed with colors in development (when
+ * `pino-pretty` is installed), plain JSON at `info` level in production.
+ *
+ * @example
+ * ```typescript
+ * logger.info('server started')
+ * // dev:  14:03:27 INFO: server started
+ * // prod: {"level":30,"msg":"server started"}
+ *
+ * logger.error({ err }, 'upload failed')
+ * logger.debug('only visible in development')
+ * ```
  */
 export declare const logger: pino.Logger<never, boolean>;
 //# sourceMappingURL=logger.d.ts.map

package/dist/logger/logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/logger/logger.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,MAAM,CAAA;AAGvB;;;GAGG;AACH,eAAO,MAAM,MAAM,6BAyBO,CAAA"}
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/logger/logger.ts"],"names":[],"mappings":"AACA,OAAO,IAAI,MAAM,MAAM,CAAA;AAgBvB;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,MAAM,6BA0BQ,CAAA"}

package/dist/logger/logger.js

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

package/dist/logging/index.d.ts

@@ -1,16 +1,35 @@
 /**
  * Logs a message with a timestamp.
+ *
+ * @example
+ * ```typescript
+ * logWithTimestamp('server started') // [2026-08-11T14:03:27.913Z] server started
+ * logWithTimestamp('disk almost full', 'warn') // via console.warn
+ * ```
+ *
  * @param message The message to log.
  * @param level The log level (default: 'info').
  */
 export declare function logWithTimestamp(message: string, level?: 'info' | 'warn' | 'error'): void;
 /**
  * Logs a warning message.
+ *
+ * @example
+ * ```typescript
+ * warn('deprecated option') // [WARN] deprecated option
+ * ```
+ *
  * @param message The warning message.
  */
 export declare function warn(message: string): void;
 /**
  * Logs an error message.
+ *
+ * @example
+ * ```typescript
+ * error('upload failed') // [ERROR] upload failed
+ * ```
+ *
  * @param message The error message.
  */
 export declare function error(message: string): void;

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/logging/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,GAAE,MAAM,GAAG,MAAM,GAAG,OAAgB,GAAG,IAAI,CAIjG;AAED;;;GAGG;AACH,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAG1C;AAED;;;GAGG;AACH,wBAAgB,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAG3C;AAED;;;GAGG;AACH,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAG1C;AAED;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAA;AAE5D;;;;GAIG;AACH,wBAAgB,cAAc,CAC7B,QAAQ,EAAE,CAAC,IAAI,EAAE,YAAY,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GACxD,MAAM,IAAI,CAgBZ"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/logging/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,GAAE,MAAM,GAAG,MAAM,GAAG,OAAgB,GAAG,IAAI,CAIjG;AAED;;;;;;;;;GASG;AACH,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAG1C;AAED;;;;;;;;;GASG;AACH,wBAAgB,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAG3C;AAED;;;GAGG;AACH,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAG1C;AAED;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAA;AAE5D;;;;GAIG;AACH,wBAAgB,cAAc,CAC7B,QAAQ,EAAE,CAAC,IAAI,EAAE,YAAY,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GACxD,MAAM,IAAI,CAgBZ"}

package/dist/maps/index.d.ts

@@ -1,11 +1,25 @@
 /**
  * Inverts a Map (swaps keys and values). If duplicate values exist, later keys overwrite earlier ones.
+ *
+ * @example
+ * ```typescript
+ * invertMap(new Map([['a', 1], ['b', 2]]))
+ * // Map { 1 => 'a', 2 => 'b' }
+ * ```
+ *
  * @param map The map to invert.
  * @returns {Map<any, any>} The inverted map.
  */
 export declare function invertMap<K, V>(map: Map<K, V>): Map<V, K>;
 /**
  * Maps the values of a Map using a function.
+ *
+ * @example
+ * ```typescript
+ * mapValues(new Map([['a', 1], ['b', 2]]), (v) => v * 10)
+ * // Map { 'a' => 10, 'b' => 20 }
+ * ```
+ *
  * @param map The map to map over.
  * @param fn The function to apply to each value.
  * @returns {Map<K, U>} A new map with mapped values.
@@ -13,6 +27,13 @@ export declare function invertMap<K, V>(map: Map<K, V>): Map<V, K>;
 export declare function mapValues<K, V, U>(map: Map<K, V>, fn: (value: V, key: K) => U): Map<K, U>;
 /**
  * Merges two or more maps. Later maps overwrite earlier keys.
+ *
+ * @example
+ * ```typescript
+ * mergeMaps(new Map([['a', 1]]), new Map([['a', 9], ['b', 2]]))
+ * // Map { 'a' => 9, 'b' => 2 }
+ * ```
+ *
  * @param maps The maps to merge.
  * @returns {Map<K, V>} The merged map.
  */