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

package/dist/src/mocks.d.ts

@@ -1,8 +1,34 @@
-import { Effect, Schema } from 'effect';
+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 { EffectModbusClient } from './modbus-client';
+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.
  *
@@ -115,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}.
@@ -125,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 | WasmWsTransportOptions | WasmSerialTransportOptions) => 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

@@ -2,6 +2,7 @@ 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. */
@@ -9,7 +10,7 @@ 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 method on the underlying native
  * or WASM client, converting the Promise-based API into an
@@ -23,7 +24,7 @@ export type AnyModbusClient = NativeModbusClient | WasmModbusClient;
  * @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).
      *
@@ -187,4 +188,54 @@ export interface EffectModbusClient {
  * @see AsyncSerialModbusClient — Upstream native serial client API.
  * @see AsyncTcpModbusClient — Upstream native TCP client API.
  */
-export declare const makeEffectModbusClient: (client: AnyModbusClient) => 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/resilience.test.d.ts

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

package/dist/src/retry.d.ts

@@ -0,0 +1,227 @@
+import { Duration, Effect, Schedule } from 'effect';
+import type { ModbusError } from './errors';
+/**
+ * The `_tag` of every {@link ModbusError} variant.
+ *
+ * Used to key per-error retry behaviour in
+ * {@link ModbusRetryPolicyOptions.errors}.
+ */
+export type ModbusErrorTag = ModbusError['_tag'];
+/**
+ * Backoff curve for a single error category.
+ *
+ * The delay before retry _n_ (zero-based) is
+ * `min(maxDelay, baseDelay * factor ** n)`, optionally jittered by the
+ * policy-level {@link ModbusRetryPolicyOptions.jitter | jitter} setting.
+ *
+ * @see Schedule.exponential — The equivalent built-in Effect schedule.
+ */
+export interface RetryDelayOptions {
+    /** Delay before the first retry. */
+    readonly baseDelay?: Duration.DurationInput;
+    /** Multiplier applied to the delay after each attempt. */
+    readonly factor?: number;
+    /** Upper bound on the delay, whatever the attempt count. */
+    readonly maxDelay?: Duration.DurationInput;
+}
+/**
+ * Per-error retry configuration.
+ *
+ * - `false` — never retry this error.
+ * - `true` — retry using the policy-level backoff curve.
+ * - {@link RetryDelayOptions} — retry using a curve specific to this error.
+ */
+export type RetryErrorOptions = boolean | RetryDelayOptions;
+/**
+ * Options accepted by {@link makeRetryPolicy} and by every preset in
+ * {@link RetryPolicies}.
+ *
+ * Nothing here is applied automatically — a policy only takes effect once it is
+ * attached to a transport, to a client, or piped over an effect with
+ * {@link retryModbus}. Library defaults stay single-shot so that timing is
+ * predictable unless retries are explicitly opted into.
+ *
+ * These are **application-level** retries, and the only ones in play: the
+ * transport-level knobs `modbus-rs` offers are withheld from every transport
+ * constructor in this package, so the two layers cannot be combined by
+ * accident. See `UpstreamRetryOptionKey` in `src/shared-transport.ts`.
+ */
+export interface ModbusRetryPolicyOptions {
+    /** Maximum number of retries (attempts = `maxRetries + 1`). Default `3`. */
+    readonly maxRetries?: number;
+    /** Wall-clock budget for the whole retry sequence. Unbounded by default. */
+    readonly maxElapsed?: Duration.DurationInput;
+    /**
+     * Randomness applied to each delay, as a multiplier range.
+     *
+     * `true` (default) uses Effect's `0.8 – 1.2` range; `false` disables jitter;
+     * an object customises the range. Jitter keeps a fleet of pollers from
+     * re-hitting a recovering device in lockstep.
+     *
+     * @see Schedule.jitteredWith — The underlying combinator.
+     */
+    readonly jitter?: boolean | {
+        readonly min?: number;
+        readonly max?: number;
+    };
+    /** Policy-level delay before the first retry. Default `100 millis`. */
+    readonly baseDelay?: Duration.DurationInput;
+    /** Policy-level backoff multiplier. Default `2`. */
+    readonly factor?: number;
+    /** Policy-level delay ceiling. Default `5 seconds`. */
+    readonly maxDelay?: Duration.DurationInput;
+    /**
+     * Which {@link ModbusError} variants are retryable, with optional
+     * per-error backoff overrides.
+     *
+     * Defaults retry the errors that a healthy bus recovers from on its own —
+     * {@link ModbusTimeoutError}, {@link ModbusTransportError},
+     * {@link ModbusConnectionClosedError}, and the transient exception codes in
+     * {@link retryableExceptionCodes} — and never retry
+     * {@link ModbusInvalidArgumentError}, {@link ModbusNotConnectedError}, or
+     * {@link ModbusInternalError}.
+     */
+    readonly errors?: Partial<Record<ModbusErrorTag, RetryErrorOptions>>;
+    /**
+     * Modbus exception codes worth retrying when the device answers with an
+     * exception response. Default {@link retryableExceptionCodes}.
+     *
+     * Only consulted when `ModbusExceptionError` is retryable at all.
+     */
+    readonly retryableExceptions?: ReadonlyArray<number>;
+}
+/**
+ * A resolved retry policy: a schedule plus the predicates that produced it.
+ *
+ * Produced by {@link makeRetryPolicy} or a {@link RetryPolicies} preset, and
+ * attached to a transport or client (or piped with {@link retryModbus}). The
+ * `schedule` is a plain Effect `Schedule`, so it can also be handed straight
+ * to `Effect.retry`, `Effect.repeat`, or `Stream.retry`.
+ */
+export interface ModbusRetryPolicy {
+    /**
+     * Schedule driving the retries. Its input is the failing {@link ModbusError},
+     * its output the `[retryIndex, error]` pair that produced the delay.
+     */
+    readonly schedule: Schedule.Schedule<[number, ModbusError], ModbusError>;
+    /** Whether this policy retries the given error at all. */
+    readonly isRetryable: (error: ModbusError) => boolean;
+}
+/**
+ * Modbus exception codes retried by default.
+ *
+ * These are the codes that mean "ask again later" rather than "your request is
+ * wrong": `5` ACKNOWLEDGE, `6` SERVER_DEVICE_BUSY,
+ * `10` GATEWAY_PATH_UNAVAILABLE, `11` GATEWAY_TARGET_DEVICE_FAILED_TO_RESPOND.
+ *
+ * Codes such as `1` ILLEGAL_FUNCTION, `2` ILLEGAL_DATA_ADDRESS, and
+ * `3` ILLEGAL_DATA_VALUE are deterministic — retrying them only adds bus
+ * traffic and latency.
+ */
+export declare const retryableExceptionCodes: ReadonlyArray<number>;
+/**
+ * Builds a {@link ModbusRetryPolicy} from {@link ModbusRetryPolicyOptions}.
+ *
+ * The resulting schedule is exponential, jittered, capped per error category,
+ * and bounded by `maxRetries` (and `maxElapsed`, when set). The retry budget is
+ * shared across error categories — only the delay curve is per-error — so an
+ * operation that fails with a mix of timeouts and transport errors still stops
+ * after `maxRetries` retries.
+ *
+ * @param options - Policy configuration. Defaults to a general-purpose policy:
+ *   3 retries, `100 millis` base, factor `2`, `5 seconds` ceiling, jittered.
+ * @returns A resolved policy for a transport, a client, or {@link retryModbus}.
+ *
+ * @example
+ * ```ts
+ * const policy = makeRetryPolicy({
+ *   maxRetries: 5,
+ *   baseDelay: "50 millis",
+ *   errors: { ModbusExceptionError: false },
+ * });
+ * ```
+ *
+ * @see RetryPolicies — Ready-made templates built on top of this factory.
+ */
+export declare const makeRetryPolicy: (options?: ModbusRetryPolicyOptions) => ModbusRetryPolicy;
+/**
+ * Retry templates for common deployments.
+ *
+ * Each entry is a factory taking optional overrides, so a template can be used
+ * as-is or as a starting point:
+ *
+ * ```ts
+ * RetryPolicies.serial();
+ * RetryPolicies.serial({ maxRetries: 6 });
+ * ```
+ *
+ * None of these are applied implicitly — pick one and pipe through
+ * {@link retryModbus}.
+ */
+export declare const RetryPolicies: {
+    /**
+     * No retries — the library default behaviour, stated explicitly.
+     *
+     * Useful as a base for opting individual call sites out of an
+     * application-wide policy.
+     */
+    readonly none: (overrides?: ModbusRetryPolicyOptions) => ModbusRetryPolicy;
+    /**
+     * Serial (RTU/ASCII) buses: short delays, tight ceiling.
+     *
+     * A framing or CRC error on RS-485 is usually a collision or a noise burst,
+     * so retrying quickly is the right move; timeouts back off a little further
+     * to let a slow device finish its turnaround. Reconnects are reserved for a
+     * genuinely closed port — reopening a USB serial adapter is expensive.
+     */
+    readonly serial: (overrides?: ModbusRetryPolicyOptions) => ModbusRetryPolicy;
+    /**
+     * Modbus/TCP: room for a TCP handshake to re-establish.
+     *
+     * A transport error over TCP generally means the socket is gone rather than
+     * a corrupted frame, so it reconnects alongside an explicit connection close.
+     */
+    readonly tcp: (overrides?: ModbusRetryPolicyOptions) => ModbusRetryPolicy;
+    /**
+     * Long-running background polling: keep trying, but stop hammering.
+     *
+     * Backs off to a 30-second ceiling and gives up after 5 minutes of failures
+     * so a permanently dead device surfaces as an error instead of silently
+     * retrying forever.
+     */
+    readonly persistent: (overrides?: ModbusRetryPolicyOptions) => ModbusRetryPolicy;
+};
+/**
+ * Applies a {@link ModbusRetryPolicy} to an effect.
+ *
+ * Errors the policy considers non-retryable fail through immediately, so an
+ * `ModbusInvalidArgumentError` still surfaces on the first attempt under a
+ * policy tuned for flaky wiring.
+ *
+ * **This wraps rather than replaces.** `withClient(unitId, { retry })` and
+ * `client.withRetry(policy)` are resolved inside the client, so they discard
+ * the policy already in force. `retryModbus` is piped *around* an effect the
+ * client has already wrapped in its own retry, and nothing in that path can see
+ * the inner policy — so over a policied client both run and the attempt counts
+ * multiply (a `maxRetries: 2` client under a `maxRetries: 3` pipe makes 3 × 4 =
+ * 12 attempts). Reach for it only over a {@link RetryPolicies.none} client, to
+ * drive a compound operation as a unit; for a single operation, prefer
+ * `client.withRetry(policy)`.
+ *
+ * @param policy - The policy to apply.
+ * @returns A combinator that can be piped over any effect failing with
+ *   {@link ModbusError}.
+ *
+ * @example
+ * ```ts
+ * // A read-modify-write retried as a unit — retrying either frame alone
+ * // would be wrong. The client carries no policy of its own.
+ * const client = yield* transport.withClient(1, { retry: RetryPolicies.none() });
+ *
+ * yield* Effect.gen(function* () {
+ *   const current = yield* client.readHoldingRegisters({ address: 0, quantity: 2 });
+ *   yield* client.writeMultipleRegisters({ address: 0, values: bump(current) });
+ * }).pipe(retryModbus(RetryPolicies.serial()));
+ * ```
+ */
+export declare const retryModbus: (policy: ModbusRetryPolicy) => <A, E extends ModbusError, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;

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

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

package/dist/src/shared-transport.d.ts

@@ -1,6 +1,63 @@
-import { Effect, Scope } from 'effect';
+import { Effect, Scope, SubscriptionRef } from 'effect';
+import { ConnectionState, type ReconnectOptions } from './connection';
 import { type ModbusError, ModbusNotConnectedError } from './errors';
 import { type AnyModbusClient, type EffectModbusClient } from './modbus-client';
+import type { ModbusRetryPolicy } from './retry';
+/**
+ * Resilience configuration accepted by every transport service alongside its
+ * `modbus-rs` options.
+ *
+ * Both are opt-in: with neither set, a transport behaves exactly as it always
+ * has — one attempt per operation, reconnection only when asked for.
+ */
+export interface TransportResilienceOptions {
+    /**
+     * Retry policy applied to every operation of every client from this
+     * transport. Overridable per client and per operation.
+     */
+    readonly retry?: ModbusRetryPolicy;
+    /**
+     * Hands reconnection to a supervisor fiber owned by this transport, and
+     * enables the circuit breaker that keeps callers off a dead bus.
+     */
+    readonly reconnect?: ReconnectOptions;
+}
+/**
+ * The `modbus-rs` transport-level retry knobs this package deliberately does
+ * not expose.
+ *
+ * They are withheld rather than merely discouraged because enabling them is
+ * never the right call under this design:
+ *
+ * - **They retry below the Effect boundary.** A failure they paper over never
+ *   reaches the policy, the circuit breaker, or the logs — the caller sees one
+ *   slow success instead of several failures and a recovery, and any
+ *   caller-side timeout is measuring inflated time.
+ * - **They reconnect.** Upstream re-establishes the link inline and replays
+ *   in-flight requests after it, which races the one supervisor fiber that is
+ *   supposed to own reconnection for the whole transport.
+ * - **They multiply.** Neither layer knows about the other, so attempt counts
+ *   compound and the two backoff curves interleave.
+ * - **`retryDelayMs` is flat and unjittered**, the collision pattern that
+ *   `RetryPolicies.serial()` exists to break up; `retryBackoffStrategy` is
+ *   documented upstream as inert, so setting it does nothing at all.
+ *
+ * Use the `retry` and `reconnect` options on {@link TransportResilienceOptions}
+ * instead. Callers who genuinely need frame-level resends can construct a raw
+ * `modbus-rs` client directly, where the trade-off is explicit.
+ */
+export type UpstreamRetryOptionKey = 'retryAttempts' | 'retryDelayMs' | 'retryBackoffStrategy';
+/**
+ * Upstream `modbus-rs` transport options with the retry knobs removed.
+ *
+ * Applied to every transport-creation entry point this package exposes. All
+ * three keys are optional upstream, so the result stays assignable to the
+ * original type and still satisfies the upstream `open`/`connect` call.
+ *
+ * @typeParam TOptions - The upstream options type (e.g. `RtuTransportOptions`).
+ * @see UpstreamRetryOptionKey — Why these are withheld.
+ */
+export type WithoutUpstreamRetry<TOptions> = Omit<TOptions, UpstreamRetryOptionKey>;
 /**
  * Shared API surface that every transport service exposes to consumers.
  *
@@ -10,13 +67,44 @@ import { type AnyModbusClient, type EffectModbusClient } from './modbus-client';
  * @see makeTransportScoped — Factory that produces this API from a raw transport.
  */
 export interface TransportServiceApi {
-    /** Obtains (or creates) a cached {@link EffectModbusClient} for the given unit ID. */
-    withClient(unitId: number): Effect.Effect<EffectModbusClient, ModbusError>;
+    /**
+     * Obtains an {@link EffectModbusClient} for the given unit ID.
+     *
+     * The client carries the transport's retry policy unless `options.retry`
+     * replaces it — useful when one bus hosts device types that need different
+     * logic. The underlying `modbus-rs` client is cached per unit ID, so clients
+     * built with different policies still share one connection.
+     *
+     * @param unitId - Modbus unit ID to address.
+     * @param options - Per-client policy replacing the transport default.
+     */
+    withClient(unitId: number, options?: {
+        readonly retry?: ModbusRetryPolicy;
+    }): Effect.Effect<EffectModbusClient, ModbusError>;
+    /**
+     * Live connection state, published by the transport.
+     *
+     * Read it with `SubscriptionRef.get`, or subscribe with `.changes` to drive
+     * a status indicator:
+     *
+     * ```ts
+     * yield* Stream.runForEach(transport.connectionState.changes, (state) =>
+     *   Console.log(`link: ${state._tag}`))
+     * ```
+     */
+    readonly connectionState: SubscriptionRef.SubscriptionRef<ConnectionState>;
     /** Sets a request timeout (ms) on the underlying transport. Fails if not connected. */
     setRequestTimeout(timeoutMs: number): Effect.Effect<void, ModbusError>;
     /** Clears the request timeout. Fails if not connected. */
     clearRequestTimeout(): Effect.Effect<void, ModbusError>;
-    /** Reconnects the transport. Opens lazily if no prior connection exists. */
+    /**
+     * Reconnects the transport. Opens lazily if no prior connection exists.
+     *
+     * Concurrent calls are coalesced: fibers arriving while a reconnect is in
+     * flight join it rather than starting another, and all of them observe its
+     * result. Fails with `ModbusNotConnectedError` if the transport was closed
+     * while the reconnect was running.
+     */
     reconnect(): Effect.Effect<void, ModbusError>;
     /** Closes the transport and its scope immediately. */
     close(): Effect.Effect<void, ModbusError, Scope.Scope>;
@@ -57,8 +145,21 @@ interface TransportHandle<TClient> {
 export declare function makeTransportScoped<TOptions, TClient extends AnyModbusClient, TTransport extends TransportHandle<TClient>>(transportKey: string, openMethod: (TC: unknown, options: TOptions) => Promise<TTransport>, serviceName: string, config?: {
     /** Which `modbus-rs` conditional export to import from. Defaults to `"modbus-rs"` (native). */
     moduleSpecifier?: 'modbus-rs' | 'modbus-rs/web';
-}): (options: TOptions) => Effect.Effect<{
-    withClient: (unitId: number) => Effect.Effect<EffectModbusClient, ModbusError, never>;
+}): (options: TOptions & TransportResilienceOptions) => 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<EffectModbusClient, ModbusError, never>;
     setRequestTimeout: (timeoutMs: number) => Effect.Effect<undefined, ModbusNotConnectedError, never>;
     clearRequestTimeout: () => Effect.Effect<undefined, ModbusNotConnectedError, never>;
     reconnect: () => Effect.Effect<undefined, ModbusError, never>;

package/dist/src/shared-transport.test.d.ts

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

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

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

package/package.json

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