@alwatr/signal 9.11.2 → 9.12.0

package/README.md

@@ -31,6 +31,8 @@ There is also a fourth type for stateless events:
 
 4. **`EventSignal`**: A stateless signal for dispatching one-off events that don't have a persistent value.
 
+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.
+
 ---
 
 ## Getting Started: A Practical Example
@@ -128,6 +130,179 @@ User: Jane has clicked 0 times.
 User: Jane has clicked 1 times.
 ```
 
+---
+
+## ChannelSignal: A Typed Message Bus
+
+### 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:
+
+```typescript
+// ❌ Verbose and hard to manage
+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'});
+// ... and so on for every action in your app
+```
+
+**`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
+
+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
+
+First, define a **message map** — a TypeScript interface that maps every valid message name to its payload type:
+
+```typescript
+import {ChannelSignal} from '@alwatr/signal';
+
+// Define the message map for your application
+interface AppMessages {
+  'open-drawer': {panel: string};
+  'close-drawer': void; // no payload
+  'show-toast': {message: string; type: 'info' | 'error'};
+  'navigate': {path: string};
+}
+
+// Create the channel
+const appChannel = new ChannelSignal<AppMessages>({name: 'app-channel'});
+```
+
+### 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
+});
+
+// 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
+});
+
+// Subscribe to 'close-drawer' (no payload)
+appChannel.on('close-drawer', (payload) => {
+  console.log('Closing drawer');
+  // TypeScript knows payload is void | undefined
+});
+```
+
+### 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.
+
+```typescript
+// Dispatch with payload
+appChannel.dispatch('open-drawer', {panel: 'settings'}); // ✅ Type-safe
+appChannel.dispatch('show-toast', {message: 'Saved!', type: 'info'}); // ✅
+
+// Dispatch without payload
+appChannel.dispatch('close-drawer'); // ✅
+
+// ❌ TypeScript errors:
+appChannel.dispatch('open-drawer', {panel: 123}); // Error: panel must be string
+appChannel.dispatch('show-toast', {message: 'Hi'}); // Error: missing 'type'
+appChannel.dispatch('unknown-action'); // Error: 'unknown-action' is not in AppMessages
+```
+
+### Unsubscribing
+
+Just like other signals, `.on()` returns a `SubscribeResult` with an `unsubscribe()` method:
+
+```typescript
+const sub = appChannel.on('navigate', (payload) => {
+  router.push(payload!.path);
+});
+
+// Later, when the component is destroyed:
+sub.unsubscribe();
+```
+
+### One-Time Subscriptions
+
+Use the `once` option to automatically unsubscribe after the first message:
+
+```typescript
+appChannel.on(
+  'app-ready',
+  () => {
+    console.log('App initialized!');
+  },
+  {once: true},
+);
+```
+
+### 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:
+
+```typescript
+// Log every message for debugging
+appChannel.subscribe((msg) => {
+  console.log(`[channel] ${String(msg.name)}`, msg.payload);
+});
+```
+
+**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
+
+`ChannelSignal` is ideal for:
+
+- **Action layers** in Unidirectional Data Flow architectures (like `@alwatr/action`)
+- **Event buses** in component-based UIs (e.g., a global app event channel)
+- **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
+
+```typescript
+import {ChannelSignal} from '@alwatr/signal';
+
+// Define all app actions
+interface AppActions {
+  'user-login': {username: string};
+  'user-logout': void;
+  'cart-add-item': {productId: number; quantity: number};
+  'cart-remove-item': {productId: number};
+  'navigate': {path: string};
+}
+
+const actionChannel = new ChannelSignal<AppActions>({name: 'app-actions'});
+
+// Business logic subscribes to actions
+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 dispatches actions (e.g., from button clicks)
+loginButton.addEventListener('click', () => {
+  actionChannel.dispatch('user-login', {username: 'ali'});
+});
+
+addToCartButton.addEventListener('click', () => {
+  actionChannel.dispatch('cart-add-item', {productId: 42, quantity: 1});
+});
+```
+
+---
+
 ## Advanced Topics
 
 ### Lifecycle Management and Memory Leaks
@@ -199,6 +374,14 @@ The `subscribe` method accepts an optional second argument to customize its beha
   - `config.name`: `string`
 - **`.dispatch(payload: T)`**: Dispatches an event to all listeners.
 
+### `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 }`.
@@ -252,6 +435,10 @@ Contributions are welcome! Please read our [contribution guidelines](https://git
 
 4. **`EventSignal`**: یک سیگنال بدون حالت برای ارسال رویدادهای یک‌باره که مقدار پایداری ندارند.
 
+و یک نوع پنجم برای مسیریابی پیام‌های چندگانه:
+
+5. **`ChannelSignal`**: یک Message Bus تایپ‌شده و بدون حالت. برخلاف `EventSignal` (یک سیگنال = یک نوع رویداد)، یک `ChannelSignal` واحد چندین نوع پیام با نام‌های مختلف را حمل می‌کند — هر کدام با نوع payload مخصوص خودشان — و آن‌ها را با سرعت **O(1)** به subscriber‌های مناسب هدایت می‌کند.
+
 ---
 
 ## شروع به کار: یک مثال عملی
@@ -349,6 +536,178 @@ User: Jane has clicked 0 times.
 User: Jane has clicked 1 times.
 ```
 
+---
+
+## ChannelSignal: یک Message Bus تایپ‌شده
+
+### چرا ChannelSignal؟
+
+در برنامه‌های واقعی، اغلب نیاز دارید انواع مختلفی از رویدادها یا پیام‌ها را dispatch کنید — مثلاً `'open-drawer'`، `'close-drawer'`، `'show-toast'`، `'navigate'` و غیره. می‌توانید برای هر کدام یک `EventSignal` جداگانه بسازید، اما این رویکرد به سرعت دست‌وپاگیر می‌شود:
+
+```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 آن نگاشت می‌کند:
+
+```typescript
+import {ChannelSignal} 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};
+}
+
+// ساخت 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 است
+});
+
+// Subscribe به 'close-drawer' (بدون payload)
+appChannel.on('close-drawer', () => {
+  console.log('Closing drawer');
+});
+```
+
+### Dispatch پیام‌ها
+
+از `.dispatch(name, payload)` برای ارسال پیام استفاده کنید. TypeScript اعمال می‌کند که payload با نوع تعریف‌شده برای آن نام در message map مطابقت داشته باشد.
+
+```typescript
+// Dispatch با payload
+appChannel.dispatch('open-drawer', {panel: 'settings'}); // ✅ Type-safe
+appChannel.dispatch('show-toast', {message: 'ذخیره شد!', type: 'info'}); // ✅
+
+// 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);
+});
+
+// بعداً، وقتی کامپوننت destroy می‌شود:
+sub.unsubscribe();
+```
+
+### Subscribe یک‌باره
+
+از گزینه `once` برای unsubscribe خودکار بعد از اولین پیام استفاده کنید:
+
+```typescript
+appChannel.on(
+  'app-ready',
+  () => {
+    console.log('برنامه آماده است!');
+  },
+  {once: true},
+);
+```
+
+### Subscribe به جریان خام (برای لاگ‌گیری/Middleware)
+
+اگر نیاز دارید **همه** پیام‌ها را صرف‌نظر از نام مشاهده کنید — مثلاً برای لاگ‌گیری، analytics یا middleware — از `.subscribe()` به جای `.on()` استفاده کنید. این متد envelope کامل `{name, payload}` را دریافت می‌کند:
+
+```typescript
+// لاگ کردن همه پیام‌ها برای debugging
+appChannel.subscribe((msg) => {
+  console.log(`[channel] ${String(msg.name)}`, msg.payload);
+});
+```
+
+**نکته مهم:** `.subscribe()` بر اساس نام فیلتر **نمی‌شود** — هر پیامی را دریافت می‌کند. برای موارد عادی، `.on(name, handler)` را ترجیح دهید تا subscriptionها متمرکز و کارآمد بمانند.
+
+### موارد استفاده
+
+`ChannelSignal` برای موارد زیر ایده‌آل است:
+
+- **لایه Action** در معماری‌های Unidirectional Data Flow (مثل `@alwatr/action`)
+- **Event Bus** در UI‌های مبتنی بر کامپوننت (مثلاً یک کانال رویداد سراسری برنامه)
+- **Command Dispatching** در سیستم‌های CQRS-style
+- **Pub/Sub Messaging** جایی که انواع پیام‌های مختلف دارید اما می‌خواهید یک کانال مرکزی داشته باشید
+
+### مثال کامل: یک سیستم Action
+
+```typescript
+import {ChannelSignal} from '@alwatr/signal';
+
+// تعریف همه action‌های برنامه
+interface AppActions {
+  'user-login': {username: string};
+  'user-logout': void;
+  'cart-add-item': {productId: number; quantity: number};
+  'cart-remove-item': {productId: number};
+  'navigate': {path: string};
+}
+
+const actionChannel = new ChannelSignal<AppActions>({name: 'app-actions'});
+
+// منطق تجاری به action‌ها subscribe می‌کند
+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});
+});
+```
+
+---
+
 ## مباحث پیشرفته
 
 ### مدیریت چرخه حیات و نشت حافظه
@@ -420,6 +779,14 @@ Alwatr Signal از یک مدل ناهمزمان قابل پیش‌بینی بر
   - `config.name`: `string`
 - **`.dispatch(payload: T)`**: یک رویداد را به تمام شنوندگان ارسال می‌کند.
 
+### `ChannelSignal<TMap>`
+
+- **`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 مفید است.
+
 ### متدهای مشترک
 
 - **`.subscribe(callback, options?)`**: یک شنونده را مشترک می‌کند. `{ unsubscribe: () => void }` را برمی‌گرداند.

package/dist/core/channel-signal.d.ts

@@ -0,0 +1,177 @@
+import { type AlwatrLogger } from '@alwatr/logger';
+import { SignalBase } from './signal-base.js';
+import type { SignalConfig, SubscribeOptions, SubscribeResult, ListenerCallback } from '../type.js';
+/**
+ * A single message dispatched through a `ChannelSignal`.
+ *
+ * `name` identifies the message type (e.g. `'open-drawer'`, `'add-to-cart'`).
+ * `payload` is the optional value attached to the message — its type is narrowed
+ * by the generic map `TMap` at the class level.
+ *
+ * @template TMap A record mapping message names to their payload types.
+ * @template K    The specific message name key (inferred, not set manually).
+ */
+export type ChannelMessage<TMap extends Record<string, unknown>, K extends keyof TMap = keyof TMap> = K extends keyof TMap ? {
+    name: K;
+    payload?: TMap[K];
+} : never;
+/**
+ * A typed handler for a specific named message on a `ChannelSignal`.
+ * Receives only the `payload` — the name is already known at subscription time.
+ *
+ * @template TMap A record mapping message names to their payload types.
+ * @template K    The specific message name key.
+ */
+export type ChannelHandler<TMap extends Record<string, unknown>, K extends keyof TMap> = (payload: TMap[K] | undefined) => void | Promise<void>;
+/**
+ * Configuration for creating a `ChannelSignal`.
+ */
+export interface ChannelSignalConfig extends SignalConfig {
+}
+/**
+ * A stateless multi-channel signal that acts as a typed O(1) message bus.
+ *
+ * `ChannelSignal` is ideal when you need a single signal to carry multiple
+ * distinct message types — each identified by a `name` — rather than creating
+ * a separate `EventSignal` for every event.
+ *
+ * ### Routing architecture
+ *
+ * Internally, `on()` subscriptions are stored in a per-name `Map` of handler
+ * sets. When a message is dispatched, only the handlers registered for that
+ * specific name are invoked — O(1) lookup regardless of how many distinct
+ * names are subscribed. The inherited `SignalBase` observer list is used
+ * exclusively by `subscribe()`, which receives the raw message stream for
+ * logging or middleware purposes.
+ *
+ * ### Type safety
+ *
+ * The generic parameter `TMap` is a record that maps every valid message name
+ * to its payload type. TypeScript enforces the correct payload type at both
+ * `dispatch` and `on` call sites.
+ *
+ * @template TMap A record mapping message names to their payload types.
+ *
+ * @example
+ * ```ts
+ * interface AppMessages {
+ *   'open-drawer': {panel: string};
+ *   'close-drawer': void;
+ *   'show-toast': {message: string; type: 'info' | 'error'};
+ * }
+ *
+ * const appChannel = new ChannelSignal<AppMessages>({name: 'app-channel'});
+ *
+ * // Subscribe to a specific message — handler receives payload directly
+ * appChannel.on('open-drawer', (payload) => {
+ *   openDrawer(payload!.panel);
+ * });
+ *
+ * // Dispatch a typed message
+ * appChannel.dispatch('open-drawer', {panel: 'settings'});
+ * appChannel.dispatch('close-drawer'); // no payload needed
+ * ```
+ */
+export declare class ChannelSignal<TMap extends Record<string, unknown>> extends SignalBase<ChannelMessage<TMap>> {
+    /**
+     * The logger instance for this signal.
+     * @protected
+     */
+    protected logger_: AlwatrLogger;
+    /**
+     * Per-name handler registry for O(1) routing.
+     *
+     * Each key is a message name; the value is a Set of `{handler, once}` entries
+     * registered via `on()`. Kept separate from `SignalBase`'s observer list so
+     * that `subscribe()` (raw stream) and `on()` (named routing) never interfere.
+     *
+     * @private
+     */
+    private readonly namedHandlers__;
+    constructor(config: ChannelSignalConfig);
+    /**
+     * Dispatches a named message to:
+     * 1. All handlers registered via `on(name, …)` for this specific name — O(1).
+     * 2. All raw-stream subscribers registered via `subscribe()` — O(N subscribers).
+     *
+     * The notification is scheduled as a microtask to ensure non-blocking,
+     * consistent delivery — matching the behavior of `EventSignal`.
+     *
+     * TypeScript enforces that `payload` matches the type declared for `name`
+     * in `TMap`. If the payload type is `void` or `undefined`, the argument can
+     * be omitted entirely.
+     *
+     * @param name    The message name (must be a key of `TMap`).
+     * @param payload The optional payload for the message.
+     *
+     * @example
+     * ```ts
+     * channel.dispatch('open-drawer', {panel: 'settings'});
+     * channel.dispatch('close-drawer'); // no payload needed
+     * ```
+     */
+    dispatch<K extends keyof TMap>(name: K, payload?: TMap[K]): void;
+    /**
+     * Subscribes to a specific named message on this channel.
+     *
+     * Uses an internal per-name handler map for O(1) routing — dispatching a
+     * message with name `'A'` will never invoke handlers registered for `'B'`.
+     *
+     * 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.
+     *
+     * @param name    The message name to listen for.
+     * @param handler Callback invoked with the payload each time the named message
+     *                is dispatched.
+     * @param options Standard subscribe options. Only `once` is supported here;
+     *                `priority` applies to `subscribe()` (raw stream) only.
+     * @returns A `SubscribeResult` with an `unsubscribe()` method for cleanup.
+     *
+     * @example
+     * ```ts
+     * const sub = channel.on('open-drawer', (payload) => {
+     *   openDrawer(payload!.panel);
+     * });
+     *
+     * // Stop listening when the component is destroyed
+     * sub.unsubscribe();
+     * ```
+     */
+    on<K extends keyof TMap>(name: K, handler: ChannelHandler<TMap, K>, options?: Pick<SubscribeOptions, 'once'>): SubscribeResult;
+    /**
+     * Subscribes to **all** messages dispatched on this channel, regardless of name.
+     *
+     * Use this when you need to observe the raw message stream — for example,
+     * for logging, debugging, or middleware-style processing.
+     *
+     * Prefer `on(name, handler)` for normal use cases to keep subscriptions
+     * focused and type-safe.
+     *
+     * @param callback The function called with every `ChannelMessage`.
+     * @param options  Standard subscribe options.
+     * @returns A `SubscribeResult` with an `unsubscribe()` method.
+     *
+     * @example
+     * ```ts
+     * // Log every message for debugging
+     * channel.subscribe((msg) => console.log('[channel]', msg.name, msg.payload));
+     * ```
+     */
+    subscribe(callback: ListenerCallback<ChannelMessage<TMap>>, options?: SubscribeOptions): SubscribeResult;
+    /**
+     * Core routing method — called inside the microtask scheduled by `dispatch`.
+     *
+     * 1. Looks up the per-name handler set in O(1).
+     * 2. Invokes each handler, removing `once` entries after their first call.
+     * 3. Notifies raw-stream subscribers via `SignalBase.notify_()`.
+     *
+     * @private
+     */
+    private route__;
+    /**
+     * Destroys the signal, clearing all named handlers and raw-stream subscribers.
+     */
+    destroy(): void;
+}
+//# sourceMappingURL=channel-signal.d.ts.map

package/dist/core/channel-signal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-signal.d.ts","sourceRoot":"","sources":["../../src/core/channel-signal.ts"],"names":[],"mappings":"AACA,OAAO,EAAe,KAAK,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAE/D,OAAO,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAE5C,OAAO,KAAK,EAAC,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,gBAAgB,EAAC,MAAM,YAAY,CAAC;AAIlG;;;;;;;;;GASG;AACH,MAAM,MAAM,cAAc,CAAC,IAAI,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,SAAS,MAAM,IAAI,GAAG,MAAM,IAAI,IAChG,CAAC,SAAS,MAAM,IAAI,GAAG;IAAC,IAAI,EAAE,CAAC,CAAC;IAAC,OAAO,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAA;CAAC,GAAG,KAAK,CAAC;AAE9D;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,CAAC,IAAI,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,SAAS,MAAM,IAAI,IAAI,CACvF,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,GAAG,SAAS,KACzB,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE1B;;GAEG;AACH,MAAM,WAAW,mBAAoB,SAAQ,YAAY;CAAG;AAI5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,qBAAa,aAAa,CAAC,IAAI,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAE,SAAQ,UAAU,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;IACvG;;;OAGG;IACH,SAAS,CAAC,OAAO,EAAE,YAAY,CAAC;IAEhC;;;;;;;;OAQG;IACH,OAAO,CAAC,QAAQ,CAAC,eAAe,CACpB;gBAEA,MAAM,EAAE,mBAAmB;IAMvC;;;;;;;;;;;;;;;;;;;;OAoBG;IACI,QAAQ,CAAC,CAAC,SAAS,MAAM,IAAI,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI;IAMvE;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACI,EAAE,CAAC,CAAC,SAAS,MAAM,IAAI,EAC5B,IAAI,EAAE,CAAC,EACP,OAAO,EAAE,cAAc,CAAC,IAAI,EAAE,CAAC,CAAC,EAChC,OAAO,CAAC,EAAE,IAAI,CAAC,gBAAgB,EAAE,MAAM,CAAC,GACvC,eAAe;IA2BlB;;;;;;;;;;;;;;;;;;OAkBG;IACa,SAAS,CACvB,QAAQ,EAAE,gBAAgB,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,EAChD,OAAO,CAAC,EAAE,gBAAgB,GACzB,eAAe;IAKlB;;;;;;;;OAQG;IACH,OAAO,CAAC,OAAO;IAyBf;;OAEG;IACa,OAAO,IAAI,IAAI;CAIhC"}

package/dist/core/signal-base.d.ts

@@ -68,6 +68,7 @@ export declare abstract class SignalBase<T> {
      * Executes a given observer's callback with the provided value, handling both synchronous and asynchronous callbacks.
      */
     private executeObserver__;
+    private pendingRejects__;
     /**
      * Returns a Promise that resolves with the next value dispatched by the signal.
      * This provides an elegant way to wait for a single, future event using `async/await`.

package/dist/core/signal-base.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"signal-base.d.ts","sourceRoot":"","sources":["../../src/core/signal-base.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,SAAS,EAAE,gBAAgB,EAAE,eAAe,EAAE,gBAAgB,EAAE,YAAY,EAAC,MAAM,YAAY,CAAC;AAC7G,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAEjD;;;;;GAKG;AACH,8BAAsB,UAAU,CAAC,CAAC;IAoCpB,SAAS,CAAC,OAAO,EAAE,YAAY;IAnC3C;;;OAGG;IACH,SAAgB,IAAI,EAAE,MAAM,CAAC;IAE7B;;;OAGG;IACH,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAEzC;;;OAGG;IACH,SAAS,CAAC,QAAQ,CAAC,kBAAkB,oBAA2B;IAChE,SAAS,CAAC,QAAQ,CAAC,UAAU,oBAA2B;IAExD;;;OAGG;IACH,OAAO,CAAC,aAAa,CAAS;IAE9B;;;;;OAKG;IACH,IAAW,WAAW,IAAI,OAAO,CAEhC;gBAEqB,OAAO,EAAE,YAAY;IAI3C;;;;;OAKG;IACH,SAAS,CAAC,eAAe,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI;IAYvD;;;;;;;;OAQG;IACI,SAAS,CAAC,QAAQ,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,eAAe;IAkB5F;;;;;;;;OAQG;IACH,SAAS,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI;IAiBjC;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAczB;;;;;;;;;;;;OAYG;IACI,SAAS,IAAI,OAAO,CAAC,CAAC,CAAC;IAY9B;;;;;;OAMG;IACI,OAAO,IAAI,IAAI;IAatB;;;;OAIG;IACH,SAAS,CAAC,eAAe,IAAI,IAAI;CAMlC"}
+{"version":3,"file":"signal-base.d.ts","sourceRoot":"","sources":["../../src/core/signal-base.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,SAAS,EAAE,gBAAgB,EAAE,eAAe,EAAE,gBAAgB,EAAE,YAAY,EAAC,MAAM,YAAY,CAAC;AAC7G,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAEjD;;;;;GAKG;AACH,8BAAsB,UAAU,CAAC,CAAC;IAoCpB,SAAS,CAAC,OAAO,EAAE,YAAY;IAnC3C;;;OAGG;IACH,SAAgB,IAAI,EAAE,MAAM,CAAC;IAE7B;;;OAGG;IACH,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAEzC;;;OAGG;IACH,SAAS,CAAC,QAAQ,CAAC,kBAAkB,oBAA2B;IAChE,SAAS,CAAC,QAAQ,CAAC,UAAU,oBAA2B;IAExD;;;OAGG;IACH,OAAO,CAAC,aAAa,CAAS;IAE9B;;;;;OAKG;IACH,IAAW,WAAW,IAAI,OAAO,CAEhC;gBAEqB,OAAO,EAAE,YAAY;IAI3C;;;;;OAKG;IACH,SAAS,CAAC,eAAe,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI;IAYvD;;;;;;;;OAQG;IACI,SAAS,CAAC,QAAQ,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,eAAe;IAkB5F;;;;;;;;OAQG;IACH,SAAS,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI;IAiBjC;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAczB,OAAO,CAAC,gBAAgB,CAAqC;IAE7D;;;;;;;;;;;;OAYG;IACI,SAAS,IAAI,OAAO,CAAC,CAAC,CAAC;IAmB9B;;;;;;OAMG;IACI,OAAO,IAAI,IAAI;IAqBtB;;;;OAIG;IACH,SAAS,CAAC,eAAe,IAAI,IAAI;CAMlC"}

package/dist/creators/channel.d.ts

@@ -0,0 +1,39 @@
+import { ChannelSignal } from '../core/channel-signal.js';
+import type { ChannelSignalConfig } from '../core/channel-signal.js';
+/**
+ * Creates a stateless multi-channel signal that acts as a typed message bus.
+ *
+ * `ChannelSignal` is ideal when you need a single signal to carry multiple
+ * distinct message types — each identified by a `name` — rather than creating
+ * a separate `EventSignal` for every event.
+ *
+ * The generic parameter `TMap` is a record that maps every valid message name
+ * to its payload type, giving you full type safety at both dispatch and subscribe sites.
+ *
+ * @template TMap A record mapping message names to their payload types.
+ *
+ * @param config The configuration for the channel signal.
+ * @returns A new instance of `ChannelSignal`.
+ *
+ * @example
+ * ```ts
+ * interface AppMessages {
+ *   'open-drawer': {panel: string};
+ *   'close-drawer': void;
+ *   'show-toast': {message: string; type: 'info' | 'error'};
+ * }
+ *
+ * const appChannel = createChannelSignal<AppMessages>({name: 'app-channel'});
+ *
+ * // Subscribe to a specific message
+ * appChannel.on('show-toast', (payload) => {
+ *   toast.show(payload!.message, payload!.type);
+ * });
+ *
+ * // Dispatch a message
+ * appChannel.dispatch('show-toast', {message: 'Saved!', type: 'info'});
+ * appChannel.dispatch('close-drawer');
+ * ```
+ */
+export declare function createChannelSignal<TMap extends Record<string, unknown>>(config: ChannelSignalConfig): ChannelSignal<TMap>;
+//# sourceMappingURL=channel.d.ts.map

package/dist/creators/channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../../src/creators/channel.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,aAAa,EAAC,MAAM,2BAA2B,CAAC;AAExD,OAAO,KAAK,EAAC,mBAAmB,EAAC,MAAM,2BAA2B,CAAC;AAEnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACtE,MAAM,EAAE,mBAAmB,GAC1B,aAAa,CAAC,IAAI,CAAC,CAErB"}

package/dist/main.d.ts

@@ -5,12 +5,14 @@ export * from './core/computed-signal.js';
 export * from './core/effect-signal.js';
 export * from './core/persistent-state-signal.js';
 export * from './core/session-state-signal.js';
+export * from './core/channel-signal.js';
 export * from './creators/event.js';
 export * from './creators/state.js';
 export * from './creators/computed.js';
 export * from './creators/effect.js';
 export * from './creators/persistent-state.js';
 export * from './creators/session-state.js';
+export * from './creators/channel.js';
 export * from './operators/debounce.js';
 export * from './operators/filter.js';
 export * from './operators/map.js';

package/dist/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yBAAyB,CAAC;AACxC,cAAc,mCAAmC,CAAC;AAClD,cAAc,gCAAgC,CAAC;AAE/C,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,6BAA6B,CAAC;AAE5C,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AAEnC,mBAAmB,WAAW,CAAC"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yBAAyB,CAAC;AACxC,cAAc,mCAAmC,CAAC;AAClD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,0BAA0B,CAAC;AAEzC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,uBAAuB,CAAC;AAEtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AAEnC,mBAAmB,WAAW,CAAC"}