adjust for #93

Author: Buckwich

README.md

@@ -5,7 +5,7 @@
 An extension for [bpmn-js](https://github.com/bpmn-io/bpmn-js) that makes the data model of the diagram available to other components.
 
 > [!NOTE]
-> As of version `v3` this library exposes both written and consumed variables.
+> As of version `v3` this library exposes both written and consumed variables, you can filter them via options.
 
 ## Usage
 
@@ -42,14 +42,29 @@ const elementRegistry = modeler.get('elementRegistry');
 // retrieve variables relevant to an element
 const task = elementRegistry.get('Task_1');
 
-// variables available in scope of <task>
+// default: variables relevant to <task> in its visible scopes
 await variableResolver.getVariablesForElement(task);
 
-// variables read by <task>, excluding local ones
-await variableResolver.getVariablesForElement(task, { read: true, local: false });
+// variables read by <task> only
+await variableResolver.getVariablesForElement(task, {
+  read: true,
+  written: false
+});
 
 // all variables written by <task>
-await variableResolver.getVariablesForElement(task, { written: true });
+await variableResolver.getVariablesForElement(task, { written: true, read: false });
+
+// local variables only (scope === queried element)
+await variableResolver.getVariablesForElement(task, {
+  local: true,
+  external: false
+});
+
+// non-local variables only (scope !== queried element)
+await variableResolver.getVariablesForElement(task, {
+  local: false,
+  external: true
+});
 
 // retrieve all variables defined in a process
 const processElement = elementRegistry.get('Process_1');
@@ -58,6 +73,16 @@ const processElement = elementRegistry.get('Process_1');
 await variableResolver.getProcessVariables(processElement);
 ```
 
+`getVariablesForElement(element, options)` supports five filter switches:
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `read` | `true` | Include variables consumed by the queried element |
+| `written` | `true` | Include variables written/created by the queried element |
+| `local` | `true` | Include variables local to the queried element scope |
+| `external` | `true` | Include variables outside the queried element scope |
+| `outputMappings` | `true` | Count output-mapping reads as reads |
+
 ### Adding a variable extractor
 
 To add your own variables, extend the `variableProvider` class in your extension. It only needs to implement the `getVariables` method, which takes an element as an argument and returns an array of variables you want to add to the scope of the element. The function can be asynchronous.

lib/base/VariableResolver.js

@@ -18,6 +18,21 @@ import { getParents } from './util/elementsUtil';
  * @property {Array<ModdleElement>} origin
  * @property {ModdleElement} [scope]
  * @property {Array<Object>} provider
+ * @property {Array<string|ModdleElement>} [usedBy] Elements or variable names consuming this variable
+ * @property {Array<string>} [readFrom] Source tags describing where this variable is read from
+ */
+
+/**
+ * @typedef {Object} VariablesFilterOptions
+ * @property {boolean} [read=true] Include consumed variables
+ * @property {boolean} [written=true] Include variables written in the queried element
+ * @property {boolean} [local=true] Include variables in the queried element scope
+ * @property {boolean} [external=true] Include variables outside the queried element scope
+ * @property {boolean} [outputMappings=true] Include reads originating from output mappings
+ */
+
+/**
+ * @typedef {ProcessVariable} AvailableVariable
  */
 
 /**
@@ -179,6 +194,18 @@ export class BaseVariableResolver {
               });
             }
           }
+
+          if (variable.readFrom) {
+            if (!existingVariable.readFrom) {
+              existingVariable.readFrom = [ ...variable.readFrom ];
+            } else {
+              variable.readFrom.forEach(source => {
+                if (!existingVariable.readFrom.includes(source)) {
+                  existingVariable.readFrom.push(source);
+                }
+              });
+            }
+          }
         } else {
           mergedVariables.push(variable);
         }
@@ -263,12 +290,18 @@ export class BaseVariableResolver {
   /**
    * Returns all variables in the scope of the given element.
    *
+   * All filter switches default to `true`
+    *
+    * Use `{ read: true, written: false }` to retrieve read-only variables.
+   *
    * @async
    * @param {ModdleElement} element
-   * @returns {Promise<Array<ProcessVariable>>} variables
+   * @param {VariablesFilterOptions} [options]
+   * @returns {Promise<Array<AvailableVariable>>} variables
    */
-  async getVariablesForElement(element) {
+  async getVariablesForElement(element, options = {}) {
     const bo = getBusinessObject(element);
+    const filterOptions = normalizeFilterOptions(options);
 
     const root = getRootElement(bo);
     const allVariables = await this.getProcessVariables(root);
@@ -320,14 +353,14 @@ export class BaseVariableResolver {
       return false;
     });
 
-    return deduplicatedVariables.map(variable => {
+    const projectedScopedVariables = deduplicatedVariables.map(variable => {
       if (!variable.usedBy || !Array.isArray(variable.usedBy)) {
         return variable;
       }
 
       const usedBy = filterUsedByForElement(variable, bo);
 
-      if (usedBy.length === variable.usedBy.length) {
+      if (isSameUsageList(variable.usedBy, usedBy)) {
         return variable;
       }
 
@@ -336,32 +369,41 @@ export class BaseVariableResolver {
         usedBy: usedBy.length ? usedBy : undefined
       };
     });
+
+    const consumedVariables = allVariables.filter(variable => {
+      return !variable.scope
+        && Array.isArray(variable.usedBy)
+        && variable.usedBy.some(usage => usage && usage.id === bo.id);
+    });
+
+    let candidates = projectedScopedVariables;
+
+    if (filterOptions.read && !filterOptions.written) {
+      candidates = [ ...projectedScopedVariables, ...consumedVariables ];
+    } else if (filterOptions.read && filterOptions.written && !projectedScopedVariables.length) {
+
+      // Preserve current default behavior: only fall back to consumed variables
+      // when no scoped/ancestor variables are available.
+      candidates = consumedVariables;
+    }
+
+    return candidates.filter(variable => {
+      const isLocal = !!(variable.scope && variable.scope.id === bo.id);
+      const hasReadUsage = !!(variable.usedBy && variable.usedBy.length);
+      const readSources = Array.isArray(variable.readFrom) ? variable.readFrom : [];
+      const hasOutputMappingRead = hasReadSource(readSources, 'output-mapping');
+      const hasNonOutputRead = hasReadUsage && (!readSources.length || readSources.some(source => source !== 'output-mapping'));
+      const isRead = hasNonOutputRead || (filterOptions.outputMappings && hasOutputMappingRead);
+      const isWritten = !!(variable.origin && variable.origin.some(origin => origin && origin.id === bo.id));
+
+      return matchesTypeFilter(isRead, isWritten, filterOptions)
+        && matchesScopeFilter(isLocal, filterOptions);
+    });
   }
 
   _getScope(element, containerElement, variableName, checkYourself) {
     throw new Error('not implemented VariableResolver#_getScope');
   }
-
-  /**
-   * Returns consumed variables for an element — variables
-   * the element needs as input for its expressions and mappings.
-   *
-   * Uses `getVariables()` instead of `getVariablesForElement()` to
-   * bypass the name-based deduplication that would drop requirement
-   * entries for variables that also exist in ancestor scopes.
-   *
-   * @param {Object} element
-   * @returns {Promise<Array<AvailableVariable>>}
-   */
-  async getConsumedVariablesForElement(element) {
-    const allVariablesByRoot = await this.parsedVariables.get();
-    const allVariables = Object.values(allVariablesByRoot).flat();
-
-    return allVariables.filter(v =>
-      !v.scope
-      && v.usedBy && v.usedBy.some((a) => a.id === element.id)
-    );
-  }
 }
 
 BaseVariableResolver.$inject = [ 'eventBus', 'bpmnjs' ];
@@ -496,35 +538,109 @@ function filterUsedByForElement(variable, element) {
   const elements = variable.usedBy.filter(usage => usage && usage.id);
 
   if (!variable.scope) {
-    return [ ...names, ...elements.filter(usage => isElementInScope(usage, element)) ];
+    return elements;
   }
 
   // Querying the variable's own scope: show local consumers.
   if (element.id === variable.scope.id) {
-    return [
-      ...names,
-      ...elements.filter(usage => isElementInScope(usage, variable.scope))
-    ];
+    const localConsumers = elements.filter(usage => isElementInScope(usage, variable.scope));
+
+    if (localConsumers.length) {
+      return localConsumers;
+    }
+
+    // For local mapping dependencies represented as names, expose the
+    // querying element as the consumer.
+    return names.length ? [ element ] : [];
   }
 
   // Querying an ancestor scope: show consumers outside the variable's own scope.
   if (isElementInScope(variable.scope, element)) {
-    return [
-      ...names,
-      ...elements.filter(usage =>
-        isElementInScope(usage, element)
-        && !isElementInScope(usage, variable.scope)
-      )
-    ];
+    return elements.filter(usage =>
+      isElementInScope(usage, element)
+      && !isElementInScope(usage, variable.scope)
+    );
   }
 
   // Querying a child scope: show consumers in that child scope only.
   if (isElementInScope(element, variable.scope)) {
-    return [
-      ...names,
-      ...elements.filter(usage => isElementInScope(usage, element))
-    ];
+    return elements.filter(usage => isElementInScope(usage, element));
   }
 
-  return names;
+  return [];
+}
+
+function normalizeFilterOptions(options) {
+  options = options || {};
+
+  return {
+    read: options.read !== false,
+    written: options.written !== false,
+    local: options.local !== false,
+    external: options.external !== false,
+    outputMappings: options.outputMappings !== false
+  };
+}
+
+function matchesTypeFilter(isRead, isWritten, options) {
+  if (options.read && options.written) {
+    return true;
+  }
+
+  if (options.read) {
+    return isRead;
+  }
+
+  if (options.written) {
+    return isWritten;
+  }
+
+  return false;
+}
+
+function matchesScopeFilter(isLocal, options) {
+  if (options.local && options.external) {
+    return true;
+  }
+
+  if (options.local) {
+    return isLocal;
+  }
+
+  if (options.external) {
+    return !isLocal;
+  }
+
+  return false;
+}
+
+function isSameUsageList(usagesA, usagesB) {
+  if (!Array.isArray(usagesA) || !Array.isArray(usagesB)) {
+    return false;
+  }
+
+  if (usagesA.length !== usagesB.length) {
+    return false;
+  }
+
+  const keysA = usagesA.map(getUsageKey).sort();
+  const keysB = usagesB.map(getUsageKey).sort();
+
+  return keysA.every((key, index) => key === keysB[index]);
+}
+
+function getUsageKey(usage) {
+  if (typeof usage === 'string') {
+    return `name:${usage}`;
+  }
+
+  if (usage && usage.id) {
+    return `id:${usage.id}`;
+  }
+
+  return String(usage);
+}
+
+function hasReadSource(readFrom, sourceName) {
+  return Array.isArray(readFrom) && readFrom.includes(sourceName);
 }