@nocobase/plugin-flow-engine 2.1.0-alpha.1 → 2.1.0-alpha.10

package/README.md

@@ -1,17 +1,24 @@
 # NocoBase
 
 <video width="100%" controls>
-      <source src="https://static-docs.nocobase.com/NocoBase0510.mp4" type="video/mp4">
+  <source src="https://github.com/user-attachments/assets/4d11a87b-00e2-48f3-9bf7-389d21072d13" type="video/mp4">
 </video>
 
+<p align="center">
+<a href="https://trendshift.io/repositories/4112" target="_blank"><img src="https://trendshift.io/api/badge/repositories/4112" alt="nocobase%2Fnocobase | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
+<a href="https://www.producthunt.com/posts/nocobase?embed=true&utm_source=badge-top-post-topic-badge&utm_medium=badge&utm_souce=badge-nocobase" target="_blank"><img src="https://api.producthunt.com/widgets/embed-image/v1/top-post-topic-badge.svg?post_id=456520&theme=light&period=weekly&topic_id=267" alt="NocoBase - Scalability&#0045;first&#0044;&#0032;open&#0045;source&#0032;no&#0045;code&#0032;platform | Product Hunt" style="width: 250px; height: 54px;" width="250" height="54" /></a>
+</p>
 
 ## What is NocoBase
 
-NocoBase is a scalability-first, open-source no-code development platform.  
-Instead of investing years of time and millions of dollars in research and development, deploy NocoBase in a few minutes and you'll have a private, controllable, and extremely scalable no-code development platform!
+NocoBase is the most extensible AI-powered no-code platform.   
+Total control. Infinite extensibility. AI collaboration.  
+Enable your team to adapt quickly and cut costs dramatically.  
+No years of development. No millions wasted.  
+Deploy NocoBase in minutes — and take control of everything.
 
 Homepage:  
-https://www.nocobase.com/
+https://www.nocobase.com/  
 
 Online Demo:  
 https://demo.nocobase.com/new
@@ -19,11 +26,74 @@ https://demo.nocobase.com/new
 Documents:  
 https://docs.nocobase.com/
 
-Commericial license & plugins:  
-https://www.nocobase.com/en/commercial
+Forum:  
+https://forum.nocobase.com/
 
-License agreement:   
-https://www.nocobase.com/en/agreement
+Use Cases:  
+https://www.nocobase.com/en/blog/tags/customer-stories
 
+## Release Notes
 
-## Contact Us:  
+Our [blog](https://www.nocobase.com/en/blog/timeline) is regularly updated with release notes and provides a weekly summary.
+
+## Distinctive features
+
+### 1. Data model-driven, not form/table–driven
+
+Instead of being constrained by forms or tables, NocoBase adopts a data model–driven approach, separating data structure from user interface to unlock unlimited possibilities.
+
+- UI and data structure are fully decoupled
+- Multiple blocks and actions can be created for the same table or record in any quantity or form
+- Supports the main database, external databases, and third-party APIs as data sources
+
+![model](https://static-docs.nocobase.com/model.png)
+
+### 2. AI employees, integrated into your business systems
+Unlike standalone AI demos, NocoBase allows you to embed AI capabilities seamlessly into your interfaces, workflows, and data context, making AI truly useful in real business scenarios.
+
+- Define AI employees for roles such as translator, analyst, researcher, or assistant
+- Seamless AI–human collaboration in interfaces and workflows
+- Ensure AI usage is secure, transparent, and customizable for your business needs
+
+![AI-employee](https://static-docs.nocobase.com/ai-employee-home.png)
+
+### 3. What you see is what you get, incredibly easy to use
+
+While enabling the development of complex business systems, NocoBase keeps the experience simple and intuitive.
+
+- One-click switch between usage mode and configuration mode
+- Pages serve as a canvas to arrange blocks and actions, similar to Notion
+- Configuration mode is designed for ordinary users, not just programmers
+
+![wysiwyg](https://static-docs.nocobase.com/wysiwyg.gif)
+
+### 4. Everything is a plugin, designed for extension
+Adding more no-code features will never cover every business case. NocoBase is built for extension through its plugin-based microkernel architecture.
+
+- All functionalities are plugins, similar to WordPress
+- Plugins are ready to use upon installation
+- Pages, blocks, actions, APIs, and data sources can all be extended through custom plugins
+
+![plugins](https://static-docs.nocobase.com/plugins.png)
+
+## Installation
+
+NocoBase supports three installation methods:
+
+- <a target="_blank" href="https://docs.nocobase.com/welcome/getting-started/installation/docker-compose">Installing With Docker (👍Recommended)</a>
+
+  Suitable for no-code scenarios, no code to write. When upgrading, just download the latest image and reboot.
+
+- <a target="_blank" href="https://docs.nocobase.com/welcome/getting-started/installation/create-nocobase-app">Installing from create-nocobase-app CLI</a>
+
+  The business code of the project is completely independent and supports low-code development.
+
+- <a target="_blank" href="https://docs.nocobase.com/welcome/getting-started/installation/git-clone">Installing from Git source code</a>
+
+  If you want to experience the latest unreleased version, or want to participate in the contribution, you need to make changes and debug on the source code, it is recommended to choose this installation method, which requires a high level of development skills, and if the code has been updated, you can git pull the latest code.
+
+## How NocoBase works
+
+<video width="100%" controls>
+  <source src="https://github.com/user-attachments/assets/8d183b44-9bb5-4792-b08f-bc08fe8dfaaf" type="video/mp4">
+</video>

package/dist/ai/docs/meta.json

@@ -0,0 +1,6 @@
+[
+  {
+    "module": "runjs",
+    "description": "RunJS contexts and runtime APIs"
+  }
+]

package/dist/ai/docs/runjs/context/block-model.md

@@ -0,0 +1,90 @@
+# ctx.blockModel
+
+The parent block model (BlockModel instance) where the current JS Field / JS Block is located. In scenarios such as JSField, JSItem, and JSColumn, `ctx.blockModel` points to the form block or table block carrying the current JS logic. In a standalone JSBlock, it may be `null` or the same as `ctx.model`.
+
+## Scenarios
+
+| Scenario | Description |
+|------|------|
+| **JSField** | Access the `form`, `collection`, and `resource` of the parent form block within a form field to implement linkage or validation. |
+| **JSItem** | Access the resource and collection information of the parent table/form block within a sub-table item. |
+| **JSColumn** | Access the `resource` (e.g., `getSelectedRows`) and `collection` of the parent table block within a table column. |
+| **Form Actions / FlowEngine** | Access `form` for pre-submission validation, `resource` for refreshing, etc. |
+
+> Note: `ctx.blockModel` is only available in RunJS contexts where a parent block exists. In standalone JSBlocks (without a parent form/table), it may be `null`. It is recommended to perform a null check before use.
+
+## Type Definition
+
+```ts
+blockModel: BlockModel | FormBlockModel | TableBlockModel | CollectionBlockModel | DataBlockModel | null;
+```
+
+The specific type depends on the parent block type: form blocks are mostly `FormBlockModel` or `EditFormModel`, while table blocks are mostly `TableBlockModel`.
+
+## Common Properties
+
+| Property | Type | Description |
+|------|------|------|
+| `uid` | `string` | Unique identifier of the block model. |
+| `collection` | `Collection` | The collection bound to the current block. |
+| `resource` | `Resource` | The resource instance used by the block (`SingleRecordResource` / `MultiRecordResource`, etc.). |
+| `form` | `FormInstance` | Form Block: Ant Design Form instance, supporting `getFieldsValue`, `validateFields`, `setFieldsValue`, etc. |
+| `emitter` | `EventEmitter` | Event emitter, used to listen for `formValuesChange`, `onFieldReset`, etc. |
+
+## Relationship with ctx.model and ctx.form
+
+| Requirement | Recommended Usage |
+|------|----------|
+| **Parent block of the current JS** | `ctx.blockModel` |
+| **Read/Write form fields** | `ctx.form` (equivalent to `ctx.blockModel?.form`, more convenient in form blocks) |
+| **Model of the current execution context** | `ctx.model` (Field model in JSField, Block model in JSBlock) |
+
+In a JSField, `ctx.model` is the field model, and `ctx.blockModel` is the form or table block carrying that field; `ctx.form` is typically `ctx.blockModel.form`.
+
+## Examples
+
+### Table: Get selected rows and process
+
+```ts
+const rows = ctx.blockModel?.resource?.getSelectedRows?.() || [];
+if (rows.length === 0) {
+  ctx.message.warning('Please select data first');
+  return;
+}
+```
+
+### Form Scenario: Validate and Refresh
+
+```ts
+if (ctx.blockModel?.form) {
+  await ctx.blockModel.form.validateFields();
+  await ctx.blockModel.resource?.refresh?.();
+}
+```
+
+### Listen for Form Changes
+
+```ts
+ctx.blockModel?.emitter?.on?.('formValuesChange', (payload) => {
+  // Implement linkage or re-rendering based on the latest form values
+});
+```
+
+### Trigger Block Re-render
+
+```ts
+ctx.blockModel?.rerender?.();
+```
+
+## Notes
+
+- In a **standalone JSBlock** (without a parent form or table block), `ctx.blockModel` may be `null`. It is recommended to use optional chaining when accessing its properties: `ctx.blockModel?.resource?.refresh?.()`.
+- In **JSField / JSItem / JSColumn**, `ctx.blockModel` refers to the form or table block carrying the current field. In a **JSBlock**, it may be itself or an upper-level block, depending on the actual hierarchy.
+- `resource` only exists in data blocks; `form` only exists in form blocks. Table blocks typically do not have a `form`.
+
+## Related
+
+- [ctx.model](./model.md): The model of the current execution context.
+- [ctx.form](./form.md): Form instance, commonly used in form blocks.
+- [ctx.resource](./resource.md): Resource instance (equivalent to `ctx.blockModel?.resource`, use directly if available).
+- [ctx.getModel()](./get-model.md): Get other block models by UID.

package/dist/ai/docs/runjs/context/collection-field.md

@@ -0,0 +1,132 @@
+# ctx.collectionField
+
+The `CollectionField` instance associated with the current RunJS execution context, used to access field metadata, types, validation rules, and association information. It only exists when the field is bound to a collection definition; custom/virtual fields may be `null`.
+
+## Use Cases
+
+| Scenario | Description |
+|------|------|
+| **JSField** | Perform linkage or validation in form fields based on `interface`, `enum`, `targetCollection`, etc. |
+| **JSItem** | Access metadata of the field corresponding to the current column in sub-table items. |
+| **JSColumn** | Select rendering methods based on `collectionField.interface` or access `targetCollection` in table columns. |
+
+> Note: `ctx.collectionField` is only available when the field is bound to a Collection definition; it is usually `undefined` in scenarios like JSBlock independent blocks or action events without field binding. It is recommended to check for null values before use.
+
+## Type Definition
+
+```ts
+collectionField: CollectionField | null | undefined;
+```
+
+## Common Properties
+
+| Property | Type | Description |
+|------|------|------|
+| `name` | `string` | Field name (e.g., `status`, `userId`) |
+| `title` | `string` | Field title (including internationalization) |
+| `type` | `string` | Field data type (`string`, `integer`, `belongsTo`, etc.) |
+| `interface` | `string` | Field interface type (`input`, `select`, `m2o`, `o2m`, `m2m`, etc.) |
+| `collection` | `Collection` | The collection the field belongs to |
+| `targetCollection` | `Collection` | The target collection of the association field (only for association types) |
+| `target` | `string` | Target collection name (for association fields) |
+| `enum` | `array` | Enumeration options (select, radio, etc.) |
+| `defaultValue` | `any` | Default value |
+| `collectionName` | `string` | Name of the collection it belongs to |
+| `foreignKey` | `string` | Foreign key field name (belongsTo, etc.) |
+| `sourceKey` | `string` | Association source key (hasMany, etc.) |
+| `targetKey` | `string` | Association target key |
+| `fullpath` | `string` | Full path (e.g., `main.users.status`), used for API or variable references |
+| `resourceName` | `string` | Resource name (e.g., `users.status`) |
+| `readonly` | `boolean` | Whether it is read-only |
+| `titleable` | `boolean` | Whether it can be displayed as a title |
+| `validation` | `object` | Validation rule configuration |
+| `uiSchema` | `object` | UI configuration |
+| `targetCollectionTitleField` | `CollectionField` | The title field of the target collection (for association fields) |
+
+## Common Methods
+
+| Method | Description |
+|------|------|
+| `isAssociationField(): boolean` | Whether it is an association field (belongsTo, hasMany, hasOne, belongsToMany, etc.) |
+| `isRelationshipField(): boolean` | Whether it is a relationship field (including o2o, m2o, o2m, m2m, etc.) |
+| `getComponentProps(): object` | Get the default props of the field component |
+| `getFields(): CollectionField[]` | Get the field list of the target collection (association fields only) |
+| `getFilterOperators(): object[]` | Get the filter operators supported by this field (e.g., `$eq`, `$ne`, etc.) |
+
+## Examples
+
+### Branch rendering based on field type
+
+```ts
+if (!ctx.collectionField) return null;
+const { interface: iface } = ctx.collectionField;
+if (['m2o', 'o2m', 'm2m'].includes(iface)) {
+  // Association field: display associated records
+  const target = ctx.collectionField.targetCollection;
+  // ...
+} else if (iface === 'select' || iface === 'radioGroup') {
+  const options = ctx.collectionField.enum || [];
+  // ...
+}
+```
+
+### Determine if it is an association field and access the target collection
+
+```ts
+if (ctx.collectionField?.isAssociationField()) {
+  const targetCol = ctx.collectionField.targetCollection;
+  const titleField = targetCol?.titleCollectionField?.name;
+  // Process according to the target collection structure
+}
+```
+
+### Get enumeration options
+
+```ts
+const options = ctx.collectionField?.enum ?? [];
+const labels = options.map((o) => (typeof o === 'object' ? o.label : o));
+```
+
+### Conditional rendering based on read-only/view mode
+
+```ts
+const { Input } = ctx.libs.antd;
+if (ctx.collectionField?.readonly) {
+  ctx.render(<span>{ctx.getValue?.() ?? '-'}</span>);
+} else {
+  ctx.render(<Input onChange={(e) => ctx.setValue?.(e.target.value)} />);
+}
+```
+
+### Get the title field of the target collection
+
+```ts
+// When displaying an association field, use targetCollectionTitleField to get the title field name
+const titleField = ctx.collectionField?.targetCollectionTitleField;
+const titleKey = titleField?.name ?? 'title';
+const assocValue = ctx.getValue?.() ?? ctx.record?.[ctx.collectionField?.name];
+const label = assocValue?.[titleKey];
+```
+
+## Relationship with ctx.collection
+
+| Requirement | Recommended Usage |
+|------|----------|
+| **Current field's collection** | `ctx.collectionField?.collection` or `ctx.collection` |
+| **Field metadata (name, type, interface, enum, etc.)** | `ctx.collectionField` |
+| **Target collection** | `ctx.collectionField?.targetCollection` |
+
+`ctx.collection` usually represents the collection bound to the current block; `ctx.collectionField` represents the definition of the current field in the collection. In scenarios like sub-tables or association fields, the two may differ.
+
+## Notes
+
+- In scenarios such as **JSBlock** or **JSAction (without field binding)**, `ctx.collectionField` is usually `undefined`. It is recommended to use optional chaining before access.
+- If a custom JS field is not bound to a collection field, `ctx.collectionField` may be `null`.
+- `targetCollection` only exists for association type fields (e.g., m2o, o2m, m2m); `enum` only exists for fields with options like select or radioGroup.
+
+## Related
+
+- [ctx.collection](./collection.md): Collection associated with the current context
+- [ctx.model](./model.md): Model where the current execution context is located
+- [ctx.blockModel](./block-model.md): Parent block carrying the current JS
+- [ctx.getValue()](./get-value.md), [ctx.setValue()](./set-value.md): Read and write the current field value

package/dist/ai/docs/runjs/context/collection.md

@@ -0,0 +1,100 @@
+# ctx.collection
+
+The Collection instance associated with the current RunJS execution context, used to access collection metadata, field definitions, primary keys, and other configurations. It usually originates from `ctx.blockModel.collection` or `ctx.collectionField?.collection`.
+
+## Use Cases
+
+| Scenario | Description |
+|------|------|
+| **JSBlock** | The collection bound to the block; can access `name`, `getFields`, `filterTargetKey`, etc. |
+| **JSField / JSItem / JSColumn** | The collection the current field belongs to (or the parent block's collection), used to retrieve field lists, primary keys, etc. |
+| **Table Column / Detail Block** | Used for rendering based on collection structure or passing `filterByTk` when opening popups. |
+
+> Note: `ctx.collection` is available in scenarios where a data block, form block, or table block is bound to a collection. In an independent JSBlock that is not bound to a collection, it may be `null`. It is recommended to perform a null check before use.
+
+## Type Definition
+
+```ts
+collection: Collection | null | undefined;
+```
+
+## Common Properties
+
+| Property | Type | Description |
+|------|------|------|
+| `name` | `string` | Collection name (e.g., `users`, `orders`) |
+| `title` | `string` | Collection title (includes internationalization) |
+| `filterTargetKey` | `string \| string[]` | Primary key field name, used for `filterByTk` and `getFilterByTK` |
+| `dataSourceKey` | `string` | Data source key (e.g., `main`) |
+| `dataSource` | `DataSource` | The data source instance it belongs to |
+| `template` | `string` | Collection template (e.g., `general`, `file`, `tree`) |
+| `titleableFields` | `CollectionField[]` | List of fields that can be displayed as titles |
+| `titleCollectionField` | `CollectionField` | The title field instance |
+
+## Common Methods
+
+| Method | Description |
+|------|------|
+| `getFields(): CollectionField[]` | Get all fields (including inherited ones) |
+| `getField(name: string): CollectionField \| undefined` | Get a single field by field name |
+| `getFieldByPath(path: string): CollectionField \| undefined` | Get a field by path (supports associations, e.g., `user.name`) |
+| `getAssociationFields(types?): CollectionField[]` | Get association fields; `types` can be `['one']`, `['many']`, etc. |
+| `getFilterByTK(record): any` | Extract the primary key value from a record, used for the API's `filterByTk` |
+
+## Relationship with ctx.collectionField and ctx.blockModel
+
+| Requirement | Recommended Usage |
+|------|----------|
+| **Collection associated with current context** | `ctx.collection` (equivalent to `ctx.blockModel?.collection` or `ctx.collectionField?.collection`) |
+| **Collection definition of the current field** | `ctx.collectionField?.collection` (the collection the field belongs to) |
+| **Association target collection** | `ctx.collectionField?.targetCollection` (the target collection of an association field) |
+
+In scenarios like sub-tables, `ctx.collection` might be the association target collection; in standard forms/tables, it is usually the collection bound to the block.
+
+## Examples
+
+### Get Primary Key and Open Popup
+
+```ts
+const primaryKey = ctx.collection?.filterTargetKey ?? 'id';
+await ctx.openView(popupUid, {
+  mode: 'dialog',
+  params: {
+    filterByTk: ctx.record?.[primaryKey],
+    record: ctx.record,
+  },
+});
+```
+
+### Iterate Through Fields for Validation or Linkage
+
+```ts
+const fields = ctx.collection?.getFields() ?? [];
+const requiredFields = fields.filter((f) => f.options?.required);
+for (const f of requiredFields) {
+  const v = ctx.form?.getFieldValue(f.name);
+  if (v == null || v === '') {
+    ctx.message.warning(`${f.title} is required`);
+    return;
+  }
+}
+```
+
+### Get Association Fields
+
+```ts
+const oneToMany = ctx.collection?.getAssociationFields(['many']) ?? [];
+// Used for building sub-tables, associated resources, etc.
+```
+
+## Notes
+
+- `filterTargetKey` is the primary key field name of the collection. Some collections may use a `string[]` for composite primary keys. If not configured, `'id'` is commonly used as a fallback.
+- In scenarios like **sub-tables or association fields**, `ctx.collection` may point to the association target collection, which differs from `ctx.blockModel.collection`.
+- `getFields()` merges fields from inherited collections; local fields override inherited fields with the same name.
+
+## Related
+
+- [ctx.collectionField](./collection-field.md): The collection field definition of the current field
+- [ctx.blockModel](./block-model.md): The parent block hosting the current JS, containing `collection`
+- [ctx.model](./model.md): The current model, which may contain `collection`

package/dist/ai/docs/runjs/context/data-source-manager.md

@@ -0,0 +1,120 @@
+# ctx.dataSourceManager
+
+The Data Source Manager (`DataSourceManager` instance) is used to manage and access multiple data sources (e.g., the main database `main`, logging database `logging`, etc.). It is used when multiple data sources exist or when cross-data source metadata access is required.
+
+## Use Cases
+
+| Scenario | Description |
+|------|------|
+| **Multi-data source** | Enumerate all data sources, or get a specific data source by key. |
+| **Cross-data source access** | Access metadata using the "data source key + collection name" format when the data source of the current context is unknown. |
+| **Get fields by full path** | Use the `dataSourceKey.collectionName.fieldPath` format to retrieve field definitions across different data sources. |
+
+> Note: If you are only operating on the current data source, prioritize using `ctx.dataSource`. Use `ctx.dataSourceManager` only when you need to enumerate or switch between data sources.
+
+## Type Definition
+
+```ts
+dataSourceManager: DataSourceManager;
+
+class DataSourceManager {
+  constructor();
+
+  // Data source management
+  addDataSource(ds: DataSource | DataSourceOptions): void;
+  upsertDataSource(ds: DataSource | DataSourceOptions): void;
+  removeDataSource(key: string): void;
+  clearDataSources(): void;
+
+  // Read data sources
+  getDataSources(): DataSource[];                     // Get all data sources
+  getDataSource(key: string): DataSource | undefined;  // Get data source by key
+
+  // Access metadata directly by data source + collection
+  getCollection(dataSourceKey: string, collectionName: string): Collection | undefined;
+  getCollectionField(fieldPathWithDataSource: string): CollectionField | undefined;
+}
+```
+
+## Relationship with ctx.dataSource
+
+| Requirement | Recommended Usage |
+|------|----------|
+| **Single data source bound to the current context** | `ctx.dataSource` (e.g., the data source of the current page/block) |
+| **Entry point for all data sources** | `ctx.dataSourceManager` |
+| **List or switch data sources** | `ctx.dataSourceManager.getDataSources()` / `getDataSource(key)` |
+| **Get collection within the current data source** | `ctx.dataSource.getCollection(name)` |
+| **Get collection across data sources** | `ctx.dataSourceManager.getCollection(dataSourceKey, collectionName)` |
+| **Get field within the current data source** | `ctx.dataSource.getCollectionField('users.profile.avatar')` |
+| **Get field across data sources** | `ctx.dataSourceManager.getCollectionField('main.users.profile.avatar')` |
+
+## Examples
+
+### Get a Specific Data Source
+
+```ts
+// Get the data source named 'main'
+const mainDS = ctx.dataSourceManager.getDataSource('main');
+
+// Get all collections under this data source
+const collections = mainDS?.getCollections();
+```
+
+### Access Collection Metadata Across Data Sources
+
+```ts
+// Get collection by dataSourceKey + collectionName
+const users = ctx.dataSourceManager.getCollection('main', 'users');
+const orders = ctx.dataSourceManager.getCollection('main', 'orders');
+
+// Get the primary key of the collection
+const primaryKey = users?.filterTargetKey ?? 'id';
+```
+
+### Get Field Definition by Full Path
+
+```ts
+// Format: dataSourceKey.collectionName.fieldPath
+// Get field definition by "data source key.collection name.field path"
+const field = ctx.dataSourceManager.getCollectionField('main.users.profile.avatar');
+
+// Supports association field paths
+const userNameField = ctx.dataSourceManager.getCollectionField('main.orders.createdBy.name');
+```
+
+### Iterate Through All Data Sources
+
+```ts
+const dataSources = ctx.dataSourceManager.getDataSources();
+for (const ds of dataSources) {
+  ctx.logger.info(`Data Source: ${ds.key}, Display Name: ${ds.displayName}`);
+  const collections = ds.getCollections();
+  for (const col of collections) {
+    ctx.logger.info(`  - Collection: ${col.name}`);
+  }
+}
+```
+
+### Dynamically Select Data Source Based on Variables
+
+```ts
+const dsKey = ctx.getVar('dataSourceKey') ?? 'main';
+const collectionName = ctx.getVar('collectionName') ?? 'users';
+const col = ctx.dataSourceManager.getCollection(dsKey, collectionName);
+if (col) {
+  const fields = col.getFields();
+  // ...
+}
+```
+
+## Notes
+
+- The path format for `getCollectionField` is `dataSourceKey.collectionName.fieldPath`, where the first segment is the data source key, followed by the collection name and the field path.
+- `getDataSource(key)` returns `undefined` if the data source does not exist; it is recommended to perform a null check before use.
+- `addDataSource` will throw an exception if the key already exists; `upsertDataSource` will either overwrite the existing one or add a new one.
+
+## Related
+
+- [ctx.dataSource](./data-source.md): Current data source instance
+- [ctx.collection](./collection.md): Collection associated with the current context
+- [ctx.collectionField](./collection-field.md): Collection field definition for the current field