@flux-control/effect-modbus-rs 0.6.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.**

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.`;
@@ -1694,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

@@ -162,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

@@ -3,7 +3,7 @@ import type { AsyncAsciiTransport, AsyncRtuTransport, AsyncTcpTransport } from '
 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';
 /**
@@ -145,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.
@@ -156,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.
      *
@@ -235,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.6.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"
   },