@lionweb/core 0.10.0-beta.0 → 0.10.0-beta.1

package/src/m3/factory.ts

@@ -4,6 +4,7 @@ import {
     Annotation,
     Classifier,
     Concept,
+    ConceptModifier,
     Containment,
     Enumeration,
     EnumerationLiteral,
@@ -44,8 +45,15 @@ export class LanguageFactory {
         return annotation
     }
 
-    concept(name: string, abstract: boolean, extends_?: SingleRef<Concept>): Concept {
-        const concept = new Concept(this.language, name, this.key(this.language.name, name), this.id(this.language.name, name), abstract, extends_)
+    concept(name: string, abstract: boolean | ConceptModifier, extends_?: SingleRef<Concept>): Concept {
+        const concept = new Concept(
+            this.language,
+            name,
+            this.key(this.language.name, name),
+            this.id(this.language.name, name),
+            abstract,
+            extends_
+        )
         this.language.havingEntities(concept)
         return concept
     }

package/src/m3/functions.ts

@@ -4,7 +4,13 @@
 
 
 import { LionWebId, LionWebKey } from "@lionweb/json"
-import { cycleWith, flatMapNonCyclingFollowing, sortByStringKey } from "@lionweb/ts-utils"
+import {
+    cycleWith,
+    flatMapNonCyclingFollowing,
+    mappedComparer,
+    regularStringComparer,
+    sorterWith
+} from "@lionweb/ts-utils"
 import { containmentChain } from "../functions.js"
 import { ClassifierDeducer } from "../reading.js"
 import { isRef, UnresolvedReference } from "../references.js"
@@ -156,7 +162,7 @@ const nameOf = <T extends INamed>({name}: T): string =>
  * @return the given named things sorted by name
  */
 export const nameSorted = <T extends INamed>(ts: T[]): T[] =>
-    sortByStringKey(ts, nameOf)
+    sorterWith<T>(mappedComparer(nameOf, regularStringComparer))(ts)
 
 
 /**
@@ -303,7 +309,7 @@ const metaTypedBasedClassifierDeducerFor = <NT extends Node & IMetaTyped>(langua
  * @return all {@link Concept concepts} defined in the given {@link Language language}.
  */
 const conceptsOf = (language: Language): Concept[] =>
-    language.entities.filter((entity) => entity instanceof Concept) as Concept[]
+    language.entities.filter((entity) => entity instanceof Concept)
 
 
 const isInstantiableClassifier = (entity: LanguageEntity): boolean =>

package/src/m3/types.ts

@@ -88,7 +88,7 @@ class Property extends Feature {
     metaType(): string {
         return "Property"
     }
-    type: SingleRef<DataType> = referenceToSet()   // (reference)
+    type: SingleRef<DataType> = referenceToSet   // (reference)
     ofType(type: DataType): Property {
         this.type = type
         return this
@@ -97,7 +97,7 @@ class Property extends Feature {
 
 abstract class Link extends Feature {
     multiple /*: boolean */ = false
-    type: SingleRef<Classifier> = referenceToSet()   // (reference)
+    type: SingleRef<Classifier> = referenceToSet   // (reference)
     isMultiple() {
         this.multiple = true
         return this
@@ -145,6 +145,11 @@ abstract class Classifier extends LanguageEntity {
     }
 }
 
+enum ConceptModifier {
+    concrete,
+    abstract
+}
+
 class Concept extends Classifier {
     metaType(): string {
         return "Concept"
@@ -153,9 +158,9 @@ class Concept extends Classifier {
     partition: boolean
     extends?: SingleRef<Concept>    // (reference)
     readonly implements: MultiRef<Interface> = []  // (reference)
-    constructor(language: Language, name: string, key: LionWebKey, id: LionWebId, abstract: boolean, extends_?: SingleRef<Concept>) {
+    constructor(language: Language, name: string, key: LionWebKey, id: LionWebId, abstract: boolean | ConceptModifier, extends_?: SingleRef<Concept>) {
         super(language, name, key, id)
-        this.abstract = abstract
+        this.abstract = abstract === ConceptModifier.abstract || abstract === true
         this.extends = extends_
         this.partition = false
     }
@@ -176,7 +181,7 @@ class Annotation extends Classifier {
     }
     extends?: SingleRef<Annotation> // (reference)
     readonly implements: MultiRef<Interface> = [] // (reference)
-    annotates: SingleRef<Classifier> = referenceToSet()   // (reference)
+    annotates: SingleRef<Classifier> = referenceToSet   // (reference)
     constructor(language: Language, name: string, key: LionWebKey, id: LionWebId, extends_?: SingleRef<Annotation>) {
         super(language, name, key, id)
         this.extends = extends_
@@ -291,6 +296,7 @@ export {
     Annotation,
     Classifier,
     Concept,
+    ConceptModifier,
     Containment,
     DataType,
     Datatype,

package/src/m3/versions/v2023_1/builtins-legacy.ts

@@ -2,7 +2,7 @@ import { asMinimalJsonString } from "@lionweb/ts-utils"
 import { shouldBeIdentical } from "../../builtins-common.js"
 import { DataType, Property } from "../../types.js"
 import { PropertyValueDeserializer } from "../../../deserializer.js"
-import { isUnresolvedReference } from "../../../references.js"
+import { isRef } from "../../../references.js"
 import { PropertyValueSerializer } from "../../../serializer.js"
 import { v2023_1 } from "./version.js"
 
@@ -62,7 +62,7 @@ export class BuiltinPropertyValueDeserializer
             throw new Error(`can't deserialize undefined as the value of required property "${property.name}" (on classifier "${property.classifier.name}" in language "${property.classifier.language.name}")`)
         }
         const { type } = property
-        if (isUnresolvedReference(type)) {
+        if (!isRef(type)) {
             throw new Error(`can't deserialize property "${property.name}" (on classifier "${property.classifier.name}" in language "${property.classifier.language.name}") with unspecified type`)
         }
         const specificDeserializer = this.byType(type)
@@ -104,7 +104,7 @@ export class BuiltinPropertyValueSerializer extends DataTypeRegistry<(value: unk
             throw new Error(`can't serialize undefined as the value of required property "${property.name}" (on classifier "${property.classifier.name}" in language "${property.classifier.language.name}")`)
         }
         const { type } = property
-        if (isUnresolvedReference(type)) {
+        if (!isRef(type)) {
             throw new Error(`can't serialize property "${property.name}" (on classifier "${property.classifier.name}" in language "${property.classifier.language.name}") with unspecified type`)
         }
         const specificSerializer = this.byType(type)

package/src/m3/versions/v2023_1/builtins.ts

@@ -9,6 +9,7 @@ import {
 } from "../../builtins-common.js"
 import { isBuiltinNodeConcept } from "../../builtins-function.js"
 import { LanguageFactory } from "../../factory.js"
+import { ConceptModifier } from "../../types.js"
 
 
 const factory = new LanguageFactory(
@@ -27,7 +28,7 @@ const booleanDataType = factory.primitiveType("Boolean")
 const integerDataType = factory.primitiveType("Integer")
 const jsonDataType = factory.primitiveType("JSON")
 
-const node = factory.concept("Node", true)
+const node = factory.concept("Node", ConceptModifier.abstract)
 
 const inamed = factory.interface("INamed")
 

package/src/m3/versions/v2023_1/lioncore.ts

@@ -1,6 +1,7 @@
 import { lioncoreBuiltinsFacade } from "./builtins.js"
 import { LanguageFactory } from "../../factory.js"
 import { generatedLionCoreKeyFrom, LionCoreFacade } from "../../lioncore-common.js"
+import { ConceptModifier } from "../../types.js"
 
 
 const factory = new LanguageFactory(
@@ -27,54 +28,54 @@ const { booleanDataType, stringDataType } = lioncoreBuiltinsFacade.primitiveType
 const ikeyed = factory.interface("IKeyed").extending(inamed)
 const ikeyed_key = factory.property(ikeyed, "key").ofType(stringDataType)
 
-const feature = factory.concept("Feature", true).implementing(ikeyed)
+const feature = factory.concept("Feature", ConceptModifier.abstract).implementing(ikeyed)
 factory.property(feature, "optional").ofType(booleanDataType)
 
-const property = factory.concept("Property", false, feature)
+const property = factory.concept("Property", ConceptModifier.concrete, feature)
 const property_type = factory.reference(property, "type")
 
-const link = factory.concept("Link", true, feature)
+const link = factory.concept("Link", ConceptModifier.abstract, feature)
 factory.property(link, "multiple").ofType(booleanDataType)
 const link_type = factory.reference(link, "type")
 
-const containment = factory.concept("Containment", false, link)
+const containment = factory.concept("Containment", ConceptModifier.concrete, link)
 
-const reference = factory.concept("Reference", false, link)
+const reference = factory.concept("Reference", ConceptModifier.concrete, link)
 
-const languageEntity = factory.concept("LanguageEntity", true).implementing(ikeyed)
+const languageEntity = factory.concept("LanguageEntity", ConceptModifier.abstract).implementing(ikeyed)
 
-const classifier = factory.concept("Classifier", true, languageEntity)
+const classifier = factory.concept("Classifier", ConceptModifier.abstract, languageEntity)
 factory.containment(classifier, "features").isOptional().isMultiple().ofType(feature)
 link_type.ofType(classifier)
 
-const annotation = factory.concept("Annotation", false, classifier)
+const annotation = factory.concept("Annotation", ConceptModifier.concrete, classifier)
 factory.reference(annotation, "annotates").isOptional().ofType(classifier)
 factory.reference(annotation, "extends").isOptional().ofType(annotation)
 const annotation_implements = factory.reference(annotation, "implements").isMultiple().isOptional()
 
-const concept = factory.concept("Concept", false, classifier)
+const concept = factory.concept("Concept", ConceptModifier.concrete, classifier)
 const concept_abstract = factory.property(concept, "abstract").ofType(booleanDataType)
 factory.property(concept, "partition").ofType(booleanDataType)
 factory.reference(concept, "extends").isOptional().ofType(concept)
 const concept_implements = factory.reference(concept, "implements").isOptional().isMultiple()
 
-const interface_ = factory.concept("Interface", false, classifier)
+const interface_ = factory.concept("Interface", ConceptModifier.concrete, classifier)
 factory.reference(interface_, "extends").isOptional().isMultiple().ofType(interface_)
 
 annotation_implements.ofType(interface_)
 concept_implements.ofType(interface_)
 
-const dataType = factory.concept("DataType", true, languageEntity)
+const dataType = factory.concept("DataType", ConceptModifier.abstract, languageEntity)
 property_type.ofType(dataType)
 
-const primitiveType = factory.concept("PrimitiveType", false, dataType)
+const primitiveType = factory.concept("PrimitiveType", ConceptModifier.concrete, dataType)
 
-const enumeration = factory.concept("Enumeration", false, dataType)
+const enumeration = factory.concept("Enumeration", ConceptModifier.concrete, dataType)
 const enumeration_literals = factory.containment(enumeration, "literals").isMultiple().isOptional()
-const enumerationLiteral = factory.concept("EnumerationLiteral", false).implementing(ikeyed)
+const enumerationLiteral = factory.concept("EnumerationLiteral", ConceptModifier.concrete).implementing(ikeyed)
 enumeration_literals.ofType(enumerationLiteral)
 
-const language = factory.concept("Language", false).implementing(ikeyed).isPartition()
+const language = factory.concept("Language", ConceptModifier.concrete).implementing(ikeyed).isPartition()
 const language_version = factory.property(language, "version").ofType(stringDataType)
 factory.containment(language, "entities").isOptional().isMultiple().ofType(languageEntity)
 factory.reference(language, "dependsOn").isOptional().isMultiple().ofType(language)

package/src/references.ts

@@ -1,42 +1,77 @@
+import { LionWebId } from "@lionweb/json"
+import { stringifyPropertiesOf } from "@lionweb/ts-utils"
+
 import { Node } from "./types.js"
+import { INamed } from "./m3/index.js"
 
 
 /**
- * The `unresolved` symbol indicates a reference value which hasn't been resolved yet.
+ * The `unresolved` “symbol” indicates a reference value which hasn't been resolved yet.
  * It differs from an unset (`undefined`) value.
  * This value shouldn’t be manipulated/compared to directly!
+ *
+ * @deprecated Use {@link referenceToSet} or {@link UnresolvedReference} instead.
  */
 export const unresolved = null
 
+
 /**
- * Type for unresolved references.
+ * Representation of an unresolved reference.
+ * At most one of `targetId` or `resolveInfo` can be `undefined`.
+ *
+ * *Note* that this instance will **not** exhibit object equality,
+ * i.e.: the resolved target of an unresolved reference will be a different object!
  */
-export type UnresolvedReference = typeof unresolved
+export class UnresolvedReference {
+    constructor(public readonly targetId?: LionWebId, public resolveInfo?: string) {}
+    toString = () =>
+        `unresolved reference to target:` + stringifyPropertiesOf(this, "targetId", "resolveInfo")
+}
 
 /**
- * @return a value of {@link UnresolvedReference} that’s a placeholder for a yet-to-set reference.
+ * A singleton representing an unset reference that’s meant to be set,
+ * distinguishing that from a reference that’s intentionally not set
+ *  — which can only happen if that reference is (defined as) optional.
  */
-export const referenceToSet = () =>
-    unresolved
+export const referenceToSet = Symbol("<unset reference>")
 
 /**
  * A type definition for a reference value that can be unresolved.
  * Note: this type is primarily meant to be used to type nodes’ properties,
  * but should be avoided as a return type for “auxiliary” functions.
  */
-export type SingleRef<NT extends Node> = NT | UnresolvedReference
+export type SingleRef<NT extends Node> = NT | UnresolvedReference | typeof referenceToSet
 
 /**
- * @return whether a given (at most) single-valued reference actually refers to something.
+ * @return whether the given {@link UnresolvedReference} corresponds to an (explicitly-)unset (yet-to-set) reference.
  */
-export const isRef = <NT extends Node>(ref?: SingleRef<NT>): ref is NT =>
-    ref !== undefined && ref !== unresolved
+export const isReferenceToSet = <T extends Node>(ref?: SingleRef<T>): ref is typeof referenceToSet =>
+    ref === referenceToSet
 
 /**
  * Type function for the {@link UnresolvedReference} type.
  */
 export const isUnresolvedReference = <NT extends Node>(ref?: SingleRef<NT>): ref is UnresolvedReference =>
-    ref === unresolved
+    ref instanceof UnresolvedReference
+
+/**
+ * @return whether a given (at most) single-valued reference actually refers to something.
+ */
+export const isRef = <NT extends Node>(ref?: SingleRef<NT>): ref is NT =>
+    ref !== undefined && !isReferenceToSet(ref) && !isUnresolvedReference(ref)
+
+/**
+ * @return either the referenced node’s name, or the `resolveInfo` if the reference is unresolved, or `undefined`.
+ */
+export const tryToRenderAsText = <T extends Node & INamed>(ref?: SingleRef<T>): string | undefined => {
+    if (ref === undefined || isReferenceToSet(ref)) {
+        return undefined
+    }
+    if (isUnresolvedReference(ref)) {
+        return ref.resolveInfo
+    }
+    return ref.name
+}
 
 
 /**

package/src/serializer.ts

@@ -1,7 +1,8 @@
-import { LionWebId, LionWebJsonChunk, LionWebJsonNode } from "@lionweb/json"
+import { LionWebId, LionWebJsonChunk, LionWebJsonNode, LionWebJsonReferenceTarget } from "@lionweb/json"
 import { asArray, keepDefineds, lazyMapGet, Nested3Map, uniquesAmong } from "@lionweb/ts-utils"
 import { asIds, metaPointerForFeature } from "./functions.js"
 import { Reader } from "./reading.js"
+import { isRef, isReferenceToSet, SingleRef, UnresolvedReference } from "./references.js"
 import { Node } from "./types.js"
 import { inheritsDirectlyFrom } from "./m3/functions.js"
 import {
@@ -206,8 +207,7 @@ export const serializerWith = <NT extends Node, RT extends Node = NT>(configurat
                     }
                     serializedNode.containments.push({
                         containment: featureMetaPointer,
-                        children: keepDefineds(asIds(children))
-                            .map(childId => childId as string)
+                        children: asIds(keepDefineds(children))
                     })
                     children.forEach(childOrNull => {
                         if (childOrNull !== null) {
@@ -217,19 +217,34 @@ export const serializerWith = <NT extends Node, RT extends Node = NT>(configurat
                     return
                 }
                 if (feature instanceof Reference) {
-                    // Note: value can be null === typeof unresolved, e.g. on an unset (or previously unresolved) single-valued reference
-                    const targets = asArray(value) as (RT | null)[]
+                    const targets = (asArray(value) as SingleRef<RT>[]).filter((ref) => {
+                        if (isRef(ref)) {
+                            return true // (1) ref is a node, having an ID
+                        }
+                        if (isReferenceToSet(ref)) {
+                            return false
+                        }
+                        return ref.targetId !== undefined || ref.resolveInfo !== undefined  // (2) not both are undefined
+                    }) as (RT | UnresolvedReference)[]
                     if (targets.length === 0 && !serializeEmptyFeatures) {
                         return
                     }
                     serializedNode.references.push({
                         reference: featureMetaPointer,
-                        targets: keepDefineds(targets) // (skip "non-connected" targets)
-                            .map(t => ({
-                                resolveInfo:
-                                    (reader.resolveInfoFor ? reader.resolveInfoFor(t, feature) : simpleNameDeducer(t, feature)) ?? null,
-                                reference: t.id
-                            }))
+                        targets: targets
+                            .map((t) =>
+                                t instanceof UnresolvedReference
+                                    ? {
+                                        resolveInfo: t.resolveInfo ?? null,
+                                        reference: t.targetId ?? null
+                                        // at least one of these will be non-null <== (2)
+                                    } as LionWebJsonReferenceTarget
+                                    : {
+                                        resolveInfo: (reader.resolveInfoFor ? reader.resolveInfoFor(t, feature) : simpleNameDeducer(t, feature)) ?? null,
+                                        reference: t.id
+                                        // reference will be a non-null string (~(1))
+                                    }
+                            )
                     })
                     return
                 }