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

package/src/logging/ansi.ts

@@ -0,0 +1,63 @@
+// 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
+
+const colors = {
+    black: 30,
+    red: 31,
+    green: 32,
+    yellow: 33,
+    blue: 34,
+    magenta: 35,
+    cyan: 36,
+    white: 37,
+    default: 39
+} as const
+
+const styles = {
+    default: 0,
+    bold: 1,
+    italic: 3
+} as const
+
+
+const withColorAndStyleApplied = (color: keyof typeof colors, style: keyof typeof styles) =>
+    (text: string) =>
+        `\x1b[${style === "default" ? "" : `${styles[style]}`}${color === "default" ? "" : `;${colors[color]}m`}${text}\x1b[0m`
+
+
+const clientInfo = withColorAndStyleApplied("magenta", "bold")
+const clientWarning = withColorAndStyleApplied("magenta", "italic")
+const repositoryInfo = withColorAndStyleApplied("cyan", "bold")
+const repositoryWarning = withColorAndStyleApplied("cyan", "italic")
+const genericError = withColorAndStyleApplied("red", "bold")
+const genericWarning = withColorAndStyleApplied("red", "italic")
+
+const colorSchemeExplanationString = `${withColorAndStyleApplied("magenta", "default")("magenta=client")}, ${withColorAndStyleApplied("cyan", "default")("cyan=repository")}`
+
+export const ansi = {
+    colors,
+    styles,
+    withColorAndStyleApplied,
+    clientInfo,
+    clientWarning,
+    repositoryInfo,
+    repositoryWarning,
+    genericError,
+    genericWarning,
+    colorSchemeExplanationString
+}
+

package/src/logging/index.ts

@@ -0,0 +1,21 @@
+// 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 { ansi } from "./ansi.js"
+export * from "./semantic-logging.js"
+export * from "./textual-logging.js"
+

package/src/logging/semantic-logging.ts

@@ -0,0 +1,96 @@
+// 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 { SerializedDelta } from "@lionweb/class-core"
+import { LionWebId } from "@lionweb/json"
+import { asMinimalJsonString } from "@lionweb/ts-utils"
+
+import { ansi } from "./ansi.js"
+const { clientInfo, clientWarning, repositoryInfo, withColorAndStyleApplied } = ansi
+
+import { Event } from "../payload/event-types.js"
+
+
+export interface ISemanticLogItem {
+    asText(): string
+}
+
+
+export type SemanticLogger = (semanticLogItem: ISemanticLogItem) => void
+
+export const semanticNoOpLogger: SemanticLogger = (_) => {}
+
+export const semanticLoggerFunctionFrom = (optionalSemanticLogger?: SemanticLogger) =>
+    optionalSemanticLogger ?? semanticNoOpLogger
+
+export const semanticConsoleLogger = (semanticLogItem: ISemanticLogItem) => {
+    console.log(semanticLogItem.asText())
+}
+
+
+export class DeltaOccurredOnClient implements ISemanticLogItem {
+    constructor(public readonly clientId: LionWebId, public readonly serializedDelta: SerializedDelta) {}
+    asText = () => `${clientInfo(`delta occurred on client "${this.clientId}"`)}: ${asMinimalJsonString(this.serializedDelta)}`
+}
+
+export class ClientSentMessage<TMessageForRepository> implements ISemanticLogItem {
+    constructor(public readonly clientId: LionWebId, public readonly message: TMessageForRepository) {}
+    asText = () => `${clientInfo(`client "${this.clientId}" sent message`)}: ${asMinimalJsonString(this.message)}`
+}
+
+export class ClientReceivedMessage<TMessageForClient> implements ISemanticLogItem {
+    constructor(public readonly clientId: LionWebId, public readonly message: TMessageForClient) {}
+    asText = () => `${clientInfo(`client "${this.clientId}" received message`)}: ${asMinimalJsonString(this.message)}`
+}
+
+export class ClientAppliedEvent implements ISemanticLogItem {
+    constructor(public readonly clientId: LionWebId, public readonly event: Event) {}
+    asText = () => `${clientInfo(`client "${this.clientId}" applied (the delta from) the following event`)}: ${asMinimalJsonString(this.event)}`
+}
+
+export class ClientDidNotApplyEventFromOwnCommand implements ISemanticLogItem {
+    constructor(public readonly clientId: LionWebId, public readonly originatingCommandId: LionWebId) {}
+    asText = () => clientWarning(`client "${this.clientId}" didn't apply (the delta from) an event because it's the result of a command (with ID="${this.originatingCommandId}") it sent itself`)
+}
+
+export class ClientHadProblem implements ISemanticLogItem {
+    constructor(public readonly clientId: LionWebId, public readonly message: string) {}
+    asText = () => clientWarning(`client "${this.clientId}" had a problem: ${this.message}`)
+}
+
+export class RepositoryReceivedMessage<TClientMetadata, TIncomingMessage> implements ISemanticLogItem {
+    constructor(public readonly knownMetadata: Partial<TClientMetadata>, public readonly message: TIncomingMessage) {}
+    asText = () => `${repositoryInfo(`repository received message`)} ${withColorAndStyleApplied("magenta", "default")(`(client's known metadata: ${asMinimalJsonString(this.knownMetadata)})`)}: ${asMinimalJsonString(this.message)}`
+}
+
+
+export const semanticLogItemsToConsole = (semanticLogItems: ISemanticLogItem[]) => {
+    semanticLogItems.forEach((logItem) => {
+        console.log(logItem.asText())
+    })
+}
+
+export const semanticLogItemStorer = (): [semanticLogger: SemanticLogger, semanticLogItems: ISemanticLogItem[]] => {
+    const items: ISemanticLogItem[] = []
+    return [
+        (semanticLogItem) => {
+            items.push(semanticLogItem)
+        },
+        items
+    ]
+}
+

package/src/logging/textual-logging.ts

@@ -0,0 +1,65 @@
+// 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 TextualLogger = (message: string, error?: boolean) => void
+
+/**
+ * A {@link TextualLogger textual logger} that simply logs to the console.
+ */
+export const simpleConsoleLogger: TextualLogger = (message, isError) => {
+    (isError ? console.error : console.log)(message)
+}
+
+/**
+ * A {@link TextualLogger textual logger} that does nothing.
+ */
+export const noOpTextualLogger: TextualLogger = (_, __) => {}
+
+/**
+ * @return a {@link TextualLogger textual logger} which is either the given one, or the noOpTextualLogger.
+ */
+export const textualLoggerFunctionFrom = (optionalLogger?: TextualLogger): TextualLogger =>
+    optionalLogger ?? noOpTextualLogger
+
+/**
+ * Prefixes all messages passed to the given {@link TextualLogger textual logger} with the given prefix.
+ */
+export const prefixedWith = (logger: TextualLogger, prefix: string): TextualLogger =>
+    (message, error) => logger(`${prefix}${message}`, error)
+
+
+const unit2divider: { [id: string]: bigint } = {
+    "ns": 1n,
+    "µs": 1000n,
+    "ms": 1000_000n,
+    "s": 1000_000_000n
+} as const
+
+/**
+ * A {@link TextualLogger textual logger} that logs to the console, also showing the time elapsed since the creation of it.
+ */
+export const timedConsoleLogger = (unit: "ns" | "µs" | "ms" | "s"): TextualLogger => {
+    if (!(unit in unit2divider)) {
+        throw new Error(`unknown time unit: "${unit}"`)
+    }
+    const divider = unit2divider[unit]
+    const start = process.hrtime.bigint()
+    return (message, isError) => {
+        (isError ? console.error : console.log)(`{${((process.hrtime.bigint() - start)/divider).toLocaleString()}${unit}} ${message}`)
+    }
+}
+

package/src/payload/command-types.ts

@@ -0,0 +1,378 @@
+// 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, LionWebJsonChunk, LionWebJsonMetaPointer } from "@lionweb/json"
+import { DeltaProtocolMessage } from "./common.js"
+
+export interface Command extends DeltaProtocolMessage {
+    commandId: LionWebId
+}
+
+
+// in order of the specification (§ 6.5):
+
+/** § 6.5.2.1 */
+export interface AddPartitionCommand extends Command {
+    messageKind: "AddPartition"
+    newPartition: LionWebJsonChunk
+}
+
+/** § 6.5.2.2 */
+export interface DeletePartitionCommand extends Command {
+    messageKind: "DeletePartition"
+    deletedPartition: LionWebId
+}
+
+/** § 6.5.3.1 */
+export interface ChangeClassifierCommand extends Command {
+    messageKind: "ChangeClassifier"
+    node: LionWebId
+    newClassifier: LionWebJsonMetaPointer
+}
+
+/** § 6.5.4.1 */
+export interface AddPropertyCommand<T> extends Command {
+    messageKind: "AddProperty"
+    node: LionWebId
+    property: LionWebJsonMetaPointer
+    newValue: T
+}
+
+/** § 6.5.4.2 */
+export interface DeletePropertyCommand extends Command {
+    messageKind: "DeleteProperty"
+    node: LionWebId
+    property: LionWebJsonMetaPointer
+}
+
+/** § 6.5.4.3 */
+export interface ChangePropertyCommand<T> extends Command {
+    messageKind: "ChangeProperty"
+    node: LionWebId
+    property: LionWebJsonMetaPointer
+    newValue: T
+}
+
+/** § 6.5.5.1 */
+export interface AddChildCommand extends Command {
+    messageKind: "AddChild"
+    parent: LionWebId
+    newChild: LionWebJsonChunk
+    containment: LionWebJsonMetaPointer
+    index: number
+}
+
+/** § 6.5.5.2 */
+export interface DeleteChildCommand extends Command {
+    messageKind: "DeleteChild"
+    parent: LionWebId
+    containment: LionWebJsonMetaPointer
+    index: number
+    deletedChild: LionWebId
+}
+
+/** § 6.5.5.3 */
+export interface ReplaceChildCommand extends Command {
+    messageKind: "ReplaceChild"
+    newChild: LionWebJsonChunk
+    parent: LionWebId
+    containment: LionWebJsonMetaPointer
+    index: number
+    replacedChild: LionWebId
+}
+
+/** § 6.5.5.4 */
+export interface MoveChildFromOtherContainmentCommand extends Command {
+    messageKind: "MoveChildFromOtherContainment"
+    newParent: LionWebId
+    newContainment: LionWebJsonMetaPointer
+    newIndex: number
+    movedChild: LionWebId
+}
+
+/** § 6.5.5.5 */
+export interface MoveChildFromOtherContainmentInSameParentCommand extends Command {
+    messageKind: "MoveChildFromOtherContainmentInSameParent"
+    newContainment: LionWebJsonMetaPointer
+    newIndex: number
+    movedChild: LionWebId
+    parent: LionWebId
+    oldContainment: LionWebJsonMetaPointer
+    oldIndex: number
+}
+
+/** § 6.5.5.6 */
+export interface MoveChildInSameContainmentCommand extends Command {
+    messageKind: "MoveChildInSameContainment"
+    newIndex: number
+    movedChild: LionWebId
+}
+
+/** § 6.5.5.7 */
+export interface MoveAndReplaceChildFromOtherContainmentCommand extends Command {
+    messageKind: "MoveAndReplaceChildFromOtherContainment"
+    newParent: LionWebId
+    newContainment: LionWebJsonMetaPointer
+    newIndex: number
+    replacedChild: LionWebId
+    movedChild: LionWebId
+}
+
+/** § 6.5.5.8 */
+export interface MoveAndReplaceChildFromOtherContainmentInSameParentCommand extends Command {
+    messageKind: "MoveAndReplaceChildFromOtherContainmentInSameParent"
+    newContainment: LionWebJsonMetaPointer
+    newIndex: number
+    replacedChild: LionWebId
+    movedChild: LionWebId
+}
+
+/** § 6.5.5.9 */
+export interface MoveAndReplaceChildInSameContainmentCommand extends Command {
+    messageKind: "MoveAndReplaceChildInSameContainment"
+    newIndex: number
+    replacedChild: LionWebId
+}
+
+/** § 6.5.6.1 */
+export interface AddAnnotationCommand extends Command {
+    messageKind: "AddAnnotation"
+    parent: LionWebId
+    newAnnotation: LionWebJsonChunk
+    index: number
+}
+
+/** § 6.5.6.2 */
+export interface DeleteAnnotationCommand extends Command {
+    messageKind: "DeleteAnnotation"
+    parent: LionWebId
+    index: number
+    deletedAnnotation: LionWebId
+}
+
+/** § 6.5.6.3 */
+export interface ReplaceAnnotationCommand extends Command {
+    messageKind: "ReplaceAnnotation"
+    newAnnotation: LionWebJsonChunk
+    parent: LionWebId
+    index: number
+    replacedAnnotation: LionWebId
+}
+
+/** § 6.5.6.4 */
+export interface MoveAnnotationFromOtherParentCommand extends Command {
+    messageKind: "MoveAnnotationFromOtherParent"
+    newParent: LionWebId
+    newIndex: number
+    movedAnnotation: LionWebId
+}
+
+/** § 6.5.6.5 */
+export interface MoveAnnotationInSameParentCommand extends Command {
+    messageKind: "MoveAnnotationInSameParent"
+    newIndex: number
+    movedAnnotation: LionWebId
+}
+
+/** § 6.5.6.6 */
+export interface MoveAndReplaceAnnotationFromOtherParentCommand extends Command {
+    messageKind: "MoveAndReplaceAnnotationFromOtherParent"
+    newParent: LionWebId
+    newIndex: number
+    replacedAnnotation: LionWebId
+    movedAnnotation: LionWebId
+}
+
+/** § 6.5.6.7 */
+export interface MoveAndReplaceAnnotationInSameParentCommand extends Command {
+    messageKind: "MoveAndReplaceAnnotationInSameParent"
+    newIndex: number
+    replacedAnnotation: LionWebId
+    movedAnnotation: LionWebId
+}
+
+/** § 6.5.7.1 */
+export interface AddReferenceCommand extends Command {
+    messageKind: "AddReference"
+    parent: LionWebId
+    reference: LionWebJsonMetaPointer
+    index: number
+    newTarget: LionWebId | null
+    newResolveInfo: string | null
+}
+
+/** § 6.5.7.2 */
+export interface DeleteReferenceCommand extends Command {
+    messageKind: "DeleteReference"
+    parent: LionWebId
+    reference: LionWebJsonMetaPointer
+    index: number
+    deletedTarget: LionWebId | null
+    deletedResolveInfo: string | null
+}
+
+/** § 6.5.7.3 */
+export interface ChangeReferenceCommand extends Command {
+    messageKind: "ChangeReference"
+    parent: LionWebId
+    reference: LionWebJsonMetaPointer
+    index: number
+    oldTarget: LionWebId | null
+    oldResolveInfo: string | null
+    newTarget: LionWebId | null
+    newResolveInfo: string | null
+}
+
+/** § 6.5.7.4 */
+export interface MoveEntryFromOtherReferenceCommand extends Command {
+    messageKind: "MoveEntryFromOtherReference"
+    newParent: LionWebId
+    newReference: LionWebJsonMetaPointer
+    newIndex: number
+    oldParent: LionWebId
+    oldReference: LionWebJsonMetaPointer
+    oldIndex: number
+    movedTarget: LionWebId | null
+    movedResolveInfo: string | null
+}
+
+/** § 6.5.7.5 */
+export interface MoveEntryFromOtherReferenceInSameParentCommand extends Command {
+    messageKind: "MoveEntryFromOtherReferenceInSameParent"
+    parent: LionWebId
+    newReference: LionWebJsonMetaPointer
+    newIndex: number
+    oldIndex: number
+    movedTarget: LionWebId | null
+    movedResolveInfo: string | null
+}
+
+/** § 6.5.7.6 */
+export interface MoveEntryInSameReferenceCommand extends Command {
+    messageKind: "MoveEntryInSameReference"
+    parent: LionWebId
+    reference: LionWebJsonMetaPointer
+    oldIndex: number
+    newIndex: number
+    movedTarget: LionWebId | null
+    movedResolveInfo: string | null
+}
+
+/** § 6.5.7.7 */
+export interface MoveAndReplaceEntryFromOtherReferenceCommand extends Command {
+    messageKind: "MoveAndReplaceEntryFromOtherReference"
+    newParent: LionWebId
+    newReference: LionWebJsonMetaPointer
+    newIndex: number
+    replacedTarget: LionWebId | null
+    replacedResolveInfo: string | null
+    oldParent: LionWebId
+    oldReference: LionWebJsonMetaPointer
+    oldIndex: number
+    movedTarget: LionWebId | null
+    movedResolveInfo: string | null
+}
+
+/** § 6.5.7.8 */
+export interface MoveAndReplaceEntryFromOtherReferenceInSameParentCommand extends Command {
+    messageKind: "MoveAndReplaceEntryFromOtherReferenceInSameParent"
+    parent: LionWebId
+    newReference: LionWebJsonMetaPointer
+    newIndex: number
+    replacedTarget: LionWebId | null
+    replacedResolveInfo: string | null
+    oldReference: LionWebJsonMetaPointer
+    oldIndex: number
+    movedTarget: LionWebId | null
+    movedResolveInfo: string | null
+}
+
+/** § 6.5.7.9 */
+export interface MoveAndReplaceEntryInSameReferenceCommand extends Command {
+    messageKind: "MoveAndReplaceEntryInSameReference"
+    parent: LionWebId
+    reference: LionWebJsonMetaPointer
+    oldIndex: number
+    movedTarget: LionWebId | null
+    movedResolveInfo: string | null
+    newIndex: number
+    replacedTarget: LionWebId | null
+    replacedResolveInfo: string | null
+}
+
+/** § 6.5.7.10 */
+export interface AddReferenceResolveInfoCommand extends Command {
+    messageKind: "AddReferenceResolveInfo"
+    parent: LionWebId
+    reference: LionWebJsonMetaPointer
+    index: number
+    newResolveInfo: string
+}
+
+/** § 6.5.7.11 */
+export interface DeleteReferenceResolveInfoCommand extends Command {
+    messageKind: "DeleteReferenceResolveInfo"
+    parent: LionWebId
+    reference: LionWebJsonMetaPointer
+    index: number
+    deletedResolveInfo: string
+}
+
+/** § 6.5.7.12 */
+export interface ChangeReferenceResolveInfoCommand extends Command {
+    messageKind: "ChangeReferenceResolveInfo"
+    parent: LionWebId
+    reference: LionWebJsonMetaPointer
+    index: number
+    oldResolveInfo: string
+    newResolveInfo: string
+}
+
+/** § 6.5.7.13 */
+export interface AddReferenceTargetCommand extends Command {
+    messageKind: "AddReferenceTarget"
+    parent: LionWebId
+    reference: LionWebJsonMetaPointer
+    index: number
+    newTarget: LionWebId
+}
+
+/** § 6.5.7.14 */
+export interface DeleteReferenceTargetCommand extends Command {
+    messageKind: "DeleteReferenceTarget"
+    parent: LionWebId
+    reference: LionWebJsonMetaPointer
+    index: number
+    deletedTarget: LionWebId
+}
+
+/** § 6.5.7.15 */
+export interface ChangeReferenceTargetCommand extends Command {
+    messageKind: "ChangeReferenceTarget"
+    parent: LionWebId
+    reference: LionWebJsonMetaPointer
+    index: number
+    oldTarget: LionWebId
+    newTarget: LionWebId
+}
+
+/** § 6.5.8.1 */
+export interface CompositeCommand extends Command {
+    messageKind: "CompositeCommand"
+    parts: Command[]
+}
+

package/src/payload/common.ts

@@ -0,0 +1,33 @@
+// 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"
+
+export interface Message {
+    messageKind: string
+}
+
+export interface ProtocolMessage {
+    kind: LionWebId
+    message: string
+    data: Record<LionWebId, string>
+}
+
+export interface DeltaProtocolMessage extends Message {
+    protocolMessages: ProtocolMessage[]
+}
+