tiny-essentials 1.28.19 → 1.29.0

package/docs/v1/libs/utils/TinyThrottledApi.md

@@ -0,0 +1,219 @@
+# 🚀 TinyThrottledApi Documentation
+
+`TinyThrottledApi` is a professional-grade utility designed to manage asynchronous operations. It acts as a "gatekeeper" for your API calls, ensuring you do not overwhelm a server by sending too many requests at once (**Concurrency Control**) and helping you stay within rate limits (**Rate Throttling**).
+
+## 📋 Table of Contents
+1. [Core Concepts](#core-concepts)
+2. [Getting Started](#getting-started)
+3. [API Reference](#api-reference)
+    * [Constructor](#constructorconcurrencylimit-api-timeoutinstance)
+    * [Methods](#methods)
+    * [Getters](#getters)
+    * [Setters](#setters)
+    * [Events](#events)
+4. [Practical Examples](#practical-examples)
+5. [Monitoring & Debugging](#monitoring--debugging)
+
+---
+
+## 🧠 Core Concepts
+
+To use this library effectively, you must understand the two problems it solves:
+
+### 1. Concurrency Control 🚦
+If you try to fetch 1,000 items from a database simultaneously, your application might crash or the server might block your IP. 
+**The Solution:** `TinyThrottledApi` limits the number of active requests. If the limit is 5, and you request 10, only 5 will run immediately; the other 5 will wait in a queue until a slot opens up.
+
+### 2. Rate Throttling ⏱️
+Even if you only run 5 requests at a time, sending them too quickly in "bursts" can trigger security filters.
+**The Solution:** By integrating `TinyTimeout`, the API can introduce a dynamic delay between requests. This spreads the load over a longer period, making your traffic pattern look more natural and less aggressive.
+
+---
+
+## 🚀 Getting Started
+
+### Installation Context
+This module expects the following dependencies to be present in your project structure:
+* `tiny-essentials/libs/utils/TinyPromiseQueue` (For managing the waiting list).
+* `tiny-essentials/basics/promiseUtils` (Specifically the `waitForTrue` function).
+* `tiny-essentials/libs/math/TinyTimeout` (For regulating execution frequency).
+
+### Basic Initialization
+```javascript
+import TinyThrottledApi from 'tiny-essentials/libs/utils/TinyThrottledApi';
+
+// A mock API function to simulate a network request
+const mockApi = async (id) => {
+  console.log(`🚀 Fetching data for ID: ${id}`);
+  return new Promise((resolve) => setTimeout(() => resolve(`Data ${id}`), 1000));
+};
+
+// Create an instance: Max 3 concurrent requests
+const throttledApi = new TinyThrottledApi(3, mockApi);
+```
+
+---
+
+## 🛠️ API Reference
+
+### `constructor(concurrencyLimit, api, timeoutInstance)`
+Initializes the throttled controller.
+
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+| `concurrencyLimit` | `number` | Must be a positive integer. Defines max simultaneous tasks. |
+| `api` | `Function` | The target asynchronous function to execute. |
+| `timeoutInstance` | `TinyTimeout \| null` | (Optional) An instance to control request frequency. |
+
+**Throws:**
+* `TypeError`: If `concurrencyLimit` is not a positive number or `api` is not a function.
+* `TypeError`: If `timeoutInstance` is provided but is not a `TinyTimeout` instance.
+
+### `exec(...args)`
+The primary method to execute your API calls.
+
+* **Returns:** `Promise<ReturnType<API>>`.
+* **Behavior:** 
+  1. Checks if a slot is available.
+  2. If yes, executes immediately.
+  3. If no, adds the task to the `TinyPromiseQueue` and waits for a slot to become free.
+* **Task Tracking:** Each task is assigned a unique `UUID` used in emitted events for precise tracking.
+
+### Methods
+| Method | Description |
+| :--- | :--- |
+| `exec(...args)` | Executes the API function respecting concurrency and throttling. |
+| `destroy()` | Cleans up the instance, removing all listeners and stopping pending tasks. |
+
+### Getters
+| Getter | Type | Description |
+| :--- | :--- | :--- |
+| `api` | `Function` | The original API function provided during initialization. |
+| `queue` | `TinyPromiseQueue` | Returns the internal queue instance managing pending tasks. |
+| `concurrencyLimit` | `number` | The current maximum number of simultaneous requests. |
+| `timeoutInstance` | `TinyTimeout \| null` | The current `TinyTimeout` instance used for rate limiting. |
+| `timeoutValue` | `number` | The current base delay multiplier in milliseconds. |
+| `timeoutLimit` | `number \| null` | The current maximum delay cap. |
+| `activeCount` | `number` | The number of requests currently running. |
+| `queuedCount` | `number` | The number of tasks currently waiting in the queue. |
+| `isDestroyed` | `boolean` | Indicates whether the instance has been destroyed. |
+| `timeoutFirst` | `boolean` | Indicates if the delay is applied *before* the first request in a cycle. |
+
+### Setters
+| Setter | Parameter | Description |
+| :--- | :--- | :--- |
+| `concurrencyLimit` | `number` | Sets a new maximum number of simultaneous requests. |
+| `timeoutValue` | `number` | Sets a new base delay multiplier in milliseconds. |
+| `timeoutLimit` | `number` | Sets a new maximum delay cap. |
+| `timeoutFirst` | `boolean` | If `true`, delay is applied before waiting for a slot. If `false`, delay is applied after. |
+
+### Events
+The `TinyThrottledApi` extends `EventEmitter` and emits the following events:
+
+#### Task Lifecycle Events
+| Event | Argument | Description |
+| :--- | :--- | :--- |
+| `ExecTask` | `id` (string) | Emitted when a task begins its execution. |
+| `TaskEnded` | `id` (string) | Emitted when a task completes (whether it succeeded or failed). |
+| `WaitingTask` | `id` (string) | Emitted when a task is placed into the queue because the limit was reached. |
+| `Destroyed` | | Emitted when the instance has been destroyed and can no longer be used. |
+
+#### Configuration Events
+| Event | Argument | Description |
+| :--- | :--- | :--- |
+| `SetConcurrencyLimit` | `value` (number) | Emitted when the `concurrencyLimit` is updated. |
+| `SetTimeoutValue` | `value` (number) | Emitted when the `timeoutValue` is updated. |
+| `SetTimeoutLimit` | `value` (number) | Emitted when the `timeoutLimit` is updated. |
+
+---
+
+## 💡 Practical Examples
+
+### Example 1: Simple Concurrency (The "Batch" Pattern) 🚀
+Use this when you have a large array of IDs and want to fetch data from a real API without overwhelming the client or the server. We use `JSONPlaceholder` (a free fake API) for this example.
+
+```javascript
+import TinyThrottledApi from 'tiny-essentials/libs/utils/TinyThrottledApi';
+
+/**
+ * A real-world fetch wrapper.
+ * @param {number} id 
+ * @returns {Promise<Object>}
+ */
+const fetchData = async (id) => {
+  const response = await fetch(`https://jsonplaceholder.typicode.com/posts/${id}`);
+  
+  if (!response.ok) {
+    throw new Error(`HTTP error! status: ${response.status}`);
+  }
+  
+  return await response.json();
+};
+
+// Limit to 3 simultaneous network requests
+const throttledApi = new TinyThrottledApi(3, fetchData);
+
+async function runBatch() {
+  const ids = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+
+  console.log("Starting batch fetch...");
+
+  // Map IDs to promises managed by the throttled API
+  const tasks = ids.map(id => 
+    throttledApi.exec(id)
+      .then(data => console.log(`✅ Success [ID ${id}]:`, data.title))
+      .catch(err => console.error(`❌ Error [ID ${id}]:`, err.message))
+  );
+
+  await Promise.all(tasks);
+  console.log("🏁 All batch tasks completed!");
+}
+
+runBatch();
+```
+
+### Example 2: Advanced Throttling (The "Polite" Pattern) ⏱️
+Use this when the API you are calling has strict rate limits (e.g., "no more than 5 requests per second"). By using `TinyTimeout`, we ensure our requests are spaced out gracefully.
+
+```javascript
+import TinyThrottledApi from 'tiny-essentials/libs/utils/TinyThrottledApi';
+import TinyTimeout from 'tiny-essentials/libs/math/TinyTimeout';
+
+const fetchData = async (id) => {
+  const response = await fetch(`https://jsonplaceholder.typicode.com/posts/${id}`);
+  return await response.json();
+};
+
+// 1. Initialize the timing controller
+const timeout = new TinyTimeout();
+
+// 2. Create the throttled API
+// We allow 2 concurrent requests, but we want to space them out
+const throttledApi = new TinyThrottledApi(2, fetchData, timeout);
+
+// 3. Configure the "politeness" delay
+// Base delay of 1000ms (1 second) between requests
+throttledApi.timeoutValue = 1000; 
+// Maximum delay cap of 5000ms
+throttledApi.timeoutLimit = 5000;
+// Apply delay BEFORE the first request in the cycle
+throttledApi.timeoutFirst = true; 
+
+async function runPoliteBatch() {
+  const ids = [1, 2, 3, 4, 5];
+
+  console.log("Starting polite batch fetch...");
+
+  const tasks = ids.map(id => 
+    throttledApi.exec(id).then(data => {
+      console.log(`📦 Received ID ${id} at ${new Date().toLocaleTimeString()}`);
+      return data;
+    })
+  );
+
+  await Promise.all(tasks);
+  console.log("🏁 Polite batch completed!");
+}
+
+runPoliteBatch();
+```

package/docs/v1/libs/worker/browser/TinyWebWorker.md

@@ -0,0 +1,331 @@
+# 🧵 TinyWebWorker
+
+A tiny, strictly-typed wrapper around the native `Worker` API with a built-in
+request/response (RPC) layer, lifecycle management, and a plugin system.
+
+---
+
+## 📖 Table of Contents
+
+1. [Overview](#-overview)
+2. [Features](#-features)
+3. [Installation](#-installation)
+4. [Quick Start](#-quick-start)
+5. [Core Concepts](#-core-concepts)
+6. [API Reference](#-api-reference)
+7. [The Worker Side](#-the-worker-side)
+8. [Message Protocol](#-message-protocol)
+9. [Error Handling](#-error-handling)
+10. [Best Practices](#-best-practices)
+11. [Troubleshooting](#-troubleshooting)
+
+---
+
+## 🔎 Overview
+
+`TinyWebWorker` turns the low-level, string-based `postMessage` API into a
+predictable, promise-based experience. It handles three things for you:
+
+| Responsibility | What it means |
+| --- | --- |
+| 🔄 **Lifecycle** | Start, wait for readiness, terminate, and destroy safely. |
+| 📨 **Events** | Fire-and-forget messages from the main thread to the worker. |
+| 🔌 **RPC / API** | Request/response calls in **both directions**, with timeouts. |
+
+It extends `TinyPluginCore`, so every instance is also a plugin host with an
+event emitter (`on`, `emit`, `removeAllListeners`).
+
+---
+
+## ✨ Features
+
+- ✅ **Promise-based RPC** — call functions inside the worker and `await` the result.
+- ✅ **Bidirectional API** — the worker can call back into the main thread too.
+- ✅ **Timeouts** — every API call has a configurable timeout (default: `10s`).
+- ✅ **Reserved namespace** — the `ww:` prefix protects internal events.
+- ✅ **Zero-leak teardown** — `destroy()` removes listeners and clears references.
+- ✅ **Pluggable logger** — bring your own `console`-compatible logger.
+
+---
+
+## 🚀 Quick Start
+
+### 1. Create the worker file
+
+```javascript
+// my.worker.js
+self.postMessage({ type: 'ww:EngineReady' });
+
+self.addEventListener('message', (event) => {
+  const { type, data } = event.data;
+  if (type === 'greet') {
+    self.postMessage({ type: 'greeted', data: `Hello, ${data.name}!` });
+  }
+});
+```
+
+### 2. Use it from the main thread
+
+```javascript
+import TinyWebWorker from 'tiny-essentials/libs/worker/browser/TinyWebWorker';
+
+const worker = new TinyWebWorker({
+  id: 'greeter',
+  workerUrl: new URL('./my.worker.js', import.meta.url),
+  debugMode: true,
+});
+
+// Wait until the worker signals readiness.
+await worker.init();
+
+// Listen for a standard event coming from the worker.
+worker.on('greeted', ({ data }) => {
+  console.log(data); // "Hello, Yasmin!"
+});
+
+// Send a fire-and-forget message.
+worker.emitMessage('greet', { name: 'Yasmin' });
+
+// Clean up when done.
+worker.destroy();
+```
+
+---
+
+## 🧠 Core Concepts
+
+### 🏷️ The `ww:` Reserved Prefix
+
+Any event type that starts with `ww:` is **reserved for internal use**.
+Calling `emitMessage('ww:something')` throws a `TypeError`. This prevents your
+code from accidentally colliding with lifecycle events like `ww:Started`.
+
+### 🔁 Two Communication Styles
+
+| Style | Method | Direction | Returns | Use when... |
+| --- | --- | --- | --- | --- |
+| **Event** | `emitMessage()` | Main ➡️ Worker | `void` | You don't need an answer. |
+| **API** | `emitApi()` | Main ➡️ Worker | `Promise` | You need a response. |
+| **API (reverse)** | `onApi()` | Worker ➡️ Main | — | The worker needs data from the main thread. |
+
+### 🧬 Lifecycle
+
+```
+new TinyWebWorker()  ──▶  init()  ──▶  [ ww:EngineReady ]  ──▶  ready ✅
+                             │
+                             └──▶  terminate()  ──▶  destroy()  ──▶  💀
+```
+
+---
+
+## 📚 API Reference
+
+### `new TinyWebWorker(options)`
+
+Creates a new manager instance.
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `id` | `string` | — | **Required.** Unique identifier for this instance. |
+| `workerUrl` | `string \| URL` | — | **Required.** Path to the worker file. |
+| `workerOptions` | `WorkerOptions` | `{}` | Native worker options (`type`, `name`, etc.). |
+| `debugMode` | `boolean` | `false` | Enables verbose internal logging. |
+| `useLogColors` | `boolean` | `false` | Enables ANSI colors in logs. |
+| `logger` | `Partial<Console>` | `console` | A custom logger. |
+
+**Throws:** `TypeError` if `id` is not a non-empty string, or if `workerUrl`
+is neither a `string` nor a `URL`.
+
+---
+
+### ⚙️ Methods
+
+#### `init(): Promise<void>`
+
+Instantiates the worker and wires up the message bridge. Resolves when the
+worker posts the `ww:EngineReady` signal.
+
+```javascript
+await worker.init();
+```
+
+**Throws:** `Error` if the worker is already initialized or the instance was destroyed.
+
+---
+
+#### `emitMessage(type, data?): void`
+
+Sends a fire-and-forget event to the worker. This is the **strict** sender.
+
+```javascript
+worker.emitMessage('resize', { width: 800, height: 600 });
+```
+
+**Throws:**
+- `TypeError` — if `type` is not a string.
+- `TypeError` — if `data` is not a non-null object (arrays are rejected).
+- `TypeError` — if `type` starts with the reserved `ww:` prefix.
+
+---
+
+#### `emitApi(type, data?, timeout?): Promise<any>`
+
+Sends a request and resolves with the worker's response.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `type` | `string` | — | The API call identifier. |
+| `data` | `object` | `undefined` | The request payload. |
+| `timeout` | `number` | `10000` | Max wait time in milliseconds. |
+
+```javascript
+const result = await worker.emitApi('math:sum', { a: 2, b: 3 });
+console.log(result); // 5
+```
+
+**Rejects:** with an `Error` if the worker returns an error or the timeout elapses.
+
+---
+
+#### `onApi(type, callback): void`
+
+Registers a handler for API calls **coming from the worker**.
+
+```javascript
+worker.onApi('user:getTheme', () => {
+  return { theme: 'dark' };
+});
+```
+
+**Throws:** `TypeError` if `callback` is not a function.
+
+---
+
+#### `offApi(type): boolean`
+
+Removes a previously registered handler. Returns `true` if a handler was removed.
+
+```javascript
+worker.offApi('user:getTheme');
+```
+
+---
+
+#### `terminate(): void`
+
+Immediately terminates the worker and removes all listeners. The instance can
+technically be re-initialized afterwards, but a new worker will be created.
+
+```javascript
+worker.terminate();
+```
+
+---
+
+#### `destroy(): void`
+
+The nuclear option. Calls `terminate()`, removes all event listeners, destroys
+plugins, and marks the instance as destroyed. **After this, the instance is unusable.**
+
+```javascript
+worker.destroy();
+```
+
+---
+
+### 🎛️ Getters
+
+| Getter | Type | Description |
+| --- | --- | --- |
+| `isReady` | `boolean` | `true` once the worker signals readiness. |
+| `isDestroyed` | `boolean` | `true` after `destroy()` is called. |
+| `worker` | `Worker \| null` | The native worker. **Throws if destroyed.** |
+
+---
+
+### 📡 Events
+
+Subscribe with `worker.on(eventName, handler)`.
+
+| Event | Payload | Fired when... |
+| --- | --- | --- |
+| `ww:Started` | — | The worker is ready. |
+| `ww:Error` | `{ error: ErrorEvent }` | The worker throws an uncaught error. |
+| `ww:Terminated` | — | `terminate()` completes. |
+| *custom* | `{ data, event }` | Any event sent by the worker. |
+
+```javascript
+worker.on('ww:Error', ({ error }) => {
+  console.error('Worker crashed:', error.message);
+});
+```
+
+---
+
+## 📨 Message Protocol
+
+Every message is a plain object. These are the exact shapes the main thread
+reads and writes.
+
+### Main ➡️ Worker
+
+```javascript
+// Fire-and-forget event
+{ type: 'my:event', data: { /* ... */ } }
+
+// API request
+{ type: 'my:api', data: { /* ... */ }, correlationId: 'uuid', isApi: true }
+```
+
+### Worker ➡️ Main
+
+```javascript
+// Readiness signal (required once)
+{ type: 'ww:EngineReady' }
+
+// API response (success)
+{ type: 'ww:ApiResponse', correlationId: 'uuid', data: { /* ... */ } }
+
+// API response (error)
+{ type: 'ww:ApiResponse', correlationId: 'uuid', error: 'Something failed' }
+```
+
+---
+
+## 🚨 Error Handling
+
+`TinyWebWorker` fails loudly and early:
+
+- **Construction** validates `id` and `workerUrl` immediately.
+- **`emitMessage`** rejects arrays and primitives as `data`.
+- **`emitApi`** rejects its promise on timeout or worker-side errors.
+- **`ww:Error`** is emitted for uncaught worker errors.
+
+```javascript
+try {
+  const result = await worker.emitApi('risky:operation', { id: 42 }, 5000);
+} catch (error) {
+  console.error('The call failed:', error.message);
+}
+```
+
+---
+
+## ✅ Best Practices
+
+1. **Always `await worker.init()`** before sending messages.
+2. **Always call `destroy()`** in your framework's cleanup (e.g., `useEffect`, `onUnmounted`).
+3. **Prefer `emitApi` over `emitMessage`** when you need confirmation.
+4. **Never use the `ww:` prefix** in your own event names.
+5. **Set realistic timeouts** for long-running tasks instead of relying on the default `10s`.
+
+---
+
+## 🩺 Troubleshooting
+
+| Symptom | Likely cause | Fix |
+| --- | --- | --- |
+| `init()` never resolves | Worker never posts `ww:EngineReady`. | Add the ready signal at the end of your worker. |
+| `API request timeout` | The worker never responded. | Check the `correlationId` handling in the worker. |
+| `The event type "..." is reserved` | You used the `ww:` prefix. | Rename your event. |
+| `Worker is not initialized` | You called a method before `init()`. | `await worker.init()` first. |

package/docs/v1/libs/worker/engine/TinyWebWorkerEngine.md

@@ -0,0 +1,137 @@
+# 🚀 TinyWebWorkerEngine Documentation
+
+Welcome to the official documentation for the **TinyWebWorkerEngine**. This engine is a robust, lightweight solution designed to manage complex communication patterns between a **Main Thread** and a **Web Worker**. It provides structured messaging, a request-response API pattern, and a plugin-ready architecture.
+
+---
+
+## 📖 Overview
+
+In a standard Web Worker environment, `postMessage` is "fire and forget." This makes it difficult to know when a specific request has been processed or to handle errors returned from the other side. 
+
+**TinyWebWorkerEngine** solves this by implementing:
+1.  **Unidirectional Messaging:** Simple "fire and forget" signals. 📢
+2.  **Bidirectional API Calls:** A request-response pattern using `correlationId` to track specific requests. 🔄
+3.  **Strict Validation:** Ensures data integrity by validating types and structures before processing. 🛡️
+4.  **Namespace Protection:** Uses a `ww:` prefix to prevent user messages from interfering with internal engine signals. 🔒
+
+---
+
+## 🛠 Core Concepts
+
+To use this engine effectively, you must understand the two primary communication patterns it supports.
+
+### 1. Unidirectional Messages (Fire and Forget) 📢
+This is used when you want to send information without expecting a reply.
+*   **From Worker to Main:** Use `engine.emit('type', data)`.
+*   **From Main to Worker:** Use `engine.addMessageListener('type', callback)`.
+
+### 2. The API Pattern (Request-Response) 🔄
+This is used when the Worker needs to ask the Main Thread for something (like a database value or a UI state) and **must wait** for the answer.
+*   **The Mechanism:** The engine generates a unique `correlationId` (using `crypto.randomUUID()`). This ID travels with the request and returns with the response, allowing the engine to resolve the correct `Promise`.
+*   **Timeout Protection:** Every API request has a default timeout (10,000ms) to prevent the Worker from waiting indefinitely if the Main Thread fails to respond.
+
+---
+
+## 🚀 API Reference
+
+### 🛠 Class: `TinyWebWorkerEngine`
+
+#### `constructor(lgConfig)`
+Initializes the engine instance.
+*   **Parameters:**
+    *   `lgConfig` `{Object}`: Configuration object.
+    *   `lgConfig.debugMode` `{boolean}`: Enables detailed internal logging.
+    *   `lgConfig.logger` `{Console}`: Custom logger (defaults to `console`).
+
+#### `init()`
+Starts the engine and begins listening for messages. 
+*   **Note:** This must be called **once**. Calling it twice will throw an `Error`.
+*   **Internal Signal:** Once initialized, the engine automatically sends a `ww:EngineReady` signal to the main thread.
+
+#### `onApi(type, callback)`
+Registers a handler for requests coming **from the Main Thread**.
+*   **Parameters:**
+    *   `type` `{string}`: The unique identifier for the API call.
+    *   `callback` `{ApiHandlerCallback}`: The function to execute. It can be synchronous or return a `Promise`.
+*   **Throws:** `TypeError` if the callback is not a function.
+
+#### `addMessageListener(type, callback)`
+Registers a listener for simple, unidirectional messages.
+*   **Parameters:**
+    *   `type` `{string}`: The message type.
+    *   `callback` `{MessageCallback}`: The function to execute when the message arrives.
+
+#### `emit(type, data)`
+Sends a unidirectional message to the Main Thread.
+*   **Parameters:**
+    *   `type` `{string}`: The identifier. **Cannot start with `ww:`**.
+    *   `data` `{Object|undefined}`: The payload. Must be a non-null object.
+*   **Throws:** `TypeError` if the type is reserved or data is invalid.
+
+#### `emitApi(type, data, timeout)`
+Sends a request to the Main Thread and returns a `Promise` that resolves when the reply arrives.
+*   **Parameters:**
+    *   `type` `{string}`: The identifier for the request.
+    *   `data` `{Object|undefined}`: The request payload.
+    *   `timeout` `{number}`: Max wait time in ms (default `10000`).
+*   **Returns:** `Promise<any>`
+*   **Throws:** `Error` if the timeout is reached.
+
+---
+
+## 📝 Practical Examples
+
+### 🏗 Example 1: Setting up the Worker
+This is how you would implement the engine inside your `worker.js` file.
+
+```javascript
+import TinyWebWorkerEngine from 'tiny-essentials/libs/worker/engine/TinyWebWorkerEngine';
+
+const engine = new TinyWebWorkerEngine({ debugMode: true });
+
+// 1. Handle simple messages from the main thread
+engine.addMessageListener('GREETING', (msg) => {
+  console.log('Received greeting:', msg.data.text);
+});
+
+// 2. Handle API requests (Request-Response)
+engine.onApi('GET_USER_DATA', async ({ data, correlationId }) => {
+  // Simulate an async database fetch
+  const user = await fetchUserData(data.userId); 
+  
+  // Return the result to the main thread
+  return user;
+});
+
+// 3. Start the engine
+engine.init();
+
+// 4. Emit a simple notification to the main thread
+engine.emit('STATUS_UPDATE', { status: 'Worker is running smoothly' });
+```
+
+### 📡 Example 2: Using the Engine in the Main Thread
+(Conceptual logic for the Main Thread side)
+
+```javascript
+// When the worker sends a simple message
+worker.addEventListener('message', (event) => {
+  if (event.data.type === 'STATUS_UPDATE') {
+    console.log('Worker status:', event.data.data.status);
+  }
+});
+
+// When the worker makes an API call to the main thread
+engine.onApi('GET_USER_DATA', async ({ data }) => {
+  return { id: data.userId, name: 'Yasmin', role: 'Developer' };
+});
+```
+
+---
+
+## ⚠️ Safety & Best Practices
+
+1.  **Avoid Namespace Collisions:** Never use the `ww:` prefix for your own custom message types. The engine uses this for internal lifecycle management (like `ww:ApiResponse`).
+2.  **Error Handling in API:** When writing an `onApi` handler, always wrap your logic in `try/catch` or return a rejected `Promise`. The engine will automatically catch these and send the error back to the main thread.
+3.  **Data Integrity:** Always pass objects as `data`. Avoid passing primitives (like just a string) if you plan to expand the data structure later.
+4.  **Timeout Management:** When calling `emitApi`, always be prepared to handle a potential timeout error in your `.catch()` block.