@cap-js/cds-typer 0.38.0 → 0.39.0

package/lib/cli.js

@@ -213,7 +213,11 @@ const flags = enrichFlagSchema({
         desc: `How to cache typer runs.${EOL}none: fully run cds-typer whenever it is called${EOL}blake2s256: only run if the blake2s256-hash of the model has changed. Hash is stored in a file between runs.`,
         allowed: ['none', 'blake2s256'],
         default: 'none'
-    }
+    },
+    brandedPrimitiveTypes: parameterTypes.boolean({
+        desc: `If set to true, generated primitive types will be branded to prevent accidental mixing of types with the same underlying primitive.${EOL}E.g., type CustomerID = string & { __brand: 'CustomerID' }`,
+        default: 'false'
+    })
 })
 
 const hint = () => 'Missing or invalid parameter(s). Call with --help for more details.'

package/lib/components/class.js

@@ -1,5 +1,5 @@
 /**
- * Create a class member with given modifiers in the right order.
+ * Create a class member with given modifiers in the right order and returns the resulting string.
  * @param {object} options - options
  * @param {string} options.name - the name of the member
  * @param {string} [options.type] - the type of the member

package/lib/components/enum.js

@@ -1,4 +1,4 @@
-const { normalise } = require('./identifier')
+const { enquote } = require('./identifier')
 
 /**
  * Extracts all unique values from a list of enum key-value pairs.
@@ -57,7 +57,7 @@ function printEnum(buffer, name, kvs, options = {}, doc=[]) {
     buffer.add('// enum')
     if (opts.export) buffer.add(doc)
     buffer.addIndentedBlock(`${opts.export ? 'export ' : ''}const ${name} = {`, () =>
-        kvs.forEach(([k, v]) => { buffer.add(`${normalise(k)}: ${v},`) })
+        kvs.forEach(([k, v]) => { buffer.add(`${enquote(k)}: ${v},`) })
     , '} as const;')
     buffer.add(`${opts.export ? 'export ' : ''}type ${name} = ${stringifyEnumType(kvs)}`)
     buffer.blankLine()
@@ -126,7 +126,7 @@ const isInlineEnumType = (element, csn) => element.enum
  */
 const stringifyEnumImplementation = (name, kvs, jsp) => jsp.printExport(
     name,
-    `{ ${kvs.map(([k,v]) => `${normalise(k)}: ${v}`).join(', ')} }`,
+    `{ ${kvs.map(([k,v]) => `${enquote(k)}: ${v}`).join(', ')} }`,
     { coalesce: true })
 
 

package/lib/components/identifier.js

@@ -1,12 +1,84 @@
+const { createHash } = require('node:crypto')
+const { LOG } = require('../logging')
+
+// https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Lexical_grammar
+const JS_RESERVED = new Set([
+    'abstract',
+    'arguments',
+    'await',
+    'boolean',
+    'break',
+    'byte',
+    'case',
+    'catch',
+    'char',
+    'class',
+    'const',
+    'continue',
+    'debugger',
+    'default',
+    'delete',
+    'do',
+    'double',
+    'else',
+    'enum',
+    'eval',
+    'export',
+    'extends',
+    'false',
+    'final',
+    'finally',
+    'float',
+    'for',
+    'function',
+    'goto',
+    'if',
+    'implements',
+    'import',
+    'in',
+    'instanceof',
+    'int',
+    'interface',
+    'let',
+    'long',
+    'native',
+    'new',
+    'null',
+    'object',
+    'package',
+    'private',
+    'protected',
+    'public',
+    'return',
+    'short',
+    'static',
+    'super',
+    'switch',
+    'synchronized',
+    'this',
+    'throw',
+    'throws',
+    'transient',
+    'true',
+    'try',
+    'typeof',
+    'var',
+    'void',
+    'volatile',
+    'while',
+    'with',
+    'yield',
+])
+
 const isValidIdent = /^[_$a-zA-Z][$\w]*$/
 
 /**
- * Normalises an identifier to a valid JavaScript identifier.
+ * Enquotes an identifier to a valid JavaScript identifier.
  * I.e. either the identifier itself or a quoted string.
- * @param {string} ident - the identifier to normalise
- * @returns {string} the normalised identifier
+ * @param {string} ident - the identifier to enquote
+ * @returns {string} the enquoted identifier
  */
-const normalise = ident => ident && !isValidIdent.test(ident)
+const enquote = ident => ident && !isValidIdent.test(ident)
     ? `"${ident}"`
     : ident
 
@@ -17,7 +89,111 @@ const normalise = ident => ident && !isValidIdent.test(ident)
  */
 const last = ident => ident.split('.').at(-1) ?? ident
 
+/**
+ * Normalises the name of a service or entity.
+ * This function is suited to normalise class names.
+ * To handle properties with exotic characters, see {@link enquote}.
+ * @param {string} name - name of the entity or fq thereof.
+ */
+const normalise = name => {
+    const namespace = name.split('.').slice(0, -1)
+    const unqualified = /** @type {string} */ (name.split('.').at(-1))
+    let normalised = unqualified.match(/^[a-zA-Z]+\w*$/)
+        ? unqualified
+        : `__${unqualified.replaceAll(/[^a-zA-Z0-9]/g, '_')}`
+    if (/^_+$/.test(normalised)) {
+        // very rare case when the entire name consists of non-alphanumeric characters (Kanji, etc)
+        // That would leave us with just underscores,
+        // which has high potential of colliding with other such names
+        // -> fall back to hash. Hashes still bear a small risk of collision, but much lower.
+        // Prepend underscore to avoid problems with hashes starting with a digit.
+        normalised = '_' + createHash('md5').update(name).digest('hex')
+    }
+    if (JS_RESERVED.has(normalised)) {
+        normalised = `__${name}`
+    }
+    return {
+        original: name,
+        unqualified,
+        normalised: [...namespace, normalised].filter(Boolean).join('.'),
+        wasNormalised: unqualified !== normalised
+    }
+}
+
+class Identifier {
+    /** @type {string} */
+    plain
+    /** @type {string[]} */
+    scope = []
+    /** @type {Identifier | null} */
+    #from = null
+    /** @type {Identifier | undefined} */
+    #normalised
+    /** @type {boolean} */
+    #sealed = false
+
+    /**
+     * @returns whether normalisation was applied. This does not mean the identifier has changed!
+     * If it did not require normalisation, this will be true regardless.
+     * {@link Identifier#isChangedFromNormalisation} tells whether the identifier actually changed.
+     */
+    get isNormalised () {
+        return this.#sealed || Boolean(this.#from)
+    }
+
+    /**
+     * @returns whether the identifier actually changed due to normalisation.
+     */
+    get isChangedFromNormalisation () {
+        return this.isNormalised && this.#from !== null && this.plain !== this.#from.plain
+    }
+
+    /**
+     * @returns {Identifier}
+     */
+    get normalised () {
+        return this.isNormalised
+            ? this
+            : this.#normalised ??= new Identifier(normalise(this.plain).normalised, this.scope, this)
+    }
+
+    get scoped () {
+        return [...this.scope, this.plain].join('.')
+    }
+
+    /**
+     * @param {string | Identifier} name - the inflected name
+     * @param {string[]} [scope] - the scope of the identifier
+     * @param {Identifier | null} [from] - the original inflection if this is a normalised one
+     * @param {boolean} [sealed] - whether the identifier should be sealed to prevent further normalisation (e.g., for inline declarations).
+     *  Setting this to true also prevents automatic scope splitting for identifiers with dots.
+     * @example
+     * ```js
+     * new Identifier('Books.texts')  // name: 'texts', scope: ['Books']
+     * new Identifier('text', ['Books']) // name: 'text', scope: ['Books']
+     * new Identifier(new Identifier('Books.text'), ['Books']) // name: 'text', scope: ['Books'] -> as explicit scope is passed, the original name is retained as is!
+     * new Identifier('{x: Books.text}', null, true) // name: '{x: Books.text}', scope: [] -> as sealed is true, the original name is retained as is, and no scope splitting is applied, even though there are dots in the name!
+     * ```
+     */
+    constructor (name, scope = [], from = null, sealed = false) {
+        this.plain = typeof name === 'string' ? name : name.plain
+        this.scope = scope
+        this.#from = from
+        this.#sealed = sealed
+        if (from && name !== from.plain) {
+            LOG.debug(`Identifier '${from.plain}' was normalised to '${name}'.`)
+        }
+        if (this.plain.includes('.') && !this.scope.length && !sealed) {
+            const parts = this.plain.split('.')
+            this.plain = /** @type {string} */ (parts.at(-1))
+            this.scope = parts.slice(0, -1)
+            LOG.debug(`Identifier with dots without explicitly specified scope detected. Split into scope '${this.scope.join('.')}' and name '${this.plain}'.`)
+        }
+    }
+}
+
 module.exports = {
-    normalise,
-    last
-}
+    enquote,
+    last,
+    Identifier,
+}

package/lib/components/inline.js

@@ -1,6 +1,6 @@
 const { configuration } = require('../config')
 const { SourceFile, Buffer } = require('../file')
-const { normalise } = require('./identifier')
+const { enquote } = require('./identifier')
 const { docify } = require('../printers/wrappers')
 
 /** @typedef {import('../resolution/resolver').TypeResolveInfo} TypeResolveInfo */
@@ -88,7 +88,13 @@ class InlineDeclarationResolver {
         const type = this.visitor.resolver.resolveAndRequire(element, file, resolverOptions)
         this.depth--
         if (this.depth === 0) {
-            this.printInlineType({fq: name, type, buffer, modifiers})
+            // For builtin types (Composition, Association, etc.), just print the property directly
+            // since the typeName is already fully resolved and doesn't need further flattening
+            if (type.typeInfo.isBuiltin) {
+                buffer.add(`${this.stringifyModifiers(modifiers)}${enquote(name)}${this.getPropertyTypeSeparator()} ${this.getPropertyDatatype(type)}`)
+            } else {
+                this.printInlineType({fq: name, type, buffer, modifiers})
+            }
         }
         return type
     }
@@ -193,7 +199,7 @@ class FlatInlineDeclarationResolver extends InlineDeclarationResolver {
             ? Object.entries(type.typeInfo.structuredType).map(
                 ([k,v]) => this.flatten({prefix: `${this.prefix(prefix)}${k}`, type: v, modifiers})  // for flat we pass the modifiers!
             ).flat()
-            : [`${this.stringifyModifiers(modifiers)}${normalise(prefix)}${this.getPropertyTypeSeparator()} ${this.getPropertyDatatype(type)}`]
+            : [`${this.stringifyModifiers(modifiers)}${enquote(prefix)}${this.getPropertyTypeSeparator()} ${this.getPropertyDatatype(type)}`]
     }
 
     /**
@@ -254,8 +260,11 @@ class StructuredInlineDeclarationResolver extends InlineDeclarationResolver {
         this.printDepth++
         const lineEnding = this.printDepth > 1 ? ',' : statementEnd
         if (type.typeInfo.structuredType) {
-            const prefix = fq ? `${this.stringifyModifiers(modifiers)}${normalise(fq)}${this.getPropertyTypeSeparator()}`: ''
-            buffer.add(`${prefix} {`)
+            // When fq is empty, we're generating a bare struct type without a property name
+            // (used for inline declarations in compositions/associations)
+            buffer.add(fq
+                ? `${this.stringifyModifiers(modifiers)}${enquote(fq)}${this.getPropertyTypeSeparator()} {`
+                : '{')
             buffer.indent()
             for (const [n, t] of Object.entries(type.typeInfo.structuredType)) {
                 this.flatten({fq: n, type: t, buffer})
@@ -263,7 +272,7 @@ class StructuredInlineDeclarationResolver extends InlineDeclarationResolver {
             buffer.outdent()
             buffer.add(`}${this.getPropertyDatatype(type, '')}${lineEnding}`)
         } else {
-            buffer.add(`${this.stringifyModifiers(modifiers)}${normalise(fq)}${this.getPropertyTypeSeparator()} ${this.getPropertyDatatype(type)}${lineEnding}`)
+            buffer.add(`${this.stringifyModifiers(modifiers)}${enquote(fq)}${this.getPropertyTypeSeparator()} ${this.getPropertyDatatype(type)}${lineEnding}`)
         }
         this.printDepth--
         return buffer

package/lib/file.js

@@ -4,10 +4,10 @@ const fs = require('fs').promises
 const path = require('path')
 const { readFileSync } = require('fs')
 const { printEnum, propertyToInlineEnumName, stringifyEnumImplementation } = require('./components/enum')
-const { normalise } = require('./components/identifier')
+const { enquote } = require('./components/identifier')
 const { empty } = require('./components/typescript')
 const { proxyAccessFunction } = require('./components/javascript')
-const { createObjectOf, stringIdent } = require('./printers/wrappers')
+const { createObjectOf, stringIdent, docify } = require('./printers/wrappers')
 const { configuration } = require('./config')
 const { CJSPrinter, ESMPrinter } = require('./printers/javascript')
 
@@ -142,7 +142,7 @@ class SourceFile extends File {
         this.classNames = {} // for .js file
         /** @type {{[key: string]: any}} */
         this.typeNames = {}
-        /** @type {[string, string, string][]} */
+        /** @type {{singular: string, plural: string, original: string, isNormalised: boolean}[]} */
         this.inflections = []
         /** @type {{ buffer: Buffer, names: string[]}} */
         this.services = { buffer: new Buffer(), names: [] }
@@ -190,21 +190,21 @@ class SourceFile extends File {
      */
     static stringifyLambda({name, parameters=[], returns='any', kind, initialiser, self='never', isStatic=false, callStyles={positional:true, named:true}, doc}) {
         let docStr = doc?.length ? doc.join('\n')+'\n' : ''
-        const parameterTypes = parameters.map(({name, modifier, type, doc}) => `${doc?'\n'+doc:''}${normalise(name)}${modifier}: ${type}`).join(', ')
+        const parameterTypes = parameters.map(({name, modifier, type, doc}) => `${doc?'\n'+doc:''}${enquote(name)}${modifier}: ${type}`).join(', ')
         const parameterTypeAsObject = parameterTypes.length
             ? createObjectOf(parameterTypes)
             : empty
         const callableSignatures = []
         if (callStyles.positional) {
-            const paramTypesPositional = parameters.map(({name, type, doc}) => `${doc?'\n'+doc:''}${normalise(name)}: ${type}`).join(', ') // must not include ? modifiers
+            const paramTypesPositional = parameters.map(({name, type, doc}) => `${doc?'\n'+doc:''}${enquote(name)}: ${type}`).join(', ') // must not include ? modifiers
             callableSignatures.push('// positional',`${docStr}(${paramTypesPositional}): ${returns}`) // docs shows up on action consumer side: `.action(...)`
         }
         if (callStyles.named) {
-            const parameterNames = createObjectOf(parameters.map(({name}) => normalise(name)).join(', '))
+            const parameterNames = createObjectOf(parameters.map(({name}) => enquote(name)).join(', '))
             callableSignatures.push('// named',`${docStr}(${parameterNames}: ${parameterTypeAsObject}): ${returns}`)
         }
         if (callableSignatures.length === 0) throw new Error('At least one call style must be specified')
-        let prefix = name ? `${normalise(name)}: `: ''
+        let prefix = name ? `${enquote(name)}: `: ''
         if (prefix && isStatic) {
             prefix = `static ${prefix}`
         }
@@ -222,13 +222,15 @@ class SourceFile extends File {
      * Adds a pair of singular and plural inflection.
      * These are later used to generate the singular -> plural
      * aliases in the index.js file.
-     * @param {string} singular - singular type without namespace.
-     * @param {string} plural - plural type without namespace
-     * @param {string} original - original entity name without namespace.
+     * @param {object} options - options
+     * @param {string} options.singular - singular type without namespace.
+     * @param {string} options.plural - plural type without namespace
+     * @param {string} options.original - original entity name without namespace.
      *        In many cases this will be the same as plural.
+     * @param {boolean} [options.isNormalised] - whether the passed names are already normalised.
      */
-    addInflection(singular, plural, original) {
-        this.inflections.push([singular, plural, original])
+    addInflection({singular, plural, original, isNormalised = false}) {
+        this.inflections.push({singular, plural, original, isNormalised})
     }
 
     /**
@@ -239,12 +241,22 @@ class SourceFile extends File {
      * @param {'function' | 'action'} kind - kind of the node
      * @param {string[]} doc - documentation for the function
      * @param {{positional?: boolean, named?: boolean}} callStyles - how the operation can be called
+     * @param {string} [originalName] - the original name before normalization, if different
      */
-    addOperation(name, parameters, returns, kind, doc, callStyles) {
+    addOperation(name, parameters, returns, kind, doc, callStyles, originalName) {
         // this.operations.buffer.add(`// ${kind}`)
         if (doc) this.operations.buffer.add(doc.join('\n')) // docs shows up on action provider side: `.on(action,...)`
         const [opener, content, closer] = SourceFile.stringifyLambda({name, parameters, returns, kind, doc, callStyles})
         this.operations.buffer.addIndentedBlock(`export declare const ${opener}`, content, closer)
+        // Add alias export if normalized name differs from original
+        if (originalName && originalName !== name) {
+            this.operations.buffer.add(docify([
+                ` This ${kind} can be accessed via:`,
+                ` - Named import: \`import { ${name} } from '...'\``,
+                ` - Aliased import: \`import { "${originalName}" as MyAlias } from '...'\`\n`
+            ]))
+            this.operations.buffer.add(`export { ${name} as "${originalName}" }`)
+        }
         this.operations.names.push(name)
     }
 
@@ -326,9 +338,8 @@ class SourceFile extends File {
         entityProxy.push(propertyName)
 
         // REVISIT: find a better way to do this???
-        const printEnumToBuffer = (/** @type {Buffer} */buffer) => printEnum(buffer, propertyToInlineEnumName(entityCleanName, propertyName), kvs, {export: false}, doc)
-
         if (buffer?.namespace) {
+            const printEnumToBuffer = (/** @type {Buffer} */buffer) => printEnum(buffer, propertyToInlineEnumName(entityCleanName, propertyName), kvs, {export: false}, doc)
             const tempBuffer = new Buffer()
             // we want to put the enums on class level
             tempBuffer.indent()
@@ -338,6 +349,9 @@ class SourceFile extends File {
             const [first,...rest] = buffer.parts
             buffer.parts = [first, ...tempBuffer.parts, ...rest]
         } else {
+            // top-level inline enums must be exported so they can be referenced cross-namespace
+            // (e.g. when a service projects an entity whose key has an inline enum type)
+            const printEnumToBuffer = (/** @type {Buffer} */buffer) => printEnum(buffer, propertyToInlineEnumName(entityCleanName, propertyName), kvs, {export: true}, doc)
             printEnumToBuffer(this.inlineEnums.buffer)
         }
     }
@@ -550,8 +564,8 @@ class SourceFile extends File {
             // sorting the entries based on the number of dots in their singular.
             // that makes sure we have defined all parent namespaces before adding subclasses to them e.g.:
             // "module.exports.Books" is defined before "module.exports.Books.text"
-                .sort(([a], [b]) => a.split('.').length - b.split('.').length)
-                .flatMap(([singular, plural, original]) => {
+                .sort(({singular:a}, {singular:b}) => a.split('.').length - b.split('.').length)
+                .flatMap(({singular, plural, original, isNormalised}) => {
                     const { singularRhs, pluralRhs } = this.#getEntityExportsRhs(singular, original)
 
                     const exports = [
@@ -565,8 +579,9 @@ class SourceFile extends File {
                     // FIXME: we currently produce at most 3 entries.
                     // This could be an issue when the user re-used the original name in a @singular/@plural annotation.
                     // Seems unlikely, but we have to eliminate the original entry if users start running into this.
-                    if (singular !== original) {
+                    if (singular !== original && !isNormalised) {
                         // do not do the is_singular spiel if the original name is used for the plural
+                        // or if we had to normalise the name, which would imply an invalid identifier we can not use anyway
                         const rhs = plural === original ? pluralRhs : singularRhs
                         exports.push(jsp.printExport(original, rhs))
                     }
@@ -592,21 +607,13 @@ class Buffer {
      * @param {string} indentation - indentation to use (two spaces by default)
      */
     constructor(indentation = '  ') {
-        /**
-         * @type {string[]}
-         */
+        /** @type {string[]} */
         this.parts = []
-        /**
-         * @type {string}
-         */
+        /** @type {string} */
         this.indentation = indentation
-        /**
-         * @type {string}
-         */
+        /** @type {string} */
         this.currentIndent = ''
-        /**
-         * @type {boolean}
-         */
+        /** @type {boolean} */
         this.closed = false
         /**
          * Required for inline enums of inline compositions or text entities

package/lib/printers/wrappers.js

@@ -105,6 +105,12 @@ const createIntersectionOf = (...types) => types.join(' & ')
  */
 const createPromiseOf = t => `globalThis.Promise<${t}>`
 
+/**
+ * Creates a branded type.
+ * @param {string} t - the type to brand.
+ */
+const createBrandedType = t => `{ __brand: '${t}' }`
+
 /**
  * Wraps type into a deep require (removes all posibilities of undefined recursively).
  * @param {string} t - the singular type name.
@@ -123,13 +129,16 @@ const unkey = t => `${base}.Unkey<${t}>`
 
 /**
  * Puts a passed string in docstring format.
- * @param {string | undefined} doc - raw string to docify. May contain linebreaks.
+ * @param {string | string[] | undefined} doc - raw string to docify.
+ *  Passing a string may contain linebreaks, which are used to split the doc into multiple lines.
+ *  Alternatively, an array of strings can be passed, where each string is a line in the doc.
  * @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 => {
     if (!doc) return []
-    const lines = doc.split(/\r?\n/).map(l => l.trim().replaceAll('*/', '*\\/')) // mask any */ with *\/
+    const lines = (Array.isArray(doc) ? doc : 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(['*/'])
 }
@@ -143,6 +152,7 @@ const stringIdent = s => `'${s}'`
 
 module.exports = {
     createArrayOf,
+    createBrandedType,
     createDraftOf,
     createDraftsOf,
     createKey,

package/lib/resolution/entity.js

@@ -46,7 +46,7 @@ class EntityInfo {
      */
     propertyAccess
 
-    /** @type {{singular: string, plural: string} | undefined} */
+    /** @type {import('./resolver').Inflection | undefined} */
     #inflection
 
     /** @type {import('./resolver').Resolver} */
@@ -150,22 +150,22 @@ class EntityRepository {
     #resolver
 
     /**
-     * @param {string} fq - fully qualified name of the entity
+     * @param {import('../components/identifier').Identifier |string} fq - fully qualified name of the entity
      * @returns {EntityInfo | null}
      */
     getByFq (fq) {
+        if (typeof fq !== 'string') fq = fq.plain
         if (this.#cache[fq] !== undefined) return this.#cache[fq]
-        this.#cache[fq] = this.#resolver.isPartOfModel(fq)
+        return this.#cache[fq] = this.#resolver.isPartOfModel(fq)
             ? new EntityInfo(fq, this, this.#resolver)
             : null
-        return this.#cache[fq]
     }
 
     /**
      * Convenience for getByFq when you are 100% sure the entity exists.
      * Serves to eliminate cumbersome null-handling where you know it's not necessary.
      * For example when fq is derived from a reference to another entity.
-     * @param {string} fq - fully qualified name of the entity
+     * @param {import('../components/identifier').Identifier | string} fq - fully qualified name of the entity
      * @returns {EntityInfo}
      */
     getByFqOrThrow(fq) {
@@ -195,7 +195,7 @@ class EntityRepository {
 function asIdentifier ({info, wrapper = undefined, relative = undefined}) {
     const name = isType(info.csn)
         ? info.entityName
-        : info.inflection.singular
+        : info.inflection.singular?.plain
 
     const wrapped = typeof wrapper === 'function'
         ? wrapper(name)