@alwatr/signal 9.26.0 → 9.29.0

package/README.md

@@ -1,140 +1,152 @@
 # Alwatr Signal
 
-[](https://www.google.com/search?q=alwatr+flux)
-[](https://www.google.com/search?q=alwatr+signal)
-[](https://www.google.com/search?q=alwatr)
-[](https://www.npmjs.com/package/%40alwatr/flux)
-[](https://www.npmjs.com/package/%40alwatr/signal)
-
 Alwatr Signal is a powerful, lightweight, and modern reactive programming library. It is inspired by the best concepts from major reactive libraries but engineered to be faster and more efficient than all of them. It provides a robust and elegant way to manage application state through a system of signals, offering fine-grained reactivity, predictability, and excellent performance.
 
-It's designed to be simple to learn, yet capable of handling complex state management scenarios.
+It's designed to be simple to learn, yet capable of handling complex state management scenarios in browser and Bun/Node.js environments.
 
 ## Features
 
-- **Type-Safe**: Fully implemented in TypeScript for robust, type-safe code.
-- **Lightweight**: A small footprint with zero third-party dependencies.
+- **Type-Safe**: Fully implemented in TypeScript with strong types for every signal.
+- **Lightweight**: Extremely small footprint with zero third-party dependencies.
 - **Performant**: Smart change detection and batched updates prevent unnecessary computations and re-renders.
 - **Predictable**: Asynchronous, non-blocking notifications ensure a consistent and understandable data flow.
 - **Lifecycle Management**: Built-in `destroy()` methods for easy cleanup and memory leak prevention.
-- **Easy to Debug**: Unique `name` for each signal makes logging and tracing a breeze.
+- **Easy to Debug**: Scoped logger for each signal makes logging and tracing a breeze.
 
-## Core Concepts
+---
 
-Signals are the fundamental building blocks in Alwatr Signal. They are special objects that hold a value and can notify interested consumers when that value changes. There are three main types of signals:
+## Primitives
 
-1. **`StateSignal`**: The foundation of reactivity. It holds a mutable value. When you `set()` a new value, it notifies all its dependents.
-2. **`ComputedSignal`**: A read-only signal that derives its value from other signals. It automatically updates when its dependencies change. The result is memoized, so the calculation only runs when needed.
-3. **`EffectSignal`**: The bridge to the "outside world." It executes a side effect (like logging or rendering) in response to changes in the signals it depends on.
+There are five core types of signals available:
 
-There is also a fourth type for stateless events:
+1. **`StateSignal<T>`**: The foundation of reactivity. It holds a mutable value. When you `set()` a new value, it notifies all its dependents.
+2. **`EventSignal<T>`**: A stateless signal for dispatching transient, one-off events that don't have a persistent value (e.g. user clicks).
+3. **`ComputedSignal<T>`**: A read-only signal that derives its value from other signals. It automatically updates when its dependencies change. The result is memoized, so the calculation only runs when needed.
+4. **`EffectSignal`**: The bridge to the side-effects. It executes a function (like logging, DOM rendering, or API requests) in response to changes in the signals it depends on.
+5. **`ChannelSignal<TMap>`**: A stateless, typed message bus. A single `ChannelSignal` carries multiple named message types — each with its own payload type — and routes them in **O(1)** to the right subscribers.
 
-4. **`EventSignal`**: A stateless signal for dispatching one-off events that don't have a persistent value.
+Additionally, two persistent state signals are available:
 
-5. **`ChannelSignal`**: A stateless, typed message bus. Unlike `EventSignal` (one signal = one event type), a single `ChannelSignal` carries multiple named message types — each with its own payload type — and routes them in **O(1)** to the right subscribers.
+- **`PersistentStateSignal<T>`**: Extends `StateSignal` with automatic browser `localStorage` persistence, debounced writes, and full Back/Forward Cache (BFCache) lifecycle integration.
+- **`SessionStateSignal<T>`**: Extends `StateSignal` with automatic browser `sessionStorage` persistence, debounced writes, and full BFCache lifecycle integration.
 
 ---
 
-## Getting Started: A Practical Example
+## API & Usage Examples
 
-Let's build a simple reactive system to see how the different signal types work together.
+### 1. StateSignal
 
-### 1. Install
+`StateSignal` represents a piece of mutable state. It always has a value, and new subscribers immediately receive the current value by default.
 
-First, ensure you have the package installed:
+```typescript
+import {StateSignal, createStateSignal} from '@alwatr/signal';
 
-```bash
-npm i @alwatr/signal
-```
+// Creation via factory function (preferred) or new class instance:
+const counter = createStateSignal<number>({
+  name: 'app-counter',
+  initialValue: 0,
+});
 
-### 2. Create State Signals
+// Get the current value
+console.log(counter.get()); // Outputs: 0
 
-`StateSignal` is where your application's state lives. Let's create signals for a user's name and a counter.
+// Subscribe to changes
+const subscription = counter.subscribe((value) => {
+  console.log(`Counter updated to: ${value}`);
+});
 
-```typescript
-import {StateSignal} from '@alwatr/signal';
+// Update value
+counter.set(1); // Prints: "Counter updated to: 1"
 
-// A signal to hold the user's first name.
-const firstName = new StateSignal<string>({
-  name: 'user-firstName',
-  initialValue: 'John',
-});
+// Update based on the previous value (functional state update)
+counter.update((current) => current + 1); // Prints: "Counter updated to: 2"
 
-// A signal to hold a simple counter.
-const counter = new StateSignal<number>({
-  name: 'app-counter',
-  initialValue: 0,
-});
+// Unsubscribe when no longer needed
+subscription.unsubscribe();
 ```
 
-### 3. Create a Computed Signal
+---
+
+### 2. EventSignal
 
-A `ComputedSignal` combines other signals into a new, read-only value. Let's create a `fullName` signal that automatically updates when `firstName` changes.
+`EventSignal` is stateless and is used for dispatching transient events. Subscribers only get notified of future emissions.
 
 ```typescript
-import {ComputedSignal} from '@alwatr/signal';
+import {createEventSignal} from '@alwatr/signal';
+
+const clickSignal = createEventSignal<{x: number; y: number}>({
+  name: 'user-click',
+});
 
-const fullName = new ComputedSignal<string>({
-  name: 'user-fullName',
-  deps: [firstName], // This computed signal depends on firstName.
-  get: () => `User: ${firstName.get()}`,
+// Subscribe to future click events
+clickSignal.subscribe((pos) => {
+  console.log(`Clicked at coordinates: ${pos.x}, ${pos.y}`);
 });
 
-console.log(fullName.get()); // Outputs: "User: John"
+// Dispatch event (runs asynchronously on a microtask)
+clickSignal.dispatch({x: 150, y: 300});
 ```
 
-### 4. Create an Effect Signal
+---
+
+### 3. ComputedSignal
 
-An `EffectSignal` runs a side effect whenever one of its dependencies changes. This is perfect for logging, updating the DOM, or making network requests.
+`ComputedSignal` reactively calculates and memoizes a value based on upstream dependency signals. It automatically recalculates on changes and must be destroyed when no longer needed to prevent memory leaks.
 
 ```typescript
-import {EffectSignal} from '@alwatr/signal';
+import {createStateSignal, createComputedSignal} from '@alwatr/signal';
 
-const loggerEffect = new EffectSignal({
-  deps: [fullName, counter], // This effect depends on fullName and counter.
-  run: () => {
-    console.log(`${fullName.get()} has clicked ${counter.get()} times.`);
-  },
+const firstName = createStateSignal<string>({name: 'first-name', initialValue: 'John'});
+const lastName = createStateSignal<string>({name: 'last-name', initialValue: 'Doe'});
+
+const fullName = createComputedSignal<string>({
+  name: 'full-name',
+  deps: [firstName, lastName],
+  get: () => `${firstName.get()} ${lastName.get()}`,
 });
+
+console.log(fullName.get()); // "John Doe"
+
+// Triggers asynchronous evaluation batching (macrotask)
+firstName.set('Jane');
+// Later in the next macrotask tick:
+console.log(fullName.get()); // "Jane Doe"
+
+// Always destroy when done
+fullName.destroy();
 ```
 
-### 5. Putting It All Together
+---
+
+### 4. EffectSignal
 
-Now, let's see the magic happen. When we update a `StateSignal`, the changes automatically propagate through the system.
+`EffectSignal` runs side-effects in response to dependency changes. It batches changes and runs in a separate macrotask.
 
 ```typescript
-// Subscribe to changes for demonstration
-fullName.subscribe((newFullName) => {
-  console.log(`Full name signal updated to: ${newFullName}`);
-});
+import {createStateSignal, createEffect} from '@alwatr/signal';
 
-// Let's change the first name.
-firstName.set('Jane');
-// This will trigger:
-// 1. `fullName` to recalculate its value.
-// 2. The `fullName.subscribe` callback to run.
-// 3. The `loggerEffect` to run.
-
-// Let's increment the counter.
-counter.set(1);
-// This will trigger:
-// 1. The `loggerEffect` to run again.
-```
+const count = createStateSignal<number>({name: 'count', initialValue: 0});
+
+const logEffect = createEffect({
+  name: 'log-effect',
+  deps: [count],
+  run: () => {
+    console.log(`The count changed to: ${count.get()}`);
+  },
+  runImmediately: true, // Run the effect once on creation
+});
 
-The output would be:
+count.set(5);
 
-```
-User: John
-Full name signal updated to: User: Jane
-User: Jane has clicked 0 times.
-User: Jane has clicked 1 times.
+// Always destroy to clean up dependency subscriptions
+logEffect.destroy();
 ```
 
 ---
 
-## ChannelSignal: A Typed Message Bus
+### 5. ChannelSignal: A Typed Message Bus
 
-### Why ChannelSignal?
+#### Why ChannelSignal?
 
 In real-world applications, you often need to dispatch many different types of events or messages — for example, `'open-drawer'`, `'close-drawer'`, `'show-toast'`, `'navigate'`, etc. You could create a separate `EventSignal` for each one, but that quickly becomes unwieldy:
 
@@ -148,16 +160,16 @@ const showToastSignal = new EventSignal<{message: string; type: 'info' | 'error'
 
 **`ChannelSignal` solves this problem.** It's a single signal that acts as a **typed message bus** — one channel, many named message types. Think of it as a Go-style channel or a pub/sub topic with full TypeScript type safety.
 
-### Architecture: O(1) Routing
+#### Architecture: O(1) Routing
 
 Internally, `ChannelSignal` uses a `Map<name, Set<handler>>` to route messages. When you dispatch a message with name `'A'`, only the handlers registered for `'A'` are invoked — **O(1) lookup**, regardless of how many other names are subscribed. This is a critical performance optimization for applications with hundreds or thousands of directives/components listening to different actions.
 
-### Creating a ChannelSignal
+#### Creating a ChannelSignal
 
 First, define a **message map** — a TypeScript interface that maps every valid message name to its payload type:
 
 ```typescript
-import {ChannelSignal} from '@alwatr/signal';
+import {createChannelSignal} from '@alwatr/signal';
 
 // Define the message map for your application
 interface AppMessages {
@@ -168,34 +180,33 @@ interface AppMessages {
 }
 
 // Create the channel
-const appChannel = new ChannelSignal<AppMessages>({name: 'app-channel'});
+const appChannel = createChannelSignal<AppMessages>({name: 'app-channel'});
 ```
 
-### Subscribing to Named Messages
+#### Subscribing to Named Messages
 
 Use `.on(name, handler)` to subscribe to a specific message. The handler receives the **payload directly** (not the full `{name, payload}` envelope) — since the name is already known at subscription time, passing it again would be redundant.
 
 ```typescript
 // Subscribe to 'open-drawer' messages
 appChannel.on('open-drawer', (payload) => {
-  console.log(`Opening drawer: ${payload!.panel}`);
-  // TypeScript knows payload is {panel: string} | undefined
+  console.log(`Opening drawer: ${payload.panel}`);
+  // TypeScript knows payload is {panel: string}
 });
 
 // Subscribe to 'show-toast' messages
 appChannel.on('show-toast', (payload) => {
-  toast.show(payload!.message, payload!.type);
-  // TypeScript knows payload is {message: string; type: 'info' | 'error'} | undefined
+  toast.show(payload.message, payload.type);
+  // TypeScript knows payload is {message: string; type: 'info' | 'error'}
 });
 
 // Subscribe to 'close-drawer' (no payload)
-appChannel.on('close-drawer', (payload) => {
+appChannel.on('close-drawer', () => {
   console.log('Closing drawer');
-  // TypeScript knows payload is void | undefined
 });
 ```
 
-### Dispatching Messages
+#### Dispatching Messages
 
 Use `.dispatch(name, payload)` to send a message. TypeScript enforces that the payload matches the type declared for that name in the message map.
 
@@ -213,20 +224,20 @@ appChannel.dispatch('show-toast', {message: 'Hi'}); // Error: missing 'type'
 appChannel.dispatch('unknown-action'); // Error: 'unknown-action' is not in AppMessages
 ```
 
-### Unsubscribing
+#### Unsubscribing
 
 Just like other signals, `.on()` returns a `SubscribeResult` with an `unsubscribe()` method:
 
 ```typescript
 const sub = appChannel.on('navigate', (payload) => {
-  router.push(payload!.path);
+  router.push(payload.path);
 });
 
 // Later, when the component is destroyed:
 sub.unsubscribe();
 ```
 
-### One-Time Subscriptions
+#### One-Time Subscriptions
 
 Use the `once` option to automatically unsubscribe after the first message:
 
@@ -240,7 +251,7 @@ appChannel.on(
 );
 ```
 
-### Raw Stream Subscription (for Logging/Middleware)
+#### Raw Stream Subscription (for Logging/Middleware)
 
 If you need to observe **all** messages regardless of name — for example, for logging, analytics, or middleware — use `.subscribe()` instead of `.on()`. This receives the full `{name, payload}` envelope:
 
@@ -253,7 +264,7 @@ appChannel.subscribe((msg) => {
 
 **Important:** `.subscribe()` is **not** filtered by name — it receives every message. For normal use cases, prefer `.on(name, handler)` to keep subscriptions focused and performant.
 
-### Use Cases
+#### Use Cases
 
 `ChannelSignal` is ideal for:
 
@@ -262,14 +273,14 @@ appChannel.subscribe((msg) => {
 - **Command dispatching** in CQRS-style systems
 - **Pub/sub messaging** where you have many distinct message types but want a single, centralized channel
 
-### Example: A Complete Action System
+#### Example: A Complete Action System
 
 > **Note:** `@alwatr/action` is a higher-level package built on top of `ChannelSignal`. It adds declarative HTML attribute support (`on-action="click->add-to-cart:42"`), modifier chaining, payload resolvers, and DOM lifecycle management. For production use, prefer `@alwatr/action` over wiring `ChannelSignal` manually.
 
 The example below shows what `@alwatr/action` does internally — and how you can use `ChannelSignal` directly when you need a pure-code action bus without DOM integration:
 
 ```typescript
-import {ChannelSignal} from '@alwatr/signal';
+import {createChannelSignal} from '@alwatr/signal';
 
 // Define all app actions and their payload types
 interface AppActions {
@@ -281,19 +292,19 @@ interface AppActions {
 }
 
 // One channel for the entire action layer
-const actionChannel = new ChannelSignal<AppActions>({name: 'app-actions'});
+const actionChannel = createChannelSignal<AppActions>({name: 'app-actions'});
 
 // Business logic subscribes — O(1) routing, no cross-action interference
 actionChannel.on('user-login', (payload) => {
-  authService.login(payload!.username);
+  authService.login(payload.username);
 });
 
 actionChannel.on('cart-add-item', (payload) => {
-  cartService.addItem(payload!.productId, payload!.quantity);
+  cartService.addItem(payload.productId, payload.quantity);
 });
 
 actionChannel.on('navigate', (payload) => {
-  router.push(payload!.path);
+  router.push(payload.path);
 });
 
 // UI dispatches actions
@@ -308,577 +319,160 @@ addToCartButton.addEventListener('click', () => {
 
 ---
 
-## Advanced Topics
+### 6. Persistent & Session State Signals
 
-### Lifecycle Management and Memory Leaks
-
-Signals that depend on other signals (like `ComputedSignal` and `EffectSignal`) create subscriptions internally. If you don't clean these up, they can lead to memory leaks.
-
-**Always call `destroy()` on `ComputedSignal` and `EffectSignal` when they are no longer needed.**
+State signals backed by web storage with built-in write debouncing (default 1000ms) and page/BFcache lifecycle listeners.
 
 ```typescript
-// Create a computed signal
-const isEven = new ComputedSignal({
-  deps: [counter],
-  get: () => counter.get() % 2 === 0,
-});
-
-// ... use it for a while ...
-
-// When the component/logic using it is about to be removed:
-isEven.destroy();
-```
-
-Calling `destroy()` unsubscribes the signal from all its dependencies, allowing it to be safely garbage collected.
-
-### Asynchronous Notifications
-
-Alwatr Signal uses a predictable asynchronous model for notifications:
-
-- **`StateSignal` and `EventSignal`** schedule notifications on the **microtask** queue (`Promise.resolve().then(...)`). This ensures that multiple synchronous `set()` calls within the same event loop tick are batched, and listeners are notified shortly after, but not immediately.
-- **`ComputedSignal` and `EffectSignal`** schedule their recalculations/runs on the **macrotask** queue (e.g., `setTimeout(..., 0)`). This is a crucial optimization. If multiple dependencies change in the same event loop, the computed signal will only recalculate _once_ per tick, avoiding redundant work.
-
-### Subscription Options
-
-The `subscribe` method accepts an optional second argument to customize its behavior:
-
-- `once: true`: The listener is called only once and then automatically removed.
-- `priority: true`: The listener is moved to the front of the queue and is executed before other listeners.
-- `receivePrevious: false` (For `StateSignal` only): Prevents the listener from being called immediately with the current value upon subscription.
-
-## API Overview
-
-### `StateSignal<T>`
-
-- **`constructor(config)`**: Creates a new state signal.
-  - `config.name`: `string`
-  - `config.initialValue`: `T`
-- **`.get()`**: `T` - Gets the current value.
-- **`.set(newValue: T)`**: Sets a new value and notifies listeners.
-
-### `ComputedSignal<T>`
-
-- **`constructor(config)`**: Creates a new computed signal.
-  - `config.name`: `string`
-  - `config.deps`: `IReadonlySignal<unknown>[]` - Array of dependency signals.
-  - `config.get`: `() => T` - The function to compute the value.
-- **`.get()`**: `T` - Gets the current (memoized) value.
-- **`.destroy()`**: Cleans up the signal's subscriptions. **(Important!)**
-
-### `EffectSignal`
-
-- **`constructor(config)`**: Creates a new effect signal.
-  - `config.deps`: `IReadonlySignal<unknown>[]` - Array of dependency signals.
-  - `config.run`: `() => void | Promise<void>` - The side effect function.
-  - `config.runImmediately`: `boolean` (optional) - Whether to run the effect on creation.
-- **`.destroy()`**: Cleans up the signal's subscriptions. **(Important!)**
-
-### `EventSignal<T>`
+import {createPersistentStateSignal, createSessionStateSignal} from '@alwatr/signal';
 
-- **`constructor(config)`**: Creates a new event signal.
-  - `config.name`: `string`
-- **`.dispatch(payload: T)`**: Dispatches an event to all listeners.
-
-### `PersistentStateSignal<T>`
-
-- **`constructor(config)`**: Creates a state signal that persists in `localStorage`.
-  - `config.name`: `string`
-  - `config.initialValue`: `T`
-  - config.schemaVersion: number
-  - `config.parse`: `(value: string) => T` (optional)
-  - `config.stringify`: `(value: T) => string` (optional)
-- Has all methods of `StateSignal`.
-- **Reliable Save & BFCache Support**: Automatically flushes pending writes on `pagehide` and re-syncs state on `pageshow` when restoring from BFCache.
-- **`.remove()`**: Removes the value from storage without destroying the signal.
-
-### `SessionStateSignal<T>`
-
-- **`constructor(config)`**: Creates a state signal that persists in `sessionStorage` (tab-scoped).
-  - `config.name`: `string`
-  - `config.initialValue`: `T`
-  - `config.parse`: `(value: string) => T` (optional)
-  - `config.stringify`: `(value: T) => string` (optional)
-- Has all methods of `StateSignal`.
-- **Reliable Save & BFCache Support**: Automatically flushes pending writes on `pagehide` and re-syncs state on `pageshow` when restoring from BFCache.
-- **`.remove()`**: Removes the value from storage without destroying the signal.
-
-### `ChannelSignal<TMap>`
-
-- **`constructor(config)`**: Creates a new channel signal.
-  - `config.name`: `string`
-- **`.dispatch(name, payload?)`**: Dispatches a named message. TypeScript enforces the correct payload type for each name.
-- **`.on(name, handler, options?)`**: Subscribes to a specific named message. The handler receives the `payload` directly (not the full envelope). Uses an internal `Map` for **O(1)** routing. Supports `once` option.
-- **`.subscribe(callback, options?)`**: Subscribes to the **raw message stream** — receives every `{name, payload}` envelope regardless of name. Useful for logging and middleware.
-
-### Common Methods
-
-- **`.subscribe(callback, options?)`**: Subscribes a listener. Returns `{ unsubscribe: () => void }`.
-- **`.untilNext()`**: Returns a `Promise` that resolves with the next value/payload.
-- **`.destroy()`**: (On all but `StateSignal`) Cleans up the signal.
-
----
-
-## 🌊 Part of Alwatr Flux
-
-`@alwatr/signal` is the **State Layer** of the [Alwatr Flux](https://github.com/Alwatr/alwatr/tree/next/pkg/flux) architecture — a complete Unidirectional Data Flow system for building scalable Progressive Web Applications.
-
-```
-View → Action (@alwatr/action) → Controller → State (@alwatr/signal) → View
-```
-
-In the Flux architecture, signals serve as the **single source of truth**. Controllers update signals after processing actions, and the View layer subscribes to signals to re-render only the affected parts of the UI — no Virtual DOM, no full-tree reconciliation.
-
-**The full Flux bundle** (`@alwatr/flux`) includes signals, actions, directives, page-ready, and storage — everything you need to build a complete reactive application from a single import.
-
-```typescript
-// Use @alwatr/flux for the complete architecture
-import {createStateSignal, onAction, setupActionDelegation} from '@alwatr/flux';
-
-// Or use @alwatr/signal standalone for just the reactive primitives
-import {createStateSignal, createComputedSignal} from '@alwatr/signal';
-```
-
-→ [View the complete Flux documentation](https://github.com/Alwatr/alwatr/tree/next/pkg/flux)
-
----
-
-## Sponsors
-
-The following companies, organizations, and individuals support flux ongoing maintenance and development. Become a Sponsor to get your logo on our README and website.
-
-## Contributing
-
-Contributions are welcome! Please read our [contribution guidelines](https://github.com/Alwatr/.github/blob/next/CONTRIBUTING.md) before submitting a pull request.
-
----
-
-<br>
-<br>
-<br>
-
-# Alwatr Signal (راهنمای فارسی)
-
-[](https://www.google.com/search?q=alwatr+flux)
-[](https://www.google.com/search?q=alwatr+signal)
-[](https://www.google.com/search?q=alwatr)
-[](https://www.npmjs.com/package/%40alwatr/flux)
-[](https://www.npmjs.com/package/%40alwatr/signal)
-
-کتابخانه Alwatr Signal یک ابزار قدرتمند، سبک و مدرن برای برنامه‌نویسی واکنشی (Reactive Programming) است. این کتابخانه با الگوبرداری از بهترین مفاهیم بزرگترین کتابخانه‌های واکنشی طراحی شده، اما مهندسی آن به گونه‌ای است که از تمام آن‌ها سریع‌تر و کارآمدتر باشد. این کتابخانه روشی استوار و زیبا برای مدیریت وضعیت برنامه از طریق سیگنال‌ها ارائه می‌دهد و واکنش‌پذیری دقیق (fine-grained reactivity)، پیش‌بینی‌پذیری و عملکرد عالی را به ارمغان می‌آورد.
-
-طراحی آن به گونه‌ای است که یادگیری آن ساده باشد، اما در عین حال قادر به مدیریت سناریوهای پیچیده مدیریت وضعیت نیز باشد.
-
-## ویژگی‌ها
-
-- **ایمنی نوع (Type-Safe)**: به طور کامل با TypeScript پیاده‌سازی شده تا کدی قوی و ایمن از نظر نوع داشته باشید.
-- **سبک**: حجم بسیار کم و بدون هیچ وابستگی (dependency) خارجی.
-- **عملکرد بالا**: تشخیص هوشمند تغییرات و به‌روزرسانی‌های دسته‌ای از محاسبات و رندرهای غیرضروری جلوگیری می‌کند.
-- **پیش‌بینی‌پذیر**: نوتیفیکیشن‌های ناهمزمان (asynchronous) و غیرمسدودکننده (non-blocking) جریان داده‌ای سازگار و قابل فهم را تضمین می‌کنند.
-- **مدیریت چرخه حیات (Lifecycle)**: متدهای داخلی `destroy()` برای پاک‌سازی آسان و جلوگیری از نشت حافظه (memory leak).
-- **اشکال‌زدایی آسان**: شناسه‌های منحصر به فرد (`name`) برای هر سیگنال، لاگ‌گیری و ردیابی را بسیار ساده می‌کند.
-
-## مفاهیم اصلی
-
-سیگنال‌ها بلوک‌های سازنده اصلی در Alwatr Signal هستند. آن‌ها اشیاء خاصی هستند که یک مقدار را نگه می‌دارند و می‌توانند مصرف‌کنندگان علاقه‌مند را هنگام تغییر آن مقدار مطلع کنند. سه نوع اصلی سیگنال وجود دارد:
-
-1. **`StateSignal`**: پایه و اساس واکنش‌پذیری. این سیگنال یک مقدار قابل تغییر را نگه می‌دارد. وقتی شما مقدار جدیدی را `set()` می‌کنید، تمام وابستگان خود را مطلع می‌سازد.
-2. **`ComputedSignal`**: یک سیگنال فقط-خواندنی (read-only) که مقدار خود را از سیگنال‌های دیگر استخراج می‌کند. این سیگنال به طور خودکار با تغییر وابستگی‌هایش به‌روز می‌شود. نتیجه کش (memoized) می‌شود، بنابراین محاسبات فقط در صورت نیاز انجام می‌شود.
-3. **`EffectSignal`**: پلی به "دنیای بیرون". این سیگنال یک اثر جانبی (side effect) مانند لاگ‌گیری یا رندر کردن را در پاسخ به تغییرات سیگنال‌هایی که به آن‌ها وابسته است، اجرا می‌کند.
-
-یک نوع چهارم نیز برای رویدادهای بدون حالت وجود دارد:
-
-4. **`EventSignal`**: یک سیگنال بدون حالت برای ارسال رویدادهای یک‌باره که مقدار پایداری ندارند.
-
-و یک نوع پنجم برای مسیریابی پیام‌های چندگانه:
-
-5. **`ChannelSignal`**: یک Message Bus تایپ‌شده و بدون حالت. برخلاف `EventSignal` (یک سیگنال = یک نوع رویداد)، یک `ChannelSignal` واحد چندین نوع پیام با نام‌های مختلف را حمل می‌کند — هر کدام با نوع payload مخصوص خودشان — و آن‌ها را با سرعت **O(1)** به subscriber‌های مناسب هدایت می‌کند.
-
----
-
-## شروع به کار: یک مثال عملی
-
-بیایید یک سیستم واکنشی ساده بسازیم تا ببینیم انواع مختلف سیگنال‌ها چگونه با هم کار می‌کنند.
-
-### ۱. نصب
-
-ابتدا، اطمینان حاصل کنید که بسته را نصب کرده‌اید:
-
-```bash
-npm i @alwatr/signal
-```
-
-### ۲. ایجاد `StateSignal`
-
-`StateSignal` جایی است که وضعیت برنامه شما زندگی می‌کند. بیایید سیگنال‌هایی برای نام یک کاربر و یک شمارنده ایجاد کنیم.
-
-```typescript
-import {StateSignal} from '@alwatr/signal';
-
-// سیگنالی برای نگهداری نام کوچک کاربر
-const firstName = new StateSignal<string>({
-  name: 'user-firstName',
-  initialValue: 'John',
-});
-
-// سیگنالی برای نگهداری یک شمارنده ساده
-const counter = new StateSignal<number>({
-  name: 'app-counter',
-  initialValue: 0,
+// PersistentStateSignal saves state to localStorage
+const theme = createPersistentStateSignal<'light' | 'dark'>({
+  name: 'app-theme',
+  initialValue: 'light',
+  storageKey: 'theme-preference', // optional storage key
+  saveDebounceDelay: 500, // debounce time in ms
 });
-```
 
-### ۳. ایجاد `ComputedSignal`
+theme.set('dark'); // Automatically schedules storage save
 
-یک `ComputedSignal` سیگنال‌های دیگر را ترکیب کرده و یک مقدار جدید و فقط-خواندنی ایجاد می‌کند. بیایید یک سیگنال `fullName` بسازیم که با تغییر `firstName` به طور خودکار به‌روز شود.
-
-```typescript
-import {ComputedSignal} from '@alwatr/signal';
-
-const fullName = new ComputedSignal<string>({
-  name: 'user-fullName',
-  deps: [firstName], // این سیگنال محاسباتی به firstName وابسته است
-  get: () => `User: ${firstName.get()}`,
-});
-
-console.log(fullName.get()); // خروجی: "User: John"
-```
-
-### ۴. ایجاد `EffectSignal`
-
-یک `EffectSignal` هر زمان که یکی از وابستگی‌هایش تغییر کند، یک اثر جانبی اجرا می‌کند. این برای لاگ‌گیری، به‌روزرسانی DOM یا ارسال درخواست‌های شبکه عالی است.
-
-```typescript
-import {EffectSignal} from '@alwatr/signal';
-
-const loggerEffect = new EffectSignal({
-  deps: [fullName, counter], // این افکت به fullName و counter وابسته است
-  run: () => {
-    console.log(`${fullName.get()} has clicked ${counter.get()} times.`);
-  },
-});
-```
-
-### ۵. کنار هم قرار دادن همه چیز
-
-حالا، بیایید جادو را ببینیم. وقتی ما یک `StateSignal` را به‌روز می‌کنیم، تغییرات به طور خودکار در سراسر سیستم پخش می‌شوند.
-
-```typescript
-// برای نمایش، در تغییرات مشترک می‌شویم
-fullName.subscribe((newFullName) => {
-  console.log(`Full name signal updated to: ${newFullName}`);
+// SessionStateSignal saves state to sessionStorage
+const wizardStep = createSessionStateSignal<number>({
+  name: 'wizard-step',
+  initialValue: 1,
 });
 
-// بیایید نام کوچک را تغییر دهیم
-firstName.set('Jane');
-// این کار باعث می‌شود:
-// ۱. `fullName` مقدار خود را دوباره محاسبه کند.
-// ۲. کال‌بک `fullName.subscribe` اجرا شود.
-// ۳. `loggerEffect` اجرا شود.
-
-// بیایید شمارنده را افزایش دهیم
-counter.set(1);
-// این کار باعث می‌شود:
-// ۱. `loggerEffect` دوباره اجرا شود.
-```
-
-خروجی به این صورت خواهد بود:
+// Remove persisted data from storage without destroying the signal:
+wizardStep.remove();
 
-```
-User: John
-Full name signal updated to: User: Jane
-User: Jane has clicked 0 times.
-User: Jane has clicked 1 times.
+// Clean up when unmounting
+theme.destroy();
+wizardStep.destroy();
 ```
 
 ---
 
-## ChannelSignal: یک Message Bus تایپ‌شده
+## Operators
 
-### چرا ChannelSignal؟
+The package includes utility operators to transform and debounce signals:
 
-در برنامه‌های واقعی، اغلب نیاز دارید انواع مختلفی از رویدادها یا پیام‌ها را dispatch کنید — مثلاً `'open-drawer'`، `'close-drawer'`، `'show-toast'`، `'navigate'` و غیره. می‌توانید برای هر کدام یک `EventSignal` جداگانه بسازید، اما این رویکرد به سرعت دست‌وپاگیر می‌شود:
+### 1. `createDebouncedSignal`
 
-```typescript
-// ❌ پرحجم و سخت برای مدیریت
-const openDrawerSignal = new EventSignal<{panel: string}>({name: 'open-drawer'});
-const closeDrawerSignal = new EventSignal({name: 'close-drawer'});
-const showToastSignal = new EventSignal<{message: string; type: 'info' | 'error'}>({name: 'show-toast'});
-// ... و به همین ترتیب برای هر action در برنامه
-```
-
-**`ChannelSignal` این مشکل را حل می‌کند.** یک سیگنال واحد است که به عنوان یک **Message Bus تایپ‌شده** عمل می‌کند — یک کانال، انواع پیام‌های مختلف. مثل یک Go-style channel یا یک pub/sub topic با ایمنی کامل TypeScript.
-
-### معماری: مسیریابی O(1)
-
-در داخل، `ChannelSignal` از یک `Map<name, Set<handler>>` برای مسیریابی پیام‌ها استفاده می‌کند. وقتی پیامی با نام `'A'` dispatch می‌شود، فقط handler‌هایی که برای `'A'` ثبت شده‌اند فراخوانی می‌شوند — **جستجوی O(1)**، صرف‌نظر از اینکه چه تعداد نام دیگری subscribe شده باشند. این یک بهینه‌سازی حیاتی برای برنامه‌هایی است که صدها یا هزاران directive/component دارند که به action‌های مختلف گوش می‌دهند.
-
-### ساخت یک ChannelSignal
-
-ابتدا یک **message map** تعریف کنید — یک interface در TypeScript که هر نام پیام معتبر را به نوع payload آن نگاشت می‌کند:
+Creates a new computed signal that debounces updates from a source signal.
 
 ```typescript
-import {ChannelSignal} from '@alwatr/signal';
+import {createStateSignal, createDebouncedSignal} from '@alwatr/signal';
 
-// تعریف message map برای برنامه
-interface AppMessages {
-  'open-drawer': {panel: string};
-  'close-drawer': void; // بدون payload
-  'show-toast': {message: string; type: 'info' | 'error'};
-  'navigate': {path: string};
-}
+const searchInput = createStateSignal<string>({name: 'search-input', initialValue: ''});
 
-// ساخت channel
-const appChannel = new ChannelSignal<AppMessages>({name: 'app-channel'});
-```
-
-### Subscribe به پیام‌های نام‌دار
-
-از `.on(name, handler)` برای subscribe به یک پیام خاص استفاده کنید. handler مستقیماً **payload** را دریافت می‌کند (نه envelope کامل `{name, payload}`) — چون نام در زمان subscribe مشخص است، ارسال مجدد آن اضافی خواهد بود.
-
-```typescript
-// Subscribe به پیام‌های 'open-drawer'
-appChannel.on('open-drawer', (payload) => {
-  console.log(`Opening drawer: ${payload!.panel}`);
-  // TypeScript می‌داند payload از نوع {panel: string} | undefined است
-});
-
-// Subscribe به پیام‌های 'show-toast'
-appChannel.on('show-toast', (payload) => {
-  toast.show(payload!.message, payload!.type);
-  // TypeScript می‌داند payload از نوع {message: string; type: 'info' | 'error'} | undefined است
+// Debounces input updates by 300ms
+const debouncedSearch = createDebouncedSignal(searchInput, {
+  delay: 300,
 });
 
-// Subscribe به 'close-drawer' (بدون payload)
-appChannel.on('close-drawer', () => {
-  console.log('Closing drawer');
-});
+// Must be destroyed to clean up internal debouncer timers and subscriptions
+debouncedSearch.destroy();
 ```
 
-### Dispatch پیام‌ها
+### 2. `createFilteredSignal`
 
-از `.dispatch(name, payload)` برای ارسال پیام استفاده کنید. TypeScript اعمال می‌کند که payload با نوع تعریف‌شده برای آن نام در message map مطابقت داشته باشد.
+Creates a new computed signal that only emits values satisfying a predicate function.
 
 ```typescript
-// Dispatch با payload
-appChannel.dispatch('open-drawer', {panel: 'settings'}); // ✅ Type-safe
-appChannel.dispatch('show-toast', {message: 'ذخیره شد!', type: 'info'}); // ✅
+import {createStateSignal, createFilteredSignal} from '@alwatr/signal';
 
-// Dispatch بدون payload
-appChannel.dispatch('close-drawer'); // ✅
-
-// ❌ خطاهای TypeScript:
-appChannel.dispatch('open-drawer', {panel: 123}); // خطا: panel باید string باشد
-appChannel.dispatch('show-toast', {message: 'سلام'}); // خطا: 'type' وجود ندارد
-appChannel.dispatch('unknown-action'); // خطا: 'unknown-action' در AppMessages نیست
-```
-
-### Unsubscribe کردن
-
-مثل سایر سیگنال‌ها، `.on()` یک `SubscribeResult` با متد `unsubscribe()` برمی‌گرداند:
-
-```typescript
-const sub = appChannel.on('navigate', (payload) => {
-  router.push(payload!.path);
-});
+const numberSignal = createStateSignal<number>({name: 'number', initialValue: 0});
+const evenNumberSignal = createFilteredSignal(numberSignal, (n) => n % 2 === 0);
 
-// بعداً، وقتی کامپوننت destroy می‌شود:
-sub.unsubscribe();
+evenNumberSignal.destroy();
 ```
 
-### Subscribe یک‌باره
+### 3. `createMappedSignal`
 
-از گزینه `once` برای unsubscribe خودکار بعد از اولین پیام استفاده کنید:
+Transforms values from a source signal using a projection function.
 
 ```typescript
-appChannel.on(
-  'app-ready',
-  () => {
-    console.log('برنامه آماده است!');
-  },
-  {once: true},
-);
-```
-
-### Subscribe به جریان خام (برای لاگ‌گیری/Middleware)
+import {createStateSignal, createMappedSignal} from '@alwatr/signal';
 
-اگر نیاز دارید **همه** پیام‌ها را صرف‌نظر از نام مشاهده کنید — مثلاً برای لاگ‌گیری، analytics یا middleware — از `.subscribe()` به جای `.on()` استفاده کنید. این متد envelope کامل `{name, payload}` را دریافت می‌کند:
+const userSignal = createStateSignal({name: 'user', initialValue: {name: 'John', age: 30}});
+const userNameSignal = createMappedSignal(userSignal, (user) => user.name);
 
-```typescript
-// لاگ کردن همه پیام‌ها برای debugging
-appChannel.subscribe((msg) => {
-  console.log(`[channel] ${String(msg.name)}`, msg.payload);
-});
+console.log(userNameSignal.get()); // John
 ```
 
-**نکته مهم:** `.subscribe()` بر اساس نام فیلتر **نمی‌شود** — هر پیامی را دریافت می‌کند. برای موارد عادی، `.on(name, handler)` را ترجیح دهید تا subscriptionها متمرکز و کارآمد بمانند.
-
-### موارد استفاده
-
-`ChannelSignal` برای موارد زیر ایده‌آل است:
-
-- **لایه Action** در معماری‌های Unidirectional Data Flow (مثل `@alwatr/action`)
-- **Event Bus** در UI‌های مبتنی بر کامپوننت (مثلاً یک کانال رویداد سراسری برنامه)
-- **Command Dispatching** در سیستم‌های CQRS-style
-- **Pub/Sub Messaging** جایی که انواع پیام‌های مختلف دارید اما می‌خواهید یک کانال مرکزی داشته باشید
+---
 
-### مثال کامل: یک سیستم Action
+## Advanced Subscription Options
 
-> **نکته:** پکیج `@alwatr/action` یک لایه بالاتر است که روی `ChannelSignal` ساخته شده. این پکیج پشتیبانی از attribute‌های HTML (`on-action="click->add-to-cart:42"`)، modifier chaining، payload resolver و مدیریت lifecycle DOM را اضافه می‌کند. برای استفاده در پروداکشن، `@alwatr/action` را به جای wiring مستقیم `ChannelSignal` ترجیح دهید.
+When subscribing to signals, you can customize the behavior with the `SubscribeOptions` parameter:
 
-مثال زیر نشان می‌دهد که `@alwatr/action` در داخل چه کاری انجام می‌دهد — و چگونه می‌توانید `ChannelSignal` را مستقیماً زمانی که به یک action bus خالص بدون DOM integration نیاز دارید استفاده کنید:
+- `once?: boolean`: If `true`, the listener runs once and automatically unsubscribes.
+- `priority?: boolean`: If `true`, the listener is added to the front of the queue and executes before standard observers.
+- `receivePrevious?: boolean`: (For `StateSignal` only, default `true`). If `false`, the listener ignores the current value and only runs on future updates.
 
 ```typescript
-import {ChannelSignal} from '@alwatr/signal';
-
-// تعریف همه action‌های برنامه و نوع payload آن‌ها
-interface AppActions {
-  'user-login': {username: string};
-  'user-logout': void;
-  'cart-add-item': {productId: number; quantity: number};
-  'cart-remove-item': {productId: number};
-  'navigate': {path: string};
-}
-
-// یک کانال برای کل لایه action
-const actionChannel = new ChannelSignal<AppActions>({name: 'app-actions'});
-
-// منطق تجاری subscribe می‌کند — routing با O(1)، بدون تداخل بین action‌ها
-actionChannel.on('user-login', (payload) => {
-  authService.login(payload!.username);
-});
-
-actionChannel.on('cart-add-item', (payload) => {
-  cartService.addItem(payload!.productId, payload!.quantity);
-});
-
-actionChannel.on('navigate', (payload) => {
-  router.push(payload!.path);
-});
-
-// UI اقدام به dispatch action می‌کند
-loginButton.addEventListener('click', () => {
-  actionChannel.dispatch('user-login', {username: 'ali'});
-});
-
-addToCartButton.addEventListener('click', () => {
-  actionChannel.dispatch('cart-add-item', {productId: 42, quantity: 1});
+// Subscribe with options
+mySignal.subscribe((val) => console.log(val), {
+  once: true,
+  priority: true,
 });
 ```
 
 ---
 
-## مباحث پیشرفته
-
-### مدیریت چرخه حیات و نشت حافظه
+## Lifecycle Management and Memory Leaks
 
-سیگنال‌هایی که به سیگنال‌های دیگر وابسته‌اند (مانند `ComputedSignal` و `EffectSignal`) به صورت داخلی اشتراک (subscription) ایجاد می‌کنند. اگر این اشتراک‌ها را پاک‌سازی نکنید، می‌توانند منجر به نشت حافظه شوند.
+Signals that depend on other signals (like `ComputedSignal` and `EffectSignal`) create subscriptions internally. If you don't clean these up, they can lead to memory leaks.
 
-**همیشه متد `destroy()` را روی `ComputedSignal` و `EffectSignal` زمانی که دیگر به آن‌ها نیازی نیست، فراخوانی کنید.**
+**Always call `destroy()` on `ComputedSignal` and `EffectSignal` when they are no longer needed.**
 
 ```typescript
-// یک سیگنال محاسباتی ایجاد کنید
-const isEven = new ComputedSignal({
+import {createStateSignal, createComputedSignal} from '@alwatr/signal';
+
+const counter = createStateSignal<number>({name: 'counter', initialValue: 0});
+
+// Create a computed signal
+const isEven = createComputedSignal<boolean>({
+  name: 'is-even',
   deps: [counter],
   get: () => counter.get() % 2 === 0,
 });
 
-// ... مدتی از آن استفاده کنید ...
+// ... use it for a while ...
 
-// زمانی که کامپوننت/منطقی که از آن استفاده می‌کند در شرف حذف شدن است:
+// When the component/logic using it is about to be removed:
 isEven.destroy();
 ```
 
-فراخوانی `destroy()` اشتراک سیگنال را از تمام وابستگی‌هایش لغو می‌کند و به جمع‌آورنده زباله (garbage collector) اجازه می‌دهد آن را با خیال راحت پاک کند.
-
-### نوتیفیکیشن‌های ناهمزمان (Asynchronous)
-
-Alwatr Signal از یک مدل ناهمزمان قابل پیش‌بینی برای نوتیفیکیشن‌ها استفاده می‌کند:
-
-- **`StateSignal` و `EventSignal`** نوتیفیکیشن‌ها را در صف **microtask** (`Promise.resolve().then(...)`) زمان‌بندی می‌کنند. این تضمین می‌کند که چندین فراخوانی `set()` همزمان در یک تیک حلقه رویداد (event loop) دسته‌بندی شده و شنوندگان کمی بعد، اما نه بلافاصله، مطلع می‌شوند.
-- **`ComputedSignal` و `EffectSignal`** محاسبات/اجراهای خود را در صف **macrotask** (مانند `setTimeout(..., 0)`) زمان‌بندی می‌کنند. این یک بهینه‌سازی حیاتی است. اگر چندین وابستگی در یک حلقه رویداد تغییر کنند، سیگنال محاسباتی فقط _یک بار_ در هر تیک دوباره محاسبه می‌شود و از کار اضافی جلوگیری می‌کند.
-
-### گزینه‌های اشتراک (`subscribe`)
-
-متد `subscribe` یک آرگومان دوم اختیاری برای سفارشی‌سازی رفتار خود می‌پذیرد:
-
-- `once: true`: شنونده فقط یک بار فراخوانی شده و سپس به طور خودکار حذف می‌شود.
-- `priority: true`: شنونده به ابتدای صف منتقل شده و قبل از سایر شنوندگان اجرا می‌شود.
-- `receivePrevious: false` (فقط برای `StateSignal`): از فراخوانی فوری شنونده با مقدار فعلی در هنگام اشتراک جلوگیری می‌کند.
-
-## مرور کلی API
-
-### `StateSignal<T>`
-
-- **`constructor(config)`**: یک سیگنال وضعیت جدید ایجاد می‌کند.
-  - `config.name`: `string`
-  - `config.initialValue`: `T`
-- **`.get()`**: `T` - مقدار فعلی را دریافت می‌کند.
-- **`.set(newValue: T)`**: مقدار جدیدی را تنظیم کرده و شنوندگان را مطلع می‌کند.
-
-### `ComputedSignal<T>`
-
-- **`constructor(config)`**: یک سیگنال محاسباتی جدید ایجاد می‌کند.
-  - `config.name`: `string`
-  - `config.deps`: `IReadonlySignal<unknown>[]` - آرایه‌ای از سیگنال‌های وابسته.
-  - `config.get`: `() => T` - تابعی برای محاسبه مقدار.
-- **`.get()`**: `T` - مقدار فعلی (کش شده) را دریافت می‌کند.
-- **`.destroy()`**: اشتراک‌های سیگنال را پاک‌سازی می‌کند. **(مهم!)**
-
-### `EffectSignal`
-
-- **`constructor(config)`**: یک سیگنال افکت جدید ایجاد می‌کند.
-  - `config.deps`: `IReadonlySignal<unknown>[]` - آرایه‌ای از سیگنال‌های وابسته.
-  - `config.run`: `() => void | Promise<void>` - تابع اثر جانبی.
-  - `config.runImmediately`: `boolean` (اختیاری) - آیا افکت در هنگام ایجاد اجرا شود یا خیر.
-- **`.destroy()`**: اشتراک‌های سیگنال را پاک‌سازی می‌کند. **(مهم!)**
+Calling `destroy()` unsubscribes the signal from all its dependencies, allowing it to be safely garbage collected.
 
-### `EventSignal<T>`
+---
 
-- **`constructor(config)`**: یک سیگنال رویداد جدید ایجاد می‌کند.
-  - `config.name`: `string`
-- **`.dispatch(payload: T)`**: یک رویداد را به همه شنوندگان ارسال می‌کند.
+## Asynchronous Scheduling
 
-### `PersistentStateSignal<T>`
+To prevent performance degradation, Alwatr Signal employs an asynchronous execution strategy:
 
-- **`constructor(config)`**: یک سیگنال وضعیت ایجاد می‌کند که در `localStorage` ماندگار است.
-  - `config.name`: `string`
-  - `config.initialValue`: `T`
-  - config.schemaVersion: number
-  - `config.parse`: `(value: string) => T` (اختیاری)
-  - `config.stringify`: `(value: T) => string` (اختیاری)
-- دارای تمامی متدهای `StateSignal` است.
-- **ذخیره مطمئن و پشتیبانی از BFCache**: به طور خودکار داده‌ها را در رویداد `pagehide` ذخیره می‌کند و در صورت بازگشت از BFCache (رویداد `pageshow`)، سیگنال را دوباره با حافظه همگام‌سازی (Sync) می‌کند.
-- **`.remove()`**: مقدار را از حافظه (storage) بدون از بین بردن سیگنال پاک می‌کند.
+- **`StateSignal` & `EventSignal`**: Notifications are pushed to the **microtask** queue (`Promise.resolve()`). This batches multiple synchronous modifications and delivers them at the end of the current task.
+- **`ComputedSignal` & `EffectSignal`**: Recalculations and side-effects are scheduled as **macrotasks** (`delay.nextMacrotask`). If multiple dependency signals change in the same tick, the computed/effect signal updates once, preventing costly redundant evaluations.
 
-### `SessionStateSignal<T>`
+---
 
-- **`constructor(config)`**: یک سیگنال وضعیت ایجاد می‌کند که در `sessionStorage` (در سطح tab) ماندگار است.
-  - `config.name`: `string`
-  - `config.initialValue`: `T`
-  - `config.parse`: `(value: string) => T` (اختیاری)
-  - `config.stringify`: `(value: T) => string` (اختیاری)
-- دارای تمامی متدهای `StateSignal` است.
-- **ذخیره مطمئن و پشتیبانی از BFCache**: به طور خودکار داده‌ها را در رویداد `pagehide` ذخیره می‌کند و در صورت بازگشت از BFCache (رویداد `pageshow`)، سیگنال را دوباره با حافظه همگام‌سازی (Sync) می‌کند.
-- **`.remove()`**: مقدار را از حافظه (storage) بدون از بین بردن سیگنال پاک می‌کند.
+## 🌊 Part of Alwatr Flux
 
-### `ChannelSignal<TMap>`
+`@alwatr/signal` serves as the **State Layer** of the **Alwatr Flux** unidirectional architecture:
 
-- **`constructor(config)`**: یک channel signal جدید ایجاد می‌کند.
-  - `config.name`: `string`
-- **`.dispatch(name, payload?)`**: یک پیام با نام مشخص ارسال می‌کند. TypeScript نوع صحیح payload را برای هر نام اعمال می‌کند.
-- **`.on(name, handler, options?)`**: به یک پیام با نام مشخص subscribe می‌کند. handler مستقیماً `payload` را دریافت می‌کند (نه envelope کامل). از یک `Map` داخلی برای routing **O(1)** استفاده می‌کند. از گزینه `once` پشتیبانی می‌کند.
-- **`.subscribe(callback, options?)`**: به **جریان خام پیام‌ها** subscribe می‌کند — هر envelope `{name, payload}` را صرف‌نظر از نام دریافت می‌کند. برای لاگ‌گیری و middleware مفید است.
+```
+View → Action (@alwatr/action) → Controller → State (@alwatr/signal) → View
+```
 
-### متدهای مشترک
+For full UI integration, check out the `@alwatr/flux` bundle package.
 
-- **`.subscribe(callback, options?)`**: یک شنونده را مشترک می‌کند. `{ unsubscribe: () => void }` را برمی‌گرداند.
-- **`.untilNext()`**: یک `Promise` برمی‌گرداند که با مقدار/پیام بعدی resolve می‌شود.
-- **`.destroy()`**: (روی همه سیگنال‌ها به جز `StateSignal`) سیگنال را پاک‌سازی می‌کند.
+---
 
-## حامیان (Sponsors)
+## Sponsors
 
-شرکت‌ها، سازمان‌ها و افراد زیر از نگهداری و توسعه مداوم flux حمایت می‌کنند. با تبدیل شدن به یک حامی، لوگوی خود را در README و وب‌سایت ما قرار دهید.
+Flux and Alwatr packages are supported by our sponsors. Become a Sponsor to place your logo here.
 
-## مشارکت (Contributing)
+## Contributing
 
-از مشارکت‌ها استقبال می‌شود! لطفاً قبل از ارسال pull request، [راهنمای مشارکت ما](https://github.com/Alwatr/.github/blob/next/CONTRIBUTING.md) را مطالعه کنید.
+Contributions are welcome! Please read our [contribution guidelines](https://github.com/Alwatr/.github/blob/next/CONTRIBUTING.md) before submitting pull requests.