@cap-js/cds-typer 0.33.1 → 0.35.0

package/cds-plugin.js

@@ -5,9 +5,12 @@ const util = require('util')
 const exec = util.promisify(require('child_process').exec)
 const typer = require('./lib/compile')
 const { fs, path } = cds.utils
+const { configuration } = require('./lib/config')
+
 const DEBUG = cds.debug('cli|build')
 const BUILD_CONFIG = 'tsconfig.cdsbuild.json'
-const { configuration } = require('./lib/config')
+const DEFAULT_MODEL_DIRECTORY_NAME = '@cds-models'
+
 
 /**
  * Check if the project is a TypeScript project by looking for a dependency on TypeScript.
@@ -54,6 +57,15 @@ const rmFiles = async (dir, exts) => fs.existsSync(dir)
 
 // IIFE to be able to return early
 ;(() => {
+    if (cds.watched) {
+        if (fs.existsSync(cds.env.typer.output_directory)) return
+        DEBUG?.('>> start cds-typer before cds watch')
+        module.exports = typer.compileFromFile('*')
+            .then(() => DEBUG?.('<< end cds-typer before cds watch'))
+            .catch(e => DEBUG?.(e))
+        return
+    }
+
     // FIXME: remove once cds7 has been phased out
     if (!cds?.version || cds.version < '8.0.0') {
         DEBUG?.('typescript build task requires @sap/cds-dk version >= 8.0.0, skipping registration')
@@ -94,7 +106,7 @@ const rmFiles = async (dir, exts) => fs.existsSync(dir)
             } catch {
                 DEBUG?.('tsconfig.json not found, not parsable, or inconclusive. Using default model directory name')
             }
-            return '@cds-models'
+            return DEFAULT_MODEL_DIRECTORY_NAME
         }
 
         init() {
@@ -151,4 +163,4 @@ const rmFiles = async (dir, exts) => fs.existsSync(dir)
             this.#copyCleanModel(buildDirCdsModels)
         }
     })
-})()
+})()

package/lib/boilerplate/tsBoilerplate.ts

@@ -0,0 +1,95 @@
+import cds from '@sap/cds'
+import { type } from '@sap/cds'
+
+export type ElementsOf<T> = {[name in keyof Required<T>]: type }
+
+export namespace Association {
+    export type to <T> = T;
+    export namespace to {
+        export type many <T extends readonly any[]> = T;
+    }
+}
+
+export namespace Composition {
+    export type of <T> = T;
+    export namespace of {
+        export type many <T extends readonly any[]> = T;
+    }
+}
+
+export class Entity {
+    static data<T extends Entity> (this:T, _input:Object) : T {
+        return {} as T // mock
+    }
+}
+
+export type EntitySet<T> = T[] & {
+    data (input:object[]) : T[]
+    data (input:object) : T
+};
+
+export type DraftEntity<T> = T & {
+    IsActiveEntity?: boolean | null
+    HasActiveEntity?: boolean | null
+    HasDraftEntity?: boolean | null
+    DraftAdministrativeData_DraftUUID?: string | null
+}
+
+export type DraftOf<T> = { new(...args: any[]): DraftEntity<T> }
+export type DraftsOf<T> = typeof Array<DraftEntity<T>>
+
+export type DeepRequired<T> = { 
+    [K in keyof T]: DeepRequired<Unkey<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] 
+}
+
+export type Unkey<T> = T extends Key<infer U> ? U : T
+
+/**
+ * Dates and timestamps are strings during runtime, so cds-typer represents them as such.
+ */
+export type CdsDate = `${number}${number}${number}${number}-${number}${number}-${number}${number}`;
+/**
+ * @see {@link CdsDate}
+ */
+export type CdsDateTime = string;
+/**
+ * @see {@link CdsDate}
+ */
+export type CdsTime = `${number}${number}:${number}${number}:${number}${number}`;
+/**
+ * @see {@link CdsDate}
+ */
+export type CdsTimestamp = string;
+
+export type CdsMap = { [key: string]: unknown };
+
+
+export const createEntityProxy = function (fqParts: any, opts = {}) {
+    const { target, customProps } = { target: {}, customProps: [], ...opts }
+    const fq = fqParts.filter((p: any) => !!p).join('.')
+    return new Proxy(target, {
+        get: function (target:any, prop:any) {
+            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 as never)) 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.`)
+        }
+    })
+}

package/lib/cli.js

@@ -174,7 +174,7 @@ const flags = enrichFlagSchema({
     },
     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'
+        default: 'true'
     }),
     version: {
         desc: 'Prints the version of this tool.'
@@ -185,7 +185,7 @@ const flags = enrichFlagSchema({
         default: 'flat'
     },
     propertiesOptional: parameterTypes.boolean({
-        desc: `If set to true, properties in entities are${EOL}always generated as optional (a?: T).`,
+        desc: `If set to true, properties in entities are${EOL}always generated as optional (a?: T).${EOL}Setting it to false makes properties non-optional instead (a: T).`,
         default: 'true'
     }),
     IEEE754Compatible: parameterTypes.boolean({
@@ -204,7 +204,12 @@ const flags = enrichFlagSchema({
     buildTask: parameterTypes.boolean({
         desc: `If set to true, the typescript build task will not be registered/ executed.${EOL}This value must be set in your project configuration.${EOL}Passing it as parameter to the cds-typer CLI has no effect.`,
         default: 'true'
-    })
+    }),
+    cache: {
+        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'
+    }
 })
 
 const hint = () => 'Missing or invalid parameter(s). Call with --help for more details.'

package/lib/compile.js

@@ -1,13 +1,35 @@
 'use strict'
 
 const fs = require('fs')
-const { normalize } = require('path')
+const { normalize, join } = require('path')
 const cds = require(require.resolve('@sap/cds', { paths: [process.cwd(), __dirname] }))
 const util = require('./util')
 const { writeout } = require('./file')
 const { Visitor } = require('./visitor')
 const { LOG, setLevel } = require('./logging')
 const { configuration } = require('./config')
+const cdsTyperVersion = process.env.npm_package_version
+    ?? require('../package.json').version
+
+/**
+ * @param {JSON} csn - the model
+ * @param {string} hashFile - path to the hash file
+ * @returns {[boolean, string]}
+ */
+const checkHash = (csn, hashFile) => {
+    const crypto = require('crypto')
+    const currentHash = crypto
+        .createHash('blake2s256')
+        .update(JSON.stringify({'cds-typer-version': cdsTyperVersion, csn}))
+        .digest('hex')
+    if (fs.existsSync(hashFile)) {
+        const oldHash = fs.readFileSync(hashFile, 'utf8')
+        if (oldHash === currentHash) {
+            return [false, currentHash]
+        }
+    }
+    return [true, currentHash]
+}
 
 /**
  * Writes the accompanying jsconfig.json file to the specified paths.
@@ -39,11 +61,11 @@ const writeJsConfig = path => {
  * @param {{xtended: import('./typedefs').resolver.CSN, inferred: import('./typedefs').resolver.CSN}} csn - csn tuple
  */
 const compileFromCSN = async csn => {
-
     setLevel(configuration.logLevel)
     if (configuration.jsConfigPath) {
         writeJsConfig(configuration.jsConfigPath)
     }
+
     return writeout(
         configuration.outputDirectory,
         Object.values(new Visitor(csn).getWriteoutFiles())
@@ -55,10 +77,31 @@ const compileFromCSN = async csn => {
  * @param {string | string[]} inputFile - path to input .cds file
  */
 const compileFromFile = async inputFile => {
+    const hashFile = join(configuration.outputDirectory, '.hash')
     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 xtendedPlain = await cds.load(paths, { docs: true, flavor: 'xtended' })
+    let modelHash
+
+    if (configuration.cache === 'blake2s256') {
+        const [shouldCompile, hash] = checkHash(xtendedPlain, hashFile)
+        if (!shouldCompile) {
+            LOG.info('Model has not changed. Skipping generation.')
+            return
+        }
+        modelHash = hash
+    }
+
+    const xtended = await cds.linked(xtendedPlain)
     const inferred = await cds.linked(await cds.load(paths, { docs: true }))
-    return compileFromCSN({xtended, inferred})
+    const result = await compileFromCSN({xtended, inferred})
+
+    if (modelHash) {
+        // write hash as last thing before returning,
+        // so that we don't write it if an error occurs,
+        // which would block the next run although the model has changed
+        fs.writeFileSync(hashFile, modelHash)
+    }
+    return result
 }
 
 module.exports = {

package/lib/components/basedefs.js

@@ -1,88 +1,31 @@
 const { SourceFile } = require('../file')
+const fs = require('node:fs')
+const path = require('node:path')
 
-// eslint-disable-next-line no-template-curly-in-string
-const dateRegex = '`${number}${number}${number}${number}-${number}${number}-${number}${number}`'
-// eslint-disable-next-line no-template-curly-in-string
-const timeRegex = '`${number}${number}:${number}${number}:${number}${number}`'
+/** @type {string} */
+let tsBoilerplate
+/** @type {SourceFile} */
+let baseDefinitions
 
 /**
- * Base definitions used throughout the typing process,
- * such as Associations and Compositions.
- * @type {SourceFile}
+ * @returns {string}
  */
-const baseDefinitions = new SourceFile('_')
-// FIXME: this should be a library someday
-baseDefinitions.addPreamble(`
-import { type } from '@sap/cds'
-
-export type ElementsOf<T> = {[name in keyof Required<T>]: type }
-
-export namespace Association {
-    export type to <T> = T;
-    export namespace to {
-        export type many <T extends readonly any[]> = T;
+function getTsBoilerplate () {
+    if (!tsBoilerplate) {
+        tsBoilerplate = fs.readFileSync(path.join(__filename, '..', '..', 'boilerplate/tsBoilerplate.ts'), 'utf8')
     }
+    return tsBoilerplate
 }
 
-export namespace Composition {
-    export type of <T> = T;
-    export namespace of {
-        export type many <T extends readonly any[]> = T;
-    }
-}
-
-export class Entity {
-    static data<T extends Entity> (this:T, _input:Object) : T {
-        return {} as T // mock
-    }
-}
-
-export type EntitySet<T> = T[] & {
-    data (input:object[]) : T[]
-    data (input:object) : T
-};
-
-export type DraftEntity<T> = T & {
-    IsActiveEntity?: boolean | null
-    HasActiveEntity?: boolean | null
-    HasDraftEntity?: boolean | null
-    DraftAdministrativeData_DraftUUID?: string | null
-}
-
-export type DraftOf<T> = { new(...args: any[]): DraftEntity<T> }
-export type DraftsOf<T> = typeof Array<DraftEntity<T>>
-
-export type DeepRequired<T> = { 
-    [K in keyof T]: DeepRequired<Unkey<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] 
-}
-
-export type Unkey<T> = T extends Key<infer U> ? U : T
-
 /**
- * Dates and timestamps are strings during runtime, so cds-typer represents them as such.
+ * @returns {SourceFile}
  */
-export type CdsDate = ${dateRegex};
-/**
- * @see {@link CdsDate}
- */
-export type CdsDateTime = string;
-/**
- * @see {@link CdsDate}
- */
-export type CdsTime = ${timeRegex};
-/**
- * @see {@link CdsDate}
- */
-export type CdsTimestamp = string;
-
-export type CdsMap = { [key: string]: unknown };
-`)
+function getBaseDefinitions () {
+    if (!baseDefinitions) {
+        baseDefinitions = new SourceFile('_')
+        baseDefinitions.addPreamble(getTsBoilerplate())
+    }
+    return baseDefinitions
+}
 
-module.exports = { baseDefinitions }
+module.exports = { getBaseDefinitions }

package/lib/file.js

@@ -471,7 +471,7 @@ class SourceFile extends File {
         const boilerplate = [AUTO_GEN_NOTE]
         if (configuration.useEntitiesProxy) {
             if (namespace === '_') {
-                boilerplate.push(jsp.printImport('cds', '@sap/cds'), this.#getEntityProxyFunctionExport())
+                boilerplate.push(jsp.printDefaultImport('cds', '@sap/cds'), this.#getEntityProxyFunctionExport())
             } else {
                 boilerplate.push(
                     jsp.printDeconstructedImport(

package/lib/printers/javascript.js

@@ -33,6 +33,17 @@ class JavaScriptPrinter {
         throw Error('not implemented')
     }
 
+    /**
+     * @abstract
+     * @param {string} alias - what the import should be known as within the importing file
+     * @param {string} from - the package/ location to import from
+     * @returns {string}
+     */
+    // eslint-disable-next-line no-unused-vars
+    printDefaultImport (alias, from) {
+        throw Error('not implemented')
+    }
+
     /**
      * @abstract
      * @param {string[]} imports - the deconstructed elements
@@ -83,6 +94,11 @@ class ESMPrinter extends JavaScriptPrinter {
         return `import * as ${alias} from '${from}'`
     }
 
+    /** @type {JavaScriptPrinter['printDefaultImport']} */
+    printDefaultImport (alias, from) {
+        return `import ${alias} from '${from}'`
+    }
+
     /** @type {JavaScriptPrinter['printDeconstructedImport']} */
     printDeconstructedImport (imports, from) {
         return `import { ${imports.join(', ')} } from '${from}/index.js'`
@@ -115,6 +131,11 @@ class CJSPrinter extends JavaScriptPrinter {
         return `const ${alias} = require('${from}')`
     }
 
+    /** @type {JavaScriptPrinter['printDefaultImport']} */
+    printDefaultImport (alias, from) {
+        return `const ${alias} = require('${from}')`
+    }
+
     /** @type {JavaScriptPrinter['printDeconstructedImport']} */
     printDeconstructedImport (imports, from) {
         return `const { ${imports.join(', ')} } = require('${from}')`

package/lib/resolution/resolver.js

@@ -8,13 +8,15 @@ const { StructuredInlineDeclarationResolver } = require('../components/inline')
 const { isInlineEnumType, propertyToInlineEnumName } = require('../components/enum')
 const { isReferenceType } = require('../components/reference')
 const { isEntity, getMaxCardinality } = require('../csn')
-const { baseDefinitions } = require('../components/basedefs')
+const { getBaseDefinitions } = require('../components/basedefs')
 const { BuiltinResolver } = require('./builtin')
 const { LOG } = require('../logging')
 const { last } = require('../components/identifier')
 const { getPropertyModifiers } = require('../components/property')
 const { configuration } = require('../config')
 
+const baseDefinitions = getBaseDefinitions()
+
 /** @typedef {import('../visitor').Visitor} Visitor */
 /** @typedef {import('../typedefs').resolver.CSN} CSN */
 /** @typedef {import('../typedefs').resolver.EntityCSN} EntityCSN */
@@ -68,6 +70,14 @@ class Resolver {
         return type.items ? !type.items.notNull : !type.notNull
     }
 
+    /**
+     * @param {EntityCSN} type - a CSN type
+     * @returns {boolean} whether the type has the @mandatory annotation
+     */
+    isMandatory(type) {
+        return type['@mandatory'] === true
+    }
+
     /**
      * Returns all libraries that have been referenced at least once.
      * @returns {Library[]}
@@ -475,6 +485,11 @@ class Resolver {
                 : element?.key || element?.notNull || cardinality > 1,
         }
 
+        // parameters with @mandatory are always not null
+        // as of today, it is not clear if this also applies to other fields annotated with @mandatory.
+        result.isNotNull ||= element.kind === 'param' && this.isMandatory(element)
+
+
         if (element?.type === undefined) {
             // "fallback" type "empty object". May be overriden via #resolveInlineDeclarationType
             // later on with an inline declaration
@@ -521,9 +536,10 @@ class Resolver {
             result.isBuiltin = true
             this.resolveType(element.items, file)
             //delete element.items
-        } else if (element?.elements && (options?.forceInlineStructs || !element?.type)) {
+        } else if (!result.isBuiltin && element?.elements && (options?.forceInlineStructs || !element?.type)) {
             // explicitly skip named type definitions, which have elements too, but should not be considered inline declarations
             // if the resolver option `forceInlineStructs` is `true`, named types in elements will be converted to inline
+            // Skipping isBuiltin will skip cds.Map, which has elements
             this.#resolveInlineDeclarationType(element.elements, result, file, options)
         }
 

package/lib/typedefs.d.ts

@@ -27,6 +27,7 @@ export module resolver {
         name: string,
         '@singular'?: string,
         '@plural'?: string,
+        '@mandatory'?: boolean,
         '@odata.draft.enabled'?: boolean // custom!
         _unresolved?: boolean
         isRefNotNull?: boolean // custom!
@@ -188,6 +189,7 @@ export module config {
 
     export type Configuration = {
         outputDirectory: string,
+        cache: 'none' | 'blake2s256'
         logLevel: number,
         /**
          * `useEntitiesProxy = true` will wrap the `module.exports.<entityName>` in `Proxy` objects

package/lib/visitor.js

@@ -10,7 +10,7 @@ const { docify, createPromiseOf, createUnionOf, createKeysOf, createElementsOf,
 const { csnToEnumPairs, propertyToInlineEnumName, isInlineEnumType, stringifyEnumType } = require('./components/enum')
 const { isReferenceType } = require('./components/reference')
 const { empty } = require('./components/typescript')
-const { baseDefinitions } = require('./components/basedefs')
+const { getBaseDefinitions } = require('./components/basedefs')
 const { EntityRepository, asIdentifier } = require('./resolution/entity')
 const { last } = require('./components/identifier')
 const { getPropertyModifiers } = require('./components/property')
@@ -18,6 +18,8 @@ const { configuration } = require('./config')
 const { createMember } = require('./components/class')
 const { overrideNameProperty } = require('./printers/javascript')
 
+const baseDefinitions = getBaseDefinitions()
+
 /** @typedef {import('./file').File} File */
 /** @typedef {import('./typedefs').visitor.Context} Context */
 /** @typedef {import('./typedefs').visitor.Inflection} Inflection */
@@ -403,7 +405,9 @@ class Visitor {
             .filter(([, type]) => type?.type !== '$self' && type.items?.type !== '$self')
             .map(([name, type]) => ({
                 name,
-                modifier: this.resolver.isOptional(type) ? '?' : '',
+                modifier: this.resolver.isOptional(type) && !this.resolver.isMandatory(type)
+                    ? '?'
+                    : '',
                 type: this.#stringifyFunctionParamType(type, file),
                 doc: docify(type.doc).join('\n'),
             }))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cap-js/cds-typer",
-  "version": "0.33.1",
+  "version": "0.35.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",
@@ -16,8 +16,8 @@
     "test:unit": "node test/testRunner.js ./test/unit ./test/unit/setup.mjs",
     "test:integration": "node test/testRunner.js ./test/integration ./test/integration/setup.mjs",
     "test:smoke": "node test/testRunner.js ./test/smoke ./test/smoke/setup.mjs",
-    "test:all": "npm run test:smoke && npm run test:unit",
-    "test": "npm run test:smoke && npm run test:unit",
+    "test:all": "npm run test:smoke && npm run test:unit && npm run test:integration",
+    "test": "npm run test:all",
     "lint": "npx eslint .",
     "lint:fix": "npx eslint . --fix",
     "cli": "node lib/cli.js",
@@ -45,7 +45,6 @@
   },
   "devDependencies": {
     "@cap-js/cds-types": "^0",
-    "@sap/cds": "^8",
     "@stylistic/eslint-plugin-js": "^4.2.0",
     "acorn": "^8.10.0",
     "eslint": "^9",
@@ -58,7 +57,7 @@
       "inline_declarations": "flat",
       "target_module_type": "auto",
       "properties_optional": true,
-      "use_entities_proxy": false,
+      "use_entities_proxy": true,
       "build_task": true
     },
     "schema": {
@@ -71,6 +70,15 @@
           "type": "object",
           "description": "Configuration for CDS Typer",
           "properties": {
+            "cache": {
+              "type": "string",
+              "description": "How to cache typer runs.\nnone: fully run cds-typer whenever it is called\nblake2s256: only run if the blake2s256-hash of the model has changed. Hash is stored in a file between runs.",
+              "enum": [
+                "none",
+                "blake2s256"
+              ],
+              "default": "none"
+            },
             "output_directory": {
               "type": "string",
               "description": "Root directory to write the generated files to.",
@@ -101,7 +109,7 @@
             "use_entities_proxy": {
               "type": "boolean",
               "description": "If set to true the 'cds.entities' exports in the generated 'index.js'\nfiles will be wrapped in 'Proxy' objects\nso static import/require calls can be used everywhere.\n\nWARNING: entity properties can still only be accessed after\n'cds.entities' has been loaded",
-              "default": false
+              "default": true
             },
             "inline_declarations": {
               "type": "string",
@@ -114,7 +122,7 @@
             },
             "properties_optional": {
               "type": "boolean",
-              "description": "If set to true, properties in entities are\nalways generated as optional (a?: T).",
+              "description": "If set to true, properties in entities are\nalways generated as optional (a?: T).\nSetting it to false makes properties non-optional instead (a: T).",
               "default": true
             },
             "ieee754compatible": {