@reykjavik/webtools 0.3.5 → 0.3.7

package/esm/alertsStore/index.d.ts

@@ -0,0 +1,201 @@
+import * as v from 'valibot';
+declare const messageSchema: v.UnionSchema<[v.StringSchema<undefined>, v.ArraySchema<v.UnionSchema<[v.StringSchema<undefined>, v.ObjectSchema<{
+    readonly tag: v.LiteralSchema<"a", undefined>;
+    readonly text: v.StringSchema<undefined>;
+    readonly href: v.StringSchema<undefined>;
+    readonly target: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly hrefLang: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly lang: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+}, undefined>, v.ObjectSchema<{
+    readonly tag: v.LiteralSchema<"strong", undefined>;
+    readonly text: v.StringSchema<undefined>;
+}, undefined>], undefined>, undefined>], undefined>;
+export type AlertMessage = v.InferOutput<typeof messageSchema>;
+type _AlertNotification<Level, Type, Flag> = {
+    level: Level;
+    message: AlertMessage;
+    type?: Type;
+    flags?: Array<Flag>;
+    duration?: number;
+    id: string;
+};
+declare const defaultAlertLevels: readonly ["info", "warning", "success", "error"];
+declare const defaultDurations: {
+    BLINK: number;
+    SHORT: number;
+    MEDIUM: number;
+    LONG: number;
+    XLONG: number;
+    INDEFINITE: number;
+};
+/**
+ * A configuration object for the `createAlerter` factory function, that allows
+ * the customization of all of the accepted alert values and durations.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.3/README.md#type-alerterconfig
+ */
+export type AlerterConfig<Level extends string = (typeof defaultAlertLevels)[number], Type extends string = string, Flag extends string = string, Duration extends string = keyof typeof defaultDurations, Durations extends Record<Duration, number> = Record<Duration, number>> = {
+    /**
+     * Identifier for the alerts store, used to create the key to persist alerts
+     * in `sessionStorage` (or other provided storage).
+     *
+     * Only required if you need to create multiple independent alert stores in
+     * the same app.
+     *
+     * Default: `"app~alerts"`
+     */
+    key?: string;
+    /**
+     * The allowed alert "levels". The returned `alerter` object will have a
+     * named dispatcher method for each level.
+     *
+     * Default: `['info', 'warning', 'success', 'error']`
+     */
+    levels?: Array<Level>;
+    /**
+     * The allowed alert "types", which can be used to, for example, to dispatch
+     * both "toasts" vs. "static alert banners" via the same store.
+     *
+     * This can also be used for more basic styling or categorization purposes.
+     *
+     * Default: no restrictions, any string value is allowed.
+     */
+    types?: Array<Type>;
+    /**
+     * The allowed alert "flags", which can be changed during the lifetime of
+     * an alert using the `setFlags` function on the `AlertInfo` object.
+     *
+     * This can be used for styling or any other purpose you like.
+     *
+     * Default: no restriction, any string value is allowed.
+     */
+    flags?: Array<Flag>;
+    /**
+     * Optionally controls the allowed alert "duration" names and their lengths
+     * in milliseconds.
+     *
+     * Default:
+     * ```ts
+     *  {
+          BLINK: 2_000,
+          SHORT: 4_000,
+          MEDIUM: 8_000,
+          LONG: 16_000,
+          XLONG: 32_000,
+          INDEFINITE: 0,
+        }
+      * ```
+      */
+    durations?: Durations;
+    /**
+     * Default duration to use for alerts if no duration is specified when
+     * dispatching.
+     *
+     * Default: `SHORT` if using the default durations, otherwise the default
+     * is `0` (indefinite)
+     */
+    defaultDuration?: Durations extends Record<infer D, number> ? D : never;
+    /**
+     * Optional custom storage object to use instead of `sessionStorage` (the
+     * default) for persisting alerts across page reloads, etc.
+     */
+    storage?: {
+        getItem: (key: string) => string | undefined | null;
+        setItem: (key: string, value: string) => void;
+    };
+};
+/**
+ * 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
+ */
+export declare const createAlerterStore: <Level extends string = (typeof defaultAlertLevels)[number], Type extends string = string, Flag extends string = string, Duration extends string = keyof typeof defaultDurations>(cfg?: AlerterConfig<Level, Type, Flag, Duration>) => {
+    /**
+     * 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: Record<Level, (payload: {
+        /**
+         * A simple string containing the alert message.
+         *
+         * For sightly more complex alert messages pass an array of strings
+         * (representing text nodes), objects with `tag: 'a'` and hyperlink-related
+         * props, or `tag: 'strong'` objects for minimal rich formatting.
+         *
+         * (Assume that such array itmes will be rendered with whitespace between
+         * them.)
+         */
+        message: AlertMessage;
+        /**
+         * Allows distinguishing between different "types" of alerts, for example,
+         * to dispatch both "toasts" vs. "static alert banners" via the same store.
+         *
+         * May also be used for more basic styling or categorization purposes.
+         */
+        type?: Type;
+        /**
+         * Flag values can be changed during the lifetime of
+         * an alert using the `setFlags` function on each `AlertInfo` object.
+         *
+         * Flags may be used for styling or any other purpose you like.
+         */
+        flags?: Array<Flag>;
+        /**
+         * Hint for how long the notification should remain displayed before
+         * auto-dismissing.
+         *
+         * **NOTE:** The alerter store does not implement auto-dismissing. However,
+         * this value can be used by UI component that actually render the alert,
+         * by calling each `AlertInfo`'s `dismiss` method.
+         */
+        duration?: Duration;
+        delay?: number;
+    }) => void>;
+    /**
+     * 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: (callback: (notifications: Array<_AlertNotification<Level, Type, Flag> & {
+        /** Dispatcher function that dismisses/hides/removes the callback */
+        dismiss: () => void;
+        /**
+         * Dispatcher function that can be used to set a simple "flag" on the alert,
+         * which can be used for styling or other purposes.
+         */
+        setFlags: (value: Flag | Array<Flag> | ((flags: Array<Flag> | undefined) => Array<Flag> | undefined)) => void;
+    }>, meta: {
+        type: "clear" | "add" | "change";
+        /** IDs of the alerts that were added or cleared in this event. */
+        ids: Array<string>;
+    }) => void) => () => void;
+};
+/**
+ * Utility type for inferring the payload shape of the dispatching methods of a
+ * specific `alerter` singleton.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.3/README.md#createalerterstore
+ */
+export type InferAlerterPayload<F extends Record<string, (...args: Array<any>) => void>> = F extends Record<string, (payload: infer P) => void> ? P : never;
+/**
+ * Utility type for inferring the alert info object shape received by the
+ * callbacks of a specific alerter `subscribe` function.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.3/README.md#createalerterstore
+ */
+export type InferSubscriberAlerts<F extends (callback: (alerts: Array<unknown>, meta: unknown) => void) => () => void> = F extends (callback: (alerts: Array<infer A>) => void) => () => void ? A : never;
+export {};

package/esm/alertsStore/index.js

@@ -0,0 +1,280 @@
+import { dumbId, ObjectFromEntries } from '@reykjavik/hanna-utils';
+import * as v from '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__*/
+export 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: 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 = 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,
+    };
+};

package/esm/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/esm/alertsStore/react.js

@@ -0,0 +1,58 @@
+import React, { useEffect, useState } from '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__*/
+export const makeReactSubscription = (subscribe) => {
+    const useAlerter = () => {
+        const [alerts, setAlerts] = useState([]);
+        useEffect(() => subscribe((alerts) => setAlerts(alerts)), []);
+        return alerts;
+    };
+    const AlertsContainer = (props) => {
+        const alerts = useAlerter();
+        return props.children(alerts);
+    };
+    return {
+        useAlerter,
+        AlertsContainer,
+    };
+};
+/**
+ * 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__*/
+export 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.createElement(Link, { key: i, ...linkProps }, text),
+                ];
+            }
+            return [' ', React.createElement(part.tag, { key: i }, part.text)];
+        });
+};
+/**
+ * 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__*/
+renderAlertMessage.withLinkRenderer =
+    (LinkCompnent) => (message) => renderAlertMessage(message, LinkCompnent);

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 `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 {};