@cap-js/cds-typer 0.25.0 → 0.27.0

package/CHANGELOG.md

@@ -4,7 +4,30 @@ 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.26.0 - TBD
+## Version 0.28.0 - TBD
+
+## Version 0.27.0 - 2024-10-02
+### Changed
+- Any configuration variable (via CLI or `cds.env`) can now be passed in snake_case in addition to camelCase
+- Action parameters are now generated as optional by default, which is how the runtime treats them. Mandatory parameters have to be marked as `not null` in CDS/CDL, or `notNull` in CSN.
+
+### Fixed
+- Fix build task for projects with spaces
+- Fixa bug where cds-typer would produce redundant type declarations when the model contains an associations to another entity's property
+
+## Version 0.26.0 - 2024-09-11
+### Added
+- Added a static `.keys` property in all entities. That property is dictionary which holds all properties as keys that are marked as `key` in CDS
+- Added a CLI option `--useEntitiesProxy`. When set to `true`, all entities are wrapped into `Proxy` objects during runtime, allowing top level imports of entity types.
+- Added a static `.kind` property for entities and types, which contains `'entity'` or `'type'` respectively
+- Apps need to provide `@sap/cds` version `8.2` or higher.
+- Apps need to provide `@cap-js/cds-types` version `0.6.4` or higher.
+- Typed methods are now generated for calls of unbound actions. Named and positional call styles are supported, e.g. `service.action({one, two})` and `service.action(one, two)`.
+- Action parameters can be optional in the named call style (`service.action({one:1, ...})`).
+- Actions for ABAP RFC modules cannot be called with positional parameters, but only with named ones. They have 'parameter categories' (import/export/changing/tables) that cannot be called in a flat order.
+- Services now have their own export (named like the service itself). The current default export is not usable in some scenarios from CommonJS modules.
+- Enums and operation parameters can have doc comments
+
 
 ## Version 0.25.0 - 2024-08-13
 ### Added
@@ -34,6 +57,7 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/).
 
 
 ## Version 0.22.0 - 2024-06-20
+
 ### Fixed
 - Fixed a bug where keys would sometimes inconsistently become nullable
 
@@ -85,7 +109,7 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/).
 - Importing an enum into a service will now generate an alias to the original enum, instead of incorrectly duplicating the definition
 - Returning entities from actions/ functions and using them as parameters will now properly use the singular inflection instead of returning an array thereof
 - Aspects are now consistently named and called in their singular form
-- Only detect inflection clash if singular and plural share the same namespace. This also no longer reports `sap.common` as erroneous during type creation 
+- Only detect inflection clash if singular and plural share the same namespace. This also no longer reports `sap.common` as erroneous during type creation
 
 ## Version 0.19.0 - 2024-03-28
 ### Added

package/README.md

@@ -9,6 +9,25 @@ Generates `.ts` files for a CDS model to receive code completion in VS Code.
 
 Exhaustive documentation can be found on [CAPire](https://cap.cloud.sap/docs/tools/cds-typer).
 
+## Known Restrictions
+
+Certain language features of CDS can not be represented in TypeScript.
+Trying to generate types for models using these features will therefore result in incorrect or broken TypeScript code.
+
+### Changing Types
+
+While the following is valid CDS, there is no TypeScript equivalent that would allow the type of an inherited property to change (TS2416).
+
+```cds
+entity A {
+  foo: Integer
+};
+
+entity B: A {
+  foo: String
+}
+```
+
 ## Support, Feedback, Contributing
 
 This project is open to feature requests/suggestions, bug reports etc. via [GitHub issues](https://github.com/cap-js/cds-typer/issues). Contribution and feedback are encouraged and always welcome. For more information about how to contribute, the project structure, as well as additional contribution information, see our [Contribution Guidelines](CONTRIBUTING.md).

package/cds-plugin.js

@@ -36,7 +36,7 @@ const rmDirIfExists = dir => {
  * Remove files with given extensions from a directory recursively.
  * @param {string} dir - The directory to start from.
  * @param {string[]} exts - The extensions to remove.
- * @returns {Promise<void>}
+ * @returns {Promise<unknown>}
  */
 const rmFiles = async (dir, exts) => fs.existsSync(dir)
     ? Promise.all(
@@ -68,10 +68,15 @@ cds.build?.register?.('typescript', class extends cds.build.Plugin {
 
     get #appFolder () { return cds?.env?.folders?.app ?? 'app' }
 
+    /**
+     * cds.env > tsconfig.compilerOptions.paths > '@cds-models' (default)
+     */
     get #modelDirectoryName () {
+        const outputDirectory = cds.env.typer?.outputDirectory
+        if (outputDirectory) return outputDirectory
         try {
             // expected format: { '#cds-models/*': [ './@cds-models/*/index.ts' ] }
-            //                                       ^^^^^^^^^^^^^^^
+            //                                          ^^^^^^^^^^^
             //                             relevant part - may be changed by user
             const config = JSON.parse(fs.readFileSync ('tsconfig.json', 'utf8'))
             const alias = config.compilerOptions.paths['#cds-models/*'][0]
@@ -89,7 +94,9 @@ cds.build?.register?.('typescript', class extends cds.build.Plugin {
 
     async #runCdsTyper () {
         DEBUG?.('running cds-typer')
-        await typer.compileFromFile('*', { outputDirectory: this.#modelDirectoryName })
+        cds.env.typer ??= {}
+        cds.env.typer.outputDirectory ??= this.#modelDirectoryName
+        await typer.compileFromFile('*')
     }
 
     async #buildWithConfig () {
@@ -103,7 +110,7 @@ cds.build?.register?.('typescript', class extends cds.build.Plugin {
         DEBUG?.('building without config')
         // this will include gen/ that was created by the nodejs task
         // _within_ the project directory. So we need to remove it afterwards.
-        await exec(`npx tsc --outDir ${this.task.dest}`)
+        await exec(`npx tsc --outDir "${this.task.dest}"`)
         rmDirIfExists(path.join(this.task.dest, cds.env.build.target))
         rmDirIfExists(path.join(this.task.dest, this.#appFolder))
     }

package/lib/cli.js

@@ -2,20 +2,147 @@
 /* eslint-disable no-console */
 'use strict'
 
+/**
+ * @typedef {import('./typedefs').config.cli.ParameterSchema[number]} Parameter
+ */
+
 const cds = require('@sap/cds')
 const { compileFromFile } = require('./compile')
-const { parseCommandlineArgs } = require('./util')
+const { camelToSnake } = require('./util')
 const { deprecated, _keyFor } = require('./logging')
 const path = require('path')
 const { EOL } = require('node:os')
+const { camelSnakeHybrid, configuration } = require('./config')
 
 const EOL2 = EOL + EOL
 const toolName = 'cds-typer'
-
 // @ts-expect-error - nope, it is actually there. Types just seem to be out of sync.
 const lls = cds.log.levels
+const parameterTypes = {
+    boolean:
+    /**
+     * @param {Parameter} props - additional parameter properties
+     * @returns {Parameter}
+     */
+    props => ({...{
+        allowed: ['true', 'false'],
+        type: 'boolean',
+        postprocess: (/** @type {string} */ value) => value === 'true'
+    },
+    ...props})
+}
+
+/**
+ * Adds additional properties to the CLI parameter schema.
+ * @param {import('./typedefs').config.cli.ParameterSchema } flags - The CLI parameter schema.
+ * @returns {import('./typedefs').config.cli.ParameterSchema} - The enriched schema.
+ */
+const enrichFlagSchema = flags => {
+    const flagKeys = Object.keys(flags)
+    for (const [key, value] of Object.entries(flags)) {
+        /** @type {Parameter} */(value).camel = key;
+        /** @type {Parameter} */(value).snake = camelToSnake(key)
+    }
+    // non-enumerable utilities
+    Object.defineProperties(flags, {
+        hasFlag: {
+            value: (/** @type {string} **/ flag) => Object.values(flags).some(f => f.snake === flag || f.camel === flag)
+        },
+        keys: {
+            value: flagKeys
+        }
+    })
+    return camelSnakeHybrid(flags)
+}
+
+/**
+ * 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 {string[]} argv - list of command line arguments
+ * @param {import('./typedefs').config.cli.ParameterSchema} schema - allowed flags. May specify default values.
+ * @returns {import('./typedefs').config.cli.ParsedParameters} - parsed arguments
+ */
+const parseCommandlineArgs = (argv, schema) => {
+    const isFlag = (/** @type {string} */ arg) => arg.startsWith('--')
+    const positional = []
+    /** @type {import('./typedefs').config.cli.ParsedParameters['named']} */
+    const named = {}
+
+    let i = 0
+    while (i < argv.length) {
+        const originalArgName = argv[i]  // so our feedback to the user is less confusing
+        let arg = originalArgName
+        if (isFlag(arg)) {
+            arg = camelToSnake(arg.slice(2))
+            // @ts-expect-error - cba to add hasFlag to the general dictionary
+            if (!schema.hasFlag(arg)) {
+                throw new Error(`invalid named flag '${originalArgName}'`)
+            }
+            const next = argv[i + 1]
+            if (next && !isFlag(next)) {
+                named[arg] = { value: next, isDefault: false }
+                i++
+            } else {
+                named[arg] = { value: schema[arg].default, isDefault: true }
+            }
+
+            const { allowed, allowedHint } = schema[arg]
+            if (allowed && !allowed.includes(named[arg].value)) {
+                throw new Error(`invalid value '${named[arg]?.value ?? named[arg]}' for flag ${originalArgName}. Must be one of ${(allowedHint ?? allowed.join(', '))}`)
+            }
+        } else {
+            positional.push(arg)
+        }
+        i++
+    }
+
+    // enrich with defaults
+    /** @type {import('./typedefs').config.cli.ParameterSchema} */
+    const defaults = Object.entries(schema)
+        .filter(e => !!e[1].default)
+        .reduce((dict, [k, v]) => {
+            // @ts-expect-error - can't infer type of initial {}
+            dict[camelToSnake(k)] = { value: v.default, isDefault: true }
+            return dict
+        }, {})
+
+    const namedWithDefaults = {...defaults, ...named}
 
-const flags = {
+    // apply postprocessing
+    for (const [key, {value}] of Object.entries(namedWithDefaults)) {
+        const { postprocess } = schema[key]
+        if (typeof postprocess === 'function') {
+            namedWithDefaults[key].value = postprocess(value)
+        }
+    }
+
+    return {
+        named: namedWithDefaults,
+        positional,
+    }
+}
+
+/**
+ * Adds CLI parameters to the configuration object.
+ * Precedence: CLI > env > default.
+ * @param {ReturnType<parseCommandlineArgs>['named']} params - CLI parameters.
+ */
+const addCLIParamsToConfig = params => {
+    for (const [key, value] of Object.entries(params)) {
+        if (!value.isDefault || Object.hasOwn(configuration, key)) {
+            configuration[key] = value.value
+        }
+    }
+}
+
+const flags = enrichFlagSchema({
     outputDirectory: {
         desc: 'Root directory to write the generated files to.',
         default: './',
@@ -30,11 +157,24 @@ const flags = {
         allowedHint: Object.keys(lls).join(' | '),  // FIXME: remove once old levels are faded out
         defaultHint: _keyFor(lls.ERROR),
         default: cds?.env?.log?.levels?.['cds-typer'] ?? _keyFor(lls.ERROR),
+        postprocess: level => {
+            const newLogLevel = deprecated[level]
+            if (newLogLevel) {
+                console.warn(`deprecated log level '${level}', use '${newLogLevel}' instead (changing this automatically for now).`)
+                return newLogLevel
+            }
+            return level
+        }
     },
     jsConfigPath: {
         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'
+        type: 'string',
+        postprocess: file => file && !file.endsWith('jsconfig.json') ? path.join(file, 'jsconfig.json') : path
     },
+    useEntitiesProxy: parameterTypes.boolean({
+        desc: `If set to true the 'cds.entities' exports in the generated 'index.js'${EOL}files will be wrapped in 'Proxy' objects\nso static import/require calls can be used everywhere.${EOL}${EOL}WARNING: entity properties can still only be accessed after${EOL}'cds.entities' has been loaded`,
+        default: 'false'
+    }),
     version: {
         desc: 'Prints the version of this tool.'
     },
@@ -43,17 +183,15 @@ const flags = {
         allowed: ['flat', 'structured'],
         default: 'structured'
     },
-    propertiesOptional: {
+    propertiesOptional: parameterTypes.boolean({
         desc: `If set to true, properties in entities are${EOL}always generated as optional (a?: T).`,
-        allowed: ['true', 'false'],
         default: 'true'
-    },
-    IEEE754Compatible: {
+    }),
+    IEEE754Compatible: parameterTypes.boolean({
         desc: `If set to true, floating point properties are generated${EOL}as IEEE754 compatible '(number | string)' instead of 'number'.`,
-        allowed: ['true', 'false'],
         default: 'false'
-    }
-}
+    })
+})
 
 const hint = () => 'Missing or invalid parameter(s). Call with --help for more details.'
 /**
@@ -69,19 +207,22 @@ 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)
+            flags.keys
                 .sort(([a], [b]) => a.localeCompare(b))
-                .map(([key, value]) => {
+                .map(key => {
+                    const value = flags[key]
                     let s = indent(`--${key}`, '  ')
-                    // @ts-expect-error - not going to check presence of each property. Same for the following expect-errors.
+                    const snake = camelToSnake(key)
+                    if (key !== snake) s += EOL + indent(`--${snake}`, '  ')
+                    // ts-expect-error - not going to check presence of each property. Same for the following expect-errors.
                     if (value.allowedHint) s += ` ${value.allowedHint}`
-                    // @ts-expect-error
+                    // ts-expect-error
                     else if (value.allowed) s += `: <${value.allowed.join(' | ')}>`
                     else if ('type' in value && value.type) s += `: <${value.type}>`
-                    // @ts-expect-error
+                    // ts-expect-error
                     if (value.defaultHint || value.default) {
                         s += EOL
-                        // @ts-expect-error
+                        // ts-expect-error
                         s += indent(`(default: ${value.defaultHint ?? value.default})`, '    ')
                     }
                     s += `${EOL2}${indent(value.desc, '    ')}`
@@ -91,7 +232,9 @@ const help = () => `SYNOPSIS${EOL2}` +
 
 const version = () => require('../package.json').version
 
-const main = async (/** @type {any} */ args) => {
+const prepareParameters = (/** @type {any[]} */ argv) => {
+    const args = parseCommandlineArgs(argv, flags)
+
     if ('help' in args.named) {
         console.log(help())
         process.exit(0)
@@ -104,26 +247,21 @@ const main = async (/** @type {any} */ args) => {
         console.log(hint())
         process.exit(1)
     }
-    if (args.named.jsConfigPath && !args.named.jsConfigPath.endsWith('jsconfig.json')) {
-        args.named.jsConfigPath = path.join(args.named.jsConfigPath, 'jsconfig.json')
-    }
-    const newLogLevel = deprecated[args.named.logLevel]
-    if (newLogLevel) {
-        console.warn(`deprecated log level '${args.named.logLevel}', use '${newLogLevel}' instead (changing this automatically for now).`)
-        args.named.logLevel = newLogLevel
-    }
 
-    compileFromFile(args.positional, {
-        // temporary fix until rootDir is faded out
-        outputDirectory: [args.named.outputDirectory, args.named.rootDir].find(d => d !== './') ?? './',
-        logLevel: args.named.logLevel,
-        jsConfigPath: args.named.jsConfigPath,
-        inlineDeclarations: args.named.inlineDeclarations,
-        propertiesOptional: args.named.propertiesOptional === 'true',
-        IEEE754Compatible: args.named.IEEE754Compatible === 'true'
-    })
+    addCLIParamsToConfig(args.named)
+    return args
+}
+
+const main = async (/** @type {any[]} */ argv) => {
+    const { positional } = prepareParameters(argv)
+    compileFromFile(positional)
 }
 
 if (require.main === module) {
-    main(parseCommandlineArgs(process.argv.slice(2), flags))
+    main(process.argv.slice(2))
+}
+
+module.exports = {
+    flags,
+    prepareParameters
 }

package/lib/compile.js

@@ -7,10 +7,7 @@ const util = require('./util')
 const { writeout } = require('./file')
 const { Visitor } = require('./visitor')
 const { LOG, setLevel } = require('./logging')
-
-/**
- * @typedef {import('./typedefs').visitor.CompileParameters} CompileParameters
- */
+const { configuration } = require('./config')
 
 /**
  * Writes the accompanying jsconfig.json file to the specified paths.
@@ -40,31 +37,28 @@ const writeJsConfig = path => {
 /**
  * Compiles a CSN object to Typescript types.
  * @param {{xtended: import('./typedefs').resolver.CSN, inferred: import('./typedefs').resolver.CSN}} csn - csn tuple
- * @param {CompileParameters} parameters - path to root directory for all generated files, min log level
  */
-const compileFromCSN = async (csn, parameters) => {
-    const envSettings = cds.env?.typer ?? {}
-    parameters = { ...envSettings, ...parameters }
-    setLevel(parameters.logLevel)
-    if (parameters.jsConfigPath) {
-        writeJsConfig(parameters.jsConfigPath)
+const compileFromCSN = async csn => {
+
+    setLevel(configuration.logLevel)
+    if (configuration.jsConfigPath) {
+        writeJsConfig(configuration.jsConfigPath)
     }
     return writeout(
-        parameters.outputDirectory,
-        Object.values(new Visitor(csn, parameters).getWriteoutFiles())
+        configuration.outputDirectory,
+        Object.values(new Visitor(csn).getWriteoutFiles())
     )
 }
 
 /**
  * Compiles a .cds file to Typescript types.
  * @param {string | string[]} inputFile - path to input .cds file
- * @param {CompileParameters} parameters - path to root directory for all generated files, min log level, etc.
  */
-const compileFromFile = async (inputFile, parameters) => {
+const compileFromFile = async inputFile => {
     const paths = typeof inputFile === 'string' ? normalize(inputFile) : inputFile.map(f => normalize(f))
     const xtended = await cds.linked(await cds.load(paths, { docs: true, flavor: 'xtended' }))
     const inferred = await cds.linked(await cds.load(paths, { docs: true }))
-    return compileFromCSN({xtended, inferred}, parameters)
+    return compileFromCSN({xtended, inferred})
 }
 
 module.exports = {

package/lib/components/basedefs.js

@@ -42,6 +42,12 @@ export type DeepRequired<T> = {
     [K in keyof T]: DeepRequired<T[K]>
 } & Exclude<Required<T>, null>;
 
+const key = Symbol('key')  // to avoid .key showing up in IDE's auto-completion
+export type Key<T> = T & {[key]?: true}
+
+export type KeysOf<T> = {
+  [K in keyof T as NonNullable<T[K]> extends Key<unknown> ? K : never]-?: Key<{}>  // T[K] 
+}
 
 /**
  * Dates and timestamps are strings during runtime, so cds-typer represents them as such.

package/lib/components/enum.js

@@ -22,7 +22,7 @@ const stringifyEnumType = kvs => [...uniqueValues(kvs)].join(' | ')
 /**
  * @param {string} key - the key of the enum
  * @param {any} value - the value of the enum
- * @param {string | import('@sap/cds').ref} enumType - the type of the enum
+ * @param {string | import('../typedefs').resolver.ref} enumType - the type of the enum
  */
 const enumVal = (key, value, enumType) => enumType === 'cds.String' ? JSON.stringify(`${value ?? key}`) : value
 
@@ -50,10 +50,12 @@ const enumVal = (key, value, enumType) => enumType === 'cds.String' ? JSON.strin
  * @param {string} name - local name of the enum, i.e. the name under which it should be created in the .ts file
  * @param {[string, string][]} kvs - list of key-value pairs
  * @param {object} options - options for printing the enum
+ * @param {string[]} doc - the enum docs
  */
-function printEnum(buffer, name, kvs, options = {}) {
+function printEnum(buffer, name, kvs, options = {}, doc=[]) {
     const opts = {...{export: true}, ...options}
     buffer.add('// enum')
+    if (opts.export) doc.forEach(d => { buffer.add(d) })
     buffer.addIndentedBlock(`${opts.export ? 'export ' : ''}const ${name} = {`, () =>
         kvs.forEach(([k, v]) => { buffer.add(`${normalise(k)}: ${v},`) })
     , '} as const;')

package/lib/components/inline.js

@@ -1,3 +1,4 @@
+const { configuration } = require('../config')
 const { SourceFile, Buffer } = require('../file')
 const { normalise } = require('./identifier')
 const { docify } = require('./wrappers')
@@ -94,7 +95,7 @@ class InlineDeclarationResolver {
      * @returns {'?:'|':'}
      */
     getPropertyTypeSeparator() {
-        return this.visitor.options.propertiesOptional ? '?:' : ':'
+        return configuration.propertiesOptional ? '?:' : ':'
     }
 
     /**

package/lib/components/javascript.js

@@ -0,0 +1,28 @@
+/* eslint-disable no-undef */
+// this function will be stringified as part of the generated types and is not supposed to be used internally
+// @ts-nocheck
+const proxyAccessFunction = function (fqParts, opts = {}) {
+    const { target, customProps } = { target: {}, customProps: [], ...opts }
+    const fq = fqParts.filter(p => !!p).join('.')
+    return new Proxy(target, {
+        get: function (target, prop) {
+            if (cds.entities) {
+                target.__proto__ = cds.entities(fqParts[0])[fqParts[1]]
+                // overwrite/simplify getter after cds.entities is accessible
+                this.get = (target, prop) => target[prop]
+                return target[prop]
+            }
+            // we already know the name so we skip the cds.entities proxy access
+            if (prop === 'name') return fq
+            // custom properties access on 'target' as well as cached _entity property access goes here
+            if (Object.hasOwn(target, prop)) return target[prop]
+            // inline enums have to be caught here for first time access, as they do not exist on the entity
+            if (customProps.includes(prop)) return target[prop]
+            // last but not least we pass the property access to cds.entities
+            throw new Error(`Property ${prop} does not exist on entity '${fq}' or cds.entities is not yet defined. Ensure the CDS runtime is fully booted before accessing properties.`)
+        }
+    })
+}.toString()
+/* eslint-enable no-undef */
+
+module.exports = { proxyAccessFunction }

package/lib/components/wrappers.js

@@ -3,6 +3,20 @@
 // this was derived from baseDefinitions before, but caused a circular dependency
 const base = '__'
 
+/**
+ * Wraps type into the Key type.
+ * @param {string} t - the type name.
+ * @returns {string}
+ */
+const createKey = t => `${base}.Key<${t}>`
+
+/**
+ * Wraps type into KeysOf type.
+ * @param {string} t - the type name.
+ * @returns {string}
+ */
+const createKeysOf = t => `${base}.KeysOf<${t}>`
+
 /**
  * Wraps type into association to scalar.
  * @param {string} t - the singular type name.
@@ -45,6 +59,24 @@ const createArrayOf = t => `Array<${t}>`
  */
 const createObjectOf = t => `{${t}}`
 
+/**
+ * Wraps types into a union type string
+ * @param {string[]} types - an array of types
+ * @returns {string}
+ */
+const createUnionOf = (...types) => types.join(' | ')
+
+/**
+ * Wraps type into a promise
+ * @param {string} t - the type to wrap.
+ * @returns {string}
+ * @example
+ * ```js
+ * createPromiseOf('string') // -> 'Promise<string>'
+ * ```
+ */
+const createPromiseOf = t => `Promise<${t}>`
+
 /**
  * Wraps type into a deep require (removes all posibilities of undefined recursively).
  * @param {string} t - the singular type name.
@@ -59,13 +91,20 @@ const deepRequire = (t, lookup = '') => `${base}.DeepRequired<${t}>${lookup}`
  * @returns {string[]} an array of lines wrapped in doc format. The result is not
  *          concatenated to be properly indented by `buffer.add(...)`.
  */
-const docify = doc => doc
-    ? ['/**'].concat(doc.split('\n').map(line => `* ${line}`)).concat(['*/'])
-    : []
+const docify = doc => {
+    if (!doc) return []
+    const lines = doc.split(/\r?\n/).map(l => l.trim().replaceAll('*/', '*\\/')) // mask any */ with *\/
+    if (lines.length === 1) return [`/** ${lines[0]} */`] // one-line doc
+    return ['/**'].concat(lines.map(line => `* ${line}`)).concat(['*/'])
+}
 
 module.exports = {
     createArrayOf,
+    createKey,
+    createKeysOf,
     createObjectOf,
+    createPromiseOf,
+    createUnionOf,
     createToOneAssociation,
     createToManyAssociation,
     createCompositionOfOne,