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

package/dist/src/AsciiTransportService.d.ts

@@ -1,7 +1,6 @@
-import { Context, Effect, Layer } from 'effect';
+import { Context, Layer } from 'effect';
 import type { AsciiTransportOptions } from 'modbus-rs';
-import { SlaveDeviceDefinitions } from './mocks';
-import type { MockFaultOptions } from './mocks';
+import { type MockFaultOptions, type SlaveDeviceDefinitions } from './mocks';
 import type { TransportResilienceOptions, WithoutUpstreamRetry, TransportServiceApi } from './shared-transport';
 /**
  * {@link AsciiTransportOptions} minus the upstream retry knobs.
@@ -24,14 +23,14 @@ declare const AsciiTransportService_base: Context.ServiceClass<AsciiTransportSer
  *
  * @see AsyncAsciiTransport — Upstream `modbus-rs` ASCII transport.
  * @see AsciiTransportOpenOptions — Configuration for the ASCII serial port.
- * @see makeTransportScoped — Generic lifecycle logic from shared-transport.
+ * @see createTransportScoped — Generic lifecycle logic from shared-transport.
  */
 export declare class AsciiTransportService extends AsciiTransportService_base {
     /**
      * Scoped constructor effect for the service. v4 does not auto-generate a
      * layer from this, so {@link AsciiTransportService.make} builds one explicitly.
      */
-    static readonly makeScoped: (options: AsciiTransportOpenOptions & TransportResilienceOptions) => Effect.Effect<{
+    static readonly makeScoped: (options: AsciiTransportOpenOptions & TransportResilienceOptions) => import("effect/Effect").Effect<{
         connectionState: import("effect/SubscriptionRef").SubscriptionRef<{
             readonly _tag: "Connected";
         } | {
@@ -45,11 +44,16 @@ export declare class AsciiTransportService extends AsciiTransportService_base {
         }>;
         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>;
+        } | undefined) => import("effect/Effect").Effect<import("./modbus-client").EffectModbusClient, import("./errors").ModbusError, never>;
+        setRequestTimeout: (timeoutMs: number) => import("effect/Effect").Effect<undefined, import("./errors").ModbusNotConnectedError, never>;
+        clearRequestTimeout: () => import("effect/Effect").Effect<undefined, import("./errors").ModbusNotConnectedError, never>;
+        reconnect: () => import("effect/Effect").Effect<undefined, import("./errors").ModbusError, never>;
+        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>;
+        batchingClient: (unitId: number) => import("effect/Effect").Effect<import("./batching-client").BatchingModbusClient, import("./errors").ModbusError>;
+        readonly touchedUnits: Set<number>;
         hasPendingRequests: () => boolean;
     }, never, import("effect/Scope").Scope>;
     /**

package/dist/src/RtuTransportService.d.ts

@@ -1,7 +1,6 @@
-import { Context, Effect, Layer } from 'effect';
+import { Context, Layer } from 'effect';
 import type { RtuTransportOptions } from 'modbus-rs';
-import type { MockFaultOptions } from './mocks';
-import type { SlaveDeviceDefinitions } from './mocks';
+import { type MockFaultOptions, type SlaveDeviceDefinitions } from './mocks';
 import type { TransportResilienceOptions, WithoutUpstreamRetry, TransportServiceApi } from './shared-transport';
 /**
  * {@link RtuTransportOptions} minus the upstream retry knobs.
@@ -24,14 +23,14 @@ declare const RtuTransportService_base: Context.ServiceClass<RtuTransportService
  *
  * @see AsyncRtuTransport — Upstream `modbus-rs` RTU transport.
  * @see RtuTransportOpenOptions — Configuration for the RTU serial port.
- * @see makeTransportScoped — Generic lifecycle logic from shared-transport.
+ * @see createTransportScoped — Generic lifecycle logic from shared-transport.
  */
 export declare class RtuTransportService extends RtuTransportService_base {
     /**
      * Scoped constructor effect for the service. v4 does not auto-generate a
      * layer from this, so {@link RtuTransportService.make} builds one explicitly.
      */
-    static readonly makeScoped: (options: RtuTransportOpenOptions & TransportResilienceOptions) => Effect.Effect<{
+    static readonly makeScoped: (options: RtuTransportOpenOptions & TransportResilienceOptions) => import("effect/Effect").Effect<{
         connectionState: import("effect/SubscriptionRef").SubscriptionRef<{
             readonly _tag: "Connected";
         } | {
@@ -45,11 +44,16 @@ export declare class RtuTransportService extends RtuTransportService_base {
         }>;
         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>;
+        } | undefined) => import("effect/Effect").Effect<import("./modbus-client").EffectModbusClient, import("./errors").ModbusError, never>;
+        setRequestTimeout: (timeoutMs: number) => import("effect/Effect").Effect<undefined, import("./errors").ModbusNotConnectedError, never>;
+        clearRequestTimeout: () => import("effect/Effect").Effect<undefined, import("./errors").ModbusNotConnectedError, never>;
+        reconnect: () => import("effect/Effect").Effect<undefined, import("./errors").ModbusError, never>;
+        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>;
+        batchingClient: (unitId: number) => import("effect/Effect").Effect<import("./batching-client").BatchingModbusClient, import("./errors").ModbusError>;
+        readonly touchedUnits: Set<number>;
         hasPendingRequests: () => boolean;
     }, never, import("effect/Scope").Scope>;
     /**

package/dist/src/TcpTransportService.d.ts

@@ -1,7 +1,6 @@
-import { Context, Effect, Layer } from 'effect';
+import { Context, Layer } from 'effect';
 import type { TcpTransportOptions } from 'modbus-rs';
-import { SlaveDeviceDefinitions } from './mocks';
-import type { MockFaultOptions } from './mocks';
+import { type MockFaultOptions, type SlaveDeviceDefinitions } from './mocks';
 import type { TransportResilienceOptions, TransportServiceApi, WithoutUpstreamRetry } from './shared-transport';
 /**
  * {@link TcpTransportOptions} minus the upstream retry knobs.
@@ -24,14 +23,14 @@ declare const TcpTransportService_base: Context.ServiceClass<TcpTransportService
  *
  * @see AsyncTcpTransport — Upstream `modbus-rs` TCP transport.
  * @see TcpTransportOpenOptions — Configuration for the TCP connection.
- * @see makeTransportScoped — Generic lifecycle logic from shared-transport.
+ * @see createTransportScoped — Generic lifecycle logic from shared-transport.
  */
 export declare class TcpTransportService extends TcpTransportService_base {
     /**
      * Scoped constructor effect for the service. v4 does not auto-generate a
      * layer from this, so {@link TcpTransportService.make} builds one explicitly.
      */
-    static readonly makeScoped: (options: TcpTransportOpenOptions & TransportResilienceOptions) => Effect.Effect<{
+    static readonly makeScoped: (options: TcpTransportOpenOptions & TransportResilienceOptions) => import("effect/Effect").Effect<{
         connectionState: import("effect/SubscriptionRef").SubscriptionRef<{
             readonly _tag: "Connected";
         } | {
@@ -45,11 +44,16 @@ export declare class TcpTransportService extends TcpTransportService_base {
         }>;
         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>;
+        } | undefined) => import("effect/Effect").Effect<import("./modbus-client").EffectModbusClient, import("./errors").ModbusError, never>;
+        setRequestTimeout: (timeoutMs: number) => import("effect/Effect").Effect<undefined, import("./errors").ModbusNotConnectedError, never>;
+        clearRequestTimeout: () => import("effect/Effect").Effect<undefined, import("./errors").ModbusNotConnectedError, never>;
+        reconnect: () => import("effect/Effect").Effect<undefined, import("./errors").ModbusError, never>;
+        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>;
+        batchingClient: (unitId: number) => import("effect/Effect").Effect<import("./batching-client").BatchingModbusClient, import("./errors").ModbusError>;
+        readonly touchedUnits: Set<number>;
         hasPendingRequests: () => boolean;
     }, never, import("effect/Scope").Scope>;
     /**

package/dist/src/WasmAsciiTransportService.d.ts

@@ -1,12 +1,11 @@
-import { Context, Effect, Layer } from 'effect';
+import { Context, Layer } from 'effect';
 import type { WasmSerialPortHandle, WasmSerialTransportOptions } from 'modbus-rs/web';
-import { SlaveDeviceDefinitions } from './mocks';
-import type { MockFaultOptions } from './mocks';
+import { type MockFaultOptions, type SlaveDeviceDefinitions } from './mocks';
 import type { TransportResilienceOptions, TransportServiceApi } from './shared-transport';
 /**
  * Options for {@link WasmAsciiTransportService}. `WasmAsciiTransport.open()` takes the
  * serial port handle and the connection options as two separate arguments; this
- * combines them into one object so it fits {@link makeTransportScoped}'s single-options
+ * combines them into one object so it fits {@link createTransportScoped}'s single-options
  * shape, with `port` destructured back out inside the service's `openMethod`.
  *
  * @see requestSerialPort — Obtains the `port` handle (must be called from a user gesture).
@@ -28,7 +27,7 @@ declare const WasmAsciiTransportService_base: Context.ServiceClass<WasmAsciiTran
  *
  * @see WasmAsciiTransport — Upstream `modbus-rs` browser Web Serial ASCII transport.
  * @see requestSerialPort — Obtains the serial port handle this service's `port` option needs.
- * @see makeTransportScoped — Generic lifecycle logic from shared-transport.
+ * @see createTransportScoped — Generic lifecycle logic from shared-transport.
  */
 export declare class WasmAsciiTransportService extends WasmAsciiTransportService_base {
     /**
@@ -37,7 +36,7 @@ export declare class WasmAsciiTransportService extends WasmAsciiTransportService
      */
     static readonly makeScoped: (options: WasmSerialTransportOptions & {
         port: WasmSerialPortHandle;
-    } & TransportResilienceOptions) => Effect.Effect<{
+    } & TransportResilienceOptions) => import("effect/Effect").Effect<{
         connectionState: import("effect/SubscriptionRef").SubscriptionRef<{
             readonly _tag: "Connected";
         } | {
@@ -51,11 +50,16 @@ export declare class WasmAsciiTransportService extends WasmAsciiTransportService
         }>;
         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>;
+        } | undefined) => import("effect/Effect").Effect<import("./modbus-client").EffectModbusClient, import("./errors").ModbusError, never>;
+        setRequestTimeout: (timeoutMs: number) => import("effect/Effect").Effect<undefined, import("./errors").ModbusNotConnectedError, never>;
+        clearRequestTimeout: () => import("effect/Effect").Effect<undefined, import("./errors").ModbusNotConnectedError, never>;
+        reconnect: () => import("effect/Effect").Effect<undefined, import("./errors").ModbusError, never>;
+        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>;
+        batchingClient: (unitId: number) => import("effect/Effect").Effect<import("./batching-client").BatchingModbusClient, import("./errors").ModbusError>;
+        readonly touchedUnits: Set<number>;
         hasPendingRequests: () => boolean;
     }, never, import("effect/Scope").Scope>;
     /**

package/dist/src/WasmRtuTransportService.d.ts

@@ -1,12 +1,11 @@
-import { Context, Effect, Layer } from 'effect';
+import { Context, Layer } from 'effect';
 import type { WasmSerialPortHandle, WasmSerialTransportOptions } from 'modbus-rs/web';
-import { SlaveDeviceDefinitions } from './mocks';
-import type { MockFaultOptions } from './mocks';
+import { type MockFaultOptions, type SlaveDeviceDefinitions } from './mocks';
 import type { TransportResilienceOptions, TransportServiceApi } from './shared-transport';
 /**
  * Options for {@link WasmRtuTransportService}. `WasmRtuTransport.open()` takes the
  * serial port handle and the connection options as two separate arguments; this
- * combines them into one object so it fits {@link makeTransportScoped}'s single-options
+ * combines them into one object so it fits {@link createTransportScoped}'s single-options
  * shape, with `port` destructured back out inside the service's `openMethod`.
  *
  * @see requestSerialPort — Obtains the `port` handle (must be called from a user gesture).
@@ -28,7 +27,7 @@ declare const WasmRtuTransportService_base: Context.ServiceClass<WasmRtuTranspor
  *
  * @see WasmRtuTransport — Upstream `modbus-rs` browser Web Serial RTU transport.
  * @see requestSerialPort — Obtains the serial port handle this service's `port` option needs.
- * @see makeTransportScoped — Generic lifecycle logic from shared-transport.
+ * @see createTransportScoped — Generic lifecycle logic from shared-transport.
  */
 export declare class WasmRtuTransportService extends WasmRtuTransportService_base {
     /**
@@ -37,7 +36,7 @@ export declare class WasmRtuTransportService extends WasmRtuTransportService_bas
      */
     static readonly makeScoped: (options: WasmSerialTransportOptions & {
         port: WasmSerialPortHandle;
-    } & TransportResilienceOptions) => Effect.Effect<{
+    } & TransportResilienceOptions) => import("effect/Effect").Effect<{
         connectionState: import("effect/SubscriptionRef").SubscriptionRef<{
             readonly _tag: "Connected";
         } | {
@@ -51,11 +50,16 @@ export declare class WasmRtuTransportService extends WasmRtuTransportService_bas
         }>;
         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>;
+        } | undefined) => import("effect/Effect").Effect<import("./modbus-client").EffectModbusClient, import("./errors").ModbusError, never>;
+        setRequestTimeout: (timeoutMs: number) => import("effect/Effect").Effect<undefined, import("./errors").ModbusNotConnectedError, never>;
+        clearRequestTimeout: () => import("effect/Effect").Effect<undefined, import("./errors").ModbusNotConnectedError, never>;
+        reconnect: () => import("effect/Effect").Effect<undefined, import("./errors").ModbusError, never>;
+        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>;
+        batchingClient: (unitId: number) => import("effect/Effect").Effect<import("./batching-client").BatchingModbusClient, import("./errors").ModbusError>;
+        readonly touchedUnits: Set<number>;
         hasPendingRequests: () => boolean;
     }, never, import("effect/Scope").Scope>;
     /**

package/dist/src/WasmWsTransportService.d.ts

@@ -1,7 +1,6 @@
-import { Context, Effect, Layer } from 'effect';
+import { Context, Layer } from 'effect';
 import type { WasmWsTransportOptions } from 'modbus-rs/web';
-import { SlaveDeviceDefinitions } from './mocks';
-import type { MockFaultOptions } from './mocks';
+import { type MockFaultOptions, type SlaveDeviceDefinitions } from './mocks';
 import type { TransportResilienceOptions, TransportServiceApi } from './shared-transport';
 declare const WasmWsTransportService_base: Context.ServiceClass<WasmWsTransportService, "WasmWsTransportService", TransportServiceApi>;
 /**
@@ -17,14 +16,14 @@ declare const WasmWsTransportService_base: Context.ServiceClass<WasmWsTransportS
  *
  * @see WasmWsTransport — Upstream `modbus-rs` browser WebSocket transport.
  * @see WasmWsTransportOptions — Configuration for the WebSocket gateway connection.
- * @see makeTransportScoped — Generic lifecycle logic from shared-transport.
+ * @see createTransportScoped — Generic lifecycle logic from shared-transport.
  */
 export declare class WasmWsTransportService extends WasmWsTransportService_base {
     /**
      * Scoped constructor effect for the service. v4 does not auto-generate a
      * layer from this, so {@link WasmWsTransportService.make} builds one explicitly.
      */
-    static readonly makeScoped: (options: WasmWsTransportOptions & TransportResilienceOptions) => Effect.Effect<{
+    static readonly makeScoped: (options: WasmWsTransportOptions & TransportResilienceOptions) => import("effect/Effect").Effect<{
         connectionState: import("effect/SubscriptionRef").SubscriptionRef<{
             readonly _tag: "Connected";
         } | {
@@ -38,11 +37,16 @@ export declare class WasmWsTransportService extends WasmWsTransportService_base
         }>;
         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>;
+        } | undefined) => import("effect/Effect").Effect<import("./modbus-client").EffectModbusClient, import("./errors").ModbusError, never>;
+        setRequestTimeout: (timeoutMs: number) => import("effect/Effect").Effect<undefined, import("./errors").ModbusNotConnectedError, never>;
+        clearRequestTimeout: () => import("effect/Effect").Effect<undefined, import("./errors").ModbusNotConnectedError, never>;
+        reconnect: () => import("effect/Effect").Effect<undefined, import("./errors").ModbusError, never>;
+        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>;
+        batchingClient: (unitId: number) => import("effect/Effect").Effect<import("./batching-client").BatchingModbusClient, import("./errors").ModbusError>;
+        readonly touchedUnits: Set<number>;
         hasPendingRequests: () => boolean;
     }, never, import("effect/Scope").Scope>;
     /**

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

@@ -0,0 +1,197 @@
+/**
+ * @fileoverview A client that decides the transactions, rather than issuing the
+ * ones a caller names.
+ *
+ * `withClient` returns an {@link EffectModbusClient}: it issues exactly the
+ * transaction asked for, and it is the right client when a caller knows what the
+ * bus should carry. This module is its sibling for the other case — a caller with
+ * one accessor per register, which knows what it wants to read and write but not
+ * what that ought to cost.
+ *
+ * @module
+ */
+import { Duration, Effect, Scope, SubscriptionRef } from 'effect';
+import { ConnectionState } from './connection';
+import { 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';
+import type { ModbusRetryPolicy } from './retry';
+import { type ModbusSpanAttributes } from './span-attributes';
+/** How long operations are collected before they reach the bus. */
+export interface BatchingDebounceOptions {
+    /**
+     * The window for writes, and the ceiling on the total hold.
+     *
+     * Omitted, writes are not debounced: each one reaches the bus on its own. The
+     * package holds nothing back by default, so a caller that has not asked for a
+     * window pays no latency for one.
+     */
+    readonly writes?: {
+        readonly window: Duration.Input;
+        readonly maxHold?: Duration.Input;
+    };
+    /**
+     * The window for reads.
+     *
+     * Omitted, reads are not debounced. `readAll` still plans the addresses it is
+     * given, so a caller that reads a group in one call needs no window.
+     *
+     * A useful window is on the order of one transaction. Measure a transaction on
+     * the bus in question before choosing one.
+     */
+    readonly reads?: {
+        readonly window: Duration.Input;
+    };
+}
+/** Options for {@link makeBatchingClient}. */
+export interface BatchingClientOptions {
+    /**
+     * The write cache, which drops a write whose value the device already holds.
+     *
+     * Pass `false` to write every value, whether or not it changes anything. Pass
+     * a cache to share one with something else. The transport supplies its own by
+     * default, which is the right one: the cache is a belief about a physical
+     * device, and two caches on one unit disagree.
+     */
+    readonly cache?: boolean | RegisterCache;
+    /** The windows. Omitted, nothing is debounced. */
+    readonly debounce?: BatchingDebounceOptions;
+    /** Limits handed to the planners. */
+    readonly plan?: {
+        readonly writes?: PlanWritesOptions;
+        readonly reads?: PlanReadsOptions;
+    };
+}
+/** Reads over one register space. */
+export interface BatchingRegisterReader {
+    /** Collects an address for the read window, then returns its value. */
+    read(address: number): Effect.Effect<number, ModbusError>;
+    /** Adds an address to the batch and reads immediately, answering every reader in it. */
+    readNow(address: number): Effect.Effect<number, ModbusError>;
+    /** Reads a group as one reader, planned into spans, in the order asked for. */
+    readAll(addresses: ReadonlyArray<number>): Effect.Effect<ReadonlyArray<number>, ModbusError>;
+    /** Adds a group to the batch and reads immediately. */
+    readAllNow(addresses: ReadonlyArray<number>): Effect.Effect<ReadonlyArray<number>, ModbusError>;
+}
+/**
+ * A client that decides its own transactions.
+ *
+ * CAUTION: This is not an {@link EffectModbusClient} and does not extend
+ * {@link ModbusOperations}. There is no `writeSingleRegister` and no
+ * `readHoldingRegisters` here. A raw write on this object would go around the
+ * cache and around the batch, so a value held for an address could reach the
+ * device after a newer value written past it. A caller that needs the raw
+ * surface as well gets it from `withClient`, which shares the same connection.
+ * Once a batching client exists for a unit, that raw client remains available
+ * for reads, coils, and the other non-register-write operations, but FC06,
+ * FC16, and FC23 fail with `ModbusInvalidArgumentError`. Mixing the two register
+ * write paths would bypass the pending batch and its cache.
+ *
+ * Coils are not covered. The planners pack registers, so `readCoils`,
+ * `writeSingleCoil`, and their relatives stay on the raw client.
+ */
+export interface BatchingModbusClient extends BatchingRegisterReader {
+    /** The unit this client addresses. */
+    readonly unitId: number;
+    /** Holds a write for the write window, then issues it with whatever else arrived. */
+    write(write: RegisterWrite, attributes?: ModbusSpanAttributes): Effect.Effect<void, ModbusError>;
+    /** Adds a write to the batch and issues it immediately, newest value winning. */
+    writeNow(write: RegisterWrite, attributes?: ModbusSpanAttributes): Effect.Effect<void, ModbusError>;
+    /** Holds a group of writes as one caller. The group succeeds or fails together. */
+    writeAll(writes: ReadonlyArray<RegisterWrite>, attributes?: ModbusSpanAttributes): Effect.Effect<void, ModbusError>;
+    /** Adds a group of writes to the batch and issues it immediately. */
+    writeAllNow(writes: ReadonlyArray<RegisterWrite>, attributes?: ModbusSpanAttributes): Effect.Effect<void, ModbusError>;
+    /** Reads over the input registers (FC04). The unqualified reads are holding registers (FC03). */
+    readonly inputs: BatchingRegisterReader;
+    /**
+     * Issues everything pending, now. Never fails: the outcome goes to the callers
+     * waiting on each batch.
+     */
+    readonly flush: Effect.Effect<void>;
+    /** The cache this client filters against, or `undefined` when `cache` is `false`. */
+    readonly cache: RegisterCache | undefined;
+    /**
+     * Runs an action when the calling scope closes, while the bus is still open
+     * and before this client is torn down.
+     *
+     * A device's safe state is the device's own answer — zero volts for one, a
+     * stopped motor for another — so it is stated here, on the client that
+     * addresses it, rather than dispatched from one action over a set of units.
+     *
+     * A failure is logged and then raised as a defect. The other finalizers in the
+     * scope still run, so a device that cannot be reached does not cost the rest of
+     * the bus its turn. Wrap the action in `Effect.ignoreLogged` to accept the
+     * failure instead.
+     *
+     * @example
+     * const damper = yield* transport.withBatchingClient(3);
+     * yield* damper.onShutdown(damper.writeAllNow([{ address: 2000, value: 0 }]));
+     */
+    onShutdown(action: Effect.Effect<void, ModbusError>): Effect.Effect<void, never, Scope.Scope>;
+}
+/**
+ * Builds a batching client over an Effect-wrapped client for one unit.
+ *
+ * The transport calls this from `withBatchingClient`, which is where a consumer
+ * normally meets it. Call it directly to drive a client this package did not
+ * hand out, such as another adapter implementing `EffectModbusClient`, or a stub.
+ *
+ * @param options - The unit, the Effect-wrapped client, and the policies.
+ * @returns The batching client, bound to the current scope.
+ */
+export declare const makeBatchingClient: (options: {
+    readonly unitId: number;
+    readonly client: EffectModbusClient;
+    readonly cache: RegisterCache | undefined;
+    readonly debounce?: BatchingDebounceOptions;
+    readonly plan?: BatchingClientOptions['plan'];
+}) => Effect.Effect<BatchingModbusClient, never, Scope.Scope>;
+/** What a transport gives the registry so it can build batching clients. */
+export interface BatchingRegistryDeps {
+    /** The transport's own raw client factory. */
+    withClient(unitId: number, options?: {
+        readonly retry?: ModbusRetryPolicy;
+    }): Effect.Effect<EffectModbusClient, ModbusError>;
+    /** The link state the shared cache watches. */
+    readonly connectionState: SubscriptionRef.SubscriptionRef<ConnectionState>;
+    /** The transport's own scope, which the clients and the watcher live in. */
+    readonly scope: Scope.Scope;
+}
+/** 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.
+     *
+     * The declaration belongs to the registry's transport scope, not to the
+     * calling fiber. Construction therefore continues if the caller is
+     * interrupted. A shorter-lived owner that abandons this effect must recover
+     * the pending or completed declaration with `batchingClient` rather than
+     * trying to declare the unit again.
+     */
+    withBatchingClient(unitId: number, options?: BatchingClientOptions & {
+        readonly retry?: ModbusRetryPolicy;
+    }): Effect.Effect<BatchingModbusClient, ModbusError>;
+    /** 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. */
+    guardRawWrites(unitId: number, operations: ModbusOperations): ModbusOperations;
+}
+/**
+ * Builds the per-unit batching clients of one transport, and the cache they
+ * share.
+ *
+ * Declaring a client and reaching for one are separate operations, because every
+ * option a client takes is a fact about the unit rather than about a caller: two
+ * batching clients on one unit hold two batches and coalesce neither, two caches
+ * on one unit hold two beliefs about one device, and one batch has one window. A
+ * per-caller configuration could only ever be correct when every caller passed
+ * the same value, so it is declared once instead of compared at every call.
+ *
+ * `withBatchingClient` declares. `batchingClient` looks up, and waits for a
+ * declaration already under way rather than depending on which fiber ran first.
+ *
+ * @param deps - The transport's raw client factory, link state, and scope.
+ * @returns The batching methods, ready to spread onto a transport API.
+ */
+export declare const createBatchingRegistry: (deps: BatchingRegistryDeps) => BatchingRegistry;

package/dist/src/connection.d.ts

@@ -1,4 +1,4 @@
-import { Data, Duration, Effect, SubscriptionRef } from 'effect';
+import { Data, Duration, Effect, type Scope, SubscriptionRef } from 'effect';
 import { ModbusCircuitOpenError, type ModbusError } from './errors';
 import { type ModbusErrorTag, type ModbusRetryPolicy } from './retry';
 /**
@@ -12,8 +12,10 @@ import { type ModbusErrorTag, type ModbusRetryPolicy } from './retry';
  * - `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.
+ * - `Down` — a connection failure was observed. With a supervisor, operations
+ *   are refused while it waits to probe again. Without one, the state remains
+ *   observable but operations retain manual behavior until `reconnect()` or a
+ *   successful operation restores `Connected`.
  */
 export type ConnectionState = Data.TaggedEnum<{
     Disconnected: object;
@@ -115,7 +117,8 @@ export declare const ConnectionState: {
  * 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.
+ * failures still update `connectionState`, but `reconnect()` must be called by
+ * the application and no circuit breaker is enabled.
  */
 export interface ReconnectOptions {
     /**
@@ -168,3 +171,27 @@ export declare const guardCircuit: (state: SubscriptionRef.SubscriptionRef<Conne
  * @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>;
+/**
+ * Claims the `Connected` → `Reconnecting` transition and starts the supervisor.
+ *
+ * The transition is claimed atomically, so of the fibers that fail together
+ * exactly one starts the supervisor and the rest simply carry on failing — one
+ * reconnect for the whole transport, not one per call site. Fibers that lose
+ * the claim do nothing at all; `onClaim` runs in the winner only, after the
+ * transition is published and before the supervisor is forked.
+ *
+ * Callers decide *whether* a failure is worth reporting (the supervisor's
+ * `triggers` predicate, plus whatever local state means "no longer eligible");
+ * this owns *how* the transition is made, so the claim protocol has one
+ * implementation.
+ *
+ * @param reconnect - The transport's own reconnect operation.
+ * @param state - The state cell the transition is claimed on.
+ * @param resolved - Reconnect configuration with defaults applied.
+ * @param scope - Scope the supervisor fiber is forked into; it is interrupted
+ *   when the scope closes.
+ * @param onClaim - Optional effect run by the claiming fiber only.
+ * @returns An Effect that completes once the supervisor is forked, or
+ *   immediately when another fiber already holds the claim.
+ */
+export declare const claimReconnect: (reconnect: Effect.Effect<void, ModbusError>, state: SubscriptionRef.SubscriptionRef<ConnectionState>, resolved: ResolvedReconnect, scope: Scope.Scope, onClaim?: Effect.Effect<void>) => Effect.Effect<void>;

package/dist/src/mocks.d.ts

@@ -1,7 +1,8 @@
-import { Effect, Schema, SubscriptionRef } from 'effect';
+import { Effect, Schema, Scope, 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 BatchingClientOptions } from './batching-client';
+import { ModbusInvalidArgumentError, ModbusNotConnectedError, type ModbusError } from './errors';
 import type { ModbusRetryPolicy } from './retry';
 import type { TransportResilienceOptions, WithoutUpstreamRetry } from './shared-transport';
 /**
@@ -135,7 +136,7 @@ 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: (WithoutUpstreamRetry<RtuTransportOptions> | WithoutUpstreamRetry<AsciiTransportOptions> | WithoutUpstreamRetry<TcpTransportOptions> | WasmWsTransportOptions | WasmSerialTransportOptions) & TransportResilienceOptions & MockFaultOptions) => Effect.Effect<{
+export declare const createMockTransport: (devices: SlaveDeviceDefinitions) => (options: (WithoutUpstreamRetry<RtuTransportOptions> | WithoutUpstreamRetry<AsciiTransportOptions> | WithoutUpstreamRetry<TcpTransportOptions> | WasmWsTransportOptions | WasmSerialTransportOptions) & TransportResilienceOptions & MockFaultOptions) => Effect.Effect<{
     connectionState: SubscriptionRef.SubscriptionRef<{
         readonly _tag: "Connected";
     } | {
@@ -149,10 +150,15 @@ export declare const makeMockTransport: (devices: SlaveDeviceDefinitions) => (op
     }>;
     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>;
+    } | 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>;
+    batchingClient: (unitId: number) => Effect.Effect<import("./batching-client").BatchingModbusClient, ModbusError, never>;
+    readonly touchedUnits: Set<number>;
+    setRequestTimeout: (_timeoutMs: number) => Effect.Effect<void, ModbusNotConnectedError, never>;
+    clearRequestTimeout: () => Effect.Effect<void, ModbusNotConnectedError, never>;
     reconnect: () => Effect.Effect<void, ModbusError, never>;
-    close: () => Effect.Effect<void, ModbusError, never>;
+    close: () => Effect.Effect<void, never, Scope.Scope>;
     hasPendingRequests: () => false;
-}, never, import("effect/Scope").Scope>;
+}, never, Scope.Scope>;

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

@@ -188,7 +188,7 @@ export interface ModbusOperations {
  * @see AsyncSerialModbusClient — Upstream native serial client API.
  * @see AsyncTcpModbusClient — Upstream native TCP client API.
  */
-export declare const makeEffectModbusClient: (client: AnyModbusClient) => ModbusOperations;
+export declare const createEffectModbusClient: (client: AnyModbusClient) => ModbusOperations;
 /**
  * Transport-owned resilience applied to every operation of a client.
  *
@@ -199,6 +199,8 @@ export declare const makeEffectModbusClient: (client: AnyModbusClient) => Modbus
 export interface ClientResilience {
     /** Refuses the operation while the transport's circuit is open. */
     readonly guard: Effect.Effect<void, ModbusError>;
+    /** Records that an operation reached the device successfully. */
+    readonly onSuccess?: Effect.Effect<void>;
     /** 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. */