'
}
```
diff --git a/node.js/cds-compile.md b/node.js/cds-compile.md
index 5f8df6b80..98bf50c39 100644
--- a/node.js/cds-compile.md
+++ b/node.js/cds-compile.md
@@ -40,7 +40,6 @@ It supports different variants based on the type of the first argument `model` a
Depending on the variants, the method returns a Promise or a sync value.
-
### Compiling `.cds` files (async)
If the first argument is either a string starting with `"file:"`, or an _array_ of filenames, these files are read and compiled to a single CSN asynchronously:
@@ -53,6 +52,9 @@ let csn = await cds.compile ('file:db')
> The given filenames are resolved to effective absolute filenames using [`cds.resolve`](#cds-resolve).
+> [!TIP] Use cds compile as CLI equivalent
+> The [`cds compile` CLI](../tools/cds-cli#cds-compile) is available as entry point to the functions described here. For example, `cds compile --to hana` maps to `cds.compile.to.hana` etc.
+
### Single in-memory sources
@@ -440,7 +442,7 @@ cds.on('compile.to.edmx', ...)
> As we're using Node's standard [EventEmitter](https://nodejs.org/api/events.html#asynchronous-vs-synchronous),
> event handlers execute **synchronously** in the order they are registered.
-> [!tip] Note that several of these events coud be emitted for the same model, so ensure your handlers are idempodent.
+> [!tip] Note that several of these events could be emitted for the same model, so ensure your handlers are idempotent.
### compile.for.runtime {.event}
diff --git a/node.js/cds-serve.md b/node.js/cds-serve.md
index 351ce9f32..abb234700 100644
--- a/node.js/cds-serve.md
+++ b/node.js/cds-serve.md
@@ -296,9 +296,9 @@ Be aware that overriding requires constant updates as new middlewares by the fra
[Learn more about the middlewares default order.](#cds-middlewares){.learn-more}
-#### Customization of `req.user`
+#### Customization of `cds.context.user`
-You can register middlewares to customize `req.user`.
+You can register middlewares to customize `cds.context.user`.
It must be done after authentication.
If `cds.context.tenant` is manipulated as well, it must also be done before `cds.context.model` is set for the current request.
diff --git a/node.js/events.md b/node.js/events.md
index 10adc2207..294bf50dd 100644
--- a/node.js/events.md
+++ b/node.js/events.md
@@ -137,6 +137,11 @@ The current user, an instance of `cds.User` as identified and verified by the au
[See reference docs for `cds.User`.](authentication#cds-user){.learn-more .indent}
+::: tip
+Please note the difference between `req` in a service handler (instance of `cds.EventContext`) and `req` in an express middleware (instance of `http.IncomingMessage`).
+Case in point, `req.user` in a service handler is an official API and, if not explicitely set, points to `cds.context.user`.
+On the other hand, setting `req.user` in a custom authentication middleware is deprecated.
+:::
diff --git a/package-lock.json b/package-lock.json
index b0de7ec39..174cae6e5 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1450,9 +1450,9 @@
}
},
"node_modules/@eslint/core": {
- "version": "0.9.1",
- "resolved": "https://registry.npmjs.org/@eslint/core/-/core-0.9.1.tgz",
- "integrity": "sha512-GuUdqkyyzQI5RMIWkHhvTWLCyLo1jNK3vzkSyaExH5kHPDHcuL2VOpHjmMY+y3+NC69qAKToBqldTBgYeLSr9Q==",
+ "version": "0.10.0",
+ "resolved": "https://registry.npmjs.org/@eslint/core/-/core-0.10.0.tgz",
+ "integrity": "sha512-gFHJ+xBOo4G3WRlR1e/3G8A6/KZAH6zcE/hkLRCZTi/B9avAG365QhFA8uOGzTMqgTghpn7/fSnscW++dpMSAw==",
"dev": true,
"license": "Apache-2.0",
"dependencies": {
@@ -1511,9 +1511,9 @@
}
},
"node_modules/@eslint/js": {
- "version": "9.17.0",
- "resolved": "https://registry.npmjs.org/@eslint/js/-/js-9.17.0.tgz",
- "integrity": "sha512-Sxc4hqcs1kTu0iID3kcZDW3JHq2a77HO9P8CP6YEA/FpH3Ll8UXE2r/86Rz9YJLKme39S9vU5OWNjC6Xl0Cr3w==",
+ "version": "9.18.0",
+ "resolved": "https://registry.npmjs.org/@eslint/js/-/js-9.18.0.tgz",
+ "integrity": "sha512-fK6L7rxcq6/z+AaQMtiFTkvbHkBLNlwyRxHpKawP0x3u9+NC6MQTnFW+AdpwC6gfHTW0051cokQgtTN2FqlxQA==",
"dev": true,
"license": "MIT",
"engines": {
@@ -1531,12 +1531,13 @@
}
},
"node_modules/@eslint/plugin-kit": {
- "version": "0.2.4",
- "resolved": "https://registry.npmjs.org/@eslint/plugin-kit/-/plugin-kit-0.2.4.tgz",
- "integrity": "sha512-zSkKow6H5Kdm0ZUQUB2kV5JIXqoG0+uH5YADhaEHswm664N9Db8dXSi0nMJpacpMf+MyyglF1vnZohpEg5yUtg==",
+ "version": "0.2.5",
+ "resolved": "https://registry.npmjs.org/@eslint/plugin-kit/-/plugin-kit-0.2.5.tgz",
+ "integrity": "sha512-lB05FkqEdUg2AA0xEbUz0SnkXT1LcCTa438W4IWTUh4hdOnVbQyOJ81OrDXsJk/LSiJHubgGEFoR5EHq1NsH1A==",
"dev": true,
"license": "Apache-2.0",
"dependencies": {
+ "@eslint/core": "^0.10.0",
"levn": "^0.4.1"
},
"engines": {
@@ -2293,9 +2294,9 @@
]
},
"node_modules/@sap/cds": {
- "version": "8.6.0",
- "resolved": "https://registry.npmjs.org/@sap/cds/-/cds-8.6.0.tgz",
- "integrity": "sha512-MagthrcmAa1l+nAtx/4gMnDv9scfkIwXPFQT7N8+dLU0u1DitLePA5nYk9M62wHZy79mE1tPwxdoLS2NdMzQQw==",
+ "version": "8.6.1",
+ "resolved": "https://registry.npmjs.org/@sap/cds/-/cds-8.6.1.tgz",
+ "integrity": "sha512-JYHRrGs6Tgle5Vmj/o3BaQkOBVcroweOrXhhiUVH6twISy+Yi2cWZdTr0EFFEt94FI1dVqvrVnEM67jEjOQImQ==",
"dev": true,
"license": "SEE LICENSE IN LICENSE",
"dependencies": {
@@ -4278,19 +4279,19 @@
}
},
"node_modules/eslint": {
- "version": "9.17.0",
- "resolved": "https://registry.npmjs.org/eslint/-/eslint-9.17.0.tgz",
- "integrity": "sha512-evtlNcpJg+cZLcnVKwsai8fExnqjGPicK7gnUtlNuzu+Fv9bI0aLpND5T44VLQtoMEnI57LoXO9XAkIXwohKrA==",
+ "version": "9.18.0",
+ "resolved": "https://registry.npmjs.org/eslint/-/eslint-9.18.0.tgz",
+ "integrity": "sha512-+waTfRWQlSbpt3KWE+CjrPPYnbq9kfZIYUqapc0uBXyjTp8aYXZDsUH16m39Ryq3NjAVP4tjuF7KaukeqoCoaA==",
"dev": true,
"license": "MIT",
"dependencies": {
"@eslint-community/eslint-utils": "^4.2.0",
"@eslint-community/regexpp": "^4.12.1",
"@eslint/config-array": "^0.19.0",
- "@eslint/core": "^0.9.0",
+ "@eslint/core": "^0.10.0",
"@eslint/eslintrc": "^3.2.0",
- "@eslint/js": "9.17.0",
- "@eslint/plugin-kit": "^0.2.3",
+ "@eslint/js": "9.18.0",
+ "@eslint/plugin-kit": "^0.2.5",
"@humanfs/node": "^0.16.6",
"@humanwhocodes/module-importer": "^1.0.1",
"@humanwhocodes/retry": "^0.4.1",
diff --git a/tools/assets/help/cds-compile.out.md b/tools/assets/help/cds-compile.out.md
new file mode 100644
index 000000000..2479f58c0
--- /dev/null
+++ b/tools/assets/help/cds-compile.out.md
@@ -0,0 +1,130 @@
+
+
+> cds compile --help
+
+SYNOPSIS
+ cds compile <models> [<options>]
+
+ Compiles the specified models to CSN format, applying processors to unfold
+ and generate target outputs using the <options>.
+
+
+OPTIONS
+
+ -2 | --to <target format>
+
+ Compiles the given models to the specified <target format>.
+ Currently supported:
+
+ - json, yml
+ - edm, edmx, edmx-v2, edmx-v4, edmx-w4, edmx-x4
+ - sql, hdbcds, hdbtable, hana
+ - cdl
+ - xsuaa
+ - openapi
+ - asyncapi
+
+ -4 | --for <target>
+
+ Unfolds the compiled CSN for the specified <target> usages,
+ or get a comma-separated list, without generating target formats.
+ Currently supported:
+
+ - odata
+ - sql
+
+ --dialect <dialect>
+
+ Needs option --to.
+ Specify the dialect in combination with --to sql.
+ Currently supported:
+
+ - sqlite
+ - h2
+ - postgres
+ - hana
+
+ -s | --service <name> | all
+
+ Chooses a specific service or all to force output for all services.
+ The service name must be fully qualified, including the namespace, if any.
+
+ -l | --lang <languages> | all
+
+ Localizes the output with given <languages>, a comma-separated list
+ of language/locale codes or all.
+ Localization is carried out before all other processors (-4/u) or backends (-2).
+
+ -o | --dest <folder>
+
+ Writes output to the given folder instead of stdout.
+
+ -f | --flavor sources | files | parsed | xtended | inferred
+
+ Depending on the argument, returns a model with the given level of detail:
+
+ sources: paths and content of all resolved source files
+ files: paths of all effectively referenced files
+ parsed: the definitions and extensions, without applying the
+ extensions or includes, and without imported definitions.
+ xtended: the definitions with all imports and extensions resolved,
+ but without any derived information
+ inferred: the effective model, including imported definitions, extensions,
+ and derived information. This is the default flavor.
+
+ --parse
+
+ Shortcut for '--flavor parsed'
+
+ --plain
+
+ Shortcut for '--flavor xtended'
+
+ --docs
+
+ Preserves /**...*/ doc comments in 'doc' properties of CSN outputs,
+ as well as in 'Core.Description' annotations of EDMX outputs.
+
+ --locations
+
+ Preserves $location properties of CSN outputs.
+
+ --log-level debug | info | warn | error
+
+ Chooses which level of compiler messages to log. The default log-level is warn.
+
+ --openapi:url <Server URL for Open API export>
+
+ The server URL used in the generated OpenAPI document. The default is the service
+ base path as declared in the CDS source.
+ Use the ${service-path} variable to have the service path included in the URL.
+
+ --openapi:servers <Stringified JSON Object for Open API export>
+
+ The servers definition used in the generated OpenAPI document. --openapi:url is
+ ignored when this option is specified.
+
+ --odata-version 4.0|4.01
+
+ Adds the OData version's functionality of the input CDS/CSN file to the generated OpenAPI document.
+
+ --openapi:diagram
+
+ Include YUML diagram in the generated OpenAPI document, default: false.
+
+ --openapi:config-file filename
+
+ The passed configuration file will be read to generate the OpenAPI document, incorporating all specified options.
+ Precedence of Options: Inline options specified in the command line will take precedence over those defined in the configuration file.
+
+ --asyncapi:merged
+
+ A single AsyncAPI document is generated using the details of all input services. Information of title
+ and version should be provided as preset.
+
+EXAMPLES
+ cds compile model.cds
+ cds c model.json --to sql
+ cds srv -s all -l all -2 edmx -o [4mout
+ cds compile srv -s sap.sample.TestService -2 asyncapi -o [0mout
+
diff --git a/tools/assets/help/cds-env.out.md b/tools/assets/help/cds-env.out.md
new file mode 100644
index 000000000..e3966b940
--- /dev/null
+++ b/tools/assets/help/cds-env.out.md
@@ -0,0 +1,46 @@
+
+
+> cds env --help
+
+SYNOPSIS
+ cds env [<key>] [<options>]
+
+EXPLANATION
+ Displays the effective configuration for the given key, or all of the
+ current environment.
+
+OPTIONS
+ --sources
+
+ Lists the sources from with the current env has been compiled.
+
+ -k | --keys
+
+ Prints (top-level) keys of matching properties only
+
+ -p | --properties
+ -l | --list
+
+ Prints output in .properties format
+
+ -j | --json
+
+ Prints output in JSON format
+
+ -r | --raw
+
+ Prints output with minimum formatting or decoration
+
+ -4 | --for | --profile <profile,...>
+
+ Load configuration for the specified profile(s).
+ The development profile is used by default.
+
+ -P | --process-env
+
+ Show properties from Node.js process.env.
+
+ -b | --resolve-bindings
+
+ Resolve remote service bindings configured via cds bind.
+
diff --git a/tools/assets/help/cds-init.out.md b/tools/assets/help/cds-init.out.md
new file mode 100644
index 000000000..78c29e8af
--- /dev/null
+++ b/tools/assets/help/cds-init.out.md
@@ -0,0 +1,90 @@
+
+
+> cds init --help
+
+SYNOPSIS
+ cds init [<project>] [<options>]
+
+ Initializes a new project in folder ./<project>, with the current
+ working directory as default.
+
+OPTIONS
+ --java
+
+ Create a CAP Java project.
+
+ --add <feature | comma-separated list of features>
+
+ Add one or more features while creating the project.
+ <feature> can be one of the following:
+
+ completion - shell completion for cds commands
+ java - creates a Java-based project
+ nodejs - creates a Node.js-based project
+ esm - ESM-compatible Node.js project
+ tiny-sample - add minimal sample files
+ sample - add sample files including Fiori UI
+ typer - type generation for CDS models
+ typescript - add minimum configuration for a bare TypeScript project
+ handler - handler stubs for service entities, actions and functions
+ mta - Cloud Foundry deployment using mta.yaml
+ cf-manifest - Cloud Foundry deployment using manifest files
+ helm - Kyma deployment using Helm charts
+ helm-unified-runtime - Kyma deployment using Unified Runtime Helm charts
+ containerize - containerization using ctz CLI
+ multitenancy - schema-based multitenancy support
+ toggles - allow dynamically toggled features
+ extensibility - tenant-specific model extensibility
+ side-by-side-extensibility - logic extensibility via extension points
+ mtx - multitenancy + toggles + extensibility
+ xsuaa - authentication via XSUAA
+ ias - authentication via IAS
+ ams - authorization via AMS
+ hana - database support for SAP HANA
+ postgres - database support for PostgreSQL
+ sqlite - database support for SQLite
+ h2 - database support for H2
+ liquibase - database migration using Liquibase
+ redis - SAP BTP Redis, Hyperscaler Option
+ attachments - SAP BTP Object Store Service
+ malware-scanner - SAP Malware Scanning Service
+ local-messaging - messaging via local event bus
+ file-based-messaging - messaging via file system
+ enterprise-messaging - messaging via SAP Enterprise Messaging
+ enterprise-messaging-shared - messaging via shared SAP Enterprise Messaging
+ redis-messaging - messaging via Redis
+ kafka - messaging via Apache Kafka
+ approuter - dynamic routing using @sap/approuter
+ connectivity - SAP BTP Connectivity Service
+ destination - SAP BTP Destination Service
+ html5-repo - SAP BTP HTML5 Application Repository
+ portal - SAP BTP Portal Service
+ application-logging - SAP BTP Application Logging Service
+ audit-logging - SAP BTP Audit Logging Service
+ notifications - SAP BTP Notification Service
+ workzone-standard - SAP BTP Work Zone, Standard Edition
+ data - add CSV headers for modeled entities
+ http - add .http files for modeled services
+ lint - configure cds lint
+ pipeline - CI/CD pipeline integration
+
+ --java:mvn <Comma separated maven archetype specific parameters>
+
+ Add the given parameters to the archetype call.
+ See https://cap.cloud.sap/docs/java/developing-applications/building#the-maven-archetype
+ for parameters supported by the archetype.
+
+ --force
+
+ Overwrite all files.
+
+EXAMPLES
+ cds init bookshop
+ cds init bookshop --java
+ cds init bookshop --add hana
+ cds init bookshop --add multitenancy,mta
+ cds init --java --java:mvn groupId=myGroup,artifactId=newId,package=my.company
+
+SEE ALSO
+ cds add - to augment your projects later on
+
diff --git a/tools/assets/help/cds-watch.out.md b/tools/assets/help/cds-watch.out.md
index 21281a3a9..a19040e0d 100644
--- a/tools/assets/help/cds-watch.out.md
+++ b/tools/assets/help/cds-watch.out.md
@@ -24,6 +24,14 @@
Specify file extensions to watch for in a comma-separated list.
Example: cds w --ext cds,json,js.
+ --include <paths,...>
+
+ Comma-separated list of additional paths to watch.
+
+ --exclude <paths,...>
+
+ Comma-separated list of additional paths to ignore.
+
--livereload <port | false>
Specify the port for the livereload server. Defaults to '35729'.
diff --git a/tools/cds-cli.md b/tools/cds-cli.md
index 1bd640cde..b50d8678d 100644
--- a/tools/cds-cli.md
+++ b/tools/cds-cli.md
@@ -82,7 +82,7 @@ Use `cds help` to see an overview of all commands:
Use `cds help ` or `cds ?` to get specific help:
-
+
## cds init
@@ -102,6 +102,9 @@ For example to create a project with a sample bookshop model and configuration f
cds init --add sample,hana
```
+::: details See the full help text of `cds init`
+
+:::
## cds add
@@ -362,9 +365,22 @@ Use `cds env` to inspect currently effective config settings:
+::: details See the full help text of `cds env`
+
+:::
+
## cds compile
+Compiles the specified models to [CSN](../cds/csn) or other formats.
+
+[See simple examples in the getting started page](../get-started/in-a-nutshell#cli).{.learn-more}
+
+[For the set of built-in compile 'formats', see the `cds.compile.to` API](../node.js/cds-compile#cds-compile-to).{.learn-more}
+
+
+In addition, the following formats are available:
+
### mermaid {.compile}
This produces text for a [Mermaid class diagram](https://mermaid.js.org/syntax/classDiagram.html):
@@ -428,6 +444,24 @@ To customize the diagram layout, use these settings in the _Cds > Preview_ categ
- [Diagram: Namespaces](vscode://settings/cds.preview.diagram.namespaces)
- [Diagram: Queries](vscode://settings/cds.preview.diagram.queries)
+## cds watch
+
+Use `cds watch` to watch for changed files, restarting your server.
+
+::: details See the full help text of `cds watch`
+
+:::
+
+### Includes and Excludes
+
+Additional watched or ignored paths can be specified via CLI options:
+
+```sh
+cds watch --include ../other-app --exclude .idea/
+```
+
+Alternatively, you can add these paths through settings cds.watch.include: ["../other-app"] and cds.watch.exclude: [".idea"] to your project configuration.
+
## cds repl