@cap-js/cds-typer 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -4,7 +4,37 @@ 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.4.1 - TBD
+## Version 0.6.1 - TBD
+
+### Changed
+
+### Added
+
+### Fixed
+
+
+## Version 0.6.0 - 2023-08-07
+
+### Added
+- Support for `event` syntax
+
+### Fixed
+- Initialise bound actions with stubs to support `"strict":true` in _tsconfig.json_
+- Add leading underscore to appease `noUnusedParameters` in strict tsconfigs
+- No longer inflect `type` definitions when they are referenced within entities or other type definitions
+
+## 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
+
+### Fixed
+- 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

package/README.md

@@ -1,174 +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 `@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).
-
-#### 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`.
-
-_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.
-- `--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
 
@@ -176,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/inline.js

@@ -142,7 +142,7 @@ class FlatInlineDeclarationResolver extends InlineDeclarationResolver {
     flatten(prefix, type) {
         return type.typeInfo.structuredType
             ? Object.entries(type.typeInfo.structuredType).map(([k,v]) => this.flatten(`${this.prefix(prefix)}${k}`, v))
-            : [`${prefix} ${this.getPropertyTypeSeparator()} ${type.typeName}`]
+            : [`${prefix}${this.getPropertyTypeSeparator()} ${type.typeName}`]
     }
 
     printInlineType(name, type, buffer) {
@@ -185,7 +185,7 @@ class StructuredInlineDeclarationResolver extends InlineDeclarationResolver {
         this.printDepth++
         const lineEnding = this.printDepth > 1 ? ',' : statementEnd
         if (type.typeInfo.structuredType) {
-            const prefix = name ? `${name} ${this.getPropertyTypeSeparator()}`: ''
+            const prefix = name ? `${name}${this.getPropertyTypeSeparator()}`: ''
             buffer.add(`${prefix} {`)
             buffer.indent()
             for (const [n, t] of Object.entries(type.typeInfo.structuredType)) {
@@ -194,7 +194,7 @@ class StructuredInlineDeclarationResolver extends InlineDeclarationResolver {
             buffer.outdent()
             buffer.add(`}${lineEnding}`)
         } else {
-            buffer.add(`${name} ${this.getPropertyTypeSeparator()} ${type.typeName}${lineEnding}`)
+            buffer.add(`${name}${this.getPropertyTypeSeparator()} ${type.typeName}${lineEnding}`)
         }
         this.printDepth--
         return buffer

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'
@@ -115,7 +116,7 @@ class Resolver {
         let qualifier = parts.join('.')
         while (
             this.csn.definitions[qualifier] &&
-            ['entity', 'type', 'aspect'].includes(this.csn.definitions[qualifier].kind)
+            ['entity', 'type', 'aspect', 'event'].includes(this.csn.definitions[qualifier].kind)
         ) {
             parts.pop()
             qualifier = parts.join('.')
@@ -130,6 +131,7 @@ class Resolver {
      * - explicit annotation by the user in the CSN
      * - implicitly derived inflection based on simple grammar rules
      * - collisions between singular and plural name (resolved by appending a '_' suffix)
+     * - type definitions, which are not inflected
      * - inline type definitions, which don't really have a linguistic plural,
      *   but need to expressed as array type to be consumable by the likes of Composition.of.many<T>
      * @param {import('./resolver').TypeResolveInfo} typeInfo information about the type gathered so far.
@@ -137,6 +139,16 @@ class Resolver {
      * @returns {Inflection}
      */
     inflect(typeInfo, namespace) {
+        // TODO: handle builtins here as well?
+        // guard: types don't get inflected
+        if (typeInfo.csn?.kind === 'type') {
+            return { 
+                singular: typeInfo.plainName,
+                plural: typeInfo.plainName,
+                typeName: typeInfo.plainName,
+            }
+        }
+
         let typeName
         let singular
         let plural
@@ -212,13 +224,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 +271,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 +362,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

@@ -99,6 +99,8 @@ class SourceFile extends File {
         this.imports = {}
         /** @type {Buffer} */
         this.preamble = new Buffer()
+        /** @type {{ buffer: Buffer, fqs: {name: string, fq: string}[]}} */
+        this.events = { buffer: new Buffer(), fqs: []} 
         /** @type {Buffer} */
         this.types = new Buffer()
         /** @type {{ buffer: Buffer, fqs: {name: string, fq: string}[]}} */
@@ -119,8 +121,24 @@ class SourceFile extends File {
         this.inflections = []
     }
 
-    static stringifyLambda(name, parameters = [], returns = 'any') {
-        return `${name}: (${parameters.map(([n, t]) => `${n}: ${t}`).join(', ')}) => ${returns}`
+    /**
+     * Stringifies a lambda expression.
+     * @param {{name: string, parameters: [string, string][], returns: string, initialiser: string}} - name, parameters, return type, and initialiser expression
+     * @returns {string} - the stringified lambda
+     * @example
+     * ```js
+     * stringifyLambda({parameters: [['p','T']]}  // (p: T) => any
+     * stringifyLambda({name: 'f', parameters: [['p','T']]}  // f: (p: T) => any
+     * stringifyLambda({name: 'f', parameters: [['p','T']], returns: 'number'}  // f: (p: T) => number
+     * stringifyLambda({name: 'f', parameters: [['p','T']], returns: 'number', initialiser: '_ => 42'}  // f: (p: T) => string = _ => 42
+     * 
+     * ```
+     */
+    static stringifyLambda({name, parameters=[], returns='any', initialiser}) {
+        const signature = `(${parameters.map(([n, t]) => `${n}: ${t}`).join(', ')}) => ${returns}`
+        const prefix = name ? `${name}: `: ''
+        const suffix = initialiser ? ` = ${initialiser}` : ''
+        return prefix + signature + suffix
     }
 
     /**
@@ -139,27 +157,25 @@ class SourceFile extends File {
     /**
      * Adds a function definition in form of a arrow function to the file.
      * @param {string} name name of the function
-     * @param {{relative: string | undefined, local: boolean, posix: boolean}} params list of parameters, passed as [name, type] pairs
+     * @param {{relative: string | undefined, local: boolean, posix: boolean}} parameters list of parameters, passed as [name, type] pairs
      * @param returns the return type of the function
      */
-    addFunction(name, params, returns) {
+    addFunction(name, parameters, returns) {
         // FIXME: use different buffers for buffers and actions, or at least rename buffer to the more general category "functions"?
         this.actions.buffer.add("// function")
-        this.actions.buffer.add(`export declare const ${SourceFile.stringifyLambda(name, params, returns)};`)
+        this.actions.buffer.add(`export declare const ${SourceFile.stringifyLambda({name, parameters, returns})};`)
         this.actions.names.push(name)
     }
 
     /**
      * 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 {{relative: string | undefined, local: boolean, posix: boolean}} parameters 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(', ')
+    addAction(name, parameters, returns) {
         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.buffer.add(`export declare const ${SourceFile.stringifyLambda({name, parameters, returns})};`)
         this.actions.names.push(name)
     }
 
@@ -196,6 +212,7 @@ class SourceFile extends File {
         // 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.
+        // FIXME: this really should be in visitor, as File should not contain logic of this kind
         this.enums.fqs.push({ name, fq })
         const bu = this.enums.buffer
         bu.add('// enum')
@@ -210,7 +227,6 @@ class SourceFile extends File {
         bu.add('}')
         bu.add(`export type ${name} = ${[...vals].join(' | ')}`)
         bu.add('')
-        
     }
 
     /**
@@ -225,6 +241,16 @@ class SourceFile extends File {
         this.classNames[clean] = fq
     }
 
+    /**
+     * Adds an event to this file.
+     * are supposed to be present in this file. 
+     * @param {string} name cleaned name of the event
+     * @param {string} fq fully qualified name, including the namespace
+     */
+    addEvent(name, fq) {
+        this.events.fqs.push({ name, fq })
+    }
+
     /**
      * Adds an import if it does not exist yet.
      * @param {Path} imp qualifier for the namespace to import.
@@ -289,6 +315,7 @@ class SourceFile extends File {
             namespaces.join(),
             this.aspects.join(), // needs to be before classes
             this.classes.join(),
+            this.events.buffer.join(),
             this.actions.buffer.join(),
         ].filter(Boolean).join('\n')
     }
@@ -311,6 +338,8 @@ class SourceFile extends File {
                         `module.exports.${original} = csn.${original}`
                     ])))
             ) // singular -> plural aliases
+            .concat(['// events'])
+            .concat(this.events.fqs.map(({fq, name}) => `module.exports.${name} = '${fq}'`))
             .concat(['// actions'])
             .concat(this.actions.names.map(name => `module.exports.${name} = '${name}'`))
             .concat(['// enums'])
@@ -473,7 +502,7 @@ export namespace Composition {
 }
 
 export class Entity {
-    static data<T extends Entity> (this:T, input:Object) : T {
+    static data<T extends Entity> (this:T, _input:Object) : T {
         return {} as T // mock
     }
 }

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()
@@ -132,17 +132,18 @@ class Visitor {
             this.visitElement(ename, element, file, buffer)
         }
         for (const [aname, action] of Object.entries(entity.actions ?? {})) {
+            const lambdaString = 
             buffer.add(
-                SourceFile.stringifyLambda(
-                    aname,
-                    Object.entries(action.params ?? {}).map(([n, t]) => [
+                SourceFile.stringifyLambda({
+                    name: aname,
+                    parameters: Object.entries(action.params ?? {}).map(([n, t]) => [
                         n,
                         this.resolver.resolveAndRequire(t, file).typeName,
                     ]),
-                    action.returns ? this.resolver.resolveAndRequire(action.returns, file).typeName : 'any'
-                )
+                    returns: action.returns ? this.resolver.resolveAndRequire(action.returns, file).typeName : 'any',
+                    initialiser: `undefined as unknown as this['${aname}']`
+                })
             )
-            //this.visitEntity(aname, action, file, buffer)
         }
         buffer.outdent()
         buffer.add('};')
@@ -287,6 +288,26 @@ class Visitor {
         this._aspectify(name, aspect, file.aspects, clean)
     }
 
+    #printEvent(name, event) {
+        this.logger.debug(`Printing event ${name}`)
+        const clean = this.resolver.trimNamespace(name)
+        const ns = this.resolver.resolveNamespace(name.split('.'))
+        const file = this.getNamespaceFile(ns)
+        file.addEvent(clean, name)
+        const buffer = file.events.buffer
+        buffer.add('// event')
+        buffer.add(`export class ${clean} {`)
+        buffer.indent()
+        const propOpt = this.options.propertiesOptional
+        this.options.propertiesOptional = false
+        for (const [ename, element] of Object.entries(event.elements ?? {})) {
+            this.visitElement(ename, element, file, buffer)
+        }
+        this.options.propertiesOptional = propOpt
+        buffer.outdent()
+        buffer.add('}')
+    }
+
     /**
      * Visits a single entity from the CSN's definition field.
      * Will call #printEntity or #printAction based on the entity's kind.
@@ -310,6 +331,9 @@ class Visitor {
             case 'aspect':
                 this.#printAspect(name, entity)
                 break
+            case 'event':
+                this.#printEvent(name, entity)
+                break
             default:
                 this.logger.error(`Unhandled entity kind '${entity.kind}'.`)
         }
@@ -318,7 +342,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.4.0",
+  "version": "0.6.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": {