@sap/cds-compiler 2.11.4 → 2.13.8

package/lib/transform/db/flattening.js

@@ -1,8 +1,10 @@
 'use strict';
 
 const {
-  forEachDefinition, getUtils,
-  applyTransformations, forAllElements, isBuiltinType,
+  getUtils, walkCsnPath,
+  applyTransformations, applyTransformationsOnNonDictionary,
+  isBuiltinType, cloneCsn,
+  copyAnnotations, implicitAs, isDeepEqual,
 } = require('../../model/csnUtils');
 const transformUtils = require('../transformUtilsNew');
 const { csnRefs } = require('../../model/csnRefs');
@@ -15,26 +17,21 @@ const { setProp } = require('../../base/model');
  */
 function removeLeadingSelf(csn) {
   const magicVars = [ '$now', '$self', '$projection', '$user', '$session', '$at' ];
-  forEachDefinition(csn, (artifact, artifactName) => {
-    if (artifact.kind === 'entity' || artifact.kind === 'view') {
-      forAllElements(artifact, artifactName, (parent, elements) => {
-        for (const [ elementName, element ] of Object.entries(elements)) {
-          if (element.on) {
-            // applyTransformations expects the first thing to have a "definitions"
-            const fakeDefinitions = { definitions: {} };
-            fakeDefinitions.definitions[elementName] = element;
-            applyTransformations( fakeDefinitions, {
-              ref: (root, name, ref) => {
-                // Renderers seem to expect it to not be there...
-                if (ref[0] === '$self' && ref.length > 1 && !magicVars.includes(ref[1]))
-                  root.ref = ref.slice(1);
-              },
-            });
-          }
+  applyTransformations(csn, {
+    elements: (parent, prop, elements) => {
+      for (const [ elementName, element ] of Object.entries(elements)) {
+        if (element.on) {
+          applyTransformationsOnNonDictionary(elements, elementName, {
+            ref: (root, name, ref) => {
+              // Renderers seem to expect it to not be there...
+              if (ref[0] === '$self' && ref.length > 1 && !magicVars.includes(ref[1]))
+                root.ref = ref.slice(1);
+            },
+          });
         }
-      });
-    }
-  });
+      }
+    }, /* only for kind entity and view */                                                /* do not go into .actions */
+  }, [], { skipIgnore: false, allowArtifact: artifact => (artifact.kind === 'entity'), skipDict: { actions: true } });
 }
 
 /**
@@ -46,8 +43,9 @@ function removeLeadingSelf(csn) {
  * @param {CSN.Options} options
  * @param {WeakMap} resolved Cache for resolved refs
  * @param {string} pathDelimiter
+ * @param {object} iterateOptions
  */
-function resolveTypeReferences(csn, options, resolved, pathDelimiter) {
+function resolveTypeReferences(csn, options, resolved, pathDelimiter, iterateOptions = {}) {
   /**
    * Remove .localized from the element and any sub-elements
    *
@@ -69,15 +67,24 @@ function resolveTypeReferences(csn, options, resolved, pathDelimiter) {
     }
   }
   const { toFinalBaseType } = transformUtils.getTransformers(csn, options, pathDelimiter);
+  const { getServiceName, getFinalBaseType } = getUtils(csn);
+
+  // We don't want to iterate over actions
+  if (iterateOptions.skipDict && !iterateOptions.skipDict.actions)
+    iterateOptions.skipDict.actions = true;
+  else
+    iterateOptions.skipDict = { actions: true };
   applyTransformations(csn, {
     cast: (parent) => {
       // Resolve cast already - we otherwise lose .localized
       if (parent.cast.type && !isBuiltinType(parent.cast.type))
         toFinalBaseType(parent.cast, resolved, true);
     },
-    type: (parent, prop, type) => {
-      if (!isBuiltinType(type)) {
-        const directLocalized = parent.localized || false;
+    // @ts-ignore
+    type: (parent, prop, type, csnPath) => {
+      if (options.toOdata && parent.kind && [ 'aspect', 'event', 'type' ].includes(parent.kind))
+        return;
+      if (!isBuiltinType(type) && (!options.toOdata || options.toOdata && !isODataV4BuiltinFromService(type) && !isODataItems(type))) {
         toFinalBaseType(parent, resolved);
         // structured types might not have the child-types replaced.
         // Drill down to ensure this.
@@ -94,32 +101,74 @@ function resolveTypeReferences(csn, options, resolved, pathDelimiter) {
             }
           }
         }
-
-        if (!directLocalized)
+        const directLocalized = parent.localized || false;
+        if (!directLocalized && !options.toOdata)
           removeLocalized(parent);
       }
       // HANA/SQLite do not support array-of - turn into CLOB/Text
-      if (parent.items) {
+      if (parent.items && !options.toOdata) {
         parent.type = 'cds.LargeString';
         delete parent.items;
       }
+
+      /**
+       * OData V4 only:
+       * Do not replace a type ref if:
+       * The type definition is terminating on a scalar type (that can also be a derived type chain)
+       * AND the typeName (that is the start of that (derived) type chain is defined within the same
+       * service as the artifact from which the type reference has to be resolved.
+       *
+       * @param {string} typeName
+       * @returns {boolean}
+       */
+      function isODataV4BuiltinFromService(typeName) {
+        if (!options.toOdata || (options.toOdata && options.toOdata.version === 'v2'))
+          return false;
+
+        const typeServiceName = getServiceName(typeName);
+        const finalBaseType = getFinalBaseType(typeName);
+        // we need the service of the current definition
+        const currDefServiceName = getServiceName(csnPath[1]);
+
+        return typeServiceName === currDefServiceName && isBuiltinType(finalBaseType);
+      }
+
+      /**
+       * OData stops replacing types @ 'items', if the type ref is a user defined type
+       * AND that type has items, don't do toFinalBaseType
+       *
+       * @param {string} typeName
+       * @returns {boolean}
+       */
+      function isODataItems(typeName) {
+        const typeDef = csn.definitions[typeName];
+        return !!(options.toOdata && typeDef && typeDef.items);
+      }
     },
     // HANA/SQLite do not support array-of - turn into CLOB/Text
     items: (parent) => {
-      parent.type = 'cds.LargeString';
-      delete parent.items;
+      // OData has no LargeString substitution and doesn't expand types under items
+      if (!options.toOdata) {
+        parent.type = 'cds.LargeString';
+        delete parent.items;
+      }
     },
   }, [ (definitions, artifactName, artifact) => {
     // Replace events, actions and functions with simple dummies - they don't have effect on forHanaNew stuff
     // and that way they contain no references and don't hurt.
-    if (artifact.kind === 'action' || artifact.kind === 'function' || artifact.kind === 'event') {
+
+    // Do not do for OData
+    // TODO:factor out somewhere else
+    if (!options.toOdata &&
+      ([ 'action', 'function', 'event' ].includes(artifact.kind))) {
       const dummy = { kind: artifact.kind };
       if (artifact.$location)
         setProp(dummy, '$location', artifact.$location);
 
       definitions[artifactName] = dummy;
     }
-  } ], true, { skipDict: { actions: true } });
+    // TODO: skipDict options as default function arguments not via Object.assign
+  } ], iterateOptions);
 }
 
 /**
@@ -127,8 +176,9 @@ function resolveTypeReferences(csn, options, resolved, pathDelimiter) {
  * @param {CSN.Options} options
  * @param {WeakMap} resolved Cache for resolved refs
  * @param {string} pathDelimiter
+ * @param {object} iterateOptions
  */
-function flattenAllStructStepsInRefs(csn, options, resolved, pathDelimiter) {
+function flattenAllStructStepsInRefs(csn, options, resolved, pathDelimiter, iterateOptions = {}) {
   const { inspectRef, effectiveType } = csnRefs(csn);
   const { flattenStructStepsInRef } = transformUtils.getTransformers(csn, options, pathDelimiter);
   const adaptRefs = [];
@@ -153,6 +203,7 @@ function flattenAllStructStepsInRefs(csn, options, resolved, pathDelimiter) {
   }
 
   applyTransformations(csn, {
+    // @ts-ignore
     ref: (parent, prop, ref, path) => {
       const { links, art, scope } = inspectRef(path);
       const resolvedLinkTypes = resolveLinkTypes(links);
@@ -161,7 +212,7 @@ function flattenAllStructStepsInRefs(csn, options, resolved, pathDelimiter) {
       const fn = () => {
         const scopedPath = [ ...parent.$path ];
 
-        parent.ref = flattenStructStepsInRef(ref, scopedPath, links, scope, resolvedLinkTypes );
+        parent.ref = flattenStructStepsInRef(ref, scopedPath, links, scope, resolvedLinkTypes);
         resolved.set(parent, { links, art, scope });
         // Explicitly set implicit alias for things that are now flattened - but only in columns
         // TODO: Can this be done elegantly during expand phase already?
@@ -178,7 +229,7 @@ function flattenAllStructStepsInRefs(csn, options, resolved, pathDelimiter) {
       // adapt queries later
       adaptRefs.push(fn);
     },
-  });
+  }, [], iterateOptions);
 
   adaptRefs.forEach(fn => fn());
 
@@ -207,89 +258,102 @@ function flattenAllStructStepsInRefs(csn, options, resolved, pathDelimiter) {
  * @param {CSN.Options} options
  * @param {string} pathDelimiter
  * @param {Function} error
+ * @param {Object} iterateOptions
  */
-function flattenElements(csn, options, pathDelimiter, error) {
+function flattenElements(csn, options, pathDelimiter, error, iterateOptions = {}) {
   const { isAssocOrComposition } = getUtils(csn);
   const { flattenStructuredElement } = transformUtils.getTransformers(csn, options, pathDelimiter);
   const { effectiveType } = csnRefs(csn);
-  forEachDefinition(csn, flattenStructuredElements);
+  const transformers = {
+    elements: flatten,
+  };
+
+  if (options.toOdata) // Odata needs to flatten the .params as if it was a .elements
+    transformers.params = flatten;
+
+  applyTransformations(csn, transformers, [], iterateOptions);
+
   /**
-   * Flatten structures
+   * Flatten a given .elements or .params dictionary - keeping the order consistent.
    *
-   * @param {CSN.Artifact} art Artifact
-   * @param {string} artName Artifact Name
+   * @param {object} parent The parent object having dict at prop - parent[prop] === dict
+   * @param {string} prop
+   * @param {object} dict
+   * @param {CSN.Path} path
    */
-  function flattenStructuredElements(art, artName) {
-    forAllElements(art, artName, (parent, elements, pathToElements) => {
-      const elementsArray = [];
-      for (const elemName in elements) {
-        const pathToElement = pathToElements.concat([ elemName ]);
-        const elem = parent.elements[elemName];
-        elementsArray.push([ elemName, elem ]);
-        if (elem.elements) {
-          elementsArray.pop();
-          // Ignore the structured element, replace it by its flattened form
-          // TODO: use $ignore - _ is for links
-          elem._ignore = true;
-
-          const branches = getBranches(elem, elemName);
-          const flatElems = flattenStructuredElement(elem, elemName, [], pathToElement);
-
-          for (const flatElemName in flatElems) {
-            if (parent.elements[flatElemName])
-              error(null, pathToElement, `"${artName}.${elemName}": Flattened struct element name conflicts with existing element: "${flatElemName}"`);
-
-            const flatElement = flatElems[flatElemName];
-
-            // Check if we have a valid notNull chain
-            const branch = branches[flatElemName];
-            if (flatElement.notNull !== false && !branch.some(s => !s.notNull))
-              flatElement.notNull = true;
-
-
-            if (flatElement.type && isAssocOrComposition(flatElement.type) && flatElement.on) {
-              // Make refs resolvable by fixing the first ref step
-              for (let i = 0; i < flatElement.on.length; i++) {
-                const onPart = flatElement.on[i];
-                if (onPart.ref) {
-                  const firstRef = flatElement.on[i].ref[0];
-
-                  /*
-                      when element is defined in the current name resolution scope, like
-                        entity E {
-                          key x: Integer;
-                              s : {
-                              y : Integer;
-                              a3 : association to E on a3.x = y;
-                              }
-                        }
-                        We need to replace y with s_y and a3 with s_a3 - we must take care to not escape our local scope
-                    */
-                  const prefix = flatElement._flatElementNameWithDots.split('.').slice(0, -1).join(pathDelimiter);
-                  const possibleFlatName = prefix + pathDelimiter + firstRef;
-
-                  if (flatElems[possibleFlatName])
-                    flatElement.on[i].ref[0] = possibleFlatName;
-                }
+  function flatten(parent, prop, dict, path) {
+    if (!parent[prop].$orderedElements)
+      setProp(parent[prop], '$orderedElements', []);
+    Object.entries(dict).forEach(([ elementName, element ]) => {
+      if (element.elements) {
+        // Ignore the structured element, replace it by its flattened form
+        // TODO: use $ignore - _ is for links
+        element._ignore = true;
+
+        const branches = getBranches(element, elementName);
+        const flatElems = flattenStructuredElement(element, elementName, [], path.concat([ 'elements', elementName ]));
+
+        for (const flatElemName in flatElems) {
+          if (parent[prop][flatElemName])
+          // TODO: combine message ID with generated FK duplicate
+          // do the duplicate check in the consruct callback, requires to mark generated flat elements,
+          // check: Error location should be the existing element like @odata.foreignKey4
+            error(null, path.concat([ 'elements', elementName ]), `"${path[1]}.${elementName}": Flattened struct element name conflicts with existing element: "${flatElemName}"`);
+
+          const flatElement = flatElems[flatElemName];
+
+          // Check if we have a valid notNull chain
+          const branch = branches[flatElemName];
+          if (flatElement.notNull !== false && !branch.some(s => !s.notNull))
+            flatElement.notNull = true;
+
+
+          if (flatElement.type && isAssocOrComposition(flatElement.type) && flatElement.on) {
+            // Make refs resolvable by fixing the first ref step
+            for (const onPart of flatElement.on) {
+              if (onPart.ref) {
+                const firstRef = onPart.ref[0];
+
+                /*
+                    when element is defined in the current name resolution scope, like
+                      entity E {
+                        key x: Integer;
+                            s : {
+                            y : Integer;
+                            a3 : association to E on a3.x = y;
+                            }
+                      }
+                    We need to replace y with s_y and a3 with s_a3 - we must take care to not escape our local scope
+                  */
+                const prefix = flatElement._flatElementNameWithDots.split('.').slice(0, -1).join(pathDelimiter);
+                const possibleFlatName = prefix + pathDelimiter + firstRef;
+
+                if (flatElems[possibleFlatName])
+                  onPart.ref[0] = possibleFlatName;
               }
             }
-            elementsArray.push([ flatElemName, flatElement ]);
-            // Still add them - otherwise we might not detect collisions between generated elements.
-            parent.elements[flatElemName] = flatElement;
           }
+          parent[prop].$orderedElements.push([ flatElemName, flatElement ]);
+          // Still add them - otherwise we might not detect collisions between generated elements.
+          parent[prop][flatElemName] = flatElement;
         }
       }
-      //  Don't fake consistency of the model by adding empty elements {}
-      if (elementsArray.length === 0)
-        return;
+      else {
+        parent[prop].$orderedElements.push([ elementName, element ]);
+      }
+    });
 
-      parent.elements = elementsArray.reduce((previous, [ name, element ]) => {
-        previous[name] = element;
-        return previous;
-      }, Object.create(null));
-    }, true);
+    // $orderedElements is removed by reducing and assigning a new dictionary
+    parent[prop] = parent[prop].$orderedElements.reduce((elements, [ name, element ]) => {
+      // rewrite $path to match the flattened dictionary entry
+      // ([ 'definitions', artName ] remain constant
+      setProp(element, '$path', [ ...path, prop, name ]);
+      elements[name] = element;
+      return elements;
+    }, Object.create(null));
   }
 
+
   /**
    * Get not just the leafs, but all the branches of a structured element
    *
@@ -305,11 +369,11 @@ function flattenElements(csn, options, pathDelimiter, error) {
     /**
      * Walk the element chain
      *
-     * @param {CSN.Element} e
+     * @param {object} e
      * @param {string} name
      */
     function walkElements(e, name) {
-      if (isBuiltinType(e)) {
+      if (isBuiltinType(e.type)) {
         branches[subbranchNames.concat(name).join(pathDelimiter)] = subbranchElements.concat(e);
       }
       else {
@@ -333,9 +397,392 @@ function flattenElements(csn, options, pathDelimiter, error) {
   }
 }
 
+/**
+ * @param {CSN.Model} csn
+ * @param {CSN.Options} options
+ * @param {Function} error
+ * @param {string} pathDelimiter
+ * @param {boolean} flattenKeyRefs
+ * @param {object} iterateOptions
+ */
+function handleManagedAssociationsAndCreateForeignKeys(csn, options, error, pathDelimiter, flattenKeyRefs, iterateOptions = {}) {
+  const { isManagedAssociation, inspectRef, isStructured } = getUtils(csn);
+  const { flattenStructStepsInRef, flattenStructuredElement } = transformUtils.getTransformers(csn, options, pathDelimiter);
+  if (flattenKeyRefs) {
+    applyTransformations(csn, {
+      elements: (parent, prop, elements, path) => {
+        Object.entries(elements).forEach(([ elementName, element ]) => {
+          if (isManagedAssociation(element)) {
+          // replace foreign keys that are managed associations by their respective foreign keys
+            flattenFKs(element, elementName, [ ...path, 'elements', elementName ]);
+          }
+        });
+      },
+    }, [], {
+      skipIgnore: false,
+      allowArtifact: artifact => (artifact.kind === 'entity' || artifact.kind === 'type'),
+      skipDict: { actions: true },
+    });
+  }
+  createForeignKeyElements();
+
+  /**
+   * Flattens all foreign keys
+   *
+   * Structures will be resolved to individual elements with scalar types
+   *
+   * Associations will be replaced by their respective foreign keys
+   *
+   * If a structure contains an assoc, this will also be resolved and vice versa
+   *
+   * @param {*} assoc
+   * @param {*} assocName
+   * @param {*} path
+   */
+  function flattenFKs(assoc, assocName, path) {
+    let finished = false;
+    while (!finished) {
+      const newKeys = [];
+      finished = processKeys(newKeys);
+      assoc.keys = newKeys;
+    }
+
+    // @ts-ignore
+    /**
+     * Walk over the keys and replace structures by their leafs, managed associations by their foreign keys and keep scalar values as-is.
+     *
+     * @param {object[]} collector New keys array to collect the flattened stuff in
+     * @returns {boolean} True if all keys are scalar - false if there are things that still need to be processed.
+     */
+    function processKeys(collector) {
+      const inferredAlias = '$inferredAlias';
+
+      let done = true;
+      for (let i = 0; i < assoc.keys.length; i++) {
+        const pathToKey = path.concat([ 'keys', i ]);
+        const { art } = inspectRef(pathToKey);
+        const { ref } = assoc.keys[i];
+        if (isStructured(art)) {
+          done = false;
+          // Mark this element to filter it later - not needed after expansion
+          setProp(assoc.keys[i], '$toDelete', true);
+          const flat = flattenStructuredElement(art, ref[ref.length - 1], [], pathToKey);
+          Object.keys(flat).forEach((flatElemName) => {
+            const key = assoc.keys[i];
+            const clone = cloneCsn(assoc.keys[i], options);
+            if (clone.as) {
+              const lastRef = clone.ref[clone.ref.length - 1];
+              // Cut off the last ref part from the beginning of the flat name
+              const flatBaseName = flatElemName.slice(lastRef.length);
+              // Join it to the existing table alias
+              clone.as += flatBaseName;
+              // do not loose the $ref for nested keys
+              if (key.$ref) {
+                let aliasedLeaf = key.$ref[key.$ref.length - 1];
+                aliasedLeaf += flatBaseName;
+                setProp(clone, '$ref', key.$ref.slice(0, key.$ref.length - 1).concat(aliasedLeaf));
+              }
+            }
+            if (clone.ref) {
+              clone.ref[clone.ref.length - 1] = flatElemName;
+              // Now we need to properly flatten the whole ref
+              clone.ref = flattenStructStepsInRef(clone.ref, pathToKey);
+            }
+            if (!clone.as) {
+              clone.as = flatElemName;
+              // TODO: can we use $inferred? Does it have other weird side-effects?
+              setProp(clone, inferredAlias, true);
+            }
+            // Directly work on csn.definitions - this way the changes take effect in csnRefs/inspectRef immediately
+            // Add the newly generated foreign keys to the end - they will be picked up later on
+            // Recursive solutions run into call stack issues
+            collector.push(clone);
+          });
+        }
+        else if (art.target) {
+          done = false;
+          // Mark this element to filter it later - not needed after expansion
+          setProp(assoc.keys[i], '$toDelete', true);
+          // Directly work on csn.definitions - this way the changes take effect in csnRefs/inspectRef immediately
+          // Add the newly generated foreign keys to the end - they will be picked up later on
+          // Recursive solutions run into call stack issues
+          art.keys.forEach(key => collector.push(cloneAndExtendRef(key, assoc.keys[i], ref)));
+        }
+        else if (assoc.keys[i].ref && !assoc.keys[i].as) {
+          setProp(assoc.keys[i], inferredAlias, true);
+          if (!(options.toOdata && assoc.keys[i].ref.length === 1))
+          // In OData backend there are no aliases assigned when the same as the ref
+          // TODO: remove the if after the new flattening in OData has been compleated
+            assoc.keys[i].as = assoc.keys[i].ref[assoc.keys[i].ref.length - 1];
+          collector.push(assoc.keys[i]);
+        }
+        else {
+          collector.push(assoc.keys[i]);
+        }
+      }
+      return done;
+    }
+    assoc.keys = assoc.keys.filter(o => !o.$toDelete);
+
+    /**
+     * Clone base and extend the .ref and .as of the clone with the .ref and .as of ref.
+     *
+     * @param {object} key A foreign key entry (of a managed assoc as a fk of another assoc)
+     * @param {object} base The fk-ref that has key as a fk
+     * @param {Array} ref
+     * @returns {object} The clone of base
+     */
+    function cloneAndExtendRef(key, base, ref) {
+      const clone = cloneCsn(base, options);
+      if (key.ref) {
+        // We build a ref that contains the aliased fk - that element will be created later on, so this ref is not resolvable yet
+        // Therefore we keep it as $ref - ref is the non-aliased, resolvable "clone"
+        // Later on, after we know that these foreign key elements are created, we replace ref with this $ref
+        let $ref;
+        if (base.$ref) {
+          // if a base $ref is provided, use it to correctly resolve association chains
+          const refChain = [ base.$ref[base.$ref.length - 1] ].concat(key.as || key.ref);
+          $ref = base.$ref.slice(0, base.$ref.length - 1).concat(refChain);
+        }
+        else {
+          $ref = base.ref.concat(key.as || key.ref); // Keep along the aliases
+        }
+        setProp(clone, '$ref', $ref);
+        clone.ref = clone.ref.concat(key.ref);
+      }
+
+      if (!clone.as && clone.ref && clone.ref.length > 0) {
+        clone.as = ref[ref.length - 1] + pathDelimiter + (key.as || key.ref.join(pathDelimiter));
+        // TODO: can we use $inferred? Does it have other weird side-effects?
+        setProp(clone, '$inferredAlias', true);
+      }
+      else {
+        clone.as += pathDelimiter + (key.as || key.ref.join(pathDelimiter));
+      }
+
+      return clone;
+    }
+  }
+
+  /**
+   * Create the foreign key elements in all .elements things
+   */
+  function createForeignKeyElements() {
+    const transformers = {
+      elements: createFks,
+    };
+    if (options.toOdata)
+      transformers.params = createFks;
+
+    applyTransformations(csn, transformers, [], Object.assign({ skipIgnore: false }, iterateOptions));
+
+    /**
+     * Process a given .elements or .params dictionary and create foreign key elements
+     *
+     * @param {object} parent The thing HAVING params or elements
+     * @param {string} prop
+     * @param {object} dict The params or elements thing
+     * @param {CSN.Path} path
+     */
+    function createFks(parent, prop, dict, path) {
+      const orderedElements = [];
+      Object.entries(dict).forEach(([ elementName, element ]) => {
+        orderedElements.push([ elementName, element ]);
+        const eltPath = path.concat(prop, elementName);
+        const fks = createForeignKeysInternal(eltPath, element, elementName, csn, options, pathDelimiter);
+
+        // finalize the generated foreign keys
+        const refCount = fks.reduce((acc, fk) => {
+          // count duplicates
+          if (acc[fk[0]])
+            acc[fk[0]]++;
+          else
+            acc[fk[0]] = 1;
+
+          // check for name clash with existing elements
+          if ((parent[prop][fk[0]]) &&
+          ((options.toOdata && isDeepEqual(element, parent[prop][fk[0]], true)) ||
+            !options.toOdata)) {
+            // error location is the colliding element
+            error(null, eltPath, { name: fk[0], art: elementName },
+                  'Generated foreign key element $(NAME) for association $(ART) conflicts with existing element');
+          }
+          // attach a proper $path
+          setProp(element, '$path', eltPath);
+          return acc;
+        }, Object.create(null));
+
+        // check for duplicate foreign keys
+        Object.entries(refCount).forEach(([ name, occ ]) => {
+          if (occ > 1) {
+            error(null, eltPath, { name },
+                  'Duplicate definition of foreign key element $(NAME)');
+          }
+        });
+        if (element.keys) {
+          element.keys.forEach((key, i) => {
+            // Assumption: If all key refs have been flattened, there is a
+            // 1:1 match to the corresponding foreign key element. Order is the
+            // same, so an index access should work
+            if (flattenKeyRefs) {
+              key.$generatedFieldName = fks[i][0];
+              key.ref = [ (key.$ref || key.ref).join(pathDelimiter) ];
+              delete key.$ref;
+              // TODO: remove the if after the new flattening in OData has been completed
+              if (options.toOdata && key.as && key.as === key.ref[0])
+                delete key.as;
+            }
+          });
+          // OData specific:
+          // Not Null sets min cardinality to 1
+          if (options.toOdata && element.notNull) {
+            if (element.cardinality === undefined)
+              element.cardinality = {};
+              // min=0 is falsy => check for undefined
+            if (element.cardinality.min === undefined)
+              element.cardinality.min = 1;
+          }
+        }
+        orderedElements.push(...fks);
+      });
+
+      parent[prop] = orderedElements.reduce((elementsAccumulator, [ name, element ]) => {
+        elementsAccumulator[name] = element;
+        return elementsAccumulator;
+      }, Object.create(null));
+    }
+  }
+}
+
+/**
+ * This is the internal version of the foreign key procedure.
+ *
+ * If element is not a managed association, an empty array is returned
+ *
+ * @param {Array|object} path CSN path pointing to element or the result of a previous call to inspectRef
+ * @param {CSN.Element} element
+ * @param {string} prefix Element name
+ * @param {CSN.Model} csn
+ * @param {object} options
+ * @param {string} pathDelimiter
+ * @param {number} lvl
+ * @returns {Array[]} First element of every sub-array is the foreign key name, second is the foreign key definition
+ */
+function createForeignKeysInternal(path, element, prefix, csn, options, pathDelimiter, lvl = 0) {
+  const {
+    effectiveType,
+    inspectRef,
+  } = getUtils(csn);
+
+
+  const isInspectRefResult = !Array.isArray(path);
+
+  let fks = [];
+  if (!element)
+    return fks;
+
+  let finalElement = element;
+  // TODO: effectiveType's return value is 'path' for the next inspectRef
+  if (element.type && !isBuiltinType(element.type)) {
+    const tmpElt = effectiveType(element);
+    // effective type resolves to structs and enums only but not scalars
+    if (Object.keys(tmpElt).length) {
+      finalElement = tmpElt;
+    }
+    else {
+      // unwind a derived type chain to a scalar type
+      while (finalElement.type && !isBuiltinType(finalElement.type))
+        finalElement = csn.definitions[finalElement.type];
+    }
+  }
+
+  if (finalElement.target && !finalElement.on) {
+    const hasKeys = !!finalElement.keys;
+    if (!hasKeys) {
+      const target = csn.definitions[finalElement.target];
+
+      setProp(finalElement, 'keys', [ ] );
+      if (target && target.elements) {
+        finalElement.keys = Object.entries(target.elements).filter(([ _n, e ]) => e.key)
+          . map(([ n, _e ]) => ({ ref: [ n ], as: n }));
+      }
+    }
+    // TODO: has managed assoc keys?
+    finalElement.keys.forEach((key, keyIndex) => {
+      const continuePath = isInspectRefResult ? [ path, 'keys', keyIndex ] : [ ...path, 'keys', keyIndex ];
+      const alias = key.as || implicitAs(key.ref);
+      const result = inspectRef(continuePath);
+      fks = fks.concat(createForeignKeysInternal(result, result.art, alias, csn, options, pathDelimiter, lvl + 1));
+    });
+    if (!hasKeys)
+      delete finalElement.keys;
+  }
+  // return if the toplevel element is not a managed association
+  else if (lvl === 0) {
+    return fks;
+  }
+  // we have reached a leaf element, create a foreign key
+  else if (finalElement && isBuiltinType(finalElement.type)) {
+    const newFk = Object.create(null);
+    for (const prop of [ 'type', 'length', 'scale', 'precision', 'srid', 'default', '@odata.Type' ]) {
+      // copy props from original element to preserve derived types!
+      if (element[prop] !== undefined)
+        newFk[prop] = element[prop];
+    }
+    return [ [ prefix, newFk ] ];
+  }
+  else if (finalElement.elements) {
+    Object.entries(finalElement.elements).forEach(([ elemName, elem ]) => {
+      // Skip already produced foreign keys
+      if (!elem['@odata.foreignKey4']) {
+        const continuePath = isInspectRefResult ? [ path, 'elements', elemName ] : [ ...path, 'elements', elemName ];
+        fks = fks.concat(createForeignKeysInternal(continuePath, elem, elemName, csn, options, pathDelimiter, lvl + 1));
+      }
+    });
+  }
+
+  fks.forEach((fk) => {
+    // prepend current prefix
+    fk[0] = `${prefix}${pathDelimiter}${fk[0]}`;
+    // if this is the entry association, decorate the final foreign keys with the association props
+    if (lvl === 0) {
+      fk[1]['@odata.foreignKey4'] = prefix;
+      if (!options.forHana)
+        copyAnnotations(element, fk[1], true);
+
+      // propagate not null to final foreign key
+      for (const prop of [ 'notNull', 'key' ]) {
+        if (element[prop] !== undefined)
+          fk[1][prop] = element[prop];
+      }
+      if (element.$location)
+        setProp(fk[1], '$location', element.$location);
+    }
+  });
+  return fks;
+}
+
+/**
+ * This is the public createForeignKeys function that has no side effects
+ *
+ * @param {CSN.Path} path Path to the managed association
+ * @param {CSN.Model} csn
+ * @param {string} pathDelimiter
+ * @returns {Array}
+ */
+function createForeignKeys(path, csn, pathDelimiter = '_') {
+  if (!path || !Array.isArray(path))
+    throw Error('path must be a CSN path array');
+  if (!csn || typeof csn !== 'object')
+    throw Error('csn not provided');
+  return createForeignKeysInternal(path, walkCsnPath(csn, path), path[path.length - 1], csn, {}, pathDelimiter);
+}
+
 module.exports = {
   resolveTypeReferences,
   flattenAllStructStepsInRefs,
   flattenElements,
   removeLeadingSelf,
+  handleManagedAssociationsAndCreateForeignKeys,
+  createForeignKeys,
 };