tiny-essentials 1.28.18 → 1.29.0

package/docs/v1/libs/sw/service/shared/TinyPushPayload.md

@@ -0,0 +1,316 @@
+# 📬 TinyPushPayload
+
+> A tiny, isomorphic contract for **Web Push** messages. 🚀
+> One single source of truth shared between your **Service Worker** and your **page**.
+
+[![Version](https://img.shields.io/badge/schema-v1-blue)](#-versioning)
+[![Module](https://img.shields.io/badge/module-ESM-green)](#-installation)
+[![License](https://img.shields.io/badge/license-MIT-lightgrey)](#)
+
+---
+
+## 📖 Table of Contents
+
+1. [What is this?](#-what-is-this)
+2. [Why it exists](#-why-it-exists)
+3. [Installation](#-installation)
+4. [Core concepts](#-core-concepts)
+5. [API Reference](#-api-reference)
+   - [`TinyPushPayload.VERSION`](#-tinypushpayloadversion)
+   - [`TinyPushPayload.MAX_TTL`](#-tinypushpayloadmax_ttl)
+   - [`TinyPushPayload.PUSH_TYPE`](#-tinypushpayloadpush_type)
+   - [`from(raw)`](#-fromraw)
+   - [`fromEvent(event)`](#-fromeventevent)
+   - [`isExpired(message, now)`](#-isExpiredmessage-now)
+   - [`toNotification(message, defaults)`](#-tonotificationmessage-defaults)
+6. [Type definitions](#-type-definitions)
+8. [Error handling](#-error-handling)
+9. [Best practices](#-best-practices)
+
+---
+
+## ✨ What is this?
+
+`TinyPushPayload` is a **stateless utility class** that normalizes, validates and
+converts Web Push payloads.
+
+It is **isomorphic on purpose**:
+
+| Environment       | What it does                                                       |
+| ----------------- | ------------------------------------------------------------------ |
+| 🧑‍💻 **Page**        | Builds and validates the payload *before* it reaches the backend.  |
+| ⚙️ **Service Worker** | Parses the incoming `push` event and turns it into a notification. |
+
+Because both sides import the **same file**, the message contract can never
+drift out of sync. 🎯
+
+---
+
+## 🧠 Why it exists
+
+Web Push payloads arrive as **untrusted strings** over the network. Anything can
+be inside them. This class gives you:
+
+- 🛡️ **Strict validation** — every field is type-checked before use.
+- 🧊 **Immutable output** — every returned message is frozen with `Object.freeze`.
+- 🔁 **One-shot safe** — reads the `PushMessageData` stream exactly once.
+- 🧩 **Zero dependencies** — pure ECMAScript, no runtime libraries.
+
+---
+
+## 📦 Installation
+
+This module is part of the project. Import it with a **relative path** (ESM only):
+
+```javascript
+import TinyPushPayload from 'tiny-essentials/libs/sw/service/shared/TinyPushPayload';
+```
+
+---
+
+## 🧩 Core concepts
+
+### The message shape
+
+Every message is a plain object that follows the `TinyPushMessage` contract:
+
+```javascript
+{
+  v: 1,                          // 🔢 schema version
+  type: 'order:shipped',        // 🏷️ message type (from PUSH_TYPE)
+  id: 'evt_123',                 // 🆔 optional unique id
+  topic: 'orders',               // 📁 optional topic
+  expiresAt: 1735689600000,      // ⏰ optional expiration (ms)
+  ttl: 3600,                     // ⏳ optional TTL (seconds, clamped)
+  data: { orderId: 'A1' },       // 📦 optional custom data
+  notification: { /* ... */ }    // 🔔 optional notification descriptor
+}
+```
+
+### The `PUSH_TYPE.UNKNOWN` fallback
+
+If the incoming payload has no valid `type`, the class falls back to
+`PUSH_TYPE.UNKNOWN`. This guarantees the `type` field is **never** `undefined`.
+
+---
+
+## 📚 API Reference
+
+### 🔢 `TinyPushPayload.VERSION`
+
+**Type:** `number` — default `1`
+
+The current payload schema version. Used as the fallback for the `v` field.
+
+```javascript
+console.log(TinyPushPayload.VERSION); // 1
+```
+
+---
+
+### ⏳ `TinyPushPayload.MAX_TTL`
+
+**Type:** `number` — value `2419200` (28 days, in seconds)
+
+The maximum allowed TTL. Any `ttl` above this value is clamped down to it.
+
+```javascript
+console.log(TinyPushPayload.MAX_TTL); // 2419200
+```
+
+---
+
+### 🏷️ `TinyPushPayload.PUSH_TYPE`
+
+**Type:** `Object` (read-only getter)
+
+A passthrough to the shared `PUSH_TYPE` enum. Handy so consumers do not need a
+second import.
+
+```javascript
+TinyPushPayload.PUSH_TYPE.UNKNOWN; // 'unknown'
+```
+
+---
+
+### 🏗️ `from(raw)`
+
+Normalizes an **untrusted** value into a frozen `TinyPushMessage`.
+
+| Parameter | Type      | Description                       |
+| --------- | --------- | --------------------------------- |
+| `raw`     | `unknown` | The value received from the wire. |
+
+**Returns:** `TinyPushMessage` — a frozen, normalized message.
+
+**Throws:** `TypeError` if `raw` is not a non-null object or is an array.
+
+```javascript
+const message = TinyPushPayload.from({
+  type: 'order:shipped',
+  ttl: 99999999, // 👈 will be clamped to MAX_TTL
+});
+
+console.log(message.ttl); // 2419200
+Object.isFrozen(message); // true 🧊
+```
+
+**Normalization rules:**
+
+| Field          | Rule                                                       |
+| -------------- | ---------------------------------------------------------- |
+| `v`            | Kept if `number`, else `VERSION`.                          |
+| `type`         | Kept if non-empty string, else `PUSH_TYPE.UNKNOWN`.        |
+| `id`           | Kept only if `string`.                                     |
+| `topic`        | Kept only if `string`.                                     |
+| `expiresAt`    | Kept only if `number`.                                     |
+| `ttl`          | Clamped to `[0, MAX_TTL]` and truncated.                   |
+| `data`         | Kept only if a non-null, non-array object.                 |
+| `notification` | Normalized via the private `#normalizeNotification`.       |
+
+---
+
+### 📥 `fromEvent(event)`
+
+Reads the payload of a `push` event **exactly once**.
+
+> ⚠️ **Why a dedicated method?**
+> `PushMessageData` is a **one-shot stream**. Calling `json()` and then `text()`
+> throws a `TypeError`. This method reads the body once and parses it manually,
+> so you never have to think about it.
+
+| Parameter | Type       | Description             |
+| --------- | ---------- | ----------------------- |
+| `event`   | `PushEvent`| The native push event.  |
+
+**Returns:** `Promise<TinyPushMessage>` — never `null`.
+
+**Throws:** `TypeError` if `event` is not an object or has no `data` property.
+
+```javascript
+self.addEventListener('push', async (event) => {
+  const message = await TinyPushPayload.fromEvent(event);
+  console.log(message.type);
+});
+```
+
+**Fallback behavior:**
+
+| Situation                        | Result                                             |
+| -------------------------------- | -------------------------------------------------- |
+| `event.data` is `null`           | `{ v, type: UNKNOWN }`                             |
+| `text()` throws                  | `{ v, type: UNKNOWN }`                             |
+| Body is an empty string          | `{ v, type: UNKNOWN }`                             |
+| Body is not valid JSON           | `{ v, type: UNKNOWN, notification: { title, body } }` |
+| Body is valid JSON               | Parsed via [`from()`](#-fromraw).                  |
+
+---
+
+### ⏰ `isExpired(message, now)`
+
+Checks whether a message is past its expiration time.
+
+| Parameter | Type             | Default      | Description                    |
+| --------- | ---------------- | ------------ | ------------------------------ |
+| `message` | `TinyPushMessage`| —            | The message to inspect.        |
+| `now`     | `number`         | `Date.now()` | Reference time in milliseconds.|
+
+**Returns:** `boolean` — `true` when the message must be discarded.
+
+**Throws:** `TypeError` if `message` is not a non-null object or `now` is not a
+finite number.
+
+```javascript
+if (TinyPushPayload.isExpired(message)) {
+  return; // 🗑️ too late, drop it
+}
+```
+
+> 💡 A message **without** `expiresAt` is **never** considered expired.
+
+---
+
+### 🔔 `toNotification(message, defaults)`
+
+Converts a message into the `{ title, options }` object expected by
+`showNotification`.
+
+| Parameter  | Type                            | Default | Description             |
+| ---------- | ------------------------------- | ------- | ----------------------- |
+| `message`  | `TinyPushMessage`               | —       | The normalized message. |
+| `defaults` | `TinyPushNotificationDefaults`  | `{}`    | Fallback values.        |
+
+**Returns:** `{ title: string, options: NotificationOptions & { data: object } }`
+
+**Throws:** `TypeError` if `message` is not a non-null object.
+
+```javascript
+const { title, options } = TinyPushPayload.toNotification(message, {
+  defaultIcon: '/icons/default.png',
+  defaultUrl: '/',
+});
+
+await self.registration.showNotification(title, options);
+```
+
+**What lands inside `options.data`:**
+
+| Key        | Source                                             |
+| ---------- | -------------------------------------------------- |
+| `url`      | `notification.url` → `defaults.defaultUrl` → `'/'` |
+| `actions`  | Map of `action → url` built from `notification.actions`. |
+| `pushId`   | `message.id`                                       |
+| `pushType` | `message.type`                                     |
+
+---
+
+## 🧬 Type definitions
+
+### `TinyPushMessage`
+
+| Property       | Type                     | Required | Description                        |
+| -------------- | ------------------------ | -------- | ---------------------------------- |
+| `v`            | `number`                 | ✅       | Schema version.                    |
+| `type`         | `string`                 | ✅       | Message type.                      |
+| `id`           | `string`                 | ❌       | Unique id.                         |
+| `topic`        | `string`                 | ❌       | Grouping topic.                    |
+| `expiresAt`    | `number`                 | ❌       | Expiration timestamp (ms).         |
+| `ttl`          | `number`                 | ❌       | Time-to-live in seconds.           |
+| `data`         | `Record<string, unknown>`| ❌       | Custom data.                       |
+| `notification` | `TinyPushNotification`   | ❌       | Notification descriptor.           |
+
+### `TinyPushNotificationDefaults`
+
+| Property        | Type     | Description          |
+| --------------- | -------- | -------------------- |
+| `defaultIcon`   | `string` | Fallback icon.       |
+| `defaultBadge`  | `string` | Fallback badge.      |
+| `defaultUrl`    | `string` | Fallback click URL.  |
+
+---
+
+## 🚨 Error handling
+
+Every method validates its arguments and throws a **specific** error type:
+
+| Method             | Throws      | When                                          |
+| ------------------ | ----------- | --------------------------------------------- |
+| `from`             | `TypeError` | `raw` is not a non-null object / is an array. |
+| `fromEvent`        | `TypeError` | `event` is not a valid `PushEvent`.          |
+| `isExpired`        | `TypeError` | `message` invalid or `now` not finite.        |
+| `toNotification`   | `TypeError` | `message` is not a non-null object.           |
+| `#normalizeNotification` | `TypeError` | `notification.title` is missing/empty.  |
+
+> 💡 `fromEvent` is the **only** method that never throws for bad payloads — it
+> always resolves to a safe `UNKNOWN` message. This is intentional: a malformed
+> push must never crash the Service Worker.
+
+---
+
+## ✅ Best practices
+
+- 🧊 **Never mutate** a returned message. It is frozen — use `from()` again.
+- 🛡️ **Always validate** on the page *and* on the Service Worker.
+- ⏰ **Always check** `isExpired()` before showing a notification.
+- 🏷️ **Always handle** `PUSH_TYPE.UNKNOWN` in your `switch` statements.
+- 🔢 **Never hardcode** the TTL limit — use `TinyPushPayload.MAX_TTL`.

package/docs/v1/libs/text/TinyI18.md

@@ -46,6 +46,14 @@ await TinyI18.mergeLocaleFiles({
 
 ### Properties 🛠️
 
+#### `destroyed` 🔹
+
+Indicates whether the instance has been destroyed.
+
+* **Type:** `boolean`
+
+---
+
 #### `currentLocale` 🔹
 
 The currently selected locale, or `null` if only the default locale is active.
@@ -86,6 +94,14 @@ Whether strict mode is enabled.
 
 ---
 
+#### `acceptNullResults` 🔹
+
+Whether null results are accepted when a translation is missing.
+
+* **Type:** `boolean`
+
+---
+
 #### `basePath` 🔹
 
 Base directory path used in `"file"` mode to locate locale JSON files.
@@ -191,8 +207,8 @@ Resolves a key exactly in the provided locale order.
 
 **Parameters:**
 
-| Name    | Type       | Description                    |
-| ------- | ---------- | ------------------------------ |
+| Name   | Type     | Description                               |
+| ------- | -------- | ----------------------------------------- |
 | `order` | `string[]` | Array of locale codes to check |
 | `key`   | `string`   | Exact key to look up           |
 
@@ -206,10 +222,10 @@ Resolves a key by matching regex patterns in locale tables.
 
 **Parameters:**
 
-| Name    | Type       | Description                               |
-| ------- | ---------- | ----------------------------------------- |
-| `order` | `string[]` | Array of locale codes in resolution order |
-| `key`   | `string`   | Key to match against patterns             |
+| Name               | Type     | Description                               |
+| ------------------ | -------- | ----------------------------------------- |
+| `order`            | `string[]` | Array of locale codes to check |
+| `key`              | `string`   | Input string to test against regex patterns |
 
 **Returns:** `any` – Value associated with matched pattern, or `undefined`
 
@@ -227,10 +243,10 @@ Converts a raw translation entry into a final string for display.
 
 **Parameters:**
 
-| Name     | Type     | Description                           |                                |                       |
-| -------- | -------- | ------------------------------------- | ------------------------------ | --------------------- |
-| `value`  | `string` | HelperCallback                        | { \$fn: string; args?: any }\` | Raw translation entry |
-| `params` | `Dict`   | Optional parameters for interpolation |                                |                       |
+| Name     | Type                                                              | Description                                                               |                       |
+| -------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------ | --------------------- |
+| `value`  | `string` | `HelperCallback`                        | `{ $fn: string; args?: any }` | Raw translation entry |
+| `params` | `Dict`   | Optional parameters for interpolation |                                                               |
 
 **Returns:** `string` – Materialized result
 
@@ -242,10 +258,10 @@ Interpolates `{named}` placeholders in a string using given parameters.
 
 **Parameters:**
 
-| Name       | Type     | Description                       |
-| ---------- | -------- | --------------------------------- |
-| `template` | `string` | Template string with placeholders |
-| `params`   | `Dict`   | Values to interpolate             |
+| Name       | Type         | Description                                |
+| ---------- | ------------ | ------------------------------------------ |
+| `template` | `string`     | Template string with placeholders |
+| `params`   | `Dict`       | Values to interpolate             |
 
 **Returns:** `string` – Interpolated string
 
@@ -257,9 +273,9 @@ Safely retrieves a nested property using dot notation.
 
 **Parameters:**
 
-| Name   | Type     | Description                          |
-| ------ | -------- | ------------------------------------ |
-| `obj`  | `Dict`   | Object to retrieve from              |
+| Name   | Type  | Description                               |
+| ------ | ----- | ----------------------------------------- |
+| `obj`  | `Dict` | Object to retrieve from              |
 | `path` | `string` | Dot-separated path (e.g., `"a.b.c"`) |
 
 **Returns:** `any` – Value at path or `undefined`
@@ -298,9 +314,9 @@ Removes a previously loaded locale from memory (except default).
 
 **Parameters:**
 
-| Name     | Type     | Description           |
-| -------- | -------- | --------------------- |
-| `locale` | `string` | Locale code to unload |
+| Name     | Type     | Description                 |
+| -------- | -------- | --------------------------- |
+| `locale` | `string` | Locale code                 |
 
 ---
 
@@ -314,11 +330,11 @@ Loads a locale JSON file and flattens it into internal maps (file mode only).
 
 * Dot-flattens nested keys
 * Compiles `$pattern` entries into RegExp
-* Preserves `$fn` placeholders for helper resolution
+* Preserves `$fn` references for later resolution via helpers
 
 **Parameters:**
 
-| Name     | Type         | Description         |
+| Name     | Type         | Description |
 | -------- | ------------ | ------------------- |
 | `locale` | `LocaleCode` | Locale code to load |
 
@@ -333,7 +349,7 @@ Strict mode → throws on invalid regex; otherwise returns a never-matching rege
 
 **Parameters:**
 
-| Name  | Type     | Description                    |
+| Name  | Type     | Description |
 | ----- | -------- | ------------------------------ |
 | `src` | `string` | Regex source string (no flags) |
 
@@ -350,11 +366,11 @@ Normalizes a JSON value from file mode into internal representation.
 
 **Parameters:**
 
-| Name | Type     | Description |                |
-| ---- | -------- | ----------- | -------------- |
-| `v`  | \`string | FileValue\` | Raw JSON value |
+| Name | Type | Description |                |
+| ---- | ---- | -------------- | -------------- |
+| `v`  | `string | FileValue` | Raw JSON value |
 
-**Returns:** `string | { $fn: string, args?: any }`
+**Returns:** `string | { $fn: string; args?: any }`
 
 ---
 
@@ -376,7 +392,7 @@ Creates a new TinyI18 instance for managing localized strings and patterns.
 
 **Parameters:**
 
-| Name      | Type             | Description          |
+| Name      | Type             | Description             |
 | --------- | ---------------- | -------------------- |
 | `options` | `TinyI18Options` | Configuration object |
 
@@ -399,10 +415,10 @@ Registers a helper function for function-based entries or `$fn` references.
 
 **Parameters:**
 
-| Name   | Type             | Description          |
-| ------ | ---------------- | -------------------- |
-| `name` | `string`         | Helper function name |
-| `fn`   | `HelperCallback` | Callback function    |
+| Name   | Type     | Description         |
+| ------ | -------- | -------------------- |
+| `name` | `string` | Helper function name |
+| `fn` | `HelperCallback` | Callback function    |
 
 ---
 
@@ -412,23 +428,23 @@ Removes a previously registered helper function.
 
 **Parameters:**
 
-| Name   | Type     | Description              |
-| ------ | -------- | ------------------------ |
-| `name` | `string` | Name of helper to remove |
+| Name     | Type     | Description |
+| -------- | -------- | ------------------------ |
+| `name` | `string` | Name of the helper to remove |
 
-**Returns:** `boolean` – `true` if removed, `false` if not found
+**Returns:** `boolean` – `true` if the helper was removed, `false` if it was not found
 
 ---
 
 ### `loadLocaleLocal(locale, data)` 📦
 
-Loads or updates locale data in-memory (local mode only).
+Loads or updates a locale data in-memory (local mode only).
 
 **Parameters:**
 
-| Name     | Type         | Description      |
-| -------- | ------------ | ---------------- |
-| `locale` | `LocaleCode` | Locale code      |
+| Name     | Type     | Description |
+| -------- | -------- | ---------------- |
+| `locale` | `LocaleCode` | Locale code |
 | `data`   | `Dict`       | Translation data |
 
 ---
@@ -437,14 +453,14 @@ Loads or updates locale data in-memory (local mode only).
 
 Sets the currently selected locale. In file mode, loads from disk.
 
-* Keeps only default + selected locale in memory
+* Keeps only the default + selected locale in memory
 * Unloads previous selected locale
 
 **Parameters:**
 
-| Name     | Type         | Description |                                             |
-| -------- | ------------ | ----------- | ------------------------------------------- |
-| `locale` | \`LocaleCode | null\`      | Locale code, or `null` to keep only default |
+| Name     | Type | Description |                                             |
+| -------- | ------------------------------------------- | ------------------------------------------------ |
+| `locale` | `LocaleCode | null` | Locale code, or `null` to keep only default |
 
 **Returns:** `Promise<void>`
 
@@ -460,9 +476,9 @@ Resolves a translation by **exact key**.
 
 | Name      | Type             | Description                                      |
 | --------- | ---------------- | ------------------------------------------------ |
-| `key`     | `string`         | Translation key (dot.notation)                   |
+| `key`     | `string`         | Translation key (dot.notation) |
 | `params`  | `Dict`           | Optional parameters for interpolation or helpers |
-| `options` | `ResolveOptions` | Optional resolution overrides                    |
+| `options` | `ResolveOptions` | Optional resolution overrides |
 
 **Returns:** `any` – Usually `string`, but may be HTMLElement, DocumentFragment, or helper return type
 
@@ -478,10 +494,10 @@ Resolves a translation by **regex pattern match**.
 
 **Parameters:**
 
-| Name      | Type             | Description                            |
-| --------- | ---------------- | -------------------------------------- |
-| `key`     | `string`         | Input string to match against patterns |
-| `options` | `ResolveOptions` | Optional resolution overrides          |
+| Name     | Type     | Description                                      |
+| -------- | -------- | ------------------------------------------------ |
+| `key`     | `string` | Input string to match against regex patterns |
+| `options` | `ResolveOptions` | Optional resolution overrides |
 
 **Returns:** `any` – Translation value
 
@@ -496,8 +512,6 @@ Clears all loaded locales except the default.
 * Selected locale becomes `null`
 * In file mode, non-default locales are unloaded
 
-**Returns:** `void`
-
 ---
 
 ### `getStatsForLocale(locale)` 📊
@@ -506,10 +520,20 @@ Returns statistics for a specific locale.
 
 **Parameters:**
 
-| Name     | Type         | Description            |
-| -------- | ------------ | ---------------------- |
-| `locale` | `LocaleCode` | Locale code to inspect |
+| Name     | Type     | Description |
+| -------- | -------- | ---------------------- |
+| `locale` | `string` | Locale code to inspect |
 
 **Returns:** `StatLocale` – Locale stats including number of strings, patterns, and flags
 
-**Throws:** Error if locale is not registered
+**Throws:** Error if the locale is not registered
+
+---
+
+### `destroy()` 🗑️
+
+Destroys the TinyI18 instance, clearing all internal maps and references to free up memory. Once destroyed, the instance cannot be reused.
+
+**Throws:** `Error` if the instance has already been destroyed.
+
+**Returns:** `void`