@cap-js/ord 1.0.3 → 1.2.0

package/lib/templates.js

@@ -1,25 +1,33 @@
-const defaults = require("./defaults");
 const cds = require("@sap/cds");
-const fReplaceSpecialCharacters = (namespace) => {
-  return namespace.replace(/customer\.(.+)/, (match, group1) => 'customer.' + group1.replace(/[^a-zA-Z0-9]/g, ''))
+const defaults = require("./defaults");
+const _ = require("lodash");
+const {
+    DESCRIPTION_PREFIX,
+    ORD_EXTENSIONS_PREFIX,
+    ORD_RESOURCE_TYPE,
+    RESOURCE_VISIBILITY,
+    SHORT_DESCRIPTION_PREFIX
+} = require("./constants");
+const { Logger } = require("./logger");
+
+function unflatten(flattedObject) {
+    let result = {}
+    _.keys(flattedObject).forEach(function (key) {
+        _.set(result, key, flattedObject[key])
+    })
+    return result
 }
 
-/**
- * Reads the ORD (Open Resource Discovery) annotation from a given service definition object and returns them as an object.
- *
- * @param {Object} srv The service definition object.
- * @returns {Object} An object containing ORD annotation.
- */
-const fReadORDExtensions = (srv) =>
-  Object.entries(srv)
-    .filter(([key]) => key.startsWith("@ORD.Extensions."))
-    .reduce(
-      (ordExtensions, [key, value]) => ({
-        ...ordExtensions,
-        [key.slice("@ORD.Extensions.".length)]: value,
-      }),
-      {}
-    );
+function readORDExtensions(model) {
+    const ordExtensions = {};
+    for (const key in model) {
+        if (key.startsWith(ORD_EXTENSIONS_PREFIX)) {
+            const ordKey = key.replace(ORD_EXTENSIONS_PREFIX, "");
+            ordExtensions[ordKey] = model[key];
+        }
+    }
+    return unflatten(ordExtensions);
+}
 
 /**
  * Reads the service definition and returns an array of entryPoint paths.
@@ -29,28 +37,28 @@ const fReadORDExtensions = (srv) =>
  * @returns {Array} An array containing paths and it's kind.
  */
 
-const fGeneratePaths = (srv, srvDefinition) => {
-  const srvObj = { name: srv, definition: srvDefinition };
-  const protocols = cds.service.protocols;
+const _generatePaths = (srv, srvDefinition) => {
+    const srvObj = { name: srv, definition: srvDefinition };
+    const protocols = cds.service.protocols;
 
-  const paths = protocols.endpoints4(srvObj);
+    const paths = protocols.endpoints4(srvObj);
 
-  //TODO: check graphql replication in paths object and re-visit logic
-  //removing instances of graphql protocol from paths
-  for (var index = paths.length - 1; index >= 0; index--) {
-    if (paths[index].kind === "graphql") {
-      console.warn("Graphql protocol is not supported.");
-      paths.splice(index, 1);
+    //TODO: check graphql replication in paths object and re-visit logic
+    //removing instances of graphql protocol from paths
+    for (var index = paths.length - 1; index >= 0; index--) {
+        if (paths[index].kind === "graphql") {
+            Logger.warn('Graphql protocol is not supported.');
+            paths.splice(index, 1);
+        }
     }
-  }
 
-  //putting default as odata in case no supported protcol is there
-  if (paths.length === 0) {
-    srvDefinition["@odata"] = true;
-    paths.push({ kind: "odata", path: protocols.path4(srvDefinition) });
-  }
+    //putting OData as default in case of non-supported protocol
+    if (paths.length === 0) {
+        srvDefinition["@odata"] = true;
+        paths.push({ kind: "odata", path: protocols.path4(srvDefinition) });
+    }
 
-  return paths;
+    return paths;
 };
 
 /**
@@ -59,30 +67,21 @@ const fGeneratePaths = (srv, srvDefinition) => {
  * @param {string} entity The name of the entity.
  * @returns {Object} An object for the entity type.
  */
-const fCreateEntityTypeTemplate = (entity) => ({
-  ordId: `sap.odm:entityType:${entity["@ODM.entityName"]}:v1`,
+const createEntityTypeTemplate = (entity) => ({
+    ordId: `sap.odm:entityType:${entity["@ODM.entityName"]}:v1`,
 });
 
-/**
- * This is a template function to form the group id.
- * 
- * @param {string} fullyQualifiedName The fully qualified name of the service or event.
- * @param {string} groupTypeId The group type id.
- * @returns {string} a group id.
- */
-function _getGroupID(fullyQualifiedName, groupTypeId = defaults.groupTypeId, isService = true) {
-    if (isService) {
-        return `${groupTypeId}:${fReplaceSpecialCharacters(global.namespace)}:${fullyQualifiedName}`;
-    } else {
-        return `${groupTypeId}:${fReplaceSpecialCharacters(global.namespace)}:` +
-                `${fullyQualifiedName.slice(0, fullyQualifiedName.lastIndexOf("."))}`;
-    }
+function _getGroupID(
+    fullyQualifiedName,
+    groupTypeId = defaults.groupTypeId,
+    appConfig,
+) {
+    return `${groupTypeId}:${appConfig.ordNamespace}:${fullyQualifiedName}`;
 }
 
-
 /**
  * This is a function to resolve the title of the service group.
- * 
+ *
  * @param {string} srv The name of the service.
  * @returns {string} The title of the service group.
  */
@@ -90,265 +89,157 @@ function _getTitleFromServiceName(srv) {
     let serviceName = srv.substring(srv.lastIndexOf(".") + 1);
     let index = serviceName.indexOf("Service");
     if (index >= 0) {
-        return `${serviceName.substring(0, index)} Service Title`;
+        return `${serviceName.substring(0, index)} Service`;
     } else {
-        return `${serviceName} Service Title`;
+        return `${serviceName} Service`;
     }
 }
 
-
 /**
  * This is a template function to create group object of a service for groups array in ORD doc.
- * 
- * @param {string} srv The name of the service.
- * @param {object} srvDefinition The definition of the service
- * @param {Set} groupIds A set of group ids.
- * @returns {Object} A group object.
- */
-const fCreateGroupsTemplateForService = (srv, srvDefinition, groupIds) => {
-    const ordExtensions = fReadORDExtensions(srvDefinition);
-
-    let fullyQualifiedServiceName = srv;
-    if(!srv.includes(global.capNamespace)){
-      fullyQualifiedServiceName = global.capNamespace + "." + srv;
-    }
-
-    if (checkEntityFunctionAction(srvDefinition, global).length > 0) {
-      let groupId = _getGroupID(fullyQualifiedServiceName, defaults.groupTypeId);
-      if (groupIds.has(groupId)) {
-          return null;
-      } else {
-          groupIds.add(groupId);
-          return {
-              groupId: groupId,
-              groupTypeId: `${defaults.groupTypeId}`,
-              title: ordExtensions.title ?? _getTitleFromServiceName(srv)
-          };
-      }
-    }
-}
-
-/**
- * 
- * @param {string} event The name of the event. 
- * @returns {string} The title of the event group.
- */
-function _getEventTitle(event) {
-    let serviceName = event.substring(0, event.lastIndexOf("."));
-    return _getTitleFromServiceName(serviceName);
-}
-
-/**
- * This is a template function to create group object of an event for groups array in ORD doc.
- * 
- * @param {string} event The name of the event.
- * @param {object} eventDefinition The definition of the event.
+ *
+ * @param {string} serviceName The name of the service.
+ * @param {object} serviceDefinition The definition of the service
  * @param {Set} groupIds A set of group ids.
  * @returns {Object} A group object.
  */
-const fCreateGroupsTemplateForEvent = (event, eventDefinition, groupIds) => {
-    const ordExtensions = fReadORDExtensions(eventDefinition);
+const createGroupsTemplateForService = (serviceName, serviceDefinition, appConfig) => {
+    const ordExtensions = readORDExtensions(serviceDefinition);
 
-    let fullyQualifiedEventName = event;
-    if(!event.includes(global.capNamespace)){
-      fullyQualifiedEventName = global.capNamespace + "." + event;
+    if (!serviceDefinition) {
+        Logger.warn('Unable to find service definition:', serviceName)
+        return undefined
     }
 
-    let groupId = _getGroupID(fullyQualifiedEventName, defaults.groupTypeId, global, false);
-    if (groupIds.has(groupId)) {
-        return null;
-    } else {
-        groupIds.add(groupId);
-        return {
-            groupId: groupId,
-            groupTypeId: `${defaults.groupTypeId}`,
-            title: ordExtensions.title ?? _getEventTitle(event)
-        };
-    }
+    const groupId = _getGroupID(serviceName, defaults.groupTypeId, appConfig);
+    return {
+        groupId: groupId,
+        groupTypeId: defaults.groupTypeId,
+        title: ordExtensions.title ?? _getTitleFromServiceName(serviceName)
+    };
 }
 
 /**
  * This is a template function to create API Resource object for API Resource Array.
- *
- * @param {string} srv The name of the service.
- * @param {object} srvDefinition The definition of the service
+ * Properties of an API resource can be overwritten by the ORD extensions. Example: visibility.
+
+ * @param {string} serviceName The name of the service.
+ * @param {object} serviceDefinition The definition of the service
  * @returns {Array} An array of objects for the API Resources.
  */
-const fCreateAPIResourceTemplate = (srv, srvDefinition, global,packageIds) => {
-  const ordExtensions = fReadORDExtensions(srvDefinition);
-  const paths = fGeneratePaths(srv, srvDefinition);
-  const apiResources = [];
-
-  let srvName = srv;
-  if (!srvName.includes(global.capNamespace)) {
-    srvName = global.capNamespace + "." + srv;
-  }
+const createAPIResourceTemplate = (serviceName, serviceDefinition, appConfig, packageIds) => {
+    const ordExtensions = readORDExtensions(serviceDefinition);
+    const paths = _generatePaths(serviceName, serviceDefinition);
+    const apiResources = [];
 
-  if (checkEntityFunctionAction(srvDefinition, global).length > 0) {
     paths.forEach((generatedPath) => {
-      let resourceDefinitions = [
-        {
-          type: "openapi-v3",
-          mediaType: "application/json",
-          url: `/.well-known/open-resource-discovery/v1/api-metadata/${srv}.oas3.json`,
-          accessStrategies: [{ type: "open" }],
-        },
-      ];
-
-      if (generatedPath.kind !== "rest") {
-        //edmx resource definition is not generated in case of 'rest' protocol
-        resourceDefinitions.push({
-          type: "edmx",
-          mediaType: "application/xml",
-          url: `/.well-known/open-resource-discovery/v1/api-metadata/${srv}.edmx`,
-          accessStrategies: [{ type: "open" }],
-        });
-      }
-
-      let obj = {
-        ordId: `${fReplaceSpecialCharacters(global.namespace)}:apiResource:${srvName}:v1`,
-        title:
-          ordExtensions.title ??
-          srvDefinition["@title"] ??
-          srvDefinition["@Common.Label"] ??
-          `The service is for ${srv}`,
-        shortDescription:
-          ordExtensions.shortDescription ??
-          `Here we have the shortDescription for ${srv}`,
-        description:
-          ordExtensions.description ??
-          srvDefinition["@Core.Description"] ??
-          `Here we have the description for ${srv}`,
-        version: ordExtensions.version ?? "1.0.0",
-        visibility: ordExtensions.visibility ?? "public",
-        partOfPackage: _getPackageID(global.capNamespace,packageIds,'api'),
-        partOfGroups: [_getGroupID(srvName, defaults.groupTypeId, global)],
-        releaseStatus: ordExtensions.active ?? "active",
-        partOfConsumptionBundles: [
-          {
-            ordId: `${fReplaceSpecialCharacters(global.namespace)}:consumptionBundle:noAuth:v1`,
-          },
-        ],
-        apiProtocol:
-          generatedPath.kind === "odata" ? "odata-v4" : generatedPath.kind,
-        resourceDefinitions: resourceDefinitions,
-        entryPoints: [generatedPath.path],
-        extensible: {
-          supported: ordExtensions["extensible.supported"] ?? "no",
-        },
-        entityTypeMappings: [{ entityTypeTargets: global.aODMEntity }],
-      };
+        let resourceDefinitions = [
+            {
+                type: "openapi-v3",
+                mediaType: "application/json",
+                url: `/.well-known/open-resource-discovery/v1/api-metadata/${serviceName}.oas3.json`,
+                accessStrategies: [{ type: "open" }],
+            },
+        ];
+
+        if (generatedPath.kind !== "rest") {
+            //edmx resource definition is not generated in case of 'rest' protocol
+            resourceDefinitions.push({
+                type: "edmx",
+                mediaType: "application/xml",
+                url: `/.well-known/open-resource-discovery/v1/api-metadata/${serviceName}.edmx`,
+                accessStrategies: [{ type: "open" }],
+            });
+        }
+
+        let obj = {
+            ordId: `${appConfig.ordNamespace}:apiResource:${serviceName}:v1`,
+            title:
+                serviceDefinition["@title"] ??
+                serviceDefinition["@Common.Label"] ??
+                serviceName,
+            shortDescription: SHORT_DESCRIPTION_PREFIX + serviceName,
+            description:
+                serviceDefinition["@Core.Description"] ??
+                DESCRIPTION_PREFIX + serviceName,
+            version: "1.0.0",
+            lastUpdate: appConfig.lastUpdate,
+            visibility: RESOURCE_VISIBILITY.public,
+            partOfPackage: _getPackageID(appConfig.ordNamespace, packageIds, ORD_RESOURCE_TYPE.api),
+            partOfGroups: [_getGroupID(serviceName, defaults.groupTypeId, appConfig)],
+            releaseStatus: "active",
+            apiProtocol:
+                generatedPath.kind === "odata" ? "odata-v4" : generatedPath.kind,
+            resourceDefinitions: resourceDefinitions,
+            entryPoints: [generatedPath.path],
+            extensible: {
+                supported: "no",
+            },
+            entityTypeMappings: [{ entityTypeTargets: appConfig.odmEntity }],
+            ...ordExtensions,
+        };
 
-      apiResources.push(obj);
+        if (obj.visibility === RESOURCE_VISIBILITY.public) apiResources.push(obj);
     });
-  }
-  if (apiResources.length > 0) return apiResources;
+
+    return apiResources;
 };
 
 /**
  * This is a template function to create Event Resource object for Event Resource Array.
+ * There can be only one event resource per service because all events are using the same protocol, they are always Cloud Events.
+ * Properties of an event resource can be overwritten by the ORD extensions. Example: visibility.
  *
- * @param {string} srv The name of the event.
- * @param {object} srvDefinition The definition of the event.
- * @returns {Object} An object for the Event Resource.
+ * @param {string} serviceName The name of the service.
+ * @param {object} serviceDefinition The definition of the service
+ * @returns {Array} An single-item array of objects for the Event Resources.
  */
-const fCreateEventResourceTemplate = (srv, srvDefinition, global,packageIds) => {
-  const ordExtensions = fReadORDExtensions(srvDefinition);
-  let srvName = srv;
-  if(!srvName.includes(global.capNamespace)){
-    srvName = global.capNamespace + "." + srv;
-  }
-  return {
-    ordId: `${fReplaceSpecialCharacters(global.namespace)}:eventResource:${srvName}:v1`,
-    title:  ordExtensions.title ?? srvDefinition['@title'] ?? srvDefinition['@Common.Label'] ?? `ODM ${global.appName.replace(/[^a-zA-Z0-9]/g, '')} Events`,
-    shortDescription: ordExtensions.shortDescription ?? "Example ODM Event",
-    description:  ordExtensions.description ?? 
-                  srvDefinition['@description'] ?? srvDefinition['@Core.Description'] ??
-                  `This is an example event catalog that contains only a partial ODM ${global.appName} V1 event`,
-    version:  ordExtensions.version ?? "1.0.0",
-    releaseStatus:  ordExtensions.releaseStatus ?? "beta",
-    partOfPackage: _getPackageID(global.capNamespace,packageIds,'event'),
-    partOfGroups: [_getGroupID(srvName, defaults.groupTypeId, global, false)],
-    visibility: ordExtensions.visibility ?? "public",
-    resourceDefinitions: [
-      {
-        type: "asyncapi-v2",
-        mediaType: "application/json",
-        url: `/.well-known/open-resource-discovery/v1/api-metadata/${srvDefinition._service.name}.asyncapi2.json`,
-        accessStrategies: [
-          {
-            type: "open",
-          },
+const createEventResourceTemplate = (serviceName, serviceDefinition, appConfig, packageIds) => {
+    const ordExtensions = readORDExtensions(serviceDefinition);
+    if (!!ordExtensions.visibility && ordExtensions.visibility !== RESOURCE_VISIBILITY.public) return [];
+    return [{
+        ordId: `${appConfig.ordNamespace}:eventResource:${serviceName}:v1`,
+        title:
+            serviceDefinition["@title"] ??
+            serviceDefinition["@Common.Label"] ??
+            `ODM ${appConfig.appName.replace(/[^a-zA-Z0-9]/g, "")} Events`,
+        shortDescription: `${serviceName} event resource`,
+        description:
+            serviceDefinition['@description'] ?? serviceDefinition['@Core.Description'] ??
+            "CAP Event resource describing events / messages.",
+        version: "1.0.0",
+        lastUpdate: appConfig.lastUpdate,
+        releaseStatus: "active",
+        partOfPackage: _getPackageID(appConfig.ordNamespace, packageIds, ORD_RESOURCE_TYPE.event),
+        partOfGroups: [_getGroupID(serviceName, defaults.groupTypeId, appConfig)],
+        visibility: RESOURCE_VISIBILITY.public,
+        resourceDefinitions: [
+            {
+                type: "asyncapi-v2",
+                mediaType: "application/json",
+                url: `/.well-known/open-resource-discovery/v1/api-metadata/${serviceName}.asyncapi2.json`,
+                accessStrategies: [
+                    {
+                        type: "open",
+                    },
+                ],
+            },
         ],
-      },
-    ],
-    extensible: { supported: ordExtensions["extensible.supported"] ?? "no" },
-  };
-};
-
+        extensible: { supported: "no" },
 
-/**
- * This is a function to check whether entity is a function or action.
- * @param {object} srvDefinition The definition of the event.
- * @returns {Object} An object for the Event Resource.
- */
-function checkEntityFunctionAction(srvDefinition, global) {
-  if (srvDefinition.entities) {
-    return srvDefinition.entities.map((entity) => {
-      return {
-        type: "entity",
-        name: entity.name,
-        entityType: entity.name,
-        entitySet: entity.name,
-        entityTypeMapping: `${global.namespace}:entityType:${entity.name}:v1`,
-        entitySetMapping: `${global.namespace}:entitySet:${entity.name}:v1`,
-      };
-    });
-  } else if (srvDefinition.actions) {
-    return srvDefinition.actions.map((action) => {
-      return {
-        type: "action",
-        name: action.name,
-        actionType: action.name,
-        actionMapping: `${global.namespace}:action:${action.name}:v1`,
-      };
-    });
-  } else if (srvDefinition.functions) {
-    return srvDefinition.functions.map((func) => {
-      return {
-        type: "function",
-        name: func.name,
-        functionType: func.name,
-        functionMapping: `${global.namespace}:function:${func.name}:v1`,
-      };
-    });
-  }
-}
+        ...ordExtensions
+    }]
+};
 
-/**
- * This is a function to get the corresponding package ordId mapped to the service.
- */
+function _getPackageID(namespace, packageIds, resourceType) {
+    if (!packageIds) return;
 
-function _getPackageID(capNamespace, packageIds, apiOrEvent) {
-  if (packageIds instanceof Set) {
-    const packageArray = Array.from(packageIds);
-    
-    if (apiOrEvent === "api") {
-      const apiPackage = packageArray.find(pkg => pkg.includes("-api"));
-      if (apiPackage) return apiPackage;
-    } else if (apiOrEvent === "event") {
-      const eventPackage = packageArray.find(pkg => pkg.includes("-event"));
-      if (eventPackage) return eventPackage;
-    }
-    
-    return packageArray.find(pkg => pkg.includes(capNamespace));
-  }
+    return packageIds.find((id) => id.includes("-" + resourceType)) || packageIds.find((id) => id.includes(namespace));
 }
 
 module.exports = {
-  fCreateEntityTypeTemplate,
-  fCreateGroupsTemplateForService,
-  fCreateGroupsTemplateForEvent,
-  fCreateAPIResourceTemplate,
-  fCreateEventResourceTemplate,
+    createEntityTypeTemplate,
+    createGroupsTemplateForService,
+    createAPIResourceTemplate,
+    createEventResourceTemplate,
 };

package/package.json

@@ -1,27 +1,34 @@
 {
-  "name": "@cap-js/ord",
-  "version": "1.0.3",
-  "description": "CAP Plugin for generating ORD document.",
-  "repository": "cap-js/ord",
-  "author": "SAP SE (https://www.sap.com)",
-  "homepage": "https://cap.cloud.sap/",
-  "license": "SEE LICENSE IN LICENSE",
-  "main": "cds-plugin.js",
-  "files": [
-    "lib",
-    "data",
-    "LICENSES"
-  ],
-  "scripts": {
-    "lint": "npx eslint ."
-  },
-  "devDependencies": {
-    "eslint": "^8"
-  },
-  "peerDependencies": {
-    "@sap/cds": "7.9.4",
-    "@sap/cds-compiler" : "5.0.6",
-    "@cap-js/asyncapi": "^1.0.0",
-    "@cap-js/openapi": "^1.0.2"
-  }
-}
+    "name": "@cap-js/ord",
+    "version": "1.2.0",
+    "description": "CAP Plugin for generating ORD document.",
+    "repository": "cap-js/ord",
+    "author": "SAP SE (https://www.sap.com)",
+    "homepage": "https://cap.cloud.sap/",
+    "license": "SEE LICENSE IN LICENSE",
+    "main": "cds-plugin.js",
+    "files": [
+        "lib",
+        "data",
+        "LICENSES"
+    ],
+    "scripts": {
+        "lint": "npx eslint .",
+        "test": "jest --ci --collectCoverage",
+        "update-snapshot": "jest --ci --updateSnapshot",
+        "cds:version": "cds v -i"
+    },
+    "devDependencies": {
+        "eslint": "^8",
+        "jest": "^29.7.0"
+    },
+    "peerDependencies": {
+        "@cap-js/asyncapi": "^1.0.0",
+        "@cap-js/openapi": "^1.0.2",
+        "@sap/cds": "^8.1.1",
+        "@sap/cds-compiler": "5.0.6"
+    },
+    "dependencies": {
+        "lodash": "^4.17.21"
+    }
+}