@actdim/msgmesh 1.2.8 → 1.2.9

package/README.md

@@ -4,6 +4,39 @@
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.9+-blue.svg)](https://www.typescriptlang.org/)
 [![License: Proprietary](https://img.shields.io/badge/License-Proprietary-red.svg)](LICENSE)
 
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Installation](#installation)
+- [Overview](#overview)
+  - [The Challenge](#the-challenge)
+  - [Analysis of Existing Solutions](#analysis-of-existing-solutions)
+  - [The Solution](#the-solution-actdimmsgmesh)
+  - [Implementation Foundation](#implementation-foundation)
+  - [Key Design Goals](#key-design-goals)
+- [Architecture](#architecture)
+  - [Message Structure](#message-structure)
+  - [Type Definition Example](#type-definition-example)
+- [Usage Patterns](#usage-patterns)
+  - [Global vs Local Usage](#global-vs-local-usage)
+  - [Creating a Message Bus](#creating-a-message-bus)
+  - [Type Utilities](#type-utilities)
+- [API Reference](#api-reference)
+  - [Configuration](#configuration)
+  - [`send()`](#sending-messages-send)
+  - [`on()`](#subscribing-to-messages-on)
+  - [`once()`](#awaiting-a-single-message-once)
+  - [`stream()`](#streaming-messages-stream)
+  - [`provide()`](#providing-response-handlers-provide)
+  - [`request()`](#request-response-pattern-request)
+- [Advanced Features](#advanced-features)
+  - [Message Replay](#message-replay)
+  - [Throttling and Debouncing](#throttling-and-debouncing)
+  - [Error Handling](#error-handling)
+  - [Headers and Metadata](#headers-and-metadata)
+  - [Service Adapters](#service-adapters)
+- [Comparison](#comparison-with-other-solutions)
+
 ## Quick Start
 
 Try @actdim/msgmesh instantly in your browser without any installation:
@@ -545,9 +578,6 @@ for await (const msg of messageStream) {
 const taskStream = msgBus.stream({
     channel: 'Test.DoSomeWork',
     topic: '/^task-.*/',
-    options: {
-        timeout: 30000, // Stop streaming after 30s of inactivity
-    },
 });
 
 for await (const msg of taskStream) {
@@ -555,6 +585,39 @@ for await (const msg of taskStream) {
 }
 ```
 
+#### Timeout and Cancellation
+
+The `timeout` option is an **inactivity timeout** — the timer resets on each received message. If no message arrives within the timeout window, the stream ends with a `TimeoutError`. This is useful for detecting when the producer has stopped sending.
+
+For a hard time limit on the stream's total duration, use `AbortSignal.timeout()`.
+
+```typescript
+// Inactivity timeout: end stream if no messages for 5s
+const stream1 = msgBus.stream({
+    channel: 'Test.Events',
+    options: {
+        timeout: 5000,
+    },
+});
+
+// Total duration limit: end stream after 60s regardless of activity
+const stream2 = msgBus.stream({
+    channel: 'Test.Events',
+    options: {
+        abortSignal: AbortSignal.timeout(60000),
+    },
+});
+
+// Both: inactivity 5s + hard limit 60s
+const stream3 = msgBus.stream({
+    channel: 'Test.Events',
+    options: {
+        timeout: 5000,
+        abortSignal: AbortSignal.timeout(60000),
+    },
+});
+```
+
 ### Providing Response Handlers: `provide()`
 
 Register a handler for messages on a selected channel and group (typically `in`), which generates a response message for the `out` group of the same channel. This is essentially a subscription with automatic response handling.
@@ -896,6 +959,134 @@ await msgBus.send({
 });
 ```
 
+### Service Adapters
+
+Automatically register any service object (e.g. a Swagger-generated API client) as a message bus provider. The adapter system uses TypeScript's type system to map service methods to bus channels at compile time — channel names, payload types, and return types are all derived from the service class. No manual wiring, no runtime errors.
+
+#### How It Works
+
+Given a service class:
+
+```typescript
+class OrderApiClient {
+    static readonly name = 'OrderApiClient' as const;
+    readonly name = 'OrderApiClient' as const;
+
+    createOrder(items: Item[], priority: number): Promise<OrderResult> { /* ... */ }
+    getOrder(id: string): Promise<Order> { /* ... */ }
+
+    // Internal helper — should not be exposed on the bus
+    formatResponse() { /* ... */ }
+}
+```
+
+The type utilities transform it into a bus structure:
+
+```typescript
+import {
+    ToMsgChannelPrefix,
+    ToMsgStruct,
+    BaseServiceSuffix,
+    registerAdapters,
+    getMsgChannelSelector,
+    MsgProviderAdapter
+} from '@actdim/msgmesh/adapters';
+
+// 1. Generate channel prefix from class name
+//    "OrderApiClient" → remove suffix "Client" → uppercase → "API.ORDER."
+type ApiPrefix = 'API';
+type OrderChannelPrefix = ToMsgChannelPrefix<
+    typeof OrderApiClient.name,  // "OrderApiClient"
+    ApiPrefix,                    // "API"
+    BaseServiceSuffix             // removes CLIENT, API, SERVICE, etc.
+>;
+// Result: "API.ORDER."
+
+// 2. Transform service methods into bus struct (skip internal methods)
+type OrderApiStruct = ToMsgStruct<
+    OrderApiClient,
+    OrderChannelPrefix,
+    'formatResponse'  // skip this method
+>;
+// Result type (compile-time):
+// {
+//     "API.ORDER.CREATEORDER": {
+//         in: [items: Item[], priority: number];  // ← tuple from Parameters<>
+//         out: OrderResult;                        // ← from ReturnType<>
+//     };
+//     "API.ORDER.GETORDER": {
+//         in: [id: string];
+//         out: Order;
+//     };
+// }
+```
+
+All channel names, payload types, and return types are verified at compile time. If you rename a method, add a parameter, or change a return type — the compiler catches it immediately.
+
+#### Registering Adapters
+
+```typescript
+const services: Record<OrderChannelPrefix, any> = {
+    'API.ORDER.': new OrderApiClient(),
+};
+
+const adapters = Object.entries(services).map(([_, service]) => ({
+    service,
+    channelSelector: getMsgChannelSelector(services),
+}) as MsgProviderAdapter);
+
+const msgBus = createMsgBus<OrderApiStruct>();
+const abortController = new AbortController();
+
+// Register all methods as providers
+registerAdapters(msgBus, adapters, abortController.signal);
+
+// Clean up when done
+abortController.abort();
+```
+
+`registerAdapters()` iterates over each method of the service prototype, resolves the channel name via `channelSelector`, and calls `msgBus.provide()` for each one. The provider callback spreads `msg.payload` (a tuple) as arguments to the original method: `service[methodName](...msg.payload)`.
+
+#### Calling Adapted Methods
+
+Since method parameters are mapped to tuple types in the bus struct, use `payloadFn` for a natural function-call syntax:
+
+```typescript
+// Type-safe call — fn signature matches createOrder(items, priority)
+const response = await msgBus.request({
+    channel: 'API.ORDER.CREATEORDER',
+    payloadFn: fn => fn([{ id: '1', qty: 2 }], 1),
+});
+
+console.log(response.payload); // OrderResult
+
+// Also works with payload directly (tuple)
+const response2 = await msgBus.request({
+    channel: 'API.ORDER.GETORDER',
+    payload: ['order-123'],
+});
+```
+
+#### Type Transformation Chain
+
+```
+Service class                  ToMsgChannelPrefix              ToMsgStruct
+─────────────                  ──────────────────              ───────────
+OrderApiClient          →      "API.ORDER."              →    Bus struct
+  .createOrder(a, b)              ↑                              ↓
+  .getOrder(id)              removes suffix              "API.ORDER.CREATEORDER"
+  .formatResponse()          from class name               in: [a, b] (Parameters<>)
+                             + uppercases                  out: Result  (ReturnType<>)
+                                                         "API.ORDER.GETORDER"
+                                                           in: [id]
+                                                           out: Order
+                                                         (formatResponse skipped)
+```
+
+#### Supported Service Suffixes
+
+The following suffixes are automatically removed from class names: `CLIENT`, `API`, `SERVICE`, `FETCHER`, `CONTROLLER`, `LOADER`, `REPOSITORY`, `PROVIDER`.
+
 ## Comparison with Other Solutions
 
 | Feature          | @actdim/msgmesh | Event Emitters | RxJS        |

package/dist/adapters.d.ts

@@ -0,0 +1,20 @@
+import { MsgBus, MsgStruct, MsgStructFactory } from './contracts';
+import { AddPrefix, Filter, Func, RemoveSuffix, Skip, ToUpper } from '@actdim/utico/typeCore';
+export type MsgProviderAdapter = {
+    service: any;
+    channelSelector: (service: any, methodName: string) => string;
+};
+export declare function registerAdapters(msgBus: MsgBus<MsgStruct>, adapters: MsgProviderAdapter[], abortSignal?: AbortSignal): void;
+export type BaseServiceSuffix = 'CLIENT' | 'API' | 'SERVICE' | 'FETCHER' | 'CONTROLLER' | 'LOADER' | 'REPOSITORY' | 'PROVIDER';
+export type BaseWordSeparator = ".";
+export type ToMsgChannelPrefix<TServiceName extends string, Prefix extends string, Suffix extends string = BaseServiceSuffix, WordSeparator extends string = BaseWordSeparator> = `${Prefix}${WordSeparator}${RemoveSuffix<Uppercase<TServiceName>, Suffix>}${WordSeparator}`;
+type ToMsgStructSource<TService, TPrefix extends string, TSkip extends keyof TService = never> = Filter<ToUpper<AddPrefix<Skip<TService, TSkip>, TPrefix>>, Func>;
+export type ToMsgStruct<TService, TPrefix extends string, TSkip extends keyof TService = never, TMsgStructSource = ToMsgStructSource<TService, TPrefix, TSkip>> = MsgStructFactory<{
+    [K in keyof TMsgStructSource as TMsgStructSource[K] extends Func ? (Uppercase<K extends string ? K : never>) : never]: {
+        in: TMsgStructSource[K] extends Func ? Parameters<TMsgStructSource[K]> : never;
+        out: TMsgStructSource[K] extends Func ? ReturnType<TMsgStructSource[K]> : never;
+    };
+}>;
+export declare function getMsgChannelSelector<TTPrefix extends string>(services: Record<TTPrefix, any>): (service: any, methodName: string) => string;
+export {};
+//# sourceMappingURL=adapters.d.ts.map

package/dist/adapters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapters.d.ts","sourceRoot":"","sources":["../src/adapters.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAClE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAY9F,MAAM,MAAM,kBAAkB,GAAG;IAC7B,OAAO,EAAE,GAAG,CAAC;IAEb,eAAe,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,KAAK,MAAM,CAAC;CACjE,CAAC;AAEF,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,CAAC,SAAS,CAAC,EAAE,QAAQ,EAAE,kBAAkB,EAAE,EAAE,WAAW,CAAC,EAAE,WAAW,QAwBpH;AAED,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,KAAK,GAAG,SAAS,GAAG,SAAS,GAAG,YAAY,GAAG,QAAQ,GAAG,YAAY,GAAG,UAAU,CAAC;AAC/H,MAAM,MAAM,iBAAiB,GAAG,GAAG,CAAC;AAIpC,MAAM,MAAM,kBAAkB,CAC1B,YAAY,SAAS,MAAM,EAC3B,MAAM,SAAS,MAAM,EACrB,MAAM,SAAS,MAAM,GAAG,iBAAiB,EACzC,aAAa,SAAS,MAAM,GAAG,iBAAiB,IAChD,GAAG,MAAM,GAAG,aAAa,GAAG,YAAY,CAAC,SAAS,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC,GAAG,aAAa,EAAE,CAAC;AAEhG,KAAK,iBAAiB,CAAC,QAAQ,EAAE,OAAO,SAAS,MAAM,EAAE,KAAK,SAAS,MAAM,QAAQ,GAAG,KAAK,IAAI,MAAM,CACnG,OAAO,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,EAAE,OAAO,CAAC,CAAC,EAClD,IAAI,CACP,CAAC;AAEF,MAAM,MAAM,WAAW,CAAC,QAAQ,EAAE,OAAO,SAAS,MAAM,EAAE,KAAK,SAAS,MAAM,QAAQ,GAAG,KAAK,EAAE,gBAAgB,GAAG,iBAAiB,CAAC,QAAQ,EAAE,OAAO,EAAE,KAAK,CAAC,IAAI,gBAAgB,CAAC;KAC9K,CAAC,IAAI,MAAM,gBAAgB,IAAI,gBAAgB,CAAC,CAAC,CAAC,SAAS,IAAI,GAAG,CAAC,SAAS,CAAC,CAAC,SAAS,MAAM,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,GAAG,KAAK,GAAG;QACnH,EAAE,EAAE,gBAAgB,CAAC,CAAC,CAAC,SAAS,IAAI,GAAG,UAAU,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC;QAC/E,GAAG,EAAE,gBAAgB,CAAC,CAAC,CAAC,SAAS,IAAI,GAAG,UAAU,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC;KACnF;CACJ,CAAC,CAAC;AAEH,wBAAgB,qBAAqB,CAAC,QAAQ,SAAS,MAAM,EACzD,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,GAAG,CAAC,IAEvB,SAAS,GAAG,EAAE,YAAY,MAAM,YAO3C"}

package/dist/adapters.es.js

@@ -0,0 +1,33 @@
+const s = (t) => Object.getOwnPropertyNames(t).filter(
+  (e) => e !== "constructor" && typeof t[e] == "function"
+);
+function l(t, e, n) {
+  if (e)
+    for (const o of e) {
+      const { service: r, channelSelector: c } = o;
+      if (!r || !c)
+        throw new Error("Service and channelSelector are required for an adapter");
+      for (const a of s(Object.getPrototypeOf(r))) {
+        const f = c?.(r, a);
+        f && t.provide({
+          channel: f,
+          topic: "/.*/",
+          callback: (i) => r[a](...i.payload || []),
+          options: {
+            abortSignal: n
+          }
+        });
+      }
+    }
+}
+function p(t) {
+  return (e, n) => {
+    const o = Object.entries(t).find((r) => r[1] === e);
+    return o ? `${o[0]}${n.toUpperCase()}` : null;
+  };
+}
+export {
+  p as getMsgChannelSelector,
+  l as registerAdapters
+};
+//# sourceMappingURL=adapters.es.js.map

package/dist/adapters.es.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapters.es.js","sources":["../src/adapters.ts"],"sourcesContent":null,"names":["getMethodNames","client","name","registerAdapters","msgBus","adapters","abortSignal","adapter","service","channelSelector","methodName","channel","msg","getMsgChannelSelector","services","entry"],"mappings":"AAGA,MAAMA,IAAiB,CAACC,MAEb,OAAO,oBAAoBA,CAAM,EAAE;AAAA,EACtC,CAACC,MAASA,MAAS,iBAAiB,OAAOD,EAAOC,CAAI,KAAM;AAAA;AAa7D,SAASC,EAAiBC,GAA2BC,GAAgCC,GAA2B;AACnH,MAAID;AACA,eAAWE,KAAWF,GAAU;AAC5B,YAAM,EAAE,SAAAG,GAAS,iBAAAC,EAAA,IAAoBF;AACrC,UAAI,CAACC,KAAW,CAACC;AACb,cAAM,IAAI,MAAM,yDAAyD;AAE7E,iBAAWC,KAAcV,EAAe,OAAO,eAAeQ,CAAO,CAAC,GAAG;AACrE,cAAMG,IAAUF,IAAkBD,GAASE,CAAU;AACrD,QAAIC,KACAP,EAAO,QAAQ;AAAA,UACX,SAAAO;AAAA,UACA,OAAO;AAAA,UACP,UAAU,CAACC,MACCJ,EAAQE,CAAU,EAAW,GAAKE,EAAI,WAAW,CAAA,CAAa;AAAA,UAE1E,SAAS;AAAA,YACL,aAAAN;AAAA,UAAA;AAAA,QACJ,CACH;AAAA,MAET;AAAA,IACJ;AAER;AA0BO,SAASO,EACZC,GACF;AACE,SAAO,CAACN,GAAcE,MAAuB;AACzC,UAAMK,IAAQ,OAAO,QAAQD,CAAQ,EAAE,KAAK,CAACC,MAAUA,EAAM,CAAC,MAAMP,CAAO;AAC3E,WAAKO,IAGE,GAAGA,EAAM,CAAC,CAAC,GAAGL,EAAW,aAAa,KAFlC;AAAA,EAGf;AACJ;"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@actdim/msgmesh",
-    "version": "1.2.8",
+    "version": "1.2.9",
     "description": "A type-safe, modular message mesh for scalable async communication in TypeScript",
     "author": "Pavel Borodaev",
     "license": "Proprietary",