@lionweb/utilities 0.7.0-beta.2 → 0.7.0-beta.21

package/src/hashing.ts

@@ -0,0 +1,148 @@
+import { LionWebId } from "@lionweb/json"
+import { createHash } from "crypto"
+import { nanoid } from "nanoid"
+
+
+/**
+ * Type def. for a hashing function string → string.
+ */
+export type StringHasher = (str: string) => string
+
+
+/**
+ * Hasher based on the {@link https://zelark.github.io/nano-id-cc/ `nanoid` NPM package}.
+ */
+export const nanoIdGen = (): StringHasher =>
+    (_) => nanoid()
+
+
+const defaultHashAlgorithm = "SHA256"
+
+/**
+ * Type definition for objects that configure a
+ * {@link StringHasher hasher}.
+ */
+export type StringHasherConfig = {
+    algorithm?: typeof defaultHashAlgorithm | string
+    salt?: string
+    encoding?: "base64url" | "base64"
+}
+
+/**
+ * Creates a {@link StringHasher hasher},
+ * optionally using a {@link StringHasherConfig configuration object}.
+ * The default is:
+ *   - uses the *SHA256* hashing algorithm
+ *   - without salt prefix string
+ */
+export const hasher = (config?: StringHasherConfig): StringHasher => {
+    const algorithm = config?.algorithm ?? defaultHashAlgorithm
+    const salt = config?.salt ?? ""
+    const encoding = config?.encoding ?? "base64url"
+
+    return (data) => {
+        if (data === undefined) {
+            throw new Error(`expected data for hashing`)
+        }
+        return createHash(algorithm)
+            .update(salt + data)
+            .digest(encoding)
+            .toString()
+    }
+}
+
+
+/**
+ * Augments the given {@link StringHasher hasher} by checking
+ * whether it's been given unique strings,
+ * throwing an error when not.
+ */
+export const checkUniqueData = (hasher: StringHasher): StringHasher => {
+    const datas: string[] = []
+    return (data) => {
+        if (datas.indexOf(data) > -1) {
+            throw new Error(`duplicate data encountered: "${data}"`)
+        }
+        datas.push(data)
+        return hasher(data)
+    }
+}
+
+
+/**
+ * Augments the given {@link StringHasher hasher} by checking
+ * whether it's been given defined ({@code !== undefined}) data,
+ * throwing an error when not.
+ */
+export const checkDefinedData = (hasher: StringHasher): StringHasher =>
+    (data) => {
+        if (data === undefined) {
+            throw new Error(`expected data`)
+        }
+        return hasher(data)
+    }
+
+
+/**
+ * Augments the given {@link StringHasher hasher} by checking
+ * whether that returns unique IDs, throwing an error when not.
+ */
+export const checkUniqueId = (hasher: StringHasher): StringHasher => {
+    const ids: LionWebId[] = []
+
+    return (data) => {
+        const id = hasher(data)
+        if (ids.indexOf(id) > -1) {
+            throw new Error(`duplicate ID generated: "${id}"`)
+        }
+        ids.push(id)
+        return id
+    }
+}
+
+
+/**
+ * Augments the given {@link StringHasher hasher} by checking
+ * whether it returns valid IDs, meaning [Base64URL](https://www.base64url.com/).
+ * (See also [Wikipedia](https://en.wikipedia.org/wiki/Base64#Variants_summary_table).)
+ * If a generated ID is not valid, an error is thrown.
+ */
+export const checkValidId = (hasher: StringHasher): StringHasher =>
+    (data) => {
+        const id = hasher(data)
+        if (!id.match(/^[A-Za-z0-9_-]+$/)) {
+            throw new Error(`generated ID is not valid: ${id}`)
+        }
+        return id
+    }
+
+
+/**
+ * Type definition for transformers of {@link StringHasher hashers}.
+ */
+export type StringHasherTransformer = (hasher: StringHasher) => StringHasher
+
+/**
+ * Wraps the given ("initial") {@link StringHasher hasher}
+ * with the given {@link HasherTransformer hasher transfomers}.
+ * In other words:
+ *
+ *      chain(hasher, trafo1, trafo2, ..., trafoN) === trafoN(...trafo2(trafo1(hasher)))
+ */
+export const chain = (hasher: StringHasher, ...hasherTransformers: StringHasherTransformer[]): StringHasher =>
+    hasherTransformers.reduce((acc, current) => current(acc), hasher)
+
+
+/**
+ * Wraps the given ("initial") {@link StringHasher hasher} with all
+ * {@link HasherTransformer hasher transfomers} defined above.
+ */
+export const checkAll = (hasher: StringHasher): StringHasher =>
+    chain(
+        hasher,
+        checkDefinedData,
+        checkUniqueData,
+        checkValidId,
+        checkUniqueId
+    )
+

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from "./hashing.js"
+export * from "./m1/reference-utils.js"
+export * from "./m3/index.js"
+export * from "./serialization/index.js"
+export * from "./utils/json.js"

package/src/m1/reference-utils.ts

@@ -0,0 +1,2 @@
+export {referenceValues, incomingReferences, referencesToOutOfScopeNodes} from "@lionweb/core"
+export type {ReferenceValue} from "@lionweb/core"

package/src/m3/dependencies.ts

@@ -0,0 +1,62 @@
+// 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 { Classifier, inheritsDirectlyFrom, Language, nameOf, nameSorted } from "@lionweb/core"
+import { indent } from "@lionweb/textgen-utils"
+import { cycleWith, uniquesAmong } from "@lionweb/ts-utils"
+import { asString, when } from "littoral-templates"
+
+
+/**
+ * @return all languages that any {@link Classifier classifier} of the given {@link Language language} depends on through direct inheritance.
+ */
+export const dependenciesThroughDirectInheritanceOf = (language: Language) =>
+    uniquesAmong(
+        language.entities
+            .filter((entity) => entity instanceof Classifier)
+            .flatMap((entity) => inheritsDirectlyFrom(entity as Classifier))
+            .map((classifier) => classifier.language)
+            .filter((depLanguage) => depLanguage !== language)
+    )
+
+
+/**
+ * @return the – currently only those arising from direct inheritance on classifier-level – dependencies of the given {@link Language languages},
+ *  as a human-readable text
+ */
+export const verboseDependencies = (languages: Language[]): string => {
+    const nameSortedLanguages = nameSorted(languages)
+    return asString([
+        nameSortedLanguages.map((language) => {
+            const deps = dependenciesThroughDirectInheritanceOf(language)
+            const what = `direct type-wise dependencies (through inheritance)`
+            const cycle = cycleWith(language, dependenciesThroughDirectInheritanceOf)
+            return deps.length === 0
+                ? `language ${language.name} has no ${what}`
+                : [
+                    `language ${language.name} has the following ${what}:`,
+                    indent([
+                        nameSorted(dependenciesThroughDirectInheritanceOf(language)).map(nameOf),
+                        when(cycle.length > 0)(
+                            `⚠ language "${language.name}" is part of the following cycle through type-wise (through direct inheritance): ${cycle.map(nameOf).join(" -> ")}`
+                        )
+                    ])
+                ]
+        })
+    ])
+}
+

package/src/m3/diagrams/Mermaid-generator.ts

@@ -0,0 +1,129 @@
+import {
+    Annotation,
+    Concept,
+    Containment,
+    Enumeration,
+    Feature,
+    Interface,
+    isBuiltinNodeConcept,
+    isRef,
+    Language,
+    LanguageEntity,
+    Link,
+    nameSorted,
+    nonRelationalFeatures,
+    PrimitiveType,
+    relationsOf,
+    type,
+    unresolved
+} from "@lionweb/core"
+import { asString, indentWith, Template } from "littoral-templates"
+
+// define some layouting basics/building algebra:
+
+const indented = indentWith(`  `)(1)
+
+const block = (header: Template, elements: Template[]): Template =>
+    elements.length === 0 ? header : [`${header} {`, indented(elements), `}`]
+
+const withNewLine = (content: Template): Template => [content, ``]
+
+/**
+ * Generates a string with a Mermaid class diagram
+ * representing the given {@link Language LionCore instance}.
+ */
+export const generateMermaidForLanguage = ({ entities }: Language) =>
+    asString([
+        "```mermaid",
+        `classDiagram
+`,
+        indented(nameSorted(entities).map(generateForEntity)),
+        ``,
+        indented(nameSorted(entities).map(generateForRelationsOf)),
+        ``,
+        "```"
+    ])
+
+const generateForEnumeration = ({ name, literals }: Enumeration) =>
+    withNewLine(block(`class ${name}`, [`<<enumeration>>`, literals.map(({name}) => name)]))
+
+const generateForAnnotation = ({ name, features, extends: extends_, implements: implements_, annotates }: Annotation) => [
+    block(
+        [`class ${name}`, `<<Annotation>> ${name}`, isRef(annotates) ? `${name} ..> ${annotates.name}` : []],
+        nonRelationalFeatures(features).map(generateForNonRelationalFeature)
+    ),
+    isRef(extends_) && !isBuiltinNodeConcept(extends_) ? `${extends_.name} <|-- ${name}` : [],
+    implements_.filter(isRef).map(interface_ => `${interface_.name} <|.. ${name}`),
+    ``
+]
+
+const generateForConcept = ({
+    name,
+    features,
+    abstract: abstract_,
+    extends: extends_ /*, implements: implements_*/,
+    partition
+}: Concept) => [
+    block(`class ${partition ? `<<partition>> ` : ``}${name}`, nonRelationalFeatures(features).map(generateForNonRelationalFeature)),
+    abstract_ ? `<<Abstract>> ${name}` : [],
+    isRef(extends_) && !isBuiltinNodeConcept(extends_) ? `${extends_.name} <|-- ${name}` : [],
+    ``
+]
+
+const generateForInterface = ({ name, features, extends: extends_ }: Interface) => [
+    block(`class ${name}`, nonRelationalFeatures(features).map(generateForNonRelationalFeature)),
+    `<<Interface>> ${name}`,
+    extends_.map(({ name: extendsName }) => `${extendsName} <|-- ${name}`),
+    ``
+]
+
+const generateForNonRelationalFeature = (feature: Feature) => {
+    const { name, optional } = feature
+    const multiple = feature instanceof Link && feature.multiple
+    const type_ = type(feature)
+    const typeText = `${multiple ? `List~` : ``}${type_ === unresolved ? `???` : type_.name}${multiple ? `~` : ``}${optional ? `?` : ``}`
+    return `+${typeText} ${name}`
+}
+
+const generateForPrimitiveType = ({ name }: PrimitiveType) =>
+    `class ${name}
+<<PrimitiveType>> ${name}
+`
+
+const generateForEntity = (entity: LanguageEntity) => {
+    if (entity instanceof Annotation) {
+        return generateForAnnotation(entity)
+    }
+    if (entity instanceof Concept) {
+        return generateForConcept(entity)
+    }
+    if (entity instanceof Enumeration) {
+        return generateForEnumeration(entity)
+    }
+    if (entity instanceof Interface) {
+        return generateForInterface(entity)
+    }
+    if (entity instanceof PrimitiveType) {
+        return generateForPrimitiveType(entity)
+    }
+    return `// unhandled language entity: <${entity.constructor.name}>${entity.name}`
+}
+
+const generateForRelationsOf = (entity: LanguageEntity) => {
+    const relations = relationsOf(entity)
+    return relations.length === 0 ? `` : relations.map(relation => generateForRelation(entity, relation))
+}
+
+const generateForRelation = ({ name: leftName }: LanguageEntity, relation: Link) => {
+    const { name: relationName, optional, multiple, type } = relation
+    const rightName = isRef(type) ? type.name : type === unresolved ? `<unresolved>` : `<null>`
+    const isContainment = relation instanceof Containment
+    const leftMultiplicity = isContainment ? `1` : `*`
+    const rightMultiplicity = (() => {
+        if (multiple) {
+            return "*"
+        }
+        return optional ? "0..1" : "1"
+    })()
+    return `${leftName} "${leftMultiplicity}" ${isContainment ? `o` : ``}--> "${rightMultiplicity}" ${rightName}: ${relationName}`
+}

package/src/m3/diagrams/PlantUML-generator.ts

@@ -0,0 +1,147 @@
+import {
+    Annotation,
+    Concept,
+    Containment,
+    Enumeration,
+    Feature,
+    Interface,
+    isBuiltinNodeConcept,
+    isRef,
+    Language,
+    LanguageEntity,
+    Link,
+    nameOf,
+    nameSorted,
+    nonRelationalFeatures,
+    PrimitiveType,
+    relationsOf,
+    type,
+    unresolved
+} from "@lionweb/core"
+import { asString, indentWith } from "littoral-templates"
+
+const indented = indentWith(`  `)(1)
+
+/**
+ * Generates a string with a PlantUML class diagram
+ * representing the given {@link Language LionCore instance}.
+ */
+export const generatePlantUmlForLanguage = ({ name, entities }: Language) =>
+    asString([
+        `@startuml
+hide empty members
+
+' qualified name: "${name}"
+
+`,
+        nameSorted(entities).map(generateForEntity),
+        `
+
+' relations:
+`,
+        nameSorted(entities).map(generateForRelationsOf),
+        `
+@enduml`
+    ])
+
+const generateForEnumeration = ({ name, literals }: Enumeration) => [
+    `enum ${name} {`,
+    indented(literals.map(({name}) => name)),
+    `}
+`
+]
+
+const generateForAnnotation = ({ name, features, extends: extends_, implements: implements_, annotates }: Annotation) => {
+    const fragments: string[] = []
+    fragments.push(`annotation`, name)
+    if (isRef(extends_) && !isBuiltinNodeConcept(extends_)) {
+        fragments.push(`extends`, extends_.name)
+    }
+    if (implements_.length > 0) {
+        fragments.push(`implements`, implements_.map(nameOf).sort().join(", "))
+    }
+    const nonRelationalFeatures_ = nonRelationalFeatures(features)
+    return nonRelationalFeatures_.length === 0
+        ? [`${fragments.join(" ")}`, isRef(annotates) ? `${name} ..> ${annotates.name}` : [], ``]
+        : [`${fragments.join(" ")} {`, indented(nonRelationalFeatures_.map(generateForNonRelationalFeature)), `}`, ``]
+}
+
+const generateForConcept = ({ name, features, abstract: abstract_, extends: extends_, implements: implements_, partition }: Concept) => {
+    const fragments: string[] = []
+    if (abstract_) {
+        fragments.push(`abstract`)
+    }
+    fragments.push(`class`, name)
+    if (partition) {
+        fragments.push(`<<partition>>`)
+    }
+    if (isRef(extends_) && !isBuiltinNodeConcept(extends_)) {
+        fragments.push(`extends`, extends_.name)
+    }
+    if (implements_.length > 0) {
+        fragments.push(`implements`, implements_.map(nameOf).sort().join(", "))
+    }
+    const nonRelationalFeatures_ = nonRelationalFeatures(features)
+    return nonRelationalFeatures_.length === 0
+        ? [`${fragments.join(" ")}`, ``]
+        : [`${fragments.join(" ")} {`, indented(nonRelationalFeatures_.map(generateForNonRelationalFeature)), `}`, ``]
+}
+
+const generateForInterface = ({ name, extends: extends_, features }: Interface) => {
+    const fragments: string[] = [`interface`, name]
+    if (extends_.length > 0) {
+        fragments.push(`extends`, extends_.map(superInterface => superInterface.name).join(", "))
+    }
+    const nonRelationalFeatures_ = nonRelationalFeatures(features)
+    return nonRelationalFeatures_.length === 0
+        ? `${fragments.join(" ")}`
+        : [`${fragments.join(" ")} {`, indented(nonRelationalFeatures_.map(generateForNonRelationalFeature)), `}`, ``]
+}
+
+const generateForNonRelationalFeature = (feature: Feature) => {
+    const { name, optional } = feature
+    const multiple = feature instanceof Link && feature.multiple
+    const type_ = type(feature)
+    return `${name}: ${multiple ? `List<` : ``}${type_ === unresolved ? `???` : type_.name}${optional && !multiple ? `?` : ``}${multiple ? `>` : ``}`
+}
+
+const generateForPrimitiveType = ({ name }: PrimitiveType) => `class "${name}" <<primitive type>>`
+
+const generateForEntity = (entity: LanguageEntity) => {
+    if (entity instanceof Annotation) {
+        return generateForAnnotation(entity)
+    }
+    if (entity instanceof Enumeration) {
+        return generateForEnumeration(entity)
+    }
+    if (entity instanceof Concept) {
+        return generateForConcept(entity)
+    }
+    if (entity instanceof Interface) {
+        return generateForInterface(entity)
+    }
+    if (entity instanceof PrimitiveType) {
+        return generateForPrimitiveType(entity)
+    }
+    return `' unhandled language entity: <${entity.constructor.name}>${entity.name}
+`
+}
+
+const generateForRelationsOf = (entity: LanguageEntity) => {
+    const relations = relationsOf(entity)
+    return relations.length === 0 ? `` : relations.map(relation => generateForRelation(entity, relation))
+}
+
+const generateForRelation = ({ name: leftName }: LanguageEntity, relation: Link) => {
+    const { name: relationName, type, optional, multiple } = relation
+    const rightName = isRef(type) ? type.name : type === unresolved ? `<unresolved>` : `<null>`
+    const isContainment = relation instanceof Containment
+    const leftMultiplicity = isContainment ? `1` : `*`
+    const rightMultiplicity = multiple ? "*" : optional ? "0..1" : "1"
+    return `${leftName} "${leftMultiplicity}" ${isContainment ? `o` : ``}--> "${rightMultiplicity}" ${rightName}: ${relationName}`
+}
+
+/*
+ Notes:
+    1. No construct for PrimitiveType in PlantUML.
+ */

package/src/m3/index.ts

@@ -0,0 +1,6 @@
+export * from "./diagrams/Mermaid-generator.js"
+export * from "./diagrams/PlantUML-generator.js"
+export * from "./dependencies.js"
+export * from "./infer-languages.js"
+export * from "./textualizer.js"
+export * from "./ts-generation/ts-types-generator.js"

package/src/m3/infer-languages.ts

@@ -0,0 +1,147 @@
+import {
+    builtinPrimitives,
+    Concept,
+    Containment,
+    Language,
+    Link,
+    Property,
+    Reference
+} from "@lionweb/core"
+import { LionWebId, LionWebJsonChunk, LionWebKey } from "@lionweb/json"
+import { asArray, chain, concatenator, lastOf } from "@lionweb/ts-utils"
+import { hasher } from "../hashing.js"
+
+const possibleKeySeparators = ["-", "_"]
+
+const id = chain(concatenator("-"), hasher())
+const key = lastOf
+
+const { stringDataType, booleanDataType, integerDataType } = builtinPrimitives
+
+export const inferLanguagesFromSerializationChunk = (chunk: LionWebJsonChunk): Language[] => {
+    const languages = new Map<string, Language>()
+    const concepts = new Map<string, Concept>()
+    const links = new Array<{ link: Link; conceptId: LionWebId }>()
+
+    for (const chunkLanguage of chunk.languages) {
+        const languageName = chunkLanguage.key
+        const language = new Language(languageName, chunkLanguage.version, id(languageName), key(languageName))
+        languages.set(languageName, language)
+    }
+
+    for (const node of chunk.nodes) {
+        const languageName = node.classifier.language
+        const entityName = node.classifier.key
+
+        const language = findLanguage(languages, languageName)
+        if (language.entities.filter(entity => entity.key === entityName).length) {
+            continue
+        }
+
+        const concept = new Concept(language, entityName, key(language.name, entityName), id(language.name, entityName), false)
+        language.havingEntities(concept)
+        concepts.set(node.id, concept)
+
+        for (const property of node.properties) {
+            const propertyName = deriveLikelyPropertyName(property.property.key)
+            if (concept.features.filter(feature => feature.key === propertyName).length) {
+                continue
+            }
+
+            const feature = new Property(
+                concept,
+                propertyName,
+                key(languageName, concept.name, propertyName),
+                id(languageName, concept.name, propertyName)
+            ).havingKey(property.property.key)
+
+            if (property.value === null) {
+                feature.isOptional()
+            } else {
+                if (isBoolean(property.value)) {
+                    feature.ofType(booleanDataType)
+                } else if (isNumeric(property.value)) {
+                    feature.ofType(integerDataType)
+                } else {
+                    feature.ofType(stringDataType)
+                }
+            }
+
+            concept.havingFeatures(feature)
+        }
+
+        for (const containment of node.containments) {
+            const containmentName = containment.containment.key
+
+            if (concept.features.filter(feature => feature.key === containmentName).length) {
+                continue
+            }
+
+            const children = asArray(containment.children)
+            const feature = new Containment(
+                concept,
+                containmentName,
+                key(languageName, concept.name, containmentName),
+                id(languageName, concept.name, containmentName)
+            )
+            if (children.length) {
+                feature.isMultiple()
+            }
+            concept.havingFeatures(feature)
+
+            links.push({ link: feature, conceptId: children[0] })
+        }
+
+        for (const reference of node.references) {
+            const referenceName = reference.reference.key
+            if (concept.features.filter(feature => feature.key === referenceName).length) {
+                continue
+            }
+
+            const feature = new Reference(
+                concept,
+                referenceName,
+                key(languageName, concept.name, referenceName),
+                id(languageName, concept.name, referenceName)
+            )
+            concept.havingFeatures(feature)
+
+            const value = reference.targets[0].reference
+            links.push({ link: feature, conceptId: value })
+        }
+    }
+
+    for (const link of links) {
+        const linkedConcept = concepts.get(link.conceptId)
+        if (linkedConcept) {
+            link.link.ofType(linkedConcept)
+        } else {
+            // Containment of primitive types??
+        }
+    }
+
+    return Array.from(languages.values())
+}
+
+const findLanguage = (languages: Map<string, Language>, languageName: string) => {
+    const language = languages.get(languageName)
+    if (language === undefined) {
+        throw new Error(`Language '${languageName} does not exist in the languages section`)
+    }
+    return language
+}
+
+export const deriveLikelyPropertyName = (key: LionWebKey) => {
+    for (const separator of possibleKeySeparators) {
+        const name = key.split(separator)[2]
+        if (name) {
+            return name
+        }
+    }
+
+    return key
+}
+
+const isBoolean = (value: string) => value === "true" || value === "false"
+
+const isNumeric = (value: string) => !isNaN(parseFloat(value))