@lionweb/delta-protocol-client 0.7.0-beta.21

package/dist/priority-queue.js

@@ -0,0 +1,81 @@
+//
+// 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
+/**
+ * @return the index at which `t` should be inserted to keep the array `ts` sorted in the numeric order determined by applying `valueFunc` to its members.
+ * In case `t` has the same numeric value as existing members of `ts`, the lowest index having that numeric value is returned.
+ * (Exported for testing purposes only!)
+ */
+export const insertionIndex = (ts, valueFunc, tToInsert) => {
+    const valueToInsert = valueFunc(tToInsert);
+    let low = 0;
+    let high = ts.length - 1;
+    while (low <= high) {
+        const mid = low + ((high - low) >>> 1); // not buggy! ;D
+        const midValue = valueFunc(ts[mid]);
+        if (midValue < valueToInsert) {
+            low = mid + 1;
+        }
+        else if (valueToInsert < midValue) {
+            high = mid - 1;
+        }
+        else {
+            return mid;
+        }
+    }
+    return low;
+};
+/**
+ * @return a {@link PriorityQueueAcceptor} function that accepts instances of `T`,
+ * passing them to the `process` function in (min-max) priority order,
+ * as computed by the `priorityFunc`, starting with the `firstPriority`.
+ * @throws an {@link Error error} when a `T` is passed with a priority that has already been processed.
+ */
+export const priorityQueueAcceptor = (priorityFunc, firstPriority, process) => {
+    const ts = [];
+    let nextPriority = firstPriority;
+    return (t) => {
+        const priority = priorityFunc(t);
+        if (priority < nextPriority) {
+            throw new Error(`priority ${priority} has already been processed; (next expected priority: ${nextPriority})`);
+        }
+        const index0 = insertionIndex(ts, priorityFunc, t);
+        if (priority === nextPriority) {
+            nextPriority++;
+            process(t);
+            let index = index0;
+            let stop = false;
+            while (index < ts.length && !stop) {
+                const currentT = ts[index];
+                const currentPriority = priorityFunc(currentT);
+                if (currentPriority === nextPriority) {
+                    nextPriority++;
+                    process(currentT);
+                    index++;
+                }
+                else {
+                    stop = true;
+                }
+            }
+            if (index > index0) {
+                ts.splice(index0, index - index0);
+            }
+        }
+        else {
+            ts.splice(index0, 0, t);
+        }
+    };
+};
+//# sourceMappingURL=priority-queue.js.map

package/dist/priority-queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"priority-queue.js","sourceRoot":"","sources":["../src/priority-queue.ts"],"names":[],"mappings":"AAAA,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;AAKtC;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAI,EAAO,EAAE,SAA2B,EAAE,SAAY,EAAU,EAAE;IAC5F,MAAM,aAAa,GAAG,SAAS,CAAC,SAAS,CAAC,CAAA;IAC1C,IAAI,GAAG,GAAG,CAAC,CAAA;IACX,IAAI,IAAI,GAAG,EAAE,CAAC,MAAM,GAAG,CAAC,CAAA;IAExB,OAAO,GAAG,IAAI,IAAI,EAAE,CAAC;QACjB,MAAM,GAAG,GAAG,GAAG,GAAG,CAAC,CAAC,IAAI,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,CAAA,CAAE,gBAAgB;QACxD,MAAM,QAAQ,GAAG,SAAS,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAA;QAEnC,IAAI,QAAQ,GAAG,aAAa,EAAE,CAAC;YAC3B,GAAG,GAAG,GAAG,GAAG,CAAC,CAAA;QACjB,CAAC;aAAM,IAAI,aAAa,GAAG,QAAQ,EAAE,CAAC;YAClC,IAAI,GAAG,GAAG,GAAG,CAAC,CAAA;QAClB,CAAC;aAAM,CAAC;YACJ,OAAO,GAAG,CAAA;QACd,CAAC;IACL,CAAC;IAED,OAAO,GAAG,CAAA;AACd,CAAC,CAAA;AAWD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAI,YAA8B,EAAE,aAAqB,EAAE,OAAqB,EAA4B,EAAE;IAC/I,MAAM,EAAE,GAAQ,EAAE,CAAA;IAClB,IAAI,YAAY,GAAG,aAAa,CAAA;IAChC,OAAO,CAAC,CAAI,EAAE,EAAE;QACZ,MAAM,QAAQ,GAAG,YAAY,CAAC,CAAC,CAAC,CAAA;QAChC,IAAI,QAAQ,GAAG,YAAY,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CAAC,YAAY,QAAQ,yDAAyD,YAAY,GAAG,CAAC,CAAA;QACjH,CAAC;QACD,MAAM,MAAM,GAAG,cAAc,CAAC,EAAE,EAAE,YAAY,EAAE,CAAC,CAAC,CAAA;QAClD,IAAI,QAAQ,KAAK,YAAY,EAAE,CAAC;YAC5B,YAAY,EAAE,CAAA;YACd,OAAO,CAAC,CAAC,CAAC,CAAA;YACV,IAAI,KAAK,GAAG,MAAM,CAAA;YAClB,IAAI,IAAI,GAAG,KAAK,CAAA;YAChB,OAAO,KAAK,GAAG,EAAE,CAAC,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;gBAChC,MAAM,QAAQ,GAAG,EAAE,CAAC,KAAK,CAAC,CAAA;gBAC1B,MAAM,eAAe,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAA;gBAC9C,IAAI,eAAe,KAAK,YAAY,EAAE,CAAC;oBACnC,YAAY,EAAE,CAAA;oBACd,OAAO,CAAC,QAAQ,CAAC,CAAA;oBACjB,KAAK,EAAE,CAAA;gBACX,CAAC;qBAAM,CAAC;oBACJ,IAAI,GAAG,IAAI,CAAA;gBACf,CAAC;YACL,CAAC;YACD,IAAI,KAAK,GAAG,MAAM,EAAE,CAAC;gBACjB,EAAE,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,GAAG,MAAM,CAAC,CAAA;YACrC,CAAC;QACL,CAAC;aAAM,CAAC;YACJ,EAAE,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC,CAAA;QAC3B,CAAC;IACL,CAAC,CAAA;AACL,CAAC,CAAA"}

package/package.json

@@ -0,0 +1,37 @@
+{
+    "name": "@lionweb/delta-protocol-client",
+    "version": "0.7.0-beta.21",
+    "description": "Part of the implementation of a delta protocol client not tied to a specific message transport protocol",
+    "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/class-core": "0.7.0-beta.21",
+        "@lionweb/core": "0.7.0-beta.21",
+        "@lionweb/delta-protocol-common": "0.7.0-beta.21",
+        "@lionweb/delta-protocol-client": "0.7.0-beta.21",
+        "@lionweb/json": "0.7.0-beta.21",
+        "@lionweb/ts-utils": "0.7.0-beta.21"
+    }
+}

package/src/client.ts

@@ -0,0 +1,339 @@
+// 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 {
+    allNodesFrom,
+    applyDelta,
+    combinedFactoryFor,
+    DeltaReceiver,
+    IdMapping,
+    ILanguageBase,
+    INodeBase,
+    nodeBaseDeserializer,
+    NodeBaseFactory,
+    PartitionAddedDelta,
+    PartitionDeletedDelta,
+    serializeDelta
+} from "@lionweb/class-core"
+import { Concept } from "@lionweb/core"
+import { LionWebId, LionWebJsonChunk } from "@lionweb/json"
+import { byIdMap } from "@lionweb/ts-utils"
+
+import {
+    ansi,
+    ClientAppliedEvent,
+    ClientDidNotApplyEventFromOwnCommand,
+    ClientHadProblem,
+    ClientReceivedMessage,
+    ClientSentMessage,
+    Command,
+    deltaAsCommand,
+    DeltaOccurredOnClient,
+    Event,
+    eventToDeltaTranslator,
+    isEvent,
+    isQueryResponse,
+    QueryMessage,
+    ReconnectRequest,
+    ReconnectResponse,
+    SemanticLogger,
+    semanticLoggerFunctionFrom,
+    SignOffRequest,
+    SignOnRequest,
+    SignOnResponse,
+    SubscribeToChangingPartitionsRequest,
+    SubscribeToPartitionChangesParameters,
+    SubscribeToPartitionContentsRequest,
+    SubscribeToPartitionContentsResponse,
+    UnsubscribeFromPartitionContentsRequest
+} from "@lionweb/delta-protocol-common"
+import { LowLevelClient, LowLevelClientInstantiator } from "./low-level-client.js"
+import { priorityQueueAcceptor } from "./priority-queue.js"
+
+const { clientWarning } = ansi
+
+
+/**
+ * Type def. for parameters – required and optional – for instantiating a {@link LionWebClient LionWeb delta protocol client}.
+ */
+export type LionWebClientParameters = {
+    clientId: LionWebId
+    url: string
+    languageBases: ILanguageBase[]
+    lowLevelClientInstantiator: LowLevelClientInstantiator<Event | QueryMessage, Command | QueryMessage>
+    serializationChunk?: LionWebJsonChunk
+    instantiateDeltaReceiverForwardingTo?: (commandSender: DeltaReceiver) => DeltaReceiver
+    semanticLogger?: SemanticLogger
+}
+
+
+/**
+ * Implementation of a LionWeb delta protocol client.
+ */
+export class LionWebClient {
+
+    private _participationId?: LionWebId // !== undefined => signed on
+
+    get participationId() {
+        return this._participationId
+    }
+
+    private signedOff = false
+
+    private lastReceivedSequenceNumber = -1
+    // TODO  could also get this from the priority queue (which would need to be adapted for that)
+
+    private constructor(
+        public readonly clientId: LionWebId,
+        public model: INodeBase[],
+        public readonly idMapping: IdMapping,
+        public readonly createNode: NodeBaseFactory,
+        private readonly effectiveReceiveDelta: DeltaReceiver,
+        private readonly lowLevelClient: LowLevelClient<Command | QueryMessage>
+    ) {}
+
+    private readonly queryResolveById: { [queryId: string]: (value: QueryMessage) => void } = {}
+
+    private static readonly nodesByIdFrom = (model: INodeBase[]) =>
+        byIdMap(model.flatMap(allNodesFrom))
+
+    static async create({clientId, url, languageBases, instantiateDeltaReceiverForwardingTo, serializationChunk, semanticLogger, lowLevelClientInstantiator}: LionWebClientParameters): Promise<LionWebClient> {
+        const log = semanticLoggerFunctionFrom(semanticLogger)
+
+        let loading = true
+        let commandNumber = 0
+        const issuedCommandIds: string[] = []
+        const commandSender: DeltaReceiver = (delta) => {
+            try {
+                const serializedDelta = serializeDelta(delta)
+                log(new DeltaOccurredOnClient(clientId, serializedDelta))
+                if (!loading) {
+                    const commandId = `cmd-${++commandNumber}`
+                    const command = deltaAsCommand(delta, commandId)
+                    if (command !== undefined) {
+                        issuedCommandIds.push(commandId)  // (register the ID before actually sending the command so that effectively-synchronous tests mimic the actual behavior more reliably)
+                        lowLevelClient.sendMessage(command)
+                        log(new ClientSentMessage(clientId, command))
+                    }
+                }
+            } catch (e: unknown) {
+                console.error(`error occurred during serialization of delta: ${(e as Error).message}`)
+                console.dir(delta)
+            }
+        }
+        const effectiveReceiveDelta = instantiateDeltaReceiverForwardingTo === undefined ? commandSender : instantiateDeltaReceiverForwardingTo(commandSender)
+
+        const deserialized = nodeBaseDeserializer(languageBases, effectiveReceiveDelta)
+        const model = serializationChunk === undefined ? [] : deserialized(serializationChunk)
+        const idMapping = new IdMapping(LionWebClient.nodesByIdFrom(model))
+        const eventAsDelta = eventToDeltaTranslator(languageBases, deserialized)
+        loading = false
+
+        const processEvent = (event: Event) => {
+            lionWebClient.lastReceivedSequenceNumber = event.sequenceNumber
+            const commandOriginatingFromSelf = event.originCommands.find(({ commandId }) => issuedCommandIds.indexOf(commandId) > -1)
+            // Note: we can't remove members from issuedCommandIds because there may be multiple events originating fom a single command.
+            if (commandOriginatingFromSelf === undefined) {
+                try {
+                    const delta = eventAsDelta(event, idMapping)
+                    if (delta !== undefined) {
+                        try {
+                            applyDelta(delta)
+                            log(new ClientAppliedEvent(clientId, event))
+                        } catch (e) {
+                            log(new ClientHadProblem(clientId, `couldn't apply delta of type ${delta.constructor.name} because of: ${(e as Error).message}`))
+                        }
+                    }
+                } catch (eventTranslationError) {
+                    log(new ClientHadProblem(clientId, `couldn't translate event to a delta because of: ${(eventTranslationError as Error).message}\n\tdelta = ${JSON.stringify(event)}`))
+                }
+            } else {
+                log(new ClientDidNotApplyEventFromOwnCommand(clientId, commandOriginatingFromSelf.commandId))
+            }
+        }
+
+        const acceptEvent = priorityQueueAcceptor<Event>(({sequenceNumber}) => sequenceNumber, 0, processEvent)
+
+        const receiveMessageOnClient = (message: Event | QueryMessage) => {
+            log(new ClientReceivedMessage(clientId, message))
+            if (isQueryResponse(message)) {
+                const { queryId } = message
+                if (queryId in lionWebClient.queryResolveById) {
+                    const resolveResponse = lionWebClient.queryResolveById[queryId]
+                    resolveResponse(message)
+                    delete lionWebClient.queryResolveById[queryId]
+                    return  // ~void
+                }
+                console.log(clientWarning(`client received response for a query with ID="${queryId} without having sent a corresponding request - ignoring`))
+                return
+            }
+            if (isEvent(message)) {
+                acceptEvent(message)
+                return
+            }
+        }
+
+        const lowLevelClient = await
+            lowLevelClientInstantiator({ url, clientId, receiveMessageOnClient /* no logging parameter */ })
+
+        const lionWebClient = new LionWebClient(
+            clientId,
+            model,
+            idMapping,
+            combinedFactoryFor(languageBases, effectiveReceiveDelta),
+            effectiveReceiveDelta,
+            lowLevelClient
+        ) // Note: we need this `lionWebClient` constant non-inlined for write-access to lastReceivedSequenceNumber and queryResolveById.
+        return lionWebClient
+    }
+
+    /**
+     * Sets the model held by the client to the given model, discarding the previous one.
+     * No commands will be sent because of this action.
+     */
+    setModel(newModel: INodeBase[]) {
+        this.model = newModel
+        this.idMapping.reinitializeWith(LionWebClient.nodesByIdFrom(newModel))
+    }
+
+    async disconnect(): Promise<void> {
+        // TODO  abort responses to all queries that the repository hasn't responded to?
+        await this.lowLevelClient.disconnect()
+    }
+
+
+    // queries, in order of the specification (§ 6.3):
+
+    /**
+     * Makes the query in the sense that the given query request is sent (as a client message),
+     * and that the `resolve` callback of the associated `Promise` is stored so the promise can be resolved,
+     * so that query call can be `await`ed.
+     */
+    private readonly makeQuery = (queryRequest: QueryMessage): Promise<QueryMessage> =>
+        new Promise((resolveResponse, rejectResponse) => {
+            this.queryResolveById[queryRequest.queryId] = resolveResponse
+            this.lowLevelClient.sendMessage(queryRequest)
+                .catch(rejectResponse)
+        })
+
+    async subscribeToChangingPartitions(queryId: LionWebId, parameters: SubscribeToPartitionChangesParameters): Promise<void> {
+        await this.makeQuery({
+            messageKind: "SubscribeToChangingPartitionsRequest",
+            queryId,
+            ...parameters,
+            protocolMessages: []
+        } as SubscribeToChangingPartitionsRequest)
+    }
+
+    async subscribeToPartitionContents(queryId: LionWebId, partition: LionWebId): Promise<LionWebJsonChunk> {   // TODO  already deserialize, because we've got everything we need
+        const response = await this.makeQuery({
+            messageKind: "SubscribeToPartitionContentsRequest",
+            queryId,
+            partition,
+            protocolMessages: []
+        } as SubscribeToPartitionContentsRequest) as SubscribeToPartitionContentsResponse
+        return response.contents
+    }
+
+    async unsubscribeFromPartitionContents(queryId: LionWebId, partition: LionWebId): Promise<void> {
+        await this.makeQuery({
+            messageKind: "UnsubscribeFromPartitionContentsRequest",
+            queryId,
+            partition,
+            protocolMessages: []
+        } as UnsubscribeFromPartitionContentsRequest)
+    }
+
+    async signOn(queryId: LionWebId, repositoryId: LionWebId): Promise<void> {
+        if (this.signedOff) {
+            return Promise.reject(new Error(`can't sign on after having signed off`))
+        }
+        const response = await this.makeQuery({
+            messageKind: "SignOnRequest",
+            queryId,
+            repositoryId,
+            deltaProtocolVersion: "2025.1",
+            clientId: this.clientId,
+            protocolMessages: []
+        } as SignOnRequest) as SignOnResponse
+        this._participationId = response.participationId
+    }
+
+    async signOff(queryId: LionWebId): Promise<void> {
+        await this.makeQuery({
+            messageKind: "SignOffRequest",
+            queryId,
+            protocolMessages: []
+        } as SignOffRequest)
+        this.signedOff = true
+        this._participationId = undefined
+    }
+
+    async reconnect(queryId: LionWebId, participationId: LionWebId, lastReceivedSequenceNumber: number): Promise<void> {
+        const response = await this.makeQuery({
+            messageKind: "ReconnectRequest",
+            queryId,
+            participationId,
+            lastReceivedSequenceNumber,
+            protocolMessages: []
+        } as ReconnectRequest) as ReconnectResponse
+        this._participationId = participationId
+        this.lastReceivedSequenceNumber = response.lastReceivedSequenceNumber
+    }
+
+
+    // commands, in order of the specification (§ 6.5):
+
+    private static checkWhetherPartition(node: INodeBase): void {
+        const {classifier} = node
+        if (!(classifier instanceof Concept)) {
+            throw new Error(`node with classifier ${classifier.name} from language ${classifier.language.name} is not an instance of a Concept`)
+        }
+        if (!classifier.partition) {
+            throw new Error(`classifier ${classifier.name} from language ${classifier.language.name} is not a partition`)
+        }
+    }
+
+    private checkSignedOn(): void {
+        if (this._participationId === undefined) {
+            throw new Error(`client ${this.clientId} can't send a command without being signed on`)
+        }
+    }
+
+    addPartition(partition: INodeBase): void {
+        this.checkSignedOn()
+        LionWebClient.checkWhetherPartition(partition)
+        if (this.model.indexOf(partition) === -1) {
+            this.model.push(partition)
+            this.idMapping.updateWith(partition)
+            this.effectiveReceiveDelta(new PartitionAddedDelta(partition))
+        } // else: ignore; already done
+    }
+
+    deletePartition(partition: INodeBase): void {
+        this.checkSignedOn()
+        const index = this.model.indexOf(partition)
+        if (index > -1) {
+            this.model.splice(index, 1)
+            this.effectiveReceiveDelta(new PartitionDeletedDelta(partition))
+        } else {
+            throw new Error(`node with id "${partition.id}" is not a partition in the current model`)
+        }
+    }
+
+}
+

package/src/index.ts

@@ -0,0 +1,25 @@
+// 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 { LionWebClient } from "./client.js"
+export type { LionWebClientParameters } from "./client.js"
+
+export { noOpLowLevelClientLogger } from "./log-types.js"
+export type { MessageReceivedOnClient, MessageSentToServer, TextualLogItem, LowLevelClientLogItem, LowLevelClientLogger } from "./log-types.js"
+
+export type { LowLevelClient, LowLevelClientInstantiator, LowLevelClientLoggingParameters, LowLevelClientParameters } from "./low-level-client.js"
+

package/src/log-types.ts

@@ -0,0 +1,48 @@
+// 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 type MessageReceivedOnClient<TMessageForClient> = {
+    receivedOnClient: TMessageForClient
+}
+
+export type MessageSentToServer<TMessageForServer> = {
+    sentToServer: TMessageForServer
+}
+
+export type TextualLogItem = {
+    message: string
+    error?: boolean
+}
+
+/**
+ * Type def. for activity logged by a low-level client.
+ */
+export type LowLevelClientLogItem<TMessageForClient, TMessageForServer> =
+    | TextualLogItem
+    | MessageReceivedOnClient<TMessageForClient>
+    | MessageSentToServer<TMessageForServer>
+
+
+export type LowLevelClientLogger<TMessageForClient, TMessageForServer> =
+    (logItem: LowLevelClientLogItem<TMessageForClient, TMessageForServer>) => void
+
+
+/**
+ * Implementation of {@link LowLevelClientLogger} that does nothing.
+ */
+export const noOpLowLevelClientLogger: LowLevelClientLogger<unknown, unknown> = (_logItem) => {}
+

package/src/low-level-client.ts

@@ -0,0 +1,61 @@
+// 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 { LionWebId } from "@lionweb/json"
+import { TextualLogger } from "@lionweb/delta-protocol-common"
+
+
+/**
+ * Type def. for a client that's able to send messages.
+ */
+export type LowLevelClient<TMessageToServer> = {
+    sendMessage: (message: TMessageToServer) => Promise<void>
+    disconnect: () => Promise<void>
+}
+
+/**
+ * Type def. for parameters *required* for instantiating a {@link LowLevelClient low-level client}.
+ */
+export type LowLevelClientParameters<TMessageForClient> = {
+    /** The URL of the WebSocket server to connect to. */
+    url: string
+    /** An ID for the created client. */
+    clientId: LionWebId
+    /** A function that's called with a received message. */
+    receiveMessageOnClient: (message: TMessageForClient) => void
+    /** An optional {@link TextualLogger textual logger}. */
+}
+
+/**
+ * Type def. for optional parameters for a {@link LowLevelClient low-level client} regarding logging.
+ */
+export type LowLevelClientLoggingParameters<TMessageForClient, TMessageToServer> = {
+    /** An optional {@link TextualLogger textual logger}. */
+    textualLogger?: TextualLogger
+    /** An optional message logger. */
+    messageLogger?: (message: (TMessageForClient | TMessageToServer)) => void
+}
+
+/**
+ * Type def. for functions that instantiate a {@link LowLevelClient}.
+ *
+ * Note that the instantiator implementation is responsible for passing logging parameters.
+ */
+export type LowLevelClientInstantiator<TMessageForClient, TMessageToServer> =
+    (lowLevelClientParameters: LowLevelClientParameters<TMessageForClient>) =>
+        Promise<LowLevelClient<TMessageToServer>>
+