[automated commit] Bump docs to versions 2.12.0, 1.53.4

docs/cli.md

@@ -300,7 +300,7 @@ Options:
 * `-t, --typescript` - Generate the client plugin in TypeScript.
 * `-R, --runtime <serviceId>` - Generate the client for the `serviceId` running in the current runtime
 * `--frontend` - Generated a browser-compatible client that uses `fetch`
-* `--full-response` - Client will return full response object rather than just the body.
+* `--full-response` - Client will return full response object rather than just the body. Bear in mind that in some cases the full response will be forced (f.e. generating the frontend with an OpenAPI schema that contains an empty response).
 * `--full-request` - Client will be called with all parameters wrapped in `body`, `headers` and `query` properties. Ignored if `--frontend`
 * `--full` - Enables both `--full-request` and `--full-response` overriding them.
 * `--optional-headers <headers>` - Comma separated string of headers that will be marked as optional in the type file. Ignored if `--frontend`

docs/client/programmatic.md

@@ -75,6 +75,7 @@ console.log(res)
 ## Optional properties
 You can also pass the following properties to `buildOpenAPIClient`:
 ```ts
+import { Agent } from 'undici'
 import { buildOpenAPIClient } from '@platformatic/client'
 
 const client = await buildOpenAPIClient({
@@ -87,7 +88,8 @@ const client = await buildOpenAPIClient({
   bodyTimeout: 900000, // body timeout passed to the undici request method
   headersTimeout: 900000, // headers timeout passed to the undici request method
   validateResponse: true, // validate or not the response received against the expected schema
-  queryParser: (query) => `${query.toString()}[]` // override the default query parser logic
+  queryParser: (query) => `${query.toString()}[]`, // override the default query parser logic
+  dispatcher: new Agent(), // optional property that allows passing a custom undici Agent
 })
 ```
 

docs/getting-started/quick-start-watt.md

@@ -345,3 +345,22 @@ Open `chrome://inspect` in Chrome, and you will see the services listed there.
 ![Chrome Inspector showing 4 services](./images/inspector.png)
 
 Then, you can click on `inspect` to open the DevTools for that service.
+
+## Debug individual services with VS Code
+
+You can debug the code of individual Watt services directly in VS Code.
+
+To run the debugger in VS Code:
+* add a breakpoint in your Watt service code
+* open the `Command Palette` (`Ctrl+Shift+P` on Windows, `CMD+Shift+P` on Mac)
+* search `Debug: Toggle Auto Attach`, then select `Always` from the list of options
+* run watt with `npm run dev`
+* you should now see in your shell a log that confirms that the debugger is listening
+```shell
+Debugger listening on ws://127.0.0.1:62807/6132054c-766e-4d86-a716-f634118275ed
+For help, see: https://nodejs.org/en/docs/inspector
+Debugger attached.
+```
+* do a request to your service, to trigger the breakpoint code, and use VS Code to debug it as by the following screenshot
+
+![VS Code Debug Watt service](./images/vs-code-debug.png)

docs/packages/node/overview.md

@@ -76,6 +76,31 @@ app.get(`${prefix}/env`, (req, res) => {
 app.listen(3000)
 ```
 
+### Typescript
+
+The Platformatic Node allows to run Typescript application with the use of custom commands via the `commands` property.
+
+To make Typescript work in development mode, setup a `commands.development` value which will start Node.js with a TypeScript loader.
+
+When configuring production mode instead, you have to configure both the `commands.build` and `commands.production` values. The former will be used to compile your service, while the latter will be used to start it.
+
+A complete typical setup for the service `watt.json` file will be something like this:
+
+```
+{
+  "$schema": "https://schemas.platformatic.dev/@platformatic/node/2.9.1.json",
+  "application": {
+    "commands": {
+      "development": "node --import tsx server.ts",
+      "build": "tsc",
+      "production": "node dist/server.js"
+    }
+  }
+}
+```
+
+Watt supports setting up `npm run ...` commands so you can reuse your existing npm scripts flow.
+
 ## Configuration
 
 See the [configuration](./configuration.md) page.
@@ -89,8 +114,5 @@ See the [configuration](./configuration.md) page.
 - **`platformatic.basePath`**: The base path of the service in the composer.
 - **`platformatic.logLevel`**: The log level configured for the service.
 - **`platformatic.events.on('close')`**: This event is emitted when the process is being closed. A listener should be installed to perform a graceful close, which must finish in 10 seconds. If there is no listener, the process will be terminated by invoking `process.exit(0)`.
-  <Issues />
-
-```
 
-```
+<Issues />

docs/runtime/_shared-configuration.md

@@ -221,6 +221,10 @@ Allowing to configure the options in the agent as well as [interceptors](https:/
 
 It's important to note that `IDP` stands for Identity Provider, and its token `url` is the URL that will be called to generate a new token.
 
+### `serviceTimeout`
+
+The number of milliseconds to wait when invoking another service using the its `plt.local` before considering the request timed out. Default: `300000` (5 minutes).
+
 ### `metrics`
 
 This configures the Platformatic Runtime Prometheus server. The Prometheus server exposes aggregated metrics from the Platformatic Runtime services.

versioned_docs/version-2.11.0/cli.md → versioned_docs/version-2.12.0/cli.md

@@ -300,7 +300,7 @@ Options:
 * `-t, --typescript` - Generate the client plugin in TypeScript.
 * `-R, --runtime <serviceId>` - Generate the client for the `serviceId` running in the current runtime
 * `--frontend` - Generated a browser-compatible client that uses `fetch`
-* `--full-response` - Client will return full response object rather than just the body.
+* `--full-response` - Client will return full response object rather than just the body. Bear in mind that in some cases the full response will be forced (f.e. generating the frontend with an OpenAPI schema that contains an empty response).
 * `--full-request` - Client will be called with all parameters wrapped in `body`, `headers` and `query` properties. Ignored if `--frontend`
 * `--full` - Enables both `--full-request` and `--full-response` overriding them.
 * `--optional-headers <headers>` - Comma separated string of headers that will be marked as optional in the type file. Ignored if `--frontend`

versioned_docs/version-2.11.0/client/programmatic.md → versioned_docs/version-2.12.0/client/programmatic.md

@@ -75,6 +75,7 @@ console.log(res)
 ## Optional properties
 You can also pass the following properties to `buildOpenAPIClient`:
 ```ts
+import { Agent } from 'undici'
 import { buildOpenAPIClient } from '@platformatic/client'
 
 const client = await buildOpenAPIClient({
@@ -87,7 +88,8 @@ const client = await buildOpenAPIClient({
   bodyTimeout: 900000, // body timeout passed to the undici request method
   headersTimeout: 900000, // headers timeout passed to the undici request method
   validateResponse: true, // validate or not the response received against the expected schema
-  queryParser: (query) => `${query.toString()}[]` // override the default query parser logic
+  queryParser: (query) => `${query.toString()}[]`, // override the default query parser logic
+  dispatcher: new Agent(), // optional property that allows passing a custom undici Agent
 })
 ```
 

versioned_docs/version-2.11.0/getting-started/quick-start-watt.md → versioned_docs/version-2.12.0/getting-started/quick-start-watt.md

@@ -345,3 +345,22 @@ Open `chrome://inspect` in Chrome, and you will see the services listed there.
 ![Chrome Inspector showing 4 services](./images/inspector.png)
 
 Then, you can click on `inspect` to open the DevTools for that service.
+
+## Debug individual services with VS Code
+
+You can debug the code of individual Watt services directly in VS Code.
+
+To run the debugger in VS Code:
+* add a breakpoint in your Watt service code
+* open the `Command Palette` (`Ctrl+Shift+P` on Windows, `CMD+Shift+P` on Mac)
+* search `Debug: Toggle Auto Attach`, then select `Always` from the list of options
+* run watt with `npm run dev`
+* you should now see in your shell a log that confirms that the debugger is listening
+```shell
+Debugger listening on ws://127.0.0.1:62807/6132054c-766e-4d86-a716-f634118275ed
+For help, see: https://nodejs.org/en/docs/inspector
+Debugger attached.
+```
+* do a request to your service, to trigger the breakpoint code, and use VS Code to debug it as by the following screenshot
+
+![VS Code Debug Watt service](./images/vs-code-debug.png)

versioned_docs/version-2.11.0/packages/node/overview.md → versioned_docs/version-2.12.0/packages/node/overview.md

@@ -76,6 +76,31 @@ app.get(`${prefix}/env`, (req, res) => {
 app.listen(3000)
 ```
 
+### Typescript
+
+The Platformatic Node allows to run Typescript application with the use of custom commands via the `commands` property.
+
+To make Typescript work in development mode, setup a `commands.development` value which will start Node.js with a TypeScript loader.
+
+When configuring production mode instead, you have to configure both the `commands.build` and `commands.production` values. The former will be used to compile your service, while the latter will be used to start it.
+
+A complete typical setup for the service `watt.json` file will be something like this:
+
+```
+{
+  "$schema": "https://schemas.platformatic.dev/@platformatic/node/2.9.1.json",
+  "application": {
+    "commands": {
+      "development": "node --import tsx server.ts",
+      "build": "tsc",
+      "production": "node dist/server.js"
+    }
+  }
+}
+```
+
+Watt supports setting up `npm run ...` commands so you can reuse your existing npm scripts flow.
+
 ## Configuration
 
 See the [configuration](./configuration.md) page.
@@ -89,8 +114,5 @@ See the [configuration](./configuration.md) page.
 - **`platformatic.basePath`**: The base path of the service in the composer.
 - **`platformatic.logLevel`**: The log level configured for the service.
 - **`platformatic.events.on('close')`**: This event is emitted when the process is being closed. A listener should be installed to perform a graceful close, which must finish in 10 seconds. If there is no listener, the process will be terminated by invoking `process.exit(0)`.
-  <Issues />
-
-```
 
-```
+<Issues />

versioned_docs/version-2.11.0/runtime/_shared-configuration.md → versioned_docs/version-2.12.0/runtime/_shared-configuration.md

@@ -221,6 +221,10 @@ Allowing to configure the options in the agent as well as [interceptors](https:/
 
 It's important to note that `IDP` stands for Identity Provider, and its token `url` is the URL that will be called to generate a new token.
 
+### `serviceTimeout`
+
+The number of milliseconds to wait when invoking another service using the its `plt.local` before considering the request timed out. Default: `300000` (5 minutes).
+
 ### `metrics`
 
 This configures the Platformatic Runtime Prometheus server. The Prometheus server exposes aggregated metrics from the Platformatic Runtime services.

versions.json

@@ -1,4 +1,4 @@
 [
-  "2.11.0",
+  "2.12.0",
   "1.53.4"
 ]