@lionweb/core 0.6.10 → 0.6.11-beta.0

package/CHANGELOG.md

@@ -0,0 +1,133 @@
+# Changelog
+
+## 0.6.11 - not officially released yet
+
+* Separate CHANGELOG from README.
+* Move the reference util functions (`referenceValues`, `incomingReferences`, `referencesToOutOfScopeNodes`) and type (class `ReferenceValue`) from the `utilities` package to `core`.
+    Aliases (as re-exports) are left in its place to avoid code breaking.
+    The move is necessary because not all clients of `@lionweb/utilities` can install the Node.js-specific dependencies of the dependencies that package (such as `crypto`).
+
+
+## 0.6.10
+
+* Make `DefaultPrimitiveTypeDeserializer` and `DefaultPrimitiveTypeSerializer` be able to deal with duplicate definitions of datatypes.
+    * Expose a function `shouldBeIdentical` that determines whether two datatypes should be structurally equal based on equality of: meta type, key, and language's key.
+* Make serializer more resilient against unresolved (i.e., `null`-valued) children.
+* Fix that `resolveInfo` of a serialized reference must be `null`, not `undefined`.
+
+
+## 0.6.9
+
+* Improve deserialization:
+    * Produce more meaningful messages for problems
+    * Configure how problems are reported through an instance of a `SimplisticHandler`, calling a new function `deserializeLanguagesWithHandler`.
+      The default value for the handler is `defaultSimplisticHandler` which just reports the problem to the JavaScript console (using `console.log`).
+      The `AccumulatingSimplisticHandler` class accumulates the problems reported, which can be accessed through its `allProblems` method.
+      The `AggregatingSimplisticHandler` class aggregates the problems reported (with count), which can be output using its `reportAllProblemsOnConsole` method, and accessed through its `allProblems` method.
+    * Pass dependent languages also _as languages_ from languages deserializer to regular deserializer, not just as referable data (which is only useful for the built-ins)
+* Fix a bug in the serializer that caused an "unhelpful" exception on an unset or unresolved — i.e., "not-connected", represented by a `null` value — reference target .
+  Now, such reference targets are simply skipped.
+
+
+## 0.6.8
+
+* With respect to deserialization:
+    * Relax deserialization to just skip serialized nodes for which the corresponding M2 data can't be found.
+    * Fix a bug w.r.t. enumeration literals — deserializing changed the keys of enumeration literals in the language's definition.
+    * Deserialization doesn't throw on unresolvable references, but warns on the console and returns `null` (which means “unresolved”).
+* Export `byIdMap` function, which computes a map id → thing from an array of things with an `id`, from the package.
+* Make `SerializedProperty.value` `null`-able, to align with the specification.
+
+
+## 0.6.7
+
+* Fix cycle in imports that some bundlers were having trouble with.
+
+
+## 0.6.6
+
+* The serializer now also serializes annotations.
+* Add support for custom primitive types.
+  Specifically:
+    * A new interface type `PrimitiveTypeSerializer`.
+    * A default implementation `DefaultPrimitiveTypeSerializer` of that that's aware of the LionCore built-in primitive types.
+    * `serializeNodes` has an additional argument of type `PrimitiveTypeSerializer` with as default value an instance of `DefaultPrimitiveTypeSerializer`.
+
+
+## 0.6.5
+
+* Add support for custom primitive types.
+  Specifically:
+    * A new interface type `PrimitiveTypeDeserializer`.
+    * A default implementation `DefaultPrimitiveTypeDeserializer` of that that's aware of the LionCore built-in primitive types.
+    * `deserializeSerializationChunk` has an additional argument of type `PrimitiveTypeDeserializer` with as default value an instance of `DefaultPrimitiveTypeDeserializer`.
+* Expose function `inheritsFrom`.
+
+
+## 0.6.4
+
+* Add functions `mapValues` and `instantiableClassifiers`.
+* Add a method `SymbolTable.languageMatching` to look up a language.
+
+
+## 0.6.3
+
+* The deserializer now deserializes all nodes in the serialization chunk, not just the root nodes (identified as having `parent` set to `null`).
+  (This fixes [issue #145](https://github.com/LionWeb-io/lionweb-typescript/issues/145).)
+    * Also: `deserializeChunk` is renamed to `deserializeSerializationChunk` for naming consistency, although `deserializeChunk` is retained as an alias.
+* Add a method `metaType` to M3 types, to deduce classifiers' names from.
+  (That fixes [issue #143](https://github.com/LionWeb-io/lionweb-typescript/issues/143).)
+
+
+## 0.6.2
+
+* Add a method `Classifier.metaPointer`.
+
+
+## 0.6.1
+
+* Introduce a `isBuiltinNodeConcept` function that checks whether a classifier happens to be the `Node` concept built into LionCore.
+* Add a reference `annotates` to `Annotation`.
+
+
+## 0.6.0
+
+* Introduce a type `SymbolTable` to encapsulate lookup of languages' entities and their features.
+    * Provide a naive and a memoising implementation of the `SymbolTable` abstraction, and use the latter in the deserializer to make that (a bit) more performant.
+
+
+## 0.5.0
+
+This is the first version corresponding to a release of LionWeb (version: 2023.1) as a whole.
+
+* Remove JSON Schema generation functionality – this wasn't up-to-date at all.
+* Implement persistence of annotations on `Node`s, including (de-)serialization.
+* Added an optional field `resolveInfoFor` to the `ExtractionFacade` type, to compute the field `resolveInfo` field of a serialized reference target.
+  The default used is to check whether a node instance implements `INamed` and takes the value of the `name` field.
+* _Breaking change:_ `serializeLanguage` and `deserializeLanguage` are now "multi-lingual" in the sense that a serialization chunk can contain multiple `Language`s.
+  As a result, these functions have been renamed to (the plural) `serializeLanguages` (with varargs), and `deserializeLanguages` (returning `Language[]`).
+* (Bugfix:) Deserialize `Annotation`s.
+* _Breaking change:_ Rework ID and key generation in the LionCore `LanguageFactory`.
+  As part of that:
+    * Add `String[s]Mapper` types, a `StringsMapper` instance `last`, and functions `concatenator` and `chain` to produce instances of them.
+    * Remove `M3Node.keyed` and the "awkward" key generation in the `InstantiationFacade` for the LionCore language.
+    * Remove types `IdGenerator`, and `KeyGenerator` and everything related to that.
+    * Expose keys (instead of qualified names) for LionCore M3 and the LionCore built-ins.
+* Add a type `DynamicINamed` and an M3-function `conceptsOf`, primarily for generation purposes.
+* Move `asText` and ID checking to `@lionweb/utilities`.
+* Expose a helper function `nameSorted`.
+* Rename `ConceptInterface` → `Interface`.
+* Change names: `ReadModelAPI` → `ExtractionFacade`, `WriteModelAPI` → `InstantiationFacade`.
+* Change name of `concept` fields to `classifier`, and their types (where applicable) to `Classifier`.
+* Fix `license` field in `package.json` to `"Apache-2.0"`.
+* Replace all occurrences of "LIon" (with uppercase 'I') with "Lion" (with lowercase 'i').
+* Split the `ModelAPI` interface into a read- and write-part: `ReadModelAPI` vs. `WriteModelAPI`.
+* Make fixes w.r.t. multi-language models.
+* Migrate from Deno to Node.js.
+* Implement import of enums in Ecore importer.
+
+
+## Prior to 0.5.0
+
+No changelog has been kept for previous versions, regardless of whether these were published or not.
+

package/README.md

@@ -30,123 +30,6 @@ The following is a list of links to potential starting points:
   * [Serialization](src/serialization.ts).
 
 
-## Changelog
-
-### 0.6.10 - not officially released yet
-
-* Make `DefaultPrimitiveTypeDeserializer` and `DefaultPrimitiveTypeSerializer` be able to deal with duplicate definitions of datatypes.
-  * Expose a function `shouldBeIdentical` that determines whether two datatypes should be structurally equal based on equality of: meta type, key, and language's key.
-* Make serializer more resilient against unresolved (i.e., `null`-valued) children.
-* Fix that `resolveInfo` of a serialized reference must be `null`, not `undefined`.
-
-
-### 0.6.9
-
-* Improve deserialization:
-  * Produce more meaningful messages for problems
-  * Configure how problems are reported through an instance of a `SimplisticHandler`, calling a new function `deserializeLanguagesWithHandler`.
-    The default value for the handler is `defaultSimplisticHandler` which just reports the problem to the JavaScript console (using `console.log`).
-    The `AccumulatingSimplisticHandler` class accumulates the problems reported, which can be accessed through its `allProblems` method.
-    The `AggregatingSimplisticHandler` class aggregates the problems reported (with count), which can be output using its `reportAllProblemsOnConsole` method, and accessed through its `allProblems` method.
-  * Pass dependent languages also _as languages_ from languages deserializer to regular deserializer, not just as referable data (which is only useful for the built-ins)
-* Fix a bug in the serializer that caused an "unhelpful" exception on an unset or unresolved — i.e., "not-connected", represented by a `null` value — reference target .
-    Now, such reference targets are simply skipped.
-
-
-### 0.6.8
-
-* With respect to deserialization:
-  * Relax deserialization to just skip serialized nodes for which the corresponding M2 data can't be found.
-  * Fix a bug w.r.t. enumeration literals — deserializing changed the keys of enumeration literals in the language's definition.
-  * Deserialization doesn't throw on unresolvable references, but warns on the console and returns `null` (which means “unresolved”).
-* Export `byIdMap` function, which computes a map id → thing from an array of things with an `id`, from the package.
-* Make `SerializedProperty.value` `null`-able, to align with the specification.
-
-
-### 0.6.7
-
-* Fix cycle in imports that some bundlers were having trouble with.
-
-
-### 0.6.6
-
-* The serializer now also serializes annotations.
-* Add support for custom primitive types.
-  Specifically:
-    * A new interface type `PrimitiveTypeSerializer`.
-    * A default implementation `DefaultPrimitiveTypeSerializer` of that that's aware of the LionCore built-in primitive types.
-    * `serializeNodes` has an additional argument of type `PrimitiveTypeSerializer` with as default value an instance of `DefaultPrimitiveTypeSerializer`.
-
-
-### 0.6.5
-
-* Add support for custom primitive types.
-    Specifically:
-  * A new interface type `PrimitiveTypeDeserializer`.
-  * A default implementation `DefaultPrimitiveTypeDeserializer` of that that's aware of the LionCore built-in primitive types.
-  * `deserializeSerializationChunk` has an additional argument of type `PrimitiveTypeDeserializer` with as default value an instance of `DefaultPrimitiveTypeDeserializer`.
-* Expose function `inheritsFrom`.
-
-### 0.6.4
-
-* Add functions `mapValues` and `instantiableClassifiers`.
-* Add a method `SymbolTable.languageMatching` to look up a language.
-
-### 0.6.3
-
-* The deserializer now deserializes all nodes in the serialization chunk, not just the root nodes (identified as having `parent` set to `null`).
-  (This fixes [issue #145](https://github.com/LionWeb-io/lionweb-typescript/issues/145).)
-  * Also: `deserializeChunk` is renamed to `deserializeSerializationChunk` for naming consistency, although `deserializeChunk` is retained as an alias.
-* Add a method `metaType` to M3 types, to deduce classifiers' names from.
-  (That fixes [issue #143](https://github.com/LionWeb-io/lionweb-typescript/issues/143).)
-
-### 0.6.2
-
-* Add a method `Classifier.metaPointer`.
-
-### 0.6.1
-
-* Introduce a `isBuiltinNodeConcept` function that checks whether a classifier happens to be the `Node` concept built into LionCore.
-* Add a reference `annotates` to `Annotation`.
-
-### 0.6.0
-
-* Introduce a type `SymbolTable` to encapsulate lookup of languages' entities and their features.
-  * Provide a naive and a memoising implementation of the `SymbolTable` abstraction, and use the latter in the deserializer to make that (a bit) more performant.
-
-### 0.5.0
-
-This is the first version corresponding to a release of LionWeb (version: 2023.1) as a whole.
-
-* Remove JSON Schema generation functionality – this wasn't up-to-date at all.
-* Implement persistence of annotations on `Node`s, including (de-)serialization.
-* Added an optional field `resolveInfoFor` to the `ExtractionFacade` type, to compute the field `resolveInfo` field of a serialized reference target.
-  The default used is to check whether a node instance implements `INamed` and takes the value of the `name` field.
-* _Breaking change:_ `serializeLanguage` and `deserializeLanguage` are now "multi-lingual" in the sense that a serialization chunk can contain multiple `Language`s.
-  As a result, these functions have been renamed to (the plural) `serializeLanguages` (with varargs), and `deserializeLanguages` (returning `Language[]`).
-* (Bugfix:) Deserialize `Annotation`s.
-* _Breaking change:_ Rework ID and key generation in the LionCore `LanguageFactory`.
-  As part of that:
-  * Add `String[s]Mapper` types, a `StringsMapper` instance `last`, and functions `concatenator` and `chain` to produce instances of them.
-  * Remove `M3Node.keyed` and the "awkward" key generation in the `InstantiationFacade` for the LionCore language.
-  * Remove types `IdGenerator`, and `KeyGenerator` and everything related to that.
-  * Expose keys (instead of qualified names) for LionCore M3 and the LionCore built-ins.
-* Add a type `DynamicINamed` and an M3-function `conceptsOf`, primarily for generation purposes.
-* Move `asText` and ID checking to `@lionweb/utilities`.
-* Expose a helper function `nameSorted`.
-* Rename `ConceptInterface` → `Interface`.
-* Change names: `ReadModelAPI` → `ExtractionFacade`, `WriteModelAPI` → `InstantiationFacade`.
-* Change name of `concept` fields to `classifier`, and their types (where applicable) to `Classifier`.
-* Fix `license` field in `package.json` to `"Apache-2.0"`.
-* Replace all occurrences of "LIon" (with uppercase 'I') with "Lion" (with lowercase 'i').
-* Split the `ModelAPI` interface into a read- and write-part: `ReadModelAPI` vs. `WriteModelAPI`.
-* Make fixes w.r.t. multi-language models.
-* Migrate from Deno to Node.js.
-* Implement import of enums in Ecore importer.
-
-No changelog has been kept for previous versions, regardless of whether these were published or not.
-
-
 ## Development
 
 Build it from source as follows:

package/dist/index.d.ts

@@ -11,4 +11,5 @@ export * from "./types.js";
 export * from "./utils/index.js";
 export * from "./version.js";
 export * from "./m3/index.js";
+export * from "./m1/reference-utils.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAA;AACjC,cAAc,qBAAqB,CAAA;AACnC,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,oBAAoB,CAAA;AAClC,cAAc,mBAAmB,CAAA;AACjC,cAAc,YAAY,CAAA;AAC1B,cAAc,kBAAkB,CAAA;AAChC,cAAc,cAAc,CAAA;AAC5B,cAAc,eAAe,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAA;AACjC,cAAc,qBAAqB,CAAA;AACnC,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,oBAAoB,CAAA;AAClC,cAAc,mBAAmB,CAAA;AACjC,cAAc,YAAY,CAAA;AAC1B,cAAc,kBAAkB,CAAA;AAChC,cAAc,cAAc,CAAA;AAC5B,cAAc,eAAe,CAAA;AAC7B,cAAc,yBAAyB,CAAA"}

package/dist/index.js

@@ -11,4 +11,5 @@ export * from "./types.js";
 export * from "./utils/index.js";
 export * from "./version.js";
 export * from "./m3/index.js";
+export * from "./m1/reference-utils.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAA;AACjC,cAAc,qBAAqB,CAAA;AACnC,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,oBAAoB,CAAA;AAClC,cAAc,mBAAmB,CAAA;AACjC,cAAc,YAAY,CAAA;AAC1B,cAAc,kBAAkB,CAAA;AAChC,cAAc,cAAc,CAAA;AAC5B,cAAc,eAAe,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAA;AACjC,cAAc,qBAAqB,CAAA;AACnC,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,oBAAoB,CAAA;AAClC,cAAc,mBAAmB,CAAA;AACjC,cAAc,YAAY,CAAA;AAC1B,cAAc,kBAAkB,CAAA;AAChC,cAAc,cAAc,CAAA;AAC5B,cAAc,eAAe,CAAA;AAC7B,cAAc,yBAAyB,CAAA"}

package/dist/m1/reference-utils.d.ts

@@ -0,0 +1,56 @@
+import { Reference } from "../m3/index.js";
+import { ExtractionFacade } from "../facade.js";
+import { Node } from "../types.js";
+/**
+ * Represents information about a source and target node related through a {@link Reference}.
+ * An index of `null` means that the reference is (at most) single-valued.
+ */
+export declare class ReferenceValue<NT extends Node> {
+    readonly sourceNode: NT;
+    readonly targetNode: NT;
+    readonly reference: Reference;
+    readonly index: number | null;
+    constructor(sourceNode: NT, targetNode: NT, reference: Reference, index: number | null);
+}
+/**
+ * Finds all references within the given scope, as {@link ReferenceValue reference values}.
+ * To search within all nodes under a collection of root nodes,
+ * use _child extraction_ to compute all nodes in the forest hanging off of those root nodes as scope.
+ * Note that any reference is found uniquely,
+ * i.e. the returned {@link ReferenceValue reference values} are pairwise distinct,
+ * even if the scope passed contains duplicate nodes.
+ *
+ * @param scope - the {@link Node nodes} that are searched for references
+ * @param extractionFacade - an {@link ExtractionFacade} to reflect on nodes.
+ * _Note_ that it's assumed that its {@link getFeatureValue} function doesn't throw.
+ */
+export declare const referenceValues: <NT extends Node>(scope: NT[], extractionFacade: ExtractionFacade<NT>) => ReferenceValue<NT>[];
+/**
+ * Finds all references coming into the given target node or any of the given target nodes,
+ * within the given scope, as {@link ReferenceValue reference values}.
+ * To search within all nodes under a collection of root nodes,
+ * use _child extraction_ to compute all nodes in the forest hanging off of those root nodes as scope.
+ * Note that any reference is found uniquely,
+ * i.e. the returned {@link ReferenceValue reference values} are pairwise distinct,
+ * even if the given target nodes or scope contain duplicate nodes.
+ *
+ * @param targetNodeOrNodes - one or more target {@link Node nodes} for which the incoming references are searched
+ * @param scope - the {@link Node nodes} that are searched for references
+ * @param extractionFacade - an {@link ExtractionFacade} to reflect on nodes.
+ * _Note_ that it's assumed that its {@link getFeatureValue} function doesn't throw.
+ */
+export declare const incomingReferences: <NT extends Node>(targetNodeOrNodes: NT | NT[], scope: NT[], extractionFacade: ExtractionFacade<NT>) => ReferenceValue<NT>[];
+/**
+ * Finds all references to nodes that are not in the given scope, as {@link ReferenceValue reference values}.
+ * To search within all nodes under a collection of root nodes,
+ * use _child extraction_ to compute all nodes in the forest hanging off of those root nodes as scope.
+ * Note that any reference is found uniquely,
+ * i.e. the returned {@link ReferenceValue reference values} are pairwise distinct,
+ * even if the given scope contains duplicate nodes.
+ *
+ * @param scope - the {@link Node nodes} that form the scope of “reachable” nodes
+ * @param extractionFacade - an {@link ExtractionFacade} to reflect on nodes.
+ * _Note_ that it's assumed that its {@link getFeatureValue} function doesn't throw.
+ */
+export declare const referencesToOutOfScopeNodes: <NT extends Node>(scope: NT[], extractionFacade: ExtractionFacade<NT>) => ReferenceValue<NT>[];
+//# sourceMappingURL=reference-utils.d.ts.map

package/dist/m1/reference-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-utils.d.ts","sourceRoot":"","sources":["../../src/m1/reference-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,SAAS,EAAC,MAAM,gBAAgB,CAAA;AACvD,OAAO,EAAC,gBAAgB,EAAC,MAAM,cAAc,CAAA;AAC7C,OAAO,EAAC,IAAI,EAAC,MAAM,aAAa,CAAA;AAGhC;;;GAGG;AACH,qBAAa,cAAc,CAAC,EAAE,SAAS,IAAI;aAEnB,UAAU,EAAE,EAAE;aACd,UAAU,EAAE,EAAE;aACd,SAAS,EAAE,SAAS;aACpB,KAAK,EAAE,MAAM,GAAG,IAAI;gBAHpB,UAAU,EAAE,EAAE,EACd,UAAU,EAAE,EAAE,EACd,SAAS,EAAE,SAAS,EACpB,KAAK,EAAE,MAAM,GAAG,IAAI;CAE3C;AAGD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,eAAe,gGA4B3B,CAAA;AAGD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,kBAAkB,8HAQ9B,CAAA;AAGD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,2BAA2B,gGAK4C,CAAA"}

package/dist/m1/reference-utils.js

@@ -0,0 +1,78 @@
+import { allFeaturesOf, Reference } from "../m3/index.js";
+/**
+ * Represents information about a source and target node related through a {@link Reference}.
+ * An index of `null` means that the reference is (at most) single-valued.
+ */
+export class ReferenceValue {
+    constructor(sourceNode, targetNode, reference, index) {
+        this.sourceNode = sourceNode;
+        this.targetNode = targetNode;
+        this.reference = reference;
+        this.index = index;
+    }
+}
+/**
+ * Finds all references within the given scope, as {@link ReferenceValue reference values}.
+ * To search within all nodes under a collection of root nodes,
+ * use _child extraction_ to compute all nodes in the forest hanging off of those root nodes as scope.
+ * Note that any reference is found uniquely,
+ * i.e. the returned {@link ReferenceValue reference values} are pairwise distinct,
+ * even if the scope passed contains duplicate nodes.
+ *
+ * @param scope - the {@link Node nodes} that are searched for references
+ * @param extractionFacade - an {@link ExtractionFacade} to reflect on nodes.
+ * _Note_ that it's assumed that its {@link getFeatureValue} function doesn't throw.
+ */
+export const referenceValues = (scope, extractionFacade) => {
+    const visit = (sourceNode, reference) => {
+        if (reference.multiple) {
+            const targetNodes = extractionFacade.getFeatureValue(sourceNode, reference) ?? [];
+            return targetNodes
+                .map((targetNode, index) => new ReferenceValue(sourceNode, targetNode, reference, index));
+        }
+        const targetNode = extractionFacade.getFeatureValue(sourceNode, reference);
+        if (targetNode !== undefined) {
+            return [new ReferenceValue(sourceNode, targetNode, reference, null)];
+        }
+        return [];
+    };
+    return [...new Set(scope)] // ~ .distinct()
+        .flatMap((sourceNode) => allFeaturesOf(extractionFacade.classifierOf(sourceNode))
+        .filter((feature) => feature instanceof Reference)
+        .map((feature) => feature)
+        .flatMap((reference) => visit(sourceNode, reference)));
+};
+/**
+ * Finds all references coming into the given target node or any of the given target nodes,
+ * within the given scope, as {@link ReferenceValue reference values}.
+ * To search within all nodes under a collection of root nodes,
+ * use _child extraction_ to compute all nodes in the forest hanging off of those root nodes as scope.
+ * Note that any reference is found uniquely,
+ * i.e. the returned {@link ReferenceValue reference values} are pairwise distinct,
+ * even if the given target nodes or scope contain duplicate nodes.
+ *
+ * @param targetNodeOrNodes - one or more target {@link Node nodes} for which the incoming references are searched
+ * @param scope - the {@link Node nodes} that are searched for references
+ * @param extractionFacade - an {@link ExtractionFacade} to reflect on nodes.
+ * _Note_ that it's assumed that its {@link getFeatureValue} function doesn't throw.
+ */
+export const incomingReferences = (targetNodeOrNodes, scope, extractionFacade) => {
+    const targetNodes = Array.isArray(targetNodeOrNodes) ? targetNodeOrNodes : [targetNodeOrNodes];
+    return referenceValues(scope, extractionFacade)
+        .filter((referenceValue) => targetNodes.indexOf(referenceValue.targetNode) > -1);
+};
+/**
+ * Finds all references to nodes that are not in the given scope, as {@link ReferenceValue reference values}.
+ * To search within all nodes under a collection of root nodes,
+ * use _child extraction_ to compute all nodes in the forest hanging off of those root nodes as scope.
+ * Note that any reference is found uniquely,
+ * i.e. the returned {@link ReferenceValue reference values} are pairwise distinct,
+ * even if the given scope contains duplicate nodes.
+ *
+ * @param scope - the {@link Node nodes} that form the scope of “reachable” nodes
+ * @param extractionFacade - an {@link ExtractionFacade} to reflect on nodes.
+ * _Note_ that it's assumed that its {@link getFeatureValue} function doesn't throw.
+ */
+export const referencesToOutOfScopeNodes = (scope, extractionFacade) => referenceValues(scope, extractionFacade)
+    .filter((referenceValue) => scope.indexOf(referenceValue.targetNode) === -1);
+//# sourceMappingURL=reference-utils.js.map

package/dist/m1/reference-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-utils.js","sourceRoot":"","sources":["../../src/m1/reference-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,aAAa,EAAE,SAAS,EAAC,MAAM,gBAAgB,CAAA;AAKvD;;;GAGG;AACH,MAAM,OAAO,cAAc;IACvB,YACoB,UAAc,EACd,UAAc,EACd,SAAoB,EACpB,KAAoB;QAHpB,eAAU,GAAV,UAAU,CAAI;QACd,eAAU,GAAV,UAAU,CAAI;QACd,cAAS,GAAT,SAAS,CAAW;QACpB,UAAK,GAAL,KAAK,CAAe;IACrC,CAAC;CACP;AAGD;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAC3B,KAAW,EACX,gBAAsC,EAClB,EAAE;IACtB,MAAM,KAAK,GAAG,CAAC,UAAc,EAAE,SAAoB,EAAwB,EAAE;QACzE,IAAI,SAAS,CAAC,QAAQ,EAAE,CAAC;YACrB,MAAM,WAAW,GAAG,gBAAgB,CAAC,eAAe,CAAC,UAAU,EAAE,SAAS,CAAS,IAAI,EAAE,CAAA;YACzF,OAAO,WAAW;iBACb,GAAG,CAAC,CAAC,UAAU,EAAE,KAAK,EAAE,EAAE,CACvB,IAAI,cAAc,CAAK,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,KAAK,CAAC,CACnE,CAAA;QACT,CAAC;QAED,MAAM,UAAU,GAAG,gBAAgB,CAAC,eAAe,CAAC,UAAU,EAAE,SAAS,CAAqB,CAAA;QAC9F,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;YAC3B,OAAO,CAAC,IAAI,cAAc,CAAK,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC,CAAA;QAC5E,CAAC;QAED,OAAO,EAAE,CAAA;IACb,CAAC,CAAA;IAED,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAE,gBAAgB;SACvC,OAAO,CAAC,CAAC,UAAU,EAAE,EAAE,CACpB,aAAa,CAAC,gBAAgB,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC;SACnD,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,YAAY,SAAS,CAAC;SACjD,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAoB,CAAC;SACtC,OAAO,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,KAAK,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC,CAC5D,CAAA;AACT,CAAC,CAAA;AAGD;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAC9B,iBAA4B,EAC5B,KAAW,EACX,gBAAsC,EAClB,EAAE;IACtB,MAAM,WAAW,GAAG,KAAK,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAA;IAC9F,OAAO,eAAe,CAAC,KAAK,EAAE,gBAAgB,CAAC;SAC1C,MAAM,CAAC,CAAC,cAAc,EAAE,EAAE,CAAC,WAAW,CAAC,OAAO,CAAC,cAAc,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAA;AACxF,CAAC,CAAA;AAGD;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,CACvC,KAAW,EACX,gBAAsC,EAClB,EAAE,CACtB,eAAe,CAAC,KAAK,EAAE,gBAAgB,CAAC;KACnC,MAAM,CAAC,CAAC,cAAc,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,cAAc,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lionweb/core",
-  "version": "0.6.10",
+  "version": "0.6.11-beta.0",
   "description": "LionWeb core for {Java|Type}Script",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",