@cap-js/cds-typer 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -4,7 +4,20 @@ All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 The format is based on [Keep a Changelog](http://keepachangelog.com/).
 
-## Version 0.4.1 - TBD
+## Version 0.5.1 - TBD
+
+## Version 0.5.0 - 2023-07-25
+
+### Changed
+- Facilitate strict property checks. Note: `checkJs: true` must be present in the project's _jsconfig.json_ or _tsconfig.json_ respectively for this feature to become effective
+
+### Added
+- Support for `array of` syntax
+
+### Fixes
+- Generate `string` type for date-related types in CDS definitions
+- Generate `Buffer | string` type for the CDS type `LargeBinary`
+
 
 ## Version 0.4.0 - 2023-07-06
 ### Added

package/README.md

@@ -1,174 +1,13 @@
 # CDS type generator for JavaScript
 
+[![REUSE status](https://api.reuse.software/badge/github.com/cap-js/cds-typer)](https://api.reuse.software/info/github.com/cap-js/cds-typer)
+![Unit Tests passing](https://github.com/cap-js/cds-typer/actions/workflows/test.yml/badge.svg)
+
 ## About this project
 
 Generates `.ts` files for a CDS model to receive code completion in VS Code.
 
-
-## Requirements and Setup
-This project is [available as `@cap-js/cds-typer`](https://www.npmjs.com/package/@cap-js/cds-typer) as NPM package.
-
-### Usage
-The type generator can either be used as a standalone tool, or as part of of the [CDS VSCode-Extension](https://www.npmjs.com/package/@sap/vscode-cds).
-
-#### Standalone CLI
-Assuming you have the following CDS project structure:
-
-```
-/home/
-├── mybookshop/
-│   ├── db/
-│   │   └── schema.cds
-│   ├── srv/
-│   │   └── service.js
-```
-
-a typical workflow to generate types for your CDS project could look something like this:
-
-```sh
-npx @cap-js/cds-typer /home/mybookshop/db/schema.cds --outputDirectory /home/mybookshop/@types
-```
-
-You would then end up with a directory `@types`, which contains your entities and their accompanying types in a directory structure. The directory structure directly reflects the namespaces you have defined your entities in. They have to be imported in any JavaScript-based service handlers you want to have type support in and can replace calls to `cds.entities(...)`:
-
-```js
-// srv/service.js
-const { Books } = require('my.bookshop')
-```
-
-becomes
-
-```js
-// srv/service.js
-const { Books } = require('../@types/mybookshop')
-```
-
-From that point on you should receive code completion from the type system for `Books`.
-
-_Note:_ the above command generates types for the model contained within the mentioned `schema.cds` file. If you have multiple `.cds` files that are included via `using` statements by `schema.cds`, then those files will also be included in the type generation process. If you have `.cds` files that are _not_ in some way included in `schema.cds`, you have to explicitly pass those as positional argument as well, if you want types for them.
-
-_cds-typer_ comes with rudimentary CLI support and a few command line options:
-
-- `--help`: prints all available parameters.
-- `--outputDirectory`: specifies the root directory where all generated files should be put. Defaults to the CWD.
-- `--jsConfigPath`: specifies the path to the `jsconfig.json` file to generate. Usually your project's root directory. If specified, a config file is created that restricts the usage of types even further:
-
-```js
-// generated .ts file
-class Book {
-    title: string;
-}
-
-// some hook in your service
-SELECT(Books, b => {
-    b.title // 👍 no problem, property exists
-    b.numberOfPages // ❌ property does not exist
-})
-```
-With the generated config in place, the language server will display an error, telling you that `numberOfPages` does not exist in this context. Without the config it would just infer it as `any`.
-
-- `--loglevel`: minimum log level that should be printed. Defaults to `NONE`. Available log levels roughly follow [Microsoft's dotnet log levels](https://docs.microsoft.com/en-us/dotnet/api/microsoft.extensions.logging.loglevel?view=dotnet-plat-ext-6.0):
-
-```
-TRACE
-DEBUG
-INFO
-WARNING
-ERROR
-CRITICAL
-NONE
-```
-
-The utility expects (at least) one path to a `.cds` file as positional parameter which serves as entry point to the model in question, e.g.:
-
-```sh
-npx @cap-js/cds-typer ./path/to/my/model/model.cds --outputDirectory /tmp/
-```
-
-Note that you can also pass multiple paths or `"*"` as glob pattern (with quotes to circumvent expansion by the shell). This passes the pattern on to the compiler where the [regular resolve strategy](https://cap.cloud.sap/docs/node.js/cds-compile?q=compiler#cds-resolve) is used.
-
-#### From VSCode
-Installing the [CDS VSCode Extension](https://www.npmjs.com/package/@sap/vscode-cds) also adds support for generating types for your model from within VSCode. Adding the appropriate facet to your project via `cds add typer` (and installing the added dependencies thereafter) allows you to simply hit save on any `.cds` file that is part of your model to trigger the generation process.
-#### Programmatically
-The main API for using _cds-typer_ within another project is contained in [`compile.js`](https://github.tools.sap/cap/cds-typer/blob/master/lib/compile.js), specifically:
-
-- `compileFromFile(…)` to parse a `.cds` file. This involves compiling it to CSN first.
-- `compileFromCSN(…)` to directly compile from CSN object. This is useful when you already have your CSN available as part of a tool chain. ⚠️ **WARNING**: the application of `cdstyper` may be impure, meaning that it _could_ alter the provided CSN. If you use the typer this way, you may want to apply it as last step of your tool chain.
-
-
-### Features
-#### Plural Types
-While CDS encourages the use of plural form for defined entities, their OOP equivalent classes are usually named in singular. _cds-typer_ automatically transforms entity names to singular and adds the plural form for arrays:
-
-```cds
-entity Books : cuid {
-    …
-}
-```
-
-becomes
-
-```ts
-class Book {
-	…
-}
-
-class Books extends Array<Book> {}
-```
-
-If you need to customise the singular or plural form, or if your entities are already in singular form, you can do so using annotations:
-
-```cds
-@singular: 'Mouse'
-entity Mice {}
-
-@plural: 'SomeListList'
-entity SomeList {}
-```
-
-results in
-
-```ts
-class Mouse { … }
-class Mice extends Array<Mouse> { … }
-
-class SomeList { … }
-class SomeListList extends Array<SomeList> { … }
-```
-
-### Relation to _cds2types_
-This project is inspired by the existing [_cds2types_](https://github.com/mrbandler/cds2types), but differs in a few aspects:
-
-#### Reworked Imports
-Instead of one monolithic `.d.ts` file containing all entities in nested namespaces, multiple files are generated where each namespace is represented by a directory structure. This facilicates simpler imports in a more Java-esque style:
-
-```js
-const types = require('./cds2types/compiled.d.ts')
-
-console.log(types.sap.cap.bookshop.Books) // a class
-```
-
-becomes
-
-```js
-const { Books } = require('./cds-typer/sap/cap/bookshop')
-
-console.log(Books) // the same class
-```
-
-#### Usable in Javascript Projects
-Generated code is usable from within plain Javascript projects. The code generated by _cds2types_ would represent each cds-entity as an interface, which are not visible to Javascript projects. _cds-typer_ uses classes instead.
-
-#### Faster
-_cds2types_ takes a detour to create a Typescript AST first and then print out the formatted source files. _cds-typer_ directly walks the linked CSN and creates strings on the fly. Also, file operations are `async`. These two changes speed up _cds-typer_ by around one to two orders of magnitude compared to _cds2types_.
-
-#### Small Footprint
-_cds-typer_ tries to keep its dependency footprint as small as possible. Libraries like `typescript` are only needed as dev dependencies.
-
-
-
-
-
+Exhaustive documentation can be found on [CAPire](https://cap.cloud.sap/docs/tools/cds-typer).
 
 ## Support, Feedback, Contributing
 
@@ -176,8 +15,8 @@ This project is open to feature requests/suggestions, bug reports etc. via [GitH
 
 ## Code of Conduct
 
-We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone. By participating in this project, you agree to abide by its [Code of Conduct](CODE_OF_CONDUCT.md) at all times.
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone. By participating in this project, you agree to abide by its [Code of Conduct](https://github.com/cap-js/.github/blob/main/CODE_OF_CONDUCT.md) at all times.
 
 ## Licensing
 
-Copyright 2022-2022 SAP SE or an SAP affiliate company and cds-dts-generator contributors. Please see our [LICENSE](LICENSE) for copyright and license information. Detailed information including third-party components and their licensing/copyright information is available [via the REUSE tool](https://api.reuse.software/info/github.com/SAP/cds-dts-generator).
+Copyright 2022-2022 SAP SE or an SAP affiliate company and cds-typer contributors. Please see our [LICENSE](LICENSE) for copyright and license information. Detailed information including third-party components and their licensing/copyright information is available [via the REUSE tool](https://api.reuse.software/info/github.com/SAP/cds-dts-generator).

package/lib/cli.js

@@ -6,80 +6,82 @@ const { compileFromFile } = require('./compile')
 const { parseCommandlineArgs } = require('./util')
 const { Levels } = require('./logging')
 const path = require('path')
+const { EOL } = require('node:os')
 
+const EOL2 = EOL + EOL
 const toolName = 'cds-typer'
 
 const flags = {
-    // FIXME: remove asap
-    rootDir: {
-        desc: '[DEPRICATED] use outputDirectory instead',
-        default: './',
-    },
     outputDirectory: {
-        desc: 'root directory to write generated files to',
+        desc: 'Root directory to write the generated files to.',
         default: './',
+        type: 'string'
     },
     help: {
-        desc: 'this text',
+        desc: 'This text.',
     },
     logLevel: {
-        desc: `minimum log level`,
+        desc: `Minimum log level that is printed.`,
         allowed: Object.keys(Levels),
         default: Object.keys(Levels).at(-1),
     },
     jsConfigPath: {
-        desc: `Path to where the jsconfig.json should be written. If specified, ${toolName} will create a jsconfig.json file and set it up to restrict property usage in types entities to existing properties only.`,
+        desc: `Path to where the jsconfig.json should be written.${EOL}If specified, ${toolName} will create a jsconfig.json file and${EOL}set it up to restrict property usage in types entities to${EOL}existing properties only.`,
+        type: 'string'
     },
     version: {
-        desc: 'prints the version of this tool'
+        desc: 'Prints the version of this tool.'
     },
     inlineDeclarations: {
-        desc: 'whether to resolve inline type declarations flat (x_a, x_b, ...) or structured (x: {a, b})',
+        desc: `Whether to resolve inline type declarations${EOL}flat: (x_a, x_b, ...)${EOL}or structured: (x: {a, b}).`,
         allowed: ['flat', 'structured'],
         default: 'structured'
     },
     propertiesOptional: {
-        desc: 'if set to true, properties in entities are always generated as optional (a?: T)',
+        desc: `If set to true, properties in entities are${EOL}always generated as optional (a?: T).`,
         allowed: ['true', 'false'],
         default: 'true'
     }
 }
 
 const hint = () => console.log('Missing or invalid parameter(s). Call with --help for more details.')
+const indent = (s, indentation) => s.split(EOL).map(line => `${indentation}${line}`).join(EOL)
 
-const help = () =>
-    console.log(
-        '[SYNOPSIS]\n' +
-        'Call with at least one positional parameter pointing to the (root) CDS file you want to compile.\n' +
-            'Additionaly, you can use the following parameters:\n' +
+const help = () => `SYNOPSIS${EOL2}` +
+        indent(`cds-typer [cds file | "*"]`, '  ') + EOL2 +
+        indent(`Generates type information based on a CDS model.${EOL}Call with at least one positional parameter pointing${EOL}to the (root) CDS file you want to compile.`, '  ') + EOL2 +
+            `OPTIONS${EOL2}` +
             Object.entries(flags)
                 .sort()
                 .map(([key, value]) => {
-                    let s = `--${key}: ${value.desc}`
+                    let s = indent(`--${key}`, '  ')
                     if (value.allowed) {
-                        s += ` [allowed: ${value.allowed.join(' | ')}]`
+                        s += `: <${value.allowed.join(' | ')}>`
+                    } else if (value.type) {
+                        s += `: <${value.type}>`
                     }
                     if (value.default) {
-                        s += ` (default: ${value.default})`
+                        s += EOL
+                        s += indent(`(default: ${value.default})`, '    ')
                     }
+                    s += `${EOL2}${indent(value.desc, '    ')}`
                     return s
                 }
-            ).join('\n\n')
-    )
+            ).join(EOL2)
 
-const version = () => console.log(require('../package.json').version)
+const version = () => require('../package.json').version
 
 const main = async (args) => {
     if ('help' in args.named) {
-        help()
+        console.log(help())
         process.exit(0)
     }
     if ('version' in args.named) {
-        version()
+        console.log(version())
         process.exit(0)
     }
     if (args.positional.length === 0) {
-        hint()
+        console.log(hint())
         process.exit(1)
     }
     if (args.named.jsConfigPath && !args.named.jsConfigPath.endsWith('jsconfig.json')) {
@@ -98,3 +100,7 @@ const main = async (args) => {
 if (require.main === module) {
     main(parseCommandlineArgs(process.argv.slice(2), flags))
 }
+
+function helpToCapire() {
+
+}

package/lib/compile.js

@@ -8,11 +8,16 @@ const { writeout } = require('./file')
 const { Logger } = require('./logging')
 const { Visitor } = require('./visitor')
 
+/**
+ * @typedef {import('./visitor').CompileParameters} CompileParameters
+ */
+
 /**
  * Writes the accompanying jsconfig.json file to the specified paths.
  * Tries to merge nicely if an existing file is found.
  * @param path {string} filepath to jsconfig.json.
  * @param logger {import('./logging').Logger} logger
+ * @private
  */
 const writeJsConfig = (path, logger) => {
     let values = {

package/lib/components/resolver.js

@@ -40,7 +40,7 @@ const Builtins = {
     String: 'string',
     Binary: 'string',
     LargeString: 'string',
-    LargeBinary: 'string',
+    LargeBinary: 'Buffer | string',
     Integer: 'number',
     UInt8: 'number',
     Int16: 'number',
@@ -52,10 +52,11 @@ const Builtins = {
     Float: 'number',
     Double: 'number',
     Boolean: 'boolean',
-    Date: 'Date',
-    DateTime: 'Date',
-    Time: 'Date',
-    Timestamp: 'Date',
+    // note: the date-related types _can_ be Date in some cases, but let's start with string
+    Date: 'string',  // yyyy-mm-dd
+    DateTime: 'string', // yyyy-mm-dd + time + TZ (precision: seconds
+    Time: 'string',
+    Timestamp: 'string', // yyy-mm-dd + time + TZ (ms precision)
     //
     Composition: 'Array',
     Association: 'Array'
@@ -212,13 +213,14 @@ class Resolver {
                 {
                     Association: [createToOneAssociation, createToManyAssociation],
                     Composition: [createCompositionOfOne, createCompositionOfMany],
+                    array: [createArrayOf, createArrayOf]
                 }[element.constructor.name] ?? []
 
             if (toOne && toMany) {
-                const target = typeof element.target === 'string' ? { type: element.target } : element.target
+                const target = element.items ?? (typeof element.target === 'string' ? { type: element.target } : element.target)
                 const { singular, plural } = this.resolveAndRequire(target, file).typeInfo.inflection
                 typeName =
-                    cardinality > 1 ? toMany(plural) : toOne(this.visitor.isSelfReference(element.target) ? 'this' : singular)
+                    cardinality > 1 ? toMany(plural) : toOne(this.visitor.isSelfReference(target) ? 'this' : singular)
                 file.addImport(baseDefinitions.path)
             }
         } else {
@@ -258,8 +260,11 @@ class Resolver {
             typeInfo.inflection = this.inflect(typeInfo)
         }
 
-        if (typeInfo.isArray === true) {
-            typeName = createArrayOf(typeName)
+        // add fallback inflection. Mainly needed for array-of with builtin types.
+        // (array-of relies on inflection being present, which is not the case in builtin)
+        typeInfo.inflection ??= {
+            singular: typeName,
+            plural: typeName
         }
 
         // FIXME: typeName could probably just become part of typeInfo
@@ -346,8 +351,8 @@ class Resolver {
 
         // objects and arrays
         if (element?.items) {
-            // FIXME: builtin = true? arrays are kinda builtin
             result.isArray = true
+            result.isBuiltin = true
             this.resolveType(element.items, file)
             //delete element.items
         } else if (element?.elements && !element?.type) {

package/lib/visitor.js

@@ -124,7 +124,7 @@ class Visitor {
         })
 
         // CLASS ASPECT
-        buffer.add(`export function ${identAspect(clean)}<TBase extends new (...args: any[]) => any>(Base: TBase) {`)
+        buffer.add(`export function ${identAspect(clean)}<TBase extends new (...args: any[]) => object>(Base: TBase) {`)
         buffer.indent()
         buffer.add(`return class ${clean} extends Base {`)
         buffer.indent()
@@ -318,7 +318,7 @@ class Visitor {
     /**
      * A self reference is a property that references the class it appears in.
      * They need to be detected on CDS level, as the emitted TS types will try to
-     * refer to refer to types via their alias that hides the aspectification.
+     * refer to types via their alias that hides the aspectification.
      * If we attempt to directly refer to this alias while it has not been fully created,
      * that will result in a TS error.
      * @param {String} entityName

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@cap-js/cds-typer",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Generates .ts files for a CDS model to receive code completion in VS Code",
   "main": "index.js",
+  "repository": "github:cap-js/cds-typer",
   "homepage": "https://cap.cloud.sap/",
   "keywords": [
     "CAP",
@@ -17,7 +18,14 @@
     "test:all": "jest",
     "test": "npm run test:unit",
     "lint": "eslint",
-    "cli": "node lib/cli.js"
+    "cli": "node lib/cli.js",
+    "doc:clean": "rm -rf ./doc",
+    "doc:prepare": "npm run doc:clean && mkdir -p doc/types",
+    "doc:typegen": "./node_modules/.bin/tsc ./lib/*.js  --skipLibCheck --declaration --allowJs --emitDeclarationOnly --outDir doc/types && cd doc/types && tsc --init",
+    "doc:html": "npm run doc:typegen && ./node_modules/.bin/typedoc 'doc/types/**/*.d.ts' --entryPointStrategy expand --out doc/html --tsconfig doc/types/tsconfig.json",
+    "doc:md": "npm run doc:typegen && ./node_modules/.bin/typedoc --plugin typedoc-plugin-markdown 'doc/types/compile.d.ts' --out doc/md --tsconfig doc/types/tsconfig.json",
+    "doc:cli": "npm run cli -- --help > ./doc/cli.txt",
+    "doc:full": "npm run doc:prepare && npm run doc:html && npm run doc:cli"
   },
   "files": [
     "lib/",
@@ -39,6 +47,8 @@
     "eslint-config-prettier": "^8.5.0",
     "eslint-plugin-prettier": "^4.0.0",
     "jest": "^29",
+    "typedoc": "^0.24.8",
+    "typedoc-plugin-markdown": "^3.15.3",
     "typescript": ">=4.6.4"
   },
   "jest": {