@cap-js/cds-typer 0.2.5-beta.1

package/lib/file.js

@@ -0,0 +1,497 @@
+'use strict'
+
+const fs = require('fs').promises
+const { readFileSync } = require('fs')
+const path = require('path')
+
+const AUTO_GEN_NOTE = "// This is an automatically generated file. Please do not change its contents manually!"
+
+/** @typedef {Object<string, Buffer>} Namespace */ 
+
+class File {
+    /**
+     * Creates one string from the buffers representing the type definitions.
+     * @returns {string} complete file contents.
+     */
+    toTypeDefs() { return '' }
+
+    /**
+     * Concats the classnames to an export dictionary 
+     * to create the accompanying JS file for the typings.
+     * @returns {string} a string containing the module.exports for the JS file.
+     */
+    toJSExports() { return '' }
+}
+
+/**
+ * Library files that contain predefined types.
+ * For example, the cap.hana types are included in a separate predefined library file
+ * which is only included if the model that is being compiled references any of these types.
+ * A library is uniquely identified by the namespace it represents. That namespace is directly
+ * derived from the file's name. i.e. path/to/file/cap.hana.ts will be considered to hold 
+ * definitions describing the namespace "cap.hana".
+ * These files are supposed to contain fully usable types, not CSN or a CDS file, as they are just
+ * being copied verbatim when they are being used.
+ */
+class Library extends File {
+    toTypeDefs() {
+        return this.contents
+    }
+
+    constructor(file) {
+        super()
+        this.contents = readFileSync(file, 'utf-8')
+        /**
+         * The path to the file where the lib definitions are stored (some/path/name.space.ts)
+         * @type {string}
+         * @private
+         */
+        this.file = file
+
+        /**
+         * List of entity names (plain, without namespace)
+         * @type {string[]}
+         */
+        this.entities = Array.from(this.contents.matchAll(/export class (\w+)/g), ([,m]) => m)
+        
+        /**
+         * Namespace (a.b.c.d)
+         * @type {string}
+         */
+        this.namespace = path.basename(file, '.ts')
+        
+        /**
+         * Whether this library was referenced at least once
+         * @type {boolean}
+         */
+        this.referenced = false
+        
+        /**
+         * The Path for this library file, which is constructed from its namespace.
+         * @type {Path}
+         */
+        this.path = new Path(this.namespace.split('.'))
+    }
+
+    /**
+     * Whether this library offers an entity of a given type (fully qualified).
+     * @param {string} entity the entity's name, e.g. cap.hana.TINYINT
+     * @returns {boolean} true, iff the namespace inferred from the passed string matches that of this library 
+     *          and this library contains a class of that name. i.e.:
+     *          ```js
+     *          new Library('cap.hana.ts').offers('cap.hana.TINYINT') // -> true`
+     *          ```
+     */
+    offers(entity) {
+        return this.entities.some(e => `${this.namespace}.${e}` === entity)
+    }
+}
+
+/**
+ * Source file containing several buffers.
+ */
+class SourceFile extends File {
+    constructor(path) {
+        super()
+        /** @type {Path} */
+        this.path = new Path(path.split('.'))
+        /** @type {Object} */
+        this.imports = {}
+        /** @type {Buffer} */
+        this.preamble = new Buffer()
+        /** @type {Buffer} */
+        this.types = new Buffer()
+        /** @type {Buffer} */
+        this.enums = new Buffer()
+        /** @type {Buffer} */
+        this.classes = new Buffer()
+        /** @type {{ buffer: Buffer, names: string[]} */
+        this.actions = { buffer: new Buffer(), names: [] }
+        /** @type {Buffer} */
+        this.aspects = new Buffer()
+        /** @type {Namespace} */
+        this.namespaces = {}
+        /** @type {Object<string, any>} */
+        this.classNames = {} // for .js file
+        /** @type {Object<string, any>} */
+        this.typeNames = {}
+        /** @type {[string, string, string][]} */
+        this.inflections = []
+    }
+
+    static stringifyLambda(name, parameters = [], returns = 'any') {
+        return `${name}: (${parameters.map(([n, t]) => `${n}: ${t}`).join(', ')}) => ${returns}`
+    }
+
+    /**
+     * Adds a pair of singular and plural inflection.
+     * These are later used to generate the singular -> plural
+     * aliases in the index.js file.
+     * @param {string} singular singular type without namespace.
+     * @param {string} plural plural type without namespace
+     * @param {string} original original entity name without namespace. 
+     *        In many cases this will be the same as plural.
+     */
+    addInflection(singular, plural, original) {
+        this.inflections.push([singular, plural, original])
+    }
+
+    /**
+     * Adds an action definition in form of a arrow function to the file.
+     * @param {string} name name of the action
+     * @param {{relative: string | undefined, local: boolean, posix: boolean}} params list of parameters, passed as [name, type] pairs
+     * @param returns the return type of the action
+     */
+    addAction(name, params, returns) {
+        //const ps = params.map(([n, t]) => `${n}: ${t}`).join(', ')
+        this.actions.buffer.add("// action")
+        //this.actions.buffer.add(`export declare const ${name}: ( args: { ${ps} }) => ${returns};`)
+        this.actions.buffer.add(`export declare const ${SourceFile.stringifyLambda(name, params, returns)};`)
+        this.actions.names.push(name)
+    }
+
+    /**
+     * Retrieves or creates and retrieves a sub namespace
+     * with a given name.
+     * @param {string} name of the sub namespace.
+     * @returns {Namespace} the sub namespace.
+     */
+    getSubNamespace(name) {
+        if (!(name in this.namespaces)) {
+            const buffer = new Buffer()
+            buffer.closed = false
+            buffer.add(`export namespace ${name} {`)
+            buffer.indent()
+            this.namespaces[name] = buffer
+        }
+        const buffer = this.namespaces[name]
+        if (buffer.closed) {
+            throw new Error(`Tried to add content to namespace buffer '${name}' that was already closed.`)
+        }
+        return this.namespaces[name]
+    }
+
+    /**
+     * Adds an enum to this file.
+     * @param {string} fq fully qualified name of the enum
+     * @param {string} name local name of the enum
+     * @param {[string, string][]} kvs list of key-value pairs
+     */
+    addEnum(fq, name, kvs) {
+        this.enums.add(`export enum ${name} {`)
+        this.enums.indent()
+        for (const [k, v] of kvs) {
+            this.enums.add(`${k} = ${v},`)
+        }
+        this.enums.outdent()
+        this.enums.add('}')
+    }
+
+    /**
+     * Adds a class to this file. 
+     * This differs from writing to the classes buffer,
+     * as it is just a cache to collect all classes that 
+     * are supposed to be present in this file. 
+     * @param {string} clean cleaned name of the class 
+     * @param {string} fq fully qualified name, including the namespace
+     */
+    addClass(clean, fq) {
+        this.classNames[clean] = fq
+    }
+
+    /**
+     * Adds an import if it does not exist yet.
+     * @param {Path} imp qualifier for the namespace to import.
+     */
+    addImport(imp) {
+        const dir = imp.asDirectory({relative: this.path.asDirectory()})
+        if (!(dir in this.imports)) {
+            this.imports[dir] = imp
+        }
+    }
+
+    /**
+     * Adds an arbitrary piece of code that is added
+     * right after the imports.
+     * @param {string} code the preamble code.
+     */
+    addPreamble(code) {
+        this.preamble.add(code)
+    }
+
+    /**
+     * Adds a type alias to this file.
+     * @param {string} fq fully qualified name of the enum
+     * @param {string} name local name of the enum
+     * @param {string} rhs the right hand side of the assignment
+     */
+    addType(fq, clean, rhs) {
+        this.typeNames[clean] = fq
+        this.types.add(`export type ${clean} = ${rhs};`)
+    }
+
+    /**
+     * Writes all imports to a buffer, relative to the current file.
+     * Creates a new buffer on each call, as concatenating import strings directly
+     * upon discovering them would complicate filtering out duplicate entries.
+     * @returns {Buffer} all imports written to a buffer.
+     */
+    getImports() {
+        const buffer = new Buffer()
+        for (const imp of Object.values(this.imports)) {
+            if (!imp.isCwd(this.path.asDirectory())) {
+                buffer.add(`import * as ${imp.asIdentifier()} from '${imp.asDirectory({relative: this.path.asDirectory()})}';`)
+            }
+        }
+        return buffer
+    }
+
+    toTypeDefs() {
+        const namespaces = new Buffer()
+        for (const ns of Object.values(this.namespaces)) {
+            ns.outdent()
+            ns.add('}')
+            ns.closed = true
+            namespaces.add(ns.join())
+        }
+        return [
+            AUTO_GEN_NOTE,
+            this.getImports().join(),
+            this.preamble.join(),
+            this.types.join(),
+            this.enums.join(),
+            namespaces.join(),
+            this.aspects.join(), // needs to be before classes
+            this.classes.join(),
+            this.actions.buffer.join(),
+        ].filter(Boolean).join('\n')
+    }
+
+    toJSExports() {
+        return [AUTO_GEN_NOTE, "const cds = require('@sap/cds')", `const csn = cds.entities('${this.path.asNamespace()}')`] // boilerplate
+            .concat(
+                this.inflections
+                    // sorting the entries based on the number of dots in their singular.
+                    // that makes sure we have defined all parent namespaces before adding subclasses to them e.g.:
+                    // "module.exports.Books" is defined before "module.exports.Books.text"
+                    .sort(([a], [b]) => a.split('.').length - b.split('.').length)
+                    // by using a temporary Set we make sure to catch cases where
+                    // (1) plural is the same as original (default case) and
+                    // (2) plural differs from original, i.e. when a @plural annotation is present
+                    //     or when plural4 produced weird inflection.
+                    .flatMap(([singular, plural, original]) => Array.from(new Set([
+                        `module.exports.${singular} = csn.${original}`,
+                        `module.exports.${plural} = csn.${original}`,
+                        `module.exports.${original} = csn.${original}`
+                    ])))
+            ) // singular -> plural aliases
+            .concat(['// actions'])
+            .concat(this.actions.names.map(name => `module.exports.${name} = '${name}'`))
+            .join('\n') + '\n'
+    }
+}
+
+/**
+ * String buffer to conveniently append strings to.
+ */
+class Buffer {
+
+    /**
+     * @param {string} indentation
+     */
+    constructor(indentation = '  ') {
+        /**
+         * @type {string[]}
+         */
+        this.parts = []
+        /**
+         * @type {string}
+         */
+        this.indentation = indentation
+        /**
+         * @type {string}
+         */
+        this.currentIndent = ''
+    }
+
+    /**
+     * Indents by the predefined spacing.
+     */
+    indent() {
+        this.currentIndent += this.indentation
+    }
+
+    /**
+     * Removes one level of indentation.
+     */
+    outdent() {
+        if (this.currentIndent.length === 0) {
+            throw new Error('Can not outdent buffer further. Probably mismatched indent.')
+        }
+        this.currentIndent = this.currentIndent.slice(0, -this.indentation.length)
+    }
+
+    /**
+     * Concats all elements in the buffer into a single string.
+     * @param {string} glue string to intersperse all buffer contents with
+     * @returns {string} string spilled buffer contents.
+     */
+    join(glue = '\n') {
+        return this.parts.join(glue)
+    }
+
+    /**
+     * Clears the buffer.
+     */
+    clear() {
+        this.parts = []
+    }
+
+    /**
+     * Adds an element to the buffer with the current indentation level.
+     * @param {string} part 
+     */
+    add(part) {
+        this.parts.push(this.currentIndent + part)
+    }
+}
+
+/**
+ * Convenience class to handle path qualifiers.
+ */
+class Path {
+
+    /**
+     * @param {string[]} parts parts of the path. 'a.b.c' -> ['a', 'b', 'c']
+     * @param kind FIXME: currently unused
+     */
+    constructor(parts, kind) {
+        this.parts = parts
+        this.kind = kind
+    }
+
+    /**
+     * @returns {Path} the path to the parent directory. 'a.b.c'.getParent() -> 'a.b'
+     */
+    getParent() {
+        return new Path(this.parts.slice(0, -1))
+    }
+
+    /**
+     * Transfoms the Path into a directory path.
+     * @param {string?} params.relative if defined, the path is constructed relative to this directory
+     * @param {boolean} params.local if set to true, './' is prefixed to the directory
+     * @param {boolean} params.posix if set to true, all slashes will be forward slashes on every OS. Useful for require/ import
+     * @returns {string} directory 'a.b.c'.asDirectory() -> 'a/b/c' (or a\b\c when on Windows without passing posix = true)
+     */
+    asDirectory(params = {}) {
+        const { relative, local, posix } = {relative: undefined, local: true, posix: true, ...params}
+        const sep = posix ? path.posix.sep : path.sep
+        const prefix = local ? `.${sep}` : ''
+        const absolute = path.join(...this.parts)
+        let p = relative ? path.relative(relative, absolute) : absolute
+        if (posix) {
+            // NOTE: this could fail for absolute paths (D:\\...) or network drives on windows
+            p = p.split(path.sep).join(path.posix.sep)
+        }
+        // path.join removes leading ./, so we have to concat manually here
+        return prefix + p
+    }
+
+    /**
+     * Transforms the Path into a namespace qualifier.
+     * @returns {string} namespace qualifier 'a.b.c'.asNamespace() -> 'a.b.c'
+     */
+    asNamespace() {
+        return this.parts.join('.')
+    }
+
+    /**
+     * Transforms the Path into an identifier that can be used as variable name.
+     * @returns {string} identifier 'a.b.c'.asIdentifier() -> '_a_b_c', ''.asIdentifier() -> '_'
+     */
+    asIdentifier() {
+        return `_${this.parts.join('_')}`
+    }
+
+    /**
+     * @returns {boolean} true, iff the Path refers to the current working directory, aka './'
+     */
+    isCwd(relative = undefined) {
+        return (!relative && this.parts.length === 0) || (!!relative && this.asDirectory({relative}) === './')
+    }
+}
+
+/**
+ * Base definitions used throughout the typing process,
+ * such as Associations and Compositions.
+ * @type {SourceFile}
+ */
+const baseDefinitions = new SourceFile('_')
+baseDefinitions.addPreamble(`
+export namespace Association {
+    export type to <T> = T;
+    export namespace to {
+        export type many <T extends readonly any[]> = T;
+    }
+}
+
+export namespace Composition {
+    export type of <T> = T;
+    export namespace of {
+        export type many <T extends readonly any[]> = T;
+    }
+}
+
+export class Entity {
+    static data<T extends Entity> (this:T, input:Object) : T {
+        return {} as T // mock
+    }
+}
+
+export type EntitySet<T> = T[] & {
+    data (input:object[]) : T[]
+    data (input:object) : T
+};
+
+export type DeepRequired<T> = { 
+    [K in keyof T]: DeepRequired<T[K]>
+} & Required<T>;
+`)
+
+/**
+ * Writes the files to disk. For each source, a index.d.ts holding the type definitions
+ * and a index.js holding implementation stubs is generated at the appropriate directory.
+ * Missing directories are created automatically and asynchronously.
+ * @param {string} root root directory to prefix all directories with
+ * @param {File[]} sources source files to write to disk
+ * @returns {Promise<string[]>} Promise that resolves to a list of all directory paths pointing to generated files.
+ */
+const writeout = async (root, sources) =>
+    Promise.all(
+        sources.map(async (source) => {
+            const dir = path.join(root, source.path.asDirectory({local: false, posix: false}))
+            try {
+                await fs.mkdir(dir, { recursive: true })
+                await Promise.all([
+                        fs.writeFile(path.join(dir, 'index.ts'), source.toTypeDefs()),
+                        fs.writeFile(path.join(dir, 'index.js'), source.toJSExports()),
+                    ])
+
+            } catch (err) {
+                // eslint-disable-next-line no-console
+                console.error(`Could not create parent directory ${dir}: ${err}.`)
+            }
+            return dir
+        })
+    )
+
+module.exports = {
+    Library,
+    Buffer,
+    File,
+    SourceFile,
+    Path,
+    writeout,
+    baseDefinitions,
+}

package/lib/logging.d.ts

@@ -0,0 +1,50 @@
+export enum Levels {
+    TRACE = 1,
+    DEBUG = 2,
+    INFO = 3,
+    WARNING = 4,
+    ERROR = 8,
+    CRITICAL = 16,
+    NONE = 32
+}
+
+export class Logger {
+    private mask: number;
+
+    public constructor();
+
+    /**
+     * Add all log levels starting at level.
+     * @param level level to start from.
+     */
+    public addFrom(level: number): void;
+
+    /**
+     * Adds a log level to react to.
+     * @param level the level to react to. 
+     */
+    public add(level: number): void;
+
+    /**
+     *  Ignores a log level.
+     * @param level the level to ignore.
+     */
+    public ignore(level: number): void;
+
+    /**
+     * Attempts to log a message.
+     * Only iff levelName is a valid log level
+     * and the corresponding number if part of mask,
+     * the message gets logged.
+     * @param levelName name of the log level.
+     * @param message message to log.
+     */
+    private _log(levelName: Levels, message: string);
+
+    public trace(message: string);
+    public debug(message: string);
+    public info(message: string);
+    public warning(message: string);
+    public error(message: string);
+    public critical(message: string);
+}

package/lib/logging.js

@@ -0,0 +1,73 @@
+/** @enum {number} */
+const Levels = {
+    TRACE: 1,
+    DEBUG: 2,
+    INFO: 3,
+    WARNING: 4,
+    ERROR: 8,
+    CRITICAL: 16,
+    NONE: 32,
+}
+
+class Logger {
+    constructor() {
+        this.mask = 0
+        const lvls = Object.keys(Levels)
+        for (let i = 0; i < lvls.length - 1; i++) {
+            // -1 to ignore NONE
+            const level = lvls[i]
+            this[level.toLowerCase()] = function (message) {
+                this._log(level, message)
+            }.bind(this)
+        }
+    }
+
+    /**
+     * Add all log levels starting at level.
+     * @param {number} level level to start from.
+     */
+    addFrom(baseLevel) {
+        const vals = Object.values(Levels)
+        const highest = vals[vals.length - 1]
+        for (let l = Math.log2(baseLevel); Math.pow(2, l) <= highest; l++) {
+            this.add(Math.pow(2, l))
+        }
+    }
+
+    /**
+     * Adds a log level to react to.
+     * @param {number} level the level to react to. 
+     */
+    add(level) {
+        this.mask = this.mask | level
+    }
+
+    /**
+     *  Ignores a log level.
+     * @param {number} level the level to ignore.
+     */
+    ignore(level) {
+        this.mask = this.mask ^ level
+    }
+
+    /**
+     * Attempts to log a message.
+     * Only iff levelName is a valid log level
+     * and the corresponding number if part of mask,
+     * the message gets logged.
+     * @param {Levels} levelName name of the log level.
+     * @param {string} message message to log.
+     */
+    _log(levelName, message) {
+        const level = Levels[levelName]
+        if (level && (this.mask & level) === level) {
+            // eslint-disable-next-line no-console
+            console.log(`[${levelName}]`, message)
+        }
+    }
+}
+
+module.exports = {
+    Levels,
+    Logger,
+}

package/lib/util.d.ts

@@ -0,0 +1,87 @@
+interface Annotations {
+    name?: string,
+    '@singular'?: string,
+    '@plural'?: string
+}
+
+interface CommandlineFlag {
+    desc: string,
+    default?: any
+}
+
+interface ParsedFlags {
+    positional: string[],
+    named: {[key: string]: any}
+}
+
+/**
+ * Tries to retrieve an annotation that specifies the singular name
+ * from a CSN. Valid annotations are listed in util.annotations
+ * and their precedence is in order of definition.
+ * If no singular is specified at all, undefined is returned.
+ * @param csn the CSN of an entity to check
+ * @returns the singular annotation or undefined
+ */
+export function getSingularAnnotation(csn: {}): string | undefined;
+
+/**
+ * Tries to retrieve an annotation that specifies the plural name
+ * from a CSN. Valid annotations are listed in util.annotations
+ * and their precedence is in order of definition.
+ * If no plural is specified at all, undefined is returned.
+ * @param csn the CSN of an entity to check
+ * @returns the plural annotation or undefined
+ */
+ export function getPluralAnnotation(csn: {}): string | undefined;
+
+
+ /**
+  * Users can specify that they want to refer to localisation
+  * using the syntax {i18n>Foo}, where Foo is the name of the
+  * entity as found in the .cds file
+  * (see: https://pages.github.tools.sap/cap/docs/guides/i18n)
+  * As this throws off the naming, we remove this wrapper
+  * unlocalize("{i18n>Foo}") -> "Foo"
+  * @param name the entity name (singular or plural).
+  * @returns the name without localisation syntax or untouched.
+  */
+ export function unlocalize(name: string): string;
+
+/**
+ * Attempts to derive the singular form of an English noun.
+ * If '@singular' is passed as annotation, that is preferred.
+ * @param dn annotations
+ * @param stripped if true, leading namespace will be stripped
+ */
+export function singular4(dn: Annotations | string, stripped: boolean): string;
+
+/**
+ * Attempts to derive the plural form of an English noun.
+ * If '@plural' is passed as annotation, that is preferred. 
+ * @param dn annotations
+ * @param stripped if true, leading namespace will be stripped
+ */
+export function plural4(dn: Annotations | string, stripped: boolean): string;
+
+/**
+ * Parses command line arguments into named and positional parameters.
+ * Named parameters are expected to start with a double dash (--). 
+ * If the next argument `B` after a named parameter `A` is not a named parameter itself,
+ * `B` is used as value for `A`.
+ * If `A` and `B` are both named parameters, `A` is just treated as a flag (and may receive a default value).
+ * Only named parameters that occur in validFlags are allowed. Specifying named flags that are not listed there
+ * will cause an error.
+ * Named parameters that are either not specified or do not have a value assigned to them may draw a default value 
+ * from their definition in validFlags.
+ * @param argv list of command line arguments
+ * @param validFlags allowed flags. May specify default values.
+ */
+export function parseCommandlineArgs(argv: string[], validFlags: {[key: string]: CommandlineFlag}): ParsedFlags;
+
+/**
+ * Performs a deep merge of the passed objects into the first object. 
+ * See Object.assign(target, source).
+ * @param target object to assign into.
+ * @param source object to assign from.
+ */
+export function deepMerge(target: {}, source: {}): void;