@lionweb/core 0.10.0-alpha.0 → 0.10.0-alpha.2

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, metaPointerFor } from "./functions.js"
+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 {
@@ -177,7 +178,7 @@ export const serializerWith = <NT extends Node, RT extends Node = NT>(configurat
                 const value = reader.getFeatureValue(node, feature)
                 const featureLanguage = feature.classifier.language
                 registerLanguageUsed(featureLanguage)
-                const featureMetaPointer = metaPointerFor(feature)
+                const featureMetaPointer = metaPointerForFeature(feature)
                 if (feature instanceof Property) {
                     if (value === undefined && !serializeEmptyFeatures) {
                         // for immediate backward compatibility: skip empty property values regardless of options?.skipEmptyValues
@@ -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
                 }