@flux-control/effect-modbus-rs 0.5.0 → 0.7.0

package/README.md

@@ -394,7 +394,23 @@ const damper =
 const same = yield * transport.batchingClient(3); // elsewhere, no options to restate
 ```
 
-`withBatchingClient` declares. Declaring a unit twice fails with `ModbusInvalidArgumentError`, whatever the second call asks for. `batchingClient` looks up, and fails the same way when nothing has declared that unit. A lookup that arrives while a declaration is still in flight waits for it, so neither call has to know which one ran first.
+`withBatchingClient` declares. Declaring a unit twice fails with `ModbusUnitAlreadyDeclaredError`, whatever the second call asks for. `batchingClient` looks up, and fails with `ModbusInvalidArgumentError` when nothing has declared that unit. A lookup that arrives while a declaration is still in flight waits for it, so neither call has to know which one ran first.
+
+A declaration belongs to the transport scope, not to the caller. It stays when the caller is interrupted, and when the owner that made it closes while the transport stays open. An owner that can start again over the same transport can catch the error and recover the existing client:
+
+```ts
+const damper =
+  yield *
+  transport
+    .withBatchingClient(3, { debounce })
+    .pipe(
+      Effect.catchTag('ModbusUnitAlreadyDeclaredError', (error) =>
+        transport.batchingClient(error.unitId),
+      ),
+    );
+```
+
+The recovered client keeps the options of the first declaration. `client.debounce` gives its debounce windows as frozen, resolved `Duration` values, so the owner can compare them with the windows that it expects. An omitted `maxHold` shows as four times the write window, which is the limit that the client applies.
 
 ### Shutdown
 
@@ -547,6 +563,8 @@ Errors from the underlying Rust layer are mapped to typed `Effect` errors via `D
 
 Handle with `Effect.catchTags`. The `ModbusError` union type covers all seven variants.
 
+`withBatchingClient` can also fail with `ModbusUnitAlreadyDeclaredError` when the unit already has a batching client. This error is not a member of `ModbusError`, because it never comes from the bus. See [Declaring a unit, and reaching for it](#declaring-a-unit-and-reaching-for-it).
+
 ## Resilience: retries, reconnection, and circuit breaking
 
 > **These are application-level policies, and they are opt-in.**
@@ -711,6 +729,32 @@ Effect.gen(function* () {
 });
 ```
 
+### Connect timeout
+
+The `modbus-rs` bindings do not limit the time of a connect. A TCP connect to a host that does not answer waits until the operating system stops it. On Linux with default settings, this takes about 2 minutes. During that time, every operation joins the same pending connect.
+
+Set `connectTimeout` to limit how long each operation waits for an open or a reconnect:
+
+```ts
+TcpTransportService.make({
+  host: '192.0.2.1',
+  port: 502,
+  connectTimeout: '3 seconds', // limit for each wait on an open or reconnect
+  reconnect: {},
+});
+```
+
+The limit applies to each operation that waits for an open or reconnect. When it expires, that operation fails with `ModbusTimeoutError`.
+
+The native connect cannot be cancelled, so it continues after the timeout:
+
+- Later operations wait for the same native connect, each for at most the limit. A transport never has more than one pending native connect.
+- When the native connect succeeds later, the transport uses it. A late reconnect that succeeds after the supervisor published `Down` publishes `Connected` at once.
+- When the native connect fails, the next operation starts a new connect.
+- A supervised reconnect attempt that times out is retried by the reconnect policy by default. When the attempts are exhausted, the transport publishes `Down`.
+
+The option applies to every transport. It is unbounded by default. `requestTimeoutMs` limits each request, but it does not limit the connect.
+
 ### Retrying a transaction
 
 `retryModbus(policy)` remains exported for the one case the transport cannot express: driving a **compound** operation as a unit, where retrying individual frames would be wrong.

package/dist/index.d.ts

@@ -159,7 +159,7 @@ export type { DebouncedWrite, WriteDebouncer, WriteDebouncerOptions } from './sr
 export { createReadDebouncer } from './src/read-debouncer';
 export type { ReadDebouncer, ReadDebouncerOptions } from './src/read-debouncer';
 export { makeBatchingClient, createBatchingRegistry } from './src/batching-client';
-export type { BatchingClientOptions, BatchingDebounceOptions, BatchingModbusClient, BatchingRegistry, BatchingRegistryDeps, BatchingRegisterReader, } from './src/batching-client';
+export type { BatchingClientOptions, BatchingDebounceOptions, BatchingDebounceWindows, BatchingModbusClient, BatchingRegistry, BatchingRegistryDeps, BatchingRegisterReader, } from './src/batching-client';
 export { mergeSpanAttributes } from './src/span-attributes';
 export type { ModbusSpanAttributes } from './src/span-attributes';
 export { AsciiTransportService } from './src/AsciiTransportService';

package/dist/index.js

@@ -25,6 +25,9 @@ class ModbusNotConnectedError extends Data.TaggedError("ModbusNotConnectedError"
 
 class ModbusCircuitOpenError extends Data.TaggedError("ModbusCircuitOpenError") {
 }
+
+class ModbusUnitAlreadyDeclaredError extends Data.TaggedError("ModbusUnitAlreadyDeclaredError") {
+}
 function parseExceptionCode(message) {
   const m = message.match(/\[MODBUS_EXCEPTION:(\d+)\]/);
   return m ? Number(m[1]) : undefined;
@@ -393,9 +396,13 @@ var createRegisterCache = () => {
 };
 // src/write-debouncer.ts
 import { Clock, Deferred, Duration as Duration3, Effect as Effect3, Fiber, Semaphore } from "effect";
+var resolveWriteHold = (window, maxHold) => {
+  const windowMs = Duration3.toMillis(Duration3.fromInputUnsafe(window));
+  const maxHoldMs = maxHold === undefined ? windowMs * 4 : Duration3.toMillis(Duration3.fromInputUnsafe(maxHold));
+  return { windowMs, maxHoldMs };
+};
 var createWriteDebouncer = (options) => Effect3.gen(function* () {
-  const windowMs = Duration3.toMillis(Duration3.fromInputUnsafe(options.window));
-  const maxHoldMs = options.maxHold === undefined ? windowMs * 4 : Duration3.toMillis(Duration3.fromInputUnsafe(options.maxHold));
+  const { windowMs, maxHoldMs } = resolveWriteHold(options.window, options.maxHold);
   const scope = yield* Effect3.scope;
   const lock = yield* Semaphore.make(1);
   const flushLock = yield* Semaphore.make(1);
@@ -663,6 +670,7 @@ var createReadDebouncer = (options) => Effect4.gen(function* () {
 // src/batching-client.ts
 import {
   Deferred as Deferred3,
+  Duration as Duration5,
   Effect as Effect5,
   Exit as Exit2,
   Fiber as Fiber3,
@@ -693,6 +701,22 @@ var mergeSpanAttributes = (sources) => {
 };
 
 // src/batching-client.ts
+var resolveDebounceWindows = (options) => {
+  if (options === undefined)
+    return;
+  const hold = options.writes === undefined ? undefined : resolveWriteHold(options.writes.window, options.writes.maxHold);
+  return Object.freeze({
+    ...hold && {
+      writes: Object.freeze({
+        window: Duration5.millis(hold.windowMs),
+        maxHold: Duration5.millis(hold.maxHoldMs)
+      })
+    },
+    ...options.reads && {
+      reads: Object.freeze({ window: Duration5.fromInputUnsafe(options.reads.window) })
+    }
+  });
+};
 var makeBatchingClient = (options) => Effect5.gen(function* () {
   const { unitId, client, cache } = options;
   const scope = yield* Effect5.scope;
@@ -772,6 +796,7 @@ var makeBatchingClient = (options) => Effect5.gen(function* () {
   return {
     unitId,
     cache,
+    debounce: resolveDebounceWindows(options.debounce),
     write: writes.write,
     writeNow: writes.writeNow,
     writeAll: writes.writeAll,
@@ -842,7 +867,7 @@ var createBatchingRegistry = (deps) => {
   };
   const alreadyDeclaredError = (unitId) => {
     const message = `Unit ${unitId} already has a batching client. One unit has one batch, so a unit ` + `is declared once. Use batchingClient(${unitId}) to reach the existing one.`;
-    return new ModbusInvalidArgumentError({ cause: new Error(message), message });
+    return new ModbusUnitAlreadyDeclaredError({ cause: new Error(message), message, unitId });
   };
   const notDeclaredError = (unitId) => {
     const message = `No batching client is declared for unit ${unitId}. Declare one with ` + `withBatchingClient(${unitId}) before reaching for it.`;
@@ -1250,7 +1275,7 @@ var createMockTransport = (devices) => {
 };
 
 // src/shared-transport.ts
-import { Deferred as Deferred4, Effect as Effect8, Exit as Exit4, Option, Ref, Scope as Scope3, SubscriptionRef as SubscriptionRef4 } from "effect";
+import { Deferred as Deferred4, Duration as Duration6, Effect as Effect8, Exit as Exit4, Option, Ref, Scope as Scope3, SubscriptionRef as SubscriptionRef4 } from "effect";
 var makeInFlight = () => Ref.make(Option.none());
 var singleFlight = (inFlight, work) => Effect8.uninterruptibleMask((restore) => Effect8.gen(function* () {
   const fresh = yield* Deferred4.make();
@@ -1292,9 +1317,11 @@ var loadTransportConstructor = async (transportKey, moduleSpecifier) => {
 function createTransportScoped(transportKey, openMethod, serviceName, config) {
   return Effect8.fnUntraced(function* (options) {
     const { retry: transportRetry, reconnect: reconnectOptions } = options;
+    const connectTimeout = options.connectTimeout === undefined ? undefined : Duration6.fromInputUnsafe(options.connectTimeout);
     const openOptions = { ...options };
     Reflect.deleteProperty(openOptions, "retry");
     Reflect.deleteProperty(openOptions, "reconnect");
+    Reflect.deleteProperty(openOptions, "connectTimeout");
     const TC = yield* Effect8.promise(() => loadTransportConstructor(transportKey, config?.moduleSpecifier ?? "modbus-rs"));
     let transport = null;
     const opening = yield* makeInFlight();
@@ -1310,6 +1337,15 @@ function createTransportScoped(transportKey, openMethod, serviceName, config) {
       message: "Transport has been closed"
     });
     const closeOrphan = (t) => Effect8.forkDetach(Effect8.ignore(Effect8.tryPromise(() => t.close())));
+    const limitConnect = (wait) => {
+      if (connectTimeout === undefined)
+        return wait;
+      const message = `${serviceName}: connect did not complete within ${Duration6.format(connectTimeout)}`;
+      return Effect8.timeoutOrElse(wait, {
+        duration: connectTimeout,
+        orElse: () => Effect8.fail(new ModbusTimeoutError({ cause: new Error(message), message }))
+      });
+    };
     const openTransport = Effect8.tryPromise({
       try: () => openMethod(TC, openOptions),
       catch: (cause) => toModbusError(cause instanceof Error ? cause : new Error(String(cause)))
@@ -1321,7 +1357,7 @@ function createTransportScoped(transportKey, openMethod, serviceName, config) {
         return yield* transportClosed();
       if (transport)
         return transport;
-      const t = yield* singleFlight(opening, openTransport);
+      const t = yield* limitConnect(singleFlight(opening, openTransport));
       if (closed)
         return yield* transportClosed();
       return t;
@@ -1340,14 +1376,15 @@ function createTransportScoped(transportKey, openMethod, serviceName, config) {
     });
     yield* Effect8.addFinalizer(() => Effect8.orDie(closeTransport));
     const notConnectedMsg = "Transport is not connected. Call withClient() first.";
+    const reconnectTransport = (t) => limitConnect(singleFlight(reconnecting, Effect8.tryPromise({
+      try: () => t.reconnect(),
+      catch: (cause) => toModbusError(cause instanceof Error ? cause : new Error(String(cause)))
+    }).pipe(Effect8.tap(() => closed ? closeOrphan(t) : SubscriptionRef4.update(connectionState, (current) => ConnectionState.$is("Down")(current) ? ConnectionState.Connected() : current)))));
     const reconnectOnce = Effect8.suspend(() => {
       const t = transport;
       if (closed || !t)
         return transportClosed();
-      return singleFlight(reconnecting, Effect8.tryPromise({
-        try: () => t.reconnect(),
-        catch: (cause) => toModbusError(cause instanceof Error ? cause : new Error(String(cause)))
-      }).pipe(Effect8.tap(() => closed ? closeOrphan(t) : Effect8.void)));
+      return reconnectTransport(t);
     });
     const report = (error) => {
       if (closed || !resolvedReconnect.triggers(error))
@@ -1424,10 +1461,7 @@ function createTransportScoped(transportKey, openMethod, serviceName, config) {
           yield* ensureOpen();
           return;
         }
-        yield* singleFlight(reconnecting, Effect8.tryPromise({
-          try: () => t.reconnect(),
-          catch: (cause) => toModbusError(cause instanceof Error ? cause : new Error(String(cause)))
-        }).pipe(Effect8.tap(() => closed ? closeOrphan(t) : Effect8.void)));
+        yield* reconnectTransport(t);
         if (closed)
           return yield* transportClosed();
         yield* SubscriptionRef4.set(connectionState, ConnectionState.Connected());
@@ -1685,6 +1719,7 @@ export {
   ModbusNotConnectedError,
   ModbusTimeoutError,
   ModbusTransportError,
+  ModbusUnitAlreadyDeclaredError,
   RetryPolicies,
   RtuTransportService,
   SerialTransportService,

package/dist/src/AsciiTransportService.d.ts

@@ -51,7 +51,7 @@ export declare class AsciiTransportService extends AsciiTransportService_base {
         close: () => import("effect/Effect").Effect<void, import("./errors").ModbusError, import("effect/Scope").Scope>;
         withBatchingClient: (unitId: number, options?: import("./batching-client").BatchingClientOptions & {
             readonly retry?: import("./retry").ModbusRetryPolicy;
-        }) => import("effect/Effect").Effect<import("./batching-client").BatchingModbusClient, import("./errors").ModbusError>;
+        }) => import("effect/Effect").Effect<import("./batching-client").BatchingModbusClient, import("./errors").ModbusError | import("./errors").ModbusUnitAlreadyDeclaredError>;
         batchingClient: (unitId: number) => import("effect/Effect").Effect<import("./batching-client").BatchingModbusClient, import("./errors").ModbusError>;
         readonly touchedUnits: Set<number>;
         hasPendingRequests: () => boolean;

package/dist/src/RtuTransportService.d.ts

@@ -51,7 +51,7 @@ export declare class RtuTransportService extends RtuTransportService_base {
         close: () => import("effect/Effect").Effect<void, import("./errors").ModbusError, import("effect/Scope").Scope>;
         withBatchingClient: (unitId: number, options?: import("./batching-client").BatchingClientOptions & {
             readonly retry?: import("./retry").ModbusRetryPolicy;
-        }) => import("effect/Effect").Effect<import("./batching-client").BatchingModbusClient, import("./errors").ModbusError>;
+        }) => import("effect/Effect").Effect<import("./batching-client").BatchingModbusClient, import("./errors").ModbusError | import("./errors").ModbusUnitAlreadyDeclaredError>;
         batchingClient: (unitId: number) => import("effect/Effect").Effect<import("./batching-client").BatchingModbusClient, import("./errors").ModbusError>;
         readonly touchedUnits: Set<number>;
         hasPendingRequests: () => boolean;

package/dist/src/TcpTransportService.d.ts

@@ -51,7 +51,7 @@ export declare class TcpTransportService extends TcpTransportService_base {
         close: () => import("effect/Effect").Effect<void, import("./errors").ModbusError, import("effect/Scope").Scope>;
         withBatchingClient: (unitId: number, options?: import("./batching-client").BatchingClientOptions & {
             readonly retry?: import("./retry").ModbusRetryPolicy;
-        }) => import("effect/Effect").Effect<import("./batching-client").BatchingModbusClient, import("./errors").ModbusError>;
+        }) => import("effect/Effect").Effect<import("./batching-client").BatchingModbusClient, import("./errors").ModbusError | import("./errors").ModbusUnitAlreadyDeclaredError>;
         batchingClient: (unitId: number) => import("effect/Effect").Effect<import("./batching-client").BatchingModbusClient, import("./errors").ModbusError>;
         readonly touchedUnits: Set<number>;
         hasPendingRequests: () => boolean;

package/dist/src/WasmAsciiTransportService.d.ts

@@ -57,7 +57,7 @@ export declare class WasmAsciiTransportService extends WasmAsciiTransportService
         close: () => import("effect/Effect").Effect<void, import("./errors").ModbusError, import("effect/Scope").Scope>;
         withBatchingClient: (unitId: number, options?: import("./batching-client").BatchingClientOptions & {
             readonly retry?: import("./retry").ModbusRetryPolicy;
-        }) => import("effect/Effect").Effect<import("./batching-client").BatchingModbusClient, import("./errors").ModbusError>;
+        }) => import("effect/Effect").Effect<import("./batching-client").BatchingModbusClient, import("./errors").ModbusError | import("./errors").ModbusUnitAlreadyDeclaredError>;
         batchingClient: (unitId: number) => import("effect/Effect").Effect<import("./batching-client").BatchingModbusClient, import("./errors").ModbusError>;
         readonly touchedUnits: Set<number>;
         hasPendingRequests: () => boolean;

package/dist/src/WasmRtuTransportService.d.ts

@@ -57,7 +57,7 @@ export declare class WasmRtuTransportService extends WasmRtuTransportService_bas
         close: () => import("effect/Effect").Effect<void, import("./errors").ModbusError, import("effect/Scope").Scope>;
         withBatchingClient: (unitId: number, options?: import("./batching-client").BatchingClientOptions & {
             readonly retry?: import("./retry").ModbusRetryPolicy;
-        }) => import("effect/Effect").Effect<import("./batching-client").BatchingModbusClient, import("./errors").ModbusError>;
+        }) => import("effect/Effect").Effect<import("./batching-client").BatchingModbusClient, import("./errors").ModbusError | import("./errors").ModbusUnitAlreadyDeclaredError>;
         batchingClient: (unitId: number) => import("effect/Effect").Effect<import("./batching-client").BatchingModbusClient, import("./errors").ModbusError>;
         readonly touchedUnits: Set<number>;
         hasPendingRequests: () => boolean;

package/dist/src/WasmWsTransportService.d.ts

@@ -44,7 +44,7 @@ export declare class WasmWsTransportService extends WasmWsTransportService_base
         close: () => import("effect/Effect").Effect<void, import("./errors").ModbusError, import("effect/Scope").Scope>;
         withBatchingClient: (unitId: number, options?: import("./batching-client").BatchingClientOptions & {
             readonly retry?: import("./retry").ModbusRetryPolicy;
-        }) => import("effect/Effect").Effect<import("./batching-client").BatchingModbusClient, import("./errors").ModbusError>;
+        }) => import("effect/Effect").Effect<import("./batching-client").BatchingModbusClient, import("./errors").ModbusError | import("./errors").ModbusUnitAlreadyDeclaredError>;
         batchingClient: (unitId: number) => import("effect/Effect").Effect<import("./batching-client").BatchingModbusClient, import("./errors").ModbusError>;
         readonly touchedUnits: Set<number>;
         hasPendingRequests: () => boolean;

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

@@ -12,7 +12,7 @@
  */
 import { Duration, Effect, Scope, SubscriptionRef } from 'effect';
 import { ConnectionState } from './connection';
-import { type ModbusError } from './errors';
+import { ModbusUnitAlreadyDeclaredError, type ModbusError } from './errors';
 import type { EffectModbusClient, ModbusOperations } from './modbus-client';
 import { type RegisterCache } from './register-cache';
 import { type PlanReadsOptions, type PlanWritesOptions, type RegisterWrite } from './register-plan';
@@ -44,6 +44,23 @@ export interface BatchingDebounceOptions {
         readonly window: Duration.Input;
     };
 }
+/**
+ * The debounce windows that a batching client applies, as resolved values.
+ *
+ * A write entry always has `maxHold`. When the declaration omitted it, it is
+ * four times the window, which is the limit the write debouncer applies.
+ */
+export interface BatchingDebounceWindows {
+    /** The write window and the hold limit. Omitted when writes are not debounced. */
+    readonly writes?: {
+        readonly window: Duration.Duration;
+        readonly maxHold: Duration.Duration;
+    };
+    /** The read window. Omitted when reads are not debounced. */
+    readonly reads?: {
+        readonly window: Duration.Duration;
+    };
+}
 /** Options for {@link makeBatchingClient}. */
 export interface BatchingClientOptions {
     /**
@@ -111,6 +128,17 @@ export interface BatchingModbusClient extends BatchingRegisterReader {
     readonly flush: Effect.Effect<void>;
     /** The cache this client filters against, or `undefined` when `cache` is `false`. */
     readonly cache: RegisterCache | undefined;
+    /**
+     * The debounce windows this client applies, or `undefined` when its
+     * declaration had no `debounce` option.
+     *
+     * The values are resolved and frozen when the client is built. An omitted
+     * `maxHold` shows as four times the write window.
+     *
+     * A caller that recovers an existing client with `batchingClient` did not
+     * choose these windows. Compare them with the windows that the caller expects.
+     */
+    readonly debounce: BatchingDebounceWindows | undefined;
     /**
      * Runs an action when the calling scope closes, while the bus is still open
      * and before this client is torn down.
@@ -161,7 +189,10 @@ export interface BatchingRegistryDeps {
 /** The batching half of a transport's API. */
 export interface BatchingRegistry {
     /**
-     * Declares the batching client for a unit. Fails if the unit already has one.
+     * Declares the batching client for a unit.
+     *
+     * Fails with `ModbusUnitAlreadyDeclaredError` if the unit already has a
+     * completed declaration or a declaration in progress.
      *
      * The declaration belongs to the registry's transport scope, not to the
      * calling fiber. Construction therefore continues if the caller is
@@ -171,7 +202,7 @@ export interface BatchingRegistry {
      */
     withBatchingClient(unitId: number, options?: BatchingClientOptions & {
         readonly retry?: ModbusRetryPolicy;
-    }): Effect.Effect<BatchingModbusClient, ModbusError>;
+    }): Effect.Effect<BatchingModbusClient, ModbusError | ModbusUnitAlreadyDeclaredError>;
     /** The batching client for a unit. Fails if nothing has declared one. */
     batchingClient(unitId: number): Effect.Effect<BatchingModbusClient, ModbusError>;
     /** Disables raw holding-register writes once a batching client exists for the unit. */

package/dist/src/errors.d.ts

@@ -30,6 +30,9 @@ declare const ModbusTimeoutError_base: new <A extends Record<string, any> = {}>(
  * with {@link RtuTransportOptions.requestTimeoutMs | requestTimeoutMs} /
  * {@link RtuTransportOptions.responseTimeoutMs | responseTimeoutMs}.
  *
+ * The transport also raises this error locally when an operation waits for an
+ * open or reconnect longer than the `connectTimeout` transport option.
+ *
  * @see ModbusErrorCode.TIMEOUT — `modbus-rs` error code that triggers this error.
  */
 export declare class ModbusTimeoutError extends ModbusTimeoutError_base<{
@@ -159,6 +162,42 @@ export declare class ModbusCircuitOpenError extends ModbusCircuitOpenError_base<
     readonly message: string;
 }> {
 }
+declare const ModbusUnitAlreadyDeclaredError_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: "ModbusUnitAlreadyDeclaredError";
+} & Readonly<A>;
+/**
+ * Error indicating that a unit already has a batching client on this transport.
+ *
+ * This is a **local** error. `modbus-rs` never returns it. The transport
+ * raises it from `withBatchingClient` when the unit has a completed
+ * declaration or a declaration in progress.
+ *
+ * The declaration belongs to the transport scope, not to the caller. It stays
+ * after its caller is interrupted, and after the owner that made it closes.
+ * Catch this error to recover the existing client with `batchingClient(unitId)`.
+ *
+ * This error is not a member of {@link ModbusError}. It can occur only when a
+ * caller declares a unit. It never occurs on the bus, so retry policies do not
+ * apply to it.
+ *
+ * @example
+ * ```ts
+ * const client = yield* transport.withBatchingClient(3).pipe(
+ *   Effect.catchTag('ModbusUnitAlreadyDeclaredError', (error) =>
+ *     transport.batchingClient(error.unitId),
+ *   ),
+ * );
+ * ```
+ */
+export declare class ModbusUnitAlreadyDeclaredError extends ModbusUnitAlreadyDeclaredError_base<{
+    /** A descriptive error. */
+    readonly cause: Error;
+    /** Human-readable explanation of the error. */
+    readonly message: string;
+    /** The unit that already has a batching client. */
+    readonly unitId: number;
+}> {
+}
 /**
  * Union of all typed Modbus errors emitted by this library.
  *

package/dist/src/mocks.d.ts

@@ -153,7 +153,7 @@ export declare const createMockTransport: (devices: SlaveDeviceDefinitions) => (
     } | undefined) => Effect.Effect<import("./modbus-client").EffectModbusClient, ModbusInvalidArgumentError | ModbusNotConnectedError, never>;
     withBatchingClient: (unitId: number, clientOptions?: BatchingClientOptions & {
         readonly retry?: ModbusRetryPolicy;
-    }) => Effect.Effect<import("./batching-client").BatchingModbusClient, ModbusError, never>;
+    }) => Effect.Effect<import("./batching-client").BatchingModbusClient, import("./errors").ModbusUnitAlreadyDeclaredError | ModbusError, never>;
     batchingClient: (unitId: number) => Effect.Effect<import("./batching-client").BatchingModbusClient, ModbusError, never>;
     readonly touchedUnits: Set<number>;
     setRequestTimeout: (_timeoutMs: number) => Effect.Effect<void, ModbusNotConnectedError, never>;

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

@@ -1,9 +1,9 @@
-import { Effect, Scope, SubscriptionRef } from 'effect';
+import { Duration, Effect, Scope, SubscriptionRef } from 'effect';
 import type { AsyncAsciiTransport, AsyncRtuTransport, AsyncTcpTransport } from 'modbus-rs';
 import type { WasmAsciiTransport, WasmRtuTransport, WasmWsTransport } from 'modbus-rs/web';
 import { type BatchingClientOptions, type BatchingModbusClient } from './batching-client';
 import { ConnectionState, type ReconnectOptions } from './connection';
-import { ModbusNotConnectedError, type ModbusError } from './errors';
+import { ModbusNotConnectedError, type ModbusError, type ModbusUnitAlreadyDeclaredError } from './errors';
 import { type AnyModbusClient, type EffectModbusClient } from './modbus-client';
 import type { ModbusRetryPolicy } from './retry';
 /**
@@ -24,6 +24,24 @@ export interface TransportResilienceOptions {
      * enables the circuit breaker that keeps callers off a dead bus.
      */
     readonly reconnect?: ReconnectOptions;
+    /**
+     * Time limit for each operation that waits for an open or reconnect of the
+     * underlying transport.
+     *
+     * The `modbus-rs` bindings do not limit the connect time. A TCP connect to a
+     * host that does not answer waits until the operating system stops it, which
+     * takes about 2 minutes on Linux with default settings.
+     *
+     * The limit applies to each caller that waits for an open or reconnect.
+     * When it expires, that caller fails with {@link ModbusTimeoutError}.
+     *
+     * The native connect cannot be cancelled, so it continues. Later callers wait
+     * for the same native connect, each for at most this limit, so one transport
+     * has at most one pending native connect. When the native connect succeeds
+     * later, the transport uses it. When it fails, the next caller starts a new
+     * connect. Unbounded by default.
+     */
+    readonly connectTimeout?: Duration.Input;
 }
 /**
  * The `modbus-rs` transport-level retry knobs this package deliberately does
@@ -127,8 +145,12 @@ export interface TransportServiceApi {
      * A unit is declared once, because every option here is a fact about the unit
      * rather than about a caller: one unit holds one batch, one belief about the
      * device, and one window. Declaring a unit twice fails with
-     * `ModbusInvalidArgumentError`. Use {@link batchingClient} to reach a client
-     * another part of the program declared.
+     * `ModbusUnitAlreadyDeclaredError`. Use {@link batchingClient} to reach a
+     * client another part of the program declared.
+     *
+     * The declaration lasts as long as the transport. A new owner that starts over
+     * a transport that stays open finds the unit declared. It can catch
+     * `ModbusUnitAlreadyDeclaredError` and use {@link batchingClient} instead.
      *
      * Nothing is debounced unless `debounce` asks for it, matching the rest of
      * this package: default timing stays predictable.
@@ -138,7 +160,7 @@ export interface TransportServiceApi {
      */
     withBatchingClient(unitId: number, options?: BatchingClientOptions & {
         readonly retry?: ModbusRetryPolicy;
-    }): Effect.Effect<BatchingModbusClient, ModbusError>;
+    }): Effect.Effect<BatchingModbusClient, ModbusError | ModbusUnitAlreadyDeclaredError>;
     /**
      * The {@link BatchingModbusClient} declared for a unit.
      *
@@ -217,7 +239,7 @@ export declare function createTransportScoped<TOptions, TClient extends AnyModbu
     close: () => Effect.Effect<void, ModbusError, Scope.Scope>;
     withBatchingClient: (unitId: number, options?: BatchingClientOptions & {
         readonly retry?: ModbusRetryPolicy;
-    }) => Effect.Effect<BatchingModbusClient, ModbusError>;
+    }) => Effect.Effect<BatchingModbusClient, ModbusError | ModbusUnitAlreadyDeclaredError>;
     batchingClient: (unitId: number) => Effect.Effect<BatchingModbusClient, ModbusError>;
     readonly touchedUnits: Set<number>;
     hasPendingRequests: () => boolean;

package/dist/src/write-debouncer.d.ts

@@ -131,4 +131,17 @@ export interface WriteDebouncer {
  *   debouncer.write({ address: 2001, value: 20 }),
  * ], { concurrency: 'unbounded' });
  */
+/**
+ * Resolves the window and the hold limit that a write debouncer applies.
+ *
+ * The batching client reports these values, so both use this one rule.
+ *
+ * @param window - The write window.
+ * @param maxHold - The hold limit. When omitted, it is four times the window.
+ * @returns The window and the hold limit in milliseconds.
+ */
+export declare const resolveWriteHold: (window: Duration.Input, maxHold: Duration.Input | undefined) => {
+    windowMs: number;
+    maxHoldMs: number;
+};
 export declare const createWriteDebouncer: (options: WriteDebouncerOptions) => Effect.Effect<WriteDebouncer, never, Scope.Scope>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flux-control/effect-modbus-rs",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Type-safe Modbus communication via Effect-TS, wrapping the modbus-rs npm bindings.",
   "license": "GPL-3.0",
   "repository": {
@@ -47,10 +47,10 @@
     "@effect/platform-bun": "^4.0.0-rc.109",
     "@oxlint/plugins": "1.76.0",
     "@types/bun": "latest",
-    "effect": "^4.0.0-rc.109",
+    "effect": "4.0.0-rc.109",
     "fallow": "^2.104.0",
     "husky": "^9.1.7",
-    "oxfmt": "^0.60.0",
+    "oxfmt": "^0.71.0",
     "oxlint": "1.76.0",
     "typescript": "^7.0.2"
   },