cap-domain 3.0.0

package/src/Handlers.js

@@ -0,0 +1,273 @@
+const { getEntityName, createMockEntity } = require('./Utils.js');
+const { getEntityFC } = require('./SymbolHelper');
+
+/**
+ * Bind field control handlers to a field control entity instance.
+ * @param {object} fc The field control instance.
+ * @returns {object} Object with bound handlers
+ */
+function bindHandlers(fc) {
+  /**
+   * Provides structured errors to the request based on a given prefix.
+   * @param {object} req The CDS request object.
+   * @param {Array<object>} errors An array of error objects, each with at least `fieldName` and `message` properties.
+   * @param {object} csnEntity The CSN entity definition.
+   * @param {string} [targetPrefix] Optional prefix for the error target. If not provided, it will be calculated.
+   */
+  function provideErrors(req, errors, csnEntity, targetPrefix) {
+    if (!errors || !errors.length) {
+      return;
+    }
+
+    /**
+     * Builds a property string from an object of descriptors.
+     * @param {object} descriptors An object where keys are property names and values are objects with a `value` property.
+     * @returns {string} A comma-separated string of key=value pairs.
+     */
+    function buildPropertyString(descriptors) {
+      /**
+       * @param {string} key Entity field
+       */
+      function isStringType(key) {
+        return csnEntity.elements[key].type === 'cds.String';
+      }
+
+      const keys = Object.entries(descriptors);
+
+      if (keys.length === 1) {
+        return keys.map(([, desc]) => desc.value).at(0);
+      }
+
+      return keys.map(([key, desc]) => isStringType(key) ? `${key}='${desc.value}'` : `${key}=${desc.value}`)
+        .join(',');
+    }
+
+    /**
+     * Calculates the prefix for error targets based on request parameters and entity name.
+     * @returns {string} The calculated prefix.
+     */
+    function calculatePrefix() {
+      const params = buildPropertyString(Object.getOwnPropertyDescriptors(req.params[0]));
+
+      const entityName = getEntityName(csnEntity);
+
+      return `/${entityName}(${params})`;
+    }
+
+    const prefix = targetPrefix || calculatePrefix();
+
+    errors.forEach(({ fieldName, message }) => {
+      req.error({
+        target: `${prefix}/${fieldName}`,
+        message,
+        description: message,
+        code: 400
+      });
+    });
+  }
+
+  /**
+   * Validates data with field controls, merging with a database record and calculating field controls.
+   * @param {object} req The CDS request object.
+   * @param {object} dataForValidation The data to be validated.
+   * @param {object} context The context object.
+   * @returns {Promise<object>} An object containing the original database record, the database record with virtual updates and calculated field controls, and any validation errors.
+   */
+  async function validateWithFCs(req, dataForValidation, context) {
+    const dbRecord = req.params.at(0) ? await SELECT.one.from(req.target).where(req.params.at(0)) : null;
+
+    const mergedRecord = Object.assign({}, dbRecord, dataForValidation);
+    const dbRecordWithVirtualUpdate = await fc.calculateFieldControls(mergedRecord, req, context);
+
+    // Mock defaults only make sense when there is no persisted record yet (CREATE);
+    // for an existing record, unrelated untouched fields must keep their real values.
+    const diffForValidation = fc.configuration.liveValidations && !dbRecord
+      ? Object.assign(createMockEntity(req.target.name), dataForValidation)
+      : mergedRecord;
+    const { errors, fieldControlAnnotationValues } = await fc.validatePayload(dbRecordWithVirtualUpdate, diffForValidation, dataForValidation, dbRecord || {});
+
+    return {
+      dbRecord,
+      dbRecordWithVirtualUpdate,
+      errors,
+      fieldControlAnnotationValues
+    };
+  }
+
+  // 1. Calculate FC for the DB record
+  // 2. Merge DB record with changes and calculate FCs
+  // 3. Apply validations
+  // 4. Compare FC from steps 1 and 2
+  // 5. Erase Fields which changed their FCs from Optional/Mandatory to Readonly/Hidden
+  /**
+   * Handles the UPDATE operation, including field control calculation, validation, and saving.
+   * @param {object} req The CDS request object.
+   * @param {Function} next The next middleware function.
+   * @param {object} context The context object.
+   * @returns {Promise<object>} The record after applying field control calculations.
+   */
+  async function UPDATEHandler(req, next, context) {
+    const { errors, dbRecordWithVirtualUpdate, fieldControlAnnotationValues } = await validateWithFCs(req, req.data, context);
+
+    fc.configuration.liveValidations && provideErrors(req, errors, fc.csnEntity);
+
+    fc.eraseUnavailableDynamicFields(dbRecordWithVirtualUpdate, req.data, fc.configuration, fieldControlAnnotationValues);
+
+    await fc.callOnBeforeSave(dbRecordWithVirtualUpdate, req, context);
+
+    const record = await next();
+
+    return await fc.calculateFieldControls(record, req, context);
+  }
+
+  /**
+   * Handles the DRAFT_PREPARE operation, including field control calculation and validation for draft entities.
+   * @param {object} req The CDS request object.
+   * @param {Function} next The next middleware function.
+   * @returns {Promise<object>} The record after applying field control calculations for the draft.
+   */
+  async function DRAFTPrepareHandler(req, next) {
+    const dbRecord = await SELECT.one.from(req.target).where(req.params.at(0));
+
+    const dbRecordWithFCs = await fc.calculateFieldControls(dbRecord, req);
+
+    const dbRecordWithVirtualUpdate = await fc.calculateFieldControls(Object.assign({}, dbRecord, req.data), req);
+
+    const { errors } = await fc.validatePayload(dbRecordWithFCs, dbRecordWithFCs);
+
+    provideErrors(req, errors, fc.csnEntity, 'in');
+
+    await fc.callOnBeforeSave(dbRecordWithVirtualUpdate, req);
+
+    const record = await next();
+
+    await fc.callOnAfterSave(dbRecordWithVirtualUpdate, req);
+
+    return await fc.calculateFieldControls(record, req);
+  }
+
+  /**
+   * Handles the READ operation, applying field control calculations to the entity data.
+   * @param {object} entity The entity data being read.
+   * @param {object} req The CDS request object.
+   * @param {object} context The context object.
+   * @returns {Promise<object>} The entity data after applying field control calculations.
+   */
+  async function READHandler(entity, req, context) {
+    return await fc.calculateFieldControls(entity, req, context);
+  }
+
+  /**
+   * Handles the CREATE_DRAFT operation, applying field control calculations to the newly created draft record.
+   * @param {object} req The CDS request object.
+   * @param {Function} next The next middleware function.
+   * @returns {Promise<object>} The draft record after applying field control calculations.
+   */
+  async function CreateDraftHandler(req, next) {
+    const record = await next();
+
+    return await fc.calculateFieldControls(record, req);
+  }
+
+  return {
+    UPDATEHandler,
+    DRAFTPrepareHandler,
+    READHandler,
+    CreateDraftHandler,
+    validateWithFCs,
+    provideErrors
+  };
+}
+
+/**
+ * Bind field control handlers to a field control instance for a specific entity.
+ * @param {string} csnEntity CSN entity definition
+ * @returns {object} Object with bound handlers
+ */
+function bindEntityHandlers(csnEntity) {
+  const fc = getEntityFC(csnEntity);
+
+  return bindHandlers(fc);
+}
+
+/**
+ * Provide structured errors to the request.
+ * @param {object} req The CDS request object.
+ * @param {Array} errors Array of error objects.
+ * @param {string} targetPrefix Error target prefix.x
+ */
+function provideErrors(req, errors, targetPrefix) {
+  const csnEntity = req.target;
+  const { provideErrors } = bindEntityHandlers(csnEntity);
+
+  provideErrors(req, errors, csnEntity, targetPrefix);
+}
+
+/**
+ * Throw errors and stop request if errors exist.
+ * @param {object} req The CDS request object.
+ * @param {Array} args Error arguments.
+ */
+function throwErrorsAndStopIfExists(req, ...args) {
+  provideErrors(req, ...args);
+
+  if (req?.errors?.length) {
+    req.reject();
+  }
+}
+
+/**
+ * Validate data with field controls and return errors.
+ * @param {object} req The CDS request object.
+ * @param {object} dataForValidation Data to validate.
+ * @param {object} context Context
+ * @returns {Promise<Array>} Array of validation errors.
+ */
+async function validateWithFCs(req, dataForValidation, context) {
+  const { validateWithFCs } = bindEntityHandlers(req.target);
+
+  return await validateWithFCs(req, dataForValidation, context);
+}
+
+module.exports = {
+  async calculateFieldControls(data, req, { csnEntity, context = {} }) {
+    const fc = getEntityFC(csnEntity || req.target);
+
+    return await fc.calculateFieldControls(data, req, { context });
+  },
+  bindHandlers,
+  bindEntityHandlers,
+  async execAfterREADHandler(entity, req, context) {
+    const { READHandler } = bindEntityHandlers(req.target);
+
+    return await READHandler(entity, req, context);
+  },
+
+  async execUPDATEHandler(req, next, context) {
+    const { UPDATEHandler } = bindEntityHandlers(req.target);
+
+    return await UPDATEHandler(req, next, context);
+  },
+
+  validateWithFCs,
+
+  async validateAndThowErrorsIfExists(req, dataForValidation, targetPrefix, context) {
+    const { dbRecord, errors } = await validateWithFCs(req, dataForValidation, context);
+
+    throwErrorsAndStopIfExists(req, errors, targetPrefix);
+
+    return dbRecord;
+  },
+
+  async validateAndAttachErrors(req, dataForValidation, targetPrefix, context) {
+    const { dbRecord, errors } = await validateWithFCs(req, dataForValidation, context);
+
+    provideErrors(req, errors, targetPrefix);
+
+    return { dbRecord, errors };
+  },
+
+  provideErrors,
+
+  throwErrorsAndStopIfExists
+};

package/src/ServiceParser.js

@@ -0,0 +1,56 @@
+const defaultAnnotationValues = require('./defaultAnnotationValues');
+
+/**
+ * Extract FCSettings annotations from an annotation object.
+ * @param {object} annotations The annotation object.
+ * @returns {object|null} Settings object
+ */
+function extractFCSettings(annotations) {
+  if (!annotations) {
+    return null;
+  }
+
+  const FCSettings = {};
+
+  for (const [ key, value ] of Object.entries(annotations)) {
+    if (key.startsWith('@FCSettings.')) {
+      const path = key.slice('@FCSettings.'.length).split('.');
+      let current = FCSettings;
+
+      for (let i = 0; i < path.length - 1; i++) {
+        const segment = path[i];
+
+        if (!(segment in current)) {
+          current[segment] = {};
+        }
+
+        current = current[segment];
+      }
+
+      current[path[path.length - 1]] = value;
+    }
+  }
+
+  return Object.keys(FCSettings).length > 0
+    ? { ...structuredClone(defaultAnnotationValues), ...FCSettings }
+    : null;
+}
+
+module.exports = class ServiceParser {
+  /**
+   * Call a callback for each FC entity in the given services.
+   * @param {Array|object} services The services to process.
+   * @param {Function} callback The callback to call for each FC entity.
+   */
+  static onEachFCEntity(services, callback) {
+    for (const srv of services) {
+      if (srv instanceof cds.ApplicationService) {
+        Object.values(srv.entities).forEach((entity) => {
+          const FCSettings = extractFCSettings(entity?.$flatAnnotations);
+
+          FCSettings && FCSettings.path && callback(srv, entity, FCSettings);
+        });
+      }
+    }
+  }
+};

package/src/SymbolHelper.js

@@ -0,0 +1,125 @@
+const actions = {
+  onBeforeSave: Symbol('onBeforeSave'),
+  onAfterSave: Symbol('onAfterSave'),
+  setOnBeforeCalculateFC: Symbol('setOnBeforeCalculateFC'),
+  srvEntitiesFC: Symbol('srvEntitiesFC'),
+  entityFC: Symbol('entityFC')
+};
+
+/**
+ * Set the onBeforeSave handler.
+ * @param {object} obj The configuration object.
+ * @param {Function} handler The handler function.
+ */
+function setOnBeforeSave(obj, handler) {
+  obj[actions.onBeforeSave] = handler;
+}
+
+/**
+ * Get the onBeforeSave handler.
+ * @param {object} obj The configuration object.
+ * @returns {object|null} Field Control object definition
+ */
+function getOnBeforeSave(obj) {
+  return obj[actions.onBeforeSave];
+}
+
+/**
+ * Get the onAfterSave handler.
+ * @param {object} obj The configuration object.
+ * @returns {object|null} Field Control object definition
+ */
+function getOnAfterSave(obj) {
+  return obj[actions.onAfterSave];
+}
+
+/**
+ * Set the onAfterSave handler.
+ * @param {object} obj The configuration object.
+ * @param {Function} handler The handler function.
+ */
+function setOnAfterSave(obj, handler) {
+  obj[actions.onAfterSave] = handler;
+}
+
+/**
+ * Set the onBeforeCalculateFC handler.
+ * @param {object} obj The configuration object.
+ * @param {Function} handler The handler function.
+ */
+function setOnBeforeCalculateFC(obj, handler) {
+  obj[actions.setOnBeforeCalculateFC] = handler;
+}
+
+/**
+ * Get the onBeforeCalculateFC handler.
+ * @param {object} obj The configuration object.
+ * @returns {object|null} Field Control object definition
+ */
+function getOnBeforeCalculateFC(obj) {
+  return obj[actions.setOnBeforeCalculateFC];
+}
+
+/**
+ * Set the entity field control handler.
+ * @param {object} obj The configuration object.
+ * @param {Function} handler The handler function.
+ */
+function setEntityFC(obj, handler) {
+  obj[actions.entityFC] = handler;
+}
+
+/**
+ * Get the entity field control handler.
+ * @param {object} obj The configuration object.
+ * @returns {object|null} Field Control object definition
+ */
+function getEntityFC(obj) {
+  const fcObject = obj[actions.entityFC];
+
+  if (!fcObject) {
+    throw Error(`CSN Entity: ${ obj.name } doesn't have configuration, check annotations definitions`);
+  }
+
+  return fcObject;
+}
+
+/**
+ * Get the service entities field controls.
+ * @param {object} obj The configuration object.
+ * @returns {object|null} Field Control object definition
+ */
+function getSrvEntitiesFCs(obj) {
+  return obj[actions.srvEntitiesFC];
+}
+
+/**
+ * Add service entities field controls.
+ * @param {object} obj The configuration object.
+ * @param {object} handler The handler object.
+ */
+function addSrvEntitiesFCs(obj, handler) {
+  const reference = obj[actions.srvEntitiesFC];
+
+  if (!reference) {
+    obj[actions.srvEntitiesFC] = handler;
+  } else {
+    Object.assign(reference, handler);
+  }
+}
+
+module.exports = {
+  setOnBeforeSave,
+  getOnBeforeSave,
+  setOnBeforeCalculateFC,
+  getOnBeforeCalculateFC,
+
+  getSrvEntitiesFCs,
+  addSrvEntitiesFCs,
+
+  getOnAfterSave,
+  setOnAfterSave,
+
+  setEntityFC,
+  getEntityFC
+};

package/src/Utils.js

@@ -0,0 +1,61 @@
+function formatMessage(msg, args) {
+  return args.reduce((result, val, i) => result.replace(`{${i}}`, val), msg);
+}
+
+const FIELD_TYPE_DEFAULTS = {
+  'cds.Timestamp': null,
+  'cds.DateTime': null,
+  'cds.Date': null,
+  'cds.Association': null,
+  'cds.Composition': null,
+  'cds.Integer': null,
+  'cds.UUID': null,
+  'cds.Boolean': false,
+};
+
+module.exports = class Utils {
+  static createMockEntity(entityName) {
+    const { elements } = cds.entities[entityName];
+
+    return Object.entries(elements).reduce((acc, [fieldKey, fieldInfo]) => {
+      const hasValueList = fieldInfo['@Common.ValueList.CollectionPath'];
+
+      acc[fieldKey] = hasValueList
+        ? null
+        : FIELD_TYPE_DEFAULTS[fieldInfo.type] ?? '';
+
+      return acc;
+    }, {});
+  }
+
+  static decorateAllFCs(configs, decorator) {
+    for (const key in configs) {
+      if (configs.hasOwnProperty(key)) {
+        const originalFc = configs[key].fc;
+
+        configs[key].fc = (...args) => decorator(originalFc, ...args);
+      }
+    }
+  }
+
+  static getEntityName(csnEntity) {
+    const [, entityName] = csnEntity.name.split('.');
+
+    return entityName;
+  }
+
+  static getText(key, args) {
+    const locale = cds.context.locale || 'en';
+    const bundle = cds.i18n.bundle4();
+    const texts = bundle.texts4(locale);
+    const msg = texts[key] || key;
+
+    return formatMessage(msg, args || []);
+  }
+
+  static getBoundI18nBundle() {
+    return {
+      getText: (...args) => Utils.getText(...args)
+    };
+  }
+};

package/src/cdsPluginImpl.js

@@ -0,0 +1,22 @@
+const path = require('path');
+const ServiceParser = require('./ServiceParser.js');
+const { FieldControls } = require('./FieldControls.js');
+const Utils = require('./Utils.js');
+const { setEntityFC, addSrvEntitiesFCs } = require('./SymbolHelper');
+
+module.exports = function(service) {
+  const services = Array.isArray(service) ? service : [ service ];
+
+  ServiceParser.onEachFCEntity(services, async (srv, csnEntity, configuration) => {
+    const entityName = Utils.getEntityName(csnEntity);
+    const configurationFilePath = path.resolve('./', configuration.path);
+
+    const configurationEntity = require(configurationFilePath);
+
+    const fc = new FieldControls(srv, csnEntity, configurationEntity, configuration);
+
+    setEntityFC(csnEntity, fc);
+    csnEntity.drafts && setEntityFC(csnEntity.drafts, fc);
+    addSrvEntitiesFCs(srv, { [entityName]: fc });
+  });
+};

package/src/defaultAnnotationValues.js

@@ -0,0 +1,44 @@
+
+/**
+ *  Available annotation examples.
+ *  @FCSettings.liveValidations: true
+ *  @FCSettings.autoErase: true
+ *  @FCSettings.path: 'srv/@FCDefinitions/InternalUsersForm.js'
+ * @FCSettings: {
+ *      useImpl.BeneficiaryAddress: 'Addresses',
+ *      useImpl.DeliveryAddress: 'Addresses',
+ *   }
+ * or
+ * @FCSettings: {
+ *  useImpl: {
+ *    BeneficiaryAddress: 'Addresses',
+ *    DeliveryAddress: 'Addresses',
+ *  }
+ * }
+ */
+
+/**
+ * Cds configs:
+ *
+ * "cds": {
+ *  "enable:capdomain:plugin": true,
+ *  "enable:capdomain:liveValidations": false,
+ *  "enable:capdomain:autoErase": false,
+ *  "enable:capdomain:defaultFCValue": 3,
+ *  "enable:capdomain:blockUnannotatedValueChanges": true,
+ * }
+ */
+
+/**
+ * Merge logic of configurations should work in the following way
+ * Object.assing({}, defaultLibValues, cdsConfiguration, annotationConfiguration, codeCallConfigurations)
+ */
+
+const FCSettings = {
+  autoErase: cds.env['enable:capdomain:autoErase'] ?? true,
+  liveValidations: cds.env['enable:capdomain:liveValidations'] ?? true,
+  blockUnannotatedValueChanges: cds.env['enable:capdomain:blockUnannotatedValueChanges'] ?? true,
+  useImpl: {}
+};
+
+module.exports = FCSettings;

package/tests/.cdsrc.json

@@ -0,0 +1 @@
+{}

package/tests/.vscode/extensions.json

@@ -0,0 +1,18 @@
+{
+	// See https://go.microsoft.com/fwlink/?LinkId=827846 to learn about workspace recommendations.
+	// Extension identifier format: ${publisher}.${name}. Example: vscode.csharp
+
+	// List of extensions which should be recommended for users of this workspace.
+	"recommendations": [
+		"SAPSE.vscode-cds",
+		"dbaeumer.vscode-eslint",
+		"esbenp.prettier-vscode",
+		"mechatroner.rainbow-csv",
+		"qwtel.sqlite-viewer",
+		"humao.rest-client"
+	],
+	// List of extensions recommended by VS Code that should not be recommended for users of this workspace.
+	"unwantedRecommendations": [
+
+	]
+}

package/tests/.vscode/launch.json

@@ -0,0 +1,18 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "cds serve",
+      "request": "launch",
+      "type": "node",
+      "cwd": "${workspaceFolder}",
+      "runtimeExecutable": "cds",
+      "args": [
+        "serve",
+        "--with-mocks",
+        "--in-memory?"
+      ],
+
+    }
+  ]
+}

package/tests/.vscode/settings.json

@@ -0,0 +1,11 @@
+{
+  // uncomment entries once all libraries have been installed via 'npm install'
+  "eslint.validate": [
+    // "cds",
+    // "csn",
+    // "csv",
+    // "csv (semicolon)",
+    // "tab",
+    // "tsv"
+  ]
+}

package/tests/.vscode/tasks.json

@@ -0,0 +1,25 @@
+{
+  // See https://go.microsoft.com/fwlink/?LinkId=733558
+  // for the documentation about the tasks.json format
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "type": "shell",
+      "label": "cds watch",
+      "command": "cds",
+      "args": ["watch"],
+      "group": {
+        "kind": "build",
+        "isDefault": true
+      },
+      "problemMatcher": []
+    },
+    {
+      "type": "shell",
+      "label": "cds serve",
+      "command": "cds",
+      "args": ["serve", "--with-mocks", "--in-memory?"],
+      "problemMatcher": []
+    }
+  ]
+}

package/tests/_i18n/i18n.properties

@@ -0,0 +1,5 @@
+previewDate=Preview Date has to after today
+dateToday-errorMessage= Date has to be greater than today
+price-error = Price must be set
+statusCheck-Cancelled = Please use remaining stock before cancelling
+statusCheck-Released = Release Date must be today: {{custom-today}}

package/tests/db/data/my.bookshop-Authors.csv

@@ -0,0 +1,3 @@
+ID;name;
+1;Alex
+2;Pavel

package/tests/db/data/my.bookshop-Books.csv

@@ -0,0 +1,3 @@
+ID;title;stock;enableDetails;Author_ID
+1;Wuthering Heights;100;true;1
+2;Jane Eyre;500;false;2

package/tests/db/data/my.bookshop-Details.csv

@@ -0,0 +1,3 @@
+ID;title;
+1;detail name 1;
+2;detail name 2;

package/tests/db/data/my.bookshop-Request.csv

@@ -0,0 +1,3 @@
+ID;title;Detail_ID;
+1;Adjsut height;1;
+2;Adjust weight;2;