@sap/cds-compiler 2.11.4 → 2.13.8

package/lib/transform/draft/odata.js

@@ -0,0 +1,227 @@
+'use strict';
+
+const { forEachDefinition, getUtils, getServiceNames } = require('../../model/csnUtils');
+const { forEach } = require('../../utils/objectUtils');
+const { isArtifactInSomeService, getServiceOfArtifact } = require('../odata/utils');
+const { getTransformers } = require('../transformUtilsNew');
+const { ModelError } = require('../../base/error');
+const { makeMessageFunction } = require('../../base/messages');
+
+/**
+ * - Generate artificial draft fields if requested
+ *
+ * - Check associations for:
+ *      - exposed associations do not point to non-exposed targets
+ *      - structured types must not contain associations for OData V2
+ * - Element must not be an 'array of' for OData V2 TODO: move to the validator
+ * - Perform checks for exposed non-abstract entities and views - check media type and key-ness
+ *
+ * @param {CSN.Model} csn
+ * @param {CSN.Options} options
+ * @param {Array} [services] Will be calculated JIT if not provided
+ * @returns {CSN.Model} Returns the transformed input model
+ * @todo should be done by the compiler - Check associations for valid foreign keys
+ * @todo check if needed at all: Remove '$projection' from paths in the element's ON-condition
+ */
+function generateDrafts(csn, options, services) {
+  const {
+    createForeignKeyElement,
+    createAndAddDraftAdminDataProjection, createScalarElement,
+    createAssociationElement, createAssociationPathComparison,
+    addElement, createAction, assignAction,
+    resetAnnotation,
+  } = getTransformers(csn, options);
+
+  const {
+    getFinalType,
+    getServiceName,
+    hasAnnotationValue,
+    getFinalBaseType,
+    getFinalTypeDef,
+  } = getUtils(csn);
+
+  const { error, info } = makeMessageFunction(csn, options, 'for.odata');
+
+  if (!services)
+    services = getServiceNames(csn);
+
+  const visitedArtifacts = Object.create(null);
+  // @ts-ignore
+  const externalServices = services.filter(serviceName => csn.definitions[serviceName]['@cds.external']);
+  // @ts-ignore
+  const isExternalServiceMember = (_art, name) => externalServices.includes(getServiceName(name));
+
+  forEachDefinition(csn, (def, defName) => {
+    // Generate artificial draft fields for entities/views if requested, ignore if not part of a service
+    if (def.kind === 'entity' && def['@odata.draft.enabled'] && isArtifactInSomeService(defName, services))
+      generateDraftForOdata(def, defName, def);
+
+    visitedArtifacts[defName] = true;
+  }, { skipArtifact: isExternalServiceMember });
+
+  return csn;
+  /**
+   * Generate all that is required in ODATA for draft enablement of 'artifact' into the artifact,
+   * into its transitively reachable composition targets, and into the model.
+   * 'rootArtifact' is the root artifact where composition traversal started.
+   *
+   * Constraints
+   * Draft Root: Exactly one PK of type UUID
+   * Draft Node: One PK of type UUID + 0..1 PK of another type
+   * Draft Node: Must not be reachable from multiple draft roots
+   *
+   * @param {CSN.Artifact} artifact
+   * @param {string} artifactName
+   * @param {CSN.Artifact} rootArtifact artifact where composition traversal started
+   */
+  function generateDraftForOdata(artifact, artifactName, rootArtifact) {
+    // Sanity check
+    // @ts-ignore
+    if (!isArtifactInSomeService(artifactName, services))
+      throw new ModelError(`Expecting artifact to be part of a service: ${JSON.stringify(artifact)}`);
+
+    // Nothing to do if already draft-enabled (composition traversal may have circles)
+    if ((artifact['@Common.DraftRoot.PreparationAction'] || artifact['@Common.DraftNode.PreparationAction']) &&
+        artifact.actions && artifact.actions.draftPrepare)
+      return;
+
+
+    // Generate the DraftAdministrativeData projection into the service, unless there is already one
+    // @ts-ignore
+    const draftAdminDataProjectionName = `${getServiceOfArtifact(artifactName, services)}.DraftAdministrativeData`;
+    let draftAdminDataProjection = csn.definitions[draftAdminDataProjectionName];
+    if (!draftAdminDataProjection) {
+      // @ts-ignore
+      draftAdminDataProjection = createAndAddDraftAdminDataProjection(getServiceOfArtifact(artifactName, services));
+    }
+    // Report an error if it is not an entity or not what we expect
+    if (draftAdminDataProjection.kind !== 'entity' || !draftAdminDataProjection.elements.DraftUUID) {
+      error(null, [ 'definitions', draftAdminDataProjectionName ], { name: draftAdminDataProjectionName },
+            'Generated entity $(NAME) conflicts with existing artifact');
+    }
+    // Generate the annotations describing the draft actions (only draft roots can be activated/edited)
+    if (artifact === rootArtifact) {
+      resetAnnotation(artifact, '@Common.DraftRoot.ActivationAction', 'draftActivate', info, [ 'definitions', draftAdminDataProjectionName ]);
+      resetAnnotation(artifact, '@Common.DraftRoot.EditAction', 'draftEdit', info, [ 'definitions', draftAdminDataProjectionName ]);
+      resetAnnotation(artifact, '@Common.DraftRoot.PreparationAction', 'draftPrepare', info, [ 'definitions', draftAdminDataProjectionName ]);
+    }
+    else {
+      resetAnnotation(artifact, '@Common.DraftNode.PreparationAction', 'draftPrepare', info, [ 'definitions', draftAdminDataProjectionName ]);
+    }
+
+    Object.values(artifact.elements || {}).forEach( (elem) => {
+      // Make all non-key elements nullable
+      if (elem.notNull && elem.key !== true)
+        delete elem.notNull;
+    });
+    // Generate the additional elements into the draft-enabled artifact
+
+    // key IsActiveEntity : Boolean default true
+    const isActiveEntity = createScalarElement('IsActiveEntity', 'cds.Boolean', true, true, false);
+    isActiveEntity.IsActiveEntity['@UI.Hidden'] = true;
+    addElement(isActiveEntity, artifact, artifactName);
+
+    // HasActiveEntity : Boolean default false
+    const hasActiveEntity = createScalarElement('HasActiveEntity', 'cds.Boolean', false, false, true);
+    hasActiveEntity.HasActiveEntity['@UI.Hidden'] = true;
+    addElement(hasActiveEntity, artifact, artifactName);
+
+    // HasDraftEntity : Boolean default false;
+    const hasDraftEntity = createScalarElement('HasDraftEntity', 'cds.Boolean', false, false, true);
+    hasDraftEntity.HasDraftEntity['@UI.Hidden'] = true;
+    addElement(hasDraftEntity, artifact, artifactName);
+
+    // @odata.contained: true
+    // DraftAdministrativeData : Association to one DraftAdministrativeData;
+    const draftAdministrativeData = createAssociationElement('DraftAdministrativeData', draftAdminDataProjectionName, true);
+    draftAdministrativeData.DraftAdministrativeData.cardinality = { max: 1 };
+    draftAdministrativeData.DraftAdministrativeData['@odata.contained'] = true;
+    draftAdministrativeData.DraftAdministrativeData['@UI.Hidden'] = true;
+    addElement(draftAdministrativeData, artifact, artifactName);
+
+    // Note that we need to do the ODATA transformation steps for managed associations
+    // (foreign key field generation, generatedFieldName) by hand, because the corresponding
+    // transformation steps have already been done on all artifacts when we come here)
+    let uuidDraftKey = draftAdministrativeData.DraftAdministrativeData.keys.filter(key => key.ref && key.ref.length === 1 && key.ref[0] === 'DraftUUID');
+    if (uuidDraftKey && uuidDraftKey[0]) {
+      uuidDraftKey = uuidDraftKey[0]; // filter returns an array, but it has only one element
+      const path = [ 'definitions', artifactName, 'elements', 'DraftAdministrativeData', 'keys', 0 ];
+      createForeignKeyElement(draftAdministrativeData.DraftAdministrativeData, 'DraftAdministrativeData', uuidDraftKey, artifact, artifactName, path);
+    }
+    // SiblingEntity : Association to one <artifact> on (... IsActiveEntity unequal, all other key fields equal ...)
+    const siblingEntity = createAssociationElement('SiblingEntity', artifactName, false);
+    siblingEntity.SiblingEntity.cardinality = { max: 1 };
+    addElement(siblingEntity, artifact, artifactName);
+    // ... on SiblingEntity.IsActiveEntity != IsActiveEntity ...
+    siblingEntity.SiblingEntity.on = createAssociationPathComparison('SiblingEntity', 'IsActiveEntity', '!=', 'IsActiveEntity');
+
+    // Iterate elements
+    // TODO: Iterative vs recursive? What is more likely: Super deep nesting or cycles via malicious CSN?
+    if (artifact.elements) {
+      // No need to reverse the stack, not order dependent
+      const stack = [ artifact ];
+      while (stack.length > 0) {
+        const { elements } = stack.pop();
+        forEach(elements, (elemName, elem) => {
+          if (elemName !== 'IsActiveEntity' && elem.key) {
+            // Amend the ON-condition above:
+            // ... and SiblingEntity.<keyfield> = <keyfield> ... (for all key fields except 'IsActiveEntity')
+            const cond = createAssociationPathComparison('SiblingEntity', elemName, '=', elemName);
+            cond.push('and');
+            cond.push(...siblingEntity.SiblingEntity.on);
+            siblingEntity.SiblingEntity.on = cond;
+          }
+
+          // Draft-enable the targets of composition elements (draft nodes), too
+          // TODO rewrite
+          if (elem.target && elem.type && getFinalType(elem.type) === 'cds.Composition') {
+            const draftNode = csn.definitions[elem.target];
+
+            // Ignore if that is our own draft root
+            if (draftNode !== rootArtifact) {
+              // Report error when the draft node has @odata.draft.enabled itself
+              if (hasAnnotationValue(draftNode, '@odata.draft.enabled', true)) {
+                error('ref-unexpected-draft-enabled', [ 'definitions', artifactName, 'elements', elemName ], { anno: '@odata.draft.enabled' });
+              }
+              // Ignore composition if it's target is not part of a service or explicitly draft disabled
+              else if (!getServiceName(elem.target) || hasAnnotationValue(draftNode, '@odata.draft.enabled', false)) {
+                return;
+              }
+              else {
+                // Generate draft stuff into the target
+                generateDraftForOdata(draftNode, elem.target, rootArtifact);
+              }
+            }
+          }
+          else if (elem.elements) { // anonymous structure
+            stack.push(elem);
+          }
+          else if (elem.type) { // types - possibly structured
+            const typeDef = elem.type.ref ? getFinalBaseType(elem.type) : getFinalTypeDef(elem.type);
+            if (typeDef.elements)
+              stack.push(typeDef);
+          }
+        });
+      }
+    }
+
+
+    // Generate the actions into the draft-enabled artifact (only draft roots can be activated/edited)
+
+    // action draftPrepare (SideEffectsQualifier: String) return <artifact>;
+    const draftPrepare = createAction('draftPrepare', artifactName, 'SideEffectsQualifier', 'cds.String');
+    assignAction(draftPrepare, artifact);
+
+    if (artifact === rootArtifact) {
+      // action draftActivate() return <artifact>;
+      const draftActivate = createAction('draftActivate', artifactName);
+      assignAction(draftActivate, artifact);
+
+      // action draftEdit (PreserveChanges: Boolean) return <artifact>;
+      const draftEdit = createAction('draftEdit', artifactName, 'PreserveChanges', 'cds.Boolean');
+      assignAction(draftEdit, artifact);
+    }
+  }
+}
+
+module.exports = generateDrafts;