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

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

@@ -0,0 +1,134 @@
+/**
+ * @fileoverview Coalesces register writes that arrive separately into one batch.
+ *
+ * `planWrites` packs the writes a caller holds at one moment. A caller that
+ * derives each register independently — one fiber per output, each settling at
+ * its own pace — never holds two values at the same moment, so a planner alone
+ * never sees a run longer than one. Batching those would need a collection point
+ * upstream that the caller does not have.
+ *
+ * This module is that collection point, and it collects on time rather than on
+ * structure. A write is held for `window`, each new arrival restarts the window,
+ * and `maxHold` caps the total hold so a register that updates without a pause
+ * still reaches the wire.
+ *
+ * Callers still await their own write. Each caller gets its own `Deferred`,
+ * completed with the exit of the flush that carried its value, so a write that
+ * fails still fails for the caller that issued it. That keeps "the effect
+ * succeeded" meaning "the value reached the device", which is the invariant a
+ * caller uses to decide whether it may report an actuation.
+ *
+ * @module
+ */
+import { Duration, Effect, type Scope } from 'effect';
+import { type ModbusError } from './errors';
+import { type RegisterWrite } from './register-plan';
+import type { ModbusSpanAttributes } from './span-attributes';
+/** One write in a flushed batch, with the attributes of the caller that issued it. */
+export interface DebouncedWrite {
+    /** Register address. */
+    readonly address: number;
+    /** Value to write, as the caller gave it. */
+    readonly value: number;
+    /** Attributes of the caller that issued the newest value for this address. */
+    readonly attributes: ModbusSpanAttributes | undefined;
+}
+/** Options for {@link createWriteDebouncer}. */
+export interface WriteDebouncerOptions {
+    /**
+     * How long a write is held before it reaches the wire. Each new arrival
+     * restarts this window.
+     *
+     * A window of zero disables the debouncer: every write is flushed on its own,
+     * with no timer and no batch. That is the escape hatch for a harness that
+     * settles by yielding rather than by advancing a clock, which would otherwise
+     * never reach a flush that runs on a forked fiber.
+     */
+    readonly window: Duration.Input;
+    /**
+     * Longest total hold, measured from the arrival that opened the batch.
+     *
+     * Without a ceiling, a register that updates faster than the window never
+     * reaches the wire at all, because every arrival restarts the wait.
+     *
+     * @defaultValue four times `window`
+     */
+    readonly maxHold?: Duration.Input;
+    /**
+     * Issues one batch.
+     *
+     * The batch holds at most one entry per address, newest value. The callback
+     * owns everything below it: the cache filter, the planning, and the span.
+     */
+    flush(batch: ReadonlyArray<DebouncedWrite>): Effect.Effect<void, ModbusError>;
+}
+/** A collection point for writes that arrive separately. */
+export interface WriteDebouncer {
+    /**
+     * Holds a write for the window, then issues it with whatever else arrived.
+     *
+     * Succeeds when the value reached the device, and fails with the error of the
+     * flush that carried it.
+     */
+    write(write: RegisterWrite, attributes?: ModbusSpanAttributes): Effect.Effect<void, ModbusError>;
+    /**
+     * Adds a write to the batch and flushes immediately, rather than waiting.
+     *
+     * This is an enqueue and then a flush, not a path around the batch. A write
+     * already pending for the same address is superseded, so the newest value is
+     * the one that reaches the device. A path that went around the batch would let
+     * an older held value be written after a newer immediate one.
+     */
+    writeNow(write: RegisterWrite, attributes?: ModbusSpanAttributes): Effect.Effect<void, ModbusError>;
+    /**
+     * Holds several writes for the window, as one caller.
+     *
+     * A caller that already holds every value does not need a collection point,
+     * but it still must not go around the batch: a write held for one of these
+     * addresses would otherwise reach the device after the newer value. The whole
+     * group succeeds or fails together.
+     *
+     * With a window of zero the group is issued at once, so a caller of this
+     * method gets packed transactions with no debouncer at all.
+     */
+    writeAll(writes: ReadonlyArray<RegisterWrite>, attributes?: ModbusSpanAttributes): Effect.Effect<void, ModbusError>;
+    /** Adds several writes to the batch and flushes immediately. */
+    writeAllNow(writes: ReadonlyArray<RegisterWrite>, attributes?: ModbusSpanAttributes): Effect.Effect<void, ModbusError>;
+    /**
+     * Issues whatever is pending, now.
+     *
+     * Never fails: the outcome goes to the callers waiting on the batch, not to
+     * whoever asked for the flush.
+     */
+    readonly flush: Effect.Effect<void>;
+    /** Addresses currently held. Intended for tests. */
+    readonly pending: number;
+}
+/**
+ * Creates a write debouncer bound to the current scope.
+ *
+ * The flush runs in that scope, not in the caller's. A caller interrupted while
+ * waiting — an output recomputed before its write landed — must not take the
+ * pending batch down with it, and a caller must not have to carry a `Scope` to
+ * issue a write.
+ *
+ * When the scope closes, callers still waiting are interrupted and the batch is
+ * discarded. Their writes never reached the device, and reporting success for
+ * them would break the invariant the `Deferred` exists to hold.
+ *
+ * @param options - The window, the ceiling, and the callback that issues a batch.
+ * @returns The debouncer.
+ *
+ * @example
+ * const debouncer = yield* createWriteDebouncer({
+ *   window: '250 millis',
+ *   maxHold: '1 second',
+ *   flush: (batch) => issue(batch),
+ * });
+ * // Two callers that never meet, one transaction:
+ * yield* Effect.all([
+ *   debouncer.write({ address: 2000, value: 10 }),
+ *   debouncer.write({ address: 2001, value: 20 }),
+ * ], { concurrency: 'unbounded' });
+ */
+export declare const createWriteDebouncer: (options: WriteDebouncerOptions) => Effect.Effect<WriteDebouncer, never, Scope.Scope>;

package/dist/test/retry.test.d.ts

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

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

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

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

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

package/dist/test/upstream-options.test.d.ts

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

package/dist/test/wasm-mocks.test.d.ts

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

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flux-control/effect-modbus-rs",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Type-safe Modbus communication via Effect-TS, wrapping the modbus-rs npm bindings.",
   "license": "GPL-3.0",
   "repository": {
@@ -33,8 +33,8 @@
     "lock": "bash tools/refresh-lockfile.sh",
     "prepare": "husky",
     "release": "changeset publish",
-    "test": "bun test ./src/ ./examples/",
-    "test:coverage": "bun test --coverage ./src/ ./examples/",
+    "test": "bun test ./test/ ./examples/",
+    "test:coverage": "bun test --coverage ./test/ ./examples/",
     "typecheck": "tsc --noEmit",
     "version": "changeset version"
   },
@@ -45,12 +45,13 @@
     "@changesets/cli": "^2.31.1",
     "@effect/language-service": "0.87.2",
     "@effect/platform-bun": "^4.0.0-rc.109",
+    "@oxlint/plugins": "1.76.0",
     "@types/bun": "latest",
     "effect": "^4.0.0-rc.109",
     "fallow": "^2.104.0",
     "husky": "^9.1.7",
     "oxfmt": "^0.60.0",
-    "oxlint": "^1.75.0",
+    "oxlint": "1.76.0",
     "typescript": "^7.0.2"
   },
   "peerDependencies": {