Merge branch 'main' into postgres-deploy

cap-js · Oct 5, 2023 · ba7decc · ba7decc
2 parents f4d2306 + 0b42c6c
commit ba7decc
Show file tree

Hide file tree

Showing 50 changed files with 1,427 additions and 1,038 deletions.
diff --git a/.github/cds-snippet-checker/package.json b/.github/cds-snippet-checker/package.json
@@ -12,6 +12,6 @@
     "check": "node check-cds-snippets.js"
   },
   "dependencies": {
-    "@sap/cds-compiler": "^3.9.2"
+    "@sap/cds-compiler": "^4.2.0"
   }
 }
diff --git a/.github/etc/create-review.cjs b/.github/etc/create-review.cjs
@@ -189,27 +189,30 @@ module.exports = async ({ github, require, exec, core }) => {
                 continue
             }
 
+            // Github requires that no path starts with './', but cspell provides the paths exactly in this format
+            const properlyStructuredPath = path.replace(/^\.\//, '')
+
             if (suggestions.length > 0) {
                 // replace word with first suggestions and remove first "+" sign
                 const suggestion = line.replace(word, suggestions[0]).replace('+', '')
 
                 const commentBody = createCspellSuggestionText(suggestion, suggestions.slice(1))
 
-                comments.push({ path, position, body: commentBody })
+                comments.push({ path: properlyStructuredPath, position, body: commentBody })
             } else {
-                comments.push({ path, position, body: createUnknownWordComment(word) })
+                comments.push({ path: properlyStructuredPath, position, body: createUnknownWordComment(word) })
 
                 wordsWithoutSuggestions.push(word)
             }
 
             spellingMistakesText += `* **${path}**${pointer} Unknown word "**${word}**"\n`
         }
 
-        if (wordsWithoutSuggestions.length > 0) {
+        if (wordsWithoutSuggestions.length > 0 && comments.length > 0) {
             spellingMistakesText += `\n${createWordsWithoutSuggestionsText(wordsWithoutSuggestions)}\n`
         }
 
-        if (matches.length > 0) {
+        if (matches.length > 0 && comments.length > 0) {
             spellingMistakesText += `${getSpellingCorrectionTip()}\n`
         }
 

diff --git a/.vitepress/config.ts b/.vitepress/config.ts
@@ -22,13 +22,12 @@ const redirectLinks: Record<string, string> = {}
 
 const latestVersions = {
   java_services: '2.2.0',
-  java_cds4j: '2.2.0'
+  java_cds4j: '2.3.0'
 }
 
 const localSearchOptions = {
   provider: 'local',
   options: {
-    exclude: (relativePath:string) => relativePath.includes('/customization-old'),
     miniSearch: {
       options: {
         tokenize: text => text.split( /[\n\r #%*,=/:;?[\]{}()&]+/u ), // simplified charset: removed [-_.@] and non-english chars (diacritics etc.)

diff --git a/.vitepress/syntaxes/log.tmLanguage.json b/.vitepress/syntaxes/log.tmLanguage.json
@@ -48,7 +48,7 @@
       "match": "^(?:\\[.*?\\]|\\$) (cds) (.*)$",
       "captures": {
         "1": {
-          "name": "constant.other.key"
+          "name": "entity.name.type"
         },
         "2": {
           "name": "string"

diff --git a/.vitepress/theme/custom.scss b/.vitepress/theme/custom.scss
@@ -109,7 +109,7 @@ main {
         }
       }
       em {
-        color: #00ff00e0;
+        color: #00ab00e0;
       }
       b {
         color: #ee0000e0;
@@ -119,7 +119,6 @@ main {
       }
 
       background: var(--vp-code-block-bg);
-      color: #fafafa;
     }
   }
 
@@ -201,6 +200,7 @@ main {
   .good { color:teal }
   .bad, .important { color:darkred }; .dark & { .bad, .important { color:#e00 } }
   .constructor::before { content: 'Constructor: '; color: #999 }
+  .annotation::before { content: 'Annotation: '; color: #999 }
   .property::before { content: 'Property: '; color: #999 }
   .method::before { content: 'Method: '; color: #999 }
   .event::before { content: 'Event: '; color: #999 }
@@ -210,9 +210,11 @@ main {
     margin-top: 5em;
     // font-size: 22px;
   }
+  h4.annotation + h4.annotation,
   h4.property + h4.property,
   h4.event + h4.event,
   h4.method + h4.method,
+  h3.annotation + h3.annotation,
   h3.property + h3.property,
   h3.event + h3.event,
   h3.class + h3.class,
@@ -225,17 +227,20 @@ main {
 aside.VPSidebar {
   .group {
     padding-top: 5px !important;
-    .VPSidebarItem.level-0 {
-      padding-bottom: 11px;
-      &.collapsed {
-        padding-bottom: 1px;
+    .VPSidebarItem {
+      &.level-0 {
+        padding-bottom: 11px;
+        &.collapsed {
+          padding-bottom: 1px;
+        }
       }
-      .VPSidebarItem.level-1 {
+      &.level-1 {
         padding-left: 15px;
         h2, h3, p {
           padding: 2px 0;
         }
       }
+      .caret { height: inherit; }
     }
   }
 }
@@ -306,19 +311,6 @@ html.node .java {
 }
 
 
-// enable for light code theme
-// pre.log {
-//   background: #f8f8f8; // matches to light theme
-//   color: #032F62; // matches to light theme
-//   em {
-//     color: #db8b0b;
-//   }
-//   :root.dark & {
-//     background: var(--vp-code-block-bg);
-//     color: #fafafa;
-//   }
-// }
-
 /* expand width on big screens */
 @media screen and (min-width: 1600px) {
   div[class^='language-']:hover,
@@ -327,6 +319,7 @@ html.node .java {
   pre.log:focus {
     min-width: fit-content;
     padding-right: 40px;
+    z-index: 1;  // draw over outline
   }
   table:hover,
   table:focus {

diff --git a/README.md b/README.md
@@ -14,6 +14,37 @@ This project is open to feature requests/suggestions, bug reports, etc. via [Git
 
 See our [contribution guidelines](CONTRIBUTING.md) for information about how to contribute, the project structure, as well as additional contribution information.
 
+## Running Locally
+
+If you contribute often to the documentation it's best to create your own fork, clone it to your local machine. 
+
+```sh
+git clone https://github.com/<your-git-account>/sap-cap-js-docs.git
+```
+
+Install the dependencies:
+
+```sh
+npm run setup
+```
+
+Start the local server:
+
+```sh
+npm run start
+```
+
+This will respond with:
+```sh
+  vitepress v1.0.0-rc.15
+
+  ➜  Local:   http://localhost:5173/docs/
+  ➜  Network: use --host to expose
+  ➜  press h to show help
+```
+
+Once this is running, if you are reading this documentation at https://cap.cloud.sap/ anytime you press <key>l</key> it opens the locally hosted site at the same page. 
+
 ## Code of Conduct
 
 We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone. By participating in this project, you agree to abide by its [Code of Conduct](CODE_OF_CONDUCT.md) at all times.

diff --git a/about/features.md b/about/features.md
@@ -62,13 +62,13 @@ Following is an index of the features currently covered by CAP, with status and
 <br>
 
 | Editors/IDE Support      | Application Studio | VS Code | Eclipse |
-|--------------------------|:------------------:|:------:|:-------:|
-| CDS Syntax Highlighting  |        <X/>        |  <X/>  |  <X/>   |
-| CDS Code Completion      |        <X/>        |  <X/>  |  <X/>   |
-| CDS Prettifier           |        <X/>        |  <X/>  |  <X/>   |
-| Advanced Debug/Run Tools |        <X/>        |        |         |
-| Project Explorer         |        <X/>        |        |         |
-| ...                      |                    |        |         |
+|--------------------------|:------------------:|:-------:|:-------:|
+| CDS Syntax Highlighting  |        <X/>        |  <X/>   |  <X/>   |
+| CDS Code Completion      |        <X/>        |  <X/>   |  <X/>   |
+| CDS Prettifier           |        <X/>        |  <X/>   |  <X/>   |
+| Advanced Debug/Run Tools |        <X/>        |         |         |
+| Project Explorer         |        <X/>        |         |         |
+| ...                      |                    |         |         |
 
 
 ### CDS Language & Compiler
@@ -96,20 +96,20 @@ Following is an index of the features currently covered by CAP, with status and
 
 ### Providing Services
 
-| Core Framework Features                                                                 |  CDS  | Node.js | Java |
-|-----------------------------------------------------------------------------------------|:-----:|:-------:|:----:|
+| Core Framework Features                                                                |  CDS  | Node.js | Java |
+|----------------------------------------------------------------------------------------|:-----:|:-------:|:----:|
 | [Automatically Serving CRUD Requests](../guides/providing-services#generic-providers)  | <Na/> |  <X/>   | <X/> |
-| [Deep-Read/Write Structured Documents](../guides/providing-services#serving-documents) | <X/>  |  <X/>   | <X/> |
+| [Deep-Read/Write Structured Documents](../guides/providing-services#deep-reads-writes) | <X/>  |  <X/>   | <X/> |
 | [Automatic Input Validation](../guides/providing-services#input-validation)            | <X/>  |  <X/>   | <X/> |
-| [Auto-filled Primary Keys](../guides/domain-modeling#prefer-uuids-for-keys)             | <X/>  |  <X/>   | <X/> |
+| [Auto-filled Primary Keys](../guides/domain-modeling#prefer-uuids-for-keys)            | <X/>  |  <X/>   | <X/> |
 | [Implicit Paging](../guides/providing-services#implicit-pagination)                    | <X/>  |  <X/>   | <X/> |
 | [Implicit Sorting](../guides/providing-services#implicit-sorting)                      | <X/>  |  <X/>   | <X/> |
-| [Access Control](../guides/authorization)                                               | <X/>  |  <X/>   | <X/> |
-| [Arrayed Elements](../cds/cdl#arrayed-types)                                            | <X/>  |  <X/>   | <X/> |
-| [Streaming & Media Types](../guides/media-data)                                         | <X/>  |  <X/>   | <X/> |
+| [Access Control](../guides/authorization)                                              | <X/>  |  <X/>   | <X/> |
+| [Arrayed Elements](../cds/cdl#arrayed-types)                                           | <X/>  |  <X/>   | <X/> |
+| [Streaming & Media Types](../guides/media-data)                                        | <X/>  |  <X/>   | <X/> |
 | [Conflict Detection through _ETags_](../guides/providing-services#etag)                | <X/>  |  <X/>   | <X/> |
-| [Authentication via JWT](../guides/authorization#prerequisite-authentication)           | <Na/> |  <X/>   | <X/> |
-| [Basic Authentication](../guides/authorization#prerequisite-authentication)             | <Na/> |  <X/>   | <X/> |
+| [Authentication via JWT](../guides/authorization#prerequisite-authentication)          | <Na/> |  <X/>   | <X/> |
+| [Basic Authentication](../guides/authorization#prerequisite-authentication)            | <Na/> |  <X/>   | <X/> |
 
 
 <br>
@@ -119,12 +119,12 @@ Following is an index of the features currently covered by CAP, with status and
 | [Authorization](../guides/authorization)                                                    | <X/>  |  <X/>   | <X/> |
 | [Analytics in Fiori](../advanced/odata#data-aggregation)                                    | <X/>  |  <D/>   | <X/> |
 | [Localization/i18n](../guides/i18n)                                                         | <X/>  |  <X/>   | <X/> |
-| [Managed Data](../guides/providing-services#managed-data)                                  | <X/>  |  <X/>   | <X/> |
 | [Localized Data](../guides/localized-data)                                                  | <X/>  |  <X/>   | <X/> |
 | [Temporal Data](../guides/temporal-data)                                                    | <X/>  |  <X/>   | <X/> |
+| [Managed Data](../guides/domain-modeling#managed-data)                                      | <X/>  |  <X/>   | <X/> |
 | [Dynamic Extensibility](../guides/extensibility/)                                           | <X/>  |  <X/>   | <X/> |
 | Monitoring / Logging [[Node.js](../node.js/cds-log)\|[Java](../java/observability#logging)] | <Na/> |  <X/>   | <X/> |
-| Audit Logging [[Node.js](../guides/data-privacy/audit-logging)\|[Java](../java/auditlog)]       | <Na/> |  <X/>   | <X/> |
+| Audit Logging [[Node.js](../guides/data-privacy/audit-logging)\|[Java](../java/auditlog)]   | <Na/> |  <X/>   | <X/> |
 
 
 <br>
@@ -151,22 +151,22 @@ Following is an index of the features currently covered by CAP, with status and
 ### Consuming Services
 
 | [Service Consumption APIs](../guides/using-services) | Node.js | Java |
-|-------------------------------------------------------|:-------:|:----:|
-| Uniform Consumption APIs → Hexagonal Architecture     |  <X/>   | <X/> |
-| Dynamic Querying                                      |  <X/>   | <X/> |
-| Programmatic Delegation                               |  <X/>   | <X/> |
-| Generic Delegation                                    |  <O/>   | <O/> |
-| Resilience (retry, circuit breaking, ...)             |  <C/>   | <X/> |
+|------------------------------------------------------|:-------:|:----:|
+| Uniform Consumption APIs → Hexagonal Architecture    |  <X/>   | <X/> |
+| Dynamic Querying                                     |  <X/>   | <X/> |
+| Programmatic Delegation                              |  <X/>   | <X/> |
+| Generic Delegation                                   |  <O/>   | <O/> |
+| Resilience (retry, circuit breaking, ...)            |  <C/>   | <X/> |
 
 
 <br>
 
-| Outbound Protocol Support                             | CDS <sup>1</sup> | Node.js | Java |
-|-------------------------------------------------------|:----------------:|:-------:|:----:|
-| [REST/OpenAPI](../node.js/cds-dk#import-from-openapi) |       <X/>       |  <X/>   | <X/> |
-| OData V2                                              |       <X/>       |  <X/>   | <X/> |
-| OData V4                                              |       <X/>       |  <X/>   | <X/> |
-| GraphQL<sup>2</sup>                                   |       <C/>       |  <C/>   | <C/> |
+| Outbound Protocol Support                                 | CDS <sup>1</sup> | Node.js | Java |
+|-----------------------------------------------------------|:----------------:|:-------:|:----:|
+| [REST/OpenAPI](../node.js/cds-dk#cds-import-from-openapi) |       <X/>       |  <X/>   | <X/> |
+| OData V2                                                  |       <X/>       |  <X/>   | <X/> |
+| OData V4                                                  |       <X/>       |  <X/>   | <X/> |
+| GraphQL<sup>2</sup>                                       |       <C/>       |  <C/>   | <C/> |
 
 > <sup>1</sup> Import API to CSN <br>
 > <sup>2</sup> Could be a good case for 3rd-party contribution <br>
@@ -188,16 +188,16 @@ Following is an index of the features currently covered by CAP, with status and
 
 ### Database Support
 
-|                                                 | CDS/deploy |      Node.js       | Java |
-|-------------------------------------------------|:----------:|:------------------:|:----:|
-| [SAP HANA](../guides/databases)                |    <X/>    |        <X/>        | <X/> |
-| [SAP HANA Cloud](../guides/databases-hana) |    <X/>    |        <X/>        | <X/> |
-| [PostgreSQL](../guides/databases-postgres)              |    <X/>    | <X/> | <X/> |
-| [SQLite](../guides/databases-sqlite) <sup>1</sup>     |    <X/>    |        <X/>        | <X/> |
-| [H2](../java/persistence-services#h2) <sup>1</sup>         |    <X/>    |        <Na/>       | <X/> |
-| [MongoDB](../guides/databases) out of the box  |   <Na/>    |       <Na/>        | <D/> |
-| Pluggable drivers architecture                  |    <D/>    |        <D/>        | <X/> |
-| Out-of-the-box support for other databases?     |    <C/>    |        <C/>        | <C/> |
+|                                                    | CDS/deploy | Node.js | Java |
+|----------------------------------------------------|:----------:|:-------:|:----:|
+| [SAP HANA](../guides/databases)                    |    <X/>    |  <X/>   | <X/> |
+| [SAP HANA Cloud](../guides/databases-hana)         |    <X/>    |  <X/>   | <X/> |
+| [PostgreSQL](../guides/databases-postgres)         |    <X/>    |  <X/>   | <X/> |
+| [SQLite](../guides/databases-sqlite) <sup>1</sup>  |    <X/>    |  <X/>   | <X/> |
+| [H2](../java/persistence-services#h2) <sup>1</sup> |    <X/>    |  <Na/>  | <X/> |
+| [MongoDB](../guides/databases) out of the box      |   <Na/>    |  <Na/>  | <D/> |
+| Pluggable drivers architecture                     |    <D/>    |  <D/>   | <X/> |
+| Out-of-the-box support for other databases?        |    <C/>    |  <C/>   | <C/> |
 
 
 > <sup>1</sup> To speed up development. Not for productive use! <br>
@@ -234,7 +234,7 @@ Following is an index of the features currently covered by CAP, with status and
 | [Deploy to/run on _SAP BTP, Cloud Foundry environment_](../guides/deployment/) |  <X/>   | <X/> |
 | Deploy to/run on _Kubernetes_<sup>1</sup>                                      |  <D/>   | <D/> |
 | [Deploy to/run on _Kyma_](../guides/deployment/deploy-to-kyma)                 |  <X/>   | <X/> |
-| [SaaS on-/off-boarding](../guides/deployment/as-saas)                          |  <X/>   | <X/> |
+| [SaaS on-/offboarding](../guides/deployment/as-saas)                          |  <X/>   | <X/> |
 | [Multitenancy](../guides/multitenancy/)                                        |  <X/>   | <X/> |
 | Health checks                                                                  |  <O/>   | <X/> |
 
@@ -243,20 +243,20 @@ Following is an index of the features currently covered by CAP, with status and
 
 ### Extensibility { .impl.internal}
 
-|                                                                                                  |      |
-|--------------------------------------------------------------------------------------------------|:----:|
-| [Tenant-Specific Extensions](../guides/extensibility/)                                           | <X/> |
-| [Adding Extension Fields](../guides/extensibility/customization#about-extension-models)          | <X/> |
-| [Adding new Entities](../guides/extensibility/customization#about-extension-models)              | <X/> |
-| [Adding new Relationships](../guides/extensibility/customization#about-extension-models)         | <X/> |
-| [Adding/Overriding Annotations](../guides/extensibility/customization)                           | <X/> |
-| Adding Events                                                                                    | <O/> |
-| [Extension Namespaces](../guides/extensibility/customization)                                    | <X/> |
-| [Extension Templates](../guides/extensibility/customization#templates)                           | <X/> |
-| Custom Governance Checks                                                                         | <D/> |
-| [Generic Input Validations](../guides/providing-services#input-validation)                      | <X/> |
-| Declarative Constraints                                                                          | <O/> |
-| Execute Sandboxed Code                                                                           | <O/> |
-| Runtime API for In-App Extensibility                                                             | <D/> |
-| [Key-User Extensibility (incl. UI)](../guides/extensibility/ui-flex)                             | <D/> |
-| Propagating Extensions across (µ) Services                                                       | <O/> |
+|                                                                                          |      |
+|------------------------------------------------------------------------------------------|:----:|
+| [Tenant-Specific Extensions](../guides/extensibility/)                                   | <X/> |
+| [Adding Extension Fields](../guides/extensibility/customization#about-extension-models)  | <X/> |
+| [Adding new Entities](../guides/extensibility/customization#about-extension-models)      | <X/> |
+| [Adding new Relationships](../guides/extensibility/customization#about-extension-models) | <X/> |
+| [Adding/Overriding Annotations](../guides/extensibility/customization)                   | <X/> |
+| Adding Events                                                                            | <O/> |
+| [Extension Namespaces](../guides/extensibility/customization)                            | <X/> |
+| [Extension Templates](../guides/extensibility/customization#templates)                   | <X/> |
+| Custom Governance Checks                                                                 | <D/> |
+| [Generic Input Validations](../guides/providing-services#input-validation)               | <X/> |
+| Declarative Constraints                                                                  | <O/> |
+| Execute Sandboxed Code                                                                   | <O/> |
+| Runtime API for In-App Extensibility                                                     | <D/> |
+| [Key-User Extensibility (incl. UI)](../guides/extensibility/ui-flex)                     | <D/> |
+| Propagating Extensions across (µ) Services                                               | <O/> |