@cap-js/cds-typer 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -4,7 +4,11 @@ All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 The format is based on [Keep a Changelog](http://keepachangelog.com/).
 
-## Version 0.3.1 - TBD
+## Version 0.4.1 - TBD
+
+## Version 0.4.0 - 2023-07-06
+### Added
+- Support for enums when they are defined separately (not inline in the property type of an entity)
 
 ## Version 0.3.0 - 2023-06-26
 ### Added

package/README.md

@@ -6,7 +6,7 @@ Generates `.ts` files for a CDS model to receive code completion in VS Code.
 
 
 ## Requirements and Setup
-This project is [available as `@cds-js/cds-typer`](https://www.npmjs.com/package/@cap-js/cds-typer) as NPM package.
+This project is [available as `@cap-js/cds-typer`](https://www.npmjs.com/package/@cap-js/cds-typer) as NPM package.
 
 ### Usage
 The type generator can either be used as a standalone tool, or as part of of the [CDS VSCode-Extension](https://www.npmjs.com/package/@sap/vscode-cds).
@@ -45,6 +45,8 @@ const { Books } = require('../@types/mybookshop')
 
 From that point on you should receive code completion from the type system for `Books`.
 
+_Note:_ the above command generates types for the model contained within the mentioned `schema.cds` file. If you have multiple `.cds` files that are included via `using` statements by `schema.cds`, then those files will also be included in the type generation process. If you have `.cds` files that are _not_ in some way included in `schema.cds`, you have to explicitly pass those as positional argument as well, if you want types for them.
+
 _cds-typer_ comes with rudimentary CLI support and a few command line options:
 
 - `--help`: prints all available parameters.

package/lib/file.js

@@ -101,11 +101,11 @@ class SourceFile extends File {
         this.preamble = new Buffer()
         /** @type {Buffer} */
         this.types = new Buffer()
-        /** @type {Buffer} */
-        this.enums = new Buffer()
+        /** @type {{ buffer: Buffer, fqs: {name: string, fq: string}[]}} */
+        this.enums = { buffer: new Buffer(), fqs: [] }
         /** @type {Buffer} */
         this.classes = new Buffer()
-        /** @type {{ buffer: Buffer, names: string[]} */
+        /** @type {{ buffer: Buffer, names: string[]}} */
         this.actions = { buffer: new Buffer(), names: [] }
         /** @type {Buffer} */
         this.aspects = new Buffer()
@@ -191,13 +191,26 @@ class SourceFile extends File {
      * @param {[string, string][]} kvs list of key-value pairs
      */
     addEnum(fq, name, kvs) {
-        this.enums.add(`export enum ${name} {`)
-        this.enums.indent()
+        // CDS differ from TS enums as they can use bools as value (TS: only number and string)
+        // So we have to emulate enums by adding an object (name -> value mappings)
+        // and a type containing all disctinct values.
+        // We can get away with this as TS doesn't feature nominal typing, so the structure
+        // is all we care about.
+        this.enums.fqs.push({ name, fq })
+        const bu = this.enums.buffer
+        bu.add('// enum')
+        bu.add(`export const ${name} = {`)
+        bu.indent()
+        const vals = new Set()
         for (const [k, v] of kvs) {
-            this.enums.add(`${k} = ${v},`)
+            bu.add(`${k}: ${v},`)
+            vals.add(v)
         }
-        this.enums.outdent()
-        this.enums.add('}')
+        bu.outdent()
+        bu.add('}')
+        bu.add(`export type ${name} = ${[...vals].join(' | ')}`)
+        bu.add('')
+        
     }
 
     /**
@@ -272,7 +285,7 @@ class SourceFile extends File {
             this.getImports().join(),
             this.preamble.join(),
             this.types.join(),
-            this.enums.join(),
+            this.enums.buffer.join(),
             namespaces.join(),
             this.aspects.join(), // needs to be before classes
             this.classes.join(),
@@ -300,6 +313,8 @@ class SourceFile extends File {
             ) // singular -> plural aliases
             .concat(['// actions'])
             .concat(this.actions.names.map(name => `module.exports.${name} = '${name}'`))
+            .concat(['// enums'])
+            .concat(this.enums.fqs.map(({fq, name}) => `module.exports.${name} = Object.fromEntries(Object.entries(cds.model.definitions['${fq}'].enum).map(([k,v]) => [k,v.val]))`))
             .join('\n') + '\n'
     }
 }

package/lib/util.js

@@ -208,22 +208,20 @@ function fixCSN(csn) {
                 entity.erased ??= {}
                 entity.erased[attr] = ea
                 delete entity[attr]
-                this.logger.info(`Removing inherited attribute ${attr} from ${entity.name}.`)
+                //this.logger.info(`Removing inherited attribute ${attr} from ${entity.name}.`)
             }
         }
     }
 
     for (const entity of Object.values(csn.definitions)) {
         let i = 0
-        if (entity.includes) {
-            while (
-                (getSingularAnnotation(entity) || getPluralAnnotation(entity)) &&
-                i < entity.includes.length
-            ) {
-                const parent = this.csn.definitions[entity.includes[i]]
-                Object.values(annotations).flat().forEach(an => erase(entity, parent, an))
-                i++
-            }
+        while (
+            (getSingularAnnotation(entity) || getPluralAnnotation(entity)) &&
+            i < (entity.includes ?? []).length
+        ) {
+            const parent = csn.definitions[entity.includes[i]]
+            Object.values(annotations).flat().forEach(an => erase(entity, parent, an))
+            i++
         }
     }
 }

package/lib/visitor.js

@@ -260,10 +260,12 @@ class Visitor {
         const ns = this.resolver.resolveNamespace(name.split('.'))
         const file = this.getNamespaceFile(ns)
         if ('enum' in type) {
+            // in case of strings, wrap in quotes and fallback to key to make sure values are attached for every key
+            const val = (k,v) => type.type === 'cds.String' ? `"${v ?? k}"` : v
             file.addEnum(
                 name,
                 clean,
-                Object.entries(type.enum).map(([k, v]) => [k, v.val])
+                Object.entries(type.enum).map(([k, v]) => [k, val(k, v.val)])
             )
         } else {
             // alias

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cap-js/cds-typer",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Generates .ts files for a CDS model to receive code completion in VS Code",
   "main": "index.js",
   "homepage": "https://cap.cloud.sap/",

package/lib/compile.d.ts

@@ -1,273 +0,0 @@
-import { Path, SourceFile} from './file'
-import { Logger } from './logging';
-
-// mock
-interface CSN {
-    definitions?: { [key: string]: EntityCSN }
-}
-
-interface EntityCSN {
-    cardinality?: {
-        max?: '*' | number
-    }
-}
-
-interface TypeResolveInfo {
-    isBuiltin: boolean,
-    isInlineDefinition: boolean,
-    isForeignKeyReference: boolean,
-    type: string, 
-    path?: Path,
-    csn?: CSN,
-    
-    /**
-     * When nested inline types require additional imports. E.g.:
-     * // mymodel.cds
-     * Foo {
-     *   bar: {
-     *     baz: a.b.c.Baz // need to require a.b.c in mymodel.cds!
-     *   }
-     * }
-     */
-    imports: Path[]
-}
-
-interface CompileParameters {
-    rootDirectory: String,
-    logLevel: number,
-    jsConfigPath?: string
-}
-
-interface VisitorOptions {
-    // if set to true, _all_ properties are generated as optional ?:.
-    // This is the standard CAP behaviour, where any property could not be available/ not yet be constructed
-    // at any point
-    propertiesOptional: boolean
-}
-
-type VisitorParameters = { logger?: Logger, options?: VisitorOptions }
-
-/**
- * Compiles a .cds file to Typescript types.
- * @param inputFile path to input .cds file
- * @param parameters path to root directory for all generated files, min log level
- */
-export function compileFromFile(inputFile: string, parameters: CompileParameters): Promise<string[]>;
-
-/**
- * Compiles a CSN object to Typescript types.
- * @param csn CSN
- * @param parameters path to root directory for all generated files, min log level
- */
-export function compileFromCSN(csn: CSN, parameters: CompileParameters): Promise<string[]>;
-
-/**
- * Writes the accompanying jsconfig.json file to the specified paths.
- * Tries to merge nicely if an existing file is found.
- * @param file filepath to jsconfig.json.
- * @param logger logger
- */
-export function writeJsConfig(file: string, logger: Logger);
-
-export class Visitor {
-    /**
-     * @param csn root CSN
-     */
-    constructor(csn: CSN, params: VisitorParameters);
-
-    /**
-     * Determines the file corresponding to the namespace.
-     * If no such file exists yet, it is created first.
-     * @param {string} path the name of the namespace (foo.bar.baz)
-     * @returns the file corresponding to that namespace name
-     */
-    private getNamespaceFile(path: Path): SourceFile;
-
-    /**
-     * Conveniently combines _resolveNamespace and _trimNamespace
-     * to end up with both the resolved Path of the namespace,
-     * and the clean name of the class.
-     * @param fq the fully qualified name of an entity.
-     * @returns a tuple, [0] holding the path to the namespace, [1] holding the clean name of the entity.
-     */ 
-    private untangle(fq: string): [Path, string];
-
-    /**
-     * Visits all definitions within the CSN definitions.
-     */
-    private visitDefinitions(): void;
-
-    /**
-     * Visits a single entity from the CSN's definition field.
-     * Will call _printEntity or _printAction based on the entity's kind.
-     * @param name name of the entity, fully qualified as is used in the definition field.
-     * @param entity CSN data belonging to the entity to perform lookups in.
-     */
-    private visitEntity(name: string, entity: CSN): void;
-    private _printEntity(name: string, entity: CSN): void;
-    private _printAction(name: string, action: CSN): void;
-    private _printType(name: string, type: CSN): void;
-    private _printAspect(name: string, aspect: CSN): void;
-
-    /**
-     * Visits a single element in an entity.
-     * @param name name of the element
-     * @param element CSN data belonging to the the element.
-     * @param file the namespace file the surrounding entity is being printed into.
-     * @param buffer buffer to add the definition to. If no buffer is passed, the passed file's class buffer is used instead.
-     */
-    public visitElement(name: string, element: CSN, file: SourceFile, buffer?: Buffer): void;
-
-    /**
-     * Attempts to retrieve the max cardinality of a CSN for an entity.
-     * @param element csn of entity to retrieve cardinality for
-     * @returns max cardinality of the element. 
-     * If no cardinality is attached to the element, cardinality is 1.
-     * If it is set to '*', result is Infinity.
-     */
-    private getMaxCardinality(element: EntityCSN): number;
-
-    /**
-     * Convenience method to shave off the namespace of a fully qualified path.
-     * More specifically, only the parts (reading from right to left) that are of
-     * kind "entity" are retained.
-     * a.b.c.Foo -> Foo
-     * Bar -> Bar
-     * sap.cap.Book.text -> Book.text (assuming Book and text are both of kind "entity")
-     * @param p path
-     * @returns the entity name without leading namespace.
-     */
-    private _trimNamespace(p: string): string;
-
-    /**
-     * Resolves a fully qualified identifier to a namespace.
-     * In an identifier 'a.b.c.D.E', the namespace is the part of the identifier
-     * read from left to right which does not contain a kind 'context' or 'service'.
-     * That is, if in the above example 'D' is a context and 'E' is a service,
-     * the resulting namespace is 'a.b.c'.
-     * @param pathParts the distinct parts of the namespace, i.e. ['a','b','c','D','E']
-     * @returns the namespace's name, i.e. 'a.b.c'.
-     */
-    private _resolveNamespace(pathParts: string[]): string;
-
-    /**
-     * Puts a passed string in docstring format.
-     * @param doc raw string to docify. May contain linebreaks.
-     * @returns an array of lines wrapped in doc format. The result is not
-     *          concatenated to be properly indented by `buffer.add(...)`.
-     */
-    private _docify(doc: string): string[];
-
-    /**
-     * Transforms an entity or CDS aspect into a JS aspect (aka mixin).
-     * That is, for an element A we get:
-     * - the function A(B) to mix the aspect into another class B
-     * - the const AXtended which represents the entity A with all of its aspects mixed in (this const is not exported)
-     * - the type A to use for external typing and is derived from AXtended.
-     * @param name the name of the entity
-     * @param element the pointer into the CSN to extract the elements from
-     * @param buffer the buffer to write the resulting definitions into
-     * @param cleanName the clean name to use. If not passed, it is derived from the passed name instead.
-     */
-    private _aspectify(name: string, element: CSN, buffer: Buffer, cleanName?: string);
-
-    /**
-     * Convenient API to consume resolveType.
-     * Internally calls resolveType, determines how it has to be imported,
-     * used, etc. relative to file and just returns the name under
-     * which it will finally be known within file.
-     * 
-     * For example: 
-     * model1.cds contains entity Foo
-     * model2.cds references Foo
-     * 
-     * calling resolveAndRequire({... Foo}, model2.d.ts) would then:
-     * 1. add an import of model1 to model2 with proper path resolution and alias, e.g. "import * as m1 from './model1'"
-     * 2. resolve any singular/ plural issues and association/ composition around it
-     * 3. return a properly prefixed name to use within model2.d.ts, e.g. "m1.Foo"
-     * 
-     * @param element the CSN element to resolve the type for.
-     * @param file source file for context.
-     * @returns name of the resolved type
-     */
-    private resolveAndRequire(element: CSN, file: SourceFile): string; 
-
-    /**
-     * Resolves an element's type to either a builtin or a user defined type. 
-     * Enriched with additional information for improved printout (see return type).
-     * @param element the CSN element to resolve the type for.
-     * @param file source file for context.
-     * @returns description of the resolved type
-     */
-    private resolveType(element: CSN, file: SourceFile): TypeResolveInfo;
-
-    /**
-     * Resolves the fully qualified name of an entity to its parent entity.
-     * _resolveParent(a.b.c.D) -> CSN {a.b.c}
-     * @param name fully qualified name of the entity to resolve the parent of.
-     * @returns the resolved parent CSN.
-     */
-    private _resolveParent(name: String): CSN;
-
-    /**
-     * Attempts to resolve a type that could reference another type.
-     * @param val 
-     * @param into see resolveType()
-     * @param file only needed as we may call _resolveInlineDeclarationType from here. Will be expelled at some point.
-     */
-    private _resolvePotentialReferenceType(val: any, into: TypeResolveInfo, file: SourceFile);
-
-
-    /**
-     * Resolves an inline declaration of a type.
-     * We can encounter declarations like:
-     * 
-     * record : array of {
-     *   column : String;
-     *   data   : String;
-     * }
-     * 
-     * These have to be resolved to a new type.
-     * 
-     * @param items the properties of the inline declaration.
-     * @param into see resolveType()
-     * @param relativeToindent the sourcefile in which we have found the reference to the type.
-     *  This is important to correctly detect when a field in the inline declaration is referencing
-     *  types from the CWD. In that case, we will not add an import for that type and not add a namespace-prefix.
-     */
-    private _resolveInlineDeclarationType(items: Array<unknown>, into: TypeResolveInfo, relativeTo: SourceFile): void;
-
-    /**
-     * Attempts to resolve a string to a type.
-     * String is supposed to refer to either a builtin type
-     * or any type defined in CSN.
-     * @param t fully qualified type, like cds.String, or a.b.c.d.Foo
-     * @param into optional dictionary to fill by reference, see resolveType()
-     * @returns see resolveType()
-     */
-    private _resolveTypeName(t: string, into: TypeResolveInfo): TypeResolveInfo;
-
-    /**
-     * Wraps type into association to scalar.
-     * @param t the singular type name. 
-     */
-    private _createToOneAssociation(t: string): string;
-
-    /**
-     * Wraps type into association to vector.
-     * @param t the singular type name. 
-     */
-    private _createToManyAssociation(t: string): string;
-
-    /**
-     * Wraps type into composition of scalar.
-     * @param t the singular type name. 
-     */
-    private _createCompositionOfOne(t: string): string;
-
-    /**
-     * Wraps type into composition of vector.
-     * @param t the singular type name. 
-     */
-    private _createCompositionOfMany(t: string): string;
-}

package/lib/file.d.ts

@@ -1,208 +0,0 @@
-type KVs = [string, string][]
-type Namespace = {[key: string]: Buffer}
-type ActionParams = [string, string][]
-type AsDirectoryParams = {relative: string | undefined, local: boolean, posix: boolean}
-
-/**
- * String buffer to conveniently append strings to.
- */
- export class Buffer {
-    public parts: string[];
-    private indentation: string;
-    private currentIndent: string;
-
-    constructor(indentation: string);
-
-    /**
-     * Indents by the predefined spacing.
-     */
-    indent(): void;
-
-    /**
-     * Removes one level of indentation.
-     */
-    outdent(): void; 
-
-    /**
-     * Concats all elements in the buffer into a single string.
-     * @param glue string to intersperse all buffer contents with
-     * @returns string spilled buffer contents.
-     */
-    join(glue: string): string;
-
-    /**
-     * Clears the buffer.
-     */
-    clear(): void;
-
-    /**
-     * Adds an element to the buffer with the current indentation level.
-     * @param part 
-     */
-    add(part: string): void;
-}
-
-/**
- * Convenience class to handle path qualifiers.
- */
-export class Path {
-    private parts: string[];
-
-    /**
-     * 
-     * @param parts parts of the path. 'a.b.c' -> ['a', 'b', 'c']
-     * @param kind FIXME: currently unused
-     */
-    constructor(parts: string[], kind: string);
-
-    /**
-     * @returns the path to the parent directory. 'a.b.c'.getParent() -> 'a.b'
-     */
-    getParent(): Path;
-
-    /**
-     * Transfoms the Path into a directory path.
-     * @param relative if defined, the path is constructed relative to this directory
-     * @param local if set to true, './' is prefixed to the directory
-     * @param posix if set to true, all slashes will be forward slashes on every OS. Useful for require/ import
-     * @returns directory 'a.b.c'.asDirectory() -> 'a/b/c' (or a\b\c when on Windows without passing posix = true)
-     */
-    asDirectory(params: AsDirectoryParams): string;
-
-    /**
-     * Transforms the Path into a namespace qualifier.
-     * @returns namespace qualifier 'a.b.c'.asNamespace() -> 'a.b.c'
-     */
-    asNamespace(): string;
-
-    /**
-     * Transforms the Path into an identifier that can be used as variable name.
-     * @returns identifier 'a.b.c'.asIdentifier() -> '_a_b_c', ''.asIdentifier() -> '_'
-     */
-    asIdentifier(): string;
-
-    /**
-     * @returns true, iff the Path refers to the current working directory, aka './'
-     */
-    isCwd(relative: string | undefined): boolean;
-}
-
-/**
- * Source file containing several buffers.
- */
-export class SourceFile {
-    public readonly path: Path;
-    private imports: {}
-    private types: Buffer;
-    private classes: Buffer;
-    private enums: Buffer;
-    private actions: Buffer;
-    private namespaces: Namespace;
-    private classNames: {}
-    private inflections: [string, string][]
-
-    constructor(path: string);
-
-    /**
-     * Adds a pair of singular and plural inflection.
-     * These are later used to generate the singular -> plural
-     * aliases in the index.js file.
-     * @param singular singular type without namespace.
-     * @param plural plural type without namespace
-     * @param original original entity name without namespace. 
-     *        In many cases this will be the same as plural.
-     */
-    addInflection(singular: string, plural: string, original: string);
-
-    /**
-     * Adds an action definition in form of a arrow function to the file.
-     * @param name name of the action
-     * @param params list of parameters, passed as [name, type] pairs
-     * @param returns the return type of the action
-     */
-    addAction(name: string, params: ActionParams, returns: string);
-
-    /**
-     * Adds an enum to this file.
-     * @param fq fully qualified name of the enum
-     * @param name local name of the enum
-     * @param kvs list of key-value pairs
-     */
-    addEnum(fq: string, clean: string, kvs: KVs);
-
-    /**
-     * Adds an arbitrary piece of code that is added
-     * right after the imports.
-     * @param code the preamble code.
-     */
-    addPreamble(code: string);
-
-    /**
-     * Adds a type alias to this file.
-     * @param fq fully qualified name of the enum
-     * @param name local name of the enum
-     * @param rhs the right hand side of the assignment
-     */
-    addType(fq: string, clean: string, rhs: string);
-
-    /**
-     * 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 clean cleaned name of the class 
-     * @param fq fully qualified name, including the namespace
-     */
-    addClass(clean: string, fq: string): void;
-
-    /**
-     * Retrieves or creates and retrieves a sub namespace
-     * with a given name.
-     * @param name of the sub namespace.
-     * @returns the sub namespace.
-     */
-    getSubNamespace(name: string): Namespace;
-
-    /**
-     * Adds an import if it does not exist yet.
-     * @param imp qualifier for the namespace to import.
-     */
-    addImport(imp: Path): void;
-
-    /**
-     * 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 all imports written to a buffer.
-     */
-    getImports(): Buffer;
-
-    /**
-     * Creates one string from the buffers representing the type definitions.
-     * @returns complete file contents.
-     */
-    toTypeDefs(): string;
-
-    /**
-     * Concats the classnames to an export dictionary 
-     * to create the accompanying JS file for the typings.
-     * @returns a string containing the module.exports for the JS file.
-     */
-    toJSExports(): string;
-}
-
-/**
- * Base definitions used throughout the typing process,
- * such as Associations and Compositions.
- */
-declare const baseDefinitions: SourceFile;
-
-/**
- * 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 root root directory to prefix all directories with
- * @param sources source files to write to disk
- * @returns Promise that resolves to a list of all directory paths pointing to generated files.
- */
-export function writeout(root: string, sources: SourceFile[]): Promise<string[]>;

package/lib/logging.d.ts

@@ -1,50 +0,0 @@
-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/util.d.ts

@@ -1,87 +0,0 @@
-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;