@flux-control/effect-modbus-rs 0.1.1 → 0.2.0

package/README.md

@@ -2,12 +2,16 @@
 
 **Type-safe Modbus communication via Effect-TS**, wrapping the [`modbus-rs`](https://github.com/Raghava-Ch/modbus-rs) npm bindings (Rust napi-rs under the hood).
 
+For the complete API reference, see the [GitHub Pages documentation](https://flux-control-solutions.github.io/Effect-modbus-rs/).
+
 Provides scoped [`Effect.Service`](https://effect.website) constructors for RTU (serial), TCP, and ASCII Modbus transports. Clients expose a typed `Effect`-based API for all standard Modbus function codes.
 
+> This project is under active development. Its API may change before the 1.0 release.
+
 ## Install
 
 ```sh
-bun add effect-modbus-rs
+bun add @flux-control/effect-modbus-rs
 ```
 
 TypeScript only while prototyping (JS consumers will be supported before 1.0).
@@ -17,8 +21,8 @@ TypeScript only while prototyping (JS consumers will be supported before 1.0).
 ### RTU (serial)
 
 ```ts
-import { Console, Effect } from "effect";
-import { RtuTransportService } from "effect-modbus-rs";
+import { Console, Effect } from 'effect';
+import { RtuTransportService } from '@flux-control/effect-modbus-rs';
 
 const program = Effect.gen(function* () {
   const transport = yield* RtuTransportService;
@@ -28,25 +32,19 @@ const program = Effect.gen(function* () {
     address: 0,
     quantity: 10,
   });
-  console.log("Holding registers:", registers);
+  console.log('Holding registers:', registers);
 });
 
 program.pipe(
   Effect.catchTags({
     ModbusTimeoutError: (err) => Console.log(`Timeout: ${err.message}`),
-    ModbusTransportError: (err) =>
-      Console.log(`Transport error: ${err.message}`),
-    ModbusConnectionClosedError: (err) =>
-      Console.log(`Connection lost: ${err.message}`),
-    ModbusExceptionError: (err) =>
-      Console.log(`Modbus exception ${err.exception}: ${err.message}`),
-    ModbusInvalidArgumentError: (err) =>
-      Console.log(`Invalid argument: ${err.message}`),
+    ModbusTransportError: (err) => Console.log(`Transport error: ${err.message}`),
+    ModbusConnectionClosedError: (err) => Console.log(`Connection lost: ${err.message}`),
+    ModbusExceptionError: (err) => Console.log(`Modbus exception ${err.exception}: ${err.message}`),
+    ModbusInvalidArgumentError: (err) => Console.log(`Invalid argument: ${err.message}`),
   }),
   Effect.catchAll((err) => Console.log(`Unhandled error: ${err.message}`)),
-  Effect.provide(
-    RtuTransportService.Default({ portPath: "/dev/ttyUSB0", baudRate: 9600 }),
-  ),
+  Effect.provide(RtuTransportService.Default({ portPath: '/dev/ttyUSB0', baudRate: 9600 })),
   Effect.scoped,
   Effect.runPromise,
 );
@@ -55,20 +53,18 @@ program.pipe(
 ### TCP
 
 ```ts
-import { Effect } from "effect";
-import { TcpTransportService } from "effect-modbus-rs";
+import { Effect } from 'effect';
+import { TcpTransportService } from '@flux-control/effect-modbus-rs';
 
 const program = Effect.gen(function* () {
   const transport = yield* TcpTransportService;
   const client = yield* transport.withClient(1);
   const coils = yield* client.readCoils({ address: 0, quantity: 8 });
-  console.log("Coils:", coils);
+  console.log('Coils:', coils);
 });
 
 program.pipe(
-  Effect.provide(
-    TcpTransportService.Default({ host: "192.168.1.100", port: 502 }),
-  ),
+  Effect.provide(TcpTransportService.Default({ host: '192.168.1.100', port: 502 })),
   Effect.scoped,
   Effect.runPromise,
 );
@@ -77,8 +73,8 @@ program.pipe(
 ### ASCII
 
 ```ts
-import { Effect } from "effect";
-import { AsciiTransportService } from "effect-modbus-rs";
+import { Effect } from 'effect';
+import { AsciiTransportService } from '@flux-control/effect-modbus-rs';
 
 const program = Effect.gen(function* () {
   const transport = yield* AsciiTransportService;
@@ -87,48 +83,104 @@ const program = Effect.gen(function* () {
     address: 0,
     quantity: 5,
   });
-  console.log("Input registers:", registers);
+  console.log('Input registers:', registers);
 });
 
 program.pipe(
-  Effect.provide(
-    AsciiTransportService.Default({ portPath: "/dev/ttyUSB0", baudRate: 9600 }),
-  ),
+  Effect.provide(AsciiTransportService.Default({ portPath: '/dev/ttyUSB0', baudRate: 9600 })),
   Effect.scoped,
   Effect.runPromise,
 );
 ```
 
+### Browser / WASM (`modbus-rs/web`)
+
+`modbus-rs` ships its browser bindings through the `modbus-rs/web` WASM module. This package loads that module dynamically and exposes the same scoped, typed `Effect` client API as its native transports. Since browsers can't open raw TCP or serial connections directly, there are two browser-specific transports:
+
+- **`WasmWsTransportService`** — Modbus TCP over a WebSocket-to-TCP gateway (e.g. the `modbus-gateway` application).
+- **`WasmRtuTransportService`** / **`WasmAsciiTransportService`** — Modbus RTU/ASCII over the [Web Serial API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Serial_API), via `WasmSerialTransportService.fromRtu` / `.fromAscii`.
+
+```ts
+import { Console, Effect } from 'effect';
+import { WasmWsTransportService } from '@flux-control/effect-modbus-rs';
+
+const program = Effect.gen(function* () {
+  const transport = yield* WasmWsTransportService;
+  const client = yield* transport.withClient(1);
+  const registers = yield* client.readHoldingRegisters({ address: 0, quantity: 10 });
+  console.log('Holding registers:', registers);
+});
+
+program.pipe(
+  Effect.provide(WasmWsTransportService.Default({ wsUrl: 'ws://localhost:8080' })),
+  Effect.scoped,
+  Effect.runPromise,
+);
+```
+
+Web Serial requires a user-granted port handle. **`requestSerialPort()` must be called synchronously from within a user-gesture event handler** (e.g. a button click) — this is a Web Serial API / browser security requirement, not a library restriction:
+
+```ts
+import { Effect, Layer } from 'effect';
+import { requestSerialPort, WasmRtuTransportService } from '@flux-control/effect-modbus-rs';
+
+connectButton.addEventListener('click', () => {
+  Effect.runPromise(
+    Effect.gen(function* () {
+      const port = yield* requestSerialPort();
+      yield* program.pipe(
+        Effect.provide(WasmRtuTransportService.Default({ port, baudRate: 19200 })),
+        Effect.scoped,
+      );
+    }),
+  );
+});
+```
+
+See `examples/wasm/` for a real, runnable Vite app exercising both transports in an actual browser (`cd examples/wasm && npm install && npm run dev`).
+
+#### Browser server (experimental)
+
+`wasmWsServerLayer` and `wasmSerialRtuServerLayer` / `wasmSerialAsciiServerLayer` wrap `modbus-rs`'s experimental browser server bindings — same `ServerHandlers` callback shape as the native servers below. Two things differ from native:
+
+- Unlike native servers, the WASM server doesn't start serving on bind — these layers fork the required `serve()` loop into the layer's scope automatically, so usage looks the same as the native `tcpServerLayer`.
+- For the serial variants, `options.serialPort` comes from your own app's `navigator.serial.requestPort()` call (not from this package's `requestSerialPort()`, which returns a different wrapper type used only by the client transports).
+
+Not demonstrated in `examples/wasm/` (see that app's README) — the same `import { wasmWsServerLayer } from "@flux-control/effect-modbus-rs"` pattern applies.
+
 ## Transports
 
 Each transport is a scoped `Effect.Service`. You provide it with `Effect.provide`, and the connection is opened on service access and closed when the scope ends.
 
-| Service | Options | Connection |
-|---------|---------|------------|
-| `RtuTransportService` | `{ portPath, baudRate, ... }` | `AsyncRtuTransport.open()` |
-| `TcpTransportService` | `{ host, port, ... }` | `AsyncTcpTransport.connect()` |
-| `AsciiTransportService` | `{ portPath, baudRate, ... }` | `AsyncAsciiTransport.open()` |
+| Service                               | Options                        | Connection                    |
+| ------------------------------------- | ------------------------------ | ----------------------------- |
+| `RtuTransportService`                 | `{ portPath, baudRate, ... }`  | `AsyncRtuTransport.open()`    |
+| `TcpTransportService`                 | `{ host, port, ... }`          | `AsyncTcpTransport.connect()` |
+| `AsciiTransportService`               | `{ portPath, baudRate, ... }`  | `AsyncAsciiTransport.open()`  |
+| `WasmWsTransportService` (browser)    | `{ wsUrl, requestTimeoutMs? }` | `WasmWsTransport.connect()`   |
+| `WasmRtuTransportService` (browser)   | `{ port, baudRate, ... }`      | `WasmRtuTransport.open()`     |
+| `WasmAsciiTransportService` (browser) | `{ port, baudRate, ... }`      | `WasmAsciiTransport.open()`   |
 
-All transport options types are re-exported from `modbus-rs`.
+All transport options types are re-exported from `modbus-rs` (native transports) or `modbus-rs/web` (browser transports).
 
 ### Abstract serial transport
 
 `SerialTransportService` is a transport-agnostic tag that can be backed by either RTU or ASCII framing — useful when writing code that doesn't need to commit to a specific serial protocol. Provide it with `fromRtu` or `fromAscii`:
 
 ```ts
-import { Console, Effect } from "effect";
-import { SerialTransportService } from "effect-modbus-rs";
+import { Console, Effect } from 'effect';
+import { SerialTransportService } from '@flux-control/effect-modbus-rs';
 
 const program = Effect.gen(function* () {
   const transport = yield* SerialTransportService;
   const client = yield* transport.withClient(1);
   const coils = yield* client.readCoils({ address: 0, quantity: 2 });
-  console.log("Coils:", coils);
+  console.log('Coils:', coils);
 });
 
 // RTU framing
 program.pipe(
-  Effect.provide(SerialTransportService.fromRtu({ portPath: "/dev/ttyUSB0", baudRate: 9600 })),
+  Effect.provide(SerialTransportService.fromRtu({ portPath: '/dev/ttyUSB0', baudRate: 9600 })),
   Effect.scoped,
   Effect.runPromise,
 );
@@ -149,47 +201,47 @@ It also supports `makeMockTransport` for testing:
 
 ### Registers
 
-| Method | Returns |
-|--------|---------|
-| `readHoldingRegisters({ address, quantity })` | `number[]` |
-| `readInputRegisters({ address, quantity })` | `number[]` |
-| `writeSingleRegister({ address, value })` | `void` |
-| `writeMultipleRegisters({ address, values })` | `void` |
+| Method                                                                                 | Returns    |
+| -------------------------------------------------------------------------------------- | ---------- |
+| `readHoldingRegisters({ address, quantity })`                                          | `number[]` |
+| `readInputRegisters({ address, quantity })`                                            | `number[]` |
+| `writeSingleRegister({ address, value })`                                              | `void`     |
+| `writeMultipleRegisters({ address, values })`                                          | `void`     |
 | `readWriteMultipleRegisters({ readAddress, readQuantity, writeAddress, writeValues })` | `number[]` |
 
 ### Coils / discrete inputs
 
-| Method | Returns |
-|--------|---------|
-| `readCoils({ address, quantity })` | `boolean[]` |
-| `writeSingleCoil({ address, value })` | `void` |
-| `writeMultipleCoils({ address, values })` | `void` |
+| Method                                      | Returns     |
+| ------------------------------------------- | ----------- |
+| `readCoils({ address, quantity })`          | `boolean[]` |
+| `writeSingleCoil({ address, value })`       | `void`      |
+| `writeMultipleCoils({ address, values })`   | `void`      |
 | `readDiscreteInputs({ address, quantity })` | `boolean[]` |
 
 ### Diagnostics & file access
 
-| Method | Returns |
-|--------|---------|
-| `readExceptionStatus()` | `number` |
-| `diagnostics({ subFunction, data })` | `DiagnosticsResponse` |
-| `readFifoQueue({ address })` | `FifoQueueResponse` |
-| `readFileRecord({ requests })` | `number[][]` |
-| `writeFileRecord({ requests })` | `void` |
+| Method                                                     | Returns                        |
+| ---------------------------------------------------------- | ------------------------------ |
+| `readExceptionStatus()`                                    | `number`                       |
+| `diagnostics({ subFunction, data })`                       | `DiagnosticsResponse`          |
+| `readFifoQueue({ address })`                               | `FifoQueueResponse`            |
+| `readFileRecord({ requests })`                             | `number[][]`                   |
+| `writeFileRecord({ requests })`                            | `void`                         |
 | `readDeviceIdentification({ readDeviceIdCode, objectId })` | `DeviceIdentificationResponse` |
 
 ## Error handling
 
 Errors from the underlying Rust layer are mapped to typed `Effect` errors via `Data.TaggedError`:
 
-| Error class | Meaning |
-|-------------|---------|
-| `ModbusExceptionError` | Modbus protocol exception (contains `exception` code) |
-| `ModbusTimeoutError` | Request timed out |
-| `ModbusTransportError` | Transport-level failure |
-| `ModbusInvalidArgumentError` | Invalid parameters |
-| `ModbusConnectionClosedError` | Connection lost |
-| `ModbusNotConnectedError` | Operation attempted before connection |
-| `ModbusInternalError` | Unclassified error |
+| Error class                   | Meaning                                               |
+| ----------------------------- | ----------------------------------------------------- |
+| `ModbusExceptionError`        | Modbus protocol exception (contains `exception` code) |
+| `ModbusTimeoutError`          | Request timed out                                     |
+| `ModbusTransportError`        | Transport-level failure                               |
+| `ModbusInvalidArgumentError`  | Invalid parameters                                    |
+| `ModbusConnectionClosedError` | Connection lost                                       |
+| `ModbusNotConnectedError`     | Operation attempted before connection                 |
+| `ModbusInternalError`         | Unclassified error                                    |
 
 Handle with `Effect.catchTags`. The `ModbusError` union type covers all seven variants.
 
@@ -198,8 +250,8 @@ Handle with `Effect.catchTags`. The `ModbusError` union type covers all seven va
 Each transport service provides a `makeMockTransport(devices)` static method that returns an in-memory mock `Layer` — no serial port or network required.
 
 ```ts
-import { Console, Effect } from "effect";
-import { RtuTransportService } from "effect-modbus-rs";
+import { Console, Effect } from 'effect';
+import { RtuTransportService } from '@flux-control/effect-modbus-rs';
 
 const device = {
   unitId: 1,
@@ -219,19 +271,15 @@ const program = Effect.gen(function* () {
   const transport = yield* RtuTransportService;
   const client = yield* transport.withClient(1);
   const coils = yield* client.readCoils({ address: 0, quantity: 2 });
-  console.log("Coils:", coils);
+  console.log('Coils:', coils);
 });
 
 const mockLayer = RtuTransportService.makeMockTransport([device])({
-  portPath: "/dev/ttyUSB0",
+  portPath: '/dev/ttyUSB0',
   baudRate: 9600,
 });
 
-program.pipe(
-  Effect.provide(mockLayer),
-  Effect.scoped,
-  Effect.runPromise,
-);
+program.pipe(Effect.provide(mockLayer), Effect.scoped, Effect.runPromise);
 ```
 
 The mock factory is identical for all three transports; swap `RtuTransportService` for `TcpTransportService` or `AsciiTransportService` and adjust the options shape accordingly — each exposes a static `makeMockTransport` method.
@@ -240,23 +288,23 @@ See `examples/rtu-mock.ts`, `examples/tcp-mock.ts`, and `examples/ascii-mock.ts`
 
 ### Slave device schema
 
-| Property | Type | Default |
-|----------|------|---------|
-| `unitId` | `number` | required |
-| `coils` | `{ address, default }[]` | `[]` |
-| `discreteInputs` | `{ address, default }[]` | `[]` |
-| `holdingRegisters` | `{ address, default }[]` | `[]` |
-| `inputRegisters` | `{ address, default }[]` | `[]` |
+| Property           | Type                     | Default  |
+| ------------------ | ------------------------ | -------- |
+| `unitId`           | `number`                 | required |
+| `coils`            | `{ address, default }[]` | `[]`     |
+| `discreteInputs`   | `{ address, default }[]` | `[]`     |
+| `holdingRegisters` | `{ address, default }[]` | `[]`     |
+| `inputRegisters`   | `{ address, default }[]` | `[]`     |
 
 Coil/default values default to `false` if omitted at the address level; register values default to `0`. Reads beyond the highest configured address produce a `ModbusInvalidArgumentError`.
 
 ## Development
 
-| Action | Command |
-|--------|---------|
-| Install | `bun install` |
-| Type-check | `bun run typecheck` |
-| Test | `bun test` |
+| Action      | Command                      |
+| ----------- | ---------------------------- |
+| Install     | `bun install`                |
+| Type-check  | `bun run typecheck`          |
+| Test        | `bun test`                   |
 | Run example | `bun run examples/<name>.ts` |
 
 No build step — `noEmit` is on; Bun runs `.ts` directly.
@@ -266,13 +314,23 @@ No build step — `noEmit` is on; Bun runs `.ts` directly.
 ```
 src/
   errors.ts                  — Data.TaggedError types + toModbusError converter
-  modbus-client.ts           — EffectModbusClient interface + factory
+  modbus-client.ts           — EffectModbusClient interface + factory (native + WASM)
   mocks.ts                   — Schema-validated mock transport + slave device definitions
   shared-transport.ts        — Generic scoped transport lifecycle management
   RtuTransportService.ts     — Scoped Effect.Service wrapping AsyncRtuTransport
   TcpTransportService.ts     — Scoped Effect.Service wrapping AsyncTcpTransport
   AsciiTransportService.ts   — Scoped Effect.Service wrapping AsyncAsciiTransport
   SerialTransportService.ts  — Abstract serial transport (RTU/ASCII) tag
+  TcpModbusServerService.ts  — tcpServerLayer
+  SerialModbusServerService.ts — serialRtuServerLayer / serialAsciiServerLayer
+  TcpGatewayService.ts       — tcpGatewayLayer
+  WasmSerialPort.ts          — requestSerialPort() Effect helper (browser, user-gesture gated)
+  WasmWsTransportService.ts  — Scoped Effect.Service wrapping WasmWsTransport (browser, WS gateway)
+  WasmRtuTransportService.ts — Scoped Effect.Service wrapping WasmRtuTransport (browser, Web Serial RTU)
+  WasmAsciiTransportService.ts — Scoped Effect.Service wrapping WasmAsciiTransport (browser, Web Serial ASCII)
+  WasmSerialTransportService.ts — Abstract browser serial transport (RTU/ASCII) tag
+  WasmTcpServerService.ts    — wasmWsServerLayer (experimental)
+  WasmSerialModbusServerService.ts — wasmSerialRtuServerLayer / wasmSerialAsciiServerLayer (experimental)
 examples/
   rtu-basic.ts               — RTU usage pattern
   tcp-basic.ts               — TCP usage pattern
@@ -283,6 +341,9 @@ examples/
   ascii-mock.ts              — ASCII with in-memory mock (error-case)
   tcp-polling-stream.ts      — TCP polling, reconnect, and stream
   tcp-finalizer-reset.ts     — TCP scope finalizer reset demo
+  tcp-server.ts              — TCP server example
+  serial-server.ts           — Serial RTU server example
+  wasm/                      — Standalone runnable Vite app for the browser transports (own README, own npm project)
 index.ts                     — Re-exports public API
 ```
 

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * # effect-modbus-rs
+ * # @flux-control/effect-modbus-rs
  *
  * Type-safe Modbus communication via Effect-TS, wrapping the `modbus-rs`
  * npm bindings (Rust `napi-rs` under the hood).
@@ -11,6 +11,14 @@
  * - {@link AsciiTransportService} — Serial ASCII transport.
  * - {@link TcpTransportService} — TCP/IP transport (Modbus/TCP).
  *
+ * ## Browser (WASM) transport services
+ *
+ * - {@link WasmSerialTransportService} — Abstract Web Serial transport (ASCII or RTU).
+ * - {@link WasmRtuTransportService} — Web Serial RTU transport.
+ * - {@link WasmAsciiTransportService} — Web Serial ASCII transport.
+ * - {@link WasmWsTransportService} — TCP-over-WebSocket transport (Modbus/TCP via a WS gateway).
+ * - {@link requestSerialPort} — Requests a Web Serial port handle (user-gesture gated).
+ *
  * ## Server layers
  *
  * Run a server layer with {@link Layer.launch} and execute with a runtime:
@@ -23,6 +31,8 @@
  * - {@link serialAsciiServerLayer} — Serial ASCII server.
  * - {@link tcpServerLayer} — TCP server.
  * - {@link tcpGatewayLayer} — TCP gateway.
+ * - {@link wasmWsServerLayer} — Browser WS-gateway server (experimental upstream surface).
+ * - {@link wasmSerialRtuServerLayer} / {@link wasmSerialAsciiServerLayer} — Browser Web Serial servers (experimental).
  *
  * ## Errors
  *
@@ -36,14 +46,24 @@
  * })
  * ```
  *
- * @module effect-modbus-rs
+ * @module @flux-control/effect-modbus-rs
  */
-export * from "./src/errors";
-export { AsciiTransportService } from "./src/AsciiTransportService";
-export { SerialTransportService } from "./src/SerialTransportService";
-export { TcpTransportService } from "./src/TcpTransportService";
-export { RtuTransportService } from "./src/RtuTransportService";
-export { serialRtuServerLayer, serialAsciiServerLayer } from "./src/SerialModbusServerService";
-export { tcpServerLayer } from "./src/TcpModbusServerService";
-export { tcpGatewayLayer } from "./src/TcpGatewayService";
-export type { CoilDefinition, DiscreteInputDefinition, RegisterDefinition, SlaveDeviceDefinition, SlaveDeviceDefinitions, } from "./src/mocks";
+export * from './src/errors';
+export type { EffectModbusClient } from './src/modbus-client';
+export { AsciiTransportService } from './src/AsciiTransportService';
+export { SerialTransportService } from './src/SerialTransportService';
+export { TcpTransportService } from './src/TcpTransportService';
+export { RtuTransportService } from './src/RtuTransportService';
+export { serialRtuServerLayer, serialAsciiServerLayer } from './src/SerialModbusServerService';
+export { tcpServerLayer } from './src/TcpModbusServerService';
+export { tcpGatewayLayer } from './src/TcpGatewayService';
+export { WasmWsTransportService } from './src/WasmWsTransportService';
+export { WasmRtuTransportService } from './src/WasmRtuTransportService';
+export type { WasmRtuTransportOpenOptions } from './src/WasmRtuTransportService';
+export { WasmAsciiTransportService } from './src/WasmAsciiTransportService';
+export type { WasmAsciiTransportOpenOptions } from './src/WasmAsciiTransportService';
+export { WasmSerialTransportService } from './src/WasmSerialTransportService';
+export { requestSerialPort } from './src/WasmSerialPort';
+export { wasmWsServerLayer } from './src/WasmTcpServerService';
+export { wasmSerialRtuServerLayer, wasmSerialAsciiServerLayer, } from './src/WasmSerialModbusServerService';
+export type { CoilDefinition, DiscreteInputDefinition, RegisterDefinition, SlaveDeviceDefinition, SlaveDeviceDefinitions, } from './src/mocks';