@reykjavik/webtools 0.3.5 → 0.3.7

package/alertsStore/index.js

@@ -0,0 +1,317 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAlerterStore = void 0;
+const hanna_utils_1 = require("@reykjavik/hanna-utils");
+const v = __importStar(require("valibot"));
+const messageSchema = v.union([
+    v.string(),
+    v.array(v.union([
+        // text nodes
+        v.string(),
+        // link elements
+        v.object({
+            tag: v.literal('a'),
+            text: v.string(),
+            href: v.string(),
+            target: v.optional(v.string()),
+            hrefLang: v.optional(v.string()),
+            lang: v.optional(v.string()),
+        }),
+        // strong/bold elements
+        v.object({
+            tag: v.literal('strong'),
+            text: v.string(),
+        }),
+    ])),
+]);
+// ---------------------------------------------------------------------------
+const defaultKey = 'app~alerts';
+const defaultAlertLevels = ['info', 'warning', 'success', 'error'];
+const defaultDurations = {
+    BLINK: 2000,
+    SHORT: 4000,
+    MEDIUM: 8000,
+    LONG: 16000,
+    XLONG: 32000,
+    INDEFINITE: 0,
+};
+const defaultDefaultDuration = 'SHORT';
+const storeKeys = {};
+/**
+ * Factory function that creates an alerter store singleton with optional
+ * configuration for the genarated alerts.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.3/README.md#createalerterstore
+ */
+/*#__NO_SIDE_EFFECTS__*/
+const createAlerterStore = (cfg = {}) => {
+    const STORE_KEY = cfg.key || defaultKey;
+    if (storeKeys[STORE_KEY]) {
+        throw new Error(`An alerter store with key "${STORE_KEY}" already exists.`);
+    }
+    storeKeys[STORE_KEY] = true;
+    const storgae = cfg.storage || (typeof sessionStorage !== 'undefined' ? sessionStorage : undefined);
+    const alertLevels = cfg.levels || defaultAlertLevels;
+    const durations = cfg.durations || defaultDurations;
+    const DEFAULT_DURATION = cfg.durations
+        ? cfg.defaultDuration
+        : defaultDefaultDuration;
+    const _notificationSchema = v.object({
+        level: v.picklist(alertLevels),
+        message: messageSchema,
+        type: v.optional(cfg.types ? v.picklist(cfg.types) : v.string()),
+        flags: v.optional(v.array(cfg.flags ? v.picklist(cfg.flags) : v.string())),
+        duration: v.optional(v.number()),
+        id: v.string(),
+    });
+    const alertsSchema = v.object({
+        active: v.array(_notificationSchema),
+        pending: v.array(v.intersect([_notificationSchema, v.object({ showAt: v.number() })])),
+    });
+    /** Global array of inflight alert notifications */
+    const alerts = {
+        active: [],
+        pending: [],
+    };
+    const _saveAlertsToStorage = storgae
+        ? () => storgae.setItem(STORE_KEY, JSON.stringify(alerts))
+        : () => undefined;
+    // ---------------------------------------------------------------------------
+    /** Array of callbacks to call whenever alerts are activated or cleared */
+    const subscriptions = [];
+    let isEmitting;
+    /** Calls all subscribed callbacks with the currently active alerts and the event type. */
+    const emitEvent = (meta, callback) => {
+        if (callback) {
+            setTimeout(() => callback(alerts.active, meta));
+            return;
+        }
+        _saveAlertsToStorage();
+        clearTimeout(isEmitting);
+        // For consistency, always delay pinging the subscribed callbacks until next tick.
+        isEmitting = setTimeout(() => {
+            subscriptions.forEach((callback) => {
+                callback(alerts.active, meta);
+            });
+        });
+    };
+    const clearAlert = (id) => {
+        let found = false;
+        alerts.active.some((alert, idx) => {
+            if (alert.id === id) {
+                alerts.active = alerts.active.toSpliced(idx, 1);
+                found = true;
+                return true;
+            }
+        });
+        alerts.pending.some((alert, idx) => {
+            if (alert.id === id) {
+                alerts.pending = alerts.pending.toSpliced(idx, 1);
+                found = true;
+                return true;
+            }
+        });
+        if (found) {
+            emitEvent({ type: 'clear', ids: [id] });
+        }
+    };
+    // ---------------------------------------------------------------------------
+    const _unsubscribe = (callback) => {
+        const idx = subscriptions.indexOf(callback);
+        if (idx > -1) {
+            subscriptions.splice(idx, 1);
+        }
+    };
+    const subscribe = (callback) => {
+        if (subscriptions.indexOf(callback) === -1) {
+            subscriptions.push(callback);
+            // Should we allow opting-out of immediate invocations via function param?
+            if (alerts.active.length) {
+                emitEvent({
+                    type: 'add',
+                    ids: alerts.active.map((t) => t.id),
+                }, callback);
+            }
+        }
+        return () => _unsubscribe(callback);
+    };
+    // ---------------------------------------------------------------------------
+    const buildNotification = (_payload, level) => {
+        // Strip away duration and delay (not part of the notification object)
+        const { duration, delay, ...payload } = _payload;
+        const durationMs = durations[(duration || DEFAULT_DURATION || '')] || 0;
+        return {
+            ...payload,
+            level,
+            id: (0, hanna_utils_1.dumbId)(), // Make unique ID for the notification
+            ...(durationMs && { duration: durationMs }),
+            ...(delay && delay > 50 && { showAt: Date.now() + delay }),
+        };
+    };
+    // add dismiss and setFlags dispatcher functions
+    // this way they stay stable across updates to the same alert, which can be useful for UI components that want to update or dismiss an alert after it's been rendered.
+    const addMethodsToAlertInfo = (notification) => {
+        const id = notification.id;
+        return {
+            ...notification,
+            dismiss: () => clearAlert(id),
+            setFlags: (value) => {
+                const notification = alerts.active.find((t) => t.id === id);
+                if (!notification) {
+                    return;
+                }
+                const oldFlags = notification.flags;
+                const flags = typeof value === 'string'
+                    ? [value]
+                    : Array.isArray(value)
+                        ? [...value]
+                        : value(notification.flags);
+                if (flags === oldFlags) {
+                    return;
+                }
+                alerts.active = alerts.active.toSpliced(alerts.active.findIndex((t) => t.id === id), 1, { ...notification, flags });
+                emitEvent({ type: 'change', ids: [id] });
+            },
+        };
+    };
+    const preparePendingAlertActivation = ({ id, showAt }) => {
+        setTimeout(() => {
+            const idx = alerts.pending.findIndex((t) => t.id === id);
+            if (idx === -1) {
+                return;
+            }
+            // Find and remove the pending in alert in one fell swoop
+            const { showAt, ...clonedAsActive } = alerts.pending.splice(idx, 1)[0];
+            alerts.active = [...alerts.active, addMethodsToAlertInfo(clonedAsActive)];
+            emitEvent({ type: 'add', ids: [id] });
+        }, showAt - Date.now());
+    };
+    const _addAlert = (payload, level) => {
+        const notification = buildNotification(payload, level);
+        if (!notification.showAt) {
+            // Notification starts active. Clone the array.
+            alerts.active = [...alerts.active, addMethodsToAlertInfo(notification)];
+            emitEvent({ type: 'add', ids: [notification.id] });
+            return;
+        }
+        // Set up delayed dispatch of the notification
+        // Store it as pending
+        alerts.pending.push(notification);
+        // Persist the updated alerts state immediately
+        _saveAlertsToStorage();
+        // Set up a timer for make it active
+        preparePendingAlertActivation(notification);
+    };
+    const alerter = (0, hanna_utils_1.ObjectFromEntries)(alertLevels.map((level) => [
+        level,
+        (payload) => _addAlert(payload, level),
+    ]));
+    // ---------------------------------------------------------------------------
+    // On module load, read saved alerts from the storage (def. `sessionStorage`),
+    // if available.
+    // This allows us to persist alerts across page reloads,
+    // but NOT across tabs or browser sessions.
+    storgae &&
+        (() => {
+            const storedAlerts = storgae.getItem(STORE_KEY);
+            if (!storedAlerts) {
+                return;
+            }
+            try {
+                // NOTE: This TypeAssertion is wrong rn and only becomes true after
+                // `addMethodsToAlertInfo` is called on the active alerts.
+                // Also TS has a hard time understanding the dynamically generated
+                // schema and that they're actually correct in terms of the configuration
+                // type params `Level`, `Type` and `Flag`.
+                const paesed = v.parse(alertsSchema, JSON.parse(storedAlerts));
+                alerts.pending = paesed.pending;
+                alerts.active = paesed.active.map(addMethodsToAlertInfo);
+            }
+            catch (e) {
+                console.error('Failed to parse stored alerts:', e);
+                return;
+            }
+            const now = Date.now();
+            const newActive = [];
+            // Check pending alerts and set up timers, unless they should already
+            // be active, in which case move them to active immediately.
+            alerts.pending = alerts.pending.filter((alert) => {
+                if (alert.showAt <= now) {
+                    // Remove pending alerts that should now be active. Store them in `newActive`
+                    newActive.push(alert);
+                    return false;
+                }
+                // Keep the rest, and set up timers to activate them later.
+                preparePendingAlertActivation(alert);
+                return true;
+            });
+            // Append `newActive` to the active alerts array
+            alerts.active.push(...newActive
+                // Make sure alerts with earlier `showAt` are shown first
+                .sort((a, b) => a.showAt - b.showAt)
+                // remove showAt, not part of active alerts
+                .map(({ showAt, ...rest }) => addMethodsToAlertInfo(rest)));
+            // Save the (possibly) cleaned up alerts back to the storage, because why not. :-D
+            _saveAlertsToStorage();
+        })();
+    return {
+        /**
+         * Singleton object with methods for showing alerts of different levels.
+         * Pass a payload object to the method of the level you want to dispatch,
+         * and the alert will be added to the store.
+         *
+         * Use `subscribeToAlerts` elsewhere in the app to subscribe to alert
+         * notifications and display them.
+         *
+         * @see https://github.com/reykjavikcity/webtools/blob/v0.3/README.md#createalerterstore
+         */
+        alerter,
+        /**
+         * Subscribes to alert events. The provided callback will be called whenever a
+         * alert is added or cleared.
+         *
+         * The callback is called immediately upon subscription if there are already
+         * active alerts.
+         *
+         * Returns an unsubscribe function that can be called to stop receiving alert
+         * events.
+         *
+         * @see https://github.com/reykjavikcity/webtools/blob/v0.3/README.md#createalerterstore
+         */
+        subscribe,
+    };
+};
+exports.createAlerterStore = createAlerterStore;

package/alertsStore/react.d.ts

@@ -0,0 +1,36 @@
+import React, { ReactNode } from 'react';
+import { AlertMessage } from './index.js';
+type SubsScriber<AlertInfo> = (callback: (alerts: Array<AlertInfo>, _type: string) => void) => () => void;
+/**
+ * Factory function that creates a React subscription hook and a container
+ * component linked to a specific alerter store subscibe function.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.3/README.md#makereactsubscription
+ */
+export declare const makeReactSubscription: <AlertInfo>(subscribe: SubsScriber<AlertInfo>) => {
+    useAlerter: () => AlertInfo[];
+    AlertsContainer: (props: {
+        children: (alerts: Array<AlertInfo>) => ReactNode;
+    }) => React.ReactNode;
+};
+/**
+ * Helper to render an alerter alert message, which can be a simple string or a
+ * more complex array of strings and objects representing links and rich (bold)
+ * text formatting.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.3/README.md#renderalertmessage
+ */
+export declare const renderAlertMessage: {
+    (message: AlertMessage, linkComponent?: renderAlertMessage.LinkRenderer): ReactNode;
+    withLinkRenderer(LinkCompnent: renderAlertMessage.LinkRenderer): (message: AlertMessage) => React.ReactNode;
+};
+export declare namespace renderAlertMessage {
+    type LinkRendererProps = Omit<Extract<AlertMessage[number], {
+        tag: 'a';
+    }>, 'tag' | 'text'> & {
+        children: ReactNode;
+    };
+    export type LinkRenderer = (props: LinkRendererProps) => ReactNode;
+    export {};
+}
+export {};

package/alertsStore/react.js

@@ -0,0 +1,96 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderAlertMessage = exports.makeReactSubscription = void 0;
+const react_1 = __importStar(require("react"));
+/**
+ * Factory function that creates a React subscription hook and a container
+ * component linked to a specific alerter store subscibe function.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.3/README.md#makereactsubscription
+ */
+/*#__NO_SIDE_EFFECTS__*/
+const makeReactSubscription = (subscribe) => {
+    const useAlerter = () => {
+        const [alerts, setAlerts] = (0, react_1.useState)([]);
+        (0, react_1.useEffect)(() => subscribe((alerts) => setAlerts(alerts)), []);
+        return alerts;
+    };
+    const AlertsContainer = (props) => {
+        const alerts = useAlerter();
+        return props.children(alerts);
+    };
+    return {
+        useAlerter,
+        AlertsContainer,
+    };
+};
+exports.makeReactSubscription = makeReactSubscription;
+/**
+ * Helper to render an alerter alert message, which can be a simple string or a
+ * more complex array of strings and objects representing links and rich (bold)
+ * text formatting.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.3/README.md#renderalertmessage
+ */
+/*#__NO_SIDE_EFFECTS__*/
+const renderAlertMessage = (message, linkComponent) => {
+    const Link = linkComponent || 'a';
+    return typeof message === 'string'
+        ? message
+        : message.flatMap((part, i) => {
+            if (typeof part === 'string') {
+                return ` ${part}`;
+            }
+            if (part.tag === 'a') {
+                const { text, tag, ...linkProps } = part;
+                return [
+                    ' ',
+                    react_1.default.createElement(Link, { key: i, ...linkProps }, text),
+                ];
+            }
+            return [' ', react_1.default.createElement(part.tag, { key: i }, part.text)];
+        });
+};
+exports.renderAlertMessage = renderAlertMessage;
+/**
+ * Retrns a curried version of `renderAlertMessage` that uses the provided
+ * `LinkComponent` for rendering links in alert messages.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.3/README.md#renderalertmessagewithlinkrenderer
+ */
+/*#__NO_SIDE_EFFECTS__*/
+exports.renderAlertMessage.withLinkRenderer =
+    (LinkCompnent) => (message) => (0, exports.renderAlertMessage)(message, LinkCompnent);

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 `ttl` and` `throttle` 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,60 @@ 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
+ */
+/*#__NO_SIDE_EFFECTS__*/
+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;
 }