@flux-control/effect-modbus-rs 0.3.0 → 0.4.0

package/README.md

@@ -4,7 +4,7 @@
 
 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.
+Provides scoped [`Context.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.
 
@@ -44,7 +44,7 @@ program.pipe(
     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.make({ portPath: '/dev/ttyUSB0', baudRate: 9600 })),
   Effect.scoped,
   Effect.runPromise,
 );
@@ -64,7 +64,7 @@ const program = Effect.gen(function* () {
 });
 
 program.pipe(
-  Effect.provide(TcpTransportService.Default({ host: '192.168.1.100', port: 502 })),
+  Effect.provide(TcpTransportService.make({ host: '192.168.1.100', port: 502 })),
   Effect.scoped,
   Effect.runPromise,
 );
@@ -87,7 +87,7 @@ const program = Effect.gen(function* () {
 });
 
 program.pipe(
-  Effect.provide(AsciiTransportService.Default({ portPath: '/dev/ttyUSB0', baudRate: 9600 })),
+  Effect.provide(AsciiTransportService.make({ portPath: '/dev/ttyUSB0', baudRate: 9600 })),
   Effect.scoped,
   Effect.runPromise,
 );
@@ -112,7 +112,7 @@ const program = Effect.gen(function* () {
 });
 
 program.pipe(
-  Effect.provide(WasmWsTransportService.Default({ wsUrl: 'ws://localhost:8080' })),
+  Effect.provide(WasmWsTransportService.make({ wsUrl: 'ws://localhost:8080' })),
   Effect.scoped,
   Effect.runPromise,
 );
@@ -129,7 +129,7 @@ connectButton.addEventListener('click', () => {
     Effect.gen(function* () {
       const port = yield* requestSerialPort();
       yield* program.pipe(
-        Effect.provide(WasmRtuTransportService.Default({ port, baudRate: 19200 })),
+        Effect.provide(WasmRtuTransportService.make({ port, baudRate: 19200 })),
         Effect.scoped,
       );
     }),
@@ -150,7 +150,7 @@ Not demonstrated in `examples/wasm/` (see that app's README) — the same `impor
 
 ## 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.
+Each transport is a scoped `Context.Service`. You provide it with `Effect.provide`, and the connection is opened on service access and closed when the scope ends.
 
 | Service                               | Options                        | Connection                    |
 | ------------------------------------- | ------------------------------ | ----------------------------- |
@@ -193,7 +193,32 @@ program.pipe(
 // );
 ```
 
-It also supports `makeMockTransport` for testing:
+`WasmSerialTransportService` is the browser equivalent. Provide it with `fromRtu` or `fromAscii`, and give it a port handle from `requestSerialPort`.
+
+Both abstract tags also have `makeMockTransport` for tests. The option set is the same as the option set of the concrete tags. Thus a test that keeps the framing abstract can also set `retry`, `reconnect`, and the mock fault hooks:
+
+```ts
+import {
+  ModbusTimeoutError,
+  RetryPolicies,
+  SerialTransportService,
+} from '@flux-control/effect-modbus-rs';
+
+let attempts = 0;
+
+const layer = SerialTransportService.makeMockTransport([device])({
+  portPath: '/dev/ttyUSB0',
+  baudRate: 9600,
+  retry: RetryPolicies.serial(),
+  // The first two attempts of each operation fail. The policy retries them.
+  fault: () =>
+    attempts++ < 2
+      ? new ModbusTimeoutError({ message: 'no response', cause: new Error('timeout') })
+      : undefined,
+});
+```
+
+See [Testing with mocks](#testing-with-mocks) for the `fault` hook and the `reconnectFault` hook.
 
 ## Client API
 
@@ -254,7 +279,7 @@ Handle with `Effect.catchTags`. The `ModbusError` union type covers all seven va
 Resilience belongs to the **transport**, not to call sites. Attach a policy where the transport is created and every client derived from it carries it:
 
 ```ts
-const layer = TcpTransportService.Default({
+const layer = TcpTransportService.make({
   host: '192.168.1.50',
   port: 502,
   retry: RetryPolicies.tcp(), // applied to every operation
@@ -368,7 +393,7 @@ So `RetryPolicies.tcp()` waits roughly 80–120 ms before its first retry, not e
 Passing `reconnect` hands reconnection to a supervisor fiber owned by the transport — **one reconnect for the whole application**, however many fibers were in flight when the link dropped:
 
 ```ts
-TcpTransportService.Default({
+TcpTransportService.make({
   host,
   port,
   reconnect: {
@@ -420,7 +445,7 @@ See `examples/retry-policies.ts` for a runnable walkthrough.
 `modbus-rs` exposes `retryAttempts`, `retryDelayMs`, and `retryBackoffStrategy` on its transport options. This package removes all three from every transport constructor, so setting one is a compile error rather than a documented hazard:
 
 ```ts
-TcpTransportService.Default({ host, port, retryAttempts: 3 });
+TcpTransportService.make({ host, port, retryAttempts: 3 });
 //                                        ^^^^^^^^^^^^^ Object literal may only specify
 //                                        known properties, and 'retryAttempts' does not
 //                                        exist in type 'TcpTransportOpenOptions & …'
@@ -475,10 +500,41 @@ const mockLayer = RtuTransportService.makeMockTransport([device])({
 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.
+The mock factory is the same for every transport. Each tag has a static `makeMockTransport` method, and each accepts the same options: the open options of that transport, the resilience options (`retry` and `reconnect`), and the two fault hooks below. To change transport, use a different tag and adjust the shape of the open options.
 
 See `examples/rtu-mock.ts`, `examples/tcp-mock.ts`, and `examples/ascii-mock.ts` for full walkthroughs covering read, write, multi-device access, and error-case testing.
 
+### Fault injection
+
+Two mock-only hooks make a policy testable without hardware:
+
+| Hook             | When it runs                   | Return value                                                                 |
+| ---------------- | ------------------------------ | ---------------------------------------------------------------------------- |
+| `fault`          | Before every operation attempt | A `ModbusError` fails that attempt. `undefined` lets it through.             |
+| `reconnectFault` | Before every reconnect attempt | A `ModbusError` keeps the link down. `undefined` lets the reconnect succeed. |
+
+Because `fault` runs before each _attempt_, an error from it is the same as a device that refused that attempt. A retry policy, the backoff, and the circuit breaker therefore behave as they do on a real bus:
+
+```ts
+import {
+  ModbusTimeoutError,
+  RetryPolicies,
+  RtuTransportService,
+} from '@flux-control/effect-modbus-rs';
+
+let attempts = 0;
+
+const mockLayer = RtuTransportService.makeMockTransport([device])({
+  portPath: '/dev/ttyUSB0',
+  baudRate: 9600,
+  retry: RetryPolicies.serial(),
+  fault: () =>
+    attempts++ < 2
+      ? new ModbusTimeoutError({ message: 'no response', cause: new Error('timeout') })
+      : undefined,
+});
+```
+
 ### Slave device schema
 
 | Property           | Type                     | Default  |
@@ -512,17 +568,17 @@ src/
   connection.ts              — Connection state machine, reconnect supervisor, circuit breaker
   retry.ts                   — Opt-in retry policies (backoff, jitter, per-error rules)
   shared-transport.ts        — Generic scoped transport lifecycle management, WithoutUpstreamRetry
-  RtuTransportService.ts     — Scoped Effect.Service wrapping AsyncRtuTransport
-  TcpTransportService.ts     — Scoped Effect.Service wrapping AsyncTcpTransport
-  AsciiTransportService.ts   — Scoped Effect.Service wrapping AsyncAsciiTransport
+  RtuTransportService.ts     — Scoped Context.Service wrapping AsyncRtuTransport
+  TcpTransportService.ts     — Scoped Context.Service wrapping AsyncTcpTransport
+  AsciiTransportService.ts   — Scoped Context.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)
+  WasmWsTransportService.ts  — Scoped Context.Service wrapping WasmWsTransport (browser, WS gateway)
+  WasmRtuTransportService.ts — Scoped Context.Service wrapping WasmRtuTransport (browser, Web Serial RTU)
+  WasmAsciiTransportService.ts — Scoped Context.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)

package/dist/index.d.ts

@@ -54,7 +54,7 @@
  * every client derived from it:
  *
  * ```ts
- * TcpTransportService.Default({
+ * TcpTransportService.make({
  *   host, port,
  *   retry: RetryPolicies.tcp(),      // applied to every operation
  *   reconnect: {},                   // supervised reconnect + circuit breaker