@lionweb/utilities 0.10.0-alpha.2 → 0.10.0-alpha.3

package/CHANGELOG.md

@@ -4,6 +4,9 @@
 
 * Deprecate the `readFileAsJson` and `writeJsonAsFile` functions in favor of the `readFileAsJsonSync` and `writeJsonAsFileSync` functions from `@lionweb/node-utils`.
   (This change has been propagated throughout the entire codebase.)
+* W.r.t. the `sortedSerializationChunk` function:
+  * Give it an additional, optional flag argument `sortConnections` that determines whether containments, references, and annotations are sorted by ID.
+  * It now sorts used languages and features by full meta-pointer, not just its key (language’s key for used language, feature’s key for feature).
 
 
 ## 0.9.0

package/dist/serialization/sorting.d.ts

@@ -1,7 +1,14 @@
 import { LionWebJsonChunk } from "@lionweb/json";
 /**
- * @return A sorted version of a {@link SerializedModel JSON serialization}, which should make it easier to inspect.
- *  Note that the sorted version destroy the order of links, which might effectively alter semantics.
+ * @return A sorted version of a {@link LionWebJsonChunk serialization chunk}, meaning:
+ *
+ *  - All nodes sorted by ID.
+ *  - For all nodes, their properties, containments, and references are sorted lexicographically by the tuple (language-key, feature-key, language-version) — essentially, by the meta-pointer.
+ *  - If the `sortConnections` argument is `true`, then for every node, all containments, references, and contained annotations are sorted by ID.
+ *  All key-value pairs in the objects in the JSON produced, appear according to the specification of the LionWeb serialization format, with missing key-value pairs put in with their default values.
+ *
+ * Sorted serialization chunks lean themselves well to being compared as text files.
+ * Setting `sortConnections` to `true` usually changes the meaning of the serialization chunk, but makes it easy to find out whether a list of items appearing in a containment, a reference, or the annotations of a node merely appear in a different order, or really differ.
  */
-export declare const sortedSerializationChunk: ({ serializationFormatVersion, languages, nodes }: LionWebJsonChunk) => LionWebJsonChunk;
+export declare const sortedSerializationChunk: ({ serializationFormatVersion, languages, nodes }: LionWebJsonChunk, sortConnections?: boolean) => LionWebJsonChunk;
 //# sourceMappingURL=sorting.d.ts.map

package/dist/serialization/sorting.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sorting.d.ts","sourceRoot":"","sources":["../../src/serialization/sorting.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAKhD;;;GAGG;AACH,eAAO,MAAM,wBAAwB,GAAI,kDAAgD,gBAAgB,KAAG,gBAsBtG,CAAA"}
+{"version":3,"file":"sorting.d.ts","sourceRoot":"","sources":["../../src/serialization/sorting.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,gBAAgB,EAQnB,MAAM,eAAe,CAAA;AAatB;;;;;;;;;;GAUG;AACH,eAAO,MAAM,wBAAwB,GAAI,kDAAgD,gBAAgB,EAAE,kBAAkB,OAAO,KAAG,gBAyBjI,CAAA"}

package/dist/serialization/sorting.js

@@ -1,28 +1,45 @@
-import { sortByStringKey } from "@lionweb/ts-utils";
-import { orderedMetaPointer, orderedSerializedLanguageReference, orderedSerializedProperty, orderedSerializedReferenceTarget } from "./ordering.js";
+import { mappedComparer, mappedLexiComparer, regularStringComparer, sorterWith } from "@lionweb/ts-utils";
+import { orderedMetaPointer, orderedSerializedLanguageReference, orderedSerializedReferenceTarget } from "./ordering.js";
+const sortedUsedLanguages = sorterWith(mappedLexiComparer([({ key }) => key, ({ version }) => version], regularStringComparer));
+const sortedNodes = sorterWith(mappedComparer(({ id }) => id, regularStringComparer));
+const metaPointerComparer = mappedLexiComparer([({ language }) => language, ({ version }) => version, ({ key }) => key], regularStringComparer);
+const sortedProperties = sorterWith(mappedComparer(({ property }) => property, metaPointerComparer));
+const sortedContainments = sorterWith(mappedComparer(({ containment }) => containment, metaPointerComparer));
+const sortedReferences = sorterWith(mappedComparer(({ reference }) => reference, metaPointerComparer));
+const sortedTargets = sorterWith(mappedComparer(({ reference, resolveInfo }) => (reference ?? resolveInfo), regularStringComparer));
 /**
- * @return A sorted version of a {@link SerializedModel JSON serialization}, which should make it easier to inspect.
- *  Note that the sorted version destroy the order of links, which might effectively alter semantics.
+ * @return A sorted version of a {@link LionWebJsonChunk serialization chunk}, meaning:
+ *
+ *  - All nodes sorted by ID.
+ *  - For all nodes, their properties, containments, and references are sorted lexicographically by the tuple (language-key, feature-key, language-version) — essentially, by the meta-pointer.
+ *  - If the `sortConnections` argument is `true`, then for every node, all containments, references, and contained annotations are sorted by ID.
+ *  All key-value pairs in the objects in the JSON produced, appear according to the specification of the LionWeb serialization format, with missing key-value pairs put in with their default values.
+ *
+ * Sorted serialization chunks lean themselves well to being compared as text files.
+ * Setting `sortConnections` to `true` usually changes the meaning of the serialization chunk, but makes it easy to find out whether a list of items appearing in a containment, a reference, or the annotations of a node merely appear in a different order, or really differ.
  */
-export const sortedSerializationChunk = ({ serializationFormatVersion, languages, nodes }) => ({
+export const sortedSerializationChunk = ({ serializationFormatVersion, languages, nodes }, sortConnections) => ({
     serializationFormatVersion,
-    languages: sortByStringKey(languages, ({ key }) => key).map(orderedSerializedLanguageReference),
-    nodes: sortByStringKey(nodes, ({ id }) => id)
+    languages: sortedUsedLanguages(languages)
+        .map(orderedSerializedLanguageReference),
+    nodes: sortedNodes(nodes)
         .map((node) => ({
         id: node.id,
         classifier: orderedMetaPointer(node.classifier),
-        properties: sortByStringKey(node.properties, ({ property }) => property.key).map(orderedSerializedProperty),
-        containments: sortByStringKey(node.containments, ({ containment }) => containment.key)
+        properties: sortedProperties(node.properties),
+        containments: sortedContainments(node.containments)
             .map(({ containment, children }) => ({
             containment: orderedMetaPointer(containment),
-            children: children.sort()
+            children: sortConnections ? children.sort() : children
         })),
-        references: sortByStringKey(node.references, ({ reference }) => reference.key)
+        references: sortedReferences(node.references)
             .map(({ reference, targets }) => ({
             reference: orderedMetaPointer(reference),
-            targets: sortByStringKey(targets, ({ reference, resolveInfo }) => (reference ?? resolveInfo)).map(orderedSerializedReferenceTarget)
+            targets: sortConnections
+                ? sortedTargets(targets).map(orderedSerializedReferenceTarget)
+                : targets
         })),
-        annotations: node.annotations.sort(),
+        annotations: sortConnections ? node.annotations.sort() : node.annotations,
         parent: node.parent
     }))
 });

package/dist/serialization/sorting.js.map

@@ -1 +1 @@
-{"version":3,"file":"sorting.js","sourceRoot":"","sources":["../../src/serialization/sorting.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AACnD,OAAO,EAAE,kBAAkB,EAAE,kCAAkC,EAAE,yBAAyB,EAAE,gCAAgC,EAAE,MAAM,eAAe,CAAA;AAGnJ;;;GAGG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,EAAC,0BAA0B,EAAE,SAAS,EAAE,KAAK,EAAmB,EAAoB,EAAE,CAC3H,CAAC;IACG,0BAA0B;IAC1B,SAAS,EAAE,eAAe,CAAC,SAAS,EAAE,CAAC,EAAC,GAAG,EAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,kCAAkC,CAAC;IAC7F,KAAK,EAAE,eAAe,CAAC,KAAK,EAAE,CAAC,EAAC,EAAE,EAAC,EAAE,EAAE,CAAC,EAAE,CAAC;SACtC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACZ,EAAE,EAAE,IAAI,CAAC,EAAE;QACX,UAAU,EAAE,kBAAkB,CAAC,IAAI,CAAC,UAAU,CAAC;QAC/C,UAAU,EAAE,eAAe,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC,EAAC,QAAQ,EAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,yBAAyB,CAAC;QACzG,YAAY,EAAE,eAAe,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC,EAAC,WAAW,EAAC,EAAE,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC;aAC3E,GAAG,CAAC,CAAC,EAAC,WAAW,EAAE,QAAQ,EAAC,EAAE,EAAE,CAAC,CAAC;YAC/B,WAAW,EAAE,kBAAkB,CAAC,WAAW,CAAC;YAC5C,QAAQ,EAAE,QAAQ,CAAC,IAAI,EAAE;SAC5B,CAAC,CAAC;QACX,UAAU,EAAE,eAAe,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC,EAAC,SAAS,EAAC,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC;aACnE,GAAG,CAAC,CAAC,EAAC,SAAS,EAAE,OAAO,EAAC,EAAE,EAAE,CAAC,CAAC;YAC5B,SAAS,EAAE,kBAAkB,CAAC,SAAS,CAAC;YACxC,OAAO,EAAE,eAAe,CAAC,OAAO,EAAE,CAAC,EAAC,SAAS,EAAE,WAAW,EAAC,EAAE,EAAE,CAAC,CAAC,SAAS,IAAI,WAAW,CAAE,CAAC,CAAC,GAAG,CAAC,gCAAgC,CAAC;SACrI,CAAC,CAAC;QACX,WAAW,EAAE,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE;QACpC,MAAM,EAAE,IAAI,CAAC,MAAM;KACtB,CAAC,CAAC;CACV,CAAC,CAAA"}
+{"version":3,"file":"sorting.js","sourceRoot":"","sources":["../../src/serialization/sorting.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@lionweb/utilities",
-    "version": "0.10.0-alpha.2",
+    "version": "0.10.0-alpha.3",
     "description": "LionWeb utilities",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
@@ -15,10 +15,10 @@
         "url": "https://github.com/LionWeb-io/lionweb-typescript/issues"
     },
     "dependencies": {
-        "@lionweb/core": "0.10.0-alpha.2",
-        "@lionweb/json": "0.10.0-alpha.2",
-        "@lionweb/textgen-utils": "0.10.0-alpha.2",
-        "@lionweb/ts-utils": "0.10.0-alpha.2",
+        "@lionweb/core": "0.10.0-alpha.3",
+        "@lionweb/json": "0.10.0-alpha.3",
+        "@lionweb/textgen-utils": "0.10.0-alpha.3",
+        "@lionweb/ts-utils": "0.10.0-alpha.3",
         "littoral-templates": "0.5.1",
         "nanoid": "5.1.6"
     },

package/src/serialization/sorting.ts

@@ -1,32 +1,59 @@
-import { LionWebJsonChunk } from "@lionweb/json"
-import { sortByStringKey } from "@lionweb/ts-utils"
-import { orderedMetaPointer, orderedSerializedLanguageReference, orderedSerializedProperty, orderedSerializedReferenceTarget } from "./ordering.js"
+import {
+    LionWebJsonChunk,
+    LionWebJsonContainment,
+    LionWebJsonMetaPointer,
+    LionWebJsonNode,
+    LionWebJsonProperty,
+    LionWebJsonReference,
+    LionWebJsonReferenceTarget,
+    LionWebJsonUsedLanguage
+} from "@lionweb/json"
+import { mappedComparer, mappedLexiComparer, regularStringComparer, sorterWith } from "@lionweb/ts-utils"
+import { orderedMetaPointer, orderedSerializedLanguageReference, orderedSerializedReferenceTarget } from "./ordering.js"
 
 
+const sortedUsedLanguages = sorterWith<LionWebJsonUsedLanguage>(mappedLexiComparer([({key}) => key, ({version}) => version], regularStringComparer))
+const sortedNodes = sorterWith<LionWebJsonNode>(mappedComparer(({id}) => id, regularStringComparer))
+const metaPointerComparer = mappedLexiComparer<LionWebJsonMetaPointer, string>([({language}) => language, ({version}) => version, ({key}) => key], regularStringComparer)
+const sortedProperties = sorterWith<LionWebJsonProperty>(mappedComparer(({property}) => property, metaPointerComparer))
+const sortedContainments = sorterWith<LionWebJsonContainment>(mappedComparer(({containment}) => containment, metaPointerComparer))
+const sortedReferences = sorterWith<LionWebJsonReference>(mappedComparer(({reference}) => reference, metaPointerComparer))
+const sortedTargets = sorterWith<LionWebJsonReferenceTarget>(mappedComparer(({reference, resolveInfo}) => (reference ?? resolveInfo)!, regularStringComparer))
+
 /**
- * @return A sorted version of a {@link SerializedModel JSON serialization}, which should make it easier to inspect.
- *  Note that the sorted version destroy the order of links, which might effectively alter semantics.
+ * @return A sorted version of a {@link LionWebJsonChunk serialization chunk}, meaning:
+ *
+ *  - All nodes sorted by ID.
+ *  - For all nodes, their properties, containments, and references are sorted lexicographically by the tuple (language-key, feature-key, language-version) — essentially, by the meta-pointer.
+ *  - If the `sortConnections` argument is `true`, then for every node, all containments, references, and contained annotations are sorted by ID.
+ *  All key-value pairs in the objects in the JSON produced, appear according to the specification of the LionWeb serialization format, with missing key-value pairs put in with their default values.
+ *
+ * Sorted serialization chunks lean themselves well to being compared as text files.
+ * Setting `sortConnections` to `true` usually changes the meaning of the serialization chunk, but makes it easy to find out whether a list of items appearing in a containment, a reference, or the annotations of a node merely appear in a different order, or really differ.
  */
-export const sortedSerializationChunk = ({serializationFormatVersion, languages, nodes}: LionWebJsonChunk): LionWebJsonChunk =>
+export const sortedSerializationChunk = ({serializationFormatVersion, languages, nodes}: LionWebJsonChunk, sortConnections?: boolean): LionWebJsonChunk =>
     ({
         serializationFormatVersion,
-        languages: sortByStringKey(languages, ({key}) => key).map(orderedSerializedLanguageReference),
-        nodes: sortByStringKey(nodes, ({id}) => id)
+        languages: sortedUsedLanguages(languages)
+            .map(orderedSerializedLanguageReference),
+        nodes: sortedNodes(nodes)
             .map((node) => ({
                 id: node.id,
                 classifier: orderedMetaPointer(node.classifier),
-                properties: sortByStringKey(node.properties, ({property}) => property.key).map(orderedSerializedProperty),
-                containments: sortByStringKey(node.containments, ({containment}) => containment.key)
+                properties: sortedProperties(node.properties),
+                containments: sortedContainments(node.containments)
                         .map(({containment, children}) => ({
                             containment: orderedMetaPointer(containment),
-                            children: children.sort()
+                            children: sortConnections ? children.sort() : children
                         })),
-                references: sortByStringKey(node.references, ({reference}) => reference.key)
+                references: sortedReferences(node.references)
                         .map(({reference, targets}) => ({
                             reference: orderedMetaPointer(reference),
-                            targets: sortByStringKey(targets, ({reference, resolveInfo}) => (reference ?? resolveInfo)!).map(orderedSerializedReferenceTarget)
+                            targets: sortConnections
+                                ? sortedTargets(targets).map(orderedSerializedReferenceTarget)
+                                : targets
                         })),
-                annotations: node.annotations.sort(),
+                annotations: sortConnections ? node.annotations.sort() : node.annotations,
                 parent: node.parent
             }))
     })