@flux-control/effect-modbus-rs 0.1.0

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

@@ -0,0 +1,182 @@
+import type { ReadRegistersOptions, WriteSingleRegisterOptions, WriteMultipleRegistersOptions, ReadWriteMultipleRegistersOptions, ReadBitsOptions, WriteSingleCoilOptions, WriteMultipleCoilsOptions, ReadFifoQueueOptions, ReadFileRecordOptions, WriteFileRecordOptions, DiagnosticsOptions, ReadDeviceIdentificationOptions, FifoQueueResponse, DiagnosticsResponse, DeviceIdentificationResponse, AsyncSerialModbusClient, AsyncTcpModbusClient } from "modbus-rs";
+import { Effect } from "effect";
+import type { ModbusError } from "./errors";
+export type AnyModbusClient = AsyncSerialModbusClient | AsyncTcpModbusClient;
+/**
+ * Effect-ified Modbus client wrapping a `modbus-rs` transport client.
+ *
+ * Each method delegates to the equivalent `AsyncSerialModbusClient` or
+ * `AsyncTcpModbusClient` method, converting the Promise-based API into
+ * an {@link Effect.Effect} with typed {@link ModbusError} failures.
+ *
+ * Thrown errors are classified using {@link toModbusError}, mapping
+ * `modbus-rs` error codes (timeout, transport, exception, etc.) into
+ * the corresponding `Data.TaggedError` variant for use with
+ * `Effect.catchTags`.
+ *
+ * @see AsyncSerialModbusClient — Upstream `modbus-rs` serial client API.
+ * @see AsyncTcpModbusClient — Upstream `modbus-rs` TCP client API.
+ */
+export interface EffectModbusClient {
+    /**
+     * Reads holding registers from the Modbus device (FC03).
+     *
+     * @param opts - Register address, quantity, and optional `AbortSignal`.
+     * @returns An Effect resolving to an array of 16-bit register values.
+     *
+     * @see ReadRegistersOptions — Options shape from `modbus-rs`.
+     * @see AsyncSerialModbusClient.readHoldingRegisters — Upstream implementation.
+     */
+    readHoldingRegisters(opts: ReadRegistersOptions): Effect.Effect<number[], ModbusError>;
+    /**
+     * Reads input registers from the Modbus device (FC04).
+     *
+     * @param opts - Register address, quantity, and optional `AbortSignal`.
+     * @returns An Effect resolving to an array of 16-bit input register values.
+     *
+     * @see ReadRegistersOptions — Options shape from `modbus-rs`.
+     * @see AsyncSerialModbusClient.readInputRegisters — Upstream implementation.
+     */
+    readInputRegisters(opts: ReadRegistersOptions): Effect.Effect<number[], ModbusError>;
+    /**
+     * Writes a single holding register (FC06).
+     *
+     * @param opts - Register address, value, and optional `AbortSignal`.
+     * @returns An Effect that completes when the write is acknowledged.
+     *
+     * @see WriteSingleRegisterOptions — Options shape from `modbus-rs`.
+     */
+    writeSingleRegister(opts: WriteSingleRegisterOptions): Effect.Effect<void, ModbusError>;
+    /**
+     * Writes multiple consecutive holding registers (FC16).
+     *
+     * @param opts - Starting address, array of values, and optional `AbortSignal`.
+     * @returns An Effect that completes when the write is acknowledged.
+     *
+     * @see WriteMultipleRegistersOptions — Options shape from `modbus-rs`.
+     */
+    writeMultipleRegisters(opts: WriteMultipleRegistersOptions): Effect.Effect<void, ModbusError>;
+    /**
+     * Atomic read-write of multiple registers (FC23).
+     *
+     * Performs a write operation and a read operation atomically within
+     * a single Modbus transaction.
+     *
+     * @param opts - Separate read and write addresses/quantities/values.
+     * @returns An Effect resolving to the read register values.
+     *
+     * @see ReadWriteMultipleRegistersOptions — Options shape from `modbus-rs`.
+     */
+    readWriteMultipleRegisters(opts: ReadWriteMultipleRegistersOptions): Effect.Effect<number[], ModbusError>;
+    /**
+     * Reads coils (digital outputs) from the Modbus device (FC01).
+     *
+     * @param opts - Starting address, quantity, and optional `AbortSignal`.
+     * @returns An Effect resolving to an array of boolean coil states.
+     *
+     * @see ReadBitsOptions — Options shape from `modbus-rs`.
+     */
+    readCoils(opts: ReadBitsOptions): Effect.Effect<boolean[], ModbusError>;
+    /**
+     * Writes a single coil (digital output) (FC05).
+     *
+     * @param opts - Coil address, boolean value, and optional `AbortSignal`.
+     * @returns An Effect that completes when the write is acknowledged.
+     *
+     * @see WriteSingleCoilOptions — Options shape from `modbus-rs`.
+     */
+    writeSingleCoil(opts: WriteSingleCoilOptions): Effect.Effect<void, ModbusError>;
+    /**
+     * Writes multiple consecutive coils (FC15).
+     *
+     * @param opts - Starting address, array of boolean values, and optional `AbortSignal`.
+     * @returns An Effect that completes when the write is acknowledged.
+     *
+     * @see WriteMultipleCoilsOptions — Options shape from `modbus-rs`.
+     */
+    writeMultipleCoils(opts: WriteMultipleCoilsOptions): Effect.Effect<void, ModbusError>;
+    /**
+     * Reads discrete inputs (digital inputs) from the Modbus device (FC02).
+     *
+     * @param opts - Starting address, quantity, and optional `AbortSignal`.
+     * @returns An Effect resolving to an array of boolean input states.
+     *
+     * @see ReadBitsOptions — Options shape from `modbus-rs`.
+     */
+    readDiscreteInputs(opts: ReadBitsOptions): Effect.Effect<boolean[], ModbusError>;
+    /**
+     * Reads the FIFO queue from the Modbus device (FC24).
+     *
+     * @param opts - FIFO pointer address and optional `AbortSignal`.
+     * @returns An Effect resolving to a `FifoQueueResponse` containing the queue values.
+     *
+     * @see ReadFifoQueueOptions — Options shape from `modbus-rs`.
+     * @see FifoQueueResponse — Response type from `modbus-rs`.
+     */
+    readFifoQueue(opts: ReadFifoQueueOptions): Effect.Effect<FifoQueueResponse, ModbusError>;
+    /**
+     * Reads file records from the Modbus device (FC20).
+     *
+     * @param opts - Array of file/sub-record read requests and optional `AbortSignal`.
+     * @returns An Effect resolving to an array of record data arrays.
+     *
+     * @see ReadFileRecordOptions — Options shape from `modbus-rs`.
+     */
+    readFileRecord(opts: ReadFileRecordOptions): Effect.Effect<number[][], ModbusError>;
+    /**
+     * Writes file records to the Modbus device (FC21).
+     *
+     * @param opts - Array of file/sub-record write requests and optional `AbortSignal`.
+     * @returns An Effect that completes when the write is acknowledged.
+     *
+     * @see WriteFileRecordOptions — Options shape from `modbus-rs`.
+     */
+    writeFileRecord(opts: WriteFileRecordOptions): Effect.Effect<void, ModbusError>;
+    /**
+     * Reads the Modbus exception status (FC07).
+     *
+     * Returns the contents of eight exception-status coils as a single byte.
+     *
+     * @returns An Effect resolving to the exception status byte value.
+     */
+    readExceptionStatus(): Effect.Effect<number, ModbusError>;
+    /**
+     * Sends a diagnostics request to the Modbus device (FC08).
+     *
+     * @param opts - Diagnostic sub-function code and data words.
+     * @returns An Effect resolving to a `DiagnosticsResponse` containing the echo sub-function and data.
+     *
+     * @see DiagnosticsOptions — Options shape from `modbus-rs`.
+     * @see DiagnosticsResponse — Response type from `modbus-rs`.
+     */
+    diagnostics(opts: DiagnosticsOptions): Effect.Effect<DiagnosticsResponse, ModbusError>;
+    /**
+     * Reads device identification from the Modbus device (FC43 / MEI type 14).
+     *
+     * @param opts - Read device ID code, starting object ID, and optional `AbortSignal`.
+     * @returns An Effect resolving to a `DeviceIdentificationResponse` with conformity level and objects.
+     *
+     * @see ReadDeviceIdentificationOptions — Options shape from `modbus-rs`.
+     * @see DeviceIdentificationResponse — Response type from `modbus-rs`.
+     */
+    readDeviceIdentification(opts: ReadDeviceIdentificationOptions): Effect.Effect<DeviceIdentificationResponse, ModbusError>;
+}
+/**
+ * Wraps a raw `modbus-rs` client into an {@link EffectModbusClient}.
+ *
+ * Each method converts a Promise-based call from the upstream client
+ * into an `Effect` via {@link Effect.tryPromise}, routing errors through
+ * {@link toModbusError} for typed error discrimination.
+ *
+ * Accepts both serial (`AsyncSerialModbusClient`) and TCP
+ * (`AsyncTcpModbusClient`) clients since they share the same method
+ * signatures.
+ *
+ * @param client - The upstream `modbus-rs` client instance.
+ * @returns An `EffectModbusClient` that can be used within Effect
+ *          workflows.
+ *
+ * @see AsyncSerialModbusClient — Upstream serial client API.
+ * @see AsyncTcpModbusClient — Upstream TCP client API.
+ */
+export declare const makeEffectModbusClient: (client: AsyncSerialModbusClient | AsyncTcpModbusClient) => EffectModbusClient;

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

@@ -0,0 +1,64 @@
+import { Effect, Scope } from "effect";
+import { type ModbusError, ModbusNotConnectedError } from "./errors";
+import { type AnyModbusClient, type EffectModbusClient } from "./modbus-client";
+/**
+ * Shared API surface that every transport service exposes to consumers.
+ *
+ * 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.
+ */
+export interface TransportServiceApi {
+    /** Obtains (or creates) a cached {@link EffectModbusClient} for the given unit ID. */
+    withClient(unitId: number): Effect.Effect<EffectModbusClient, ModbusError>;
+    /** Sets a request timeout (ms) on the underlying transport. Fails if not connected. */
+    setRequestTimeout(timeoutMs: number): Effect.Effect<void, ModbusError>;
+    /** Clears the request timeout. Fails if not connected. */
+    clearRequestTimeout(): Effect.Effect<void, ModbusError>;
+    /** Reconnects the transport. Opens lazily if no prior connection exists. */
+    reconnect(): Effect.Effect<void, ModbusError>;
+    /** Closes the transport and its scope immediately. */
+    close(): Effect.Effect<void, ModbusError, Scope.Scope>;
+    /** Whether the transport currently has in-flight requests. */
+    hasPendingRequests(): boolean;
+}
+interface TransportHandle<TClient> {
+    close(): Promise<void>;
+    createClient(opts: {
+        unitId: number;
+    }): TClient;
+    setRequestTimeout(ms: number): void;
+    clearRequestTimeout(): void;
+    reconnect(): Promise<void>;
+    pendingRequests: boolean;
+}
+/**
+ * Generic factory for the scoped constructor body of an `Effect.Service`.
+ *
+ * Dynamically imports `modbus-rs`, opens the transport via `openMethod`,
+ * and returns a {@link TransportServiceApi} that manages connection
+ * lifecycle, client caching, timeouts, and reconnection.
+ *
+ * The transport is opened lazily on the first `withClient()` call and
+ * automatically closed when the consuming {@link Effect.Scope | Scope}
+ * finalizes via `Effect.addFinalizer`.
+ *
+ * @typeParam TOptions - Transport options (e.g. `RtuTransportOptions`).
+ * @typeParam TClient - The client type created by the transport.
+ * @typeParam TTransport - The transport handle type.
+ * @param transportKey - The named export from `modbus-rs` (e.g. `"AsyncRtuTransport"`).
+ * @param openMethod - A function that takes the transport constructor and options,
+ *   returning a promise for the opened transport.
+ * @param serviceName - Logical name used in log messages and the finalizer guard.
+ * @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): (options: TOptions) => Effect.Effect<{
+    withClient: (unitId: number) => Effect.Effect<EffectModbusClient, ModbusError, never>;
+    setRequestTimeout: (timeoutMs: number) => Effect.Effect<undefined, ModbusNotConnectedError, never>;
+    clearRequestTimeout: () => Effect.Effect<undefined, ModbusNotConnectedError, never>;
+    reconnect: () => Effect.Effect<undefined, ModbusError, never>;
+    close: () => Effect.Effect<void, ModbusError, Scope.Scope>;
+    hasPendingRequests: () => boolean;
+}, never, Scope.Scope>;
+export {};

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@flux-control/effect-modbus-rs",
+  "version": "0.1.0",
+  "description": "Type-safe Modbus communication via Effect-TS, wrapping the modbus-rs npm bindings.",
+  "license": "GPL-3.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/flux-control-solutions/Effect-modbus-rs.git"
+  },
+  "type": "module",
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "exports": {
+      "./package.json": "./package.json",
+      ".": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./index.ts",
+      "default": "./index.ts"
+    }
+  },
+  "scripts": {
+    "changeset": "changeset",
+    "test": "bun test ./src/ ./examples/",
+    "test:coverage": "bun test --coverage ./src/ ./examples/",
+    "typecheck": "tsc --noEmit",
+    "build": "rm -rf ./dist && bun build ./index.ts --outdir ./dist --target node --external effect --external modbus-rs && tsc --noEmit false --emitDeclarationOnly --outDir ./dist --rootDir . --project tsconfig.build.json",
+    "docs": "typedoc",
+    "release": "changeset publish",
+    "version": "changeset version"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.31.1",
+    "@effect/language-service": "^0.86.2",
+    "@effect/platform-bun": "^0.90.0",
+    "@types/bun": "latest",
+    "effect": "^3.21.4",
+    "fallow": "^2.103.0",
+    "typedoc": "^0.28.20",
+    "typescript": "^6.0.3"
+  },
+  "peerDependencies": {
+    "effect": "^3.21.4"
+  },
+  "dependencies": {
+    "modbus-rs": "^0.15.3"
+  }
+}