@lionweb/delta-protocol-low-level-client-ws 0.7.0-beta.21

package/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## 0.7.0
+
+Initial creation and publication of this package.
+

package/README.md

@@ -0,0 +1,22 @@
+# The `delta-protocol-low-level-client-ws` package
+
+[![license](https://img.shields.io/badge/License-Apache%202.0-green.svg?style=flat)
+](./LICENSE)
+
+An NPM package that can be added to a Node.js/NPM codebase as follows:
+
+```shell
+$ npm add @lionweb/delta-protocol-low-level-client-ws
+```
+
+***TODO***
+
+
+## Development
+
+Build this package from source as follows:
+
+```shell
+npm run build
+```
+

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { createWSLowLevelClient } from "./low-level-client.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAA"}

package/dist/index.js

@@ -0,0 +1,18 @@
+// Copyright 2025 TRUMPF Laser SE and other contributors
+//
+// Licensed under the Apache License, Version 2.0 (the "License")
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// SPDX-FileCopyrightText: 2025 TRUMPF Laser SE and other contributors
+// SPDX-License-Identifier: Apache-2.0
+export { createWSLowLevelClient } from "./low-level-client.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,wDAAwD;AACxD,EAAE;AACF,iEAAiE;AACjE,mEAAmE;AACnE,0CAA0C;AAC1C,EAAE;AACF,iDAAiD;AACjD,EAAE;AACF,sEAAsE;AACtE,oEAAoE;AACpE,2EAA2E;AAC3E,sEAAsE;AACtE,iCAAiC;AACjC,EAAE;AACF,sEAAsE;AACtE,sCAAsC;AAEtC,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAA"}

package/dist/low-level-client.d.ts

@@ -0,0 +1,10 @@
+import { LowLevelClient, LowLevelClientLogger, LowLevelClientParameters } from "@lionweb/delta-protocol-client";
+/**
+ * @return a WebSocket-driven implementation of a {@link LowLevelClient low-level client},
+ *  based on the `ws` package,
+ *  as a {@link Promise} that resolves as soon the client was able to connect to the WebSocket server.
+ * @param lowLevelClientParameters Parameters required to create/instantiate the low-level client.
+ * @param optionalLoggingParameters Optional parameters regarding logging.
+ */
+export declare const createWSLowLevelClient: <TMessageForClient, TMessageToServer>({ url, clientId, receiveMessageOnClient }: LowLevelClientParameters<TMessageForClient>, optionalLogger?: LowLevelClientLogger<TMessageForClient, TMessageToServer>) => Promise<LowLevelClient<TMessageToServer>>;
+//# sourceMappingURL=low-level-client.d.ts.map

package/dist/low-level-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"low-level-client.d.ts","sourceRoot":"","sources":["../src/low-level-client.ts"],"names":[],"mappings":"AAiBA,OAAO,EACH,cAAc,EACd,oBAAoB,EACpB,wBAAwB,EAE3B,MAAM,gCAAgC,CAAA;AAQvC;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,GAAU,iBAAiB,EAAE,gBAAgB,EAC5E,2CAA2C,wBAAwB,CAAC,iBAAiB,CAAC,EACtF,iBAAiB,oBAAoB,CAAC,iBAAiB,EAAE,gBAAgB,CAAC,KAC3E,OAAO,CAAC,cAAc,CAAC,gBAAgB,CAAC,CAuD1C,CAAA"}

package/dist/low-level-client.js

@@ -0,0 +1,90 @@
+// Copyright 2025 TRUMPF Laser SE and other contributors
+//
+// Licensed under the Apache License, Version 2.0 (the "License")
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// SPDX-FileCopyrightText: 2025 TRUMPF Laser SE and other contributors
+// SPDX-License-Identifier: Apache-2.0
+import { noOpLowLevelClientLogger } from "@lionweb/delta-protocol-client";
+import { tryParseJson, wrappedAsPromise } from "@lionweb/delta-protocol-common";
+import { asMinimalJsonString } from "@lionweb/ts-utils";
+import { WebSocket } from "ws";
+/**
+ * @return a WebSocket-driven implementation of a {@link LowLevelClient low-level client},
+ *  based on the `ws` package,
+ *  as a {@link Promise} that resolves as soon the client was able to connect to the WebSocket server.
+ * @param lowLevelClientParameters Parameters required to create/instantiate the low-level client.
+ * @param optionalLoggingParameters Optional parameters regarding logging.
+ */
+export const createWSLowLevelClient = async ({ url, clientId, receiveMessageOnClient }, optionalLogger) => {
+    const webSocket = new WebSocket(url);
+    const log = optionalLogger ?? noOpLowLevelClientLogger;
+    log({ message: `client ${clientId} started` });
+    let state = "connecting";
+    return new Promise((resolveClientStart, rejectClientStart) => {
+        const lowLevelWebSocketClient = {
+            sendMessage: (message) => {
+                if (state === "connected") {
+                    log({ sentToServer: message });
+                    return wrappedAsPromise((callback) => {
+                        webSocket.send(asMinimalJsonString(message), callback);
+                    });
+                }
+                else {
+                    const messageText = `can't send message to server when client's state=${state}`;
+                    log({ message: messageText });
+                    return Promise.reject(new Error(messageText));
+                }
+            },
+            disconnect: () => new Promise((resolveDisconnect, rejectDisconnect) => {
+                if (state === "connected") {
+                    webSocket.close();
+                    state = "disconnected";
+                    resolveDisconnect();
+                }
+                rejectDisconnect(new Error(state));
+            })
+        };
+        webSocket
+            .on("open", () => {
+            state = "connected";
+            log({ message: `connected to server` });
+            resolveClientStart(lowLevelWebSocketClient);
+        })
+            .on("message", (messageText) => {
+            const message = tryParseJson(messageText, (message) => log({ message }));
+            log({ receivedOnClient: message });
+            receiveMessageOnClient(message);
+        })
+            .on("error", (error) => {
+            log({ message: `error occurred: ${error}`, error: true });
+            if (isConnectionRefusedError(firstRealError(error))) {
+                if (state === "connecting") {
+                    rejectClientStart(new Error(`could not connect to WebSocket server at ${url}`));
+                }
+                else {
+                    // ignore
+                    // TODO  is that OK?
+                }
+            }
+        })
+            .on("close", () => {
+            state = "disconnected";
+            log({ message: `disconnected from server` });
+        });
+    });
+};
+const firstRealError = (error) => error instanceof AggregateError ? firstRealError(error.errors[0]) : error;
+const isConnectionRefusedError = (error) => 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+error.code === "ECONNREFUSED";
+//# sourceMappingURL=low-level-client.js.map

package/dist/low-level-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"low-level-client.js","sourceRoot":"","sources":["../src/low-level-client.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,38 @@
+{
+    "name": "@lionweb/delta-protocol-low-level-client-ws",
+    "version": "0.7.0-beta.21",
+    "description": "Implementation of a low-level client for a delta protocol client using the WebSocket protocol, relying on the 'ws' package",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "typings": "dist/index.d.ts",
+    "type": "module",
+    "license": "Apache-2.0",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/LionWeb-io/lionweb-typescript.git"
+    },
+    "bugs": {
+        "url": "https://github.com/LionWeb-io/lionweb-typescript/issues"
+    },
+    "scripts": {
+        "clean": "npx rimraf dist node_modules",
+        "build": "tsc",
+        "lint": "eslint src",
+        "prep:pre-release": "npm run clean && npm install && npm run build",
+        "prerelease-alpha": "npm run prep:pre-release",
+        "release-alpha": "npm publish --tag alpha",
+        "prerelease-beta": "npm run prep:pre-release",
+        "release-beta": "npm publish --tag beta",
+        "prerelease": "npm run prep:pre-release",
+        "release": "npm publish"
+    },
+    "dependencies": {
+        "@lionweb/delta-protocol-common": "0.7.0-beta.21",
+        "@lionweb/delta-protocol-client": "0.7.0-beta.21",
+        "@lionweb/ts-utils": "0.7.0-beta.21",
+        "ws": "8.18.2"
+    },
+    "devDependencies": {
+        "@types/ws": "8.18.1"
+    }
+}

package/src/index.ts

@@ -0,0 +1,19 @@
+// Copyright 2025 TRUMPF Laser SE and other contributors
+//
+// Licensed under the Apache License, Version 2.0 (the "License")
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// SPDX-FileCopyrightText: 2025 TRUMPF Laser SE and other contributors
+// SPDX-License-Identifier: Apache-2.0
+
+export { createWSLowLevelClient } from "./low-level-client.js"
+

package/src/low-level-client.ts

@@ -0,0 +1,104 @@
+// Copyright 2025 TRUMPF Laser SE and other contributors
+//
+// Licensed under the Apache License, Version 2.0 (the "License")
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// SPDX-FileCopyrightText: 2025 TRUMPF Laser SE and other contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import {
+    LowLevelClient,
+    LowLevelClientLogger,
+    LowLevelClientParameters,
+    noOpLowLevelClientLogger
+} from "@lionweb/delta-protocol-client"
+import { tryParseJson, wrappedAsPromise } from "@lionweb/delta-protocol-common"
+import { asMinimalJsonString } from "@lionweb/ts-utils"
+import { WebSocket } from "ws"
+
+
+type ClientState = "connecting" | "connected" | "disconnected"
+
+/**
+ * @return a WebSocket-driven implementation of a {@link LowLevelClient low-level client},
+ *  based on the `ws` package,
+ *  as a {@link Promise} that resolves as soon the client was able to connect to the WebSocket server.
+ * @param lowLevelClientParameters Parameters required to create/instantiate the low-level client.
+ * @param optionalLoggingParameters Optional parameters regarding logging.
+ */
+export const createWSLowLevelClient = async <TMessageForClient, TMessageToServer>(
+    { url, clientId, receiveMessageOnClient }: LowLevelClientParameters<TMessageForClient>,
+    optionalLogger?: LowLevelClientLogger<TMessageForClient, TMessageToServer>
+): Promise<LowLevelClient<TMessageToServer>> => {
+    const webSocket = new WebSocket(url)
+    const log = optionalLogger ?? noOpLowLevelClientLogger
+    log({ message: `client ${clientId} started` })
+    let state: ClientState = "connecting"
+    return new Promise((resolveClientStart, rejectClientStart) => {
+        const lowLevelWebSocketClient: LowLevelClient<TMessageToServer> = {
+            sendMessage: (message) => {
+                if (state === "connected") {
+                    log({ sentToServer: message })
+                    return wrappedAsPromise((callback) => {
+                        webSocket.send(asMinimalJsonString(message), callback)
+                    })
+                } else {
+                    const messageText = `can't send message to server when client's state=${state}`
+                    log({ message: messageText })
+                    return Promise.reject(new Error(messageText))
+                }
+            },
+            disconnect: () => new Promise((resolveDisconnect, rejectDisconnect) => {
+                if (state === "connected") {
+                    webSocket.close()
+                    state = "disconnected"
+                    resolveDisconnect()
+                }
+                rejectDisconnect(new Error(state))
+            })
+        }
+        webSocket
+            .on("open", () => {
+                state = "connected"
+                log({ message: `connected to server` })
+                resolveClientStart(lowLevelWebSocketClient)
+            })
+            .on("message", (messageText: string) => {
+                const message = tryParseJson(messageText, (message) => log({ message })) as TMessageForClient
+                log({ receivedOnClient: message })
+                receiveMessageOnClient(message)
+            })
+            .on("error", (error) => {
+                log({ message: `error occurred: ${error}`, error: true })
+                if (isConnectionRefusedError(firstRealError(error))) {
+                    if (state === "connecting") {
+                        rejectClientStart(new Error(`could not connect to WebSocket server at ${url}`))
+                    } else {
+                        // ignore
+                        // TODO  is that OK?
+                    }
+                }
+            })
+            .on("close", () => {
+                state = "disconnected"
+                log({ message: `disconnected from server` })
+            })
+    })
+}
+
+const firstRealError = (error: Error): Error =>
+    error instanceof AggregateError ? firstRealError(error.errors[0]) : error
+
+const isConnectionRefusedError = (error: Error) =>
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (error as any).code === "ECONNREFUSED"
+