@flux-control/effect-modbus-rs 0.4.1 → 0.6.0

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

@@ -0,0 +1,100 @@
+/**
+ * @fileoverview Collects register reads that arrive separately into one span.
+ *
+ * `planReads` merges the addresses a caller holds at one moment. A caller with an
+ * accessor per parameter never holds two addresses at the same moment, so a
+ * planner alone would force every such caller to be rewritten around a batch API.
+ *
+ * This module collects the addresses on time instead, so a caller keeps its
+ * per-parameter accessors and still gets one transaction per span.
+ *
+ * The read debouncer is deliberately simpler than the write debouncer. There is
+ * no supersede rule, because a second request for an address is not a newer
+ * value, it is a second reader. There is no cache, because this package records
+ * only what it wrote. There is no ceiling on the hold, because the window does
+ * not restart: it opens on the first arrival of a batch and expires on time,
+ * which a stream of arrivals can never push out.
+ *
+ * @module
+ */
+import { Duration, Effect, type Scope } from 'effect';
+import { type ModbusError } from './errors';
+import { type PlanReadsOptions, type ReadSpan } from './register-plan';
+/** Options for {@link createReadDebouncer}. */
+export interface ReadDebouncerOptions {
+    /**
+     * How long addresses are collected before the spans are read.
+     *
+     * The window opens on the first arrival and does not restart, so it bounds the
+     * latency a reader pays. One transaction is the unit to compare it against:
+     * a window far shorter than a transaction collects nothing, and a window much
+     * longer than one delays every reader for a batch it did not need.
+     *
+     * A window of zero disables the debouncer: every read is issued on its own,
+     * with no timer and no batch.
+     */
+    readonly window: Duration.Input;
+    /** Limits handed to `planReads`. */
+    readonly plan?: PlanReadsOptions;
+    /**
+     * Reads the planned spans, in order.
+     *
+     * Must return one response per span, each holding that span's `quantity`
+     * registers. The callback owns the function code: a caller that reads input
+     * registers rather than holding registers builds a second debouncer.
+     */
+    fetch(spans: ReadonlyArray<ReadSpan>): Effect.Effect<ReadonlyArray<Uint16Array>, ModbusError>;
+}
+/** A collection point for reads that arrive separately. */
+export interface ReadDebouncer {
+    /** Collects an address for the window, then returns its value. */
+    read(address: number): Effect.Effect<number, ModbusError>;
+    /**
+     * Adds an address to the batch and reads immediately, rather than waiting.
+     *
+     * Every reader already collected is answered by the same transaction, so no
+     * reader waits longer because of this call.
+     */
+    readNow(address: number): Effect.Effect<number, ModbusError>;
+    /**
+     * Collects several addresses for the window, as one reader, and returns their
+     * values in the order asked for.
+     *
+     * A reader that already holds every address does not need a collection point,
+     * only a planner. With a window of zero the group is planned and read at once,
+     * so a caller of this method gets one transaction per span with no debouncer
+     * at all.
+     */
+    readAll(addresses: ReadonlyArray<number>): Effect.Effect<ReadonlyArray<number>, ModbusError>;
+    /** Adds several addresses to the batch and reads immediately. */
+    readAllNow(addresses: ReadonlyArray<number>): Effect.Effect<ReadonlyArray<number>, ModbusError>;
+    /**
+     * Reads whatever is collected, now.
+     *
+     * Never fails: the outcome goes to the readers waiting on the batch, not to
+     * whoever asked for the flush.
+     */
+    readonly flush: Effect.Effect<void>;
+    /** Addresses currently collected. Intended for tests. */
+    readonly pending: number;
+}
+/**
+ * Creates a read debouncer bound to the current scope.
+ *
+ * As with the write debouncer, the read runs in that scope. A reader interrupted
+ * while waiting must not take the batch down with it.
+ *
+ * When the scope closes, readers still waiting are interrupted.
+ *
+ * @param options - The window, the planner limits, and the callback that reads.
+ * @returns The debouncer.
+ *
+ * @example
+ * const debouncer = yield* createReadDebouncer({
+ *   window: '5 millis',
+ *   fetch: (spans) => Effect.forEach(spans, (span) => client.readHoldingRegisters(span)),
+ * });
+ * // 49 accessors, three transactions:
+ * yield* Effect.forEach(addresses, debouncer.read, { concurrency: 'unbounded' });
+ */
+export declare const createReadDebouncer: (options: ReadDebouncerOptions) => Effect.Effect<ReadDebouncer, never, Scope.Scope>;

package/dist/src/register-cache.d.ts

@@ -0,0 +1,90 @@
+/**
+ * @fileoverview A record of what each device already holds, used to drop writes
+ * that would change nothing.
+ *
+ * A caller that recomputes an output on every cycle proposes the same value most
+ * of the time. In steady state roughly four out of five proposals are a repeat of
+ * what the register already holds, and on a half-duplex bus each one costs a
+ * turnaround that carries no information.
+ *
+ * @module
+ */
+import { type RegisterWrite } from './register-plan';
+/** The result of {@link RegisterCache.filter}. */
+export interface RegisterCacheFilter {
+    /** Writes that change a register, in the order they were proposed. */
+    readonly pending: ReadonlyArray<RegisterWrite>;
+    /** Writes the cache removed because the device already holds the value. */
+    readonly suppressed: ReadonlyArray<RegisterWrite>;
+}
+/**
+ * A belief about the contents of the registers on a bus.
+ *
+ * The key is the unit and the address together, so one cache serves every device
+ * on a transport. That is deliberate: the cache is a belief about a physical
+ * device, and there is one physical device. Two caches on one unit disagree, and
+ * the one that is wrong suppresses a write that the device needed.
+ *
+ * The cache is not a read cache. It records only what this process wrote, so it
+ * never answers a read and never claims to know a register nobody has written.
+ */
+export interface RegisterCache {
+    /**
+     * Splits proposed writes into the ones that change something and the ones that
+     * do not.
+     *
+     * When an address appears more than once, the last write wins, which is the
+     * same rule `planWrites` applies. The earlier proposals are reported as
+     * suppressed, so the counts still add up to the number of proposals.
+     *
+     * @param unitId - Unit the writes are addressed to.
+     * @param writes - Proposed writes.
+     * @returns The writes to issue, and the ones the cache removed.
+     * @throws RangeError - An address or a value is out of range.
+     */
+    filter(unitId: number, writes: ReadonlyArray<RegisterWrite>): RegisterCacheFilter;
+    /**
+     * How many times what this cache believes about a unit has been discarded.
+     *
+     * Read it before issuing a write and hand it back to {@link observe}. The
+     * number changes when the unit is invalidated, so an observation that was
+     * already in flight can tell that it is describing a device nobody knows
+     * anything about any more.
+     */
+    generationOf(unitId: number): number;
+    /**
+     * Records that a register now holds a value.
+     *
+     * Call this only after the device acknowledged the write. A value recorded
+     * before the acknowledgement suppresses the retry that would have fixed it.
+     *
+     * Pass the `generation` read before the write was issued. An invalidation that
+     * lands while a write is on the wire has to win: the write may be the last one
+     * the device took before it power-cycled, and re-recording it afterwards would
+     * suppress exactly the write that restores the register. Omitting `generation`
+     * records unconditionally.
+     */
+    observe(unitId: number, address: number, value: number, generation?: number): void;
+    /**
+     * Forgets what a unit holds, or what every unit holds when `unitId` is omitted.
+     *
+     * A failed transaction and a reconnect both mean the state of the device is
+     * unknown: it may have power-cycled and reset its outputs. A stale belief then
+     * suppresses exactly the write that would restore it.
+     */
+    invalidate(unitId?: number): void;
+    /** Registers the cache currently holds a value for. Intended for tests. */
+    readonly size: number;
+}
+/**
+ * Creates an empty {@link RegisterCache}.
+ *
+ * The cache is synchronous and holds no scope. Its lifetime is the transport's:
+ * one cache per bus, shared by every client derived from it.
+ *
+ * @example
+ * const cache = createRegisterCache();
+ * const { pending, suppressed } = cache.filter(3, [{ address: 2000, value: 512 }]);
+ * // pending: the write; suppressed: empty, since nothing is known yet
+ */
+export declare const createRegisterCache: () => RegisterCache;

package/dist/src/register-plan.d.ts

@@ -0,0 +1,212 @@
+/**
+ * @fileoverview Pure planners that turn a set of register addresses into the
+ * smallest set of Modbus transactions that covers them.
+ *
+ * A caller that derives each register independently — one fiber per output, one
+ * accessor per parameter — naturally produces one transaction per register. On a
+ * half-duplex multi-drop bus that is the dominant cost: every transaction is a
+ * turnaround, and the registers a caller wants are usually neighbours.
+ *
+ * These functions hold no state, run no I/O, and return no `Effect`. They are the
+ * bottom layer of the batching stack and are usable on their own — a caller that
+ * already owns its scheduling can plan the transactions here and issue them with
+ * a plain {@link EffectModbusClient}.
+ *
+ * @module
+ */
+/**
+ * Registers one FC16 (write multiple registers) transaction can carry.
+ *
+ * The limit follows from the PDU: 253 bytes, less the function code, the starting
+ * address, the quantity, and the byte count, leaves 246 bytes of payload.
+ *
+ * Many devices stop at a lower number than the specification allows. Pass
+ * {@link PlanWritesOptions.maxRegistersPerWrite} when the device says so.
+ */
+export declare const MODBUS_MAX_WRITE_REGISTERS = 123;
+/**
+ * Registers one FC03/FC04 (read holding/input registers) transaction can return.
+ *
+ * As with {@link MODBUS_MAX_WRITE_REGISTERS}, a device may allow fewer. Pass
+ * {@link PlanReadsOptions.maxRegistersPerRead} when it does.
+ */
+export declare const MODBUS_MAX_READ_REGISTERS = 125;
+/** One requested register write, before planning. */
+export interface RegisterWrite {
+    /** Register address. */
+    readonly address: number;
+    /**
+     * Value to write.
+     *
+     * Accepted as unsigned (`0` to `65535`) or as two's-complement signed
+     * (`-32768` to `-1`). A signed value is encoded to its unsigned form, which is
+     * what the wire carries either way.
+     */
+    readonly value: number;
+}
+/** A planned FC06 (write single register) transaction. */
+export interface SingleWriteStep {
+    readonly kind: 'single';
+    /** Register address. */
+    readonly address: number;
+    /** Value to write, encoded unsigned. */
+    readonly value: number;
+}
+/** A planned FC16 (write multiple registers) transaction. */
+export interface MultipleWriteStep {
+    readonly kind: 'multiple';
+    /** Address of the first register in the run. */
+    readonly address: number;
+    /** Values for the run, in address order. */
+    readonly values: Uint16Array;
+}
+/**
+ * One transaction in a write plan.
+ *
+ * Each step maps onto exactly one client call — `single` onto
+ * `writeSingleRegister`, `multiple` onto `writeMultipleRegisters` — so a caller
+ * can drive a plan without re-deriving the function code.
+ */
+export type WritePlanStep = SingleWriteStep | MultipleWriteStep;
+/** Options for {@link planWrites}. */
+export interface PlanWritesOptions {
+    /**
+     * Registers one FC16 transaction may carry. A longer run is split into
+     * consecutive steps of at most this many registers.
+     *
+     * @defaultValue {@link MODBUS_MAX_WRITE_REGISTERS} (123)
+     */
+    readonly maxRegistersPerWrite?: number;
+    /**
+     * Shortest run that becomes one FC16 step. A run shorter than this becomes one
+     * FC06 step per register.
+     *
+     * Some devices answer a repeated FC06 faster than a short FC16, so the trade is
+     * device-specific. Raise this to prefer FC06; set it to `1` to send every run
+     * as FC16.
+     *
+     * @defaultValue 2
+     */
+    readonly minRunLength?: number;
+}
+/** Options for {@link planReads}. */
+export interface PlanReadsOptions {
+    /**
+     * Registers one read transaction may return. A span never grows past this.
+     *
+     * @defaultValue {@link MODBUS_MAX_READ_REGISTERS} (125)
+     */
+    readonly maxRegistersPerRead?: number;
+    /**
+     * Unrequested registers the planner may read to join two spans into one.
+     *
+     * At the default of `0`, a span holds only contiguous requested addresses.
+     * Raising it trades reading registers nobody asked for against a lower
+     * transaction count.
+     *
+     * CAUTION: A gap can cover an address the device does not implement. Such a
+     * span fails with `ILLEGAL_DATA_ADDRESS` and takes every address in it down,
+     * including the ones that would have answered. Raise this only against a
+     * register map that says the gap is readable.
+     *
+     * @defaultValue 0
+     */
+    readonly maxGap?: number;
+}
+/** One planned read transaction. */
+export interface ReadSpan {
+    /** Address of the first register in the span. */
+    readonly address: number;
+    /** Registers to read, starting at {@link address}. */
+    readonly quantity: number;
+}
+/** Where one address sits in the responses to a {@link ReadPlan}. */
+export interface ReadLocation {
+    /** Index into {@link ReadPlan.spans}, and into the responses to them. */
+    readonly span: number;
+    /** Index of the register within that span's response. */
+    readonly offset: number;
+}
+/** The result of {@link planReads}. */
+export interface ReadPlan {
+    /** Transactions to issue, in ascending address order. */
+    readonly spans: ReadonlyArray<ReadSpan>;
+    /**
+     * Maps an address back to its position in the responses.
+     *
+     * Answers for every address a span covers, which includes the addresses a
+     * `maxGap` merge pulled in. Returns `undefined` for an address no span covers.
+     */
+    locate(address: number): ReadLocation | undefined;
+}
+/**
+ * Encodes a value to its unsigned 16-bit form, rejecting one that does not fit.
+ *
+ * Both step kinds carry the encoded value, so a plan writes the same bits whether
+ * the planner grouped an address into an FC06 or an FC16. Leaving the FC06 path
+ * unencoded would let `Uint16Array` truncate one path and not the other.
+ *
+ * Anything that compares a proposed value against a value already on the device
+ * must encode first, for the same reason: `-1` and `65535` are the same register
+ * contents, and a comparison that says otherwise rewrites the register forever.
+ *
+ * @param value - Unsigned (`0` to `65535`) or two's-complement signed (`-32768` to `-1`).
+ * @returns The value as an unsigned 16-bit number.
+ * @throws RangeError - The value is not an integer, or does not fit 16 bits.
+ */
+export declare const encodeRegisterValue: (value: number) => number;
+/**
+ * Packs register writes into the fewest transactions that cover them.
+ *
+ * The planner sorts by address, groups contiguous addresses into runs, splits
+ * each run at `maxRegistersPerWrite`, and emits FC16 for a run of at least
+ * `minRunLength` registers or FC06 for anything shorter.
+ *
+ * When the same address appears more than once, the last write wins. This
+ * matches a caller that supersedes a pending value rather than queueing behind
+ * it, and it is the only rule under which the plan is order-independent for
+ * distinct addresses.
+ *
+ * @param writes - Requested writes, in any order.
+ * @param options - Device limits and the FC06/FC16 preference.
+ * @returns Transactions to issue, in ascending address order.
+ * @throws RangeError - An address, a value, or an option is out of range.
+ *
+ * @example
+ * // 2000..2003 contiguous, 2010 alone
+ * planWrites([
+ *   { address: 2003, value: 40 },
+ *   { address: 2000, value: 10 },
+ *   { address: 2010, value: 99 },
+ *   { address: 2001, value: 20 },
+ *   { address: 2002, value: 30 },
+ * ]);
+ * // [
+ * //   { kind: 'multiple', address: 2000, values: Uint16Array [10, 20, 30, 40] },
+ * //   { kind: 'single', address: 2010, value: 99 },
+ * // ]
+ */
+export declare const planWrites: (writes: ReadonlyArray<RegisterWrite>, options?: PlanWritesOptions) => ReadonlyArray<WritePlanStep>;
+/**
+ * Merges register addresses into the fewest read transactions that cover them.
+ *
+ * The planner sorts and deduplicates the addresses, then extends a span while the
+ * next address is within `maxGap` unrequested registers of the last one and the
+ * span stays within `maxRegistersPerRead`.
+ *
+ * {@link ReadPlan.locate} maps each address back to its position, so a caller
+ * issues the spans, keeps the responses in order, and reads each value out
+ * without tracking the grouping itself.
+ *
+ * @param addresses - Requested addresses, in any order, duplicates allowed.
+ * @param options - Device limits and the gap tolerance.
+ * @returns The spans to read and the index back into their responses.
+ * @throws RangeError - An address or an option is out of range.
+ *
+ * @example
+ * const plan = planReads([0x0000, 0x0001, 0x0002, 0x0020, 0x0021]);
+ * plan.spans;            // [{ address: 0, quantity: 3 }, { address: 32, quantity: 2 }]
+ * plan.locate(0x0021);   // { span: 1, offset: 1 }
+ * plan.locate(0x0010);   // undefined
+ */
+export declare const planReads: (addresses: ReadonlyArray<number>, options?: PlanReadsOptions) => ReadPlan;

package/dist/src/retry.d.ts

@@ -33,7 +33,7 @@ export interface RetryDelayOptions {
  */
 export type RetryErrorOptions = boolean | RetryDelayOptions;
 /**
- * Options accepted by {@link makeRetryPolicy} and by every preset in
+ * Options accepted by {@link createRetryPolicy} and by every preset in
  * {@link RetryPolicies}.
  *
  * Nothing here is applied automatically — a policy only takes effect once it is
@@ -93,7 +93,7 @@ export interface ModbusRetryPolicyOptions {
 /**
  * A resolved retry policy: a schedule plus the predicates that produced it.
  *
- * Produced by {@link makeRetryPolicy} or a {@link RetryPolicies} preset, and
+ * Produced by {@link createRetryPolicy} 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`.
@@ -137,7 +137,7 @@ export declare const retryableExceptionCodes: ReadonlyArray<number>;
  *
  * @example
  * ```ts
- * const policy = makeRetryPolicy({
+ * const policy = createRetryPolicy({
  *   maxRetries: 5,
  *   baseDelay: "50 millis",
  *   errors: { ModbusExceptionError: false },
@@ -146,7 +146,7 @@ export declare const retryableExceptionCodes: ReadonlyArray<number>;
  *
  * @see RetryPolicies — Ready-made templates built on top of this factory.
  */
-export declare const makeRetryPolicy: (options?: ModbusRetryPolicyOptions) => ModbusRetryPolicy;
+export declare const createRetryPolicy: (options?: ModbusRetryPolicyOptions) => ModbusRetryPolicy;
 /**
  * Retry templates for common deployments.
  *

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

@@ -1,6 +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 { type ModbusError, ModbusNotConnectedError } from './errors';
+import { ModbusNotConnectedError, type ModbusError } from './errors';
 import { type AnyModbusClient, type EffectModbusClient } from './modbus-client';
 import type { ModbusRetryPolicy } from './retry';
 /**
@@ -21,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
@@ -64,7 +85,7 @@ export type WithoutUpstreamRetry<TOptions> = Omit<TOptions, UpstreamRetryOptionK
  * Provides lazy connection, per-unit-ID client caching, timeout management,
  * reconnection, and graceful shutdown — all within the Effect scope.
  *
- * @see makeTransportScoped — Factory that produces this API from a raw transport.
+ * @see createTransportScoped — Factory that produces this API from a raw transport.
  */
 export interface TransportServiceApi {
     /**
@@ -75,6 +96,11 @@ export interface TransportServiceApi {
      * logic. The underlying `modbus-rs` client is cached per unit ID, so clients
      * built with different policies still share one connection.
      *
+     * Once `withBatchingClient` has created a client for this unit, raw FC06,
+     * FC16, and FC23 operations fail. Reads, coils, and other operations remain
+     * available. One unit must use one holding-register write path so raw writes
+     * cannot bypass a pending batch or its cache.
+     *
      * @param unitId - Modbus unit ID to address.
      * @param options - Per-client policy replacing the transport default.
      */
@@ -88,7 +114,7 @@ export interface TransportServiceApi {
      * a status indicator:
      *
      * ```ts
-     * yield* Stream.runForEach(transport.connectionState.changes, (state) =>
+     * yield* Stream.runForEach(SubscriptionRef.changes(transport.connectionState), (state) =>
      *   Console.log(`link: ${state._tag}`))
      * ```
      */
@@ -108,6 +134,47 @@ export interface TransportServiceApi {
     reconnect(): Effect.Effect<void, ModbusError>;
     /** Closes the transport and its scope immediately. */
     close(): Effect.Effect<void, ModbusError, Scope.Scope>;
+    /**
+     * Declares the {@link BatchingModbusClient} for a unit.
+     *
+     * Where `withClient` issues the transaction a caller names, this client
+     * decides the transactions for the caller: it packs neighbouring registers,
+     * drops writes the device already agrees with, and — when a window is
+     * configured — collects operations that arrive near each other.
+     *
+     * 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.
+     *
+     * Nothing is debounced unless `debounce` asks for it, matching the rest of
+     * this package: default timing stays predictable.
+     *
+     * @param unitId - Modbus unit ID to address.
+     * @param options - The cache, the windows, and the planner limits.
+     */
+    withBatchingClient(unitId: number, options?: BatchingClientOptions & {
+        readonly retry?: ModbusRetryPolicy;
+    }): Effect.Effect<BatchingModbusClient, ModbusError>;
+    /**
+     * The {@link BatchingModbusClient} declared for a unit.
+     *
+     * Fails with `ModbusInvalidArgumentError` when nothing has declared one. A
+     * declaration already under way is awaited, so a lookup does not depend on
+     * which fiber ran first.
+     *
+     * @param unitId - Modbus unit ID to address.
+     */
+    batchingClient(unitId: number): Effect.Effect<BatchingModbusClient, ModbusError>;
+    /**
+     * Units a client has been built for on this transport.
+     *
+     * Transport-wide diagnostic state, not device ownership. For a device-specific
+     * shutdown action, use `BatchingModbusClient.onShutdown` on the client that
+     * addresses the device.
+     */
+    readonly touchedUnits: ReadonlySet<number>;
     /** Whether the transport currently has in-flight requests. */
     hasPendingRequests(): boolean;
 }
@@ -121,6 +188,8 @@ interface TransportHandle<TClient> {
     reconnect(): Promise<void>;
     pendingRequests: boolean;
 }
+type TransportConstructor = typeof AsyncAsciiTransport | typeof AsyncRtuTransport | typeof AsyncTcpTransport | typeof WasmAsciiTransport | typeof WasmRtuTransport | typeof WasmWsTransport;
+type TransportConstructorName = 'AsyncAsciiTransport' | 'AsyncRtuTransport' | 'AsyncTcpTransport' | 'WasmAsciiTransport' | 'WasmRtuTransport' | 'WasmWsTransport';
 /**
  * Generic factory for the scoped constructor body of an `Effect.Service`.
  *
@@ -142,7 +211,7 @@ interface TransportHandle<TClient> {
  * @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, config?: {
+export declare function createTransportScoped<TOptions, TClient extends AnyModbusClient, TTransport extends TransportHandle<TClient>>(transportKey: TransportConstructorName, openMethod: (TC: TransportConstructor, 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<{
@@ -164,6 +233,11 @@ export declare function makeTransportScoped<TOptions, TClient extends AnyModbusC
     clearRequestTimeout: () => Effect.Effect<undefined, ModbusNotConnectedError, never>;
     reconnect: () => Effect.Effect<undefined, ModbusError, never>;
     close: () => Effect.Effect<void, ModbusError, Scope.Scope>;
+    withBatchingClient: (unitId: number, options?: BatchingClientOptions & {
+        readonly retry?: ModbusRetryPolicy;
+    }) => Effect.Effect<BatchingModbusClient, ModbusError>;
+    batchingClient: (unitId: number) => Effect.Effect<BatchingModbusClient, ModbusError>;
+    readonly touchedUnits: Set<number>;
     hasPendingRequests: () => boolean;
 }, never, Scope.Scope>;
 export {};

package/dist/src/span-attributes.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @fileoverview Caller-supplied span attributes, and the rule for merging them.
+ *
+ * @module
+ */
+/**
+ * Attributes a caller attaches to the transactions it causes.
+ *
+ * The keys are opaque to this package. A caller names a register in its own
+ * vocabulary — an alias, a point name, a tag — and this package cannot know that
+ * vocabulary, so it carries the record rather than inventing a shape for it.
+ *
+ * The library's own `modbus.*` keys are applied last and win a key collision, so
+ * a caller cannot overwrite the record of what actually reached the bus.
+ */
+export type ModbusSpanAttributes = Record<string, string | number | boolean>;
+/**
+ * Joins the attributes of every caller in one batch.
+ *
+ * A batch carries several callers' worth of vocabulary, and the keys are opaque,
+ * so a repeated key keeps every value rather than letting one silently win. The
+ * values are joined with a comma, the same shape the library uses for its own
+ * `modbus.unit_ids`.
+ *
+ * A batch of one is unaffected: a one-element join is the value itself.
+ *
+ * @param sources - One attribute record per caller. `undefined` entries are skipped.
+ * @returns One record, with each key's values joined in first-seen order.
+ *
+ * @example
+ * mergeSpanAttributes([{ 'app.point': 'Supply' }, { 'app.point': 'Exhaust' }]);
+ * // { 'app.point': 'Supply,Exhaust' }
+ */
+export declare const mergeSpanAttributes: (sources: Iterable<ModbusSpanAttributes | undefined>) => ModbusSpanAttributes;