@sap/cds-dk 6.5.1 → 6.6.0

package/lib/compile/asyncapi/components/schemas/utils.js

@@ -0,0 +1,108 @@
+
+function toString(element) {
+    let schema = getBaseTypeStructure("string");
+
+    if ('length' in element && typeof element.length === 'number') {
+        schema.maxLength = element.length;
+    }
+
+    return schema;
+}
+
+function getBaseTypeStructure(type) {
+    return { type: type };
+}
+
+function getFormatStructure(format, example) {
+    let schema = getBaseTypeStructure("string");
+
+    schema.format = format;
+    if (example) {
+        schema.example = [example];
+    }
+
+    return schema;
+}
+
+function isAssociation(entry) {
+    return !!entry && entry.type === 'cds.Association';
+}
+
+function isComposition(entry) {
+    return !!entry && entry.type === 'cds.Composition';
+}
+
+function isStructured(entry) {
+    return !!entry && typeof entry === 'object' && 'elements' in entry && isElements(entry.elements);
+}
+
+function isToMany(entry) {
+    return entry.cardinality?.max === '*' || (typeof entry.cardinality?.max === 'number' && entry.cardinality?.max > 1);
+}
+
+function isDefault(entry) {
+    return "default" in entry;
+}
+
+function isEnum(entry) {
+    return "enum" in entry;
+}
+
+function addDefaultValue(entry, schema) {
+    schema.default = entry.default.val;
+}
+
+function isVal(value) {
+    return typeof value === 'object' && !!value && 'val' in value && Object.keys(value).length === 1;
+}
+
+function isElements(value) {
+    return typeof value === 'object' && !!value && !Array.isArray(value) && !('=' in value) && !isVal(value);
+}
+
+function isManyEntry(entry) {
+    return (
+        'items' in entry &&
+        typeof entry.items === 'object' &&
+        !!entry.items &&
+        (('type' in entry.items && typeof entry.items.type === 'string') ||
+          ('elements' in entry.items && isElements(entry.items.elements)))
+    );
+}
+
+function isLocalizedElement(name, element) {
+    return (((name === 'texts' && isComposition(element)) || (name === 'localized' && isAssociation(element))) &&
+        element.target.endsWith('.texts'));
+}
+
+function isToManyAssociation(entry) {
+    return isAssociation(entry) && isToMany(entry);
+}
+
+function elementIsRelevant(name, element) {
+    return !isLocalizedElement(name, element);
+}
+
+function isRefEntry(entry) {
+    let type = entry.type;
+    return typeof type === 'object' && !!type && 'ref' in type && Array.isArray(type.ref);
+}
+
+module.exports = {
+    toString,
+    getBaseTypeStructure,
+    getFormatStructure,
+    isAssociation,
+    isComposition,
+    isStructured,
+    isToMany,
+    isDefault,
+    addDefaultValue,
+    isEnum,
+    isVal,
+    elementIsRelevant,
+    isManyEntry,
+    isElements,
+    isRefEntry,
+    isToManyAssociation
+}

package/lib/compile/asyncapi/index.js

@@ -0,0 +1,226 @@
+const csnToJSONSchema = require('./components/schemas');
+const getMessageTraits = require('./components/messageTraits');
+const definitionsToMessages = require('./components/messages');
+const getChannels = require('./channels');
+const cds = require('../../cds');
+const messages = require("./message");
+const presetMapping = {
+    'event_spec_version': 'x-sap-event-spec-version',
+    'event_source': 'x-sap-event-source',
+    'event_source_params': 'x-sap-event-source-parameters',
+    'event_characteristics': 'x-sap-event-characteristics'
+};
+
+module.exports = function processor(csn, options = {}) {
+
+    const envConf = cds.env.export?.asyncapi;
+    _serviceErrorHandling(csn, options);
+
+    const applicationNamespace = envConf?.application_namespace;
+
+    if (!applicationNamespace) {
+        throw new Error(messages.APPLICATION_NAMESPACE);
+    }
+
+    const presets = getPresets(envConf);
+
+    if (options.service === 'all') {
+        if (options["asyncapi:merged"]) {
+            if (!envConf?.merged?.title || !envConf.merged?.version ) {
+                throw new Error(messages.TITLE_VERSION_MERGED);
+            }
+
+            const infoObject = getInfoObject({}, envConf.merged);
+            // verify version follows the required pattern
+            isVersionValid(infoObject.version);
+            const shortTextObj = getShortText({}, envConf.merged.short_text);
+
+            const events = getEvents(csn.definitions);
+
+            return {
+                asyncapi: '2.0.0',
+                'x-sap-catalog-spec-version': '1.2',
+                'x-sap-application-namespace': applicationNamespace,
+                ...Object.keys(shortTextObj).length && { 'x-sap-shortText': shortTextObj },
+                info: infoObject,
+                defaultContentType: 'application/json',
+                channels: getChannels(csn.definitions, events),
+                components: getComponents(csn.definitions, events, presets)
+            }
+        } else {
+            const services  = getServicesWithEvents(csn.definitions);
+            return _iterate(services, csn, applicationNamespace, presets);
+        }
+    } else {
+        const events = getEvents(csn.definitions, options.service);
+
+        if (events.length === 0) {
+            throw new Error(messages.NO_EVENTS);
+        }
+
+        return _getAsyncApi(csn, events, options.service, applicationNamespace, presets);
+    }
+}
+
+function getPresets(envConf) {
+    let projectPresets = {};
+    for (const [key, value] of Object.entries(envConf)) {
+        if (presetMapping[key]) projectPresets[presetMapping[key]] = value;
+    }
+    return projectPresets;
+}
+
+function _getAsyncApi(csn, events, serviceName, applicationNamespace, presets) {
+
+    const infoObject = getInfoObject(csn.definitions[serviceName]);
+    const stateObj = getStateInfo(csn.definitions[serviceName]);
+    const shortTextObj = getShortText(csn.definitions[serviceName]);
+
+    return {
+        asyncapi: '2.0.0',
+        'x-sap-catalog-spec-version': '1.2',
+        'x-sap-application-namespace': applicationNamespace,
+        ...Object.keys(stateObj).length && { 'x-sap-stateInfo': stateObj },
+        ...Object.keys(shortTextObj).length && { 'x-sap-shortText': shortTextObj },
+        info: infoObject,
+        defaultContentType: 'application/json',
+        channels: getChannels(csn.definitions, events),
+        components: getComponents(csn.definitions, events, presets)
+    };
+}
+
+function getShortText(serviceCsn, presetValue = undefined) {
+    let shortTextValue = presetValue || serviceCsn["@AsyncAPI.ShortText"];
+    if (shortTextValue) {
+        return shortTextValue;
+    }
+    return {};
+}
+
+function getStateInfo(serviceCsn) {
+    const stateProperties = ['state', 'deprecationDate', 'decomissionedDate', 'link'];
+    const stateObj = {};
+
+    stateProperties.forEach(function (item) {
+        if (serviceCsn['@AsyncAPI.StateInfo.' + item]) {
+            stateObj[item] = serviceCsn['@AsyncAPI.StateInfo.' + item];
+        }
+    });
+
+    return stateObj;
+}
+
+function getInfoObject(serviceCsn, mergedPresetObject = undefined) {
+    const info = {};
+
+    if (mergedPresetObject) {
+        Object.keys(mergedPresetObject).forEach(key => {
+            if (key !== "short_text")  info[key] = mergedPresetObject[key];
+        });
+        return info;
+    }
+
+    if (!serviceCsn['@AsyncAPI.SchemaVersion'] || !serviceCsn['@AsyncAPI.Title']) {
+        throw new Error(messages.TITLE_VERSION_ANNOTATIONS);
+    }
+
+    isVersionValid(serviceCsn['@AsyncAPI.SchemaVersion']);
+
+    info.version = serviceCsn['@AsyncAPI.SchemaVersion'];
+    info.title = serviceCsn['@AsyncAPI.Title'];
+
+    if (serviceCsn['@AsyncAPI.Description']) {
+        info.description = serviceCsn['@AsyncAPI.Description'];
+    }
+
+    return info;
+}
+
+function isVersionValid(version) {
+    version.split('.').forEach(element => {
+        if (isNaN(element)) {
+            throw new Error(messages.UNSUPPORTED_VERSION);
+        }
+    });
+    return true;
+}
+
+function getEvents(definitions, service = '') {
+    let events = [];
+    for (const [key, value] of Object.entries(definitions)) {
+        if (value.kind === 'event' && value._service !== undefined) {
+            if (service === '' || value._service.name === service) {
+                events.push(key);
+            }
+        }
+    }
+    return events;
+}
+
+function getServicesWithEvents(definitions) {
+    const services = {};
+
+    // traverse the definitions list and extract services
+    for (const [key, value] of Object.entries(definitions)) {
+        if (value.kind === 'service') {
+            services[key] = {
+                events: []
+            };
+        }
+    }
+
+    // traverse the definitions list and map events to services
+    for (const [key, value] of Object.entries(definitions)) {
+        if (value.kind === 'event' && value._service) {
+            services[value._service.name].events.push(key);
+        }
+    }
+
+    // traverse the services list and remove service with no events
+    for (const [key, value] of Object.entries(services)) {
+        if (value.events.length === 0) {
+            delete services[key];
+        }
+    }
+
+    return services;
+}
+
+function getComponents(definitions, events, presets) {
+
+    return {
+        messageTraits: getMessageTraits(),
+        messages: definitionsToMessages(definitions, events, presets),
+        schemas: csnToJSONSchema(definitions, events)
+    }
+}
+
+function _serviceErrorHandling(csn, options) {
+    const services = cds.linked(csn).services;
+
+    if (services.length < 1) throw new Error(messages.NO_SERVICES);
+
+    if (!options.service && services.length > 1) throw new Error(`\n
+      Found multiple service definitions in given model(s).
+      Please choose by adding one of... \n
+      -s all ${services.map(s => `\n      -s ${s.name}`).join('')}
+    `);
+
+    if (!options.service) {
+      options.service = services[0].name;
+    } else if (options.service !== 'all') {
+      const srv = services.find(s => s.name === options.service);
+      if (!srv) throw new Error(`Service definition with given ${options.service} not found in the model(s).`);
+    }
+
+    if (options["asyncapi:merged"] && options.service !== 'all') {
+        throw new Error(messages.MERGED_FLAG);
+    }
+}
+
+function* _iterate(services, csn, applicationNamespace, presets) {
+    for (const [key, value] of Object.entries(services)) {
+        const generatedAsyncAPI = _getAsyncApi(csn, value.events, key, applicationNamespace, presets);
+        yield [generatedAsyncAPI, { file: key }];
+    }
+}

package/lib/compile/asyncapi/message.js

@@ -0,0 +1,13 @@
+"use strict";
+
+const errorMessages = {
+    APPLICATION_NAMESPACE: 'Preset for application namespace needs to be added.',
+    TITLE_VERSION_MERGED: 'Preset for Title and Version info needs to be added when merged flag is used.',
+    NO_EVENTS: 'No events found in the service.',
+    TITLE_VERSION_ANNOTATIONS: 'Title and Version info annotations needs to be added to the service(s).',
+    UNSUPPORTED_VERSION: 'The version value provided is unsupported.',
+    NO_SERVICES: 'There are no service definitions found in the given model(s).',
+    MERGED_FLAG: 'Merged flag cannot be used with single service definition.',
+};
+
+module.exports = errorMessages;

package/lib/compile/asyncapi/utils.js

@@ -0,0 +1,27 @@
+/**
+ * Returns value of EventType Annotation if it is present. Otherwise it returns the definition name only.
+ */
+function getEventName(eventName, eventDefinition) {
+
+    if (eventDefinition["@AsyncAPI.EventType"]) {
+        eventName = eventDefinition["@AsyncAPI.EventType"];
+    }
+
+    return eventName;
+}
+
+/**
+ * Gets the property value from the entry if it is defined otherwise returns undefined.
+ */
+function getOwnValue(entry, key) {
+    if (Object.prototype.hasOwnProperty.call(entry, key)) {
+        return entry[key];
+    }
+
+    return;
+}
+
+module.exports = {
+    getEventName,
+    getOwnValue
+}

package/lib/compile/index.js

@@ -4,6 +4,7 @@ const { defineProperty } = Object
 
 'xsuaa'   in comp_to || defineProperty (comp_to, 'xsuaa',   {enumerable:true, get:()=> require('./to-xsuaa')})
 'openapi' in comp_to || defineProperty (comp_to, 'openapi', {enumerable:true, get:()=> require('./openapi')})
+'asyncapi' in comp_to || defineProperty (comp_to, 'asyncapi', {enumerable:true, get:()=> require('./asyncapi')})
 
 'edmx-v2' in comp_to || defineProperty (comp_to, 'edmx-v2', {enumerable:true, value: (csn,o) => comp_to.edmx(csn,{...o,flavor:'v2'})})
 'edmx-v4' in comp_to || defineProperty (comp_to, 'edmx-v4', {enumerable:true, value: (csn,o) => comp_to.edmx(csn,{...o,flavor:'v4'})})

package/lib/compile/openapi/csdl2openapi.js

@@ -24,14 +24,23 @@ const SUFFIX = {
     read: "",
     create: "-create",
     update: "-update",
-  };
-  
-  const TITLE_SUFFIX = {
+};
+
+const TITLE_SUFFIX = {
     "": "",
     "-create": " (for create)",
     "-update": " (for update)",
-  };
-  
+};
+
+/**
+ * ODM annotations in CDS that should be converted into OpenAPI.
+ */
+const ODM_ANNOTATIONS = Object.freeze(
+    {
+        '@ODM.entityName': 'x-sap-odm-entity-name',
+        '@ODM.oid': 'x-sap-odm-oid',
+    });
+
 /**
  * Construct an OpenAPI description from a CSDL document
  * @param {object} csdl CSDL document
@@ -210,7 +219,7 @@ module.exports.csdl2openapi = function (
         const terms = {
             Authorization: ['Authorizations', 'SecuritySchemes'],
             Capabilities: ['BatchSupport', 'BatchSupported', 'ChangeTracking', 'CountRestrictions', 'DeleteRestrictions', 'DeepUpdateSupport', 'ExpandRestrictions',
-                'FilterRestrictions', 'IndexableByKey', 'InsertRestrictions', 'KeyAsSegmentSupported', 'NavigationRestrictions', 'OperationRestrictions', 
+                'FilterRestrictions', 'IndexableByKey', 'InsertRestrictions', 'KeyAsSegmentSupported', 'NavigationRestrictions', 'OperationRestrictions',
                 'ReadRestrictions', 'SearchRestrictions', 'SelectSupport', 'SkipSupported', 'SortRestrictions', 'TopSupported', 'UpdateRestrictions'],
             Core: ['AcceptableMediaTypes', 'Computed', 'DefaultNamespace', 'Description', 'Example', 'Immutable', 'LongDescription',
                 'OptionalParameter', 'Permissions', 'SchemaVersion'],
@@ -248,8 +257,8 @@ module.exports.csdl2openapi = function (
             description = containerSchema[voc.Core.LongDescription];
         }
         else {
-            description = ('This service is located at [' + serviceRoot + '/](' 
-            + serviceRoot.replace(/\(/g, '%28').replace(/\)/g, '%29') + '/)');
+            description = ('This service is located at [' + serviceRoot + '/]('
+                + serviceRoot.replace(/\(/g, '%28').replace(/\)/g, '%29') + '/)');
         }
         description += (diagram ? getResourceDiagram(csdl, entityContainer) : '');
         let title;
@@ -266,7 +275,7 @@ module.exports.csdl2openapi = function (
             title = 'OData CSDL document';
         }
         return {
-            title: title, 
+            title: title,
             description: csdl.$EntityContainer ? description : '',
             version: containerSchema[voc.Core.SchemaVersion] || ''
         };
@@ -437,7 +446,7 @@ module.exports.csdl2openapi = function (
                 throw new Error(`The input server object is invalid.`);
             }
 
-            if(!servers.length){
+            if (!servers.length) {
                 throw new Error(`The input server object should be an array.`);
             }
         } else {
@@ -712,7 +721,7 @@ module.exports.csdl2openapi = function (
                 tags: [sourceName],
                 parameters: [],
                 responses: response(200, 'Retrieved ' + (byKey ? pluralize.singular(lname) : lname), { $Type: element.$Type, $Collection: collection },
-                byKey ? readByKeyRestrictions?.ErrorResponses : readRestrictions?.ErrorResponses)
+                    byKey ? readByKeyRestrictions?.ErrorResponses : readRestrictions?.ErrorResponses)
             };
             const deltaSupported = element[voc.Capabilities.ChangeTracking] && element[voc.Capabilities.ChangeTracking].Supported;
             if (!byKey && deltaSupported) {
@@ -1412,7 +1421,7 @@ see [Expand](http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-prot
                 summary: actionImport[voc.Core.Description] || overload[voc.Core.Description] || 'Invoke action ' + name,
                 tags: [overload[voc.Common.Label] || sourceName || 'Service Operations'],
                 responses: overload.$ReturnType ? response(200, "Success", overload.$ReturnType, overload[voc.Capabilities.OperationRestrictions]?.ErrorResponses)
-                : response(204, "Success", undefined, overload[voc.Capabilities.OperationRestrictions]?.ErrorResponses),
+                    : response(204, "Success", undefined, overload[voc.Capabilities.OperationRestrictions]?.ErrorResponses),
             }
         };
         const description = actionImport[voc.Core.LongDescription] || overload[voc.Core.LongDescription];
@@ -1599,7 +1608,7 @@ see [Expand](http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-prot
      * @param {object} type Response type object
      * @param {array} errors Array of operation-specific status codes with descriptions
      */
-     function response(code, description, type, errors) {
+    function response(code, description, type, errors) {
         const r = {};
         r[code] = {
             description: description
@@ -1829,6 +1838,8 @@ see [Expand](http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-prot
         if (Object.keys(schemaProperties).length > 0)
             schemas[schemaName].properties = schemaProperties;
 
+        odmExtensions(type, schemas[schemaName]);
+
         if (suffix === SUFFIX.create && required.length > 0)
             schemas[schemaName].required = [...new Set(required)];
 
@@ -1846,6 +1857,17 @@ see [Expand](http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-prot
         }
     }
 
+    /**
+     * Add ODM extensions to OpenAPI schema for a structured type
+     * @param {object} type Structured type
+     * @param {object} schema OpenAPI schema to augment
+     */
+    function odmExtensions(type, schema) {
+        for (const [annotation, openApiExtension] of Object.entries(ODM_ANNOTATIONS)) {
+            if (type[annotation]) schema[openApiExtension] = type[annotation];
+        }
+    }
+
     /**
      * Collect all properties of a structured type along the inheritance hierarchy
      * @param {object} type Structured type
@@ -2022,7 +2044,7 @@ see [Expand](http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-prot
                 break;
             case 'Edm.Decimal':
                 s = {
-                    anyOf: [{ type: 'number', format: 'decimal'}, { type: 'string' }],
+                    anyOf: [{ type: 'number', format: 'decimal' }, { type: 'string' }],
                     example: 0
                 };
                 // eslint-disable-next-line no-case-declarations
@@ -2164,13 +2186,13 @@ see [Expand](http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-prot
         if (forFunction) {
             if (s.example && typeof s.example === "string") {
                 s.example = `${pathValuePrefix(element.$Type)}${s.example
-                    }${pathValueSuffix(element.$Type)}`;
+                    }${pathValueSuffix(element.$Type)} `;
             }
             if (s.pattern) {
                 const pre = pathValuePrefix(element.$Type);
                 const suf = pathValueSuffix(element.$Type);
-                s.pattern = s.pattern.replace(/^\^/, `^${pre}(`);
-                s.pattern = s.pattern.replace(/\$$/, `)${suf}$`);
+                s.pattern = s.pattern.replace(/^\^/, `^ ${pre} (`);
+                s.pattern = s.pattern.replace(/\$$/, `)${suf} $`);
             } else if (!element.$Type || element.$Type === "Edm.String") {
                 s.pattern = "^'([^']|'')*'$";
             }
@@ -2388,4 +2410,4 @@ see [Expand](http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-prot
         return !name.startsWith('$') && !name.includes('@');
     }
 
-};
+};

package/lib/import/message.js

@@ -15,7 +15,9 @@ const messages = {
 	INCORRECT_INPUT_NAMESPACES: 'Invalid value for --include-namespaces option. Specify namespaces as comma-separated list or "*"',
 	MISSING_ASSOCIATION: 'Association is missing in the input file provided. Please check the edmx file.',
 	COLLECTION_IN_KEY: 'Key Property of an Entity cannot be of the type Collection.',
-	INVALID_OPENAPI_FILE: 'The OpenAPI file is not valid. Specify the correct OpenAPI file.'
+	INVALID_OPENAPI_FILE: 'The OpenAPI file is not valid. Specify the correct OpenAPI file.',
+	UNRESOLVED_TYPE: 'Could not resolve the type: ',
+	NO_RETURN_TYPE: 'No ReturnType found in Function: '
 };
 
 function getMessages() {

package/lib/import/odata/metadataconverter/MetadataConverter.js

@@ -2198,7 +2198,7 @@ class ReturnTypeExpression extends Expression {
         const target = {};
         this.setTarget(target);
 
-        this.buildTypeCollectionAndFacets('$Type', '$Nullable', '$Precision', '$Scale');
+        this.buildTypeCollectionAndFacets('$Type', '$MaxLength', '$Nullable', '$Precision', '$Scale');
         super.interpret();
         return { $ReturnType: target };
     }