@cap-js/cds-typer 0.24.0 → 0.26.0

package/lib/file.js

@@ -6,13 +6,22 @@ const { readFileSync } = require('fs')
 const { printEnum, propertyToInlineEnumName, stringifyEnumImplementation } = require('./components/enum')
 const { normalise } = require('./components/identifier')
 const { empty } = require('./components/typescript')
+const { proxyAccessFunction } = require('./components/javascript')
 const { createObjectOf } = require('./components/wrappers')
 
 const AUTO_GEN_NOTE = '// This is an automatically generated file. Please do not change its contents manually!'
 
 /** @typedef {import('./typedefs').file.Namespace} Namespace */
+/** @typedef {import('./typedefs').file.FileOptions} FileOptions */
 
 class File {
+    /**
+     * The Path for this library file, which is constructed from its namespace.
+     * @type {Path}
+     */
+    // @ts-expect-error - not initialised, but will be done in subclasses (can't make File abstract in JS)
+    path
+
     /**
      * Creates one string from the buffers representing the type definitions.
      * @returns {string} complete file contents.
@@ -42,6 +51,9 @@ class Library extends File {
         return this.contents
     }
 
+    /**
+     * @param {string} file - path to the file
+     */
     constructor(file) {
         super()
         this.contents = readFileSync(file, 'utf-8')
@@ -97,12 +109,14 @@ class Library extends File {
 class SourceFile extends File {
     /**
      * @param {string | Path} path - path to the file
+     * @param {FileOptions} [options] - options for file output
      */
-    constructor(path) {
+    constructor(path, options) {
         super()
+        this.options = options ?? { useEntitiesProxy: false }
         /** @type {Path} */
         this.path = path instanceof Path ? path : new Path(path.split('.'))
-        /** @type {object} */
+        /** @type {{[key:string]: any}} */
         this.imports = {}
         /** @type {Buffer} */
         this.preamble = new Buffer()
@@ -110,7 +124,7 @@ class SourceFile extends File {
         this.events = { buffer: new Buffer(), fqs: []}
         /** @type {Buffer} */
         this.types = new Buffer()
-        /** @type {{ buffer: Buffer, data: {kvs: [string[]], name: string, fq: string, property?: string}[]}} */
+        /** @type {{ buffer: Buffer, data: {kvs: [string, string][], name: string, fq: string, property?: string}[]}} */
         this.enums = { buffer: new Buffer(), data: [] }
         /** @type {{ buffer: Buffer }} */
         this.inlineEnums = { buffer: new Buffer() }
@@ -130,44 +144,64 @@ class SourceFile extends File {
         this.inflections = []
         /** @type {{ buffer: Buffer, names: string[]}} */
         this.services = { buffer: new Buffer(), names: [] }
+        /** @type {Record<string,string[]>} */
+        this.entityProxies = {}
     }
 
     /**
      * Stringifies a lambda expression.
-     * @param {{name: string, parameters: [string, string][], returns: string, initialiser: string}} param - name, parameters, return type, and initialiser expression
-     * @returns {string} - the stringified lambda
+     * @param {object} options - options
+     * @param {string} options.name - name of the lambda
+     * @param {import('./typedefs').visitor.ParamInfo[]} [options.parameters] - list of parameters, passed as [name, modifier, type, doc] pairs
+     * @param {string} [options.returns] - the return type of the function
+     * @param {'action' | 'function'} options.kind - kind of the lambda
+     * @param {string} [options.initialiser] - the initialiser expression
+     * @param {boolean} [options.isStatic] - whether the lambda is static
+     * @param {{positional?: boolean, named?: boolean}} [options.callStyles] - whether to generate positional and/or named call styles
+     * @param {string[]?} [options.doc] - documentation for the operation
+     * @returns {string} the stringified lambda
      * @example
      * ```js
      * // note: these samples are actually simplified! See below.
-     * stringifyLambda({parameters: [['p','T']]})  // f: { (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, ...  }
+     * stringifyLambda({parameters: [['p','','T']]})  // f: { (p: T): any, ... }
+     * stringifyLambda({name: 'f', parameters: [{name:'p',type:'T'}]})  // f: { (p: T) => any, ...  }
+     * stringifyLambda({name: 'f', parameters: [{name:'p',modifier:'?',type:'T',doc:'/** doc *\/'}], returns: 'number'})  // /** doc *\/f?: { (p: T) => number, ...  }
+     * stringifyLambda({name: 'f', parameters: [{name:'p',type:'T'}], returns: 'number', initialiser: '_ => 42'})  // f?: { (p: T): string = _ => 42, ...  }
      * ```
      *
-     * The generated string will not be just the signature of the function. Instead, it will be an object offering a callable signature.
+     * The generated string will not be just the signature of the function. Instead, it will be an object offering callable signature(s).
      * On top of that, it will also expose a property `__parameters`, which is an object reflecting the functions parameters.
      * The reason for this is that the CDS runtime actually treats the function parameters as a named object. This can not be rectified via
      * type magic, as parameter names do not exist on type level. So we can not use these names to reuse them as object properties.
      * Instead, we generate this utility object for the runtime to use:
      * @example
      * ```js
-     * stringifyLambda({name: 'f', parameters: [['p','T']], returns: 'number'})  // { (p: T): number, __parameters: { p: T } }
+     * stringifyLambda({name: 'f', parameters: [{name:'p',type:'T'}], returns: 'number'})  // { (p: T): number, __parameters: { p: T } }
      * ```
      */
-    static stringifyLambda({name, parameters=[], returns='any', initialiser, isStatic=false, kind}) {
-        const parameterTypes = parameters.map(([n, t]) => `${normalise(n)}: ${t}`).join(', ')
+    static stringifyLambda({name, parameters=[], returns='any', kind, initialiser, 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 parameterTypeAsObject = parameterTypes.length
             ? createObjectOf(parameterTypes)
             : empty
-        const callableSignature = `(${parameterTypes}): ${returns}`
+        const callableSignatures = []
+        if (callStyles.positional) {
+            const paramTypesPositional = parameters.map(({name, type, doc}) => `${doc?'\n'+doc:''}${normalise(name)}: ${type}`).join(', ') // must not include ? modifiers
+            callableSignatures.push(`// positional\n${docStr}(${paramTypesPositional}): ${returns}`) // docs shows up on action consumer side: `.action(...)`
+        }
+        if (callStyles.named) {
+            const parameterNames = createObjectOf(parameters.map(({name}) => normalise(name)).join(', '))
+            callableSignatures.push(`// named\n${docStr}(${parameterNames}: ${parameterTypeAsObject}): ${returns}`)
+        }
+        if (callableSignatures.length === 0) throw new Error('At least one call style must be specified')
         let prefix = name ? `${normalise(name)}: `: ''
         if (prefix && isStatic) {
             prefix = `static ${prefix}`
         }
         const kindDef = kind ? `, kind: '${kind}'` : ''
         const suffix = initialiser ? ` = ${initialiser}` : ''
-        const lambda = `{ ${callableSignature}, __parameters: ${parameterTypeAsObject}, __returns: ${returns}${kindDef}}`
+        const lambda = `{\n${callableSignatures.join('\n')}, \n// metadata (do not use)\n__parameters: ${parameterTypeAsObject}, __returns: ${returns}${kindDef}}`
         return prefix + lambda + suffix
     }
 
@@ -187,13 +221,16 @@ 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}} parameters - list of parameters, passed as [name, type] pairs
+     * @param {import('./typedefs').visitor.ParamInfo[]} parameters - list of parameters, passed as [name, modifier, type] tuple
      * @param {string} returns - the return type of the function
      * @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
      */
-    addOperation(name, parameters, returns, kind) {
-        //this.operations.buffer.add("// operation")
-        this.operations.buffer.add(`export declare const ${SourceFile.stringifyLambda({name, parameters, returns, kind})};`)
+    addOperation(name, parameters, returns, kind, doc, callStyles) {
+        // this.operations.buffer.add(`// ${kind}`)
+        if (doc) this.operations.buffer.add(doc.join('\n')) // docs shows up on action provider side: `.on(action,...)`
+        this.operations.buffer.add(`export declare const ${SourceFile.stringifyLambda({name, parameters, returns, kind, doc, callStyles})};`)
         this.operations.names.push(name)
     }
 
@@ -223,13 +260,11 @@ class SourceFile extends File {
      * @param {string} fq - fully qualified name of the enum (entity name within CSN)
      * @param {string} name - local name of the enum
      * @param {[string, string][]} kvs - list of key-value pairs
-     * @param {string?} _property - property to which the enum is attached.
-     *  If given, the enum is considered to be an inline definition of an enum.
-     *  If not, it is considered to be regular, named enum.
+     * @param {string[]} doc - the enum docs
      */
-    addEnum(fq, name, kvs, _property) {
+    addEnum(fq, name, kvs, doc) {
         this.enums.data.push({ name, fq, kvs })
-        printEnum(this.enums.buffer, name, kvs)
+        printEnum(this.enums.buffer, name, kvs, {}, doc)
     }
 
     /**
@@ -238,6 +273,7 @@ class SourceFile extends File {
      * @param {string} entityFqName - name of the entity the enum is attached to with namespace
      * @param {string} propertyName - property to which the enum is attached.
      * @param {[string, string][]} kvs - list of key-value pairs
+     * @param {string[]} doc - the enum docs
      *  If given, the enum is considered to be an inline definition of an enum.
      *  If not, it is considered to be regular, named enum.
      * @example
@@ -261,14 +297,16 @@ class SourceFile extends File {
      * }
      * ```
      */
-    addInlineEnum(entityCleanName, entityFqName, propertyName, kvs) {
+    addInlineEnum(entityCleanName, entityFqName, propertyName, kvs, doc=[]) {
         this.enums.data.push({
             name: `${entityCleanName}.${propertyName}`,
             property: propertyName,
             kvs,
             fq: `${entityCleanName}.${propertyName}`
         })
-        printEnum(this.inlineEnums.buffer, propertyToInlineEnumName(entityCleanName, propertyName), kvs, {export: false})
+        const entityProxy = this.entityProxies[entityCleanName] ?? (this.entityProxies[entityCleanName] = [])
+        entityProxy.push(propertyName)
+        printEnum(this.inlineEnums.buffer, propertyToInlineEnumName(entityCleanName, propertyName), kvs, {export: false}, doc)
     }
 
     /**
@@ -318,10 +356,14 @@ class SourceFile extends File {
      * @param {string} fq - fully qualified name of the enum
      * @param {string} clean - local name of the enum
      * @param {string} rhs - the right hand side of the assignment
+     * @param {boolean} exportValueLevel - whether to export the value level of the type (relevant to enums)
      */
-    addType(fq, clean, rhs) {
+    addType(fq, clean, rhs, exportValueLevel = false) {
         this.typeNames[clean] = fq
         this.types.add(`export type ${clean} = ${rhs};`)
+        if (exportValueLevel) {
+            this.types.add(`export const ${clean} = ${rhs};`)
+        }
     }
 
     /**
@@ -346,11 +388,16 @@ class SourceFile extends File {
      */
     getImports() {
         const buffer = new Buffer()
+        if (this.services.names.length) {
+            // currently only needed to extend cds.Service and would trigger unused-variable-errors in strict configs
+            buffer.add('import cds from \'@sap/cds\'') // TODO should go to visitor#printService, but can't express this as Path
+        }
         for (const imp of Object.values(this.imports)) {
             if (!imp.isCwd(this.path.asDirectory())) {
                 buffer.add(`import * as ${imp.asIdentifier()} from '${imp.asDirectory({relative: this.path.asDirectory()})}';`)
             }
         }
+        buffer.add('') // empty line after imports
         return buffer
     }
 
@@ -377,31 +424,92 @@ class SourceFile extends File {
             namespaces.join()  // needs to be after classes for possible declaration merging
         ].filter(Boolean).join('\n')
     }
+    #getEntityProxyFunctionExport() {
+        return `module.exports.createEntityProxy = ${proxyAccessFunction}`
+    }
+    /**
+     * Returns boilerplate code for `index.js` files
+     * - `useEntitiesProxy = true` -> import `createEntityProxy` function for entity proxy
+     * - `useEntitiesProxy = false` -> retrieve entities via `cds.entities(namespace)`
+     * @returns {string[]}
+     */
+    #getJSExportBoilerplate() {
+        const namespace = this.path.asNamespace()
 
+        const boilerplate = [AUTO_GEN_NOTE]
+        if (this.options.useEntitiesProxy) {
+            if (namespace === '_') {
+                boilerplate.push('const cds = require(\'@sap/cds\')', this.#getEntityProxyFunctionExport())
+            } else {
+                boilerplate.push(`const { createEntityProxy } = require('${new Path(['_']).asDirectory({relative: this.path.asDirectory()})}')`)
+            }
+        } else {
+            boilerplate.push(
+                'const cds = require(\'@sap/cds\')',
+                `const csn = cds.entities('${namespace}')`
+            )
+        }
+        return boilerplate
+    }
+    /**
+     * Returns RHS for entity `module.exports` assignments
+     * - `useEntitiesProxy = true` -> use function calls to create `Proxy` objects
+     * - `useEntitiesProxy = false` -> access entity from CSN directly
+     * @param {string} singular - singular name of entity
+     * @param {string} original - original name of entity
+     * @returns {{singularRhs: string, pluralRhs: string}}
+     */
+    #getEntityExportsRhs(singular, original) {
+        if (this.options.useEntitiesProxy) {
+            const namespace = this.path.asNamespace()
+            // determine the custom properties for the proxy function call
+            const customProps = this.entityProxies[singular] ?? []
+            let customPropsStr = customProps.length ? `, customProps: ${JSON.stringify(customProps)}` : ''
+
+            return {
+                singularRhs: `createEntityProxy(['${namespace}', '${original}'], { target: { is_singular: true }${customPropsStr} })`,
+                pluralRhs: `createEntityProxy(['${namespace}', '${original}'])`,
+            }
+        } else {
+            return {
+                singularRhs: `{ is_singular: true, __proto__: csn.${original} }`,
+                pluralRhs: `csn.${original}`
+            }
+        }
+    }
     toJSExports() {
-        return [AUTO_GEN_NOTE, 'const cds = require(\'@sap/cds\')', `const csn = cds.entities('${this.path.asNamespace()}')`] // boilerplate
+        return this.#getJSExportBoilerplate() // boilerplate
             .concat(
                 // FIXME: move stringification of service into own module
-                this.services.names.map(name => `module.exports = { name: '${name}' }`))  // there should be only one
+                this.services.names.flatMap(name => {
+                    const nameSimple = name.split('.').pop()
+                    return [
+                        '// service',
+                        `const ${nameSimple} = { name: '${name}' }`,
+                        `module.exports = ${nameSimple}`, // there should be only one and must be the first
+                        `module.exports.${nameSimple} = ${nameSimple}`
+                    ]
+                })
+            )
             .concat(this.inflections
             // 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]) => {
-                    const exports = [`module.exports.${singular} = { is_singular: true, __proto__: csn.${original} }`]
+                    const { singularRhs, pluralRhs } = this.#getEntityExportsRhs(singular, original)
+
+                    const exports = [`// ${original}`, `module.exports.${singular} = ${singularRhs}`]
                     if (!/Array<.*>/.test(plural) && plural !== original) {
                         // FIXME: this is a hack to support CDS types that will produce "Array<MyType>" as plural, which we do not want as export in the index.js files
-                        exports.push(`module.exports.${plural} = csn.${original}`)
+                        exports.push(`module.exports.${plural} = ${pluralRhs}`)
                     }
                     // 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) {
                         // do not do the is_singular spiel if the original name is used for the plural
-                        const rhs = plural === original
-                            ? `csn.${original}`
-                            : `{ is_singular: true, __proto__: csn.${original} }`
+                        const rhs = plural === original ? pluralRhs : singularRhs
                         exports.push(`module.exports.${original} = ${rhs}`)
                     }
                     return exports
@@ -438,6 +546,10 @@ class Buffer {
          * @type {string}
          */
         this.currentIndent = ''
+        /**
+         * @type {boolean}
+         */
+        this.closed = false
     }
 
     /**
@@ -483,7 +595,7 @@ class Buffer {
 
     /**
      * Adds an element to the buffer with one level of indent.
-     * @param {string | (() => void)} part - either a string or a function. If it is a string, it is added to the buffer.
+     * @param {string | string[] | (() => void)} part - either a string or a function. If it is a string, it is added to the buffer.
      * If not, it is expected to be a function that manipulates the buffer as a side effect.
      */
     addIndented(part) {
@@ -492,14 +604,16 @@ class Buffer {
             part()
         } else if (Array.isArray(part)) {
             part.forEach(p => { this.add(p) })
+        } else if (typeof part === 'string') {
+            this.add(part)
         }
         this.outdent()
     }
 
     /**
-     * Adds an element to a buffer with one level of indent and and opener and closer surrounding it.
+     * Adds an element to a buffer with one level of indent and opener and closer surrounding it.
      * @param {string} opener - the string to put before the indent
-     * @param {string} content - the content to indent (see {@link addIndented})
+     * @param {string | string[] | (() => void)} content - the content to indent (see {@link addIndented})
      * @param {string} closer - the string to put after the indent
      */
     addIndentedBlock(opener, content, closer) {
@@ -518,7 +632,7 @@ class Path {
      * @param {string[]} parts - parts of the path. 'a.b.c' -> ['a', 'b', 'c']
      * @param {string} kind - FIXME: currently unused
      */
-    constructor(parts, kind) {
+    constructor(parts, kind = '') {
         this.parts = parts
         this.kind = kind
     }
@@ -533,9 +647,9 @@ class Path {
     /**
      * Transfoms the Path into a directory path.
      * @param {object} params - parameters
-     * @param {string?} params.relative - if defined, the path is constructed relative to this directory
-     * @param {boolean} params.local - if set to true, './' is prefixed to the directory
-     * @param {boolean} params.posix - if set to true, all slashes will be forward slashes on every OS. Useful for require/ import
+     * @param {string} [params.relative] - if defined, the path is constructed relative to this directory
+     * @param {boolean} [params.local] - if set to true, './' is prefixed to the directory
+     * @param {boolean} [params.posix] - if set to true, all slashes will be forward slashes on every OS. Useful for require/ import
      * @returns {string} directory 'a.b.c'.asDirectory() -> 'a/b/c' (or a\b\c when on Windows without passing posix = true)
      */
     asDirectory(params = {}) {
@@ -569,7 +683,7 @@ class Path {
     }
 
     /**
-     * @param {string} relative - directory to which we check relatively
+     * @param {string} [relative] - directory to which we check relatively
      * @returns {boolean} true, iff the Path refers to the current working directory, aka './'
      */
     isCwd(relative = undefined) {
@@ -580,8 +694,16 @@ class Path {
 // TODO: having the repository pattern in place we can separate (some of) the printing logic from the visitor.
 // Most of it hinges primarily on resolving specific files. We can now pass the repository and the resolver to a printer.
 class FileRepository {
+    /** @type {{[key:string]: SourceFile}} */
     #files = {}
 
+    /**
+     * @param {FileOptions} options - options to control file
+     */
+    constructor(options) {
+        this.options = options
+    }
+
     /**
      * @param {string} name - file name
      * @param {SourceFile} file - the file
@@ -598,7 +720,7 @@ class FileRepository {
      */
     getNamespaceFile(path) {
         const key = path instanceof Path ? path.asNamespace() : path
-        return (this.#files[key] ??= new SourceFile(path))
+        return (this.#files[key] ??= new SourceFile(path, this.options))
     }
 
     /**
@@ -628,7 +750,7 @@ const writeout = async (root, sources) =>
                     fs.writeFile(path.join(dir, 'index.js'), source.toJSExports()),
                 ])
 
-            } catch (err) {
+            } catch (/** @type {any} **/err) {
                 // eslint-disable-next-line no-console
                 console.error(`Could not create parent directory ${dir}: ${err}.`)
                 // eslint-disable-next-line no-console

package/lib/logging.js

@@ -1,12 +1,16 @@
 const cds = require('@sap/cds')
 
+/** @param {string} value - the value */
+// @ts-expect-error - yes, cds.log.levels exists...
 const _keyFor = value => Object.entries(cds.log.levels).find(([,val]) => val === value)?.[0]
 
 // workaround until retroactively setting log level to 0 is possible
+// @ts-expect-error - yes, cds.log.levels exists...
 cds.log('cds-typer', _keyFor(cds.log.levels.SILENT))
 module.exports = {
     _keyFor,
-    setLevel: level => { cds.log('cds-typer', level) },
+    setLevel: (/** @type {string | number} */ level) => { cds.log('cds-typer', level) },
+    /** @type {Record<string, string>} */
     deprecated: {
         WARNING: 'WARN',
         CRITICAL: 'ERROR',

package/lib/resolution/builtin.js

@@ -2,6 +2,7 @@ class BuiltinResolver {
     /**
      * Builtin types defined by CDS.
      */
+    /** @type {Record<string, string>} */
     #builtins = {
         UUID: 'string',
         String: 'string',
@@ -32,7 +33,7 @@ class BuiltinResolver {
 
     /**
      * @param {object} options - additional resolution options
-     * @param {boolean} options.IEEE754Compatible - if true, the Decimal, DecimalFloat, Float, and Double types are also allowed to be strings
+     * @param {boolean} [options.IEEE754Compatible] - if true, the Decimal, DecimalFloat, Float, and Double types are also allowed to be strings
      */
     constructor ({ IEEE754Compatible } = {}) {
         if (IEEE754Compatible) {
@@ -45,7 +46,7 @@ class BuiltinResolver {
     }
 
     /**
-     * @param {string | string[]} t - name or parts of the type name split on dots
+     * @param {string | string[] | import("@sap/cds").ref} t - name or parts of the type name split on dots
      * @returns {string | undefined | false} if t refers to a builtin, the name of the corresponding TS type is returned.
      *   If t _looks like_ a builtin (`cds.X`), undefined is returned.
      *   If t is obviously not a builtin, false is returned.

package/lib/resolution/entity.js

@@ -1,3 +1,5 @@
+const { isType } = require('../csn')
+
 class EntityInfo {
     /**
      * @example
@@ -6,7 +8,7 @@ class EntityInfo {
      * // v
      * Path(['n1', 'n2'])
      * ```
-     * @type {Path}
+     * @type {import('../file').Path}
      */
     namespace
 
@@ -44,7 +46,7 @@ class EntityInfo {
      */
     propertyAccess
 
-    /** @type {{singular: string, plural: string}} */
+    /** @type {{singular: string, plural: string} | undefined} */
     #inflection
 
     /** @type {import('./resolver').Resolver} */
@@ -53,10 +55,10 @@ class EntityInfo {
     /** @type {EntityRepository} */
     #repository
 
-    /** @type {EntityInfo} */
-    #parent
+    /** @type {EntityInfo | null} */
+    #parent = null
 
-    /** @type {import('../typedefs').resolver.EntityCSN} */
+    /** @type {import('../typedefs').resolver.EntityCSN | undefined} */
     #csn
 
     get csn () {
@@ -124,7 +126,7 @@ class EntityInfo {
 }
 
 class EntityRepository {
-    /** @type {{ [key: string]: EntityInfo }} */
+    /** @type {{ [key: string]: EntityInfo | null }} */
     #cache = {}
 
     /** @type {import('./resolver').Resolver} */
@@ -142,6 +144,19 @@ class EntityRepository {
         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
+     * @returns {EntityInfo}
+     */
+    getByFqOrThrow(fq) {
+        const entityInfo = this.getByFq(fq)
+        if (entityInfo === null) throw new Error(`Entity with fq "${fq}" is not part of the model`)
+        return entityInfo
+    }
+
     /**
      * @param {import('./resolver').Resolver} resolver - the resolver
      */
@@ -150,6 +165,30 @@ class EntityRepository {
     }
 }
 
+/**
+ * Derives an identifier from an entity info.
+ * That identifier can be used to refer to a specific entity within an index.ts file.
+ * By passing a relative file, the identifier will be preceeded with a scope if needed.
+ * @param {object} options - the options
+ * @param {EntityInfo} options.info - the entity info
+ * @param {function(string): string} [options.wrapper] - a function to wrap the identifier
+ * @param {import('../file').Path} [options.relative] - the path to resolve the identifier relative to
+ * @returns {string} the identifier
+ */
+function asIdentifier ({info, wrapper = undefined, relative = undefined}) {
+    const name = isType(info.csn)
+        ? info.entityName
+        : info.inflection.singular
+
+    const wrapped = typeof wrapper === 'function'
+        ? wrapper(name)
+        : name
+    return !relative || relative.isCwd(info.namespace.asDirectory())
+        ? wrapped
+        : `${info.namespace.asIdentifier()}.${wrapped}`
+}
+
 module.exports = {
-    EntityRepository
+    EntityRepository,
+    asIdentifier
 }