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

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 { type ModbusError, ModbusNotConnectedError } from "./errors";
-import { type AnyModbusClient, type EffectModbusClient } from "./modbus-client";
+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>;
@@ -51,10 +139,27 @@ interface TransportHandle<TClient> {
  * @param openMethod - A function that takes the transport constructor and options,
  *   returning a promise for the opened transport.
  * @param serviceName - Logical name used in log messages and the finalizer guard.
+ * @param config - Optional module specifier override for browser WASM transports.
  * @returns An `Effect` that produces a {@link TransportServiceApi}.
  */
-export declare function makeTransportScoped<TOptions, TClient extends AnyModbusClient, TTransport extends TransportHandle<TClient>>(transportKey: string, openMethod: (TC: unknown, options: TOptions) => Promise<TTransport>, serviceName: string): (options: TOptions) => Effect.Effect<{
-    withClient: (unitId: number) => Effect.Effect<EffectModbusClient, ModbusError, never>;
+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 & 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/dist/src/wasm-mocks.test.d.ts

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

package/package.json

@@ -1,20 +1,17 @@
 {
   "name": "@flux-control/effect-modbus-rs",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Type-safe Modbus communication via Effect-TS, wrapping the modbus-rs npm bindings.",
   "license": "GPL-3.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/flux-control-solutions/Effect-modbus-rs.git"
   },
-  "type": "module",
   "files": [
     "dist/**/*.js",
     "dist/**/*.d.ts"
   ],
-  "publishConfig": {
-    "access": "public"
-  },
+  "type": "module",
   "exports": {
     "./package.json": "./package.json",
     ".": {
@@ -22,30 +19,40 @@
       "default": "./dist/index.js"
     }
   },
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
+    "build": "rm -rf ./dist && bun build ./index.ts --outdir ./dist --target node --external effect --external modbus-rs && tsc --noEmit false --emitDeclarationOnly --outDir ./dist --rootDir . --project tsconfig.build.json",
     "changeset": "changeset",
+    "docs": "bun install --cwd tools/typedoc --frozen-lockfile && bun run --cwd \"$PWD/tools/typedoc\" generate",
+    "format": "oxfmt --check",
+    "format:fix": "oxfmt",
+    "lint": "oxlint",
+    "lint:fix": "oxlint --fix",
+    "prepare": "husky",
+    "release": "changeset publish",
     "test": "bun test ./src/ ./examples/",
     "test:coverage": "bun test --coverage ./src/ ./examples/",
     "typecheck": "tsc --noEmit",
-    "build": "rm -rf ./dist && bun build ./index.ts --outdir ./dist --target node --external effect --external modbus-rs && tsc --noEmit false --emitDeclarationOnly --outDir ./dist --rootDir . --project tsconfig.build.json",
-    "docs": "typedoc",
-    "release": "changeset publish",
     "version": "changeset version"
   },
+  "dependencies": {
+    "modbus-rs": "0.16.1"
+  },
   "devDependencies": {
     "@changesets/cli": "^2.31.1",
-    "@effect/language-service": "^0.86.2",
+    "@effect/language-service": "^0.86.6",
     "@effect/platform-bun": "^0.90.0",
     "@types/bun": "latest",
-    "effect": "^3.21.4",
-    "fallow": "^2.103.0",
-    "typedoc": "^0.28.20",
-    "typescript": "^6.0.3"
+    "effect": "^3.22.0",
+    "fallow": "^2.104.0",
+    "husky": "^9.1.7",
+    "oxfmt": "^0.60.0",
+    "oxlint": "^1.75.0",
+    "typescript": "^7.0.2"
   },
   "peerDependencies": {
-    "effect": "^3.21.4"
-  },
-  "dependencies": {
-    "modbus-rs": "^0.15.3"
+    "effect": "^3.22.0"
   }
 }