@lionweb/core 0.8.0-beta.3 → 0.8.0-beta.4

package/src/m3/types.ts

@@ -5,7 +5,7 @@
 
 import { LionWebId, LionWebJsonMetaPointer, LionWebKey } from "@lionweb/json"
 import { ResolveInfoDeducer } from "../reading.js"
-import { MultiRef, SingleRef, unresolved } from "../references.js"
+import { MultiRef, SingleRef, referenceToSet } from "../references.js"
 import { Node } from "../types.js"
 
 
@@ -94,7 +94,7 @@ class Property extends Feature {
     metaType(): string {
         return "Property"
     }
-    type: SingleRef<DataType> = unresolved   // (reference)
+    type: SingleRef<DataType> = referenceToSet()   // (reference)
     ofType(type: DataType): Property {
         this.type = type
         return this
@@ -103,7 +103,7 @@ class Property extends Feature {
 
 abstract class Link extends Feature {
     multiple /*: boolean */ = false
-    type: SingleRef<Classifier> = unresolved   // (reference)
+    type: SingleRef<Classifier> = referenceToSet()   // (reference)
     isMultiple() {
         this.multiple = true
         return this
@@ -182,7 +182,7 @@ class Annotation extends Classifier {
     }
     extends?: SingleRef<Annotation> // (reference)
     implements: MultiRef<Interface> = [] // (reference)
-    annotates: SingleRef<Classifier> = unresolved   // (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_

package/src/reading.ts

@@ -1,4 +1,4 @@
-import { Classifier, Enumeration, EnumerationLiteral, Feature } from "./m3/index.js"
+import { Classifier, Enumeration, EnumerationLiteral, Feature, Reference } from "./m3/index.js"
 import { Node } from "./types.js"
 
 
@@ -9,10 +9,11 @@ export type ClassifierDeducer<NT extends Node> = (node: NT) => Classifier
 
 /**
  * Type def. for functions that deduce the string value of the `resolveInfo` field of a
- * {@link LionWebJsonReferenceTarget serialized reference target}, or  {@code undefined}
- * to indicate that no `resolveInfo` could be derived.
+ * {@link LionWebJsonReferenceTarget serialized reference target},
+ * or {@code undefined} to indicate that no `resolveInfo` could be derived.
+ * The function’s arguments are the target {@link Node} and its containing {@link Reference}.
  */
-export type ResolveInfoDeducer<NT extends Node> = (node: NT) => string | undefined
+export type ResolveInfoDeducer<NT extends Node> = (node: NT, reference: Reference) => string | undefined
 
 /**
  * An interface that's used to parametrize generic serialization of

package/src/references.ts

@@ -4,15 +4,27 @@ import { Node } from "./types.js"
 /**
  * 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!
  */
 export const unresolved = null
 
+/**
+ * Type for unresolved references.
+ */
+export type UnresolvedReference = typeof unresolved
+
+/**
+ * @return a value of {@link UnresolvedReference} that’s a placeholder for a yet-to-set reference.
+ */
+export const referenceToSet = () =>
+    unresolved
+
 /**
  * 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> = typeof unresolved | NT
+export type SingleRef<NT extends Node> = NT | UnresolvedReference
 
 /**
  * @return whether a given (at most) single-valued reference actually refers to something.
@@ -20,6 +32,13 @@ export type SingleRef<NT extends Node> = typeof unresolved | NT
 export const isRef = <NT extends Node>(ref?: SingleRef<NT>): ref is NT =>
     ref !== undefined && ref !== unresolved
 
+/**
+ * Type function for the {@link UnresolvedReference} type.
+ */
+export const isUnresolvedReference = <NT extends Node>(ref?: SingleRef<NT>): ref is UnresolvedReference =>
+    ref === unresolved
+
+
 /**
  * A type alias for a multi-valued reference, to make it look consistent with {@link SingleRef}.
  * Note: this type is primarily meant to be used to type nodes’ properties,

package/src/reporter.ts

@@ -0,0 +1,78 @@
+/**
+ * Problems that arise during deserialization, are reported as plain text by calling the `reportProblem` function.
+ * This type is an interface rather than, say, a function definition
+ */
+export interface ProblemReporter {
+    reportProblem: (message: string) => void
+}
+
+/**
+ * Legacy alias for {@link ProblemReporter}, kept for backward compatibility, and to be deprecated and removed later.
+ */
+export type SimplisticHandler = ProblemReporter
+
+
+/**
+ * A default {@link ProblemReporter} that just outputs everything of the console.
+ */
+export const consoleProblemReporter: ProblemReporter = {
+    reportProblem: (message) => {
+        console.log(message)
+    }
+}
+
+/**
+ * Legacy alias for {@link consoleProblemReporter}, kept for backward compatibility, and to be deprecated and removed later.
+ */
+export const defaultSimplisticHandler = consoleProblemReporter
+
+
+/**
+ * A {@link ProblemReporter} that just accumulates problems (in terms of their messages).
+ */
+export class AccumulatingProblemReporter implements ProblemReporter {
+    private _allProblems: string[] = []
+    reportProblem(message: string) {
+        this._allProblems.push(message)
+    }
+    get allProblems() {
+        return this._allProblems
+    }
+}
+
+/**
+ * Legacy alias for {@link AccumulatingProblemReporter}, kept for backward compatibility, and to be deprecated and removed later.
+ */
+export const AccumulatingSimplisticHandler = AccumulatingProblemReporter
+
+
+/**
+ * A {@link ProblemReporter} that aggregates problems by their message.
+ * This is convenient for problems that arise many times during deserialization
+ * but produce the exact same message every time.
+ */
+export class AggregatingProblemReporter implements ProblemReporter {
+    private messageByCount: { [message: string]: number } = {}
+    reportProblem(message: string) {
+        this.messageByCount[message] = (this.messageByCount[message] ?? 0) + 1
+    }
+    reportAllProblemsOnConsole(asTable = false) {
+        if (asTable) {
+            console.table(this.messageByCount)
+        } else {
+            Object.entries(this.messageByCount)
+                .forEach(([message, count]) => {
+                    console.log(`${message} (${count})`)
+                })
+        }
+    }
+    allProblems() {
+        return { ...this.messageByCount }
+    }
+}
+
+/**
+ * Legacy alias for {@link AggregatingProblemReporter}, kept for backward compatibility, and to be deprecated and removed later.
+ */
+export type AggregatingSimplisticHandler = AggregatingProblemReporter
+

package/src/serializer.ts

@@ -1,12 +1,6 @@
-import {
-    currentSerializationFormatVersion,
-    LionWebId,
-    LionWebJsonChunk,
-    LionWebJsonMetaPointer,
-    LionWebJsonNode
-} from "@lionweb/json"
+import { currentSerializationFormatVersion, LionWebId, LionWebJsonChunk, LionWebJsonNode } from "@lionweb/json"
 import { asArray, keepDefineds, lazyMapGet, Nested3Map, uniquesAmong } from "@lionweb/ts-utils"
-import { asIds } from "./functions.js"
+import { asIds, metaPointerFor } from "./functions.js"
 import { Reader } from "./reading.js"
 import { Node } from "./types.js"
 import { builtinPropertyValueSerializer } from "./m3/builtins.js"
@@ -24,6 +18,12 @@ import {
 } from "./m3/types.js"
 
 
+/**
+ * Type definition for functions that serializes nodes as a {@link LionWebJsonChunk serialization chunk}.
+ */
+export type Serializer<NT extends Node> = (nodes: NT[]) => LionWebJsonChunk
+
+
 /**
  * Interface for objects that expose a method to serialize a property's value.
  */
@@ -56,7 +56,7 @@ export type SerializationOptions = Partial<{
 
     /**
      * A {@link PropertyValueSerializer} implementation.
-     * Default = DefaultPropertyValueSerializer.
+     * Default = {@link builtinPropertyValueSerializer}.
      */
     propertyValueSerializer: PropertyValueSerializer
 
@@ -67,26 +67,42 @@ export type SerializationOptions = Partial<{
 
 }>
 
+
 /**
- * @return the {@link LionWebJsonMetaPointer} for the given {@link Feature}.
+ * Type for objects to configure {@link Serializer node serializers} with.
+ * The `reader` property is mandatory,
+ * and the `serializeEmptyFeatures`, `propertyValueSerializer`,
+ * and `primitiveTypeSerializer` (which is a legacy alias for `propertyValueSerializer`)
+ * properties are optional, with defined defaults.
  */
-export const metaPointerFor = (feature: Feature): LionWebJsonMetaPointer => {
-    const { language } = feature.classifier
-    return {
-        language: language.key,
-        version: language.version,
-        key: feature.key
-    }
-}
+export type SerializerConfiguration<NT extends Node> = {
+    /**
+     * An interface with functions to “read” – i.e., introspect – nodes.
+     */
+    reader: Reader<NT>
+} & SerializationOptions
+
+
+/**
+ * @return a {@link Serializer} function that serializes the {@link Node nodes} passed to it,
+ * configured through a `reader` {@link Reader} instance,
+ * and (optionally) a `serializationOptions` {@link SerializationOptions} object.
+ *
+ * This is a legacy version of {@link serializerWith}, kept for backward compatibility, and to be deprecated and removed later.
+ */
+export const nodeSerializer = <NT extends Node>(reader: Reader<NT>, serializationOptions?: SerializationOptions): Serializer<NT> =>
+    serializerWith({ reader, ...serializationOptions })
 
 
 /**
- * @return a function that serializes the {@link Node nodes} passed to it.
+ * @return a {@link Serializer} function that serializes the {@link Node nodes} passed to it,
+ * configured through a `configuration` {@link SerializerConfiguration} object.
  */
-export const nodeSerializer = <NT extends Node>(reader: Reader<NT>, serializationOptions?: SerializationOptions) => {
+export const serializerWith = <NT extends Node>(configuration: SerializerConfiguration<NT>): Serializer<NT> => {
+    const { reader } = configuration
     const propertyValueSerializer =
-        serializationOptions?.propertyValueSerializer ?? serializationOptions?.primitiveTypeSerializer ?? builtinPropertyValueSerializer
-    const serializeEmptyFeatures = serializationOptions?.serializeEmptyFeatures ?? true
+        configuration.propertyValueSerializer ?? configuration.primitiveTypeSerializer ?? builtinPropertyValueSerializer
+    const serializeEmptyFeatures = configuration.serializeEmptyFeatures ?? true
 
     const languageKey2version2classifierKey2allFeatures: Nested3Map<Feature[]> = {}
     const memoisedAllFeaturesOf = (classifier: Classifier): Feature[] =>
@@ -199,7 +215,7 @@ export const nodeSerializer = <NT extends Node>(reader: Reader<NT>, serializatio
                             .map(t => t as NT)
                             .map(t => ({
                                 resolveInfo:
-                                    (reader.resolveInfoFor ? reader.resolveInfoFor(t) : simpleNameDeducer(t)) ?? null,
+                                    (reader.resolveInfoFor ? reader.resolveInfoFor(t, feature) : simpleNameDeducer(t, feature)) ?? null,
                                 reference: t.id
                             }))
                     })

package/dist/handler.d.ts

@@ -1,33 +0,0 @@
-/**
- * A simplistic handler to which problems that arise during deserialization,
- * are reported as plain text by calling the `reportProblem` function.
- */
-export interface SimplisticHandler {
-    reportProblem: (message: string) => void;
-}
-/**
- * A default simplistic handler that just outputs everything of the console.
- */
-export declare const defaultSimplisticHandler: SimplisticHandler;
-/**
- * A simplistic handler that just accumulates problems (in terms of their messages).
- */
-export declare class AccumulatingSimplisticHandler implements SimplisticHandler {
-    private _allProblems;
-    reportProblem(message: string): void;
-    get allProblems(): string[];
-}
-/**
- * A simplistic handler that aggregates problems by their message.
- * This is convenient for problems that arise many times during deserialization
- * but produce the exact same message every time.
- */
-export declare class AggregatingSimplisticHandler implements SimplisticHandler {
-    private messageByCount;
-    reportProblem(message: string): void;
-    reportAllProblemsOnConsole(asTable?: boolean): void;
-    allProblems(): {
-        [message: string]: number;
-    };
-}
-//# sourceMappingURL=handler.d.ts.map

package/dist/handler.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../src/handler.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAC9B,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CAC3C;AAED;;GAEG;AACH,eAAO,MAAM,wBAAwB,EAAE,iBAItC,CAAA;AAGD;;GAEG;AACH,qBAAa,6BAA8B,YAAW,iBAAiB;IACnE,OAAO,CAAC,YAAY,CAAe;IACnC,aAAa,CAAC,OAAO,EAAE,MAAM;IAG7B,IAAI,WAAW,aAEd;CACJ;AAGD;;;;GAIG;AACH,qBAAa,4BAA6B,YAAW,iBAAiB;IAClE,OAAO,CAAC,cAAc,CAAoC;IAC1D,aAAa,CAAC,OAAO,EAAE,MAAM;IAG7B,0BAA0B,CAAC,OAAO,UAAQ;IAU1C,WAAW;;;CAGd"}

package/dist/handler.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"handler.js","sourceRoot":"","sources":["../src/handler.ts"],"names":[],"mappings":"AAQA;;GAEG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAsB;IACvD,aAAa,EAAE,CAAC,OAAO,EAAE,EAAE;QACvB,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;IACxB,CAAC;CACJ,CAAA;AAGD;;GAEG;AACH,MAAM,OAAO,6BAA6B;IAA1C;QACY,iBAAY,GAAa,EAAE,CAAA;IAOvC,CAAC;IANG,aAAa,CAAC,OAAe;QACzB,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;IACnC,CAAC;IACD,IAAI,WAAW;QACX,OAAO,IAAI,CAAC,YAAY,CAAA;IAC5B,CAAC;CACJ;AAGD;;;;GAIG;AACH,MAAM,OAAO,4BAA4B;IAAzC;QACY,mBAAc,GAAkC,EAAE,CAAA;IAiB9D,CAAC;IAhBG,aAAa,CAAC,OAAe;QACzB,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAA;IAC1E,CAAC;IACD,0BAA0B,CAAC,OAAO,GAAG,KAAK;QACtC,IAAI,OAAO,EAAE,CAAC;YACV,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,CAAA;QACtC,CAAC;aAAM,CAAC;YACJ,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,cAAc,CAAC;iBAC9B,OAAO,CAAC,CAAC,CAAC,OAAO,EAAE,KAAK,CAAC,EAAE,EAAE;gBAC1B,OAAO,CAAC,GAAG,CAAC,GAAG,OAAO,KAAK,KAAK,GAAG,CAAC,CAAA;YACxC,CAAC,CAAC,CAAA;QACV,CAAC;IACL,CAAC;IACD,WAAW;QACP,OAAO,EAAE,GAAG,IAAI,CAAC,cAAc,EAAE,CAAA;IACrC,CAAC;CACJ"}

package/src/handler.ts

@@ -1,57 +0,0 @@
-/**
- * A simplistic handler to which problems that arise during deserialization,
- * are reported as plain text by calling the `reportProblem` function.
- */
-export interface SimplisticHandler {
-    reportProblem: (message: string) => void
-}
-
-/**
- * A default simplistic handler that just outputs everything of the console.
- */
-export const defaultSimplisticHandler: SimplisticHandler = {
-    reportProblem: (message) => {
-        console.log(message)
-    }
-}
-
-
-/**
- * A simplistic handler that just accumulates problems (in terms of their messages).
- */
-export class AccumulatingSimplisticHandler implements SimplisticHandler {
-    private _allProblems: string[] = []
-    reportProblem(message: string) {
-        this._allProblems.push(message)
-    }
-    get allProblems() {
-        return this._allProblems
-    }
-}
-
-
-/**
- * A simplistic handler that aggregates problems by their message.
- * This is convenient for problems that arise many times during deserialization
- * but produce the exact same message every time.
- */
-export class AggregatingSimplisticHandler implements SimplisticHandler {
-    private messageByCount: { [message: string]: number } = {}
-    reportProblem(message: string) {
-        this.messageByCount[message] = (this.messageByCount[message] ?? 0) + 1
-    }
-    reportAllProblemsOnConsole(asTable = false) {
-        if (asTable) {
-            console.table(this.messageByCount)
-        } else {
-            Object.entries(this.messageByCount)
-                .forEach(([message, count]) => {
-                    console.log(`${message} (${count})`)
-                })
-        }
-    }
-    allProblems() {
-        return { ...this.messageByCount }
-    }
-}
-