@nocobase/flow-engine 2.0.0-beta.9 → 2.0.0

package/src/resources/__tests__/sqlResource.test.ts

@@ -0,0 +1,60 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+import { FlowEngine } from '../../flowEngine';
+import { SQLResource } from '../sqlResource';
+
+function createSQLResource() {
+  const engine = new FlowEngine();
+  return engine.createResource(SQLResource);
+}
+
+describe('SQLResource - refresh', () => {
+  it('should coalesce multiple refresh calls and settle all awaiters', async () => {
+    vi.useFakeTimers();
+    try {
+      const r = createSQLResource();
+      const run = vi.fn().mockResolvedValue({ data: { ok: 1 }, meta: { page: 1 } });
+      (r as any).run = run;
+
+      const p1 = r.refresh();
+      const p2 = r.refresh();
+
+      await vi.runAllTimersAsync();
+      await expect(p1).resolves.toBeUndefined();
+      await expect(p2).resolves.toBeUndefined();
+      expect(run).toHaveBeenCalledTimes(1);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('should reject all awaiters on failure', async () => {
+    vi.useFakeTimers();
+    try {
+      const r = createSQLResource();
+      const run = vi.fn().mockRejectedValue(new Error('boom'));
+      (r as any).run = run;
+
+      const p1 = r.refresh();
+      const p2 = r.refresh();
+
+      // Attach handlers before timers run to avoid unhandled rejection warnings.
+      const e1 = expect(p1).rejects.toThrow('boom');
+      const e2 = expect(p2).rejects.toThrow('boom');
+      await vi.runAllTimersAsync();
+      await e1;
+      await e2;
+      expect(run).toHaveBeenCalledTimes(1);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});

package/src/resources/baseRecordResource.ts

@@ -12,6 +12,7 @@ import _ from 'lodash';
 import { APIResource } from './apiResource';
 import { FilterItem } from './filterItem';
 import { ResourceError } from './flowResource';
+import { DATA_SOURCE_DIRTY_EVENT } from '../views/viewEvents';
 
 export abstract class BaseRecordResource<TData = any> extends APIResource<TData> {
   protected resourceName: string;
@@ -136,6 +137,36 @@ export abstract class BaseRecordResource<TData = any> extends APIResource<TData>
     return this.resourceName;
   }
 
+  /**
+   * Mark current resource as dirty on the root FlowEngine.
+   * Used to coordinate "refresh on active" across view stacks.
+   */
+  protected markDataSourceDirty(resourceName?: string) {
+    const engine = this.context.engine;
+    if (!engine) return;
+
+    const dataSourceKey = this.getDataSourceKey() || 'main';
+    const resName = resourceName || this.getResourceName();
+    if (!resName) return;
+
+    const affectedResourceNames = new Set<string>([String(resName)]);
+    // Optional safety: association resources like "users.profile" may impact parent collection views.
+    if (typeof resName === 'string' && resName.includes('.')) {
+      affectedResourceNames.add(resName.split('.')[0]);
+    }
+
+    for (const name of affectedResourceNames) {
+      engine.markDataSourceDirty(dataSourceKey, name);
+    }
+
+    // Signal current view to re-evaluate dirty blocks (e.g., same-view sibling refresh).
+    // This is emitted on the *current* engine emitter (view-scoped) so it won't affect other views.
+    engine.emitter?.emit?.(DATA_SOURCE_DIRTY_EVENT, {
+      dataSourceKey,
+      resourceNames: Array.from(affectedResourceNames),
+    });
+  }
+
   setSourceId(sourceId: string | number) {
     this.sourceId = sourceId;
     return this;

package/src/resources/multiRecordResource.ts

@@ -16,6 +16,7 @@ export class MultiRecordResource<TDataItem = any> extends BaseRecordResource<TDa
   protected _data = observable.ref<TDataItem[]>([]);
   protected _meta = observable.ref<Record<string, any>>({});
   private refreshTimer: NodeJS.Timeout | null = null;
+  private refreshWaiters: Array<{ resolve: () => void; reject: (error: any) => void }> = [];
   protected createActionOptions = {};
   protected updateActionOptions = {};
   protected _refreshActionName = 'list';
@@ -113,6 +114,7 @@ export class MultiRecordResource<TDataItem = any> extends BaseRecordResource<TDa
   async create(data: TDataItem, options?: AxiosRequestConfig & { refresh?: boolean }): Promise<void> {
     const config = this.mergeRequestConfig({ data }, this.createActionOptions, options);
     const res = await this.runAction('create', config);
+    this.markDataSourceDirty();
     this.emit('saved', data);
     if (options?.refresh !== false) {
       await this.refresh();
@@ -145,6 +147,7 @@ export class MultiRecordResource<TDataItem = any> extends BaseRecordResource<TDa
       options,
     );
     await this.runAction('update', config);
+    this.markDataSourceDirty();
     this.emit('saved', data);
     await this.refresh();
   }
@@ -170,6 +173,7 @@ export class MultiRecordResource<TDataItem = any> extends BaseRecordResource<TDa
       options,
     );
     await this.runAction('destroy', config);
+    this.markDataSourceDirty();
     const currentPage = this.getPage();
     const lastPage = Math.ceil((this.getCount() - _.castArray(filterByTk).length) / this.getPageSize());
     if (currentPage > lastPage) {
@@ -197,7 +201,11 @@ export class MultiRecordResource<TDataItem = any> extends BaseRecordResource<TDa
 
     // 设置新的定时器，在下一个事件循环执行
     return new Promise<void>((resolve, reject) => {
+      this.refreshWaiters.push({ resolve, reject });
       this.refreshTimer = setTimeout(async () => {
+        const waiters = this.refreshWaiters;
+        this.refreshWaiters = [];
+        this.refreshTimer = null;
         try {
           this.clearError();
           this.loading = true;
@@ -213,13 +221,12 @@ export class MultiRecordResource<TDataItem = any> extends BaseRecordResource<TDa
             this.setPageSize(meta.pageSize);
           }
           this.emit('refresh');
-          this.loading = false;
-          resolve();
+          waiters.forEach((w) => w.resolve());
         } catch (error) {
           this.setError(error);
-          reject(error instanceof Error ? error : new Error(String(error)));
+          const err = error instanceof Error ? error : new Error(String(error));
+          waiters.forEach((w) => w.reject(err));
         } finally {
-          this.refreshTimer = null;
           this.loading = false;
         }
       });

package/src/resources/singleRecordResource.ts

@@ -44,6 +44,8 @@ export class SingleRecordResource<TData = any> extends BaseRecordResource<TData>
       ...config,
       data: result,
     });
+    // Mark as dirty before emitting/refreshing so other views can refresh when activated.
+    this.markDataSourceDirty();
     this.emit('saved', data);
     if (options?.refresh !== false) {
       await this.refresh();
@@ -61,6 +63,7 @@ export class SingleRecordResource<TData = any> extends BaseRecordResource<TData>
       options,
     );
     await this.runAction('destroy', config);
+    this.markDataSourceDirty();
     this.setData(null);
   }
 

package/src/resources/sqlResource.ts

@@ -27,10 +27,10 @@ type SQLSaveOptions = {
 };
 
 export class FlowSQLRepository {
-  protected ctx: FlowEngineContext;
+  protected ctx: FlowContext;
 
-  constructor(ctx: FlowEngineContext) {
-    this.ctx = new FlowContext() as FlowEngineContext;
+  constructor(ctx: FlowContext) {
+    this.ctx = new FlowContext();
     this.ctx.addDelegate(ctx);
     this.ctx.defineProperty('offset', {
       get: () => 0,
@@ -110,6 +110,7 @@ export class SQLResource<TData = any> extends BaseRecordResource<TData> {
   protected _data = observable.ref<TData>(null);
   protected _meta = observable.ref<Record<string, any>>({});
   private refreshTimer: NodeJS.Timeout | null = null;
+  private refreshWaiters: Array<{ resolve: () => void; reject: (error: any) => void }> = [];
   private _debugEnabled = false;
   private _sql: string;
 
@@ -272,7 +273,11 @@ export class SQLResource<TData = any> extends BaseRecordResource<TData> {
 
     // 设置新的定时器，在下一个事件循环执行
     return new Promise<void>((resolve, reject) => {
+      this.refreshWaiters.push({ resolve, reject });
       this.refreshTimer = setTimeout(async () => {
+        const waiters = this.refreshWaiters;
+        this.refreshWaiters = [];
+        this.refreshTimer = null;
         try {
           this.clearError();
           this.loading = true;
@@ -281,12 +286,12 @@ export class SQLResource<TData = any> extends BaseRecordResource<TData> {
           this.setData(data).setMeta(meta);
           this.loading = false;
           this.emit('refresh');
-          resolve();
+          waiters.forEach((w) => w.resolve());
         } catch (error) {
           this.setError(error);
-          reject(error instanceof Error ? error : new Error(String(error)));
+          const err = error instanceof Error ? error : new Error(String(error));
+          waiters.forEach((w) => w.reject(err));
         } finally {
-          this.refreshTimer = null;
           this.loading = false;
         }
       });

package/src/runjs-context/contexts/FormJSFieldItemRunJSContext.ts

@@ -19,6 +19,11 @@ FormJSFieldItemRunJSContext.define({
     value: `Current field value (read-only in display mode; in controlled scenarios, use setProps to modify).`,
     record: `Current record data object (read-only).
       Contains all field values of the parent record.`,
+    formValues: {
+      description: 'Snapshot of current form values (object). Available in form contexts (CreateForm/EditForm).',
+      detail: 'Record<string, any>',
+      examples: ['const { name, status } = ctx.formValues || {};'],
+    },
   },
   methods: {
     onRefReady: `Wait for form field container DOM element to be ready before executing callback.
@@ -36,6 +41,11 @@ FormJSFieldItemRunJSContext.define(
       element: 'ElementProxy，表单字段容器',
       value: '字段值（展示模式为只读；受控场景用 setProps 修改）',
       record: '当前记录（只读）',
+      formValues: {
+        description: '当前表单值快照（对象）。仅表单相关上下文可用（Create/Edit Form）。',
+        detail: 'Record<string, any>',
+        examples: ['const { name, status } = ctx.formValues || {};'],
+      },
     },
     methods: {
       onRefReady: '容器就绪回调',

package/src/runjs-context/contexts/JSBlockRunJSContext.ts

@@ -34,7 +34,9 @@ JSBlockRunJSContext.define({
       Parameters: (ref: React.RefObject, callback: (element: HTMLElement) => void, timeout?: number) => void
       Example: ctx.onRefReady(ctx.ref, (el) => { el.innerHTML = "Ready!" })`,
     requireAsync: 'Load external library: `const lib = await ctx.requireAsync(url)`',
-    importAsync: 'Dynamically import ESM module: `const mod = await ctx.importAsync(url)`',
+    importAsync:
+      'Dynamically import an ESM module by URL: `const mod = await ctx.importAsync(url)`.\n' +
+      'Note: if the module has only a default export, ctx.importAsync returns that default value directly (no `.default`).',
   },
 });
 
@@ -57,7 +59,9 @@ JSBlockRunJSContext.define(
     methods: {
       onRefReady: '容器 ref 就绪回调：\n```js\nctx.onRefReady(ctx.ref, el => { /* ... */ })\n```',
       requireAsync: '加载外部库：`const lib = await ctx.requireAsync(url)`',
-      importAsync: '按 URL 动态导入 ESM 模块：`const mod = await ctx.importAsync(url)`',
+      importAsync:
+        '按 URL 动态导入 ESM 模块：`const mod = await ctx.importAsync(url)`。\n' +
+        '注意：当模块只有 default 一个导出时，ctx.importAsync 会直接返回 default 值（无需再写 `.default`）。',
     },
   },
   { locale: 'zh-CN' },

package/src/runjs-context/contexts/JSEditableFieldRunJSContext.ts

@@ -0,0 +1,106 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+import { FlowRunJSContext } from '../../flowContext';
+
+/**
+ * RunJS context for JSEditableFieldModel (form editable custom field).
+ * NOTE: Some APIs (e.g., getValue/setValue/element) are provided by the model's runtime handler.
+ * This doc is used for editor autocomplete and AI coding assistance.
+ */
+export class JSEditableFieldRunJSContext extends FlowRunJSContext {}
+
+JSEditableFieldRunJSContext.define({
+  label: 'JSEditableField RunJS context',
+  properties: {
+    element: {
+      description:
+        'ElementProxy instance providing a safe DOM container for field rendering. In editable mode this container is typically a <span> element.',
+      detail: 'ElementProxy',
+    },
+    value: {
+      description:
+        'Current field value (read-only snapshot). In editable scenarios, prefer ctx.getValue()/ctx.setValue(v) for two-way binding.',
+      detail: 'any',
+      examples: ['const v = ctx.getValue?.() ?? ctx.value;', 'ctx.setValue?.("new value");'],
+    },
+    record: {
+      description: 'Current record data object (read-only). Available in forms that are bound to a record.',
+      detail: 'Record<string, any>',
+    },
+    form: {
+      description: 'Ant Design Form instance for reading/writing other fields. Example: ctx.form.getFieldValue("name")',
+      detail: 'FormInstance',
+    },
+    formValues: {
+      description:
+        'Snapshot of current form values (object). Prefer ctx.form.getFieldsValue() when you need the latest values.',
+      detail: 'Record<string, any>',
+    },
+    namePath: {
+      description: 'Field namePath in the form (array). Useful for advanced Form operations.',
+      detail: 'Array<string | number>',
+    },
+    disabled: 'Whether the field is disabled (boolean).',
+    readOnly: 'Whether the field is read-only (boolean).',
+  },
+  methods: {
+    getValue: {
+      description: 'Get current field value (recommended for editable custom fields).',
+      detail: '() => any',
+      completion: { insertText: 'ctx.getValue?.()' },
+    },
+    setValue: {
+      description: 'Set current field value (two-way binding with the form).',
+      detail: '(value: any) => void',
+      completion: { insertText: 'ctx.setValue?.(value)' },
+      examples: ['ctx.setValue?.(e.target.value);'],
+    },
+  },
+});
+
+JSEditableFieldRunJSContext.define(
+  {
+    label: 'JS 可编辑字段 RunJS 上下文',
+    properties: {
+      element: {
+        description: 'ElementProxy，字段渲染的安全容器（通常为 <span> 容器）。',
+        detail: 'ElementProxy',
+      },
+      value: {
+        description: '字段当前值（只读快照）。可编辑场景建议使用 ctx.getValue()/ctx.setValue(v) 做双向绑定。',
+        detail: 'any',
+        examples: ['const v = ctx.getValue?.() ?? ctx.value;', 'ctx.setValue?.("新值");'],
+      },
+      record: { description: '当前记录对象（只读；表单绑定记录时可用）。', detail: 'Record<string, any>' },
+      form: { description: 'Ant Design Form 实例，可读写其它字段。', detail: 'FormInstance' },
+      formValues: {
+        description: '当前表单值快照（对象）。需要最新值可用 ctx.form.getFieldsValue()。',
+        detail: 'Record<string, any>',
+      },
+      namePath: { description: '字段在表单中的 namePath（数组）。', detail: 'Array<string | number>' },
+      disabled: '是否禁用（boolean）',
+      readOnly: '是否只读（boolean）',
+    },
+    methods: {
+      getValue: {
+        description: '获取字段当前值（可编辑字段推荐使用）。',
+        detail: '() => any',
+        completion: { insertText: 'ctx.getValue?.()' },
+      },
+      setValue: {
+        description: '设置字段当前值（与表单双向绑定）。',
+        detail: '(value: any) => void',
+        completion: { insertText: 'ctx.setValue?.(value)' },
+        examples: ['ctx.setValue?.(e.target.value);'],
+      },
+    },
+  },
+  { locale: 'zh-CN' },
+);

package/src/runjs-context/contexts/JSItemRunJSContext.ts

@@ -20,6 +20,11 @@ JSItemRunJSContext.define({
       Provides access to the data resource associated with the current form context.`,
     record: `Current record data object (read-only).
       Contains all field values of the parent record.`,
+    formValues: {
+      description: 'Snapshot of current form values (object). Available in form contexts (CreateForm/EditForm).',
+      detail: 'Record<string, any>',
+      examples: ['const { name, status } = ctx.formValues || {};'],
+    },
   },
   methods: {
     onRefReady: `Wait for form item container DOM element to be ready before executing callback.
@@ -34,6 +39,11 @@ JSItemRunJSContext.define(
       element: 'ElementProxy，表单项渲染容器，支持 innerHTML/append 等 DOM 操作',
       resource: '当前资源（只读）',
       record: '当前记录（只读）',
+      formValues: {
+        description: '当前表单值快照（对象）。仅表单相关上下文可用（Create/Edit Form）。',
+        detail: 'Record<string, any>',
+        examples: ['const { name, status } = ctx.formValues || {};'],
+      },
     },
     methods: {
       onRefReady: '容器就绪后执行回调。参数：(ref, callback, timeout?)',