tiny-essentials 1.28.18 → 1.29.0

package/docs/v1/libs/sw/service/TinyPushRouter.md

@@ -0,0 +1,314 @@
+# 📬 TinyPushRouter
+
+> A tiny, transport-agnostic router that sends normalized push messages to the right handler — nothing more, nothing less.
+
+`TinyPushRouter` is a small routing engine for service worker `push` events. It does **not** touch the Notification API. It only decides **which handler runs** for a given message. That separation keeps your code testable in plain Node.js, with zero browser mocks.
+
+---
+
+## 📑 Table of Contents
+
+- [✨ Why TinyPushRouter?](#-why-tinypushrouter)
+- [📦 Installation](#-installation)
+- [🚀 Quick Start](#-quick-start)
+- [🧠 Core Concepts](#-core-concepts)
+- [📖 API Reference](#-api-reference)
+- [🍳 Day-to-Day Recipes](#-day-to-day-recipes)
+- [✅ Best Practices](#-best-practices)
+- [⚠️ Gotchas](#️-gotchas)
+
+---
+
+## ✨ Why TinyPushRouter?
+
+Push handling usually turns into a giant `if / else if` chain inside `self.addEventListener('push', ...)`. That is hard to test and harder to read.
+
+TinyPushRouter gives you:
+
+| Feature | Benefit |
+| --- | --- |
+| 🎯 Exact, pattern, and fallback routes | Match `message.type` however you need |
+| 🛡️ Guards | Drop messages before any handler runs |
+| 🧩 Transport agnostic | No `Notification` API inside the router |
+| 🧪 Node-testable | Pure functions in, pure functions out |
+| 🔗 Chainable API | Fluent registration |
+
+---
+
+## 🚀 Quick Start
+
+```js
+import TinyPushRouter from 'tiny-essentials/libs/sw/service/TinyPushRouter';
+
+const router = new TinyPushRouter();
+
+// 1. Exact match on message.type
+router.on('chat:message', async (message, context) => {
+  await context.engine.showNotification(message.title, { body: message.body });
+  context.notificationShown = true;
+});
+
+// 2. Pattern match
+router.onMatch(/^order:/, async (message) => {
+  console.log('Order event received:', message.type);
+});
+
+// 3. Fallback
+router.otherwise((message) => {
+  console.log('Unhandled message type:', message.type);
+});
+
+// 4. Dispatch
+self.addEventListener('push', (event) => {
+  event.waitUntil(
+    (async () => {
+      const message = event.data.json();
+      const context = { event, message, engine: null, handled: false, notificationShown: false };
+      await router.dispatch(message, context);
+    })(),
+  );
+});
+```
+
+---
+
+## 🧠 Core Concepts
+
+### 📨 The Message
+
+Every route receives a **normalized message**. The only property the router itself reads is `message.type` (a `string`). Everything else is passed through untouched.
+
+### 🧩 The Context
+
+The `context` object is shared between the router and the active handler during a single dispatch cycle.
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `event` | `PushEvent` | The native push event. |
+| `message` | `TinyPushMessage` | The normalized message. |
+| `engine` | `TinyServiceWorkerEngine` | The engine that received the push. |
+| `handled` | `boolean` | Set to `true` to stop the chain. |
+| `notificationShown` | `boolean` | Set to `true` when a notification was displayed. |
+
+### 🛡️ Guards
+
+A guard runs **before** any handler. Return `false` to drop the message completely.
+
+```js
+router.use((message) => {
+  return message.type !== 'internal:ping'; // drop pings
+});
+```
+
+### 🔗 The Fall-Through Rule
+
+A handler that returns `false` tells the router: *"I did not handle this, keep going."* Any other return value (including `undefined`) stops the chain.
+
+---
+
+## 📖 API Reference
+
+### `use(guard)`
+
+Registers a guard. Every guard runs before the handler.
+
+- **Parameter:** `guard: TinyPushGuard`
+- **Returns:** `this` (chainable)
+- **Throws:** `TypeError` if `guard` is not a function.
+
+> 🚫 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.
+
+---
+
+### `on(type, handler)`
+
+Registers a handler for an **exact** `message.type`.
+
+- **Parameters:**
+  - `type: string` — The type to match.
+  - `handler: TinyPushHandler` — The handler.
+- **Returns:** `this` (chainable)
+- **Throws:** `TypeError` if `type` is not a non-empty string or `handler` is not a function.
+
+```js
+router.on('user:follow', (message) => {
+  console.log('New follower!');
+});
+```
+
+---
+
+### `onMatch(pattern, handler)`
+
+Registers a handler for every `message.type` that matches a **regular expression**.
+
+- **Parameters:**
+  - `pattern: RegExp` — The pattern applied to `message.type`.
+  - `handler: TinyPushHandler` — The handler.
+- **Returns:** `this` (chainable)
+- **Throws:** `TypeError` if `pattern` is not a `RegExp` or `handler` is not a function.
+
+```js
+router.onMatch(/^order:\w+$/, (message) => {
+  console.log('Order event:', message.type);
+});
+```
+
+---
+
+### `otherwise(handler)`
+
+Registers the handler used when **no other handler matches**.
+
+- **Parameter:** `handler: TinyPushHandler`
+- **Returns:** `this` (chainable)
+- **Throws:** `TypeError` if `handler` is not a function.
+
+```js
+router.otherwise((message) => {
+  console.warn('No route for:', message.type);
+});
+```
+
+---
+
+### `catch(handler)`
+
+Registers an error handler. When set, any error thrown inside a guard or handler is caught and forwarded here instead of rejecting the `dispatch` promise.
+
+- **Parameter:** `handler: (error: unknown, message: unknown) => void`
+- **Returns:** `this` (chainable)
+- **Throws:** `TypeError` if `handler` is not a function.
+
+```js
+router.catch((error, message) => {
+  console.error('Dispatch failed for', message, error);
+});
+```
+
+---
+
+### `has(type)`
+
+Reports whether a handler is registered for the given type (exact or pattern).
+
+- **Parameter:** `type: string`
+- **Returns:** `boolean`
+
+```js
+router.has('user:follow'); // true
+```
+
+---
+
+### `get size`
+
+- **Returns:** `number` — The number of registered handlers (exact + pattern).
+
+```js
+console.log(router.size); // 3
+```
+
+---
+
+### `dispatch(message, context)`
+
+Dispatches a message to the first matching handler.
+
+**Order of execution:**
+
+1. Run every guard. If one returns `false`, stop and resolve `true`.
+2. Run the exact-match handler (if any). If it returns `false`, continue.
+3. Run the first matching pattern handler. If it returns `false`, continue.
+4. Run the fallback (if any).
+5. Resolve `false` if nothing claimed the message.
+
+- **Parameters:**
+  - `message: TinyPushMessage` — The normalized message.
+  - `context: TinyPushContext` — The dispatch context.
+- **Returns:** `Promise<boolean>` — `true` when a handler claimed the message.
+- **Throws:** `TypeError` if `message` or `context` are invalid.
+
+```mermaid
+flowchart TD
+    A[dispatch] --> B{Guards pass?}
+    B -- No --> Z[Resolve true]
+    B -- Yes --> C{Exact match?}
+    C -- Yes, returns false --> D[Pattern match]
+    C -- Yes, handled --> Z
+    C -- No --> D
+    D -- matched --> Z
+    D -- none --> E{Fallback?}
+    E -- Yes --> Z
+    E -- No --> F[Resolve false]
+```
+
+---
+
+### `static get PUSH_TYPE()`
+
+Exposes the `PUSH_TYPE` constant, so consumers do not need a second import.
+
+```js
+console.log(TinyPushRouter.PUSH_TYPE);
+```
+
+---
+
+## 🍳 Day-to-Day Recipes
+
+### 🗂️ Route by feature namespace
+
+```js
+router
+  .on('chat:message', handleChat)
+  .on('chat:typing', handleTyping)
+  .onMatch(/^order:/, handleOrder);
+```
+
+### 🧪 Test a handler in isolation
+
+```js
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import TinyPushRouter from 'tiny-essentials/libs/sw/service/TinyPushRouter';
+
+test('drops ping messages', async () => {
+  const router = new TinyPushRouter();
+  let called = false;
+
+  router.use((message) => message.type !== 'internal:ping');
+  router.otherwise(() => {
+    called = true;
+  });
+
+  await router.dispatch({ type: 'internal:ping' }, {});
+  assert.equal(called, false);
+});
+```
+
+### 🚨 Centralize error reporting
+
+```js
+router.catch((error, message) => {
+  reportToSentry(error, { type: message?.type });
+});
+```
+
+---
+
+## ✅ Best Practices
+
+- 🎯 Use `on()` for known types and `onMatch()` for families of types.
+- 🛡️ Prefer guards over duplicating `if` checks inside every handler.
+- 🔗 Chain your registrations — every method returns `this`.
+- 🧪 Keep handlers free of `Notification` calls; put them behind the engine in `context`.
+
+---
+
+## ⚠️ Gotchas
+
+- 🔁 **Stateful regex:** avoid the global (`g`) flag in `onMatch` patterns. `RegExp.prototype.test` is stateful with `g` and will skip matches between calls.
+- 🧊 **`has()` does not check the fallback.** It only reports exact and pattern routes.
+- 🧱 **`size` counts routes, not the fallback.** A router with only `otherwise()` reports `size === 0`.
+- 🛑 **A thrown error with no `catch()` handler rejects the `dispatch` promise.** Always register a `catch()` in production.