@nocobase/flow-engine 2.0.0-alpha.4 → 2.0.0-alpha.41

package/src/runjs-context/snippets/scene/table/export-selected-json.snippet.ts

@@ -0,0 +1,45 @@
+/**
+ * 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 type { SnippetModule } from '../../types';
+import { JSCollectionActionRunJSContext } from '../../../contexts/JSCollectionActionRunJSContext';
+
+const snippet: SnippetModule = {
+  contexts: [JSCollectionActionRunJSContext],
+  prefix: 'sn-act-export',
+  label: 'Export selected rows as JSON',
+  description: 'Download selected rows as a JSON file',
+  locales: {
+    'zh-CN': {
+      label: '导出选中行为 JSON',
+      description: '将选中的行导出为 JSON 文件下载',
+    },
+  },
+  content: `
+const rows = ctx.resource?.getSelectedRows?.() || [];
+if (!rows.length) {
+  ctx.message.warning(ctx.t('Please select at least one row'));
+  return;
+}
+
+// Create JSON file and download
+const jsonStr = JSON.stringify(rows, null, 2);
+const blob = new Blob([jsonStr], { type: 'application/json' });
+const url = URL.createObjectURL(blob);
+const link = document.createElement('a');
+link.href = url;
+link.download = \`export-\${new Date().toISOString().split('T')[0]}.json\`;
+link.click();
+URL.revokeObjectURL(url);
+
+ctx.message.success(ctx.t('Exported {{count}} records', { count: rows.length }));
+`,
+};
+
+export default snippet;

package/src/runjs-context/snippets/scene/{actions → table}/iterate-selected-rows.snippet.ts

@@ -7,10 +7,20 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 
-export default {
-  contexts: ['JSCollectionActionRunJSContext'],
+import type { SnippetModule } from '../../types';
+import { JSCollectionActionRunJSContext } from '../../../contexts/JSCollectionActionRunJSContext';
+
+const snippet: SnippetModule = {
+  contexts: [JSCollectionActionRunJSContext],
   prefix: 'sn-act-iterate',
   label: 'Iterate selected rows',
+  description: 'Loop through selected rows and process each record',
+  locales: {
+    'zh-CN': {
+      label: '遍历选中行',
+      description: '遍历选中行并处理每条记录',
+    },
+  },
   content: `
 const rows = ctx.resource?.getSelectedRows?.() || [];
 for (const row of rows) {
@@ -19,3 +29,5 @@ for (const row of rows) {
 ctx.message.success(ctx.t('Processed {{count}} rows', { count: rows.length }));
 `,
 };
+
+export default snippet;

package/src/runjs-context/snippets/types.ts

@@ -7,11 +7,15 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 
+export type SnippetContextSpecifier = string | { name: string } | (new (...args: any[]) => any);
+
 export type SnippetModule = {
   content: string;
-  contexts?: string[]; // e.g., ['JSBlockRunJSContext'] or ['*']
+  contexts?: SnippetContextSpecifier[]; // e.g., [JSBlockRunJSContext] or ['*']
   versions?: string[]; // e.g., ['v1'] or ['*']
+  scenes?: string[]; // logical placement hints like ['form', 'table']
   prefix?: string; // completion trigger text
   label?: string; // display name in snippets list
   description?: string; // optional longer description
+  locales?: Record<string, { label?: string; description?: string }>;
 };

package/src/scheduler/ModelOperationScheduler.ts

@@ -0,0 +1,304 @@
+/**
+ * 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 { uid as genUid } from 'uid/secure';
+import type { FlowEngine } from '../flowEngine';
+import type { FlowModel } from '../models/flowModel';
+
+type LifecycleType =
+  | 'created'
+  | 'mounted'
+  | 'unmounted'
+  | 'destroyed'
+  | `event:${string}:start`
+  | `event:${string}:end`
+  | `event:${string}:error`;
+
+export type ScheduleWhen = LifecycleType | ((e: LifecycleEvent) => boolean);
+
+export interface ScheduleOptions {
+  when?: ScheduleWhen;
+}
+
+export type ScheduledCancel = () => boolean;
+
+export interface LifecycleEvent {
+  type: LifecycleType;
+  uid: string;
+  model?: FlowModel;
+  runId?: string;
+  error?: any;
+  inputArgs?: Record<string, any>;
+  result?: any;
+}
+
+type ScheduledItem = {
+  id: string;
+  fromUid: string;
+  toUid: string;
+  fn: (model: FlowModel) => Promise<void> | void;
+  options: ScheduleOptions;
+};
+
+export class ModelOperationScheduler {
+  private itemsByTargetUid = new Map<string, Map<string, ScheduledItem>>();
+  private itemIdsByFromUid = new Map<string, Set<string>>();
+  private itemsById = new Map<string, ScheduledItem>();
+
+  private unbindHandlers: Array<() => void> = [];
+  private subscribedEventNames = new Set<string>();
+
+  constructor(private engine: FlowEngine) {
+    this.bindEngineLifecycle();
+  }
+
+  /** 外部调用入口 */
+  schedule(
+    fromModelOrUid: FlowModel | string,
+    toUid: string,
+    fn: (model: FlowModel) => Promise<void> | void,
+    options?: ScheduleOptions,
+  ): ScheduledCancel {
+    const fromUid = typeof fromModelOrUid === 'string' ? fromModelOrUid : fromModelOrUid?.uid;
+    if (!fromUid) {
+      throw new Error('scheduleModelOperation: invalid from model or uid');
+    }
+    if (!toUid || typeof toUid !== 'string') {
+      throw new Error('scheduleModelOperation: invalid target uid');
+    }
+
+    const item: ScheduledItem = {
+      id: genUid(),
+      fromUid,
+      toUid,
+      fn,
+      options: {
+        // 默认语义：仅当 when === 'created' 时，对“已存在的目标”进行一次立即执行；
+        // 其它 when 不做立即执行，需等待后续真实生命周期事件。
+        when: options?.when ?? 'created',
+      },
+    };
+
+    // 注册结构
+    let targetMap = this.itemsByTargetUid.get(toUid);
+    if (!targetMap) {
+      targetMap = new Map();
+      this.itemsByTargetUid.set(toUid, targetMap);
+    }
+    targetMap.set(item.id, item);
+    let fromSet = this.itemIdsByFromUid.get(fromUid);
+    if (!fromSet) {
+      fromSet = new Set();
+      this.itemIdsByFromUid.set(fromUid, fromSet);
+    }
+    fromSet.add(item.id);
+    this.itemsById.set(item.id, item);
+
+    // 若是 event:xxx:start/end 语义，确保已订阅对应的 model:event 通道
+    this.ensureEventSubscriptionIfNeeded(item.options.when);
+
+    const modelNow = this.engine.getModel<FlowModel>(toUid);
+    if (modelNow && item.options.when === 'created') {
+      // 仅 when === 'created' 时，对“已存在的目标”立即执行一次
+      void this.tryExecuteOnce(item.id, { type: 'created', uid: toUid, model: modelNow });
+    }
+
+    return () => this.internalCancel(item.id);
+  }
+
+  cancel(filter: { fromUid?: string; toUid?: string }) {
+    const { fromUid, toUid } = filter || {};
+    if (toUid && this.itemsByTargetUid.has(toUid)) {
+      const map = this.itemsByTargetUid.get(toUid);
+      if (map)
+        for (const item of map.values()) {
+          if (fromUid && item.fromUid !== fromUid) continue;
+          this.internalCancel(item.id);
+        }
+      return;
+    }
+    if (fromUid && this.itemIdsByFromUid.has(fromUid)) {
+      const set = this.itemIdsByFromUid.get(fromUid);
+      if (set)
+        for (const id of Array.from(set)) {
+          const it = this.itemsById.get(id);
+          if (!it) continue;
+          if (toUid && it.toUid !== toUid) continue;
+          this.internalCancel(id);
+        }
+    }
+  }
+
+  /** 引擎关闭时释放 */
+  dispose() {
+    try {
+      for (const unbind of this.unbindHandlers) {
+        try {
+          unbind();
+        } catch (err) {
+          // 忽略解绑异常
+          void err;
+        }
+      }
+    } finally {
+      this.unbindHandlers = [];
+    }
+
+    // 统一取消剩余任务（将触发 cleanupItem，从而移除 abort 监听与计时器）
+    for (const map of this.itemsByTargetUid.values()) {
+      for (const item of map.values()) this.internalCancel(item.id);
+    }
+    this.itemsByTargetUid.clear();
+    this.itemIdsByFromUid.clear();
+  }
+
+  private bindEngineLifecycle() {
+    const emitter = this.engine.emitter;
+    if (!emitter || typeof emitter.on !== 'function') return;
+
+    const onCreated = (e: LifecycleEvent) => {
+      this.processLifecycleEvent(e.uid, { ...e, type: 'created' });
+    };
+    emitter.on('model:created', onCreated);
+    this.unbindHandlers.push(() => emitter.off('model:created', onCreated));
+
+    const onMounted = (e: LifecycleEvent) => {
+      this.processLifecycleEvent(e.uid, { ...e, type: 'mounted' });
+    };
+    emitter.on('model:mounted', onMounted);
+    this.unbindHandlers.push(() => emitter.off('model:mounted', onMounted));
+
+    const onGenericBeforeStart = (e: LifecycleEvent) => {
+      this.processLifecycleEvent(e.uid, { ...e, type: 'event:beforeRender:start' });
+    };
+    emitter.on('model:event:beforeRender:start', onGenericBeforeStart);
+    this.unbindHandlers.push(() => emitter.off('model:event:beforeRender:start', onGenericBeforeStart));
+
+    const onGenericBeforeEnd = (e: LifecycleEvent) => {
+      this.processLifecycleEvent(e.uid, { ...e, type: 'event:beforeRender:end' });
+    };
+    emitter.on('model:event:beforeRender:end', onGenericBeforeEnd);
+    this.unbindHandlers.push(() => emitter.off('model:event:beforeRender:end', onGenericBeforeEnd));
+
+    const onUnmounted = (e: LifecycleEvent) => {
+      this.processLifecycleEvent(e.uid, { ...e, type: 'unmounted' });
+    };
+    emitter.on('model:unmounted', onUnmounted);
+    this.unbindHandlers.push(() => emitter.off('model:unmounted', onUnmounted));
+
+    const onDestroyed = (e: LifecycleEvent) => {
+      const targetBucket = this.itemsByTargetUid.get(e.uid);
+      const event = { ...e, type: 'destroyed' as const };
+      if (targetBucket && targetBucket.size) {
+        const ids = Array.from(targetBucket.keys());
+        for (const id of ids) {
+          const it = this.itemsById.get(id);
+          if (!it) continue;
+          if (this.shouldTrigger(it.options.when, event)) {
+            void this.tryExecuteOnce(id, event);
+          } else {
+            this.internalCancel(id);
+          }
+        }
+      }
+    };
+    emitter.on('model:destroyed', onDestroyed);
+    this.unbindHandlers.push(() => emitter.off('model:destroyed', onDestroyed));
+  }
+
+  private ensureEventSubscriptionIfNeeded(when?: ScheduleWhen) {
+    if (!when || typeof when !== 'string') return;
+    const parsed = this.parseEventWhen(when);
+    if (!parsed) return;
+    const { name } = parsed;
+    if (this.subscribedEventNames.has(name)) return;
+    this.subscribedEventNames.add(name);
+    const emitter = this.engine.emitter;
+    const onStart = (e: LifecycleEvent) => {
+      this.processLifecycleEvent(e.uid, { ...e, type: `event:${name}:start` as const });
+    };
+    const onEnd = (e: LifecycleEvent) => {
+      this.processLifecycleEvent(e.uid, { ...e, type: `event:${name}:end` as const });
+    };
+    const onError = (e: LifecycleEvent) => {
+      this.processLifecycleEvent(e.uid, { ...e, type: `event:${name}:error` as const });
+    };
+    emitter.on(`model:event:${name}:start`, onStart);
+    emitter.on(`model:event:${name}:end`, onEnd);
+    emitter.on(`model:event:${name}:error`, onError);
+    this.unbindHandlers.push(() => emitter.off(`model:event:${name}:start`, onStart));
+    this.unbindHandlers.push(() => emitter.off(`model:event:${name}:end`, onEnd));
+    this.unbindHandlers.push(() => emitter.off(`model:event:${name}:error`, onError));
+  }
+
+  private parseEventWhen(when?: ScheduleWhen): { name: string; phase: 'start' | 'end' | 'error' } | null {
+    if (!when || typeof when !== 'string') return null;
+    const m = /^event:([^:]+):(start|end|error)$/.exec(when);
+    if (!m) return null;
+    return { name: m[1], phase: m[2] as 'start' | 'end' | 'error' };
+  }
+
+  private processLifecycleEvent(targetUid: string, event: LifecycleEvent) {
+    const targetBucket = this.itemsByTargetUid.get(targetUid);
+    if (!targetBucket || targetBucket.size === 0) return;
+    const ids = Array.from(targetBucket.keys());
+    for (const id of ids) {
+      const item = this.itemsById.get(id);
+      if (!item) continue;
+      const should = this.shouldTrigger(item.options.when, event);
+      if (!should) continue;
+      void this.tryExecuteOnce(id, event);
+    }
+  }
+
+  private shouldTrigger(when: ScheduleWhen | undefined, event: LifecycleEvent): boolean {
+    if (!when) return false;
+    if (typeof when === 'function') return !!when(event);
+    return when === event.type;
+  }
+
+  private async tryExecuteOnce(id: string, event: LifecycleEvent) {
+    const item = this.takeItem(id);
+    if (!item) return;
+    try {
+      const model = event.model || this.engine.getModel<FlowModel>(item.toUid);
+      if (!model) return;
+      await Promise.resolve(item.fn(model));
+    } catch (err) {
+      this.engine.logger?.error?.(
+        { err, id, fromUid: item.fromUid, toUid: item.toUid, when: item.options.when },
+        'ModelOperationScheduler: operation execution failed',
+      );
+    }
+  }
+
+  private internalCancel(id: string) {
+    return !!this.takeItem(id);
+  }
+
+  private takeItem(id: string): ScheduledItem | undefined {
+    const it = this.itemsById.get(id);
+    if (!it) return undefined;
+    const { toUid, fromUid } = it;
+    const map = this.itemsByTargetUid.get(toUid);
+    if (map) {
+      map.delete(id);
+      if (map.size === 0) this.itemsByTargetUid.delete(toUid);
+    }
+    const set = this.itemIdsByFromUid.get(fromUid);
+    if (set) {
+      set.delete(id);
+      if (set.size === 0) this.itemIdsByFromUid.delete(fromUid);
+    }
+    this.itemsById.delete(id);
+    return it;
+  }
+}
+
+export default ModelOperationScheduler;

package/src/types.ts

@@ -10,6 +10,7 @@
 import { ISchema } from '@formily/json-schema';
 import { SubModelItem } from './components';
 import { FlowContext, FlowModelContext, FlowRuntimeContext, FlowSettingsContext } from './flowContext';
+import type { PropertyOptions } from './flowContext';
 import type { FlowEngine } from './flowEngine';
 import type { FlowModel } from './models';
 import { FilterGroupOptions } from './resources';
@@ -134,6 +135,8 @@ export enum ActionScene {
   BLOCK_LINKAGE_RULES = 1,
   /** 表单字段级联动规则可用 */
   FIELD_LINKAGE_RULES,
+  /** 子表单字段级联动规则可用 */
+  SUB_FORM_FIELD_LINKAGE_RULES,
   /** 详情字段级联动规则可用 */
   DETAILS_FIELD_LINKAGE_RULES,
   /** 按钮级联动规则可用 */
@@ -157,6 +160,26 @@ export interface ActionDefinition<TModel extends FlowModel = FlowModel, TCtx ext
   uiMode?: StepUIMode | ((ctx: FlowRuntimeContext<TModel>) => StepUIMode | Promise<StepUIMode>);
   scene?: ActionScene | ActionScene[];
   sort?: number;
+  /**
+   * 在执行 Action 前为 ctx 定义临时属性。
+   * - 仅支持 PropertyOptions 形态（例如：{ foo: { value: 5 } }）；
+   * - 或函数形式（接收 ctx，返回 PropertyOptions 对象；支持 Promise）。
+   */
+  defineProperties?:
+    | Record<string, PropertyOptions>
+    | ((ctx: TCtx) => Record<string, PropertyOptions> | Promise<Record<string, PropertyOptions>>);
+  /**
+   * 在执行 Action 前为 ctx 定义临时方法。
+   * - 支持 JSON 形式（对象的值应为函数）
+   * - 或函数形式（接收 ctx，返回方法对象；支持 Promise）
+   */
+  defineMethods?:
+    | Record<string, (this: TCtx, ...args: any[]) => any>
+    | ((
+        ctx: TCtx,
+      ) =>
+        | Record<string, (this: TCtx, ...args: any[]) => any>
+        | Promise<Record<string, (this: TCtx, ...args: any[]) => any>>);
 }
 
 /**
@@ -185,6 +208,16 @@ export type FlowEvent<TModel extends FlowModel = FlowModel> =
   | FlowEventName
   | { eventName: FlowEventName; defaultParams?: Record<string, any> };
 
+/**
+ * 事件分发选项。
+ */
+export interface DispatchEventOptions {
+  /** 是否顺序执行（默认并行） */
+  sequential?: boolean;
+  /** 是否使用缓存（默认 false；beforeRender 的默认值为 true，可覆盖） */
+  useCache?: boolean;
+}
+
 /**
  * 事件定义：用于事件注册表（全局/模型类级）。
  */
@@ -300,6 +333,7 @@ export interface IFlowModelRepository<T extends FlowModel = FlowModel> {
   save(model: T, options?: { onlyStepParams?: boolean }): Promise<Record<string, any>>;
   destroy(uid: string): Promise<boolean>;
   move(sourceId: string, targetId: string, position: 'before' | 'after'): Promise<void>;
+  duplicate(uid: string): Promise<Record<string, any> | null>;
 }
 
 /**

package/src/utils/__tests__/flows.test.ts

@@ -0,0 +1,65 @@
+/**
+ * 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, test, expect } from 'vitest';
+import { FlowEngine } from '../../flowEngine';
+import { FlowModel } from '../../models/flowModel';
+import { isBeforeRenderFlow } from '../index';
+
+describe('utils/isBeforeRenderFlow', () => {
+  test('identifies beforeRender by on string', () => {
+    const engine = new FlowEngine();
+    class M extends FlowModel {}
+    engine.registerModels({ M });
+    const m = engine.createModel({ use: 'M' });
+    m.registerFlow('A', { on: 'beforeRender', steps: {} });
+    const flow = m.flowRegistry.getFlow('A')!;
+    expect(isBeforeRenderFlow(flow)).toBe(true);
+  });
+
+  test('identifies beforeRender by on object', () => {
+    const engine = new FlowEngine();
+    class M extends FlowModel {}
+    engine.registerModels({ M });
+    const m = engine.createModel({ use: 'M' });
+    m.registerFlow('B', { on: { eventName: 'beforeRender' }, steps: {} });
+    const flow = m.flowRegistry.getFlow('B')!;
+    expect(isBeforeRenderFlow(flow)).toBe(true);
+  });
+
+  test('treats missing on and non-manual as beforeRender', () => {
+    const engine = new FlowEngine();
+    class M extends FlowModel {}
+    engine.registerModels({ M });
+    const m = engine.createModel({ use: 'M' });
+    m.registerFlow('C', { steps: {} });
+    const flow = m.flowRegistry.getFlow('C')!;
+    expect(isBeforeRenderFlow(flow)).toBe(true);
+  });
+
+  test('manual flow is not beforeRender when on is missing', () => {
+    const engine = new FlowEngine();
+    class M extends FlowModel {}
+    engine.registerModels({ M });
+    const m = engine.createModel({ use: 'M' });
+    m.registerFlow('D', { manual: true, steps: {} });
+    const flow = m.flowRegistry.getFlow('D')!;
+    expect(isBeforeRenderFlow(flow)).toBe(false);
+  });
+
+  test('non-beforeRender event is not beforeRender', () => {
+    const engine = new FlowEngine();
+    class M extends FlowModel {}
+    engine.registerModels({ M });
+    const m = engine.createModel({ use: 'M' });
+    m.registerFlow('E', { on: { eventName: 'click' }, steps: {} });
+    const flow = m.flowRegistry.getFlow('E')!;
+    expect(isBeforeRenderFlow(flow)).toBe(false);
+  });
+});

package/src/utils/__tests__/jsxTransform.test.ts

@@ -0,0 +1,38 @@
+/**
+ * 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, it, expect } from 'vitest';
+import { compileRunJs } from '../../utils/jsxTransform';
+
+describe('compileRunJs', () => {
+  it('returns original code when no JSX is present', async () => {
+    const src = `const a = 1; const b = a + 1;`;
+    const out = await compileRunJs(src);
+    expect(out).toBe(src);
+  });
+
+  it('transforms JSX when sucrase is available (skip if missing)', async () => {
+    const src = `ctx.render(<div className="x">hi</div>);`;
+
+    // Try to import sucrase to decide if this environment has it installed
+    const hasSucrase = await import('sucrase').then(() => true).catch(() => false);
+
+    const out = await compileRunJs(src);
+
+    if (!hasSucrase) {
+      // Environment without sucrase: current implementation falls back to original code
+      expect(out).toBe(src);
+      return;
+    }
+
+    // sucrase available: output should contain React.createElement mapping
+    expect(out).not.toBe(src);
+    expect(out).toMatch(/ctx\.React\.createElement/);
+  });
+});

package/src/utils/__tests__/parsePathnameToViewParams.test.ts

@@ -101,4 +101,29 @@ describe('parsePathnameToViewParams', () => {
     const result = parsePathnameToViewParams('///admin//xxx//tab//yyy//');
     expect(result).toEqual([{ viewUid: 'xxx', tabUid: 'yyy' }]);
   });
+
+  test('should parse filterByTk from key-value encoded segment into object', () => {
+    const kv = encodeURIComponent('id=1&tenant=ac');
+    const path = `/admin/xxx/filterbytk/${kv}`;
+    const result = parsePathnameToViewParams(path);
+    expect(result).toEqual([{ viewUid: 'xxx', filterByTk: { id: '1', tenant: 'ac' } }]);
+  });
+
+  test('should parse filterByTk from JSON object segment', () => {
+    const json = encodeURIComponent('{"id":"1","tenant":"ac"}');
+    const path = `/admin/xxx/filterbytk/${json}`;
+    const result = parsePathnameToViewParams(path);
+    expect(result).toEqual([{ viewUid: 'xxx', filterByTk: { id: '1', tenant: 'ac' } }]);
+  });
+
+  test('should keep non-object JSON (array/number) as string for filterByTk', () => {
+    const arr = encodeURIComponent('["a"]');
+    const num = encodeURIComponent('123');
+    const t = encodeURIComponent('true');
+    expect(parsePathnameToViewParams(`/admin/xxx/filterbytk/${arr}`)).toEqual([
+      { viewUid: 'xxx', filterByTk: '["a"]' },
+    ]);
+    expect(parsePathnameToViewParams(`/admin/xxx/filterbytk/${num}`)).toEqual([{ viewUid: 'xxx', filterByTk: '123' }]);
+    expect(parsePathnameToViewParams(`/admin/xxx/filterbytk/${t}`)).toEqual([{ viewUid: 'xxx', filterByTk: 'true' }]);
+  });
 });

package/src/utils/__tests__/pruneFilter.test.ts

@@ -0,0 +1,38 @@
+/**
+ * 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, it, expect } from 'vitest';
+import { pruneFilter } from '../pruneFilter';
+
+describe('pruneFilter', () => {
+  it('keeps boolean false and number 0', () => {
+    const input = { a: { $eq: false }, b: { $eq: 0 } };
+    const out = pruneFilter(input);
+    expect(out).toEqual(input);
+  });
+
+  it('removes null/undefined/empty string and empty containers', () => {
+    const input = { a: null, b: undefined, c: '', d: [], e: {} } as any;
+    const out = pruneFilter(input);
+    expect(out).toBeUndefined();
+  });
+
+  it('works recursively with nested objects/arrays', () => {
+    const input = {
+      $and: [{ isRead: { $eq: false } }, { name: { $eq: '' } }, {}, [], { nested: { empty: {}, ok: 1 } }],
+    } as any;
+    const out = pruneFilter(input);
+    expect(out).toEqual({ $and: [{ isRead: { $eq: false } }, { nested: { ok: 1 } }] });
+  });
+
+  it('returns undefined for empty arrays/objects produced by pruning', () => {
+    expect(pruneFilter([null, undefined, '', [], {}] as any)).toBeUndefined();
+    expect(pruneFilter({ a: { b: '' } } as any)).toBeUndefined();
+  });
+});

package/src/utils/__tests__/safeGlobals.test.ts

@@ -8,7 +8,7 @@
  */
 
 import { describe, expect, it } from 'vitest';
-import { createSafeDocument, createSafeWindow } from '../safeGlobals';
+import { createSafeDocument, createSafeWindow, createSafeNavigator } from '../safeGlobals';
 
 describe('safeGlobals', () => {
   it('createSafeWindow exposes only allowed globals and extras', () => {
@@ -26,4 +26,25 @@ describe('safeGlobals', () => {
     expect(doc.bar).toBe(true);
     expect(() => doc.cookie).toThrow(/not allowed/);
   });
+
+  it('createSafeNavigator exposes limited props and guards others', () => {
+    const nav: any = createSafeNavigator();
+    // clipboard object should always exist
+    expect(typeof nav.clipboard).toBe('object');
+    // writeText may or may not exist depending on environment
+    if (typeof navigator !== 'undefined' && (navigator as any).clipboard?.writeText) {
+      expect(typeof nav.clipboard.writeText).toBe('function');
+    } else {
+      expect(typeof nav.clipboard.writeText === 'undefined' || typeof nav.clipboard.writeText === 'function').toBe(
+        true,
+      );
+    }
+    // readable properties
+    expect(() => void nav.onLine).not.toThrow();
+    expect(() => void nav.language).not.toThrow();
+    expect(() => void nav.languages).not.toThrow();
+    // blocked properties
+    expect(() => (nav as any).geolocation).toThrow(/not allowed/);
+    expect(() => (nav as any).userAgent).toThrow(/not allowed/);
+  });
 });