@reykjavik/webtools 0.2.6 → 0.2.8

package/CHANGELOG.md

@@ -4,6 +4,23 @@
 
 - ... <!-- Add new lines here. -->
 
+## 0.2.8
+
+_2025-09-17_
+
+- `@reykjavik/webtools/async`:
+  - feat: Add `debounce` and `throttle` helpers
+- `@reykjavik/webtools/hooks` (new module):
+  - feat: Add `useDebounced` and `useThrottled` hooks
+
+## 0.2.7
+
+_2025-09-01_
+
+- `@reykjavik/webtools/fixIcelandicLocale`:
+  - fix: Check for support of each Intl class separately
+- docs: Improve JSDocs and README for `asError()` and `ErrorFromPayload`
+
 ## 0.2.6
 
 _2025-06-20_

package/README.md

@@ -29,6 +29,11 @@ bun add @reykjavik/webtools
 - [`@reykjavik/webtools/async`](#reykjavikwebtoolsasync)
   - [`promiseAllObject`](#promiseallobject)
   - [`maxWait`](#maxwait)
+  - [`debounce`](#debounce)
+  - [`throttle`](#throttle)
+- [`@reykjavik/webtools/hoooks`](#reykjavikwebtoolshoooks)
+  - [`useDebounced`](#usedebounced)
+  - [`useThrottled`](#usethrottled)
 - [`@reykjavik/webtools/errorhandling`](#reykjavikwebtoolserrorhandling)
   - [`asError`](#aserror)
   - [`Result` Singleton](#result-singleton)
@@ -369,6 +374,188 @@ console.log(posts?.reason); // undefined | unknown
 
 ---
 
+### `debounce`
+
+**Syntax:**
+`debounce<A extends Array<unknown>>(func: (...args: A) => void, delay: number, immediate?: boolean): ((...args: A) => void) & { cancel: (finish?: boolean) => void; }`
+
+Returns a debounced function that only runs after `delay` milliseconds of
+quiet-time, and can optionally be made to run `immediate`ly on first call
+before dbouncing subsequent calls.
+
+```ts
+import { debounce } from '@reykjavik/webtools/async';
+
+// Basic usage:
+const sayHello = debounce((namme: string) => {
+  console.log('Hello ' + name);
+}, 200);
+
+sayHello('Alice');
+sayHello('Bob');
+sayHello('Charlie');
+sayHello('Dorothy');
+// Only "Hello Dorothy" is logged, 200ms after the last call
+
+// With `immediate` param set to true:
+const sayHi = debounce(
+  (namme: string) => console.log('Hi ' + name),
+  200,
+  true
+);
+sayHi('Alice');
+sayHi('Bob');
+sayHi('Charlie');
+sayHi('Dorothy');
+// "Hi Alice" is logged immediately
+// Then "Hi Dorothy" is logged, 200ms after the last call
+```
+
+The returned function has a nice `.cancel()` method, which can optionally
+invoke the function before cancelling, if it had a debounce pending.
+
+```ts
+sayHello('Erica');
+sayHello('Fiona');
+sayHello.cancel();
+// Nothing is logged because the debounce was cancelled
+
+sayHello('George');
+sayHello('Harold');
+sayHello.cancel(true); // `finish` parmeter is true
+// "Hello Harold" is logged immediately because it was pending
+```
+
+---
+
+### `throttle`
+
+**Syntax:**
+`throttle<A extends Array<unknown>>(func: (...args: A) => void, delay: number, skipFirst?: boolean): ((...args: A) => void) & { finish: (cancel?: boolean) => void; }`
+
+Returns a throttled function that never runs more often than every `delay`
+milliseconds. It can optionally made to `skipFirst` invocation.
+
+```ts
+import { throttle } from '@reykjavik/webtools/async';
+
+// Basic usage:
+const sayHello = throttle((name: string) => {
+  console.log('Hello ' + name);
+}, 200);
+
+sayHello('Alice');
+sayHello('Bob');
+sayHello('Charlie');
+sayHello('Dorothy');
+// Only "Hello Alice" is logged immediately. The other calls were throttled.
+
+// With `skipFirst` param set to true:
+const sayHi = throttle(
+  (name: string) => console.log('Hi ' + name),
+  200,
+  true
+);
+sayHi('Alice');
+sayHi('Bob');
+sayHi('Charlie');
+sayHi('Dorothy');
+// Nothing is logged. The first call was skipped, and the rest were throttled.
+```
+
+The returned function also has a nice `.finish()` method to reset the throttle
+timer. By default it instantly invokes the function, if the last call was
+throttled (skipped)-.
+
+```ts
+sayHello('Erica');
+sayHello('Fiona');
+sayHello.finish();
+// "Hello Fiona" is logged immediately because it was pending
+
+sayHello('George');
+sayHello('Harold');
+sayHello.finish(true); // `cancel` parmeter is true
+// Nothing is logged because the pending call was cancelled
+```
+
+---
+
+## `@reykjavik/webtools/hoooks`
+
+Some useful React hooks.
+
+### `useDebounced`
+
+**Syntax:**
+`useDebounced<A extends Array<unknown>>(func: (...args: A) => void, delay: number, immediate?: boolean): ((...args: A) => void) & { cancel: (finish?: boolean) => void; }`
+
+Returns a stable debounced function that invokes the supplied function after
+the specified delay. When the component unmounts, any pending (debounced)
+calls are automatically cancelled.
+
+**NOTE:** The supplied callback does not need to be memoized. The debouncer
+will always invoke the last supplied version.
+
+```ts
+import { useDebounced } from '@reykjavik/webtools/hoooks';
+
+const MyComponent = () => {
+  const renderDate = new Date();
+  const debouncedSearch = useDebounced((query: string) => {
+    console.log('Searching for:', query, 'at', renderDate.toISOString());
+  }, 200);
+  return (
+    <input
+      type="text"
+      onChange={(e) => {
+        debouncedSearch(e.currentTarget.value);
+      }}
+    />
+  );
+};
+```
+
+See [`debounce`](#debounce) for more details about the parameters and the
+returned debounced function's `.cancel()` method.
+
+### `useThrottled`
+
+**Syntax:**
+`useThrottled<A extends Array<unknown>>(func: (...args: A) => void, delay: number, skipFirst?: boolean): ((...args: A) => void) & { finish: (cancel?: boolean) => void; }`
+
+Returns a stable throttler function that throttles the supplied function.
+
+**NOTE:** The supplied callback does not need to be memoized. The throttler
+will always invoke the last supplied version.
+
+```ts
+import { useThrottled } from '@reykjavik/webtools/hoooks';
+
+const MyComponent = () => {
+  const renderDate = new Date();
+  const throttledReportPosition = useThrottled((x: number, y: number) => {
+    console.log('Mouse position:', x, ',', y, 'at', renderDate.toISOString());
+  }, 200);
+
+  return (
+    <div
+      style={{ width: '300px', height: '300px', background: '#eee' }}
+      onMouseMove={(e) => {
+        throttledReportPosition(e.clientX, e.clientY);
+      }}
+    >
+      Move your mouse here.
+    </div>
+  );
+};
+```
+
+See [`throttle`](#throttle) for more details about the parameters and the
+returned throttled function's `.finish()` method.
+
+---
+
 ## `@reykjavik/webtools/errorhandling`
 
 A small set of lightweight tools for handling errors and promises in a safer,
@@ -386,7 +573,8 @@ Guarantees that a caught (`catch (e)`) value of `unknown` type, is indeed an
 
 If the input is an `Error` instance, it is returned as-is. If the input is
 something else it is wrapped in a new `ErrorFromPayload` instance, and the
-original value is stored in as a `payload` property.
+original value is stored in as a `payload` property, and it's `.toString()` is
+used for the `message` property.
 
 ```ts
 import { asError, type ErrorFromPayload } from '@reykjavik/webtools/errorhandling';
@@ -395,21 +583,23 @@ const theError = new Error('Something went wrong');
 try {
   throw theError;
 } catch (err) {
+  // theError is an instance of Error so it's returned as-is
   const error = asError(theError);
   console.error(error === theError); // true
-  console.error('patload' in error); // false
+  console.error('payload' in error); // false
 }
 
-const someObject = ['Something went wrong'];
+const someObject = ['Oops', 'Something went wrong'];
 try {
   throw someObject;
 } catch (err) {
+  // the thrown someObject is not an Error so an `ErrorFromPayload` is returned
   const error = asError(someObject);
   console.error(error === someObject); // false
-  console.error(error.message === someObject.join(',')); // false
   console.error(error instanceOf ErrorFromPayload); // true
 
   console.error(error.payload === someObject); // true
+  console.error(error.message === someObject.join(',')); // true
 }
 ```
 

package/async.d.ts

@@ -31,4 +31,43 @@ export declare function maxWait<PromiseMap extends PlainObj>(timeout: number, pr
  * @see https://github.com/reykjavikcity/webtools/blob/v0.2/README.md#promiseallobject
  */
 export declare const promiseAllObject: <T extends PlainObj>(promisesMap: T) => Promise<{ -readonly [K in keyof T]: Awaited<T[K]>; }>;
+type Cancellable<A extends Array<unknown>> = ((...args: A) => void) & {
+    /**
+     * Cancels any pending invocation of the debounced function.  \
+     * If `finish` is true and if a debounce is pending, the function is invoked
+     * before cancelling.
+     */
+    cancel(finish?: boolean): void;
+};
+/**
+ * Returns a debounced function that only runs after `delay` milliseconds
+ * of quiet-time.  \
+ * The returned function also has a nice `.cancel()` method.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.2/README.md#debounce
+ */
+export declare const debounce: {
+    <A extends Array<unknown>>(func: (...args: A) => void, delay: number, immediate?: boolean): Cancellable<A>;
+    d(delay: number, immediate?: boolean): Cancellable<[fn: (...args: Array<any>) => void, ...args: any[]]>;
+};
+type Finishable<A extends Array<unknown>> = ((...args: A) => void) & {
+    /**
+     * Immediately invokes the function if there is a pending throttle and its last
+     * invoication was throttled (cancelled).  \
+     * If `cancel` is true then only the timer is reset without invoking function.
+     */
+    finish(cancel?: boolean): void;
+};
+/**
+ * Returns a throttled function that never runs more often than
+ * every `delay` milliseconds.  \
+ * The returned function also has a nice `.finish()` method to reset the
+ * throttle timer
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.2/README.md#throttle
+ */
+export declare const throttle: {
+    <A extends Array<unknown>>(func: (...args: A) => void, delay: number, skipFirst?: boolean): Finishable<A>;
+    d(delay: number, skipFirst?: boolean): Finishable<[fn: (...args: Array<any>) => void, ...args: any[]]>;
+};
 export {};

package/async.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.promiseAllObject = exports.addLag = exports.sleep = void 0;
+exports.throttle = exports.debounce = exports.promiseAllObject = exports.addLag = exports.sleep = void 0;
 exports.maxWait = maxWait;
 /**
  * Simple sleep function. Returns a promise that resolves after `length`
@@ -79,3 +79,107 @@ const promiseAllObject = (promisesMap) => Promise.all(Object.values(promisesMap)
     return resolvedMap;
 });
 exports.promiseAllObject = promiseAllObject;
+/**
+ * Returns a debounced function that only runs after `delay` milliseconds
+ * of quiet-time.  \
+ * The returned function also has a nice `.cancel()` method.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.2/README.md#debounce
+ */
+/*#__NO_SIDE_EFFECTS__*/
+const debounce = (
+/** The function to debounce */
+func, 
+/** The delay, in milliseconds, to wait before running the function */
+delay, 
+/** Whether to run the function at the start of the delay instead of the end */
+immediate) => {
+    let timeout;
+    let _args;
+    let _this;
+    const debouncedFn = function (...args) {
+        _args = args;
+        _this = this;
+        immediate && !timeout && func.apply(_this, _args);
+        timeout && clearTimeout(timeout);
+        timeout = setTimeout(() => {
+            debouncedFn.cancel(true);
+        }, delay);
+    };
+    debouncedFn.cancel = (finish) => {
+        timeout && clearTimeout(timeout);
+        finish && timeout && func.apply(_this, _args);
+        timeout = undefined;
+    };
+    return debouncedFn;
+};
+exports.debounce = debounce;
+/**
+ * Sugar to produce a dynamic debounced function that accepts its contents/behavior at call time.
+ *
+ * Usage:
+ * ```ts
+ *      const myDebouncer = debounce.d(500);
+ *      myDebouncer(() => { alert('Hello world'); });
+ *      myDebouncer(() => { alert('I mean: Howdy world!'); });
+ *      myDebouncer((name) => { alert('Wazzap ' + name); }, 'world');
+ * ```
+ *
+ * Not documented in README as its usefulness is still uncertain.
+ */
+exports.debounce.d = (delay, immediate) => (0, exports.debounce)(function (fn, ...args) {
+    fn.apply(this, args);
+}, delay, immediate);
+/**
+ * Returns a throttled function that never runs more often than
+ * every `delay` milliseconds.  \
+ * The returned function also has a nice `.finish()` method to reset the
+ * throttle timer
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.2/README.md#throttle
+ */
+/*#__NO_SIDE_EFFECTS__*/
+const throttle = (
+/** The function to throttle */
+func, 
+/** The delay, in milliseconds, to wait between invocations */
+delay, 
+/** Whether to skip the first invocation instead of running it immediately */
+skipFirst) => {
+    let timeout;
+    let throttled = 0;
+    let _args;
+    let _this;
+    const throttledFn = function (...args) {
+        _args = args;
+        _this = this;
+        if (!throttled) {
+            skipFirst ? throttled++ : func.apply(_this, _args);
+            timeout = setTimeout(throttledFn.finish, delay); // Go home TypeScript, you're drunk!
+        }
+        throttled++;
+    };
+    throttledFn.finish = (cancel) => {
+        timeout && clearTimeout(timeout);
+        !cancel && throttled && func.apply(_this, _args);
+        throttled = 0;
+    };
+    return throttledFn;
+};
+exports.throttle = throttle;
+/**
+ * Sugar to produce a dynamic debounced function that accepts its contents/behavior at call time.
+ *
+ * Usage:
+ * ```ts
+ *      const myThrottler = throttle.d(500);
+ *      myThrottler(() => { alert('Hello world'); });
+ *      myThrottler(() => { alert('I mean: Howdy world!'); });
+ *      myThrottler((name) => { alert('Wazzap ' + name); }, 'world');
+ * ```
+ *
+ * Not documented in README as its usefulness is still uncertain.
+ */
+exports.throttle.d = (delay, skipFirst) => (0, exports.throttle)(function (fn, ...args) {
+    fn.apply(this, args);
+}, delay, skipFirst);

package/errorhandling.d.ts

@@ -1,10 +1,18 @@
 /**
- * Error subclass for thrown values that got cought and turned into an actual
- * Error, with the thrown value as the `payload` property.
+ * Error subclass for thrown NON-Error values that got turned into an actual
+ * Error, with the original thrown value as the `payload` property.
  *
  * @see https://github.com/reykjavikcity/webtools/blob/v0.2/README.md#aserror
  */
 export declare class ErrorFromPayload extends Error {
+    /**
+     * This payload property is only set if the original `throw` value was NOT
+     * `instanceof Error`.
+     *
+     * In such cases it contains the thrown value as is, and the `message`
+     * property of this `ErrorFromPayload` instance is set to the `.toString()`
+     * representation of the payload.
+     */
     payload?: unknown;
     constructor(payload: unknown);
     name: string;
@@ -50,7 +58,7 @@ export type ResultTupleObj<T, E extends Error = Error> = SuccessResult<T> | Fail
  * `[error, results]` tuple with the `result` and `error` also attached as
  * named properties.
  *
- * Works on both promises and sync callback functions.
+ * Works on both promises and (synchronous) callback functions.
  *
  * @see https://github.com/reykjavikcity/webtools/blob/v0.2/README.md#resultcatch
  */

package/errorhandling.js

@@ -2,8 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Result = exports.asError = exports.ErrorFromPayload = void 0;
 /**
- * Error subclass for thrown values that got cought and turned into an actual
- * Error, with the thrown value as the `payload` property.
+ * Error subclass for thrown NON-Error values that got turned into an actual
+ * Error, with the original thrown value as the `payload` property.
  *
  * @see https://github.com/reykjavikcity/webtools/blob/v0.2/README.md#aserror
  */

package/esm/async.d.ts

@@ -31,4 +31,43 @@ export declare function maxWait<PromiseMap extends PlainObj>(timeout: number, pr
  * @see https://github.com/reykjavikcity/webtools/blob/v0.2/README.md#promiseallobject
  */
 export declare const promiseAllObject: <T extends PlainObj>(promisesMap: T) => Promise<{ -readonly [K in keyof T]: Awaited<T[K]>; }>;
+type Cancellable<A extends Array<unknown>> = ((...args: A) => void) & {
+    /**
+     * Cancels any pending invocation of the debounced function.  \
+     * If `finish` is true and if a debounce is pending, the function is invoked
+     * before cancelling.
+     */
+    cancel(finish?: boolean): void;
+};
+/**
+ * Returns a debounced function that only runs after `delay` milliseconds
+ * of quiet-time.  \
+ * The returned function also has a nice `.cancel()` method.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.2/README.md#debounce
+ */
+export declare const debounce: {
+    <A extends Array<unknown>>(func: (...args: A) => void, delay: number, immediate?: boolean): Cancellable<A>;
+    d(delay: number, immediate?: boolean): Cancellable<[fn: (...args: Array<any>) => void, ...args: any[]]>;
+};
+type Finishable<A extends Array<unknown>> = ((...args: A) => void) & {
+    /**
+     * Immediately invokes the function if there is a pending throttle and its last
+     * invoication was throttled (cancelled).  \
+     * If `cancel` is true then only the timer is reset without invoking function.
+     */
+    finish(cancel?: boolean): void;
+};
+/**
+ * Returns a throttled function that never runs more often than
+ * every `delay` milliseconds.  \
+ * The returned function also has a nice `.finish()` method to reset the
+ * throttle timer
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.2/README.md#throttle
+ */
+export declare const throttle: {
+    <A extends Array<unknown>>(func: (...args: A) => void, delay: number, skipFirst?: boolean): Finishable<A>;
+    d(delay: number, skipFirst?: boolean): Finishable<[fn: (...args: Array<any>) => void, ...args: any[]]>;
+};
 export {};

package/esm/async.js

@@ -72,3 +72,105 @@ export const promiseAllObject = (promisesMap) => Promise.all(Object.values(promi
     }
     return resolvedMap;
 });
+/**
+ * Returns a debounced function that only runs after `delay` milliseconds
+ * of quiet-time.  \
+ * The returned function also has a nice `.cancel()` method.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.2/README.md#debounce
+ */
+/*#__NO_SIDE_EFFECTS__*/
+export const debounce = (
+/** The function to debounce */
+func, 
+/** The delay, in milliseconds, to wait before running the function */
+delay, 
+/** Whether to run the function at the start of the delay instead of the end */
+immediate) => {
+    let timeout;
+    let _args;
+    let _this;
+    const debouncedFn = function (...args) {
+        _args = args;
+        _this = this;
+        immediate && !timeout && func.apply(_this, _args);
+        timeout && clearTimeout(timeout);
+        timeout = setTimeout(() => {
+            debouncedFn.cancel(true);
+        }, delay);
+    };
+    debouncedFn.cancel = (finish) => {
+        timeout && clearTimeout(timeout);
+        finish && timeout && func.apply(_this, _args);
+        timeout = undefined;
+    };
+    return debouncedFn;
+};
+/**
+ * Sugar to produce a dynamic debounced function that accepts its contents/behavior at call time.
+ *
+ * Usage:
+ * ```ts
+ *      const myDebouncer = debounce.d(500);
+ *      myDebouncer(() => { alert('Hello world'); });
+ *      myDebouncer(() => { alert('I mean: Howdy world!'); });
+ *      myDebouncer((name) => { alert('Wazzap ' + name); }, 'world');
+ * ```
+ *
+ * Not documented in README as its usefulness is still uncertain.
+ */
+debounce.d = (delay, immediate) => debounce(function (fn, ...args) {
+    fn.apply(this, args);
+}, delay, immediate);
+/**
+ * Returns a throttled function that never runs more often than
+ * every `delay` milliseconds.  \
+ * The returned function also has a nice `.finish()` method to reset the
+ * throttle timer
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.2/README.md#throttle
+ */
+/*#__NO_SIDE_EFFECTS__*/
+export const throttle = (
+/** The function to throttle */
+func, 
+/** The delay, in milliseconds, to wait between invocations */
+delay, 
+/** Whether to skip the first invocation instead of running it immediately */
+skipFirst) => {
+    let timeout;
+    let throttled = 0;
+    let _args;
+    let _this;
+    const throttledFn = function (...args) {
+        _args = args;
+        _this = this;
+        if (!throttled) {
+            skipFirst ? throttled++ : func.apply(_this, _args);
+            timeout = setTimeout(throttledFn.finish, delay); // Go home TypeScript, you're drunk!
+        }
+        throttled++;
+    };
+    throttledFn.finish = (cancel) => {
+        timeout && clearTimeout(timeout);
+        !cancel && throttled && func.apply(_this, _args);
+        throttled = 0;
+    };
+    return throttledFn;
+};
+/**
+ * Sugar to produce a dynamic debounced function that accepts its contents/behavior at call time.
+ *
+ * Usage:
+ * ```ts
+ *      const myThrottler = throttle.d(500);
+ *      myThrottler(() => { alert('Hello world'); });
+ *      myThrottler(() => { alert('I mean: Howdy world!'); });
+ *      myThrottler((name) => { alert('Wazzap ' + name); }, 'world');
+ * ```
+ *
+ * Not documented in README as its usefulness is still uncertain.
+ */
+throttle.d = (delay, skipFirst) => throttle(function (fn, ...args) {
+    fn.apply(this, args);
+}, delay, skipFirst);

package/esm/errorhandling.d.ts

@@ -1,10 +1,18 @@
 /**
- * Error subclass for thrown values that got cought and turned into an actual
- * Error, with the thrown value as the `payload` property.
+ * Error subclass for thrown NON-Error values that got turned into an actual
+ * Error, with the original thrown value as the `payload` property.
  *
  * @see https://github.com/reykjavikcity/webtools/blob/v0.2/README.md#aserror
  */
 export declare class ErrorFromPayload extends Error {
+    /**
+     * This payload property is only set if the original `throw` value was NOT
+     * `instanceof Error`.
+     *
+     * In such cases it contains the thrown value as is, and the `message`
+     * property of this `ErrorFromPayload` instance is set to the `.toString()`
+     * representation of the payload.
+     */
     payload?: unknown;
     constructor(payload: unknown);
     name: string;
@@ -50,7 +58,7 @@ export type ResultTupleObj<T, E extends Error = Error> = SuccessResult<T> | Fail
  * `[error, results]` tuple with the `result` and `error` also attached as
  * named properties.
  *
- * Works on both promises and sync callback functions.
+ * Works on both promises and (synchronous) callback functions.
  *
  * @see https://github.com/reykjavikcity/webtools/blob/v0.2/README.md#resultcatch
  */

package/esm/errorhandling.js

@@ -1,6 +1,6 @@
 /**
- * Error subclass for thrown values that got cought and turned into an actual
- * Error, with the thrown value as the `payload` property.
+ * Error subclass for thrown NON-Error values that got turned into an actual
+ * Error, with the original thrown value as the `payload` property.
  *
  * @see https://github.com/reykjavikcity/webtools/blob/v0.2/README.md#aserror
  */

package/esm/fixIcelandicLocale.js

@@ -7,8 +7,12 @@ import { _PatchedCollator, _PatchedDateTimeFormat, _patchedDateToLocaleDateStrin
 if (!Intl.Collator.supportedLocalesOf(['is']).length) {
     Intl.Collator = _PatchedCollator;
     String.prototype.localeCompare = _patchedStringLocaleCompare;
+}
+if (!Intl.NumberFormat.supportedLocalesOf(['is']).length) {
     Intl.NumberFormat = _PatchedNumberFormat;
     Number.prototype.toLocaleString = _patchedNumberToLocaleString;
+}
+if (!Intl.DateTimeFormat.supportedLocalesOf(['is']).length) {
     Intl.DateTimeFormat = _PatchedDateTimeFormat;
     Date.prototype.toLocaleString = _patchedDateToLocaleString;
     Date.prototype.toLocaleDateString = _patchedDateToLocaleDateString;

package/esm/hooks.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Returns a stable debounced function that invokes the supplied function
+ * after the specified delay.  \
+ * When the component unmounts, any pending (debounced) calls are automatically cancelled.
+ *
+ * **NOTE:** The supplied callback does not need to be memoized. The debouncer
+ * will always invoke the last supplied version.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.2/README.md#usedebounced
+ */
+export declare const useDebounced: <A extends Array<unknown>>(
+/** The function to debounce */
+func: (...args: A) => void, 
+/** The delay, in milliseconds, to wait before running the function */
+delay: number, 
+/** Whether to run the function at the start of the delay instead of the end */
+immediate?: boolean) => ((...args: A) => void) & {
+    cancel(finish?: boolean): void;
+};
+/**
+ * Returns a stable throttler function that throttles the supplied function.
+ *
+ * **NOTE:** The supplied callback does not need to be memoized. The throttler
+ * will always invoke the last supplied version.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.2/README.md#usethrottled
+ */
+export declare const useThrottled: <A extends Array<unknown>>(
+/** The function to throttle */
+func: (...args: A) => void, 
+/** The delay, in milliseconds, to wait between invocations. */
+delay: number, 
+/** Whether to skip the first invocation instead of running it immediately. */
+skipFirst?: boolean) => ((...args: A) => void) & {
+    finish(cancel?: boolean): void;
+};

package/esm/hooks.js

@@ -0,0 +1,46 @@
+import { useEffect, useMemo, useRef } from 'react';
+import { debounce, throttle } from './async.js';
+/**
+ * Returns a stable debounced function that invokes the supplied function
+ * after the specified delay.  \
+ * When the component unmounts, any pending (debounced) calls are automatically cancelled.
+ *
+ * **NOTE:** The supplied callback does not need to be memoized. The debouncer
+ * will always invoke the last supplied version.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.2/README.md#usedebounced
+ */
+export const useDebounced = (
+/** The function to debounce */
+func, 
+/** The delay, in milliseconds, to wait before running the function */
+delay, 
+/** Whether to run the function at the start of the delay instead of the end */
+immediate) => {
+    const fn = useRef();
+    fn.current = func;
+    const debouncedFunc = useMemo(() => debounce((...args) => fn.current(...args), delay, immediate), [delay, immediate]);
+    useEffect(() => debouncedFunc.cancel, [debouncedFunc]);
+    return debouncedFunc;
+};
+/**
+ * Returns a stable throttler function that throttles the supplied function.
+ *
+ * **NOTE:** The supplied callback does not need to be memoized. The throttler
+ * will always invoke the last supplied version.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.2/README.md#usethrottled
+ */
+export const useThrottled = (
+/** The function to throttle */
+func, 
+/** The delay, in milliseconds, to wait between invocations. */
+delay, 
+/** Whether to skip the first invocation instead of running it immediately. */
+skipFirst) => {
+    const fn = useRef();
+    fn.current = func;
+    const throttledFunc = useMemo(() => throttle((...args) => fn.current(...args), delay, skipFirst), [delay, skipFirst]);
+    // NOTE: We don't need to run throttled.finish() on unmount, as the default behavior is no-op.
+    return throttledFunc;
+};

package/esm/http.d.ts

@@ -11,6 +11,7 @@ export declare const HTTP_103_EarlyHints = 103;
 export declare const HTTP_200_OK = 200;
 /** The request succeeded, and a new resource was created as a result. This is typically the response sent after POST or PUT requests. */
 export declare const HTTP_201_Created = 201;
+/** The request has been received but not yet acted upon. Another process or server handles the request. */
 export declare const HTTP_202_Accepted = 202;
 /** The returned metadata is not necessarily complete. */
 export declare const HTTP_203_NonAuthoritativeInformation = 203;

package/esm/http.js

@@ -12,7 +12,7 @@ export const HTTP_103_EarlyHints = 103;
 export const HTTP_200_OK = 200;
 /** The request succeeded, and a new resource was created as a result. This is typically the response sent after POST or PUT requests. */
 export const HTTP_201_Created = 201;
-/* The request has been received but not yet acted upon. Another process or server handles the request. */
+/** The request has been received but not yet acted upon. Another process or server handles the request. */
 export const HTTP_202_Accepted = 202;
 /** The returned metadata is not necessarily complete. */
 export const HTTP_203_NonAuthoritativeInformation = 203;

package/esm/index.d.ts

@@ -1,3 +1,4 @@
+/// <reference path="./hooks.d.ts" />
 /// <reference path="./vanillaExtract.d.ts" />
 /// <reference path="./http.d.ts" />
 /// <reference path="./async.d.ts" />

package/fixIcelandicLocale.js

@@ -9,8 +9,12 @@ const fixIcelandicLocale_privates_js_1 = require("./fixIcelandicLocale.privates.
 if (!Intl.Collator.supportedLocalesOf(['is']).length) {
     Intl.Collator = fixIcelandicLocale_privates_js_1._PatchedCollator;
     String.prototype.localeCompare = fixIcelandicLocale_privates_js_1._patchedStringLocaleCompare;
+}
+if (!Intl.NumberFormat.supportedLocalesOf(['is']).length) {
     Intl.NumberFormat = fixIcelandicLocale_privates_js_1._PatchedNumberFormat;
     Number.prototype.toLocaleString = fixIcelandicLocale_privates_js_1._patchedNumberToLocaleString;
+}
+if (!Intl.DateTimeFormat.supportedLocalesOf(['is']).length) {
     Intl.DateTimeFormat = fixIcelandicLocale_privates_js_1._PatchedDateTimeFormat;
     Date.prototype.toLocaleString = fixIcelandicLocale_privates_js_1._patchedDateToLocaleString;
     Date.prototype.toLocaleDateString = fixIcelandicLocale_privates_js_1._patchedDateToLocaleDateString;

package/hooks.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Returns a stable debounced function that invokes the supplied function
+ * after the specified delay.  \
+ * When the component unmounts, any pending (debounced) calls are automatically cancelled.
+ *
+ * **NOTE:** The supplied callback does not need to be memoized. The debouncer
+ * will always invoke the last supplied version.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.2/README.md#usedebounced
+ */
+export declare const useDebounced: <A extends Array<unknown>>(
+/** The function to debounce */
+func: (...args: A) => void, 
+/** The delay, in milliseconds, to wait before running the function */
+delay: number, 
+/** Whether to run the function at the start of the delay instead of the end */
+immediate?: boolean) => ((...args: A) => void) & {
+    cancel(finish?: boolean): void;
+};
+/**
+ * Returns a stable throttler function that throttles the supplied function.
+ *
+ * **NOTE:** The supplied callback does not need to be memoized. The throttler
+ * will always invoke the last supplied version.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.2/README.md#usethrottled
+ */
+export declare const useThrottled: <A extends Array<unknown>>(
+/** The function to throttle */
+func: (...args: A) => void, 
+/** The delay, in milliseconds, to wait between invocations. */
+delay: number, 
+/** Whether to skip the first invocation instead of running it immediately. */
+skipFirst?: boolean) => ((...args: A) => void) & {
+    finish(cancel?: boolean): void;
+};

package/hooks.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useThrottled = exports.useDebounced = void 0;
+const react_1 = require("react");
+const async_js_1 = require("./async.js");
+/**
+ * Returns a stable debounced function that invokes the supplied function
+ * after the specified delay.  \
+ * When the component unmounts, any pending (debounced) calls are automatically cancelled.
+ *
+ * **NOTE:** The supplied callback does not need to be memoized. The debouncer
+ * will always invoke the last supplied version.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.2/README.md#usedebounced
+ */
+const useDebounced = (
+/** The function to debounce */
+func, 
+/** The delay, in milliseconds, to wait before running the function */
+delay, 
+/** Whether to run the function at the start of the delay instead of the end */
+immediate) => {
+    const fn = (0, react_1.useRef)();
+    fn.current = func;
+    const debouncedFunc = (0, react_1.useMemo)(() => (0, async_js_1.debounce)((...args) => fn.current(...args), delay, immediate), [delay, immediate]);
+    (0, react_1.useEffect)(() => debouncedFunc.cancel, [debouncedFunc]);
+    return debouncedFunc;
+};
+exports.useDebounced = useDebounced;
+/**
+ * Returns a stable throttler function that throttles the supplied function.
+ *
+ * **NOTE:** The supplied callback does not need to be memoized. The throttler
+ * will always invoke the last supplied version.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.2/README.md#usethrottled
+ */
+const useThrottled = (
+/** The function to throttle */
+func, 
+/** The delay, in milliseconds, to wait between invocations. */
+delay, 
+/** Whether to skip the first invocation instead of running it immediately. */
+skipFirst) => {
+    const fn = (0, react_1.useRef)();
+    fn.current = func;
+    const throttledFunc = (0, react_1.useMemo)(() => (0, async_js_1.throttle)((...args) => fn.current(...args), delay, skipFirst), [delay, skipFirst]);
+    // NOTE: We don't need to run throttled.finish() on unmount, as the default behavior is no-op.
+    return throttledFunc;
+};
+exports.useThrottled = useThrottled;

package/http.d.ts

@@ -11,6 +11,7 @@ export declare const HTTP_103_EarlyHints = 103;
 export declare const HTTP_200_OK = 200;
 /** The request succeeded, and a new resource was created as a result. This is typically the response sent after POST or PUT requests. */
 export declare const HTTP_201_Created = 201;
+/** The request has been received but not yet acted upon. Another process or server handles the request. */
 export declare const HTTP_202_Accepted = 202;
 /** The returned metadata is not necessarily complete. */
 export declare const HTTP_203_NonAuthoritativeInformation = 203;

package/http.js

@@ -16,7 +16,7 @@ exports.HTTP_103_EarlyHints = 103;
 exports.HTTP_200_OK = 200;
 /** The request succeeded, and a new resource was created as a result. This is typically the response sent after POST or PUT requests. */
 exports.HTTP_201_Created = 201;
-/* The request has been received but not yet acted upon. Another process or server handles the request. */
+/** The request has been received but not yet acted upon. Another process or server handles the request. */
 exports.HTTP_202_Accepted = 202;
 /** The returned metadata is not necessarily complete. */
 exports.HTTP_203_NonAuthoritativeInformation = 203;

package/index.d.ts

@@ -1,3 +1,4 @@
+/// <reference path="./hooks.d.ts" />
 /// <reference path="./vanillaExtract.d.ts" />
 /// <reference path="./http.d.ts" />
 /// <reference path="./async.d.ts" />

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@reykjavik/webtools",
-	"version": "0.2.6",
+	"version": "0.2.8",
 	"description": "Misc. JS/TS helpers used by Reykjavík City's web dev teams.",
 	"main": "index.js",
 	"repository": "ssh://git@github.com:reykjavikcity/webtools.git",
@@ -44,6 +44,10 @@
 		"**/fixIcelandicLocale.js"
 	],
 	"exports": {
+		"./hooks": {
+			"import": "./esm/hooks.js",
+			"require": "./hooks.js"
+		},
 		".": {
 			"import": "./esm/index.js",
 			"require": "./index.js"