@sap/cds-compiler 2.10.4 → 2.12.0

package/lib/main.d.ts

@@ -4,6 +4,10 @@
 //
 // These types are improved step by step and use a lot any types at the moment.
 
+// Author's note: All "options" interfaces should actually be types.  However, due to
+//                https://github.com/TypeStrong/typedoc/issues/1519 we can't use
+//                intersection types at the moment.
+
 export = compiler;
 
 declare namespace compiler {
@@ -11,7 +15,7 @@ declare namespace compiler {
   /**
    * Options used by the core compiler and all backends.
    */
-  export type Options = {
+  export interface Options {
     [option: string]: any,
 
     /**
@@ -57,6 +61,180 @@ declare namespace compiler {
     dictionaryPrototype?: any
   }
 
+  /**
+   * Options used by OData backends.  Includes options for the OData
+   * transformer as well as for rendering EDM and EDMX.
+   */
+  export interface ODataOptions extends Options {
+    /**
+     * OData version for output files.  Either 'v4' or 'v2'.
+     *
+     * @default 'v4'
+     */
+    odataVersion?: string | 'v4' | 'v2'
+    /**
+     * Whether to generate OData as flat or as structured.
+     * Structured is only supported for OData v4.
+     *
+     * @default 'flat'
+     */
+    odataFormat?: string | 'flat' | 'structured'
+    /**
+     * Naming mode used by the corresponding SQL.
+     *
+     * @default 'plain'
+     */
+    sqlMapping?: string | 'plain' | 'quoted' | 'hdbcds'
+    /**
+     * If `true`, `cds.Compositions` are rendered as `edm:NavigationProperty` with the additional
+     * attribute `ContainsTarget="true"` and all contained entities (composition targets) have no
+     * `edm.EntitySet`.
+     *
+     * @note Only available for OData v4 EDM(X) rendering.
+     * @default false
+     */
+    odataContainment?: boolean
+    /**
+     * If `true`, render generated foreign keys for managed associations.
+     * By default foreign keys are never visible in structured OData APIs.
+     *
+     * @note Only available for structured OData v4 EDM(X) rendering.
+     * @default false
+     */
+    odataForeignKeys?: boolean
+    /**
+     * If `true`, association targets outside of the current service are added as
+     * `edm.EntityType` that only exposes their primary keys and have no `edm.EntitySet`.
+     * If the original association target is a service member, a corresponding `edm.Schema`
+     * representing the namespace of that service is added to `edm.Services`.  All association
+     * targets that are no service members are collected in an `edm.Schema` with namespace `root`.
+     *
+     * @note Only valid for structured OData v4 EDM(X) rendering.
+     * @default false
+     * @since v2.1.0
+     */
+    odataProxies?: boolean
+    /**
+     * This option is an extension to `odataProxies`.
+     * If `true`, an `edm:Reference` instead of a proxy `edm.EntityType` is rendered for each
+     * association target that is a service member outside the current service instead of proxies.
+     *
+     * @note Only valid for structured OData v4 EDM(X) rendering.
+     * @default false
+     * @since v2.1.0
+     */
+    odataXServiceRefs?: boolean
+    /**
+     * The OData specification requires that all primary keys of the principal must be used as
+     * referential constraints.  If an association is modelled with only a partial key, no
+     * referential constraints are added.  If `true`, partial constraints are rendered for
+     * backwards compatibility and mocking scenarios.  A spec violation warning is raised for
+     * each incomplete constraint.
+     *
+     * @note Only valid for OData v2 CSN transformation.
+     * @default false
+     * @since v2.2.6
+     */
+    odataV2PartialConstr?: boolean
+    /**
+     * Service name for which EDMX or EDM shall be rendered.
+     *
+     * @note Only available for `to.edmx()` and `to.edm()`.  For `to.edmx.all()`
+     *       and `to.edm.all()`, use `serviceNames` instead.
+     *
+     * @see serviceNames
+     */
+    service?: string
+    /**
+     * Array of service names for which EDMX or EDM shall be rendered.
+     * If unspecified, all services are rendered.
+     *
+     * @note Only available for `to.edmx.all()` and `to.edm.all()`.  For `to.edmx()`
+     *       and `to.edm()`, use `service` instead.
+     *
+     * @see service
+     */
+    serviceNames?: string[]
+  }
+
+  /**
+   * Options used by SQL `to.sql()` backend.
+   *
+   * @see to.sql()
+   */
+  export interface SqlOptions extends Options {
+    /**
+     * The SQL naming mode decides how names are represented.
+     * Among others, this includes whether identifiers are quoted or not (note
+     * that "smart quoting" is handled by `sqlDialect`).
+     *
+     * - `plain`:
+     *   In this naming mode, dots are replaced by underscores.
+     *   Names are neither upper-cased nor quoted, unless "smart-quoting" is used.
+     *   This mode can be used with all SQL dialects.
+     * - `quoted`:
+     *   In this mode, all identifiers are quoted.  Dots are not replaced in table
+     *   and view names but are still replaced by underscores in element names.
+     *   This mode can only be used with SQL dialect `hana`.
+     * - `hdbcds`:
+     *   This mode uses names that are compatible to SAP HANA CDS.
+     *   In this mode, all identifiers are quoted.  Dots are neither replaced in table
+     *   nor element names.  Namespace identifiers are separated from the remaining
+     *   identifier by `::`, i.e. the dot is replaced.  For example `Ns.Books`
+     *   becomes `"Ns::Books"`.
+     *   This mode can only be used with SQL dialect `hana`.
+     *
+     * @default 'plain'
+     */
+    sqlMapping?: string | 'plain' | 'quoted' | 'hdbcds'
+    /**
+     * Use this option to specify what dialect of SQL you want.
+     *
+     * Different databases may support different feature sets of SQL.
+     * For example, timestamps are handled differently.  Furthermore, "smart-quoting"
+     * is enabled for `sqlite` and `hana`.  This is useful if identifiers
+     * collide with reserved keywords.
+     *
+     * - `plain`:
+     *   Use this option for best compatibility with standard SQL.
+     *   Note that "smart-quoting" is not available for this mode.
+     *   Requires `sqlMapping: 'plain'`.
+     * - `sqlite`:
+     *   This SQL dialect ensures compatibility with SQLite, which may not support
+     *   all SQL features used in your CDS files.  For example, `$at.from`/`$at.to` are
+     *   handled differently to ensure correctness for SQLite.  "smart-quoting"
+     *   quotes identifiers that are reserved keywords, but does not upper-case them.
+     *   Requires `sqlMapping: 'plain'`.
+     * - `hana`:
+     *   Use this SQL dialect for best compatibility with SAP HANA.
+     *   "smart-quoting" upper-cases and quotes identifiers.
+     *
+     * @default 'plain'
+     */
+    sqlDialect?: string | 'plain' | 'sqlite' | 'hana'
+    /**
+     * Object containing magic variables.  These magic variables are
+     * used as placeholder values.
+     *
+     * @since 2.11.0
+     */
+    variableReplacements?: {
+      [option: string]: string | object,
+      /**
+       * Commonly used placeholders for user's name and locale.
+       */
+      $user?: {
+        [option: string]: string | object,
+        id?: string
+        locale?: string
+      },
+      /**
+       * Commonly used placeholders for session variables.
+       */
+      $session?: Record<string, string | object>
+    }
+  }
+
   /**
    * The compiler's package version.
    * For more details on versioning and SemVer, see `doc/Versioning.md`
@@ -83,6 +261,7 @@ declare namespace compiler {
    * {@link CompilationError} containing a vector of individual errors.
    *
    * @param filenames Array of files that should be compiled.
+   * @param dir Working directory. Relative paths in `filenames` will be resolved relatively to this directory.
    * @param options  Compiler options. If you do not set `messages`, they will be printed to console.
    * @param fileCache A dictionary of absolute file names to the file content with values:
    *  - false: the file does not exist
@@ -138,7 +317,7 @@ declare namespace compiler {
    * _Note_: Sorting is done in-place.
    *
    * Example of sorted messages:
-   * ```txt
+   * ```
    * A.cds:1:11: Info    id-3: First message text   (in entity:“E”/element:“c”)
    * A.cds:8:11: Error   id-5: Another message text (in entity:“C”/element:“g”)
    * B.cds:3:10: Debug   id-7: First message text   (in entity:“B”/element:“e”)
@@ -188,10 +367,11 @@ declare namespace compiler {
    * form (i.e. one line)
    *
    * Example:
-   * ```txt
+   * ```
    * <source>.cds:3:11: Error message-id: Can't find type `nu` in this scope (in entity:“E”/element:“e”)
    * ```
    *
+   * @param msg               Compiler message which shall be stringified.
    * @param normalizeFilename If true, the file path will be normalized to use `/` as the path separator.
    * @param noMessageId       If true, the message ID will _not_ be part of the string.
    * @param noHome            If true, the semantic location will _not_ be part of the string.
@@ -201,26 +381,30 @@ declare namespace compiler {
   /**
    * Returns a message string with file- and semantic location if present
    * in multiline form.
-   * The error (+ message id) will be colored according to their severity if
-   * run on a TTY.
+   * The error (+ message id) can colored according to their severity.
    *
    * Example:
-   * ```txt
-   * Error[message-id]: Can't find type `nu` in this scope (in entity:“E”/element:“e”)
+   * ```
+   * Error[message-id]: Can't find type `nu` in this scope
    *    |
-   *   <source>.cds:3:11, at entity:“E”
+   *   <source>.cds:3:11, at entity:“E”/element:“e”
    * ```
    *
    * @param config.normalizeFilename If true, the file path will be normalized to use `/` as the path separator.
    * @param config.noMessageId       If true, no messages id (in brackets) will be shown.
    * @param config.hintExplanation   If true, messages with explanations will get a "…" marker, see {@link hasMessageExplanation}.
    * @param config.withLineSpacer    If true, an additional line (with `|`) will be inserted between message and location.
+   * @param config.color             If true, ANSI escape codes will be used for coloring the severity.  If false, no
+   *                                 coloring will be used.  If 'auto', we will decide based on certain factors such
+   *                                 as whether the shell is a TTY and whether the environment variable 'NO_COLOR' is
+   *                                 unset.
    */
   export function messageStringMultiline(msg: CompileMessage, config?: {
     normalizeFilename?: boolean
     noMessageId?: boolean
     hintExplanation?: boolean
     withLineSpacer?: boolean
+    color?: boolean | 'auto'
   }): string;
 
   /**
@@ -233,16 +417,24 @@ declare namespace compiler {
    * All lines are prepended by a pipe (`|`) and show the corresponding line number.
    *
    * Example Output:
-   * ```txt
+   * ```
    *     |
    *  13 |     num * nu
    *     |           ^^
    * ```
    *
-   * @param sourceLines The source code split up into lines, e.g. by `str.split(/\r\n?|\n/);`.
-   * @param msg         Message whose location is used to print the message context.
+   * @param sourceLines  The source code split up into lines, e.g. by `str.split(/\r\n?|\n/);`.
+   * @param msg          Message whose location is used to print the message context.
+   * @param config       Configuration for the message context.
+   * @param config.color If true, ANSI escape codes will be used for coloring the severity.  If false, no
+   *                     coloring will be used.  If 'auto', we will decide based on certain factors such
+   *                     as whether the shell is a TTY and whether the environment variable 'NO_COLOR' is
+   *                     unset.
+
    */
-  export function messageContext(sourceLines: string[], msg: CompileMessage): string;
+  export function messageContext(sourceLines: string[], msg: CompileMessage, config?: {
+    color?: boolean | 'auto'
+  }): string;
 
   /**
    * Get an explanatory text for a complicated compiler message with ID
@@ -312,25 +504,32 @@ declare namespace compiler {
   export function parseToExpr(cdl: string, filename?: string, options?: Options): any;
 
   /**
-   * @todo Actual name is "for" which isn't used in the doc as it is a reserved name.
-   * @alias for
+   * @note Actual name is "for" which can't be used directly in the documentation as it is a reserved name.
+   * @see for
    */
-  export namespace For {
-    function odata(): any;
+  export namespace _for {
+    /**
+     * Transform the given (generic) CSN into one that is used for OData.
+     * Changes include flattening, type resolution and more, according to
+     * the provided options.
+     */
+    function odata(csn: CSN, options: ODataOptions): any;
   }
 
+  export { _for as for };
+
   export namespace to {
       function cdl(csn: CSN, options: Options): object;
-      function sql(csn: CSN, options: Options): any;
+      function sql(csn: CSN, options: SqlOptions): any;
 
-      function edm(csn: CSN, options: Options): any;
+      function edm(csn: CSN, options: ODataOptions): any;
       namespace edm {
-          function all(csn: CSN, options: Options): any;
+          function all(csn: CSN, options: ODataOptions): any;
       }
 
-      function edmx(csn: CSN, options: Options): any;
+      function edmx(csn: CSN, options: ODataOptions): any;
       namespace edmx {
-          function all(csn: CSN, options: Options): any;
+          function all(csn: CSN, options: ODataOptions): any;
       }
 
       function hdbcds(csn: CSN, options: Options): any;

package/lib/main.js

@@ -21,6 +21,7 @@ const { createMessageFunctions, sortMessages, sortMessagesSeverityAware, dedupli
 
 const parseLanguage = require('./language/antlrParser');
 const { parseX, compileX, compileSyncX, compileSourcesX, InvocationError } = require('./compiler');
+const { fns } = require('./compiler/shared');
 const { define } = require('./compiler/definer');
 
 // The compiler version (taken from package.json)
@@ -43,13 +44,15 @@ const { compactModel, compactQuery, compactExpr } = require('./json/to-csn')
 function parseCdl( cdl, filename, options = {} ) {
   options = Object.assign( {}, options, { parseCdl: true } );
   const sources = Object.create(null);
-  const model = { sources, options };
+  /** @type {XSN.Model} */
+  const model = { sources, options, $functions: {}, $volatileFunctions: {} };
   const messageFunctions = createMessageFunctions( options, 'parse', model );
   model.$messageFunctions = messageFunctions;
 
   const xsn = parseLanguage( cdl, filename, Object.assign( { parseOnly: true }, options ),
                              messageFunctions );
   sources[filename] = xsn;
+  fns( model );
   define( model );
   messageFunctions.throwWithError();
   return compactModel( model );
@@ -77,8 +80,8 @@ module.exports = {
   // Compiler
   version,
   compile: (...args) => compileX(...args).then( compactModel ), // main function
-  compileSync: (...args) => compactModel( compileSyncX(...args) ), // main function
-  compileSources: (...args) => compactModel( compileSourcesX(...args) ), // main function
+  compileSync: (filenames, dir, options, fileCache) => compactModel( compileSyncX(filenames, dir, options, fileCache) ), // main function
+  compileSources: (sourcesDict, options) => compactModel( compileSourcesX(sourcesDict, options) ), // main function
   compactModel: csn => csn,     // for easy v2 migration
   CompilationError,
   sortMessages,

package/lib/model/api.js

@@ -15,7 +15,7 @@
  * - the ‹property name› (might be useful if the same function is used for several props)
  */
 const defaultFunctions = {
-  '@': () => {},                // do not traverse annotation assignments
+  '@': () => { /* do not traverse annotation assignments */ },
   args: dictionary,
   elements: dictionary,
   enum: dictionary,
@@ -23,7 +23,7 @@ const defaultFunctions = {
   actions: dictionary,
   mixin: dictionary,
   definitions: dictionary,
-  '$': () => {},                // do not traverse properties starting with '$'
+  '$': () => { /*  do not traverse properties starting with '$' */},
 }
 
 /**