+
@@ -42,10 +59,6 @@ On top of open source technologies, CAP mainly adds:
- **Service SDKs and runtimes** for Node.js and Java, offering libraries to implement and consume services as well as generic provider implementations serving many requests automatically.
-
-
-
-
### Agnostic Design 
+ +
###### Core Data Services (CDS) [CDS](../cds/) is our universal modeling language to capture static, as well as behavioral aspects of problem domains in **conceptual**, **concise**, and **comprehensible** ways, and hence serves as the very backbone of CAP. +
+ ###### Domain Models in CDS -
+
+
+
+
###### CDS Aspects & Mixins
-
+
+```cds
+entity Books : cuid {
+ title : localized String;
+ author : Association to Authors;
+}
+
+entity Orders : cuid, managed {
+ descr : String;
+ Items : Composition of many {
+ book : Association to Books;
+ quantity : Integer;
+ }
+}
+```
+
+
+
+
Domain Models capture static aspects of problem domains as well-known _entity-relationship models_.
@@ -108,9 +149,36 @@ Domain Models capture static aspects of problem domains as well-known _entity-re
**_[Annotations](../cds/cdl#annotations)_** allow enriching models with additional metadata, such as for [UIs](../advanced/fiori), [Validations](../guides/providing-services/#input-validation), [Input Validation](../guides/providing-services/#input-validation) or [Authorization](../guides/authorization).
+
+
+
+
+
+
## Proven Best Practices, Served Out-of-the-Box {#generic-providers label='Proven Best Practices'}
@@ -165,9 +235,12 @@ All data access in CAP is through dynamic queries, which allows clients to reque
> The querying-based approach to process data is in strong contrast to Object-Relational Mapping (→ see also *[Related Concepts: CAP != ORM](related#orm)*)
+
+
+```cds
+// Separation of Concerns
+extend Books with @restrict: [
+ { grant:'WRITE', to:'admin' }
+];
+
+// Verticalization
+extend Books with {
+ ISBN : String
+};
+
+// Customization
+extend Orders with {
+ customer_specific : String
+};
+```
+
+
+
+
**_[Aspects](../cds/cdl#aspects)_** allow to flexibly **extend** models in same or separate modules, packages, or projects; at design time or dynamically at runtime.
@@ -118,7 +186,9 @@ This greatly promotes **[adaptability](../guides/extensibility/)** in _verticali
Moreover, that fosters [**separation of concerns**](../guides/domain-modeling#separation-of-concerns), for example to keep domain models clean and comprehensible, by factoring out technical concerns.
-
+
+
++
###### Core Query Language (CQL) +
+
**[CQL](../cds/cql)** is CDS’s advanced query language. It enhances standard SQL with elements to easily query deeply nested **object graphs** and **document structures**. For example, here's a query in CQL:
```sql
@@ -180,23 +253,71 @@ SELECT Employees.ID, Countries.name FROM Employees
LEFT JOIN Countries AS Countries ON Addresses.country_ID = Countries.ID
```
+
+
++ ###### Queries as first-order Objects (CQN) -
+
+
+
+
###### Projections at Design Time
-
+
+```js
+// In JavaScript code
+orders = await SELECT.from (Orders, o=>{
+ o.ID, o.descr, o.Items (oi=>{
+ oi.book.title, oi.quantity
+ })
+})
+```
+
+```http
+// Via OData
+GET .../Orders?$select=ID,descr
+$expand=Items(
+ $select=book/title,quantity
+)
+```
+
+
+
+
**Queries are first-order objects** – using [CQN](../cds/cqn) as a plain object notation – sent
to **local** services directly,
to **remote** services through protocols like *OData* or *GraphQL*1,
or to **database** services, which translate them to native database queries for optimized execution with **late materialization**.
+
+
+
+
+
+
## Services & Events {#services}
@@ -216,36 +337,111 @@ Services in CAP are **stateless** and with a **minimal footprint**, which allows
+
+```cds
+// Projections in CDS
+service OrdersService {
+ define entity OrderDetails
+ as select from Orders {
+ ID, descr, Items
+ }
+}
+```
+
+
+
+
We also use [CQL](../cds/cql) in CDS to declare [_de-normalized views_](../cds/cdl#views) on the underlying domain model, such as in tailored service APIs.
-
+
++
+ ###### Service Definitions in CDS -
+
+
+
###### Uniform Consumption
-
+
+```cds
+// Service Definition in CDS
+service OrdersService {
+ entity Orders as projection on my.Orders;
+ action cancelOrder (ID:Orders.ID);
+ event orderCanceled : { ID:Orders.ID }
+}
+```
+
+
+
+
Services are declared in CDS models, used to [serve requests automatically](#generic-providers). They embody the behavioral aspects of a domain in terms of exposed **entities**, **actions**, and **events**.
+
+
+
+
+
+
+
+::: tip _[Late-cut µ services](../guides/providing-services/#late-cut-microservices)_
This protocol-agnostic API allows [mocking remote services](../guides/using-services#local-mocking), as well as late changes to service topologies, for example, co-locating services in a single process or deploying them to separate micro services later on.
:::
+
+
+```js
+// Consumption in JavaScript
+let srv = cds.connect.to('OrdersService')
+let { Orders } = srv.entities
+order = await SELECT.one.from (Orders)
+ .where({ ID:4711 })
+srv.cancelOrder (order.ID)
+```
+
+```http
+// Consumption via REST APIs
+GET /orders/Orders/4711
+POST /orders/cancelOrder/4711
+```
+
+
+
+
**Every active thing in CAP is a service**, including *local* services or *remote* ones --- even *databases* are represented as services.
All services provide a **uniform** API for programmatic consumption. Thus, application code stays **agnostic** to underlying protocols.
-::: tip _[Late-cut µ services](../guides/providing-services/#late-cut-microservices)_{.tip-title}
+
+
+###### Ubiquitous Events {#events} -
+
+
+
+
+::: tip _Domain-level Eventing_
Instead of talking to message brokers, services in CAP simply emit events on themselves, and consumers subscribe to events from services. Everything else is handled behind the scenes.
:::
@@ -261,26 +457,22 @@ Over time, you **add things gradually**, only when they’re needed. For example
Finally, projects are encouraged to **parallelize workloads**. For example, following a **contracts-first** approach, a service definition is all that is required to automatically run a full-fledged REST or OData service. So, projects could spawn two teams in parallel: one working on the frontend, while the other one works on the backend part. A third one could start setting up CI/CD and delivery in parallel.
-
+
+```js
+// Service Implementation
+cds.service.impl (function(){
+ this.on ('UPDATE','Orders', (req)=>{})
+ this.on ('cancelOrder', (req)=>{})
+})
+
+
+// Emitting Events
+// e.g. in this.on ('cancelOrder', ...)
+let { ID } = req.data
+this.emit ('orderCancelled', {ID})
+
+
+// Subscribing to Events
+let srv = cds.connect.to('OrdersService')
+srv.on ('orderCancelled', (msg)=>{})
+```
+
+
+
+
**Everything in CAP happens in response to events.** CAP features a ubiquitous notion of events, which represent both, *requests* coming in through **synchronous** APIs, as well as **asynchronous** *event messages*, thus blurring the line between both worlds.
We add custom logic in [event handlers](../guides/providing-services/#event-handlers), registered to **implement** service operations. In the same way, we **subscribe** to asynchronous events emitted by other services.
-::: tip _Domain-level Eventing_{.tip-title}
+
+
+- -## [Related Concepts](./related) {.toc-redirect} +## Related Concepts [Learn more how CAP relates to other concepts.](./related){.learn-more} -## [Features Overview](./features) -{.toc-redirect} +## Features Overview [Get an overview of all features.](./features){.learn-more} -## [Glossary](./glossary) {.toc-redirect} +## Glossary [Glossary of common terms and abbreviations.](./glossary){.learn-more} -
- --- +
1 *GraphQL* and *Kafka* aren’t supported out-of-the-box today, but might be added in future.
diff --git a/advanced/assets/Annotating Entity Elements.md b/advanced/assets/Annotating Entity Elements.md
deleted file mode 100644
index 7382c920b..000000000
--- a/advanced/assets/Annotating Entity Elements.md
+++ /dev/null
@@ -1,44 +0,0 @@
- ### Annotating Entity Elements
-
-1. Place cursor in the `annotate` directive, for example `annotate Foo.Bar with {|};`, add a new line and trigger the code completion. You get the list of entity elements. Choose the one you want to annotate.
-
-#### Sample Code
-
- ```
- annotate Foo.Bar with {
- code|
- };
-
-```
-
-2. Choose ⎵ key and use the code completion again and choose `{} UI`. Micro-snippet `@UI : {|}` is inserted:
-
-#### Sample Code
-
- ```
- annotate Foo.Bar with {
- code @UI : { | }
- };
-
- ```
-
-3. Trigger completion again and choose an annotation term from UI vocabulary, in this example: **Hidden**.
-
-#### Sample Code
-
- ```
- annotate Foo.Bar with {
- code @UI : {Hidden : |}
- };
- ```
-
-4. Choose the **Tab** key to move the cursor to the next tab stop and use the code completion again to add the value. As `UI.Hidden` annotation is of Boolean type, the values true and false is suggested:
-
-#### Sample Code\
-```
- annotate Foo.Bar with {
- code @UI : {Hidden : false }
- };
-
- ```
-
diff --git a/advanced/assets/AnnotatingServiceEntities.md b/advanced/assets/AnnotatingServiceEntities.md
deleted file mode 100644
index c0de3353b..000000000
--- a/advanced/assets/AnnotatingServiceEntities.md
+++ /dev/null
@@ -1,69 +0,0 @@
-### Annotating Service Entities
-
-\(cursor position indicated by `|`\)
-
-1. Place cursor in the `annotate` directive for a service entity, for example `annotate Foo.Bar with ;` and trigger the code completion.
-2. Type `u` to filter the suggestions and choose `{} UI`. Micro-snippet `@UI : {|}` is inserted: `annotate Foo.Bar with @UI : {|};`
-3. Use the code completion again to add an annotation term from UI vocabulary, in this example `SelectionFields`. Micro snippet for this annotation is added and the cursor is placed right after the term name letting you define a qualifier: `annotate Foo.Bar with @UI : {SelectionFields : [|]};`
-4. Press the **Tab** key to move the cursor to the next tab stop and use the code completion again to add values. As `UI.SelectionFields` annotation is a collection of entity elements \(entity properties\), all elements of the annotated entity are suggested.
-
-*Note:* To choose an element of an associated entity, first select the corresponding association from the list and type *. \(period\)*. Elements of associated entity are suggested.
-
-*Note:* You can add multiple values separated by comma.
-
-#### Sample Code
-
-
- ```cds
- annotate Foo.Bar with @UI : { SelectionFields : [
- description, assignedIndividual.lastName|
- ]
- };
- ```
-
-5. Add `, (comma)` after collection brackets **\[\]** and use the code completion again to add another annotation from UI vocabulary, such as `LineItem`. Line item is a collection of DataField records. To add a record, select the record type you need from the completion list.
-
-
-#### Sample Code
-
- ```
- annotate Foo.Bar with @UI : { SelectionFields : [
- description, assignedIndividual.lastName
- ],
- LineItem : [
- {
- $Type:'UI.DataField',
- Value : |,
- },
- ]
-
- };
-
- ```
-*Note:* For each record type, two kinds of micro-snippets are provided: one containing only mandatory properties and one containing all properties defined for this record \(full record\). Usually you need just a subset of properties. So, you either select a full record and then remove the properties you don’t need, or add the record containing only required properties and then add the remaining properties.
-
-6. Use code completion to add values for the annotation properties.
-
-#### Sample Code
-
- ```cds
- annotate Foo.Bar with @UI : { SelectionFields : [
- description, assignedIndividual.lastName
- ],
- LineItem : [
- {
- $Type:'UI.DataField',
- Value : description,
- },
- {
- $Type:'UI.DataFieldForAnnotation',
- Target : 'assignedIndividual/@Communication.Contact',
- },|
- ]
- };
-
- ```
-
-*Note:* To add values pointing to annotations defined in another CDS source, you must reference this source with \`using\` directive.
-For more information, see [The 'using' Directive](../cds/cdl#using).
-
diff --git a/advanced/fiori.md b/advanced/fiori.md
index c583a8940..02f0020b0 100644
--- a/advanced/fiori.md
+++ b/advanced/fiori.md
@@ -359,7 +359,7 @@ entity Foo @(Capabilities:{
}
```
-Similar recommendations apply to `@mandatory` and others → see [Common Annotations].
+Similar recommendations apply to `@mandatory` and others → see [Common Annotations](../cds/annotations#common-annotations).
## Draft-Based Editing {#draft-support}
diff --git a/advanced/odata.md b/advanced/odata.md
index 1f69175ea..47c3374b5 100644
--- a/advanced/odata.md
+++ b/advanced/odata.md
@@ -10,7 +10,7 @@ status: released
+
# Using Databases
-## Reading and Writing Data { .impl.beta}
-
-Use `cds.ql` to read and write data based on CDS models. Its features include:
-
-* Fluent, embedded cql-like language binding, and APIs
-* Statements based on cds models
-* Parallel and serialized execution
-* Automatic parameter binding
-* Nested transactions
-* Connection pooling
-* Driver plugin architecture
-* Canonical representation for queries (→ [CQN](../cds/cqn))
-* Support for SQL as well as NoSQL databases (experimental)
-
-> All the examples in this guide can be executed without further development. For example, run `cds` from your cmd line and just copy and paste the snippets from here to the [REPL](../get-started/in-a-nutshell#repl).
+
## Providing Initial Data { #providing-initial-data}
@@ -159,28 +155,7 @@ That means, even for a valid CDS model, the deployment can fail with respective
### Influencing Persistence Mapping
-#### Using Already Existing Entities {.impl.beta}
-* Use `@cds.persistence.exists` to indicate that an object shouldn’t be created in the database,
- because the database object already exists. The names of the existing object and its columns must exactly
- match the names that would have been generated based on the entity definition.
- One of the common scenarios where this annotation comes in handy is [Using Native SAP HANA Artifacts](../advanced/hana)
- in a CAP application.
-
-* If the entity in the model annotated with `@cds.persistence.exists` represents a user-defined function or a
- calculation view, one of the annotations `@cds.persistence.udf` or `@cds.persistence.calcview` also needs to be assigned. See [Calculated Views and User-Defined Functions](../advanced/hana#calculated-views-and-user-defined-functions) for more details.
-
-#### Skipping Entities {.impl.beta}
-* Use `@cds.persistence.skip` to indicate that an object shouldn’t be created in the database,
- because it’s implemented in the service layer.
-
-#### Views as Tables {.impl.beta}
-* Use `@cds.persistence.table` to create a table with the effective signature of a view definition instead of an SQL view.
- All parts of the view definition not relevant for the signature (like `where`, `group by`, ...) are ignored.
- A common use case for this annotation is in conjunction with the `@cds.persistence.skip` annotation. The `@cds.persistence.skip` annotation is applied automatically
- on all entities imported from third-party services. For example, when an EDMX file from an S/4 system is imported in your
- CAP application, all the entities get the `@cds.persistence.skip` annotation. In order to have the remote entity as a local entity
- in your CAP application and, for example, to cache some data, you would declare a view on
- the imported entity and annotate it with `@cds.persistence: { skip: false, table }`.
+
#### Inserting SQL Snippets
@@ -207,229 +182,7 @@ CREATE TABLE foo_bar_Car_Wheel (
)
```
-### Structured Elements → Flattened Columns {.impl.beta}
-Structured elements in an entity definition are equivalent to a flattened definition of individual columns. For example, the following definition:
-
-```cds
-entity Authors { name: String;
- address { street: String;
- town { name: String; }
- }
-}
-```
-
-unfolds to the following DDL statement:
-
-```sql
-CREATE TABLE Authors (
- name NVARCHAR(5000),
- address_street NVARCHAR(5000),
- address_town_name NVARCHAR(5000)
-)
-```
-
-Correspondingly, the following CQL queries using [_Path Expressions_](../cds/cql#path-expressions) along structs:
-
-```sql
-SELECT name, address.street from Authors;
-SELECT name, address.town.name from Authors;
-SELECT name, address.* from Authors;
-```
-
-map to these plain SQL `SELECT` statements:
-
-```sql
-SELECT name, address_street from Authors;
-SELECT name, address_town_name from Authors;
-SELECT name, address_street, address_town_name from Authors;
-```
-
-> See [_Postfix Projections_](../cds/cql#postfix-projections) for additional means to query struct elements.
-
-### Associations → Forward-Declared JOINs {#associations.impl.beta}
-
-Associations introduce forward-declared Joins. Their names act like corresponding table aliases in queries. In addition, managed associations automatically add foreign keys. For example:
-
-```cds
-entity Books {
- title : String;
- author : Association to Authors;
-}
-entity Authors {
- key ID : UUID;
- name : String;
- address : Association to Addresses;
- books : Association to many Books;
-}
-entity Addresses {
- key ID : UUID;
- town : Association to Towns;
-}
-entity Towns {
- key ID : UUID;
- name : String;
-}
-```
-
-unfolds to the following SQL DDL statements with native support for associations (as referenced in the SAP HANA SQL Reference Guide with the release of SAP HANA Platform 2.0 SPS 00):
-
-```sql
-CREATE TABLE Books (
- title varchar(111),
- author_ID varchar(36) -- foreign key for managed assoc
-) WITH ASSOCIATIONS (
- JOIN Authors as author ON author.ID = author_ID -- to-one
-);
-
-CREATE TABLE Authors (
- ID varchar(36),
- name varchar(111),
- address_ID varchar(36) -- foreign key for managed assoc
-) WITH ASSOCIATIONS (
- JOIN Addresses as address ON address.ID = address_ID,
- JOIN Books as books ON books.author_ID = ID -- to-many
-);
-
-CREATE TABLE Addresses (
- ID varchar(36),
- town_ID varchar(36) -- foreign key for managed assoc
-) WITH ASSOCIATIONS (
- JOIN Towns as town ON town.ID = town_ID
-);
-
-CREATE TABLE Towns (
- ID varchar(36),
- name varchar(111)
-);
-```
-
-## Feature Comparison { .impl.beta}
-
-SAP HANA is the primary database of choice for productive use and supports the richer feature set. However, we aim for a close to equally rich feature set on other databases to support lightweight local development. The following sections detail known gaps and limitations.
-
-### Path Expressions
-
-Path expressions including infix filters can be used as described in the [CQL](../cds/cql#path-expressions) documentation.
-
-The CAP Java SDK supports [path expressions](../java/query-api#path-expressions) on HANA, H2, SQLite and PostgreSQL.
-
-HANA supports path expressions natively. On other DBs, additional joins are needed, which the Node.js runtime does not yet generate. Hence, path expressions are only supported on HANA. Exception: key properties of association to one, such that base entity has property as foreign key. then, *path-expression-like* constructs can be used on sqlite as well, for example, `GET /Books?$orderby=author/ID` works because Books has `author_ID`
-
-
-path expressions are used in:
-- ql where/ order by/ etc. -> as documented in [CQL guide](../cds/cql)
-- odata/ "sap-style rest" query options like $filter, et al.
-
-#### HANA
-
-- **Java** + **Node.js**: full support
-
-#### SQLite
-
-
-### Where Exists Predicates
-
-The CAP Java SDK supports [where exists](../java/query-api#exists-subquery) subqueries as well as [any/allMatch](../java/query-api#any-match) predicates on HANA, H2, SQLite and PostgreSQL.
-
-- Java supports path expressions including infix filters as documented in TODO also for SQLite
- + Note: no paths within infix filters (PR #2969) -> same limitation in compiler
-- Node.js allows one-level path expressions referring to target primary keys of managed associations -> are handled like structs
- + example: `GET /Books?$orderby=author/ID`
-
--> intro with link to CQL doc section
--> to be checked: same and all supported wrt HANA, SQLite, Java, Node.js
--> the restrictions, if any, re Path Expressions apply
-
-### Locale
-
-The CAP Java SDK supports [localized elements](localized-data) on HANA, H2, SQLite and PostgreSQL.
-
-If all views expose the [localized](localized-data#resolving-localized-texts-at-runtime) association, there are no restrictions on H2, SQLite and PostgreSQL. In case localized is not exposed, a system property `supported_locales` with the supported language codes has to be set:
-
-```java
- System.setProperty("supported_locales","en,fr,es,it");
-```
-
-[locale](localized-data#propagating-of-user-locale)
-
-- **Java** + **Node.js** for **HANA**: full support
-- **Java** for **SQLite**:
- + if localized assoc is available (i.e. propagated in view) CAP Java SDK sets locales dynamically (by-passing SQL views generated by compiler)
- + fallback: as in case of Node.js described below:
-- **Node.js** for **SQLite**: only for static set of locales (de,en,fr) -> requires statically created SQL views à la localized_..._de
- + on sqlite, an additional view is needed for each locale (`en` texts get written to the original table) -> extra config needed but no limitation
- + cf. [localized views](localized-data#resolving-localized-texts-via-views)
-
-
-### Session variables
-
-The CAP Java SDK has full support for session variables such as `$user.id`, `$user.locale` and `$now` on HANA. On H2, SQLite and PostgreSQL, session variables are not supported in views but only in `where` clauses of [CQL](../cds/cql) queries and `on` conditions of associations.
-
-- **Node.js** for **HANA**: full support
-- **Node.js** for **SQLite**: single static user configurable via compiler's magic vars
-
-
-### Temporal Data
-
-On databases other than HANA, only [as-of-now-queries](temporal-data#as-of-now-queries) are supported.
-
-- **Node.js**: temporal data impl requires session contexts, which are not available on sqlite. in the future, the runtimes will most likely use special where clauses, which would make temporal data available on any db. currently, SQLite is always "as of now".
-
-### Multiuser
-
-The CAP Java SDK supports connection pooling and pessimistic locking via [select for update](../java/query-execution#pessimistic-locking)
-for HANA, H2 and PostgreSQL.
-
-Although connection pooling can be configured for SQLite, we recommend to set the `maximum-pool-size` to 1, due to the limited concurrency support in SQLite.
-
-
-- **Node.js** for **HANA**: full support
-- **Node.js** for **SQLite**: no support
- + sqlite feature that would allow concurrency: https://www.sqlite.org/cgi/src/doc/begin-concurrent/doc/begin_concurrent.md -> once that is delivered, we can implement
- + [select for update](providing-services/#select-for-update) simply executes a select
-
-
-### Multitenancy
-
-The CAP Java SDK supports testing multitenant scenarios with PostgreSQL and H2. // with Aug release -> MT lib Frank
-
-
-### Functions
-
-The CAP Java SDK supports [scalar](../java/query-api#scalar-functions) and [predicate](../java/query-api#predicate-functions) functions on HANA, H2, SQLite and PostgreSQL.
-
-__TODO: check which odata funcs to take over in cqn__
-
-__TODO: Java?__
-
-
-- **Node.js** for **HANA**: `ceiling`, `floor`, `round`
-- **Node.js** for **SQLite**: `round` only
-
-### locale-dependent sorting
-
-- for **HANA**: via `WITH PARAMETERS ('LOCALE' = '+## cds.import.from.asyncapi (file) → [csn](../cds/csn) { #import-from-asyncapi } + +This API can be used to convert the AsyncAPI specification file (JSON) into CSN. +The API signature looks like this: +```js +const csn = await cds.import.from.asyncapi(AsyncAPI_JSON_file) +``` +
+ Example: ```js @@ -100,10 +109,14 @@ module.exports = async (srv) => { cds.import('./odata_sample.edmx', { includeNamespaces: 'sap,c4c', keepNamespace: true }), // for openapi cds.import('./openapi_sample.json'), + // for asyncapi + cds.import('./asyncapi_sample.json'), // for odata cds.import.from.edmx('./odata_sample.xml', { includeNamespaces: '*', keepNamespace: false }), // for openapi cds.import.from.openapi('./openapi_sample.json') + // for asyncapi + cds.import.from.asyncapi('./asyncapi_sample.json') ]); for (let i = 0; i < csns.length; i++) { @@ -129,3 +142,4 @@ The following mapping is used during the import of an external service API, see | _Edm.DateTime
Precision : Second_ 1 | `cds.DateTime` + `@odata.Type:'Edm.DateTime'` + `@odata.Precision:0` | 1 only OData V2 + diff --git a/node.js/cds-env.md b/node.js/cds-env.md index 13658be96..aa7af3ae0 100644 --- a/node.js/cds-env.md +++ b/node.js/cds-env.md @@ -1,7 +1,7 @@ --- label: Configuration synopsis: > - Learn here about using `cds.env` to specify and access configuration options for the Node.js runtimes as well as the `@sap/cds-dk` CLI commands. + Learn here about using
cds.env to specify and access configuration options for the Node.js runtimes as well as the `@sap/cds-dk` CLI commands.
status: released
---
@@ -9,20 +9,15 @@ status: released
# Project-Specific Configurations
-
+ -->
-
-
-
-
-
## CLI `cds env` Command {#cli}
Run the `cds env` command in the root folder of your project to see the effective configuration.
@@ -44,14 +39,14 @@ cds env ? #> get help
For example:
-$ cds env ls requires.sql +$ cds env ls requires.sql requires.sql.credentials.database = :memory: requires.sql.impl = @sap/cds/lib/db/sql-service requires.sql.kind = sqlite
-$ cds env get requires.sql
+$ cds env get requires.sql
{
credentials: { database: ':memory:' },
impl: '@sap/cds/lib/db/sql-service',
@@ -63,7 +58,7 @@ $ cds env get requires.sql
Alternatively, you can also use the `cds eval` or `cds repl` CLI commands to access the `cds.env` property, which provides programmatic access to the effective settings:
-$ cds -e .env.requires.sql
+$ cds -e .env.requires.sql
{
credentials: { database: ':memory:' },
impl: '@sap/cds/lib/db/sql-service',
@@ -72,7 +67,7 @@ $ cds -e .env.requires.sql
-$ cds -r
+$ cds -r
Welcome to cds repl v4.0.1
> cds.env.requires.sql
{
@@ -126,8 +121,8 @@ The settings are merged into `cds.env` starting from lower to higher order. Mean
For example, given the following sources:
-```jsonc
-// cdsrc.json
+::: code-group
+```jsonc [cdsrc.json]
{
"requires": {
"db": {
@@ -138,9 +133,10 @@ For example, given the following sources:
}
}
```
+:::
-```jsonc
-// package.json
+::: code-group
+```jsonc [package.json]
{
"cds": {
"requires": {
@@ -151,11 +147,13 @@ For example, given the following sources:
}
}
```
+:::
-```properties
-# env.properties
+::: code-group
+```properties [env.properties]
cds.requires.db.credentials.database = my.db
```
+:::
This would result in the following effective configuration:
```js
@@ -362,7 +360,9 @@ You can use the `kind` property to reference other services for prototype chaini
> CDS provides default service configurations for all supported services (`hana`, `enterprise-messaging`, ...).
Example:
-```json
+
+::: code-group
+```json [package.json]
{
"cds": {
"requires": {
@@ -379,6 +379,7 @@ Example:
}
}
```
+:::
`serviceA` will have the following properties:
@@ -397,7 +398,8 @@ Example:
Wrap entries into `[]:{ ... }` to provide settings for different environments. For example:
-```json
+::: code-group
+```json [package.json]
{
"cds": {
"requires": {
@@ -409,6 +411,7 @@ Wrap entries into `[]:{ ... }` to provide settings for different e
}
}
```
+:::
The profile is determined at bootstrap time as follows:
@@ -446,13 +449,17 @@ cds run
You can use the same machinery as documented above for app-specific configuration options:
-```json
+::: code-group
+
+```json [package.json]
"cds": { ... },
-"my-app": { ... }
+"my-app": { "myoption": "value" }
```
+:::
+
And access them from your app as follows:
```js
-const conf = cds.env('my-app')
+const { myoption } = cds.env.for('my-app')
```
diff --git a/node.js/cds-i18n.md b/node.js/cds-i18n.md
new file mode 100644
index 000000000..da36f7791
--- /dev/null
+++ b/node.js/cds-i18n.md
@@ -0,0 +1,92 @@
+# Localization / i18n
+
+##
+
+### Generic Errors
+
+You can provide localized error messages for a [growing number of runtime errors](#list-of-generic-texts). To do so, they simply need to provide `messages_.properties` files into one of the valid, model-unrelated text bundles folders. That is, as these texts aren’t model related, the properties files are only searched for in the folders listed in `cds.env.i18n.folders` and not next to any model. The first matching file is used. See [Where to Place Text Bundles?](../guides/i18n#where-to-place-text-bundles) for more details.
+
+Example:
+
+```js
+// i18n/messages_en.properties
+MULTIPLE_ERRORS=Multiple errors occurred.
+
+[...]
+
+// i18n/messages_de.properties
+MULTIPLE_ERRORS=Es sind mehrere Fehler aufgetreten.
+
+[...]
+```
+
+{ style="padding: 0 33px"}
+
+
+### Custom Errors
+
+You can define custom texts (incl. placeholders) and use them in the message API [`req.reject/error/info/warn(...)`](./events#cds-request). The respective text key is provided instead of the string message, and optional array of placeholder values are passed as the last parameter. Placeholder values can again be text keys in order to enable translatable text fragments.
+
+Example:
+
+```js
+// i18n/messages_en.properties
+ORDER_EXCEEDS_STOCK=The order of {0} books exceeds the stock by {1}
+
+[...]
+
+// srv/catalog-service.js
+const cds = require('@sap/cds')
+
+module.exports = (srv) => {
+ const { Books, Orders } = srv.entities
+
+ srv.before('CREATE', Orders, async (req) => {
+ const book = await SELECT.one(Books).where({ ID: req.data.book_ID })
+ if (book.stock < req.data.quantity) {
+ req.reject(400, 'ORDER_EXCEEDS_STOCK', [req.data.quantity, req.data.quantity - book.stock])
+ }
+ })
+}
+```
+
+{ style="padding: 0 33px"}
+
+
+### List of Generic Texts
+
+Find the current list of generic runtime texts:
+
+```
+400=Bad Request
+401=Unauthorized
+403=Forbidden
+404=Not Found
+405=Method Not Allowed
+406=Not Acceptable
+407=Proxy Authentication Required
+408=Request Timeout
+409=Conflict
+410=Gone
+411=Length Required
+412=Precondition Failed
+413=Payload Too Large
+414=URI Too Long
+415=Unsupported Media Type
+416=Range Not Satisfiable
+417=Expectation Failed
+424=Failed Dependency
+428=Precondition Required
+429=Too Many Requests
+431=Request Header Fields Too Large
+451=Unavailable For Legal Reasons
+500=Internal Server Error
+501=The server does not support the functionality required to
+fulfill the request
+502=Bad Gateway
+503=Service Unavailable
+504=Gateway Timeout
+
+MULTIPLE_ERRORS=Multiple errors occurred. See the details for more information.
+```
+
diff --git a/node.js/cds-log.md b/node.js/cds-log.md
index d68f8a6fe..27ece26a0 100644
--- a/node.js/cds-log.md
+++ b/node.js/cds-log.md
@@ -382,58 +382,7 @@ The following screenshot shows the log output for the rejection in the previous
{adapt}
-
-#### *Including Custom Fields* { .impl.beta}
-
-To show additional information (that is, information that is not included in the [list of supported fields](https://help.sap.com/docs/APPLICATION_LOGGING/ee8e8a203e024bbb8c8c2d03fce527dc/48b726c3f7534285b05eb31b5b7dc14d.html) of the SAP Application Logging Service), it needs to be provided in the following form:
-
-```js
-{
- [...],
- '#cf': {
- strings: [
- { k: '', v: '', i: },
- [...]
- ]
- }
-}
-```
-
-The information is rendered as follows:
-
-```
-custom.string.key0:
-custom.string.value0:
-```
-
-Up to 20 custom fields can be provided using this mechanism. The advantage of this approach is that the additional information can be indexed. The drawback, next to it being cumbersome, is that the indexes should be kept stable.
-
-By default, the Kibana-friendly formatter uses the following custom fields configuration (configurable via [cds.env](cds-env)):
-
-```js
-{
- log: {
- kibana_custom_fields: { // > :
- // sql
- query: 0,
- // generic validations
- target: 1,
- details: 2
- }
- }
-}
-```
-
-With the default settings and in a more practical example, the log would look something like this:
-
-```
-msg: SQL Error: Unknown column "IDONTEXIST" in table "DUMMY"
-[...]
-custom.string.key0: query
-custom.string.value0: SELECT IDONTEXIST FROM DUMMY
-```
-
-Without the additional custom field `query` and it's respective value, it would first be necessary to reproduce the issue locally to know what the faulty statement is.
+
## Request Correlation { #node-observability-correlation }
diff --git a/node.js/cds-ql.md b/node.js/cds-ql.md
index e1f0e54b6..aa7cdc900 100644
--- a/node.js/cds-ql.md
+++ b/node.js/cds-ql.md
@@ -29,7 +29,7 @@ const q = SELECT.from('Foo') //> using local variable
## Constructing Queries
-You can choose between two primary styles to construct queries: A [SQL-like fluent API](#fluent-api) style provided by `cds.ql` or a call-level [Querying API provided by `cds.Service`](services#srv-run). The lines between both blur, as the latter is actually just a shortcut to the former. This is especially true when combining both with the use of [tagged template string literals](#tts).
+You can choose between two primary styles to construct queries: A [SQL-like fluent API](#fluent-api) style provided by `cds.ql` or a call-level [Querying API provided by `cds.Service`](core-services#srv-run-query). The lines between both blur, as the latter is actually just a shortcut to the former. This is especially true when combining both with the use of [tagged template string literals](#tts).
@@ -53,7 +53,7 @@ While both, [CQN](../cds/cqn) as well as the [fluent API](#fluent-api) resemble
### Using Service APIs plus Fluent APIs {#service-api}
-The following uses [the Querying API provided by `cds.Service`](services#srv-run) to construct exactly the same effective queries as the ones constructed with the fluent API above:
+The following uses [the Querying API provided by `cds.Service`](core-services#srv-run-query) to construct exactly the same effective queries as the ones constructed with the fluent API above:
```js
let q1 = cds.read('Books',201)
@@ -62,7 +62,7 @@ let q3 = cds.update('Books',201,{title:'Sturmhöhe'})
let q4 = cds.delete('Books',201)
```
-[As documented in the `cds.Services` API](services#convenient-shortcuts) docs, these methods are actually just shortcuts to the respective Fluent API methods above, and can be continued with calls to fluent API function, thus blurring the lines. For example, also these lines are equivalent to both variants above:
+[As documented in the `cds.Services` API](core-services#crud-style-api) docs, these methods are actually just shortcuts to the respective Fluent API methods above, and can be continued with calls to fluent API function, thus blurring the lines. For example, also these lines are equivalent to both variants above:
```js
@@ -111,17 +111,17 @@ let q3 = UPDATE (Books) .where `ID=${201}` .with `title=${'Sturmhöhe'}`
let q4 = DELETE.from (Books) .where `ID=${201}`
```
-[Learn more about using reflected definitions from a service's model](services#srv-entities){.learn-more}
+[Learn more about using reflected definitions from a service's model](core-services#entities){.learn-more}
## Executing Queries
-Essentially queries are executed by passing them to a service's [`srv.run`](services#srv-run) method. Most frequently, you can also just use `await` on a query to do so.
+Essentially queries are executed by passing them to a service's [`srv.run`](core-services#srv-run-query) method. Most frequently, you can also just use `await` on a query to do so.
### Passing Queries to `srv.run(...)`
-The basic mechanism to execute a query is to pass it to a [`srv.run`](services#srv-run) method.
+The basic mechanism to execute a query is to pass it to a [`srv.run`](core-services#srv-run-query) method.
For example, using the primary database service `cds.db`:
```sql
@@ -181,7 +181,7 @@ let books = await cats.run (SELECT `ID,title` .from (Books))
### With Bound Queries from `srv.`
-Finally, when using the [CRUD-style Service Querying APIs](services#srv-run), the constructed queries returned by the respective methods are bound to the originating service, and will be sent to that service's `srv.run()` method upon `await`. Hence these samples are equivalent:
+Finally, when using the [CRUD-style Service Querying APIs](core-services#srv-run-query), the constructed queries returned by the respective methods are bound to the originating service, and will be sent to that service's `srv.run()` method upon `await`. Hence these samples are equivalent:
```js
let books = await srv.read `ID,title` .from `Books`
diff --git a/node.js/cds-reflect.md b/node.js/cds-reflect.md
index f29fb001e..9f555313d 100644
--- a/node.js/cds-reflect.md
+++ b/node.js/cds-reflect.md
@@ -194,16 +194,7 @@ m.forall (d => {
})
```
-
-
-### m.minified (level) {#minified .impl.beta}
-
-Minimizes a loaded model ...
-TODO:
-- explain how it works
-- explain when it is applied
-
-
+
## cds.builtin.**classes** {#cds-builtin-classes}
@@ -480,4 +471,3 @@ const roots = module.exports = {definitions:{
}}
```
> Indentation indicates inheritance.
-
diff --git a/node.js/cds-serve.md b/node.js/cds-serve.md
index a1b2af13e..3c55719f7 100644
--- a/node.js/cds-serve.md
+++ b/node.js/cds-serve.md
@@ -47,38 +47,30 @@ Its implementation essentially is as follows:
```js
const cds = require('@sap/cds')
-const express = require('express')
-module.exports = async function cds_server (options) {
-
- const _in_prod = process.env.NODE_ENV === 'production'
- const o = { ...options, __proto__:defaults }
-
- const app = cds.app = o.app || express()
- app.serve = _app_serve //> app.serve allows delegating to sub modules
- cds.emit ('bootstrap',app) //> hook for project-local server.js
-
- // mount static resources and logger middleware
- if (o.cors) !_in_prod && app.use (o.cors) //> CORS
- if (o.static) app.use (express_static (o.static)) //> defaults to ./app
- if (o.favicon) app.use ('/favicon.ico', o.favicon) //> if none in ./app
- if (o.index) app.get ('/',o.index) //> if none in ./app
- if (o.correlate) app.use (o.correlate) //> request correlation
+cds.server = module.exports = async function (options) {
+
+ const app = cds.app = o.app || require('express')()
+ cds.emit ('bootstrap', app)
- // load specified models or all in project
- const csn = await cds.load(o.from||'*',o) .then (cds.minify) //> separate csn for _init_db
+ // load model from all sources
+ const csn = await cds.load('*')
cds.model = cds.compile.for.nodejs(csn)
-
- // connect to essential framework services if required
- if (cds.requires.db) cds.db = await cds.connect.to ('db') .then (_init)
- if (cds.requires.messaging) await cds.connect.to ('messaging')
-
- // serve all services declared in models
- await cds.serve (o.service,o) .in (app)
- await cds.emit ('served', cds.services) //> hook for listeners
-
- // start http server
- const port = (o.port !== undefined) ? o.port : (process.env.PORT || cds.env.server?.port || 4004)
- return app.listen (port)
+ cds.emit ('loaded', cds.model)
+
+ // connect to prominent required services
+ if (cds.requires.db) cds.db = await cds.connect.to ('db')
+ if (cds.requires.messaging) await cds.connect.to ('messaging')
+
+ // serve own services as declared in model
+ await cds.serve ('all') .from(csn) .in (app)
+ await cds.emit ('served', cds.services)
+
+ // launch http server
+ cds .emit ('launching', app)
+ const port = o.port ?? process.env.PORT || 4004
+ const server = app.server = app.listen(port) .once ('listening', ()=>
+ cds.emit('listening', { server, url: `http://localhost:${port}` })
+ )
}
```
@@ -171,17 +163,44 @@ cds.on('served', (services)=>{
A one-time event, emitted when the server has been started and is listening to incoming requests.
-### cds.once ('**shutdown**', ()=>{}) { .impl.beta}
-
-A one-time event, emitted when the server is closed and/or the process finishes. Listeners can execute cleanup tasks.
-
-
+
## cds.serve... → [service](../cds/cdl#services)\(s\) {#cds-serve}
Use `cds.serve()` to construct service providers from the service definitions in corresponding CDS models. As stated above, this is usually [done automatically by the built-in `cds.server`](#built-in-server-js).
+Declaration:
+
+```ts:no-line-numbers
+async function cds.serve (
+ service : 'all' | string | cds.Service | typeof cds.Service,
+ options : { service = 'all', ... }
+) .from ( model : string | CSN ) // default: cds.model
+ .to ( protocol : string | 'rest' | 'odata' | 'odata-v2' | 'odata-v4' | ... )
+ .at ( path : string )
+ .in ( app : express.Application ) // default: cds.app
+.with ( impl : string | function | cds.Service | typeof cds.Service )
+```
+
+### cds. services {.property}
+
+All service instances constructed by `cds.connect()` or by `cds.serve()`are registered in the `cds.services` dictionary. After the bootstrapping phase you can safely refer to entries in there:
+
+```js
+const { CatalogService } = cds.services
+```
+
+Use this if you are not sure whether a service is already constructed:
+
+```js
+const CatalogService = await cds.connect.to('CatalogService')
+```
+
+
+
+
+
### cds.serve (service, options) ⇢ fluent api...
Initiates a fluent API chain to construct service providers; use the methods documented below to add more options.
@@ -301,7 +320,7 @@ cds.serve('CatalogService').at('/cat')
cds.serve('all').at('/cat') //> error
```
-**If omitted**, the mount point is determined from [annotation `@path`](services#srv-path), if present, or from the service's lowercase name, excluding trailing _Service_.
+**If omitted**, the mount point is determined from annotation `@path`, if present, or from the service's lowercase name, excluding trailing _Service_.
```cds
service MyService @(path:'/cat'){...} //> served at: /cat
@@ -348,8 +367,8 @@ cds.serve('./srv/cat-service') .with (srv => {
})
```
-[Learn more about using impl annotations.](services#srv-impl){.learn-more}
-[Learn more about adding event handlers.](services#event-handlers){.learn-more}
+[Learn more about using impl annotations.](core-services#implementing-services){.learn-more}
+[Learn more about adding event handlers.](core-services#srv-on-before-after){.learn-more}
**Note** that this is only possible when constructing single services:
diff --git a/node.js/cds-test.md b/node.js/cds-test.md
index 66739e97b..8cf2c4d53 100644
--- a/node.js/cds-test.md
+++ b/node.js/cds-test.md
@@ -97,7 +97,7 @@ To get a completely clutter-free log, check out the test runners for such a feat
## Testing Service APIs
-As `cds.test()` launches the server in the current process, you can access all services programmatically using the respective [Node.js APIs](services).
+As `cds.test()` launches the server in the current process, you can access all services programmatically using the respective [Node.js APIs](core-services).
Here is an example for that taken from [cap/samples](https://github.com/SAP-samples/cloud-cap-samples/blob/a8345122ea5e32f4316fe8faef9448b53bd097d4/test/consuming-services.test.js#L2):
```js
@@ -265,7 +265,7 @@ Data can be supplied:
-This following example shows how data can be inserted into the database using regular [CDS service APIs](services#srv-run) (using [CQL INSERT](cds-ql#INSERT) under the hood):
+This following example shows how data can be inserted into the database using regular [CDS service APIs](core-services#srv-run-query) (using [CQL INSERT](cds-ql#INSERT) under the hood):
```js
beforeAll(async () => {
diff --git a/node.js/core-services.md b/node.js/core-services.md
new file mode 100644
index 000000000..532250ba9
--- /dev/null
+++ b/node.js/core-services.md
@@ -0,0 +1,1120 @@
+---
+status: released
+uacp: This page is linked from the Help Portal at https://help.sap.com/products/BTP/65de2977205c403bbc107264b8eccf4b/29c25e504fdb4752b0383d3c407f52a6.html
+---
+
+# Core Services
+
+
+
+::: tip
+This is an overhauled documentation for `cds.Service`→ find the old one [here](services.md).
+:::
+
+
+
+[[toc]]
+
+
+
+## Provided Services
+
+A CAP application mainly consists of the services it provides to clients. Such *provided services* are commonly declared through service definitions in CDS, and served automatically during bootstrapping as follows...
+
+
+
+#### CDS-Modeling *Provided* Services
+
+For example, a simplified all-in-one variant of [*cap/samples/bookshop/srv/cat-service.cds*](https://github.com/SAP-samples/cloud-cap-samples/blob/main/bookshop/srv/cat-service.cds):
+
+```cds
+using { User, sap.capire.bookshop as my } from '../db/schema';
+service CatalogService {
+ entity Books {
+ key ID : UUID;
+ title : String;
+ descr : String;
+ author : Association to my.Authors;
+ }
+ action submitOrder ( book: UUID, quantity: Integer );
+ event OrderedBook: { book: UUID; quantity: Integer; buyer: User }
+}
+```
+
+[Learn more about defining services using CDS](../guides/providing-services/) {.learn-more}
+
+
+
+#### Serving Provided Services → `cds.serve`
+
+When starting a server with `cds watch` or `cds run` this uses `cds.serve` to automatically create instances of `cds.Service` for all such service definitions found in our models, and serve them to respective endpoints via corresponding protocols.
+
+In essence, the built-in bootstrapping logic works like that:
+
+```js
+cds.app = require('express')()
+cds.model = await cds.load('*')
+cds.services = await cds.serve('all').from(cds.model).in(cds.app)
+```
+
+[Learn more about `cds.serve`](cds-serve) {.learn-more}
+
+
+
+
+
+## Required Services
+
+In addition to provided services, your applications commonly need to consume *required services*. Most prominent example for that is the primary database `cds.db`. Others could be application services provided by other enterprise applications or micro services, or other platform services, such as secondary databases or message brokers.
+
+
+
+#### Configuring *Required* Services
+
+We need to configure required services with `cds.requires.<...>` config options. These configurations act like sockets for service bindings to fill in missing credentials later on.
+
+::: code-group
+
+```json [package.json]
+{"cds":{
+ "requires": {
+ "ReviewsService": { "kind": "odata", "model": "@capire/reviews" },
+ "db": { "kind": "sqlite", "credentials": { "url":"db.sqlite" }},
+ }
+}}
+```
+:::
+
+*Learn more about [configuring required services](cds-connect#cds-env-requires) and [service bindings](cds-connect#service-bindings)* {.learn-more}
+
+
+
+#### Connecting to Required Services → `cds.connect`
+
+Given such configurations, we can connect to the configured services like so:
+
+```js
+const ReviewsService = await cds.connect.to('ReviewsService')
+const db = await cds.connect.to('db')
+```
+
+[Learn more about `cds.connect`](cds-connect) {.learn-more}
+
+
+
+
+
+## Implementing Services
+
+By default `cds.serve` creates instances of `cds.ApplicationService` for each found service definition, which provides generic implementations for all CRUD operations, including full support for deep document structures, declarative input validation and many other out-of-the-box features. Yet, you'd likely need to provide domain-specific custom logic, especially for custom actions and functions, or for custom validations. Learn below about:
+
+- **How** to provide custom implementations?
+- **Where**, that is, in which files, to put that?
+
+
+
+#### In sibling `.js` files, next to `.cds` sources
+
+The easiest way to add custom service implementations is to simply place an equally named `.js` file next to the `.cds` file containing the respective service definition. For example, as in [*cap/samples/bookshop*](https://github.com/SAP-samples/cloud-cap-samples/blob/main/bookshop/):
+
+```zsh
+bookshop/
+├─ srv/
+│ ├─ admin-service.cds
+│ ├─ admin-service.js
+│ ├─ cat-service.cds // [!code focus]
+│ └─ cat-service.js // [!code focus]
+└─ ...
+```
+
+::: details Alternatively in subfolders `lib/` or `handlers/`...
+
+ In addition to direct neighbourhood you can place your impl files also in nested subfolders `lib/` or `handlers/` like that:
+
+```zsh
+bookshop/
+├─ srv/
+│ └─ lib/ # or handlers/ // [!code focus]
+│ │ ├─ admin-service.js
+│ │ └─ cat-service.js
+│ ├─ admin-service.cds
+│ └─ cat-service.cds
+└─ ...
+```
+
+:::
+
+
+
+#### Specified by `@impl` Annotation, or `impl` Configuration
+
+You can explicitly specify sources for service implementations using...
+
+The `@impl` annotation in CDS definitions for [provided services](#provided-services):
+
+::: code-group
+
+```cds [srv/cat-service.cds]
+@impl: 'srv/cat-service.js' // [!code focus]
+service CatalogService { ... }
+```
+
+:::
+
+The `impl` configuration property for [required services](#required-services):
+
+::: code-group
+
+```json [package.json]
+{ "cds": {
+ "requires": {
+ "ReviewsService": {
+ "impl": "srv/reviews-services.js" // [!code focus]
+ }
+ }
+}}
+```
+
+:::
+
+
+
+
+
+#### How to provide custom service implementations?
+
+Implement your custom logic as a subclass of `cds.Service`, or more commonly of `cds.ApplicationService` to benefit from generic out-of-the-box implementations. The actual implementation goes into event handlers, commonly registered in method [`srv.init()`](#srv-init):
+
+```js
+class BooksService extends cds.ApplicationService {
+ init() {
+ const { Books, Authors } = this.entities
+ this.before ('READ', Authors, req => {...})
+ this.after ('READ', Books, req => {...})
+ this.on ('submitOrder', req => {...})
+ return super.init()
+ }
+}
+module.exports = BooksService
+```
+
+[Learn more about `cds.ApplicationService`](app-services) {.learn-more}
+
+::: details Alternatively using old-style `cds.service.impl` functions...
+
+As an alternative to providing subclasses of `cds.Service` as service implementations, you can simply provide a single function like so:
+
+```js
+const cds = require('@sap/cds')
+module.exports = cds.service.impl (function(){ ... }) // [!code focus]
+```
+
+> Note: `cds.service.impl()` is just a noop wrapper that enables [IntelliSense in VSCode](https://code.visualstudio.com/docs/editor/intellisense).
+
+This will be translated behind the scenes to the equivalent of this:
+
+```js
+const cds = require('@sap/cds')
+module.exports = new class extends cds.ApplicationService {
+ async init() {
+ await srv_impl_fn .call (this,this) // [!code focus]
+ return super.init()
+ }
+}
+```
+
+:::
+
+::: details Multiple implementations in one file...
+
+In case you have multiple service definition is one `.cds` file like that:
+
+```cds
+// services.cds
+namespace foo.bar;
+service Foo {...}
+service Bar {...}
+```
+
+... you may also want to have multiple implementations provided through one corresponding `.js` file. Simply do so by by having multiple exports like that:
+
+```js
+// services.js
+exports['foo.bar.Foo'] = class Foo {...}
+exports['foo.bar.Boo'] = class Bar {...}
+```
+
+The exports' names must **match the servce definitions' fully-qualified names**.
+
+:::
+
+
+
+## Consuming Services
+
+Given access to a service instance — for example, through `cds.connect` — we can send requests, queries or asynchronously processed event messages to it:
+
+```js
+const srv = await cds.connect.to ('BooksService')
+```
+
+[Using REST-style APIs](#rest-style-api):
+
+```js
+await srv.create ('/Books', { title: 'Catweazle' })
+await srv.read ('GET','/Books/206')
+await srv.send ('submitOrder', { book:206, quantity:1 })
+```
+
+[Using typed APIs for actions and functions](../guides/providing-services/#calling-actions-or-functions):
+
+```js
+await srv.submitOrder({ book:206, quantity:1 })
+await srv.submitOrder(206,1)
+```
+
+[Using Query-style APIs](#srv-run-query):
+
+```js
+await srv.run( INSERT.into(Books).entries({ title: 'Wuthering Heights' }) )
+await srv.run( SELECT.from(Books,201) )
+await srv.run( UPDATE(Books,201).with({stock:111}) )
+await srv.run( UPDATE(Books).set({discount:'10%'}).where({stock:{'>':111}}) )
+```
+[Same with CRUD-style convenience APIs](#crud-style-api):
+
+```js
+await srv.create(Books).entries({ title: 'Wuthering Heights' })
+await srv.read(Books,201)
+await srv.update(Books,201).with({stock:111})
+await srv.update(Books).set({discount:'10%'}).where({stock:{'>':111}})
+```
+
+[Emitting Asynchronous Event Messsages:](#srv-emit-event)
+
+```js
+await srv.emit ('SomeEvent', {foo:'bar'})
+```
+
+```js
+await srv.emit ({ event: 'OrderedBooks', data: {
+ book: 206, quantity: 1,
+ buyer: 'alice@wonderland.com'
+}})
+```
+```js
+await srv.emit ('OrderedBooks', {
+ book: 206, quantity: 1,
+ buyer: 'alice@wonderland.com'
+})
+```
+
+
+
+::: tip Prefer Platform-Agnostic APIs
+
+REST-style APIs using `srv.send()` tend to become protocol-specific, for example if you'd use OData `$filter` query options, or alike. In contrast to that, the `cds.ql`-based CRUD-style APIs using `srv.run()` are platform-agnostic to a very large extend. We can translate these to local API calls, remote service calls via GraphQL, OData, or REST, or to plain SQL queries sent to underlying databases.
+
+:::
+
+
+
+## Class `cds.Service`
+
+
+
+Every active thing in CAP is a service, and class `cds.Service` is the base class for all of which.
+
+Services react to events through execution of registered event handlers. So, the following code snippets show the essence of how you'd use services.
+
+You register **[event handlers](#srv-on-before-after)** with them as implementation:
+
+```js
+const srv = (new cds.Service)
+ .on('READ','Books', req => console.log (req.event, req.entity))
+ .on('foo', req => console.log (req.event, req.data))
+ .on('*', msg => console.log (msg.event))
+```
+
+You send **[queries](#srv-run-query)**, **[requests](#srv-send-request)** or **[events](#srv-emit-event)** to them for consumption:
+
+```js
+await srv.read('Books') //> READ Service.Books
+await srv.send('foo',{bar:1}) //> foo {bar:1}
+await srv.emit('foo',{bar:1}) //> foo {bar:1} //> foo
+await srv.emit('bar') //> bar
+```
+
+> Most commonly, instances are not created like this but during bootstrapping via [`cds.serve()`](#provided-services) for provided services, or [`cds.connect()`](#required-services) for required ones.
+
+
+
+
+
+### Service ( ... ) {.constructor}
+
+```tsx
+function constructor (
+ name : string,
+ model : CSN,
+ options : { kind: string, ... }
+)
+```
+
+> *Arguments fill in equally named properties [`name`](#name), [`model`](#model), [`options`](#options).*
+
+**Don't override the constructor** in subclasses, rather override [`srv.init()`](#srv-init).
+
+
+
+### . name {.property}
+
+The service's name as passed to the constructor, and under which it is found in `cds.services`.
+
+- If constructed by [`cds.serve()`](cds-serve) it's the fully-qualified name of the CDS service definition.
+- If constructed by [`cds.connect()`](cds-connect) it's the lookup name:
+
+```js
+const srv = await cds.connect.to('audit-log')
+srv.name //> 'audit-log'
+```
+
+
+
+### . model {.property}
+
+```tsx
+var srv.model : LinkedCSN
+var srv.definition : LinkedCSN service definition
+```
+- `model`, a [`LinkedCSN`](cds-reflect#linked-csn), is the CDS model from which this service was constructed
+- `definiton`, a [`LinkedCSN` definition](cds-reflect#any) from which this service was constructed
+
+
+
+### . options {.property}
+
+```tsx
+var srv.options : { //> from cds.requires config
+ service : string, // the definition's name if different from srv.name
+ kind : string,
+ impl : string,
+}
+```
+
+
+
+### . entities {.property}
+
+### . events {.property}
+
+### . operations {.property}
+
+```tsx
+var srv.entities/events/operations : Iterable <{
+ name : CSN definition
+}>
+```
+
+These properties provide convenient access to the CSN definitions of the *entities*, *events* and operations — that is *actions* and *functions* — exposed by this service.
+
+They are *iterable* objects, which means you can use them in all of these ways:
+
+```js
+// Assumed `this` is an instance of cds.Service
+let { Books, Authors } = this.entities
+let all_entities = [ ... this.entities ]
+for (let k in this.entities) //... k is a CSN definition's name
+for (let d of this.entities) //... d is a CSN definition
+```
+
+
+
+
+
+### srv. init() {.method}
+
+```tsx
+async function srv.init()
+```
+
+Override this method in subclasses to register custom event handlers. As shown in the example, you would usually derive from [`cds.ApplicationService`](app-services):
+
+```js
+class BooksService extends cds.ApplicationService {
+ init(){
+ const { Books, Authors } = this.entities
+ this.before ('READ', Authors, req => {...})
+ this.after ('READ', Books, req => {...})
+ this.on ('submitOrder', req => {...})
+ return super.init()
+ }
+}
+```
+
+Ensure to call `super.init()` to allow subclassses to register their handlers. Do that after your registrations to go before the ones from subclasses, or before to have theirs go before yours.
+
+
+
+
+
+### srv. prepend() {.method}
+
+```tsx
+async function srv.prepend(()=>{...})
+```
+
+Sometimes, you need to register handlers to run before handlers registered by others before. Use srv.prepend() to do so ´, for example like this:
+
+```js
+cds.on('served',()=>{
+ const { SomeService } = cds.services
+ SomeService.prepend (()=>{
+ SomeService.on('READ','Foo', (req,next) => {...})
+ })
+})
+```
+
+
+
+
+
+### srv. on, before, after() {.method}
+
+```tsx
+function srv.on/before/after (
+ event : string | string[] | '*',
+ entity? : CSN definition | CSN definition[] | string | string[] | '*',
+ handler : function
+)
+```
+
+Use these methods to register event handlers with a service, usually in your service implementation's [`init()`](#srv-init) method:
+
+```js
+class BooksService extends cds.ApplicationService {
+ init(){
+ const { Books, Authors } = this.entities
+ this.on ('READ',[Books,Authors], req => {...})
+ this.after ('READ',Books, books => {...})
+ this.before (['CREATE','UPDATE'],Books, req => {...})
+ this.on ('CREATE',Books, req => {...})
+ this.on ('UPDATE',Books, req => {...})
+ this.on ('submitOrder', req => {...})
+ this.before ('*', console.log)
+ return super.init()
+ }
+}
+```
+
+
+
+**Methods `.on`, `.before`, `.after`** refer to corresponding *phases* during request processing:
+
+- **`.on`** handlers actually fulfill requests, e.g. by reading/writing data from/to databases
+- **`.before`** handlers run before the `.on` handlers, frequently for validating inbound data
+- **`.after`** handlers run before the `.on` handlers, frequently to enrich outbound data
+
+**Argument `event`** can be one of:
+
+- `'CREATE'`, `'READ'`, `'UPDATE'`, `'UPSERT'`,`'DELETE'`
+- `'INSERT'`,`'SELECT'` → as aliases for: `'CREATE'`,`'READ'`
+- `'POST'`,`'GET'`,`'PUT'`,`'PATCH'` → as aliases for: `'CREATE'`,`'READ'`,`'UPDATE'`
+- Any other string name of a custom action or function – e.g., `'submitOrder'`
+- An `array` of the above to register the given handler for multiple events
+- The string `'*'` to register the given handler for *all* potential events
+- The string `'error'` to register an error handler for *all* potential events
+
+**Argument `entity`** can be one of:
+
+- A `CSN definition` of an entity served by this service → as obtained from [`this.entities`](#entities)
+- A `string` matching the name of an entity served by this service
+- A `path` navigating from a served entity to associated ones → e.g. `'Books/author'`
+- An `array` of the above to register the given handler for multiple entities / paths
+- The string `'*'` to register the given handler for *all* potential entities / paths
+
+
+
+::: tip Best Practices
+
+Use named functions as event handlers instead of anonymous ones as that will improve both, code comprehensibility as well as debugging experiences. Moreover `this` in named functions are the [transactional derivates](cds-context-tx#srv-tx) of your service, with access to transaction and tenant-specific information, while for arrow functions it is the base instance.
+
+:::
+
+::: tip Custom domain logic mostly goes into `.before` or `.after` handlers
+
+Your services are mostly constructed by [`cds.serve()`](cds-serve) based on service definitions in CDS models. And these are mostly instances of [`cds.ApplicationService`](app-services), which provide generic handlers for a broad range of CRUD requests. So, the need to provide own `.on` handlers reduces to custom actions and functions.
+
+:::
+
+
+
+### srv. before (request) {.method}
+
+```tsx
+function srv.before (event, entity?, handler: (
+ req : cds.Request
+)))
+```
+
+*Find details on `event` and `entity` in [srv.on,before,after()](#srv-on-before-after) above*. {.learn-more}
+
+Use this method to register handlers to run *before* `.on` handlers, frequently used for validating user input. The handlers receive a single argument `req`, an instance of [`cds.Request`](./events.md#cds-request).
+
+Examples:
+
+```js
+this.before ('UPDATE',Books, req => {
+ const { stock } = req.data
+ if (stock < 0) req.error `${{ stock }} must be >= ${0}`
+})
+this.before ('submitOrder', req => {
+ const { quantity } = req.data
+ if (quantity > 11) req.error `${{ quantity }} must not exceed ${11}`
+})
+```
+
+You can as well run additional operations in before handlers, of course:
+
+```js
+this.before ('submitOrder', async req => {
+ await UPDATE(Books).set ('stock -=', req.data.quantity)
+})
+```
+
+::: details Collecting input errors with `req.error()`...
+
+The input validation handlers above collect input errors with [`req.error()`](./events#req-msg) . This method collects all failures in property `req.errors`, allowing to display them on UIs all at once. If there are `req.errors` after the before phase, request processing is aborted with a corresponding error response returned to the client.
+
+:::
+
+[Learn more about how requests are processed by `srv.handle(req)`](#srv-handle-event) {.learn-more}
+
+
+
+### srv. after (request) {.method}
+
+```tsx
+function srv.after (event, entity?, handler: (
+ results : object[] | any,
+ req : cds.Request
+)))
+```
+
+*Find details on `event` and `entity` in [srv.on,before,after()](#srv-on-before-after) above*. {.learn-more}
+
+Use this method to register handlers to run *after* the `.on` handlers, frequently used to enrich outbound data. The handlers receive two arguments:
+
+- `results` — the outcomes of the `.on` handler which ran before
+- `req` — an instance of [`cds.Request`](./events.md#cds-request)
+
+Examples:
+
+```js
+this.after ('READ', Books, books => {
+ for (let b of books) if (b.stock > 111) b.discount = '11%'
+})
+```
+
+[Learn more about how requests are processed by `srv.handle(req)`](#srv-handle-event) {.learn-more}
+
+
+
+### srv. on (request) {.method}
+
+```tsx
+function srv.on (event, entity?, handler: (
+ req : cds.Request,
+ next : function
+)))
+```
+
+*Find details on `event` and `entity` in [srv.on,before,after()](#srv-on-before-after) above*. {.learn-more}
+
+Use this method to register handlers meant to actually fulfill requests, e.g. by reading/writing data from/to databases. The handlers receive two arguments:
+
+- `req` — an instance of [`cds.Request`](./events.md#cds-request) providing access to all request data
+- `next` — a function which allows handlers to pass control down the [interceptor stack](#interceptor-stack-with-next)
+
+Examples:
+
+```js
+const { Books, Authors } = this.entities
+this.on ('READ',[Books,Authors], req => req.target.data) // [!code focus]
+this.on ('UPDATE',Books, req => { // [!code focus]
+ let [ ID ] = req.params
+ return Object.assign (Books.data[ID], req.data)
+})
+```
+
+::: details Using mock data structures...
+
+```js
+Authors.data = {
+ 111: { ID:111, name:'Emily Brontë' },
+ 112: { ID:112, name:'Edgar Allan Poe' },
+ 114: { ID:114, name:'Richard Carpenter' },
+}
+Books.data = {
+ 211: { ID:211, title:'Wuthering Heights', author: Authors.data[111], stock:11 },
+ 212: { ID:212, title:'Eleonora', author: Authors.data[112], stock:14 },
+ 214: { ID:214, title:'Catweazle', author: Authors.data[114], stock:114 },
+}
+```
+
+:::
+
+::: details Noteworthy in these examples...
+
+- The `READ` handler is using the [`req.target`](./events.md#req-target) property which points to the CSN definition of the entity addressed by the incoming request → matching one of `Books` or `Authors` we obtained from [`this.entities`](#entities) above.
+
+- The `UPDATE` handler is using the [`req.params`](./events.md#req-params) property which provides access to passed in entity keys.
+
+:::
+
+
+#### Interceptor stack with `next()`
+
+When processing requests, `.on(request)` handlers are **executed in sequence** on a first-come-first-serve basis: Starting with the first registered one, each in the chain can decide to call subsequent handlers via `next()` or not, hence breaking the chain:
+
+```js
+// Authorization check -> shadowing all other handlers registered below
+this.on ('*', function authorize (req,next) {
+ if (!req.user.is('authenticated-user')) return req.reject('FORBIDDEN')
+ else return next() // [!code focus]
+})
+this.on ('READ',[Books,Authors], req => req.target.data)
+...
+```
+
+> Alternatively, such authorization checks could also be placed in *.before* handlers.
+
+[Learn more about how requests are processed by `srv.handle(req)`](#srv-handle-event) {.learn-more}
+
+
+
+### srv. on (event) {.method}
+
+```tsx
+function srv.on (event, handler: (
+ msg : cds.Event
+)))
+```
+
+*Find details on `event` in [srv.on,before,after()](#srv-on-before-after) above*. {.learn-more}
+
+Handlers for asynchronous events, as emitted by [`srv.emit()`](#srv-emit-event), are registered in the same way as [`.on(request)`](#srv-on-request) handlers for synchrounous requests, but work slightly different:
+
+1. They are usually registered 'from the outside', not as part of a service's implementation.
+2. They receive only a single argument: `msg`, an instance of [`cds.Event`](./events.md#cds-request); no `next`.
+3. *All* of them get executed *concurrently*, not first-come-first-serve thru `next()`.
+
+For example, assumed *BooksService* would emit an event whenever books are ordered:
+
+```js
+this.on ('submitOrder', async req => {
+ // ... handle the request, and inform whoever might be interested:
+ await this.emit('BooksOrdered', req.data) // [!code focus]
+})
+```
+
+We could subscribe to this event to mashup with an `OrdersService` like so:
+
+```js
+const BooksService = await cds.connect.to('BooksService')
+const OrdersService = await cds.connect.to('OrdersService')
+BooksService.on ('BooksOrdered', async msg => { // [!code focus]
+ const { buyer, books } = msg.data
+ await OrdersService.create ('Orders', {
+ customer: buyer,
+ items: books
+ })
+})
+```
+
+Moreover, `.on(event)` handlers are *listeners*, not *interceptors*: **all** registered handlers are **executed concurrently **, not just the ones called thru `next()` chains — actually there is no argument `next`. So, if we had another consumer like that:
+
+```js
+const audit = await cds.connect.to('audit-log')
+BooksService.on ('BooksOrdered', msg => audit.log ({ // [!code focus]
+ timestamp: msg.timestamp,
+ user: msg.data.buyer,
+ event: msg.event,
+ details: msg.data
+}))
+```
+
+All these registered handlers would get executed concurrently, and independently.
+
+[Learn more about how requests are processed by `srv.handle(event)`](#srv-handle-event) {.learn-more}
+
+
+
+### srv. on (error) {.method}
+
+```ts
+function srv.on ('error', handler: (
+ err : Error,
+ req : cds.Event | cds.Request
+))
+```
+
+Use the special event name `'error'` to register a custom error handler. The handler receives the error object `err` and the respective request object `req`, an instance of [`cds.Event`](./events.md#cds-request) or [`cds.Request`](./events.md#cds-request).
+
+Example:
+
+```js
+this.on ('error', (err, req) => {
+ err.message = 'Oh no! ' + err.message
+})
+```
+
+Error handlers are invoked whenever an error occurs during event processing of *all* potential events and requests, and are used to augment or modify error messages, before they go out to clients. They are expected to be a sync function, i.e., **not `async`**, not returning Promises.
+
+
+
+
+
+### srv. send (request) {.method}
+
+```ts
+async function srv.send (
+ method : string | { method, path?, data?, headers? },
+ path? : string,
+ data? : object | any,
+ headers? : object
+)
+return : result of this.dispatch(req)
+```
+
+Use this method to send synchronous requests to a service for execution.
+
+- `method` can be a HTTP method, or a name of a custom action or function
+- `path` can be an arbitrary URL, starting with a leading `'/'`
+
+Examples:
+
+```js
+await srv.send('POST','/Books', { title: 'Catweazle' })
+await srv.send('GET','/Books')
+await srv.send('GET','/Books/201')
+await srv.send('submitOrder',{...})
+```
+
+These requests would be processed by respective [event handlers](#srv-on-before-after) registered like that:
+
+```js
+srv.on('CREATE','Books', req => {...})
+srv.on('READ','Books', req => {...})
+srv.on('submitOrder', req => {...})
+```
+
+The implementation essentially constructs and [dispatches](#srv-dispatch-event) instances of [`cds.Request`](./events.md#cds-request) like so:
+
+```js
+let req = new cds.Request (
+ (method is object) ? method
+ : (path is object) ? { method, data:path, headers:data }
+ : { method, path, data, headers }
+)
+return this.dispatch(req)
+```
+
+*See also [REST-Style Convenience API](#rest-style-api) below* {.learn-more}
+
+
+
+### srv. emit (event) {.method}
+
+```ts
+async function srv.emit (
+ event : string | { event, data?, headers? },
+ data? : object | any,
+ headers? : object
+)
+return : nothing
+```
+
+Use this method to emit asynchronous event messages to a service, for example:
+
+```js
+await srv.emit ({ event: 'SomeEvent', data: { foo: 'bar' }})
+await srv.emit ('SomeEvent', { foo:'bar' })
+```
+
+Consumers would subscribe to such events through [event handlers](#srv-on-before-after) like that:
+
+```js
+Emitter.on('SomeEvent', msg => {...})
+```
+
+The implementation essentially constructs and [dispatches](#srv-dispatch-event) instances of [`cds.Event`](./events.md#cds-event) like so:
+
+```js
+let msg = new cds.Event (
+ (event is object) ? event : { event, data, headers }
+)
+return this.dispatch(msg)
+```
+
+
+
+::: tip **INTRINSIC MESSAGING**
+
+All *cds.Services* are intrinsically events & messaging-enabled. The core implementation provides local in-process messaging, while [*cds.MessagingService*](messaging) plugs in to that to extend it to cross-process messaging via common message brokers.
+
+[**⇨ Read the Messaging Guide**](../guides/messaging/index) for the complete story.
+
+:::
+
+::: danger **PLEASE NOTE**
+
+Even though emitters never wait for consumers to receive and process event messages, keep in mind that `srv.emit()` is an *`async`* method, and that it is of **utter importance** to properly handle the returned *Promises* with `await`. Not doing so ends up in unhandled promises, and likely invalid transaction states and deadlocks.
+
+:::
+
+
+
+
+
+### srv. run (query) {.method}
+
+```ts
+async function srv.run (
+ query : CQN | CQN[]
+)
+return : result of this.dispatch(req)
+```
+
+Use this method to send queries to the service for execution.
+It accepts single [`CQN`](../cds/cqn) query objects, or arrays of which:
+
+```js
+await srv.run( INSERT.into(Books,{ title: 'Catweazle' }) )
+await srv.run( SELECT.from(Books,201) )
+await srv.run([
+ SELECT.from(Authors),
+ SELECT.from(Books)
+])
+```
+
+These queries would be processed by respective [event handlers](#srv-on-before-after) registered like that:
+
+```js
+srv.on('CREATE',Books, req => {...})
+srv.on('READ',Books, req => {...})
+```
+
+The implementation essentially constructs and [dispatches](#srv-dispatch-event) instances of [`cds.Request`](./events.md#cds-request) like so:
+
+```js
+let req = new cds.Request({query})
+return this.dispatch(req)
+```
+
+*See also [CRUD-Style Convenience API](#crud-style-api) below*{.learn-more}
+
+
+
+
+
+### srv. run ( fn ) {.method}
+
+```tsx
+function srv.run ( fn? : tx => {...} ) => Promise
+```
+
+Use this method to ensure operations in the given functions are executed in a proper transaction, either a new root transaction or a nested one to an already existing root transaction. For example:
+
+```js
+const db = await cds.connect.to('db')
+await db.run (tx => {
+ let [ Emily, Charlotte ] = await db.create (Authors, [
+ { name: 'Emily Brontë' },
+ { name: 'Charlotte Brontë' },
+ ])
+ await db.create (Books, [
+ { title: 'Wuthering Heights', author: Emily },
+ { title: 'Jane Eyre', author: Charlotte },
+ ])
+})
+```
+
+> Without the enclosing `db.run(...)` the two INSERTs would be executed in two separate transactions, if that code would have run without an outer tx in place already.
+
+This method is also used by [`srv.dispatch()`](#srv-dispatch-event) to ensure single all operations happen within a transaction. All subsequent nested operations started from within an event handler, will all be nested transactions to the root transaction started by the outermost service operation.
+
+[Learn more about transactions and `tx` transaction objects in `cds.tx` docs](cds-context-tx) {.learn-more}
+
+
+
+
+
+### srv. dispatch (event) {.method}
+
+```ts
+async function srv.dispatch (
+ this : srv | Transactional ,
+ event : cds.Event | cds.Request | cds.Event[] | cds.Request[]
+)
+return : result of this.handle(event)
+```
+
+This is the central method handling all requests or event messages sent to a service. Argument `event` is expected to be an instance of [`cds.Event`](./events.md#cds-event) or [`cds.Request`](./events.md#cds-request).
+
+The implementation basically works like that:
+
+```js
+// Ensure we are running in a proper tx, nested or root
+if (!this.context) return this.run (tx => tx.dispatch(req))
+// Handle batches of queries
+if (req.query is array) return Promise.all (req.query.map(this.dispatch))
+// Ensure req.target is properly determined
+if (!req.target) req.target = _infer_target (req)
+// Actually handle the request
+return this.handle(req)
+```
+
+Basically, methods `srv.dispatch()` and `.handle()` are designed as a pair, with the former caring for all preparatory work, and the latter actually processing the request by executing matching event handlers.
+
+::: tip
+
+When looking for overriding central event processing, rather choose [`srv.handle()`](#srv-handle-event) as that doesn't have to deal with all such input variants, and is guaranteed to be in [*tx* mode](cds-context-tx#srv-tx).
+
+:::
+
+
+
+### srv. handle (event) {.method}
+
+```ts
+async function srv.handle (
+ this : Transactional ,
+ event : cds.Event | cds.Request
+)
+return : result of executed .on handlers
+```
+
+This is the internal method called by [`this.dispatch()`](#srv-dispatch-event) to actually process requests or events by executing registered event handlers. Argument `event` is expected to be an instance of [`cds.Event`](./events.md#cds-event) or [`cds.Request`](./events.md#cds-request).
+
+The implementation basically works like that:
+
+```js
+// before phase
+await Promise.all (matching .before handlers)
+if (req.errors) throw req.reject()
+
+// on phase
+await (event.reply //> synchronous?
+ ? Promise.seq (matching .on handlers) // for synchronous requests
+ : Promise.all (matching .on handlers) // for asynchronous events
+)
+if (req.errors) throw req.reject()
+
+// after phase
+await Promise.all (matching .after handlers)
+if (req.errors) throw req.reject()
+
+return req.results
+```
+
+With `Promise.seq()` defined like this:
+
+```js
+Promise.seq = handlers => async function next(){
+ req.results = await handlers.shift()?.(req, next)
+}()
+```
+
+All matching `before`, `on`, and `after` handlers are executed in corresponding phases, with the next phase being started only if no `req.errors` have occured. In addition, note that...
+
+- **`before`** handlers are always executed *concurrently*
+- **`on`** handlers are executed...
+ - ***sequentially*** for instances of `cds.Requests`
+ - ***concurrently*** for instances of `cds.Event`
+- **`after`** handlers are always executed *concurrently*
+
+In effect, for asynchronous event messages, i.e., instances of `cds.Event`, sent via [`srv.emit()`](#srv-emit-event), all registered `.on` handlers are always executed. In contrast to that, for synchronous resuests, i.e., instances of `cds.Requests` this is up to the individual handlers calling `next()`. See [`srv.on(request)`](#interceptor-stack-with-next) for an example.
+
+
+
+
+
+## REST-style API
+
+As an alternative to `srv.send(method,...)` you can use these convenience methods:
+
+- srv. **get** (path, ...) {.method}
+- srv. **put** (path, ...) {.method}
+- srv. **post** (path, ...) {.method}
+- srv. **patch** (path, ...) {.method}
+- srv. **delete** (path, ...) {.method}
+
+Essentially they call `srv.send()` with method filled in as follows:
+
+```js
+srv.get('/Books',...) --> srv.send('GET','/Books',...)
+srv.put('/Books',...) --> srv.send('PUT','/Books',...)
+srv.post('/Books',...) --> srv.send('POST','/Books',...)
+srv.patch('/Books',...) --> srv.send('PATCH','/Books',...)
+srv.delete('/Books',...) --> srv.send('DELETE','/Books',...)
+```
+
+You can also use them as REST-style variants to run queries by omitting the leading slash in the `path` argument, or by passing a reflected entity definition instead. In that case they start constructing *bound* [`cds.ql` query objects](cds-ql), as their [CRUD-style counterparts](#crud-style-api):
+
+```js
+await srv.get(Books,201)
+await srv.get(Books).where({author_ID:106})
+await srv.post(Books).entries({title:'Wuthering Heights'})
+await srv.post(Books).entries({title:'Catweazle'})
+await srv.patch(Books).set({discount:'10%'}).where({stock:{'>':111}})
+await srv.patch(Books,201).with({stock:111})
+await srv.delete(Books,201)
+```
+
+
+## CRUD-style API
+
+As an alternative to [`srv.run(query)`](#srv-run-query) you can use these convenience methods:
+
+- srv. **read** (entity, ...) {.method}
+- srv. **create** (entity, ...) {.method}
+- srv. **insert** (entity, ...) {.method}
+- srv. **upsert** (entity, ...) {.method}
+- srv. **update** (entity, ...) {.method}
+- srv. **delete** (entity, ...) {.method}
+
+Essentially, they start constructing *bound* [`cds.ql` query objects](cds-ql) as follows:
+
+```js
+srv.read('Books',...)... --> SELECT.from ('Books',...)...
+srv.create('Books',...)... --> INSERT.into ('Books',...)...
+srv.insert('Books',...)... --> INSERT.into ('Books',...)...
+srv.upsert('Books',...)... --> UPSERT.into ('Books',...)...
+srv.update('Books',...)... --> UPDATE.entity ('Books',...)...
+srv.delete('Books',...)... --> DELETE.from ('Books',...)...
+```
+
+You can further construct the queries using the `cds.ql` fluent APIs, and then `await` them for execution thru `this.run()`. Here are some examples:
+
+```js
+await srv.read(Books,201)
+await srv.read(Books).where({author_ID:106})
+await srv.create(Books).entries({title:'Wuthering Heights'})
+await srv.insert(Books).entries({title:'Catweazle'})
+await srv.update(Books).set({discount:'10%'}).where({stock:{'>':111}})
+await srv.update(Books,201).with({stock:111})
+await srv.delete(Books,201)
+```
+
+Which are equivalent to these usages of `srv.run(query)`:
+
+```js
+await srv.run( SELECT.from(Books,201) )
+await srv.run( SELECT.from(Books).where({author_ID:106}) )
+await srv.run( INSERT.into(Books).entries({title:'Wuthering Heights'}) )
+await srv.run( INSERT.into(Books).entries({title:'Catweazle'}) )
+await srv.run( UPDATE(Books).set({discount:'10%'}).where({stock:{'>':111}}) )
+await srv.run( UPDATE(Books,201).with({stock:111}) )
+await srv.run( DELETE.from(Books,201) )
+```
diff --git a/node.js/databases.md b/node.js/databases.md
index 8081de736..d11b9c839 100644
--- a/node.js/databases.md
+++ b/node.js/databases.md
@@ -1,17 +1,14 @@
---
label: Databases
synopsis: >
- Class `cds.DatabaseService` and subclasses thereof are technical services representing persistent storage.
+ Class cds.DatabaseService and subclasses thereof are technical services representing persistent storage.
layout: node-js
status: released
---
# Databases
-{{$frontmatter?.synopsis}}
-
-
-
+
## cds.**DatabaseService** class { #cds-db-service}
@@ -206,15 +203,9 @@ Even though we provide a default pool configuration, we expect that each applica
+
-### TCP keepalive with `hdb` { .impl.beta}
-
-Starting with version `^0.18.3`, the SAP HANA driver `hdb` allows to [configure TCP keepalive behaviour](https://github.com/SAP/node-hdb#tcp-keepalive).
-You can set `tcpKeepAliveIdle` on the connection using the environment variable `HDB_TCP_KEEP_ALIVE_IDLE`.
-Valid values are a positive number or `false`.
-> As the setting must be injected into the credentials that may be received from an external source, for example in the case of multitenancy, the easiest way to do this is via the environment.
-
## cds.DatabaseService — UPSERT {#databaseservice-upsert }
[databaseservice upsert]: #databaseservice-upsert
diff --git a/node.js/events.md b/node.js/events.md
index 88995139d..c9425e512 100644
--- a/node.js/events.md
+++ b/node.js/events.md
@@ -105,7 +105,7 @@ srv.before('CREATE', Order, function(req) {
A request has `succeeded` or `failed` only once the respective transaction was finally committed or rolled back. Hence, `succeeded` handlers can't veto the commit anymore. Even more, as the final `commit` or `rollback` already happened, they run outside framework-managed transaction boundaries.
:::
-To veto requests, either use the `req.before('commit')` hook described above, or [service-level event handlers](services#event-handlers) as shown in the following example:
+To veto requests, either use the `req.before('commit')` hook described above, or [service-level event handlers](core-services#srv-after-request) as shown in the following example:
```js
const srv = await cds.connect.to('AdminService')
@@ -352,7 +352,7 @@ if (req.errors) //> get out somehow...
- `code` _Number (Optional)_ - Represents the error code associated with the message. If the number is in the range of HTTP status codes and the error has a severity of 4, this argument sets the HTTP response status code.
- `message` _String \| Object \| Error_ - See below for details on the non-string version.
- `target` _String (Optional)_ - The name of an input field/element a message is related to.
-- `args` _Array (Optional)_ - Array of placeholder values. See [Localized Messages](app-services#i18n) for details.
+- `args` _Array (Optional)_ - Array of placeholder values. See [Localized Messages](cds-i18n) for details.
#### Using an Object as Argument
@@ -367,7 +367,7 @@ req.error ({
})
```
-Additional properties can be added as well, for example to be used in [custom error handlers](services#srv-on-error).
+Additional properties can be added as well, for example to be used in [custom error handlers](core-services#srv-on-error).
> In OData responses, notifications get collected and put into HTTP response header `sap-messages` as a stringified array, while the others are collected in the respective response body properties (→ see [OData Error Responses](http://docs.oasis-open.org/odata/odata-json-format/v4.0/os/odata-json-format-v4.0-os.html#_Toc372793091)).
@@ -381,12 +381,4 @@ Additionally, the OData protocol specifies which properties an error object may
{.sub-section}
-### req.diff (data?) {#req-diff .impl.beta}
-[`req.diff`]: #req-diff
-
-Use this asynchronous method to calculate the difference between the data on the database and the passed data (defaults to `req.data`, if not passed).
-> This will trigger database requests.
-
-```js
-const diff = await req.diff()
-```
+
\ No newline at end of file
diff --git a/node.js/fiori.md b/node.js/fiori.md
new file mode 100644
index 000000000..553b0d027
--- /dev/null
+++ b/node.js/fiori.md
@@ -0,0 +1,95 @@
+# Fiori Support
+
+
+
+[[toc]]
+
+
+
+## Serving `$metadata` Requests
+
+
+
+## Serving `$batch` Requests
+
+
+
+## Draft Support
+
+Class `ApplicationService` provides built-in support for Fiori Draft, which add these additional CRUD events:
+
+You can add your validation logic in the before operation handler for the `CREATE` or `UPDATE` event (as in the case of nondraft implementations) or on the `SAVE` event (specific to drafts only):
+
+```js
+srv.before ('NEW','Books.draft', ...) // run before creating new drafts
+srv.after ('NEW','Books.draft', ...) // for newly created drafts
+srv.after ('EDIT','Books', ...) // for starting edit draft sessions
+srv.before ('PATCH','Books.draft', ...) // for field-level validations during editing
+srv.before ('SAVE','Books.draft', ...) // run at final save only
+```
+
+These events get triggered during the draft edit session whenever the user tabs from one field to the next, and can be used to provide early feedback.
+
+
+
+### Event: `'NEW'`
+
+```tsx
+function srv.on ('NEW', .draft, req => {...})
+```
+
+Starts a draft session with an empty draft entity.
+
+
+
+### Event: `'EDIT'`
+
+```tsx
+function srv.on ('EDIT', , req => {...})
+```
+
+Starts a draft session with a draft entity copied from an existing active entity.
+
+
+
+### Event: `'PATCH'`
+
+```tsx
+function srv.on ('PATCH', .draft, req => {...})
+function srv.on ('PATCH', , req => {...})
+```
+
+Reacts on PATCH events on draft entities.
+
+Same event can go to active entities, bypassing draft mechanism, but respecting draft locks.
+
+
+
+### Event: `'SAVE'`
+
+```tsx
+function srv.on ('SAVE', .draft, req => {...})
+```
+
+Ends a draft session by UPDATEing the active entity with draft entity data.
+
+
+
+### Event: `'CANCEL'`
+
+```tsx
+function srv.on ('CANCEL', .draft, req => {...})
+```
+
+Ends a draft session by canceling, i.e., deleting the draft entity.
+
+
+
+
+
+## Draft Locks
+
+
+
+## Lean Draft
+
diff --git a/node.js/index.data.js b/node.js/index.data.js
deleted file mode 100644
index ce07e6435..000000000
--- a/node.js/index.data.js
+++ /dev/null
@@ -1,11 +0,0 @@
-import { basename } from 'node:path'
-import { createContentLoader } from 'vitepress'
-import filter from '../.vitepress/theme/components/indexFilter.js'
-
-const basePath = basename(__dirname)
-
-export default createContentLoader(`**/${basePath}/*.md`, {
- transform(rawData) {
- return filter(rawData, `/${basePath}/`)
- }
-})
diff --git a/node.js/index.md b/node.js/index.md
index 7f9d7ae4b..291a6d2d6 100644
--- a/node.js/index.md
+++ b/node.js/index.md
@@ -11,15 +11,12 @@ Reference Documentation
-
-## Introduction
-
As an application developer you'd primarily use the Node.js APIs documented herein to implement **domain-specific custom logic** along these lines:
1. Define services in CDS → see [Cookbook > Providing & Consuming Services](../guides/providing-services/#defining-services)
-2. Add service implementations → [`cds.Service` > Implementations](./services#srv-impls)
-3. Register custom event handlers in which → [`srv.on`/`before`/`after`](./services#event-handlers)
-4. Read/write data from other services in which → [`srv.run`](./services#srv-run) + [`cds.ql`](./cds-ql)
+2. Add service implementations → [`cds.Service` > Implementations](./core-services#implementing-services)
+3. Register custom event handlers in which → [`srv.on`/`before`/`after`](./core-services#srv-on-before-after)
+4. Read/write data from other services in which → [`srv.run`](./core-services#srv-run-query) + [`cds.ql`](./cds-ql)
5. ..., i.e. from your primary database → [`cds.DatabaseService`](./databases)
5. ..., i.e. from other connected services → [`cds.RemoteService`](./remote-services)
6. Emit and handle asynchronous events → [`cds.MessagingService`](./messaging)
@@ -27,32 +24,3 @@ As an application developer you'd primarily use the Node.js APIs documented here
All the rest is largely handled by the CAP runtime framework behind the scenes.
This especially applies to bootstrapping the [`cds.server`](./cds-serve) and the generic features
provided through [`cds.ApplicationService`](./app-services).
-
-
-## Content
-
-
-
-