tiny-essentials 1.28.18 → 1.29.0

package/dist/v1/libs/sw/service/TinyPushRouter.d.mts

@@ -0,0 +1,138 @@
+export type TinyPushContext = {
+    /**
+     * - The native push event.
+     */
+    event: PushEvent;
+    /**
+     * - The normalized message.
+     */
+    message: import('./shared/TinyPushPayload.mjs').TinyPushMessage;
+    /**
+     * - The engine that received the push.
+     */
+    engine: import('./TinyServiceWorkerEngine.mjs').default;
+    /**
+     * - Set to `true` to stop the chain.
+     */
+    handled: boolean;
+    /**
+     * - Set to `true` when a notification was displayed.
+     */
+    notificationShown: boolean;
+};
+export type TinyPushHandler = (message: import('./shared/TinyPushPayload.mjs').TinyPushMessage, context: TinyPushContext) => Promise<boolean | void> | boolean | void;
+export type TinyPushGuard = (message: import('./shared/TinyPushPayload.mjs').TinyPushMessage, context: TinyPushContext) => Promise<boolean> | boolean;
+/**
+ * @file Routes a normalized push message to a handler, based on `message.type`.
+ *
+ * The router is transport agnostic: it never touches the Notification API. That
+ * responsibility belongs to the handler, which keeps the class testable in Node.
+ */
+/**
+ * Describes the mutable state shared between the router and the active handler
+ * during a single dispatch cycle.
+ *
+ * @typedef {Object} TinyPushContext
+ * @property {PushEvent} event - The native push event.
+ * @property {import('./shared/TinyPushPayload.mjs').TinyPushMessage} message - The normalized message.
+ * @property {import('./TinyServiceWorkerEngine.mjs').default} engine - The engine that received the push.
+ * @property {boolean} handled - Set to `true` to stop the chain.
+ * @property {boolean} notificationShown - Set to `true` when a notification was displayed.
+ */
+/**
+ * Handles a normalized push message that matched a route.
+ *
+ * @callback TinyPushHandler
+ * @param {import('./shared/TinyPushPayload.mjs').TinyPushMessage} message - The normalized message.
+ * @param {TinyPushContext} context - The dispatch context.
+ * @returns {Promise<boolean|void>|boolean|void} Return `false` to fall through to the next handler.
+ */
+/**
+ * Decides whether a normalized push message is allowed to reach a handler.
+ *
+ * @callback TinyPushGuard
+ * @param {import('./shared/TinyPushPayload.mjs').TinyPushMessage} message - The normalized message.
+ * @param {TinyPushContext} context - The dispatch context.
+ * @returns {Promise<boolean>|boolean} Return `false` to drop the message.
+ */
+/**
+ * Routes normalized push messages to registered handlers based on `message.type`.
+ *
+ * @beta
+ */
+declare class TinyPushRouter {
+    #private;
+    static get PUSH_TYPE(): Readonly<{
+        NOTIFICATION: "notification";
+        DATA: "data";
+        SYNC: "sync";
+        COMMAND: "command";
+        UNKNOWN: "unknown";
+    }>;
+    /**
+     * Registers a guard. Every guard runs before the handler.
+     *
+     * A guard that returns `false` drops the message: no handler runs and the
+     * `push` promise resolves with `true`, so the browser does not show a
+     * generic "This site has been updated in the background" notification.
+     *
+     * @param {TinyPushGuard} guard - The guard to register.
+     * @returns {this} The router, for chaining.
+     * @throws {TypeError} If `guard` is not a function.
+     */
+    use(guard: TinyPushGuard): this;
+    /**
+     * Registers a handler for an exact `message.type`.
+     *
+     * @param {string} type - The type to match.
+     * @param {TinyPushHandler} handler - The handler.
+     * @returns {this} The router, for chaining.
+     * @throws {TypeError} If `type` is not a non-empty string or `handler` is not a function.
+     */
+    on(type: string, handler: TinyPushHandler): this;
+    /**
+     * Registers a handler for every `message.type` that matches a regular expression.
+     *
+     * @param {RegExp} pattern - The pattern applied to `message.type`.
+     * @param {TinyPushHandler} handler - The handler.
+     * @returns {this} The router, for chaining.
+     * @throws {TypeError} If `pattern` is not a RegExp or `handler` is not a function.
+     */
+    onMatch(pattern: RegExp, handler: TinyPushHandler): this;
+    /**
+     * Registers the handler used when no other handler matches.
+     *
+     * @param {TinyPushHandler} handler - The fallback handler.
+     * @returns {this} The router, for chaining.
+     * @throws {TypeError} If `handler` is not a function.
+     */
+    otherwise(handler: TinyPushHandler): this;
+    /**
+     * Registers an error handler.
+     *
+     * @param {(error: unknown, message: unknown) => void} handler - The error handler.
+     * @returns {this} The router, for chaining.
+     * @throws {TypeError} If `handler` is not a function.
+     */
+    catch(handler: (error: unknown, message: unknown) => void): this;
+    /**
+     * Reports whether a handler is registered for the given type.
+     *
+     * @param {string} type - The type to look up.
+     * @returns {boolean} `true` when a handler is registered.
+     */
+    has(type: string): boolean;
+    /** @returns {number} The number of registered handlers. */
+    get size(): number;
+    /**
+     * Dispatches a message to the first matching handler.
+     *
+     * @param {import('./shared/TinyPushPayload.mjs').TinyPushMessage} message - The normalized message.
+     * @param {TinyPushContext} context - The dispatch context.
+     * @returns {Promise<boolean>} `true` when a handler claimed the message.
+     * @throws {TypeError} If `message` or `context` are invalid.
+     */
+    dispatch(message: import('./shared/TinyPushPayload.mjs').TinyPushMessage, context: TinyPushContext): Promise<boolean>;
+}
+export default TinyPushRouter;
+//# sourceMappingURL=TinyPushRouter.d.mts.map

package/dist/v1/libs/sw/service/TinyPushRouter.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TinyPushRouter.d.mts","sourceRoot":"","sources":["../../../../../../src/v1/libs/sw/service/TinyPushRouter.mjs"],"names":[],"mappings":"AAaG,YAAkB,eAAe,GACjC;;;;IAAsB,KAAK,EAAhB,SAAS,CACpB;;;;IAAmE,OAAO,EAA/D,OAAO,8BAA8B,EAAE,eAAe,CACjE;;;;IAA4D,MAAM,EAAvD,OAAO,+BAA+B,EAAE,OAAO,CAC1D;;;;IAAoB,OAAO,EAAhB,OAAO,CAClB;;;;IAAoB,iBAAiB,EAA1B,OAAO,CACpB;CAAA,CAAA;AAKE,YAAU,eAAe,GACzB,CAAgE,OAAO,EAA/D,OAAO,8BAA8B,EAAE,eAC/C,EAAyB,OAAO,EAAxB,eACR,KAAU,OAAO,CAAC,OAAO,GAAC,IAAI,CAAC,GAAC,OAAO,GAAC,IAC1C,CAAA;AAKE,YAAU,aAAa,GACvB,CAAgE,OAAO,EAA/D,OAAO,8BAA8B,EAAE,eAC/C,EAAyB,OAAO,EAAxB,eACR,KAAU,OAAO,CAAC,OAAO,CAAC,GAAC,OAC7B,CAAA;AAnCD;;;;;GAKG;AAEH;;;;;;;;;;GAUG;AAEH;;;;;;;GAOG;AAEH;;;;;;;GAOG;AAEH;;;;GAIG;AACH,cAAM,cAAc;;IAElB,MAAM,KAAK,SAAS;;;;;;OAEnB;IAiBD;;;;;;;;;;OAUG;IACH,GAAG,CAAC,KAAK,EAJE,aAIF,GAHI,IAAI,CAShB;IAED;;;;;;;OAOG;IACH,EAAE,CAAC,IAAI,EALI,MAKJ,EAAE,OAAO,EAJL,eAIK,GAHH,IAAI,CAYhB;IAED;;;;;;;OAOG;IACH,OAAO,CAAC,OAAO,EALJ,MAKI,EAAE,OAAO,EAJb,eAIa,GAHX,IAAI,CAYhB;IAED;;;;;;OAMG;IACH,SAAS,CAAC,OAAO,EAJN,eAIM,GAHJ,IAAI,CAShB;IAED;;;;;;OAMG;IACH,KAAK,CAAC,OAAO,EAJF,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,KAAK,IAIpC,GAHA,IAAI,CAShB;IAED;;;;;OAKG;IACH,GAAG,CAAC,IAAI,EAHG,MAGH,GAFK,OAAO,CAKnB;IAED,2DAA2D;IAC3D,IAAI,IAAI,IADM,MAAM,CAGnB;IAED;;;;;;;OAOG;IACG,QAAQ,CAAC,OAAO,EALX,OAAO,8BAA8B,EAAE,eAK5B,EAAE,OAAO,EAJpB,eAIoB,GAHlB,OAAO,CAAC,OAAO,CAAC,CA2C5B;CACF;eAEc,cAAc"}

package/dist/v1/libs/sw/service/TinyPushRouter.mjs

@@ -0,0 +1,201 @@
+import { PUSH_TYPE } from '../utils.mjs';
+/**
+ * @file Routes a normalized push message to a handler, based on `message.type`.
+ *
+ * The router is transport agnostic: it never touches the Notification API. That
+ * responsibility belongs to the handler, which keeps the class testable in Node.
+ */
+/**
+ * Describes the mutable state shared between the router and the active handler
+ * during a single dispatch cycle.
+ *
+ * @typedef {Object} TinyPushContext
+ * @property {PushEvent} event - The native push event.
+ * @property {import('./shared/TinyPushPayload.mjs').TinyPushMessage} message - The normalized message.
+ * @property {import('./TinyServiceWorkerEngine.mjs').default} engine - The engine that received the push.
+ * @property {boolean} handled - Set to `true` to stop the chain.
+ * @property {boolean} notificationShown - Set to `true` when a notification was displayed.
+ */
+/**
+ * Handles a normalized push message that matched a route.
+ *
+ * @callback TinyPushHandler
+ * @param {import('./shared/TinyPushPayload.mjs').TinyPushMessage} message - The normalized message.
+ * @param {TinyPushContext} context - The dispatch context.
+ * @returns {Promise<boolean|void>|boolean|void} Return `false` to fall through to the next handler.
+ */
+/**
+ * Decides whether a normalized push message is allowed to reach a handler.
+ *
+ * @callback TinyPushGuard
+ * @param {import('./shared/TinyPushPayload.mjs').TinyPushMessage} message - The normalized message.
+ * @param {TinyPushContext} context - The dispatch context.
+ * @returns {Promise<boolean>|boolean} Return `false` to drop the message.
+ */
+/**
+ * Routes normalized push messages to registered handlers based on `message.type`.
+ *
+ * @beta
+ */
+class TinyPushRouter {
+    static #PUSH_TYPE = PUSH_TYPE;
+    static get PUSH_TYPE() {
+        return TinyPushRouter.#PUSH_TYPE;
+    }
+    /** @type {Map<string, TinyPushHandler>} */
+    #exact = new Map();
+    /** @type {Array<{ source: string, regex: RegExp, handler: TinyPushHandler }>} */
+    #patterns = [];
+    /** @type {TinyPushGuard[]} */
+    #guards = [];
+    /** @type {TinyPushHandler|null} */
+    #fallback = null;
+    /** @type {((error: unknown, message: unknown) => void)|null} */
+    #onError = null;
+    /**
+     * Registers a guard. Every guard runs before the handler.
+     *
+     * A guard that returns `false` drops the message: no handler runs and the
+     * `push` promise resolves with `true`, so the browser does not show a
+     * generic "This site has been updated in the background" notification.
+     *
+     * @param {TinyPushGuard} guard - The guard to register.
+     * @returns {this} The router, for chaining.
+     * @throws {TypeError} If `guard` is not a function.
+     */
+    use(guard) {
+        if (typeof guard !== 'function') {
+            throw new TypeError('[TinyPushRouter] use: guard must be a function.');
+        }
+        this.#guards.push(guard);
+        return this;
+    }
+    /**
+     * Registers a handler for an exact `message.type`.
+     *
+     * @param {string} type - The type to match.
+     * @param {TinyPushHandler} handler - The handler.
+     * @returns {this} The router, for chaining.
+     * @throws {TypeError} If `type` is not a non-empty string or `handler` is not a function.
+     */
+    on(type, handler) {
+        if (typeof type !== 'string' || type.trim() === '') {
+            throw new TypeError('[TinyPushRouter] on: type must be a non-empty string.');
+        }
+        if (typeof handler !== 'function') {
+            throw new TypeError('[TinyPushRouter] on: handler must be a function.');
+        }
+        this.#exact.set(type, handler);
+        return this;
+    }
+    /**
+     * Registers a handler for every `message.type` that matches a regular expression.
+     *
+     * @param {RegExp} pattern - The pattern applied to `message.type`.
+     * @param {TinyPushHandler} handler - The handler.
+     * @returns {this} The router, for chaining.
+     * @throws {TypeError} If `pattern` is not a RegExp or `handler` is not a function.
+     */
+    onMatch(pattern, handler) {
+        if (!(pattern instanceof RegExp)) {
+            throw new TypeError('[TinyPushRouter] onMatch: pattern must be a RegExp.');
+        }
+        if (typeof handler !== 'function') {
+            throw new TypeError('[TinyPushRouter] onMatch: handler must be a function.');
+        }
+        this.#patterns.push({ source: pattern.source, regex: pattern, handler });
+        return this;
+    }
+    /**
+     * Registers the handler used when no other handler matches.
+     *
+     * @param {TinyPushHandler} handler - The fallback handler.
+     * @returns {this} The router, for chaining.
+     * @throws {TypeError} If `handler` is not a function.
+     */
+    otherwise(handler) {
+        if (typeof handler !== 'function') {
+            throw new TypeError('[TinyPushRouter] otherwise: handler must be a function.');
+        }
+        this.#fallback = handler;
+        return this;
+    }
+    /**
+     * Registers an error handler.
+     *
+     * @param {(error: unknown, message: unknown) => void} handler - The error handler.
+     * @returns {this} The router, for chaining.
+     * @throws {TypeError} If `handler` is not a function.
+     */
+    catch(handler) {
+        if (typeof handler !== 'function') {
+            throw new TypeError('[TinyPushRouter] catch: handler must be a function.');
+        }
+        this.#onError = handler;
+        return this;
+    }
+    /**
+     * Reports whether a handler is registered for the given type.
+     *
+     * @param {string} type - The type to look up.
+     * @returns {boolean} `true` when a handler is registered.
+     */
+    has(type) {
+        if (this.#exact.has(type))
+            return true;
+        return this.#patterns.some(({ regex }) => regex.test(type));
+    }
+    /** @returns {number} The number of registered handlers. */
+    get size() {
+        return this.#exact.size + this.#patterns.length;
+    }
+    /**
+     * Dispatches a message to the first matching handler.
+     *
+     * @param {import('./shared/TinyPushPayload.mjs').TinyPushMessage} message - The normalized message.
+     * @param {TinyPushContext} context - The dispatch context.
+     * @returns {Promise<boolean>} `true` when a handler claimed the message.
+     * @throws {TypeError} If `message` or `context` are invalid.
+     */
+    async dispatch(message, context) {
+        if (typeof message !== 'object' || message === null) {
+            throw new TypeError('[TinyPushRouter] dispatch: message must be a non-null object.');
+        }
+        if (typeof context !== 'object' || context === null) {
+            throw new TypeError('[TinyPushRouter] dispatch: context must be a non-null object.');
+        }
+        try {
+            for (const guard of this.#guards) {
+                const allowed = await guard(message, context);
+                if (allowed === false)
+                    return true;
+            }
+            const handler = this.#exact.get(message.type);
+            if (handler) {
+                const result = await handler(message, context);
+                if (result !== false)
+                    return true;
+            }
+            for (const { regex, handler: patternHandler } of this.#patterns) {
+                if (!regex.test(message.type))
+                    continue;
+                const result = await patternHandler(message, context);
+                if (result !== false)
+                    return true;
+            }
+            if (this.#fallback) {
+                await this.#fallback(message, context);
+                return true;
+            }
+            return false;
+        }
+        catch (error) {
+            if (this.#onError) {
+                this.#onError(error, message);
+                return true;
+            }
+            throw error;
+        }
+    }
+}
+export default TinyPushRouter;