@cap-js/cds-typer 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -4,7 +4,24 @@ 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.5.1 - TBD
+
+## Version 0.5.0 - 2023-07-25
+
+### Changed
+- Facilitate strict property checks. Note: `checkJs: true` must be present in the project's _jsconfig.json_ or _tsconfig.json_ respectively for this feature to become effective
+
+### Added
+- Support for `array of` syntax
+
+### Fixes
+- Generate `string` type for date-related types in CDS definitions
+- Generate `Buffer | string` type for the CDS type `LargeBinary`
+
+
+## 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

@@ -1,172 +1,13 @@
 # CDS type generator for JavaScript
 
+[![REUSE status](https://api.reuse.software/badge/github.com/cap-js/cds-typer)](https://api.reuse.software/info/github.com/cap-js/cds-typer)
+![Unit Tests passing](https://github.com/cap-js/cds-typer/actions/workflows/test.yml/badge.svg)
+
 ## About this project
 
 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.
-
-### 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).
-
-#### Standalone CLI
-Assuming you have the following CDS project structure:
-
-```
-/home/
-├── mybookshop/
-│   ├── db/
-│   │   └── schema.cds
-│   ├── srv/
-│   │   └── service.js
-```
-
-a typical workflow to generate types for your CDS project could look something like this:
-
-```sh
-npx @cap-js/cds-typer /home/mybookshop/db/schema.cds --outputDirectory /home/mybookshop/@types
-```
-
-You would then end up with a directory `@types`, which contains your entities and their accompanying types in a directory structure. The directory structure directly reflects the namespaces you have defined your entities in. They have to be imported in any JavaScript-based service handlers you want to have type support in and can replace calls to `cds.entities(...)`:
-
-```js
-// srv/service.js
-const { Books } = require('my.bookshop')
-```
-
-becomes
-
-```js
-// srv/service.js
-const { Books } = require('../@types/mybookshop')
-```
-
-From that point on you should receive code completion from the type system for `Books`.
-
-_cds-typer_ comes with rudimentary CLI support and a few command line options:
-
-- `--help`: prints all available parameters.
-- `--outputDirectory`: specifies the root directory where all generated files should be put. Defaults to the CWD.
-- `--jsConfigPath`: specifies the path to the `jsconfig.json` file to generate. Usually your project's root directory. If specified, a config file is created that restricts the usage of types even further:
-
-```js
-// generated .ts file
-class Book {
-    title: string;
-}
-
-// some hook in your service
-SELECT(Books, b => {
-    b.title // 👍 no problem, property exists
-    b.numberOfPages // ❌ property does not exist
-})
-```
-With the generated config in place, the language server will display an error, telling you that `numberOfPages` does not exist in this context. Without the config it would just infer it as `any`.
-
-- `--loglevel`: minimum log level that should be printed. Defaults to `NONE`. Available log levels roughly follow [Microsoft's dotnet log levels](https://docs.microsoft.com/en-us/dotnet/api/microsoft.extensions.logging.loglevel?view=dotnet-plat-ext-6.0):
-
-```
-TRACE
-DEBUG
-INFO
-WARNING
-ERROR
-CRITICAL
-NONE
-```
-
-The utility expects (at least) one path to a `.cds` file as positional parameter which serves as entry point to the model in question, e.g.:
-
-```sh
-npx @cap-js/cds-typer ./path/to/my/model/model.cds --outputDirectory /tmp/
-```
-
-Note that you can also pass multiple paths or `"*"` as glob pattern (with quotes to circumvent expansion by the shell). This passes the pattern on to the compiler where the [regular resolve strategy](https://cap.cloud.sap/docs/node.js/cds-compile?q=compiler#cds-resolve) is used.
-
-#### From VSCode
-Installing the [CDS VSCode Extension](https://www.npmjs.com/package/@sap/vscode-cds) also adds support for generating types for your model from within VSCode. Adding the appropriate facet to your project via `cds add typer` (and installing the added dependencies thereafter) allows you to simply hit save on any `.cds` file that is part of your model to trigger the generation process.
-#### Programmatically
-The main API for using _cds-typer_ within another project is contained in [`compile.js`](https://github.tools.sap/cap/cds-typer/blob/master/lib/compile.js), specifically:
-
-- `compileFromFile(…)` to parse a `.cds` file. This involves compiling it to CSN first.
-- `compileFromCSN(…)` to directly compile from CSN object. This is useful when you already have your CSN available as part of a tool chain. ⚠️ **WARNING**: the application of `cdstyper` may be impure, meaning that it _could_ alter the provided CSN. If you use the typer this way, you may want to apply it as last step of your tool chain.
-
-
-### Features
-#### Plural Types
-While CDS encourages the use of plural form for defined entities, their OOP equivalent classes are usually named in singular. _cds-typer_ automatically transforms entity names to singular and adds the plural form for arrays:
-
-```cds
-entity Books : cuid {
-    …
-}
-```
-
-becomes
-
-```ts
-class Book {
-	…
-}
-
-class Books extends Array<Book> {}
-```
-
-If you need to customise the singular or plural form, or if your entities are already in singular form, you can do so using annotations:
-
-```cds
-@singular: 'Mouse'
-entity Mice {}
-
-@plural: 'SomeListList'
-entity SomeList {}
-```
-
-results in
-
-```ts
-class Mouse { … }
-class Mice extends Array<Mouse> { … }
-
-class SomeList { … }
-class SomeListList extends Array<SomeList> { … }
-```
-
-### Relation to _cds2types_
-This project is inspired by the existing [_cds2types_](https://github.com/mrbandler/cds2types), but differs in a few aspects:
-
-#### Reworked Imports
-Instead of one monolithic `.d.ts` file containing all entities in nested namespaces, multiple files are generated where each namespace is represented by a directory structure. This facilicates simpler imports in a more Java-esque style:
-
-```js
-const types = require('./cds2types/compiled.d.ts')
-
-console.log(types.sap.cap.bookshop.Books) // a class
-```
-
-becomes
-
-```js
-const { Books } = require('./cds-typer/sap/cap/bookshop')
-
-console.log(Books) // the same class
-```
-
-#### Usable in Javascript Projects
-Generated code is usable from within plain Javascript projects. The code generated by _cds2types_ would represent each cds-entity as an interface, which are not visible to Javascript projects. _cds-typer_ uses classes instead.
-
-#### Faster
-_cds2types_ takes a detour to create a Typescript AST first and then print out the formatted source files. _cds-typer_ directly walks the linked CSN and creates strings on the fly. Also, file operations are `async`. These two changes speed up _cds-typer_ by around one to two orders of magnitude compared to _cds2types_.
-
-#### Small Footprint
-_cds-typer_ tries to keep its dependency footprint as small as possible. Libraries like `typescript` are only needed as dev dependencies.
-
-
-
-
-
+Exhaustive documentation can be found on [CAPire](https://cap.cloud.sap/docs/tools/cds-typer).
 
 ## Support, Feedback, Contributing
 
@@ -174,8 +15,8 @@ This project is open to feature requests/suggestions, bug reports etc. via [GitH
 
 ## Code of Conduct
 
-We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone. By participating in this project, you agree to abide by its [Code of Conduct](CODE_OF_CONDUCT.md) at all times.
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone. By participating in this project, you agree to abide by its [Code of Conduct](https://github.com/cap-js/.github/blob/main/CODE_OF_CONDUCT.md) at all times.
 
 ## Licensing
 
-Copyright 2022-2022 SAP SE or an SAP affiliate company and cds-dts-generator contributors. Please see our [LICENSE](LICENSE) for copyright and license information. Detailed information including third-party components and their licensing/copyright information is available [via the REUSE tool](https://api.reuse.software/info/github.com/SAP/cds-dts-generator).
+Copyright 2022-2022 SAP SE or an SAP affiliate company and cds-typer contributors. Please see our [LICENSE](LICENSE) for copyright and license information. Detailed information including third-party components and their licensing/copyright information is available [via the REUSE tool](https://api.reuse.software/info/github.com/SAP/cds-dts-generator).

package/lib/cli.js

@@ -6,80 +6,82 @@ const { compileFromFile } = require('./compile')
 const { parseCommandlineArgs } = require('./util')
 const { Levels } = require('./logging')
 const path = require('path')
+const { EOL } = require('node:os')
 
+const EOL2 = EOL + EOL
 const toolName = 'cds-typer'
 
 const flags = {
-    // FIXME: remove asap
-    rootDir: {
-        desc: '[DEPRICATED] use outputDirectory instead',
-        default: './',
-    },
     outputDirectory: {
-        desc: 'root directory to write generated files to',
+        desc: 'Root directory to write the generated files to.',
         default: './',
+        type: 'string'
     },
     help: {
-        desc: 'this text',
+        desc: 'This text.',
     },
     logLevel: {
-        desc: `minimum log level`,
+        desc: `Minimum log level that is printed.`,
         allowed: Object.keys(Levels),
         default: Object.keys(Levels).at(-1),
     },
     jsConfigPath: {
-        desc: `Path to where the jsconfig.json should be written. If specified, ${toolName} will create a jsconfig.json file and set it up to restrict property usage in types entities to existing properties only.`,
+        desc: `Path to where the jsconfig.json should be written.${EOL}If specified, ${toolName} will create a jsconfig.json file and${EOL}set it up to restrict property usage in types entities to${EOL}existing properties only.`,
+        type: 'string'
     },
     version: {
-        desc: 'prints the version of this tool'
+        desc: 'Prints the version of this tool.'
     },
     inlineDeclarations: {
-        desc: 'whether to resolve inline type declarations flat (x_a, x_b, ...) or structured (x: {a, b})',
+        desc: `Whether to resolve inline type declarations${EOL}flat: (x_a, x_b, ...)${EOL}or structured: (x: {a, b}).`,
         allowed: ['flat', 'structured'],
         default: 'structured'
     },
     propertiesOptional: {
-        desc: 'if set to true, properties in entities are always generated as optional (a?: T)',
+        desc: `If set to true, properties in entities are${EOL}always generated as optional (a?: T).`,
         allowed: ['true', 'false'],
         default: 'true'
     }
 }
 
 const hint = () => console.log('Missing or invalid parameter(s). Call with --help for more details.')
+const indent = (s, indentation) => s.split(EOL).map(line => `${indentation}${line}`).join(EOL)
 
-const help = () =>
-    console.log(
-        '[SYNOPSIS]\n' +
-        'Call with at least one positional parameter pointing to the (root) CDS file you want to compile.\n' +
-            'Additionaly, you can use the following parameters:\n' +
+const help = () => `SYNOPSIS${EOL2}` +
+        indent(`cds-typer [cds file | "*"]`, '  ') + EOL2 +
+        indent(`Generates type information based on a CDS model.${EOL}Call with at least one positional parameter pointing${EOL}to the (root) CDS file you want to compile.`, '  ') + EOL2 +
+            `OPTIONS${EOL2}` +
             Object.entries(flags)
                 .sort()
                 .map(([key, value]) => {
-                    let s = `--${key}: ${value.desc}`
+                    let s = indent(`--${key}`, '  ')
                     if (value.allowed) {
-                        s += ` [allowed: ${value.allowed.join(' | ')}]`
+                        s += `: <${value.allowed.join(' | ')}>`
+                    } else if (value.type) {
+                        s += `: <${value.type}>`
                     }
                     if (value.default) {
-                        s += ` (default: ${value.default})`
+                        s += EOL
+                        s += indent(`(default: ${value.default})`, '    ')
                     }
+                    s += `${EOL2}${indent(value.desc, '    ')}`
                     return s
                 }
-            ).join('\n\n')
-    )
+            ).join(EOL2)
 
-const version = () => console.log(require('../package.json').version)
+const version = () => require('../package.json').version
 
 const main = async (args) => {
     if ('help' in args.named) {
-        help()
+        console.log(help())
         process.exit(0)
     }
     if ('version' in args.named) {
-        version()
+        console.log(version())
         process.exit(0)
     }
     if (args.positional.length === 0) {
-        hint()
+        console.log(hint())
         process.exit(1)
     }
     if (args.named.jsConfigPath && !args.named.jsConfigPath.endsWith('jsconfig.json')) {
@@ -98,3 +100,7 @@ const main = async (args) => {
 if (require.main === module) {
     main(parseCommandlineArgs(process.argv.slice(2), flags))
 }
+
+function helpToCapire() {
+
+}

package/lib/compile.js

@@ -8,11 +8,16 @@ const { writeout } = require('./file')
 const { Logger } = require('./logging')
 const { Visitor } = require('./visitor')
 
+/**
+ * @typedef {import('./visitor').CompileParameters} CompileParameters
+ */
+
 /**
  * Writes the accompanying jsconfig.json file to the specified paths.
  * Tries to merge nicely if an existing file is found.
  * @param path {string} filepath to jsconfig.json.
  * @param logger {import('./logging').Logger} logger
+ * @private
  */
 const writeJsConfig = (path, logger) => {
     let values = {

package/lib/components/resolver.js

@@ -40,7 +40,7 @@ const Builtins = {
     String: 'string',
     Binary: 'string',
     LargeString: 'string',
-    LargeBinary: 'string',
+    LargeBinary: 'Buffer | string',
     Integer: 'number',
     UInt8: 'number',
     Int16: 'number',
@@ -52,10 +52,11 @@ const Builtins = {
     Float: 'number',
     Double: 'number',
     Boolean: 'boolean',
-    Date: 'Date',
-    DateTime: 'Date',
-    Time: 'Date',
-    Timestamp: 'Date',
+    // note: the date-related types _can_ be Date in some cases, but let's start with string
+    Date: 'string',  // yyyy-mm-dd
+    DateTime: 'string', // yyyy-mm-dd + time + TZ (precision: seconds
+    Time: 'string',
+    Timestamp: 'string', // yyy-mm-dd + time + TZ (ms precision)
     //
     Composition: 'Array',
     Association: 'Array'
@@ -212,13 +213,14 @@ class Resolver {
                 {
                     Association: [createToOneAssociation, createToManyAssociation],
                     Composition: [createCompositionOfOne, createCompositionOfMany],
+                    array: [createArrayOf, createArrayOf]
                 }[element.constructor.name] ?? []
 
             if (toOne && toMany) {
-                const target = typeof element.target === 'string' ? { type: element.target } : element.target
+                const target = element.items ?? (typeof element.target === 'string' ? { type: element.target } : element.target)
                 const { singular, plural } = this.resolveAndRequire(target, file).typeInfo.inflection
                 typeName =
-                    cardinality > 1 ? toMany(plural) : toOne(this.visitor.isSelfReference(element.target) ? 'this' : singular)
+                    cardinality > 1 ? toMany(plural) : toOne(this.visitor.isSelfReference(target) ? 'this' : singular)
                 file.addImport(baseDefinitions.path)
             }
         } else {
@@ -258,8 +260,11 @@ class Resolver {
             typeInfo.inflection = this.inflect(typeInfo)
         }
 
-        if (typeInfo.isArray === true) {
-            typeName = createArrayOf(typeName)
+        // add fallback inflection. Mainly needed for array-of with builtin types.
+        // (array-of relies on inflection being present, which is not the case in builtin)
+        typeInfo.inflection ??= {
+            singular: typeName,
+            plural: typeName
         }
 
         // FIXME: typeName could probably just become part of typeInfo
@@ -346,8 +351,8 @@ class Resolver {
 
         // objects and arrays
         if (element?.items) {
-            // FIXME: builtin = true? arrays are kinda builtin
             result.isArray = true
+            result.isBuiltin = true
             this.resolveType(element.items, file)
             //delete element.items
         } else if (element?.elements && !element?.type) {

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

@@ -124,7 +124,7 @@ class Visitor {
         })
 
         // CLASS ASPECT
-        buffer.add(`export function ${identAspect(clean)}<TBase extends new (...args: any[]) => any>(Base: TBase) {`)
+        buffer.add(`export function ${identAspect(clean)}<TBase extends new (...args: any[]) => object>(Base: TBase) {`)
         buffer.indent()
         buffer.add(`return class ${clean} extends Base {`)
         buffer.indent()
@@ -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
@@ -316,7 +318,7 @@ class Visitor {
     /**
      * A self reference is a property that references the class it appears in.
      * They need to be detected on CDS level, as the emitted TS types will try to
-     * refer to refer to types via their alias that hides the aspectification.
+     * refer to types via their alias that hides the aspectification.
      * If we attempt to directly refer to this alias while it has not been fully created,
      * that will result in a TS error.
      * @param {String} entityName

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@cap-js/cds-typer",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Generates .ts files for a CDS model to receive code completion in VS Code",
   "main": "index.js",
+  "repository": "github:cap-js/cds-typer",
   "homepage": "https://cap.cloud.sap/",
   "keywords": [
     "CAP",
@@ -17,7 +18,14 @@
     "test:all": "jest",
     "test": "npm run test:unit",
     "lint": "eslint",
-    "cli": "node lib/cli.js"
+    "cli": "node lib/cli.js",
+    "doc:clean": "rm -rf ./doc",
+    "doc:prepare": "npm run doc:clean && mkdir -p doc/types",
+    "doc:typegen": "./node_modules/.bin/tsc ./lib/*.js  --skipLibCheck --declaration --allowJs --emitDeclarationOnly --outDir doc/types && cd doc/types && tsc --init",
+    "doc:html": "npm run doc:typegen && ./node_modules/.bin/typedoc 'doc/types/**/*.d.ts' --entryPointStrategy expand --out doc/html --tsconfig doc/types/tsconfig.json",
+    "doc:md": "npm run doc:typegen && ./node_modules/.bin/typedoc --plugin typedoc-plugin-markdown 'doc/types/compile.d.ts' --out doc/md --tsconfig doc/types/tsconfig.json",
+    "doc:cli": "npm run cli -- --help > ./doc/cli.txt",
+    "doc:full": "npm run doc:prepare && npm run doc:html && npm run doc:cli"
   },
   "files": [
     "lib/",
@@ -39,6 +47,8 @@
     "eslint-config-prettier": "^8.5.0",
     "eslint-plugin-prettier": "^4.0.0",
     "jest": "^29",
+    "typedoc": "^0.24.8",
+    "typedoc-plugin-markdown": "^3.15.3",
     "typescript": ">=4.6.4"
   },
   "jest": {

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;