@sap/cds-compiler 2.12.0 → 2.13.6

package/lib/main.d.ts

@@ -5,7 +5,7 @@
 // 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
+//                <https://github.com/TypeStrong/typedoc/issues/1519> we can't use
 //                intersection types at the moment.
 
 export = compiler;
@@ -59,6 +59,36 @@ declare namespace compiler {
      * Dictionaries are e.g. "definitions" and "elements".
      */
     dictionaryPrototype?: any
+    /**
+     * CSN Flavor:  The compiler supports different CSN flavors.  Backends may support
+     * different flavors. This option is mainly used in `compile()`.
+     * Flavors are:
+     *  - client    : (default) Standard CSN consumable by clients and backends.
+     *  - gensrc    : CSN specifically for use as a source, e.g. for combination with
+     *                additional "extend" or "annotate" statements, but not suitable
+     *                for consumption by clients or backends.
+     *  - universal : In development (BETA)
+     */
+    csnFlavor?: string | 'client' | 'gensrc' | 'universal'
+  }
+
+  /**
+   * Options relevant for compilation and parsing of CDL and CSN files.
+   */
+  export interface CompileOptions extends Options {
+    /**
+     * If the given filename does not have a known file extension,
+     * use this frontend as the fallback parser.
+     */
+    fallbackParser?: string | 'cdl' | 'csn'
+    /**
+     * Option for {@link compileSources}.  If set, all objects inside the
+     * provided sources dictionary are interpreted as XSN structures instead
+     * of CSN, i.e. a compiler-internal representation.
+     *
+     * @since v2.12.1
+     */
+    $xsnObjects?: boolean
   }
 
   /**
@@ -235,6 +265,90 @@ declare namespace compiler {
     }
   }
 
+  /**
+   * Options used by to.hdbcds()
+   */
+  export interface HdbcdsOptions extends Options {
+    /**
+     * The SQL naming mode decides how names are represented.
+     * Among others, this includes whether identifiers are quoted or not.
+     *
+     * - `plain`:
+     *   In this naming mode, dots are replaced by underscores.
+     *   Identifiers are always uppercased. If "smart-quoting" is used, they are also quoted
+         if they are also HDBCDS keywords.
+     * - `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.
+     *   Identifier casing is kept as specified in the source.
+     * - `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: Structured elements persist, contexts are nested.
+     *   Managed associations/compositions are left as-is.  No association-to-join-translation
+     *   is done.
+     *
+     * @default 'plain'
+     */
+    sqlMapping?: string | 'plain' | 'quoted' | 'hdbcds'
+    /**
+     * For to.hdbcds(), the SQL dialect is always set to 'hana'.
+     */
+    sqlDialect?: 'hana'
+  }
+
+  /**
+   * Options used by to.hdi() and to.hdi.migration()
+   */
+  export interface HdiOptions extends Options {
+    /**
+     * The SQL naming mode decides how names are represented.
+     * Among others, this includes whether identifiers are quoted or not.
+     *
+     * - `plain`:
+     *   In this naming mode, dots are replaced by underscores.
+     *   Names are neither upper-cased nor quoted, unless "smart-quoting" is used.
+     * - `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.
+     * - `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"`.
+     *
+     * @default 'plain'
+     */
+    sqlMapping?: string | 'plain' | 'quoted' | 'hdbcds'
+    /**
+     * For to.hdi(), the SQL dialect is always set to 'hana'.
+     */
+    sqlDialect?: 'hana'
+    /**
+     * Only for to.hdi.migration().
+     * SQL change mode to use (for changed columns).
+     *
+     * @default 'alter'
+     */
+    sqlChangeMode?: string | 'alter' | 'drop'
+    /**
+     * Only for `to.hdi.migration`.  If `true`, `to.hdi.migration` allows that the two
+     * passed CSNs are of different CSN versions.  Use at own risk.
+     *
+     * @default false
+     */
+    allowCsnDowngrade?: boolean
+  }
+
+  /**
+   * Options used by `to.cdl()` backend.
+   *
+   * @note `to.cdl()` currently has no specific options.
+   * @see to.cdl()
+   */
+  export interface CdlOptions extends Options {}
+
   /**
    * The compiler's package version.
    * For more details on versioning and SemVer, see `doc/Versioning.md`
@@ -245,7 +359,7 @@ declare namespace compiler {
    * Main function: Compile the sources from the files given by the array of
    * `filenames`.  As usual with the `fs` library, relative file names are
    * relative to the working directory `process.cwd()`.  With argument `dir`, the
-   * file names are relative to `process.cwd()+dir`.
+   * file names are relative to `process.cwd()+dir` (or just `dir` if it is absolute).
    *
    * This function returns a Promise and can be used with `await`.  For an example
    * see `examples/api-usage/`.
@@ -263,15 +377,32 @@ declare namespace compiler {
    * @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
-   *  - true: file exists (fstat), no further knowledge yet - i.e. value will change!
-   *  - 'string' or Buffer: the file content
-   *  - { realname: fs.realpath(filename) }: if filename is not canonicalized
+   * @param fileCache
+   */
+  export function compile(filenames: string[], dir?: string, options?: CompileOptions, fileCache?: FileCache): Promise<CSN>;
+
+  /**
+   * Synchronous version of {@link compile}.
+   * Usage is discouraged.  Use the asynchronous version if possible.
+   *
+   * @see compile
    */
-  export function compile(filenames: string[], dir?: string, options?: Options, fileCache?: Record<string, any>): Promise<any>;
-  export function compileSync(filenames: string[], dir?: string, options?: Options, fileCache?: Record<string, any>): any;
-  export function compileSources(sourcesDict: any, options?: Options): any;
+  export function compileSync(filenames: string[], dir?: string, options?: CompileOptions, fileCache?: FileCache): CSN;
+
+  /**
+   * Synchronously compiles the given sources.
+   *
+   * Argument `sourcesDict` is a dictionary mapping filenames to either source texts (string)
+   * or JavaScript objects, which are usually CSNs, or XSNs (compiler internal AST-like augmented CSNs).
+   * The latter requires option `$xsnObjects` to be set to `true`.
+   * It could also be a simple string, which is then considered to be the source
+   * text of a file named `<stdin>.cds`.
+   *
+   * See function {@link compile} for the meaning of the argument `options`.  If there
+   * are parse or other compilation errors, throws an exception {@link CompilationError}
+   * containing a list of individual errors.
+   */
+  export function compileSources(sourcesDict: Record<string, string|object> | string, options?: CompileOptions): CSN;
 
   /**
    * In version 2 of cds-compiler, this is an identity function and
@@ -280,11 +411,17 @@ declare namespace compiler {
    * @deprecated
    * @returns The input parameter "csn".
    */
-  export function compactModel(csn: CSN): any;
+  export function compactModel(csn: CSN): CSN;
 
+  /**
+   * Exception thrown by the compiler if errors are encountered.
+   *
+   * Note that compiler functions (e.g. renderers) may not always throw if errors are encountered.
+   * You always need to check the option's `messages` array for a {@link CompileMessage} of severity 'Error'.
+   */
   export class CompilationError extends Error {
-      constructor(messages: any, model: any, text: any, ...args);
-      messages: any[];
+      constructor(messages: CompileMessage[], model?: any, text?: string, ...args: any[]);
+      messages: CompileMessage[];
       toString(): string;
       /**
        * If `options.attachValidNames` is set, this non-enumerable property holds the CSN model.
@@ -298,6 +435,15 @@ declare namespace compiler {
       hasBeenReported: boolean;
   }
 
+  /**
+   * Exception thrown by the compiler if {@link compile} and its variants are invoked incorrectly.
+   * For example, this error is thrown if the same file is passed to {@link compile} twice.
+   */
+  export class InvocationError extends Error {
+    constructor(errs: any, ...args: any[]);
+    errors: any[]
+  }
+
   /**
    * Sort the given messages according to their location.  Messages are sorted
    * in ascending order according to their:
@@ -396,7 +542,7 @@ declare namespace compiler {
    * @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
+   *                                 as whether the shell is a TTY and whether the environment variable `NO_COLOR` is
    *                                 unset.
    */
   export function messageStringMultiline(msg: CompileMessage, config?: {
@@ -428,7 +574,7 @@ declare namespace compiler {
    * @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
+   *                     as whether the shell is a TTY and whether the environment variable `NO_COLOR` is
    *                     unset.
 
    */
@@ -442,28 +588,39 @@ declare namespace compiler {
    * If the message explanation does not exist, an exception is thrown.
    *
    * @throws May throw an ENOENT error if the message explanation cannot be found.
-   * @see {@link hasMessageExplanation}
+   * @see hasMessageExplanation
    */
   export function explainMessage(messageId: string): string;
   /**
    * Returns `true` if the given messageId has an explanatory text.
-   * Contrary to {@link explainMessage}, this function does not make
-   * a file lookup.
+   * Contrary to {@link explainMessage}, this function does not do
+   * any file lookup.
    */
   export function hasMessageExplanation(messageId: string): boolean;
 
-  export class InvocationError extends Error {
-      constructor(errs: any, ...args);
-      errors: any[]
-  }
-
   /**
-   * Returns true if at least one of the given messages is of severity "Error"
+   * Returns true if at least one of the given messages is of severity "Error".
    */
   export function hasErrors(messages: CompileMessage[]): boolean;
 
-  export function preparedCsnToEdm(csn: CSN, service: string, options: any): any;
-  export function preparedCsnToEdmx(csn: CSN, service: string, options: any): any;
+  /**
+   * Same as {@link to.edm} but expects a {@link for.odata} transformed CSN.
+   *
+   * Note that parameter `service` is the same as `ODataOptions.service`.
+   * The latter is not used.  OData specific options have an internal format.
+   *
+   * @deprecated Use {@link to.edm} instead. If it detects a pre-transformed CSN, it won't run for.odata().
+   */
+  export function preparedCsnToEdm(csn: CSN, service: string, options: ODataOptions): object;
+  /**
+   * Same as {@link to.edm} but expects a {@link for.odata} transformed CSN.
+   *
+   * Note that parameter `service` is the same as `ODataOptions.service`.
+   * The latter is not used.  OData specific options have an outdated format.
+   *
+   * @deprecated Use {@link to.edmx} instead. If it detects a pre-transformed CSN, it won't run for.odata().
+   */
+  export function preparedCsnToEdmx(csn: CSN, service: string, options: ODataOptions): string;
 
   export namespace parse {
       /**
@@ -473,38 +630,42 @@ declare namespace compiler {
        * @param filename Filename to be used in compiler messages.
        * @param options  Compiler options. Note that if `options.messages` is not set, messages will be printed to stderr.
        */
-      function cdl(cdl: string, filename: string, options?: Options): any;
+      function cdl(cdl: string, filename: string, options?: Options): CSN;
 
       /**
-       * Parse the given CQL and return its corresponding CSN representation.
+       * Parse the given CQL and return its corresponding CQN representation.
        *
        * @param cdl      CDL source as string.
        * @param filename Filename to be used in compiler messages, default is '<query>.cds'
        * @param options  Compiler options. Note that if `options.messages` is not set, messages will be printed to stderr.
+       * @returns Returns the CSN representation of the expression, i.e. CDS Query Notation.
        */
-      function cql(cdl: string, filename?: string, options?: Options): any;
+      function cql(cdl: string, filename?: string, options?: Options): CQN;
 
       /**
-       * Parse the given CDL expression and return its corresponding CSN representation.
+       * Parse the given CDL expression and return its corresponding CXN representation.
        *
        * @param cdl      CDL source as string.
        * @param filename Filename to be used in compiler messages, default is '<expr>.cds'
        * @param options  Compiler options. Note that if `options.messages` is not set, messages will be printed to stderr.
+       * @returns Returns the CSN representation of the expression, i.e. CDS Expression Notation.
        */
-      function expr(cdl: string, filename?: string, options?: Options): any;
+      function expr(cdl: string, filename?: string, options?: Options): CXN;
   }
 
   /**
    * @deprecated Use {@link parse.cql} instead.
    */
-  export function parseToCqn(cdl: string, filename?: string, options?: Options): any;
+  export function parseToCqn(cql: string, filename?: string, options?: Options): CQN;
   /**
    * @deprecated Use {@link parse.expr} instead.
    */
-  export function parseToExpr(cdl: string, filename?: string, options?: Options): any;
+  export function parseToExpr(expr: string, filename?: string, options?: Options): CXN;
 
   /**
-   * @note Actual name is "for" which can't be used directly in the documentation as it is a reserved name.
+   * @note Actual name is "for" which can't be used directly in the documentation
+   *       as it is a reserved name in TypeScript.
+   *
    * @see for
    */
   export namespace _for {
@@ -513,51 +674,292 @@ declare namespace compiler {
      * Changes include flattening, type resolution and more, according to
      * the provided options.
      */
-    function odata(csn: CSN, options: ODataOptions): any;
+    function odata(csn: CSN, options?: ODataOptions): CSN;
   }
 
   export { _for as for };
 
   export namespace to {
-      function cdl(csn: CSN, options: Options): object;
-      function sql(csn: CSN, options: SqlOptions): any;
+    /**
+     * Renders the given CSN into a CDL source representation.
+     *
+     * @returns Object containing the rendered model.
+     */
+    function cdl(csn: CSN, options?: CdlOptions): CdlResult;
+    namespace cdl {
+      /**
+       * Immutable list of reserved keywords in CDL.
+       * These keywords are used for automatic quoting in {@link to.cdl}.
+       */
+      const keywords: string[];
+      /**
+       * Immutable list of CDL functions, used for automatic quoting in {@link to.cdl}.
+       * Only relevant for element references of path length 1.
+       */
+      const functions: string[];
+    }
 
-      function edm(csn: CSN, options: ODataOptions): any;
-      namespace edm {
-          function all(csn: CSN, options: ODataOptions): any;
+    /**
+     * Renders the given CSN into SQL statements such as `CREATE TABLE`, `CREATE VIEW`, etc.
+     *
+     * @returns Array of SQL statements as strings, tables first, views second and optionally table constraints last.
+     */
+    function sql(csn: CSN, options?: SqlOptions): string[];
+    namespace sql {
+      namespace sqlite {
+        /**
+         * Immutable list of reserved keywords for SQLite. The list is used by {@link to.sql}.
+         * Taken from <http://www.sqlite.org/draft/lang_keywords.html>.
+         */
+        const keywords: string[];
       }
+      function smartId(name: string, dialect: string) : string;
+      function smartFunctionId(name: string, dialect: string) : string;
+      function delimitedId(name: string, dialect: string) : string;
+    }
 
-      function edmx(csn: CSN, options: ODataOptions): any;
-      namespace edmx {
-          function all(csn: CSN, options: ODataOptions): any;
-      }
+    /**
+     * Renders the given CSN into EDM (JSON format).  Requires `options.service` to be set.
+     *
+     * @returns Rendered EDM as JSON structure.
+     */
+    function edm(csn: CSN, options?: ODataOptions): object;
+    namespace edm {
+      /**
+       * Renders the given CSN into EDM (JSON format) for each service.
+       * If `options.serviceNames` is not set, all services will be rendered.
+       *
+       * @returns A map of `{ '<serviceName>': object }` entries.
+       */
+      function all(csn: CSN, options: ODataOptions): Record<string, object>;
+    }
 
-      function hdbcds(csn: CSN, options: Options): any;
-      function hdi(csn: CSN, options: Options): any;
-      namespace hdi {
-          function migration(csn: CSN, options: Options, beforeImage: any): any;
-      }
+    /**
+     * Renders the given CSN into EDMX.  Requires `options.service` to be set.
+     *
+     * @returns Rendered EDMX as string.
+     */
+    function edmx(csn: CSN, options: ODataOptions): string;
+    namespace edmx {
+      /**
+       * Renders the given CSN into EDMX for each service.
+       * If `options.serviceNames` is not set, all services will be rendered.
+       *
+       * @returns A map of `{ '<serviceName>': '<xml>' }` entries.
+       */
+      function all(csn: CSN, options?: ODataOptions): Record<string, string>;
+    }
+
+    /**
+     * Renders the given CSN into HDBCDS artifacts.
+     *
+     * @returns A map of `{ '<artifactName>.hdbcds|hdbconstraint>': '<content>' }` entries.
+     */
+    function hdbcds(csn: CSN, options?: HdbcdsOptions): Record<string, string>;
+    namespace hdbcds {
+      /**
+       * Immutable list of SAP HANA CDS keywords, used for smart quoting in
+       * {@link to.hdbcds} with option `sqlMapping: 'plain'`.
+       */
+      const keywords: string[];
+    }
+
+    /**
+     * Renders the given CSN into HDI statements such as `COLUMN TABLE`, `VIEW`, etc.
+     *
+     * @returns A map of `{ '<artifactName>.hdbtable|hdbview|hdbconstraint>': '<content>' }` entries.
+     */
+    function hdi(csn: CSN, options?: HdiOptions): Record<string, string>;
+    namespace hdi {
+      /**
+       * Immutable list of SAP HANA keywords, used for smart quoting in
+       * {@link to.hdi} with option `sqlMapping: 'plain'`.
+       * Taken from <https://help.sap.com/viewer/7c78579ce9b14a669c1f3295b0d8ca16/Cloud/en-US/28bcd6af3eb6437892719f7c27a8a285.html>.
+       */
+      const keywords: string[];
+
+      /**
+       * Return all changes in artifacts between two given models.
+       * Note: Only supports changes in entities (not views etc.) compiled/rendered as HANA-CSN/SQL.
+       *
+       * @param csn          A clean input CSN representing the desired "after-image"
+       * @param options      Options
+       * @param beforeImage  A HANA-transformed CSN representing the "before-image", or null in case no such image
+       *                                  is known, i.e. for the very first migration step
+       * @returns See {@link HdiMigrationResult} for details.
+       */
+      function migration(csn: CSN, options: HdiOptions, beforeImage: CSN): HdiMigrationResult;
+    }
   }
 
-  export function getArtifactCdsPersistenceName(artifactName: string, namingConvention: any, csn: CSN): any;
-  export function getElementCdsPersistenceName(elemName: string, namingConvention: any): any;
+  /**
+   * Result of the `to.cdl()` renderer.
+   */
+  export type CdlResult = {
+    /**
+     * Rendered model, excluding not-applied extensions.
+     */
+    model?: string
+    /**
+     * Rendered extend/annotate statements of `csn.extensions`
+     */
+    unappliedExtensions?: string
+    /**
+     * Rendered csn.namespace property + using directives.
+     */
+    [namespace: string]: string
+  }
+
+  /**
+   * Result type of {@link to.hdi.migration}.
+   */
+  export type HdiMigrationResult = {
+    /**
+     * The desired after-image in HANA-CSN format
+     */
+    afterImage: CSN
+    /**
+     * An array of objects with all artifacts in the after-image.  Each object specifies
+     * the artifact filename, the suffix, and the corresponding SQL statement to create
+     * the artifact.
+     */
+    definitions: object[],
+    /**
+     * An array of objects with the deleted artifacts.  Each object specifies the artifact
+     * filename and the suffix.
+     */
+    deletions: object[],
+    /**
+     * An array of objects with the changed (migrated) artifacts.  Each object specifies the
+     * artifact filename, the suffix, and the changeset (an array of changes, each specifying
+     * whether it incurs potential data loss, and its respective SQL statement(s), with
+     * multiple statements concatenated as a multi-line string in case the change e.g.
+     * consists of a column drop and add).
+     */
+    migrations: Array<{
+      name: string
+      suffix: string
+      changeset: object[]
+    }>,
+  }
+
+  /**
+   * Return the resulting database name for (absolute) 'artifactName', depending on the current naming
+   * mode.
+   *
+   * - For the 'hdbcds' naming mode, this means converting `.` to `::` on
+   *   the border between namespace and top-level artifact and correctly replacing some `.` with `_`.
+   * - For the 'plain' naming mode, it means converting all `.` to `_` and upper-casing.
+   * - For the 'quoted' naming mode, this means correctly replacing some `.` with `_`.
+   *
+   * @param artifactName The fully qualified name of the artifact
+   * @param sqlMapping The naming mode to use. See {@link SqlOptions.sqlMapping} for more details.
+   * @param csn
+   * @returns {string} The resulting database name for (absolute) 'artifactName', depending on the current naming mode.
+   * @since v2.1.0
+   */
+  export function getArtifactCdsPersistenceName(artifactName: string, sqlMapping: string, csn: CSN): string;
+  /**
+   * This is an old function signature.  If it is used - with a namespace as the third argument - the result might be wrong,
+   * since the `.` -> `_` conversion for 'quoted'/'hdbcds' is missing.
+   *
+   * @deprecated Use the other overload with CSN instead.
+   */
+  export function getArtifactCdsPersistenceName(artifactName: string, sqlMapping: string, namespace: string): string;
+  /**
+   *  Return the resulting database element name for `elemName`, depending on the current
+   *  naming mode.
+   *  - For the 'hdbcds' naming mode, this is just 'elemName'.
+   *  - For the 'plain' naming mode, it means converting all `.` to `_` and upper-casing.
+   *  - For the 'quoted' naming mode, it means converting all `.` to `_`.
+   *  No other naming modes are accepted!
+   *
+   * @param elemName The name of the element. For structured elements, concat by dot, e.g. `sub.elem`.
+   * @param sqlMapping The naming mode to use. See {@link SqlOptions.sqlMapping} for more details.
+   * @returns The resulting database element name for 'elemName', depending on the current naming mode.
+   */
+  export function getElementCdsPersistenceName(elemName: string, sqlMapping: string): string;
+
+  /**
+   * Traverse the CSN node `csn`.
+   *
+   * If `csn` is an array, call it recursively on each array item.
+   * If `csn` is an(other) object, call a function on each property:
+   * - The property name is a used as key in argument `userFunctions` and the
+   *   constant `defaultFunctions` above to get the function which is called on
+   *   the property value, see `defaultFunctions` for details.
+   * - If no function is found with the property name, try to find one with the
+   *   first char, which is useful for annotations.
+   * - If still not found, call `traverseCsn` recursively.
+   *
+   * The functions in `userFunctions` are usually transformer functions, which
+   * change the input CSN destructively.
+   */
+  export function traverseCsn(userFunctions: Record<string, Function>, csn: object|any[]);
 
   /**
    * @private
    */
   export namespace $lsp {
-      function compile(filenames: string[], dir?: string, options?: Options, fileCache?: Record<string, any>): Promise<any>;
-      function parse(source: string, filename?: string, options?: Options): any;
+    /**
+     * Compiler internal notation.
+     * @private
+     */
+    type XSN = any;
+    /**
+     * Compile the given files with the given options.  The return object uses an internal object
+     * format that must not be used outside of the cds-lsp.
+     * Respects the value of `options.fallbackParser`.
+     *
+     * @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
+     * @private
+     */
+    function compile(filenames: string[], dir?: string, options?: CompileOptions, fileCache?: FileCache): Promise<XSN>;
+    /**
+     * Parse the given source with the correct parser based on the file name's
+     * extension. For example uses CDL parser for `.cds` files.
+     * Respects the value of `options.fallbackParser`.
+     *
+     * @param {string} source Source code of the file.
+     * @param {string} filename Filename including its extension, e.g. "file.cds"
+     * @param {object} options Compile options
+     * @param {object} messageFunctions If not provided, parse errors will not lead to an exception
+     * @private
+     */
+    function parse(source: string, filename: string, options?: CompileOptions, messageFunctions?: object): XSN;
+    /**
+     * Get the name of the given artifact.  This function is internal and does not work with CSN.
+     * It should be used to retrieve an artifact's name instead of relying on `artifact.name`
+     * as that object may be modified in the future.
+     *
+     * @private
+     */
+    function getArtifactName(artifact: object): object;
   }
 
   /**
-   * CSN object. Not yet specified in this TypeScript declaration file.
+   * CDS Schema Notation. Not yet specified in this TypeScript declaration file.
+   * See <https://pages.github.tools.sap/cap/docs/cds/csn> for more.
    */
   export type CSN = any;
 
+  /**
+   * CDS Query Notation. Not yet specified in this TypeScript declaration file.
+   * See <https://pages.github.tools.sap/cap/docs/cds/cqn> for more.
+   */
+  export type CQN = any;
+
+  /**
+   * CDS Expression Notation. Not yet specified in this TypeScript declaration file.
+   * See <https://pages.github.tools.sap/cap/docs/cds/cxn> for more.
+   */
+  export type CXN = any;
+
   export class CompileMessage {
     constructor(location: Location, msg: string, severity?: MessageSeverity, id?: string | null, home?: string | null, moduleName?: string | null);
-
     /**
      * Optional ID of the message.  Can be used to reclassify messages.
      *
@@ -571,7 +973,6 @@ declare namespace compiler {
      * @deprecated Use `$location` instead.
      */
     location: Location
-
     /**
      * Location information like file and line/column of the message.
      */
@@ -587,7 +988,6 @@ declare namespace compiler {
      * String representation of the message.  May be a multi-line message in the future.
      */
     message: string
-
     /**
      * A string describing the path to the artifact, e.g. `entity:"E"/element:"x"`.
      */
@@ -603,7 +1003,6 @@ declare namespace compiler {
      * If `internalMsg` is set, then this property will have an error object with a stack trace.
      */
     error?: Error
-
     /**
      * Returns a human readable string of the compiler message. Uses {@link messageString} to render
      * the message without filename normalization and without a message ID.
@@ -614,7 +1013,7 @@ declare namespace compiler {
   /**
    * Severities a compiler message can have.
    */
-  export type MessageSeverity = 'Error' | 'Warning' | 'Info' | 'Debug';
+  export type MessageSeverity = string | 'Error' | 'Warning' | 'Info' | 'Debug';
 
   /**
    * CSN Location, often exposed by `$location` in CSN.
@@ -631,4 +1030,14 @@ declare namespace compiler {
     endCol?:  number
   }
 
+  /**
+   * File cache for compile() functions.
+   * This cache is a dictionary of absolute file names to the file content with values:
+   *  - `false`: the file does not exist
+   *  - `true`: file exists (fstat), no further knowledge yet - i.e. value will change!
+   *  - `string` or `Buffer`: the file content
+   *  - `{ realname: fs.realpath(filename) }`: if filename is not canonicalized
+   */
+  export type FileCache = Record<string, boolean | string | Buffer | { realname: string }>;
+
 }