Merge remote-tracking branch 'origin/main'

docs/config/handbook.ts

@@ -1799,6 +1799,7 @@ export default [
               '/handbook/workflow/nodes/end',
               '/handbook/workflow/nodes/loop',
               '/handbook/workflow/nodes/parallel',
+              '/handbook/workflow/nodes/variable',
             ],
           },
           {
@@ -1842,11 +1843,10 @@ export default [
             'title.ja-JP': '拡張タイプ',
             type: 'group',
             children: [
-              '/handbook/workflow/nodes/request',
-              '/handbook/workflow/nodes/dynamic-calculation',
+              '/handbook/workflow/nodes/javascript',
               '/handbook/workflow/nodes/json-query',
+              '/handbook/workflow/nodes/request',
               '/handbook/workflow/nodes/response-message',
-              '/handbook/workflow/nodes/variable',
             ],
           },
         ],
@@ -1940,6 +1940,12 @@ export default [
               '/handbook/workflow-dynamic-calculation/node',
             ],
           },
+          {
+            title: 'JavaScript',
+            'title.zh-CN': 'JavaScript 脚本',
+            subTitle: '@nocobase/plugin-workflow-javascript',
+            link: '/handbook/workflow-javascript',
+          },
           {
             title: 'JSON query',
             'title.zh-CN': 'JSON 解析',

docs/en-US/handbook/index.md

@@ -1,11 +1,122 @@
-# Handbook Guide
-
-1. If you are first exposed to NocoBase, it is recommended that you start with "[Data Modeling - Overview](/handbook/data-modeling)". In this chapter, you can understand the features of NocoBase data modeling;
-2. Going further, you can add "[Pages](/handbook/ui/pages)" and "[Blocks](/handbook/ui/blocks)" in the interface. You can choose suitable blocks to display the data in the data source;
-3. Next, "[Configure Fields](/handbook/ui/fields)" and "[Configure Actions](/handbook/ui/actions)" for the data blocks. By this step, simple data processing procedures can be done;
-4. If you want to orchestrate actions, you can check the "[Workflow](/handbook/workflow)" chapter. The workflow provides various triggers and action nodes, which can satisfy your unlimited imagination for orchestrating operations;
-5. Permissions need to be configured for actions. You can check "[Users and Permissions](/handbook/acl)". In addition to understanding how to configure action permissions, this chapter can also further understand the concept of "[Departments](/handbook/departments)", which includes the management of users, roles, and departments.
-6. If you already have a ready-made IdP (Identity Provider), refer to the "[User Authentication](/handbook/auth)" chapter, which can help you understand how to access third-party user service providers;
-7. You can enable multiple languages in "[System Settings](/handbook/system-settings)". If the translation of the language you use is incomplete, you can use "[Localization Management](/handbook/localization-management)" to translate, and you are also welcome to contribute translations to NocoBase;
-8. "[Logs and Monitoring](/handbook/logger)" is an important tool for managing and maintaining NocoBase. It can help developers discover and solve problems in time, optimize system performance, ensure system security and stability, and improve system reliability and availability;
-9. You can view all added plugins in the "[Plugin Manager](/handbook/plugin-manager)". Plugins need to be activated before they can be used. If the existing plugins cannot meet your needs, you can also "[Develop Plugins](/development)" by yourself and then add them through the plugin manager.
+# 脚本
+
+<PluginInfo name="workflow-script" link="/handbook/workflow-script" commercial="true"></PluginInfo>
+
+脚本节点允许用户在工作流中执行一段自定义的 Node.js 脚本。脚本中可以使用流程上游的变量作为参数，并且可以将脚本的返回值提供给下游节点使用。
+
+脚本支持 Node.js 的大部分特性，但与原生的执行环境仍有部分差异，详见 [特性列表](#特性列表)。
+
+## 使用手册
+
+### 创建节点
+
+在工作流配置界面中，点击流程中的加号（“+”）按钮，添加“脚本”节点：
+
+![20241007122632](https://static-docs.nocobase.com/20241007122632.png)
+
+### 节点配置
+
+![20241007122825](https://static-docs.nocobase.com/20241007122825.png)
+
+#### 参数
+
+用于向脚本中传入流程上下文的变量或静态值，以供脚本中的代码逻辑使用。其中 `name` 为参数名，传入脚本后即作为变量名。`value` 为参数值，可以选择变量或输入常量。
+
+#### 脚本内容
+
+脚本内容可以看做一个函数，可以编写任意符合 Node.js 环境中支持的 JavaScript 代码，且可以使用 `return` 语句返回一个值作为节点的运行结果，以供后续节点作为变量使用。
+
+编写代码后可以通过编辑框下方的测试按钮，打开测试执行的对话框，用静态值填入参数进行模拟执行。执行后可以在对话框中看到返回值和输出（日志）的内容。
+
+![20241007153631](https://static-docs.nocobase.com/20241007153631.png)
+
+#### 超时设置
+
+单位以毫秒计算，当设置为 `0` 时表示不设置超时。
+
+#### 脚本出错后继续流程
+
+勾选后，脚本出错或者超时出错时仍然会执行后续的节点。
+
+:::info{title="提示"}
+脚本出错后将没有返回值，节点的结果会以错误信息填充。如后续节点中使用了脚本节点的结果变量，需要谨慎处理。
+:::
+
+## 特性列表
+
+### Node.js 版本
+
+与主应用运行的 Node.js 版本一致。
+
+### 模块支持
+
+在脚本中可以有限制的使用模块，与 CommonJS 一致，代码中使用 `require()` 指令引入模块。
+
+支持 Node.js 原生模块，和 `node_modules` 中已安装的模块（含 NocoBase 已使用的依赖包）。要提供给脚本节点使用的模块需在应用环境变量 `WORKFLOW_SCRIPT_MODULES` 中声明，多个包名以半角逗号分隔，例如：
+
+```ini
+WORKFLOW_SCRIPT_MODULES=crypto,timers,lodash,dayjs
+```
+
+:::info{title="提示"}
+在环境变量 `WORKFLOW_SCRIPT_MODULES` 中未声明的模块，即使是 Node.js 原生的或 `node_modules` 中已安装的，也**不能**在脚本中使用。该策略可以用于在运维层管控用户可使用的模块列表，在一些场景下避免脚本权限过高。
+:::
+
+### 全局变量
+
+**不支持** `global`、`process`、`__dirname` 和 `__filename` 等全局变量。
+
+```js
+console.log(global); // will throw error: "global is not defined"
+```
+
+### 传入参数
+
+节点中配置的参数会作为脚本中的全局变量，可以直接使用。传入脚本的参数仅支持基本类型，如 `boolean`、`number`、`string`、`number`、`object` 和数组。`Date` 对象传入后会被转换为基于 ISO 格式的字符串。其他复杂类型无法直接传递，如自定义类的实例等。
+
+### 返回值
+
+通过 `return` 语句可以返回基本类型的数据（同参数规则）回到节点作为结果。如代码中没有调用 `return` 语句，则节点执行没有返回值。
+
+```js
+return 123;
+```
+
+### 输出（日志）
+
+**支持**使用 `console` 输出日志。
+
+```js
+console.log('hello world!');
+```
+
+工作流执行时，脚本节点的输出也会记录到对应工作流的日志文件中。
+
+### 异步
+
+**支持**使用 `async` 定义异步函数，以及 `await` 调用异步函数。**支持**使用 `Promise` 全局对象。
+
+```js
+async function test() {
+  return Promise.resolve(1);
+}
+
+const value = await test();
+return value;
+```
+
+### 计时器
+
+如需使用 `setTimeout`、`setInterval` 或 `setImmediate` 等方法，需要通过 Node.js 的 `timers` 包引入。
+
+```js
+const { setTimeout, setInterval, setImmediate, clearTimeout, clearInterval, clearImmediate } = require('timers');
+
+async function sleep(time) {
+  return new Promise((resolve) => setTimeout(resolve, time));
+}
+
+await sleep(1000);
+
+return 123;
+```

docs/en-US/handbook/workflow-javascript/index.md

@@ -0,0 +1,122 @@
+# JavaScript
+
+<PluginInfo name="workflow-script" link="/handbook/workflow-script" commercial="true"></PluginInfo>
+
+脚本节点允许用户在工作流中执行一段自定义的 Node.js 脚本。脚本中可以使用流程上游的变量作为参数，并且可以将脚本的返回值提供给下游节点使用。
+
+脚本支持 Node.js 的大部分特性，但与原生的执行环境仍有部分差异，详见 [特性列表](#特性列表)。
+
+## 使用手册
+
+### 创建节点
+
+在工作流配置界面中，点击流程中的加号（“+”）按钮，添加“脚本”节点：
+
+![20241007122632](https://static-docs.nocobase.com/20241007122632.png)
+
+### 节点配置
+
+![20241007122825](https://static-docs.nocobase.com/20241007122825.png)
+
+#### 参数
+
+用于向脚本中传入流程上下文的变量或静态值，以供脚本中的代码逻辑使用。其中 `name` 为参数名，传入脚本后即作为变量名。`value` 为参数值，可以选择变量或输入常量。
+
+#### 脚本内容
+
+脚本内容可以看做一个函数，可以编写任意符合 Node.js 环境中支持的 JavaScript 代码，且可以使用 `return` 语句返回一个值作为节点的运行结果，以供后续节点作为变量使用。
+
+编写代码后可以通过编辑框下方的测试按钮，打开测试执行的对话框，用静态值填入参数进行模拟执行。执行后可以在对话框中看到返回值和输出（日志）的内容。
+
+![20241007153631](https://static-docs.nocobase.com/20241007153631.png)
+
+#### 超时设置
+
+单位以毫秒计算，当设置为 `0` 时表示不设置超时。
+
+#### 脚本出错后继续流程
+
+勾选后，脚本出错或者超时出错时仍然会执行后续的节点。
+
+:::info{title="提示"}
+脚本出错后将没有返回值，节点的结果会以错误信息填充。如后续节点中使用了脚本节点的结果变量，需要谨慎处理。
+:::
+
+## 特性列表
+
+### Node.js 版本
+
+与主应用运行的 Node.js 版本一致。
+
+### 模块支持
+
+在脚本中可以有限制的使用模块，与 CommonJS 一致，代码中使用 `require()` 指令引入模块。
+
+支持 Node.js 原生模块，和 `node_modules` 中已安装的模块（含 NocoBase 已使用的依赖包）。要提供给脚本节点使用的模块需在应用环境变量 `WORKFLOW_SCRIPT_MODULES` 中声明，多个包名以半角逗号分隔，例如：
+
+```ini
+WORKFLOW_SCRIPT_MODULES=crypto,timers,lodash,dayjs
+```
+
+:::info{title="提示"}
+在环境变量 `WORKFLOW_SCRIPT_MODULES` 中未声明的模块，即使是 Node.js 原生的或 `node_modules` 中已安装的，也**不能**在脚本中使用。该策略可以用于在运维层管控用户可使用的模块列表，在一些场景下避免脚本权限过高。
+:::
+
+### 全局变量
+
+**不支持** `global`、`process`、`__dirname` 和 `__filename` 等全局变量。
+
+```js
+console.log(global); // will throw error: "global is not defined"
+```
+
+### 传入参数
+
+节点中配置的参数会作为脚本中的全局变量，可以直接使用。传入脚本的参数仅支持基本类型，如 `boolean`、`number`、`string`、`number`、`object` 和数组。`Date` 对象传入后会被转换为基于 ISO 格式的字符串。其他复杂类型无法直接传递，如自定义类的实例等。
+
+### 返回值
+
+通过 `return` 语句可以返回基本类型的数据（同参数规则）回到节点作为结果。如代码中没有调用 `return` 语句，则节点执行没有返回值。
+
+```js
+return 123;
+```
+
+### 输出（日志）
+
+**支持**使用 `console` 输出日志。
+
+```js
+console.log('hello world!');
+```
+
+工作流执行时，脚本节点的输出也会记录到对应工作流的日志文件中。
+
+### 异步
+
+**支持**使用 `async` 定义异步函数，以及 `await` 调用异步函数。**支持**使用 `Promise` 全局对象。
+
+```js
+async function test() {
+  return Promise.resolve(1);
+}
+
+const value = await test();
+return value;
+```
+
+### 计时器
+
+如需使用 `setTimeout`、`setInterval` 或 `setImmediate` 等方法，需要通过 Node.js 的 `timers` 包引入。
+
+```js
+const { setTimeout, setInterval, setImmediate, clearTimeout, clearInterval, clearImmediate } = require('timers');
+
+async function sleep(time) {
+  return new Promise((resolve) => setTimeout(resolve, time));
+}
+
+await sleep(1000);
+
+return 123;
+```

docs/en-US/handbook/workflow/nodes/index.md

@@ -6,7 +6,7 @@ Nodes are the basic units of logical arrangement in a workflow. A workflow can c
 Workflow triggers are not considered to be nodes but are displayed in the workflow diagram as entry nodes. They are different concepts from nodes. For details, please refer to the [Triggers](../triggers/index.md) section.
 :::
 
-From a functional perspective, the nodes implemented so far are in four categories (a total of 18 types of nodes):
+From a functional perspective, the nodes implemented so far are in four categories (a total of 21 types of nodes):
 
 - Flow Control
   - [Condition](./condition.md)
@@ -32,3 +32,5 @@ From a functional perspective, the nodes implemented so far are in four categori
 - Other Extensions
   - [HTTP Request](./request.md) (provided by plugin @nocobase/plugin-workflow-request)
   - [Response Message](./response-message.md) (provided by plugin @nocobase/plugin-workflow-response-message)
+  - [JavaScript](./javascript.md) (provided by plugin @nocobase/plugin-workflow-javascript)
+  - [JSON query](./json-query.md) (provided by plugin @nocobase/plugin-workflow-json-query)

docs/en-US/handbook/workflow/nodes/javascript.md

@@ -0,0 +1,3 @@
+# Script
+
+<embed src="../../workflow-javascript/index.md#L3-L999"></embed>