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

package/dist/src/WasmWsTransportService.d.ts

@@ -0,0 +1,60 @@
+import { Effect, Layer } from 'effect';
+import type { WasmWsTransportOptions } from 'modbus-rs/web';
+import { SlaveDeviceDefinitions } from './mocks';
+import type { MockFaultOptions } from './mocks';
+import type { TransportResilienceOptions } from './shared-transport';
+declare const WasmWsTransportService_base: Effect.Service.Class<WasmWsTransportService, "WasmWsTransportService", {
+    readonly scoped: (options: WasmWsTransportOptions & TransportResilienceOptions) => Effect.Effect<{
+        connectionState: import("effect/SubscriptionRef").SubscriptionRef<{
+            readonly _tag: "Connected";
+        } | {
+            readonly _tag: "Disconnected";
+        } | {
+            readonly _tag: "Down";
+            readonly cause: import("./errors").ModbusError;
+        } | {
+            readonly _tag: "Reconnecting";
+            readonly attempt: number;
+        }>;
+        withClient: (unitId: number, clientOptions?: {
+            readonly retry?: import("./retry").ModbusRetryPolicy;
+        } | undefined) => Effect.Effect<import("./modbus-client").EffectModbusClient, import("./errors").ModbusError, never>;
+        setRequestTimeout: (timeoutMs: number) => Effect.Effect<undefined, import("./errors").ModbusNotConnectedError, never>;
+        clearRequestTimeout: () => Effect.Effect<undefined, import("./errors").ModbusNotConnectedError, never>;
+        reconnect: () => Effect.Effect<undefined, import("./errors").ModbusError, never>;
+        close: () => Effect.Effect<void, import("./errors").ModbusError, import("effect/Scope").Scope>;
+        hasPendingRequests: () => boolean;
+    }, never, import("effect/Scope").Scope>;
+}>;
+/**
+ * Scoped Effect service wrapping `modbus-rs`'s browser {@link WasmWsTransport}
+ * for Modbus TCP over a WebSocket gateway (browsers can't open raw TCP sockets).
+ *
+ * The transport connection is opened lazily on the first call to
+ * `withClient(unitId)` and automatically closed when the consuming
+ * {@link Effect.Scope | Scope} finalizes.
+ *
+ * Clients are created per `unitId` via {@link WasmWsTransport.createClient} and
+ * cached, so repeated requests for the same unit ID reuse the same client.
+ *
+ * @see WasmWsTransport — Upstream `modbus-rs` browser WebSocket transport.
+ * @see WasmWsTransportOptions — Configuration for the WebSocket gateway connection.
+ * @see makeTransportScoped — Generic lifecycle logic from shared-transport.
+ */
+export declare class WasmWsTransportService extends WasmWsTransportService_base {
+    /**
+     * Creates a {@link Layer} providing an in-memory mock
+     * {@link WasmWsTransportService} for testing or development.
+     *
+     * Accepts an array of {@link SlaveDeviceDefinition} describing the
+     * simulated Modbus slaves and their register/coil maps.
+     *
+     * @param devices - Slave device definitions for the mock.
+     * @returns A function that takes {@link WasmWsTransportOptions} and
+     *          returns a scoped {@link Layer} providing the mock service.
+     *
+     * @see makeMockTransport — The underlying mock factory.
+     */
+    static makeMockTransport: (devices: SlaveDeviceDefinitions) => (options: WasmWsTransportOptions & TransportResilienceOptions & MockFaultOptions) => Layer.Layer<WasmWsTransportService, never, never>;
+}
+export {};

package/dist/src/connection.d.ts

@@ -0,0 +1,170 @@
+import { Data, Duration, Effect, SubscriptionRef } from 'effect';
+import { ModbusCircuitOpenError, type ModbusError } from './errors';
+import { type ModbusErrorTag, type ModbusRetryPolicy } from './retry';
+/**
+ * Live connection state of a transport.
+ *
+ * Owned by the transport and published through
+ * {@link TransportServiceApi.connectionState}, so an application can show link
+ * status without inferring it from failed reads.
+ *
+ * - `Disconnected` — never opened, or closed. Operations open it lazily.
+ * - `Connected` — usable.
+ * - `Reconnecting` — the supervisor is re-establishing the link. Operations are
+ *   refused with {@link ModbusCircuitOpenError} rather than queued on a dead bus.
+ * - `Down` — reconnect attempts were exhausted; the supervisor is waiting out
+ *   `resetAfter` before probing again. Operations are refused.
+ */
+export type ConnectionState = Data.TaggedEnum<{
+    Disconnected: object;
+    Connected: object;
+    Reconnecting: {
+        readonly attempt: number;
+    };
+    Down: {
+        readonly cause: ModbusError;
+    };
+}>;
+/** Constructors and matchers for {@link ConnectionState}. */
+export declare const ConnectionState: {
+    readonly $is: <Tag extends "Connected" | "Disconnected" | "Down" | "Reconnecting">(tag: Tag) => (u: unknown) => u is Extract<{
+        readonly _tag: "Connected";
+    }, {
+        readonly _tag: Tag;
+    }> | Extract<{
+        readonly _tag: "Disconnected";
+    }, {
+        readonly _tag: Tag;
+    }> | Extract<{
+        readonly _tag: "Down";
+        readonly cause: ModbusError;
+    }, {
+        readonly _tag: Tag;
+    }> | Extract<{
+        readonly _tag: "Reconnecting";
+        readonly attempt: number;
+    }, {
+        readonly _tag: Tag;
+    }>;
+    readonly $match: {
+        <const Cases extends { readonly [Tag in "Connected" | "Disconnected" | "Down" | "Reconnecting"]: (args: Extract<{
+            readonly _tag: "Connected";
+        } | {
+            readonly _tag: "Disconnected";
+        } | {
+            readonly _tag: "Down";
+            readonly cause: ModbusError;
+        } | {
+            readonly _tag: "Reconnecting";
+            readonly attempt: number;
+        }, {
+            readonly _tag: Tag;
+        }>) => any; }>(cases: Cases & { [K in Exclude<keyof Cases, "Connected" | "Disconnected" | "Down" | "Reconnecting">]: never; }): (value: {
+            readonly _tag: "Connected";
+        } | {
+            readonly _tag: "Disconnected";
+        } | {
+            readonly _tag: "Down";
+            readonly cause: ModbusError;
+        } | {
+            readonly _tag: "Reconnecting";
+            readonly attempt: number;
+        }) => import("effect/Unify").Unify<ReturnType<Cases["Connected" | "Disconnected" | "Down" | "Reconnecting"]>>;
+        <const Cases extends { readonly [Tag in "Connected" | "Disconnected" | "Down" | "Reconnecting"]: (args: Extract<{
+            readonly _tag: "Connected";
+        } | {
+            readonly _tag: "Disconnected";
+        } | {
+            readonly _tag: "Down";
+            readonly cause: ModbusError;
+        } | {
+            readonly _tag: "Reconnecting";
+            readonly attempt: number;
+        }, {
+            readonly _tag: Tag;
+        }>) => any; }>(value: {
+            readonly _tag: "Connected";
+        } | {
+            readonly _tag: "Disconnected";
+        } | {
+            readonly _tag: "Down";
+            readonly cause: ModbusError;
+        } | {
+            readonly _tag: "Reconnecting";
+            readonly attempt: number;
+        }, cases: Cases & { [K in Exclude<keyof Cases, "Connected" | "Disconnected" | "Down" | "Reconnecting">]: never; }): import("effect/Unify").Unify<ReturnType<Cases["Connected" | "Disconnected" | "Down" | "Reconnecting"]>>;
+    };
+    readonly Connected: Data.Case.Constructor<{
+        readonly _tag: "Connected";
+    }, "_tag">;
+    readonly Disconnected: Data.Case.Constructor<{
+        readonly _tag: "Disconnected";
+    }, "_tag">;
+    readonly Down: Data.Case.Constructor<{
+        readonly _tag: "Down";
+        readonly cause: ModbusError;
+    }, "_tag">;
+    readonly Reconnecting: Data.Case.Constructor<{
+        readonly _tag: "Reconnecting";
+        readonly attempt: number;
+    }, "_tag">;
+};
+/**
+ * Transport-level reconnection and circuit-breaking configuration.
+ *
+ * Supplying this on a transport hands reconnection to a supervisor fiber owned
+ * by that transport: one reconnect for the whole application rather than one
+ * per failing call site. Omit it and the transport keeps its manual behaviour —
+ * `reconnect()` still works, nothing happens on its own.
+ */
+export interface ReconnectOptions {
+    /**
+     * How reconnect attempts are spaced. Defaults to 5 attempts, `250 millis`
+     * base, factor 2, `10 seconds` ceiling, jittered.
+     */
+    readonly policy?: ModbusRetryPolicy;
+    /**
+     * How long the circuit stays open after attempts are exhausted, before the
+     * supervisor probes again. Default `30 seconds`.
+     */
+    readonly resetAfter?: Duration.DurationInput;
+    /**
+     * Which operation failures hand control to the supervisor.
+     * Default `["ModbusConnectionClosedError", "ModbusTransportError"]`.
+     */
+    readonly triggerOn?: ReadonlyArray<ModbusErrorTag>;
+}
+/** {@link ReconnectOptions} with defaults applied. */
+export interface ResolvedReconnect {
+    readonly policy: ModbusRetryPolicy;
+    readonly resetAfter: Duration.Duration;
+    readonly triggers: (error: ModbusError) => boolean;
+}
+/** Applies defaults to {@link ReconnectOptions}. */
+export declare const resolveReconnect: (options: ReconnectOptions) => ResolvedReconnect;
+/**
+ * Refuses an operation while the link is being re-established.
+ *
+ * `Disconnected` is allowed through so the first call still opens the
+ * transport lazily; only `Reconnecting` and `Down` are refused.
+ *
+ * @param state - The transport's connection state.
+ * @returns An Effect failing with {@link ModbusCircuitOpenError} when the
+ *   circuit is open, and succeeding otherwise.
+ */
+export declare const guardCircuit: (state: SubscriptionRef.SubscriptionRef<ConnectionState>) => Effect.Effect<void, ModbusCircuitOpenError>;
+/**
+ * The supervisor loop: re-establishes the link, then keeps probing for as long
+ * as the transport lives.
+ *
+ * Each round runs `reconnect` under the configured policy. Success publishes
+ * `Connected` and ends the loop; exhausting the policy publishes `Down` and
+ * waits out `resetAfter` before the next round, so an unplugged device is
+ * retried at a steady cadence instead of being hammered or given up on.
+ *
+ * @param reconnect - The transport's own reconnect operation.
+ * @param state - The state cell to publish transitions to.
+ * @param resolved - Reconnect configuration with defaults applied.
+ * @returns An Effect that runs until the link is restored.
+ */
+export declare const superviseReconnect: (reconnect: Effect.Effect<void, ModbusError>, state: SubscriptionRef.SubscriptionRef<ConnectionState>, resolved: ResolvedReconnect) => Effect.Effect<void>;

package/dist/src/errors.d.ts

@@ -135,6 +135,30 @@ export declare class ModbusNotConnectedError extends ModbusNotConnectedError_bas
     readonly message: string;
 }> {
 }
+declare const ModbusCircuitOpenError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "ModbusCircuitOpenError";
+} & Readonly<A>;
+/**
+ * Error indicating the transport's circuit breaker is open: the device is
+ * unreachable and the transport is reconnecting (or waiting to probe again),
+ * so the request was refused without touching the wire.
+ *
+ * This is a **local** error — it is never returned by `modbus-rs`. It is raised
+ * by the transport when its connection state is `Reconnecting` or `Down`,
+ * which keeps a dead device from being hammered by every caller at once.
+ *
+ * Retryable by default: a policy with enough budget rides out the outage
+ * cheaply, since each refused attempt costs nothing on the bus.
+ *
+ * @see ConnectionState — The transport state that produces this error.
+ */
+export declare class ModbusCircuitOpenError extends ModbusCircuitOpenError_base<{
+    /** The failure that opened the circuit, or a descriptive error. */
+    readonly cause: Error;
+    /** Human-readable explanation of the error. */
+    readonly message: string;
+}> {
+}
 /**
  * Union of all typed Modbus errors emitted by this library.
  *
@@ -152,7 +176,7 @@ export declare class ModbusNotConnectedError extends ModbusNotConnectedError_bas
  *
  * @see ModbusErrorCode — The upstream error code enum driving this mapping.
  */
-export type ModbusError = ModbusExceptionError | ModbusTimeoutError | ModbusTransportError | ModbusInvalidArgumentError | ModbusConnectionClosedError | ModbusNotConnectedError | ModbusInternalError;
+export type ModbusError = ModbusExceptionError | ModbusTimeoutError | ModbusTransportError | ModbusInvalidArgumentError | ModbusConnectionClosedError | ModbusNotConnectedError | ModbusCircuitOpenError | ModbusInternalError;
 /**
  * Converts a raw `Error` from `modbus-rs` into a typed {@link ModbusError}.
  *

package/dist/src/mocks.d.ts

@@ -1,7 +1,34 @@
-import { Effect, Schema } from "effect";
-import type { AsciiTransportOptions, RtuTransportOptions, TcpTransportOptions } from "modbus-rs";
-import { ModbusInvalidArgumentError, type ModbusError } from "./errors";
-import type { EffectModbusClient } from "./modbus-client";
+import { Effect, Schema, SubscriptionRef } from 'effect';
+import { type AsciiTransportOptions, type RtuTransportOptions, type TcpTransportOptions } from 'modbus-rs';
+import type { WasmWsTransportOptions, WasmSerialTransportOptions } from 'modbus-rs/web';
+import { ModbusInvalidArgumentError, type ModbusError } from './errors';
+import type { ModbusRetryPolicy } from './retry';
+import type { TransportResilienceOptions, WithoutUpstreamRetry } from './shared-transport';
+/**
+ * Mock-only fault injection.
+ *
+ * Lets a test or example drive retry policies, backoff, and circuit-breaker
+ * behaviour end to end without hardware: the hook runs before each operation
+ * *attempt*, so returning an error is indistinguishable from a device that
+ * refused that attempt.
+ */
+export interface MockFaultOptions {
+    /**
+     * Called before every operation attempt. Return an error to fail that
+     * attempt, or `undefined` to let it through.
+     *
+     * ```ts
+     * let remaining = 2;
+     * const fault = () => (remaining-- > 0 ? new ModbusTimeoutError({ ... }) : undefined);
+     * ```
+     */
+    readonly fault?: () => ModbusError | undefined;
+    /**
+     * Called before every mock reconnect attempt. Return an error to keep the
+     * link down, or `undefined` to let the reconnect succeed.
+     */
+    readonly reconnectFault?: () => ModbusError | undefined;
+}
 /**
  * Schema for a single coil (digital output) definition.
  *
@@ -114,8 +141,8 @@ export type SlaveDeviceDefinitions = Schema.Schema.Type<typeof SlaveDeviceDefini
  * Accepts an array of {@link SlaveDeviceDefinition} that describe the
  * simulated Modbus slaves, their register maps, and coil states.
  * The returned factory matches the signature expected by the transport
- * service constructors (`RtuTransportOptions | AsciiTransportOptions |
- * TcpTransportOptions`) so it can be injected into any service layer.
+ * service constructors (`RtuTransportOpenOptions | AsciiTransportOpenOptions |
+ * TcpTransportOpenOptions`) so it can be injected into any service layer.
  *
  * Unsupported function codes (FIFO queue, file records) return
  * {@link ModbusInvalidArgumentError}.
@@ -124,11 +151,24 @@ export type SlaveDeviceDefinitions = Schema.Schema.Type<typeof SlaveDeviceDefini
  * @returns A transport factory function that returns a scoped Effect
  *          providing the mock transport.
  */
-export declare const makeMockTransport: (devices: SlaveDeviceDefinitions) => (_options: RtuTransportOptions | AsciiTransportOptions | TcpTransportOptions) => Effect.Effect<{
-    withClient: (unitId: number) => Effect.Effect<EffectModbusClient, ModbusInvalidArgumentError, never>;
+export declare const makeMockTransport: (devices: SlaveDeviceDefinitions) => (options: (WithoutUpstreamRetry<RtuTransportOptions> | WithoutUpstreamRetry<AsciiTransportOptions> | WithoutUpstreamRetry<TcpTransportOptions> | WasmWsTransportOptions | WasmSerialTransportOptions) & TransportResilienceOptions & MockFaultOptions) => Effect.Effect<{
+    connectionState: SubscriptionRef.SubscriptionRef<{
+        readonly _tag: "Connected";
+    } | {
+        readonly _tag: "Disconnected";
+    } | {
+        readonly _tag: "Down";
+        readonly cause: ModbusError;
+    } | {
+        readonly _tag: "Reconnecting";
+        readonly attempt: number;
+    }>;
+    withClient: (unitId: number, clientOptions?: {
+        readonly retry?: ModbusRetryPolicy;
+    } | undefined) => Effect.Effect<import("./modbus-client").EffectModbusClient, ModbusInvalidArgumentError, never>;
     setRequestTimeout: (_timeoutMs: number) => Effect.Effect<void, never, never>;
     clearRequestTimeout: () => Effect.Effect<void, never, never>;
     reconnect: () => Effect.Effect<void, ModbusError, never>;
     close: () => Effect.Effect<void, ModbusError, never>;
     hasPendingRequests: () => false;
-}, never, never>;
+}, never, import("effect/Scope").Scope>;

package/dist/src/modbus-client.d.ts

@@ -1,13 +1,20 @@
-import type { ReadRegistersOptions, WriteSingleRegisterOptions, WriteMultipleRegistersOptions, ReadWriteMultipleRegistersOptions, ReadBitsOptions, WriteSingleCoilOptions, WriteMultipleCoilsOptions, ReadFifoQueueOptions, ReadFileRecordOptions, WriteFileRecordOptions, DiagnosticsOptions, ReadDeviceIdentificationOptions, FifoQueueResponse, DiagnosticsResponse, DeviceIdentificationResponse, AsyncSerialModbusClient, AsyncTcpModbusClient } from "modbus-rs";
-import { Effect } from "effect";
-import type { ModbusError } from "./errors";
-export type AnyModbusClient = AsyncSerialModbusClient | AsyncTcpModbusClient;
+import { Effect } from 'effect';
+import type { ReadRegistersOptions, WriteSingleRegisterOptions, WriteMultipleRegistersOptions, ReadWriteMultipleRegistersOptions, ReadBitsOptions, WriteSingleCoilOptions, WriteMultipleCoilsOptions, ReadFifoQueueOptions, ReadFileRecordOptions, WriteFileRecordOptions, DiagnosticsOptions, ReadDeviceIdentificationOptions, FifoQueueResponse, DiagnosticsResponse, DeviceIdentificationResponse, AsyncSerialModbusClient, AsyncTcpModbusClient, CoilState } from 'modbus-rs';
+import type { WasmWsModbusClient, WasmSerialModbusClient } from 'modbus-rs/web';
+import type { ModbusError } from './errors';
+import { type ModbusRetryPolicy } from './retry';
+/** The two native (napi) clients — same method surface, sharing one factory. */
+export type NativeModbusClient = AsyncSerialModbusClient | AsyncTcpModbusClient;
+/** The two browser (WASM) clients — same method surface, sharing one factory. */
+export type WasmModbusClient = WasmSerialModbusClient | WasmWsModbusClient;
+/** Any client this package knows how to wrap into an {@link EffectModbusClient}. */
+export type AnyModbusClient = NativeModbusClient | WasmModbusClient;
 /**
- * Effect-ified Modbus client wrapping a `modbus-rs` transport client.
+ * The Modbus function-code surface, before any resilience is layered on.
  *
- * Each method delegates to the equivalent `AsyncSerialModbusClient` or
- * `AsyncTcpModbusClient` method, converting the Promise-based API into
- * an {@link Effect.Effect} with typed {@link ModbusError} failures.
+ * Each method delegates to the equivalent method on the underlying native
+ * or WASM client, converting the Promise-based API into an
+ * {@link Effect.Effect} with typed {@link ModbusError} failures.
  *
  * Thrown errors are classified using {@link toModbusError}, mapping
  * `modbus-rs` error codes (timeout, transport, exception, etc.) into
@@ -17,7 +24,7 @@ export type AnyModbusClient = AsyncSerialModbusClient | AsyncTcpModbusClient;
  * @see AsyncSerialModbusClient — Upstream `modbus-rs` serial client API.
  * @see AsyncTcpModbusClient — Upstream `modbus-rs` TCP client API.
  */
-export interface EffectModbusClient {
+export interface ModbusOperations {
     /**
      * Reads holding registers from the Modbus device (FC03).
      *
@@ -27,7 +34,7 @@ export interface EffectModbusClient {
      * @see ReadRegistersOptions — Options shape from `modbus-rs`.
      * @see AsyncSerialModbusClient.readHoldingRegisters — Upstream implementation.
      */
-    readHoldingRegisters(opts: ReadRegistersOptions): Effect.Effect<number[], ModbusError>;
+    readHoldingRegisters(opts: ReadRegistersOptions): Effect.Effect<Uint16Array, ModbusError>;
     /**
      * Reads input registers from the Modbus device (FC04).
      *
@@ -37,7 +44,7 @@ export interface EffectModbusClient {
      * @see ReadRegistersOptions — Options shape from `modbus-rs`.
      * @see AsyncSerialModbusClient.readInputRegisters — Upstream implementation.
      */
-    readInputRegisters(opts: ReadRegistersOptions): Effect.Effect<number[], ModbusError>;
+    readInputRegisters(opts: ReadRegistersOptions): Effect.Effect<Uint16Array, ModbusError>;
     /**
      * Writes a single holding register (FC06).
      *
@@ -67,7 +74,7 @@ export interface EffectModbusClient {
      *
      * @see ReadWriteMultipleRegistersOptions — Options shape from `modbus-rs`.
      */
-    readWriteMultipleRegisters(opts: ReadWriteMultipleRegistersOptions): Effect.Effect<number[], ModbusError>;
+    readWriteMultipleRegisters(opts: ReadWriteMultipleRegistersOptions): Effect.Effect<Uint16Array, ModbusError>;
     /**
      * Reads coils (digital outputs) from the Modbus device (FC01).
      *
@@ -76,7 +83,7 @@ export interface EffectModbusClient {
      *
      * @see ReadBitsOptions — Options shape from `modbus-rs`.
      */
-    readCoils(opts: ReadBitsOptions): Effect.Effect<boolean[], ModbusError>;
+    readCoils(opts: ReadBitsOptions): Effect.Effect<CoilState[], ModbusError>;
     /**
      * Writes a single coil (digital output) (FC05).
      *
@@ -103,7 +110,7 @@ export interface EffectModbusClient {
      *
      * @see ReadBitsOptions — Options shape from `modbus-rs`.
      */
-    readDiscreteInputs(opts: ReadBitsOptions): Effect.Effect<boolean[], ModbusError>;
+    readDiscreteInputs(opts: ReadBitsOptions): Effect.Effect<CoilState[], ModbusError>;
     /**
      * Reads the FIFO queue from the Modbus device (FC24).
      *
@@ -122,7 +129,7 @@ export interface EffectModbusClient {
      *
      * @see ReadFileRecordOptions — Options shape from `modbus-rs`.
      */
-    readFileRecord(opts: ReadFileRecordOptions): Effect.Effect<number[][], ModbusError>;
+    readFileRecord(opts: ReadFileRecordOptions): Effect.Effect<Uint16Array[], ModbusError>;
     /**
      * Writes file records to the Modbus device (FC21).
      *
@@ -162,21 +169,73 @@ export interface EffectModbusClient {
     readDeviceIdentification(opts: ReadDeviceIdentificationOptions): Effect.Effect<DeviceIdentificationResponse, ModbusError>;
 }
 /**
- * Wraps a raw `modbus-rs` client into an {@link EffectModbusClient}.
+ * Wraps a raw `modbus-rs` client — native (napi) or browser (WASM) — into an
+ * {@link EffectModbusClient}.
  *
  * Each method converts a Promise-based call from the upstream client
  * into an `Effect` via {@link Effect.tryPromise}, routing errors through
  * {@link toModbusError} for typed error discrimination.
  *
- * Accepts both serial (`AsyncSerialModbusClient`) and TCP
- * (`AsyncTcpModbusClient`) clients since they share the same method
- * signatures.
+ * The native and WASM clients share the same method surface (same options
+ * shapes, same resolved value shapes — `CoilState[]`, full `FifoQueueResponse`,
+ * full `DeviceIdentificationResponse`), so one factory covers both; no
+ * transport-specific reshaping is needed.
  *
- * @param client - The upstream `modbus-rs` client instance.
+ * @param client - The upstream `modbus-rs` or `modbus-rs/web` client instance.
  * @returns An `EffectModbusClient` that can be used within Effect
  *          workflows.
  *
- * @see AsyncSerialModbusClient — Upstream serial client API.
- * @see AsyncTcpModbusClient — Upstream TCP client API.
+ * @see AsyncSerialModbusClient — Upstream native serial client API.
+ * @see AsyncTcpModbusClient — Upstream native TCP client API.
  */
-export declare const makeEffectModbusClient: (client: AsyncSerialModbusClient | AsyncTcpModbusClient) => EffectModbusClient;
+export declare const makeEffectModbusClient: (client: AnyModbusClient) => ModbusOperations;
+/**
+ * Transport-owned resilience applied to every operation of a client.
+ *
+ * Assembled by the transport, not by call sites: the guard and the failure
+ * report both consult state that belongs to the transport, so a single
+ * reconnect serves every client derived from it.
+ */
+export interface ClientResilience {
+    /** Refuses the operation while the transport's circuit is open. */
+    readonly guard: Effect.Effect<void, ModbusError>;
+    /** Reports a failure so the transport can decide whether to reconnect. */
+    readonly report: (error: ModbusError) => Effect.Effect<void>;
+    /** Retry policy applied to each operation, if any. */
+    readonly policy?: ModbusRetryPolicy;
+}
+/**
+ * A Modbus client with the transport's resilience already applied.
+ *
+ * Obtained from `transport.withClient(unitId)`. Every operation is guarded by
+ * the transport's circuit breaker, reports connection failures to the
+ * transport's reconnect supervisor, and carries whatever retry policy the
+ * transport or the `withClient` call attached.
+ */
+export interface EffectModbusClient extends ModbusOperations {
+    /**
+     * Returns an equivalent client whose operations use `policy` **instead of**
+     * the one this client carries.
+     *
+     * Replaces rather than composes, so an override cannot accidentally multiply
+     * attempt counts. `RetryPolicies.none()` opts a call site out entirely.
+     *
+     * ```ts
+     * yield* client.withRetry(RetryPolicies.none()).writeSingleCoil({ address: 0, value })
+     * ```
+     */
+    withRetry(policy: ModbusRetryPolicy): EffectModbusClient;
+}
+/**
+ * Layers transport-owned resilience over a raw {@link ModbusOperations}.
+ *
+ * Each operation runs as: circuit guard → operation → failure report, with the
+ * retry policy (if any) wrapped around the whole sequence. Ordering matters —
+ * the guard runs per *attempt*, so once the breaker opens, a retrying operation
+ * costs nothing on the wire while it waits for the link to come back.
+ *
+ * @param operations - The unwrapped function-code surface.
+ * @param resilience - Guard, failure report, and optional retry policy.
+ * @returns A client with resilience applied to every operation.
+ */
+export declare const withResilience: (operations: ModbusOperations, resilience: ClientResilience) => EffectModbusClient;

package/dist/src/modbus-client.wasm.test.d.ts

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

package/dist/src/resilience.test.d.ts

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