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

package/README.md

@@ -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
 
@@ -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  |

package/dist/src/SerialTransportService.d.ts

@@ -1,6 +1,6 @@
 import { Context, Layer } from 'effect';
 import { type AsciiTransportOpenOptions } from './AsciiTransportService';
-import { type SlaveDeviceDefinitions } from './mocks';
+import { type MockFaultOptions, type SlaveDeviceDefinitions } from './mocks';
 import { type RtuTransportOpenOptions } from './RtuTransportService';
 import type { TransportResilienceOptions, TransportServiceApi } from './shared-transport';
 declare const SerialTransportService_base: Context.TagClass<SerialTransportService, "SerialTransportService", TransportServiceApi>;
@@ -35,12 +35,22 @@ export declare class SerialTransportService extends SerialTransportService_base
      */
     static fromRtu(options: RtuTransportOpenOptions & TransportResilienceOptions): Layer.Layer<SerialTransportService>;
     /**
-     * Creates a mock {@link Layer} providing {@link SerialTransportService}
-     * for testing or development.
+     * Creates a mock {@link Layer} that provides {@link SerialTransportService}
+     * for tests or development.
      *
-     * Accepts an array of {@link SlaveDeviceDefinition} describing the
-     * simulated Modbus slaves and their register/coil maps.
+     * The `devices` parameter is an array of {@link SlaveDeviceDefinition}. Each
+     * definition gives the coil map and the register map of one simulated slave.
+     *
+     * 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`,
+     * `fault`, and `reconnectFault`.
+     *
+     * @param devices - The slave device definitions for the mock.
+     * @returns A function that takes the mock options and gives a scoped
+     *          {@link Layer} that provides the mock service.
+     * @see MockFaultOptions — The `fault` hook and the `reconnectFault` hook.
+     * @see makeMockTransport — The mock factory that this method uses.
      */
-    static makeMockTransport: (devices: SlaveDeviceDefinitions) => (options: (AsciiTransportOpenOptions | RtuTransportOpenOptions) & TransportResilienceOptions) => Layer.Layer<SerialTransportService>;
+    static makeMockTransport: (devices: SlaveDeviceDefinitions) => (options: (AsciiTransportOpenOptions | RtuTransportOpenOptions) & TransportResilienceOptions & MockFaultOptions) => Layer.Layer<SerialTransportService>;
 }
 export {};

package/dist/src/WasmSerialTransportService.d.ts

@@ -1,6 +1,6 @@
 import { Context, Layer } from 'effect';
-import { type SlaveDeviceDefinitions } from './mocks';
-import type { TransportServiceApi } from './shared-transport';
+import { type MockFaultOptions, type SlaveDeviceDefinitions } from './mocks';
+import type { TransportResilienceOptions, TransportServiceApi } from './shared-transport';
 import { type WasmAsciiTransportOpenOptions } from './WasmAsciiTransportService';
 import { type WasmRtuTransportOpenOptions } from './WasmRtuTransportService';
 declare const WasmSerialTransportService_base: Context.TagClass<WasmSerialTransportService, "WasmSerialTransportService", TransportServiceApi>;
@@ -30,19 +30,29 @@ export declare class WasmSerialTransportService extends WasmSerialTransportServi
      * Creates a {@link Layer} providing {@link WasmSerialTransportService}
      * backed by an ASCII transport.
      */
-    static fromAscii(options: WasmAsciiTransportOpenOptions): Layer.Layer<WasmSerialTransportService>;
+    static fromAscii(options: WasmAsciiTransportOpenOptions & TransportResilienceOptions): Layer.Layer<WasmSerialTransportService>;
     /**
      * Creates a {@link Layer} providing {@link WasmSerialTransportService}
      * backed by an RTU transport.
      */
-    static fromRtu(options: WasmRtuTransportOpenOptions): Layer.Layer<WasmSerialTransportService>;
+    static fromRtu(options: WasmRtuTransportOpenOptions & TransportResilienceOptions): Layer.Layer<WasmSerialTransportService>;
     /**
-     * Creates a mock {@link Layer} providing {@link WasmSerialTransportService}
-     * for testing or development.
+     * Creates a mock {@link Layer} that provides {@link WasmSerialTransportService}
+     * for tests or development.
      *
-     * Accepts an array of {@link SlaveDeviceDefinition} describing the
-     * simulated Modbus slaves and their register/coil maps.
+     * The `devices` parameter is an array of {@link SlaveDeviceDefinition}. Each
+     * definition gives the coil map and the register map of one simulated slave.
+     *
+     * 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`,
+     * `fault`, and `reconnectFault`.
+     *
+     * @param devices - The slave device definitions for the mock.
+     * @returns A function that takes the mock options and gives a scoped
+     *          {@link Layer} that provides the mock service.
+     * @see MockFaultOptions — The `fault` hook and the `reconnectFault` hook.
+     * @see makeMockTransport — The mock factory that this method uses.
      */
-    static makeMockTransport: (devices: SlaveDeviceDefinitions) => (options: WasmAsciiTransportOpenOptions | WasmRtuTransportOpenOptions) => Layer.Layer<WasmSerialTransportService>;
+    static makeMockTransport: (devices: SlaveDeviceDefinitions) => (options: (WasmAsciiTransportOpenOptions | WasmRtuTransportOpenOptions) & TransportResilienceOptions & MockFaultOptions) => Layer.Layer<WasmSerialTransportService>;
 }
 export {};

package/dist/src/mock-options.test.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flux-control/effect-modbus-rs",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Type-safe Modbus communication via Effect-TS, wrapping the modbus-rs npm bindings.",
   "license": "GPL-3.0",
   "repository": {