@reykjavik/webtools 0.3.5 → 0.3.6

package/CHANGELOG.md

@@ -4,11 +4,20 @@
 
 - ... <!-- Add new lines here. -->
 
+## 0.3.6
+
+_2026-02-24_
+
+- `@reykjavik/webtools/async`:
+  - feat: Add `cachifyAsync` helper for simple (yet robust) caching of async
+    functions
+
 ## 0.3.5
 
 _2026-02-18_
 
-- fix: `Result.ErrorOf<T>` not handling functions with parameters correctly
+- `@reykjavik/webtools/errorhandling`:
+  - fix: `Result.ErrorOf<T>` not handling functions with parameters correctly
 
 ## 0.3.4
 

package/README.md

@@ -30,6 +30,7 @@ bun add @reykjavik/webtools
   - [`promiseAllObject`](#promiseallobject)
   - [`maxWait`](#maxwait)
   - [`debounce`](#debounce)
+  - [`cachifyAsync`](#cachifyasync)
   - [`throttle`](#throttle)
 - [`@reykjavik/webtools/hoooks`](#reykjavikwebtoolshoooks)
   - [`useDebounced`](#usedebounced)
@@ -307,20 +308,21 @@ detection test.)
 
 **`Intl.NumberFormat` and `toLocaleString`:**
 
-- The `style: "unit"` option is not supported and prints units in Danish. (Soo
-  many units and unit-variants…)
+- The `style: "unit"` option is not supported and prints units in Danish. (So,
+  so (!!) many units and unit-variants… Impractical to handle size-wise.)
 - The `currencyDisplay: "name"` option is not supported and prints the
-  currency's full name in Danish.
+  currency's full name in Danish. (Impractical to handle size-wise.)
 
 **`Intl.DateTimeFormat` and `toLocaleDateString`:**
 
 - The `month: 'narrow'` and `weekday: 'narrow'` options are not supported, and
-  print the corresponding Danish initials.
+  print the corresponding Danish initials. (Near impossible to patch because
+  the Danish initials are ambigious)
 - For `timeZoneName` the values `"long"`, `"shortGeneric"` and `"longGeneric"`
-  will appear in Danish.
+  will appear in Danish. (Impractical to handle size-wise.)
 - The `timeStyle: 'full'` option prints the timezone names in Danish
 - The `dayPeriod` option has a couple of slight mismatches, at 5 am and 12
-  noon.
+  noon. (Completely harmless.)
 
 We eagerly accept bugfixes, additions, etc. to this module!
 
@@ -439,6 +441,67 @@ sayHello.cancel(true); // `finish` parmeter is true
 
 ---
 
+### `cachifyAsync`
+
+**Syntax:**
+`cachifyAsync<R, F extends (...args: any[]) => Promise<Result.TupleObj<R>>>(opts: { fn: F; ttl: TTL; throttle?: TTL; customTtl?: (args: Parameters<F>, result: Result.TupleObj<R>) => TTL | undefined; getKey?: (...args: Parameters<F>) => string; returnStale?: boolean }): F`
+
+Wraps an async function with a simple, robust caching layer. Returns a
+function with the same signature as `fn`, but with caching applied.
+
+The caching strategy is simple. If `fn` resolves to an error result, the error
+is cached for a short time (default: `30s`) to avoid hammering the underlying
+function, and a stale (last successful) result is returned if available. The
+error result is only while waiting for the issue to be resolved. Return stale
+(last successful) result while throttling.
+
+- No max size or eviction strategy—intended for caching a small, clearly
+  bounded number of different cache "keys" (e.g. per language).
+
+**Options:**
+
+- `fn: <T>(...args: ay[]) => Promise<Result.TupleObj<T>>` — The async function
+  to cache.
+- `ttl: TTL` — How long to cache successful results. Number values are treated
+  as seconds. (See (`TTL` type)[#type-ttl]).
+- `throttle? TTL` — The minimum time between retries for error results.
+  Numbers are treated as seconds.
+- `customTtl?: (args: Parameters<typeof fn>, result: Result.TupleObj<T>) => TTL | undefined;`
+  — set a custom TTL on success and/or error results. Return `undefined` to
+  use the default `ttl`/`throttle` values.
+- `getKey?: (...args: Parameters<typeof fn>) => string` — Creates a custom
+  cache key for the current result set. Default: `JSON.stringify(args)`.
+- `returnStale?: boolean` — Whether to return stale (last successful) result
+  when `fn` resolves to an error result. Defaults to `true`.
+
+**Example:**
+
+```ts
+import { cachifyAsync } from '@reykjavik/webtools/async';
+import { Result } from '@reykjavik/webtools/errorhandling';
+
+const fetchUser = async (id: string) =>
+  Result.ify(fetch(`/api/user/${id}`).then((r) => r.json()));
+
+const cachedFetchUser = cachifyAsync({
+  fn: fetchUser,
+  ttl: '10m',
+});
+
+// ---------------------****---------------------------------------
+// Usage:
+
+const result = await cachedFetchUser('123');
+
+if (result.error) {
+  // handle error
+} else {
+  // use result.result
+}
+```
+
+---
+
 ### `throttle`
 
 **Syntax:**
@@ -621,7 +684,7 @@ handling `ResultTupleObj` instances:
 
 - `Result.Success`
 - `Result.Fail`
-- `Result.catch`
+- `Result.catch` / `Result.ify`
 - `Result.map`
 - `Result.throw`
 
@@ -855,7 +918,9 @@ import { Result } from '@reykjavik/webtools/errorhandling';
 type ResTpl = Result.Tuple<string, Error>;
 type ResTplPromise = Promise<Result.Tuple<number, Error>>;
 type ResTplFn = (arg: unknown) => Result.Tuple<boolean, Error>;
-type ResTplPromiseFn = (arg: unknown) => Promise<Result.Tuple<Date, Error>>;
+type ResTplPromiseFn = (
+  arg: unknown
+) => Promise<Result.TupleObj<Date, Error>>;
 
 type Payload1 = Result.PayloadOf<ResTpl>; // string
 type Payload2 = Result.PayloadOf<ResTplPromise>; // number
@@ -863,6 +928,9 @@ type Payload3 = Result.PayloadOf<ResTplFn>; // boolean
 type Payload4 = Result.PayloadOf<ResTplPromiseFn>; // Date
 ```
 
+NOTE: This type also works for [`ResultTupleObj`](#type-resulttupleobj) as
+it's a subtype of `ResultTuple`.
+
 ---
 
 ### Type `Result.ErrorOf`
@@ -881,7 +949,7 @@ type ResTplPromise = Promise<Result.Tuple<number, RangeError>>;
 type ResTplFn = (arg: unknown) => Result.Tuple<boolean, RangeError>;
 type ResTplPromiseFn = (
   arg: unknown
-) => Promise<Result.Tuple<Date, RangeError>>;
+) => Promise<Result.TupleÞObj<Date, RangeError>>;
 
 type Error1 = Result.ErrorOf<ResTpl>; // RangeError
 type Error2 = Result.ErrorOf<ResTplPromise>; // RangeError
@@ -889,6 +957,9 @@ type Error3 = Result.ErrorOf<ResTplFn>; // RangeError
 type Error4 = Result.ErrorOf<ResTplPromiseFn>; // RangeError
 ```
 
+NOTE: This type also works for [`ResultTupleObj`](#type-resulttupleobj) as
+it's a subtype of `ResultTuple`.
+
 ---
 
 ## `@reykjavik/webtools/SiteImprove`

package/async.d.ts

@@ -1,4 +1,6 @@
 import { EitherObj } from '@reykjavik/hanna-utils';
+import { Result } from './errorhandling.js';
+import { TTL } from './http.js';
 type PlainObj = Record<string, unknown>;
 /**
  * Simple sleep function. Returns a promise that resolves after `length`
@@ -70,4 +72,53 @@ 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[]]>;
 };
+/**
+ * Wraps an async function with a simple, but fairly robust caching layer.
+ *
+ * Successful results are cached for `ttlMs`, while error results are
+ * throttled to avoid hammering the underlying function.
+ *
+ * Has no max size or eviction strategy; intended for caching a small,
+ * clearly bounded number of different cache "keys" (e.g. per language).
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.3/README.md#cachifyasync
+ */
+export declare const cachifyAsync: <R, F extends (...args: Array<any>) => Promise<Result.TupleObj<R>>>(opts: {
+    /** The async function to cache. */
+    fn: F;
+    /** How long to cache successful results. Number values are treated as seconds */
+    ttl: TTL;
+    /**
+     * The minimum time between retries for error results, to avoid hammering
+     * the underlying function while waiting for the issue to be (hopefully)
+     * resolved.
+     *
+     * Raw numbers are treated as seconds.
+     *
+     *  Default: '30s'
+     */
+    throttle?: TTL;
+    /**
+     * Function to optionally set a custom TTL on success and/or error results,
+     * when the promise resolves.
+     *
+     * If `undefined` is returned, the default `ttlMs` and` `throttleMs` settings
+     * are used.
+     */
+    customTtl?: (args: Parameters<F>, result: Result.TupleObj<R>) => TTL | undefined;
+    /**
+     * Creates a custom cache key for the current result set
+     *
+     * Default: `JSON.stringify` of the function arguments
+     *
+     */
+    getKey?: (...args: Parameters<F>) => string;
+    /**
+     * Whether to return stale (last successful) result when `fn` resolves to an
+     * error result.
+     *
+     * Default: `true`
+     */
+    returnStale?: boolean;
+}) => F;
 export {};

package/async.js

@@ -1,7 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.throttle = exports.debounce = exports.promiseAllObject = exports.addLag = exports.sleep = void 0;
+exports.cachifyAsync = exports.throttle = exports.debounce = exports.promiseAllObject = exports.addLag = exports.sleep = void 0;
 exports.maxWait = maxWait;
+const http_js_1 = require("./http.js");
 /**
  * Simple sleep function. Returns a promise that resolves after `length`
  * milliseconds.
@@ -183,3 +184,59 @@ exports.throttle = throttle;
 exports.throttle.d = (delay, skipFirst) => (0, exports.throttle)(function (fn, ...args) {
     fn.apply(this, args);
 }, delay, skipFirst);
+// ---------------------------------------------------------------------------
+// Wrap toSec to use a 90% shorter TTL in development mode
+const toSec = process.env.NODE_ENV === 'production' ? http_js_1.toSec : (val) => (0, http_js_1.toSec)(val) / 10;
+const DEFAULT_THROTTLING_MS = '30s';
+/**
+ * Wraps an async function with a simple, but fairly robust caching layer.
+ *
+ * Successful results are cached for `ttlMs`, while error results are
+ * throttled to avoid hammering the underlying function.
+ *
+ * Has no max size or eviction strategy; intended for caching a small,
+ * clearly bounded number of different cache "keys" (e.g. per language).
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.3/README.md#cachifyasync
+ */
+const cachifyAsync = (opts) => {
+    const { fn, getKey = (...args) => JSON.stringify(args), customTtl, returnStale } = opts;
+    // Set up the cache object
+    const TTL_SEC = toSec(opts.ttl);
+    const THROTTLING_SEC = toSec(opts.throttle || 0) || Math.min(toSec(DEFAULT_THROTTLING_MS), TTL_SEC);
+    const _cache = new Map();
+    return (async (...args) => {
+        const now = Date.now();
+        const key = getKey(...args);
+        const cached = _cache.get(key);
+        if (cached && now < cached.freshUntil) {
+            return cached.data;
+        }
+        const lastData = returnStale !== false && (cached === null || cached === void 0 ? void 0 : cached.data);
+        const entry = {
+            // Set an initial "fresh until" that's longer than TTL_SEC to cover
+            // (somewhat) safely the time it takes for the promise to resolve,
+            // so that we don't trigger multiple calls to `fn` in parallel
+            // TODO: Build in a proper AbortSignal timeout, etc. to handle this more robustly
+            freshUntil: now + (TTL_SEC + 60) * 1000,
+            data: fn(...args).then((result) => {
+                const customTtlSec = toSec((customTtl === null || customTtl === void 0 ? void 0 : customTtl(args, result)) || 0);
+                entry.freshUntil = now + (customTtlSec || TTL_SEC) * 1000;
+                if (result.error) {
+                    if (!customTtlSec) {
+                        // Set shorter TTL on errors to allow quicker retries
+                        entry.freshUntil = now + THROTTLING_SEC * 1000;
+                    }
+                    if (lastData) {
+                        // Return last known good data if available, even if it's a bit stale
+                        return lastData;
+                    }
+                }
+                return result;
+            }),
+        };
+        _cache.set(key, entry);
+        return entry.data;
+    });
+};
+exports.cachifyAsync = cachifyAsync;

package/errorhandling.d.ts

@@ -119,7 +119,7 @@ export declare namespace Result {
      * Extracts the error type `E` from a `Result.Tuple<T, E>`-like
      * type, a `Promise` of such type, or a function returning either of those.
      *
-     * @see https://github.com/reykjavikcity/webtools/blob/v0.3/README.md#type-resultpayloadof
+     * @see https://github.com/reykjavikcity/webtools/blob/v0.3/README.md#type-resulterrorof
      */
     type ErrorOf<T extends ResultTuple<unknown> | Promise<ResultTuple<unknown>> | ((...args: Array<any>) => ResultTuple<unknown> | Promise<ResultTuple<unknown>>)> = T extends [infer E, undefined?] ? E : T extends Promise<infer P> ? P extends [infer E, undefined?] ? E : never : T extends (...args: Array<any>) => infer R ? R extends [infer E, undefined?] ? E : R extends Promise<infer P> ? P extends [infer E, undefined?] ? E : never : never : never;
 }

package/esm/async.d.ts

@@ -1,4 +1,6 @@
 import { EitherObj } from '@reykjavik/hanna-utils';
+import { Result } from './errorhandling.js';
+import { TTL } from './http.js';
 type PlainObj = Record<string, unknown>;
 /**
  * Simple sleep function. Returns a promise that resolves after `length`
@@ -70,4 +72,53 @@ 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[]]>;
 };
+/**
+ * Wraps an async function with a simple, but fairly robust caching layer.
+ *
+ * Successful results are cached for `ttlMs`, while error results are
+ * throttled to avoid hammering the underlying function.
+ *
+ * Has no max size or eviction strategy; intended for caching a small,
+ * clearly bounded number of different cache "keys" (e.g. per language).
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.3/README.md#cachifyasync
+ */
+export declare const cachifyAsync: <R, F extends (...args: Array<any>) => Promise<Result.TupleObj<R>>>(opts: {
+    /** The async function to cache. */
+    fn: F;
+    /** How long to cache successful results. Number values are treated as seconds */
+    ttl: TTL;
+    /**
+     * The minimum time between retries for error results, to avoid hammering
+     * the underlying function while waiting for the issue to be (hopefully)
+     * resolved.
+     *
+     * Raw numbers are treated as seconds.
+     *
+     *  Default: '30s'
+     */
+    throttle?: TTL;
+    /**
+     * Function to optionally set a custom TTL on success and/or error results,
+     * when the promise resolves.
+     *
+     * If `undefined` is returned, the default `ttlMs` and` `throttleMs` settings
+     * are used.
+     */
+    customTtl?: (args: Parameters<F>, result: Result.TupleObj<R>) => TTL | undefined;
+    /**
+     * Creates a custom cache key for the current result set
+     *
+     * Default: `JSON.stringify` of the function arguments
+     *
+     */
+    getKey?: (...args: Parameters<F>) => string;
+    /**
+     * Whether to return stale (last successful) result when `fn` resolves to an
+     * error result.
+     *
+     * Default: `true`
+     */
+    returnStale?: boolean;
+}) => F;
 export {};

package/esm/async.js

@@ -1,3 +1,4 @@
+import { toSec as _toSec } from './http.js';
 /**
  * Simple sleep function. Returns a promise that resolves after `length`
  * milliseconds.
@@ -174,3 +175,58 @@ skipFirst) => {
 throttle.d = (delay, skipFirst) => throttle(function (fn, ...args) {
     fn.apply(this, args);
 }, delay, skipFirst);
+// ---------------------------------------------------------------------------
+// Wrap toSec to use a 90% shorter TTL in development mode
+const toSec = process.env.NODE_ENV === 'production' ? _toSec : (val) => _toSec(val) / 10;
+const DEFAULT_THROTTLING_MS = '30s';
+/**
+ * Wraps an async function with a simple, but fairly robust caching layer.
+ *
+ * Successful results are cached for `ttlMs`, while error results are
+ * throttled to avoid hammering the underlying function.
+ *
+ * Has no max size or eviction strategy; intended for caching a small,
+ * clearly bounded number of different cache "keys" (e.g. per language).
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.3/README.md#cachifyasync
+ */
+export const cachifyAsync = (opts) => {
+    const { fn, getKey = (...args) => JSON.stringify(args), customTtl, returnStale } = opts;
+    // Set up the cache object
+    const TTL_SEC = toSec(opts.ttl);
+    const THROTTLING_SEC = toSec(opts.throttle || 0) || Math.min(toSec(DEFAULT_THROTTLING_MS), TTL_SEC);
+    const _cache = new Map();
+    return (async (...args) => {
+        const now = Date.now();
+        const key = getKey(...args);
+        const cached = _cache.get(key);
+        if (cached && now < cached.freshUntil) {
+            return cached.data;
+        }
+        const lastData = returnStale !== false && (cached === null || cached === void 0 ? void 0 : cached.data);
+        const entry = {
+            // Set an initial "fresh until" that's longer than TTL_SEC to cover
+            // (somewhat) safely the time it takes for the promise to resolve,
+            // so that we don't trigger multiple calls to `fn` in parallel
+            // TODO: Build in a proper AbortSignal timeout, etc. to handle this more robustly
+            freshUntil: now + (TTL_SEC + 60) * 1000,
+            data: fn(...args).then((result) => {
+                const customTtlSec = toSec((customTtl === null || customTtl === void 0 ? void 0 : customTtl(args, result)) || 0);
+                entry.freshUntil = now + (customTtlSec || TTL_SEC) * 1000;
+                if (result.error) {
+                    if (!customTtlSec) {
+                        // Set shorter TTL on errors to allow quicker retries
+                        entry.freshUntil = now + THROTTLING_SEC * 1000;
+                    }
+                    if (lastData) {
+                        // Return last known good data if available, even if it's a bit stale
+                        return lastData;
+                    }
+                }
+                return result;
+            }),
+        };
+        _cache.set(key, entry);
+        return entry.data;
+    });
+};

package/esm/errorhandling.d.ts

@@ -119,7 +119,7 @@ export declare namespace Result {
      * Extracts the error type `E` from a `Result.Tuple<T, E>`-like
      * type, a `Promise` of such type, or a function returning either of those.
      *
-     * @see https://github.com/reykjavikcity/webtools/blob/v0.3/README.md#type-resultpayloadof
+     * @see https://github.com/reykjavikcity/webtools/blob/v0.3/README.md#type-resulterrorof
      */
     type ErrorOf<T extends ResultTuple<unknown> | Promise<ResultTuple<unknown>> | ((...args: Array<any>) => ResultTuple<unknown> | Promise<ResultTuple<unknown>>)> = T extends [infer E, undefined?] ? E : T extends Promise<infer P> ? P extends [infer E, undefined?] ? E : never : T extends (...args: Array<any>) => infer R ? R extends [infer E, undefined?] ? E : R extends Promise<infer P> ? P extends [infer E, undefined?] ? E : never : never : never;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@reykjavik/webtools",
-	"version": "0.3.5",
+	"version": "0.3.6",
 	"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",