cap-domain 3.0.0

package/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

package/README.md

@@ -0,0 +1,239 @@
+# cap-domain - SAP CAP Field Control Plugin
+
+A SAP CAP plugin that provides dynamic field control: it calculates OData `Common.FieldControl`
+values (Mandatory / Optional / ReadOnly / Hidden) at runtime and enforces matching server-side
+validation, so the client (e.g. Fiori Elements) and the backend always agree on what a field's
+current state allows.
+
+Requires `@sap/cds` >= 10.
+
+## Installation
+
+```sh
+npm install cap-domain
+```
+
+## Quick Start
+
+### 1. Enable the plugin
+
+```json
+{
+  "cds": {
+    "enable:capdomain:plugin": true
+  }
+}
+```
+
+### 2. Provide the required i18n texts
+
+The library reports read-only and mandatory violations using its own i18n keys. Add these to
+your app's i18n bundle (e.g. `_i18n/i18n.properties`) - otherwise the raw key is shown instead
+of a readable message:
+
+```properties
+capdomain.validation.message.readOnly={0} is Read-only field
+capdomain.validation.message.required={0} is Required field
+```
+
+### 3. Create a field control configuration
+
+Create `srv/@FCDefinitions/MyEntity.js`:
+
+```javascript
+const { fieldControlDictionary } = require('cap-domain');
+
+const fieldControlConfigurations = {
+  mandatory: {
+    fc: () => fieldControlDictionary.Mandatory
+  },
+  conditional: {
+    fc: (entity) => entity.condition ? 
+      fieldControlDictionary.Mandatory : 
+      fieldControlDictionary.Hidden
+  },
+  validated: {
+    fc: () => fieldControlDictionary.Mandatory,
+    validator: (value, { i18n }) => {
+      if (!value || value.length < 5) {
+        return i18n.getText('validation.minLength', [5]);
+      }
+    }
+  }
+};
+
+module.exports = fieldControlConfigurations;
+```
+
+Each key must match the *short* name of a virtual `<field>_fc` element declared on the service
+entity (see step 4), i.e. `mandatory` configures `mandatory_fc`.
+
+### 4. Configure the CDS service
+
+```cds
+service MyService {
+  @FCSettings: {
+    path: 'srv/@FCDefinitions/MyEntity.js'
+  }
+  entity MyEntity as projection on my.MyEntity {
+    *,
+    virtual null as mandatory_fc    : Integer @odata.Type: 'Edm.Byte',
+    virtual null as conditional_fc  : Integer @odata.Type: 'Edm.Byte',
+    virtual null as validated_fc    : Integer @odata.Type: 'Edm.Byte'
+  }
+}
+
+annotate MyService.MyEntity with {
+  fieldName @(Common.FieldControl: {$value: conditional_fc});
+};
+```
+
+> Every field that clients are allowed to change must carry its own `@Common.FieldControl`
+> annotation. By default (`enable:capdomain:blockUnannotatedValueChanges`), updates to any
+> unannotated field are silently dropped - see [Configuration](#configuration).
+
+### 5. Wire up the handlers
+
+Create `srv/my-service.js`:
+
+```javascript
+const { 
+  execAfterREADHandler, 
+  execUPDATEHandler, 
+  bindEntityHandlers
+} = require('cap-domain');
+
+module.exports = (srv) => {
+  const { MyEntity } = srv.entities;
+
+  // Basic handlers
+  srv.after('READ', MyEntity, execAfterREADHandler);
+  srv.on('UPDATE', MyEntity, execUPDATEHandler);
+
+  // Draft-enabled entity handlers
+  if (MyEntity['@odata.draft.enabled']) {
+    const { DRAFTPrepareHandler, CreateDraftHandler } = bindEntityHandlers(MyEntity);
+
+    srv.on('NEW', MyEntity.drafts, CreateDraftHandler);
+    srv.after('READ', MyEntity.drafts, execAfterREADHandler);
+    srv.on('UPDATE', MyEntity.drafts, execUPDATEHandler);
+  }
+};
+```
+
+For `CREATE`, validate explicitly with `validateAndThowErrorsIfExists` (see below) since CAP has
+no generic hook equivalent to `execUPDATEHandler` for creates.
+
+## Configuration
+
+### Environment Variables
+
+```json
+{
+  "cds": {
+    "enable:capdomain:plugin": true,
+    "enable:capdomain:liveValidations": true,
+    "enable:capdomain:autoErase": true,
+    "enable:capdomain:defaultFCValue": 3,
+    "enable:capdomain:blockUnannotatedValueChanges": true
+  }
+}
+```
+
+| Variable | Default | Effect |
+|---|---|---|
+| `enable:capdomain:plugin` | `false` | Activates the CDS plugin that wires field control metadata onto annotated entities. |
+| `enable:capdomain:liveValidations` | `true` | For a request with no persisted record yet (`CREATE`), validates the whole entity using empty defaults for any field missing from the payload, so mandatory checks fire progressively as a form is filled in. For an existing record (`UPDATE`), untouched fields always keep their persisted values regardless of this setting. |
+| `enable:capdomain:autoErase` | `true` | Nulls out a field's value as soon as its field control becomes ReadOnly/Hidden. |
+| `enable:capdomain:defaultFCValue` | `3` (Optional) | Fallback field control value used when a field has no explicit calculator. |
+| `enable:capdomain:blockUnannotatedValueChanges` | `true` | Drops any incoming field that has no `@Common.FieldControl` annotation of its own. This is a strict, secure-by-default setting: every editable field - including plain "trigger" fields that only influence *other* fields' field control - must be annotated. |
+
+Per-entity `@FCSettings` annotations (`path`, `liveValidations`, `autoErase`,
+`blockUnannotatedValueChanges`, `useImpl`) override these environment defaults for that entity.
+
+### Core Functions
+
+#### `validateAndThowErrorsIfExists(req, dataForValidation, targetPrefix)`
+Validates data and throws errors if validation fails. Typical use in a `CREATE` handler, where
+there is no generic update hook to bind to:
+
+```javascript
+const { validateAndThowErrorsIfExists } = require('cap-domain');
+
+srv.on('CREATE', MyEntity, async (req, next) => {
+  await validateAndThowErrorsIfExists(req, req.data, 'in');
+  return await next();
+});
+```
+
+#### `validateWithFCs(req, dataForValidation)`
+Validates data and returns validation errors.
+
+```javascript
+const { validateWithFCs } = require('cap-domain');
+
+const errors = await validateWithFCs(req, req.data, { csnEntity, context = {} });
+
+validateAndAddMyMessage(errors);
+
+if (errors.length > 0) {
+  errors.forEach(error => {
+    req.error({
+      target: `/MyEntity(${req.params.at(0).ID})/${error.fieldName}`,
+      message: error.message,
+      code: 400
+    });
+  });
+  req.reject();
+}
+```
+
+#### `calculateFieldControls(data, req, { csnEntity, context = {} })`
+Calculates field control values for entities.
+
+```javascript
+const { calculateFieldControls } = require('cap-domain');
+
+const entityWithFCs = await calculateFieldControls(entity, req, { 
+  csnEntity: MyEntity, // optional, req.target will be used by default
+  context: { additionalData: 'value' }
+});
+```
+
+#### `execAfterREADHandler(entity, req, context)`
+Executes READ handler for field control calculation.
+
+```javascript
+const { execAfterREADHandler } = require('cap-domain');
+
+srv.after('READ', MyEntity, execAfterREADHandler);
+```
+
+#### `execUPDATEHandler(req, next, context)`
+Executes UPDATE handler with field control validation.
+
+```javascript
+const { execUPDATEHandler } = require('cap-domain');
+
+srv.on('UPDATE', MyEntity, execUPDATEHandler);
+```
+
+
+#### `Utils`
+```javascript
+const { Utils } = require('cap-domain');
+
+const message = Utils.getText('validation.required', ['dynamic field value']);
+const entityName = Utils.getEntityName(csnEntity);
+const i18n = Utils.getBoundI18nBundle();
+```
+
+## Example project
+
+See [`tests/`](./tests) for a runnable CAP showcase (bookshop-style model) exercising mandatory
+fields, conditional field control, read-only enforcement, auto-erase and the
+`blockUnannotatedValueChanges` guard:
+
+```sh
+npm test
+```

package/cds-plugin.js

@@ -0,0 +1,5 @@
+const cdsPluginImpl = require('./src/cdsPluginImpl');
+
+cds.env['enable:capdomain:plugin'] && cds.once('served', async () => {
+  cdsPluginImpl(Object.values(cds.services));
+});

package/index.js

@@ -0,0 +1,33 @@
+// https://cap.cloud.sap/docs/node.js/fiori
+
+const { fieldControlDictionary, handlers } = require('./src/FieldControls');
+const cdsPluginImpl = require('./src/cdsPluginImpl');
+const Utils = require('./src/Utils');
+const {
+  execAfterREADHandler,
+  execUPDATEHandler,
+  validateWithFCs,
+  provideErrors,
+  throwErrorsAndStopIfExists,
+  validateAndThowErrorsIfExists,
+  validateAndAttachErrors,
+  calculateFieldControls,
+  bindEntityHandlers
+} = require('./src/Handlers');
+
+module.exports = {
+  Utils,
+  fieldControlDictionary,
+  init: cdsPluginImpl,
+  ...handlers,
+
+  bindEntityHandlers,
+  calculateFieldControls,
+  execAfterREADHandler,
+  execUPDATEHandler,
+  validateWithFCs,
+  provideErrors,
+  throwErrorsAndStopIfExists,
+  validateAndThowErrorsIfExists,
+  validateAndAttachErrors
+};

package/package.json

@@ -0,0 +1,25 @@
+{
+    "name": "cap-domain",
+    "version": "3.0.0",
+    "description": "SAP CAP Field Control Plugin - dynamic field visibility, editability and validation",
+    "main": "index.js",
+    "scripts": {
+        "test": "cd tests && npx jest --silent=true"
+    },
+    "license": "ISC",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/yauhenshalik-hub/cap-domain.git"
+    },
+    "bugs": {
+        "url": "https://github.com/yauhenshalik-hub/cap-domain/issues"
+    },
+    "homepage": "https://github.com/yauhenshalik-hub/cap-domain#readme",
+    "dependencies": {},
+    "peerDependencies": {
+        "@sap/cds": ">=10"
+    },
+    "workspaces": [
+        "tests"
+    ]
+}

package/src/FieldControls.js

@@ -0,0 +1,356 @@
+const Utils = require('./Utils');
+const { getOnBeforeCalculateFC, getOnBeforeSave, getOnAfterSave, setOnBeforeSave, setOnBeforeCalculateFC, setOnAfterSave, getSrvEntitiesFCs } = require('./SymbolHelper');
+
+/**
+ * https://sap.github.io/odata-vocabularies/vocabularies/Common.html#FieldControlType
+ * Field control value constants
+ * These values determine the visibility and editability of fields
+ */
+const fieldControlDictionary = {
+
+  // Visible, Editable, Required
+  Mandatory: 7,
+
+  // Visible, Editable, Not Required
+  Optional: 3,
+
+  // Visible, Not Editable
+  ReadOnly: 1,
+
+  // Not Visible
+  Hidden: 0
+};
+
+const defaultEnvFC = Number(cds.env['enable:capdomain:defaultFCValue'] ?? fieldControlDictionary.Optional);
+
+/**
+ * Calculate field control for a specific field.
+ * @param {Function} calculator Function to calculate field control value.
+ * @param {object} entity The entity data.
+ * @param {object} helperContext Context object for calculation.
+ * @returns {number|boolean} Field Control calculated value
+ */
+function calculateFieldControl(calculator, entity, helperContext) {
+  if (!calculator) {
+    return fieldControlDictionary.ReadOnly;
+  }
+
+  return calculator(entity, helperContext);
+}
+
+/**
+ * Get field control values from data and CSN definition
+ * @param {object} data The data object
+ * @param {object} csnEntityDefinition The CSN entity definition
+ * @param {object} i18n The i18n bundle
+ * @returns {object} Field Control values
+ */
+function getFieldControlValues(data, csnEntityDefinition, i18n) {
+  return Object.entries(csnEntityDefinition.elements).reduce(
+    (acc, [ key, cdsDefinition ]) => {
+      const fieldControlAnnotation = cdsDefinition['@Common.FieldControl'];
+      const label = cdsDefinition['@Common.Label'];
+
+      if (fieldControlAnnotation) {
+        const isMandatory = cdsDefinition['@mandatory'];
+        const fieldControlValuePath = fieldControlAnnotation['='];
+        const fcValue =
+          data[fieldControlValuePath] ??
+          ((isMandatory && fieldControlDictionary.Mandatory) ||
+          defaultEnvFC);
+
+        acc[key] = {
+          fcShortPath: fieldControlValuePath?.replace('_fc', ''),
+          label: label ? i18n.getText(label.replace('{i18n>', '').replace('}', '')) : '',
+          fcValue
+        };
+      }
+
+      return acc;
+    },
+    {}
+  );
+}
+
+/**
+ * Get mapping of entity field control annotations.
+ * @param {object} entityDefinitionElements The entity definition elements.
+ * @returns {object} Fields mapping
+ */
+function getEntityFCAnnotationsMapping(entityDefinitionElements) {
+  const { elements } = entityDefinitionElements;
+  const settings = Object.entries(elements).reduce((acc, [ fieldName, element ]) => {
+    const elementFC = element['@Common.FieldControl'];
+    const { '=': fieldControlBindingPath } = elementFC || {};
+
+    if (fieldControlBindingPath) {
+      acc[fieldName] = { fieldName, FCPath: fieldControlBindingPath };
+    }
+
+    return acc;
+  }, {});
+
+  return settings;
+}
+
+/**
+ * FieldControls class to handle the logic for field control values
+ * based on different conditions in the request or entity data
+ */
+class FieldControls {
+  /**
+   * @param {object} srv - SRV Definition
+   * @param {object} csnEntity - CSN Entity Definition
+   * @param {object} configurationEntity - Field Control configurations
+   * @param {object} configuration - Entity Configuration
+   */
+  constructor(srv, csnEntity, configurationEntity, configuration) {
+    this.configuration = configuration;
+    this.srv = srv;
+    this.csnEntity = csnEntity;
+    this.configurationEntity = configurationEntity;
+  }
+
+  /**
+   * Call the onBeforeCalculateFC hook if defined.
+   * @param {object} updatedEntry The updated entity.
+   * @param {object} helperObject The helper context object.
+   * @returns {Promise<*>} Request
+   */
+  async callOnBeforeCalculateFC(updatedEntry, helperObject) {
+    const onBeforeCalculateFC = getOnBeforeCalculateFC(this.configurationEntity);
+
+    if (onBeforeCalculateFC) {
+      return onBeforeCalculateFC(updatedEntry, helperObject);
+    }
+  }
+
+  /**
+   * Call the onBeforeSave hook if defined.
+   * @param {object} updatedEntry The updated entity.
+   * @param {object} req The CDS request object.
+   * @returns {Promise<void>} Request
+   */
+  async callOnBeforeSave(updatedEntry, req) {
+    const onBeforeSave = getOnBeforeSave(this.configurationEntity);
+
+    if (onBeforeSave) {
+      return await onBeforeSave(updatedEntry, this.buildHelperObject(req));
+    }
+  }
+
+  /**
+   * Call the onAfterSave hook if defined.
+   * @param {object} updatedEntry The updated entity.
+   * @param {object} req The CDS request object.
+   * @returns {Promise<void>} Request
+   */
+  async callOnAfterSave(updatedEntry, req) {
+    const onAfterSave = getOnAfterSave(this.configurationEntity);
+
+    if (onAfterSave) {
+      return await onAfterSave(updatedEntry, this.buildHelperObject(req));
+    }
+  }
+
+  /**
+   * Build a helper context object for hooks.
+   * @param {object} req The CDS request object.
+   * @param {object} [context] Additional context.
+   * @returns {object} Helper object
+   */
+  buildHelperObject(req, context = {}) {
+    return Object.assign({}, { srv: this.srv, req, context: Object.assign({ req }, context.context) });
+  }
+
+  /**
+   * Erase unavailable or unannotated fields from update data.
+   * @param {object} updatedEntry The updated entity.
+   * @param {object} updateData The update data object.
+   * @param {object} configuration The configuration object.
+   * @param {object} fieldControlAnnotationValues The annotations configuration object.
+   */
+  eraseUnavailableDynamicFields(updatedEntry, updateData, configuration, fieldControlAnnotationValues) {
+    const { autoErase, blockUnannotatedValueChanges } = configuration;
+
+    const entityFCsSettings = getEntityFCAnnotationsMapping(this.csnEntity);
+
+    blockUnannotatedValueChanges && Object.entries(updateData).forEach(([ fieldName ]) => {
+      const fieldDefinition = this.csnEntity.elements[fieldName];
+      const fcFieldName = entityFCsSettings?.[fieldName]?.FCPath;
+
+      if (!fieldDefinition || fieldDefinition.key) {
+        return;
+      }
+
+      if (!fcFieldName || !updatedEntry.hasOwnProperty(fcFieldName)) {
+        delete updateData[fieldName];
+      }
+    });
+
+    autoErase && Object.entries(this.configurationEntity).forEach(([ fieldName ]) => {
+      const fieldDefinition = this.csnEntity.elements[fieldName];
+
+      if (fieldDefinition) {
+        const fcValue = fieldControlAnnotationValues[fieldName].fcValue;
+        const finalFieldName =
+          fieldDefinition.type === 'cds.Association'
+            ? fieldDefinition.$generatedForeignKeys.at(0).name
+            : fieldName;
+
+        if (autoErase && fcValue <= fieldControlDictionary.ReadOnly) {
+          updateData[finalFieldName] = null;
+        }
+      }
+    });
+  }
+
+  /**
+   * Validate payload against field control configurations.
+   * @param {object} data The data to validate.
+   * @param {object} dataUpdate The data update to validate against.
+   * @param {object} [rawUpdate] The original, unmerged update payload as submitted by the caller.
+   *   Used to detect whether a field was actually part of the change, since `dataUpdate` may be
+   *   backfilled with mock defaults for live validation. Defaults to `dataUpdate`.
+   * @param {object} [previousData] The persisted state prior to this change, used to detect whether
+   *   a read-only/hidden field's value actually changed. Defaults to `data`.
+   * @returns {object} Validation results containing any errors.
+   */
+  async validatePayload(data, dataUpdate, rawUpdate = dataUpdate, previousData = data) {
+    const i18n = Utils.getBoundI18nBundle();
+    const fieldControlAnnotationValues = getFieldControlValues(data, this.csnEntity, i18n);
+
+    const validationPromises = Object.entries(dataUpdate).map(
+      async ([ key, entityValue ]) => {
+        const { fcValue, label, fcShortPath } = fieldControlAnnotationValues[key] || {};
+        const { validator } = this.configurationEntity[fcShortPath] || {};
+        const fieldErrors = [];
+
+        if (validator && fcValue >= fieldControlDictionary.Optional) {
+          const validationMessage = await validator.call(this.srv, entityValue, {
+            i18n,
+            entity: data,
+            fieldName: key
+          });
+
+          if (validationMessage) {
+            fieldErrors.push({
+              fieldName: key,
+              message: validationMessage
+            });
+          }
+        }
+
+        if (fcValue <= fieldControlDictionary.ReadOnly && rawUpdate.hasOwnProperty(key) && previousData[key] !== entityValue) {
+          fieldErrors.push({
+            fieldName: key,
+            message: i18n.getText('capdomain.validation.message.readOnly', [ label ])
+          });
+        }
+
+        if ((entityValue === null || entityValue === '') && fcValue === fieldControlDictionary.Mandatory) {
+          fieldErrors.push({
+            fieldName: key,
+            message: i18n.getText('capdomain.validation.message.required', [ label ])
+          });
+        }
+
+        return fieldErrors;
+      }
+    );
+
+    const allResults = await Promise.all(validationPromises);
+
+    const errors = allResults.flat();
+
+    return { errors, fieldControlAnnotationValues };
+  }
+
+  /**
+   * Calculate field controls for associated entities.
+   * @param {object} entity The main entity.
+   * @param {object} req The CDS request object.
+   * @param {object} context The context object.
+   * @returns {Promise<Array>} Requests
+   */
+  async calculateAssociatedEntitiesFC(entity, req, context) {
+    const requests = Object.entries(this.configuration.useImpl).map(async ([ associationName, targetSrvEntity ]) => {
+      const record = entity[associationName];
+
+      if (!record) {
+        return;
+      }
+
+      const fc = getSrvEntitiesFCs(this.srv)[targetSrvEntity];
+
+      return await fc.calculateFieldControls(record, req, context);
+    });
+
+    return await Promise.all(requests);
+  }
+
+  /**
+   * Calculate field controls for an Entity or array of Entities.
+   * @param {object | Array} entities Single entity or array of entities.
+   * @param {object | Array} req Request
+   * @param {object} context Context object.
+   * @returns {object | Array} Entity/Entities with field controls.
+   */
+  async calculateFieldControls(entities, req, context = {}) {
+    if (!entities) {
+      return entities;
+    }
+
+    const entitiesArray = Array.isArray(entities)
+      ? entities
+      : [ entities ];
+
+    const processEntitiesRequests = entitiesArray.map(async (entity) => {
+      const helperObject = this.buildHelperObject(req, context);
+
+      await this.calculateAssociatedEntitiesFC(entity, req, context);
+
+      await this.callOnBeforeCalculateFC(entity, helperObject);
+
+      const entityFCsSettings = getEntityFCAnnotationsMapping(this.csnEntity);
+      const fieldControls = Object.values(entityFCsSettings).reduce(
+        (fcAcc, { FCPath }) => {
+          if (fcAcc.hasOwnProperty(FCPath)) {
+            return fcAcc;
+          }
+
+          const fcValue = calculateFieldControl(this.configurationEntity[FCPath.replace('_fc', '')]?.fc, entity, helperObject);
+
+          if (fcValue !== null) {
+            fcAcc[FCPath] = fcValue;
+          }
+
+          return fcAcc;
+        },
+        {}
+      );
+
+      Object.assign(entity, fieldControls);
+
+      return entity;
+    });
+
+    const processedEntities = await Promise.all(processEntitiesRequests);
+
+    return Array.isArray(entities)
+      ? processedEntities
+      : processedEntities[0];
+  }
+}
+
+module.exports = {
+  FieldControls,
+  fieldControlDictionary,
+  handlers: {
+    setOnBeforeSave,
+    setOnBeforeCalculateFC,
+
+    getOnAfterSave,
+    setOnAfterSave
+  }
+};