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

package/src/utils/dateVariable.ts

@@ -0,0 +1,397 @@
+/**
+ * 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 dayjs from 'dayjs';
+
+const CTX_DATE_REGEX = /^\{\{\s*ctx\.date(?:\.(.+?))?\s*\}\}$/;
+
+const PRESET_KEYS = new Set([
+  'today',
+  'now',
+  'yesterday',
+  'tomorrow',
+  'thisWeek',
+  'lastWeek',
+  'nextWeek',
+  'thisMonth',
+  'lastMonth',
+  'nextMonth',
+  'thisQuarter',
+  'lastQuarter',
+  'nextQuarter',
+  'thisYear',
+  'lastYear',
+  'nextYear',
+]);
+
+const RELATIVE_DIRECTIONS = new Set(['next', 'past']);
+const RELATIVE_UNITS = new Set(['day', 'week', 'month', 'year']);
+
+function parseCtxDateSegments(value: string): string[] | null {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  const match = trimmed.match(CTX_DATE_REGEX);
+  if (!match) return null;
+  const rawPath = String(match[1] || '');
+  if (!rawPath) return [];
+  return rawPath
+    .split('.')
+    .map((seg) => seg.trim())
+    .filter(Boolean);
+}
+
+export function isCtxDatePathPrefix(pathSegments: string[]): boolean {
+  const segments = withDatePrefix((pathSegments || []).map((seg) => String(seg)));
+  if (segments[0] !== 'date') return false;
+  if (segments.length === 1) return true;
+
+  if (segments[1] === 'preset') {
+    if (segments.length === 2) return true;
+    return segments.length === 3 && PRESET_KEYS.has(segments[2]);
+  }
+
+  if (segments[1] === 'relative') {
+    if (segments.length === 2) return true;
+    if (segments.length === 3) return RELATIVE_DIRECTIONS.has(segments[2]);
+    if (segments.length === 4) {
+      return RELATIVE_DIRECTIONS.has(segments[2]) && RELATIVE_UNITS.has(segments[3]);
+    }
+    if (segments.length === 5) {
+      return (
+        RELATIVE_DIRECTIONS.has(segments[2]) &&
+        RELATIVE_UNITS.has(segments[3]) &&
+        typeof parseNumberToken(segments[4]) === 'number'
+      );
+    }
+    return false;
+  }
+
+  if (segments[1] === 'exact') {
+    if (segments.length === 2) return true;
+
+    if (segments[2] === 'single') {
+      if (segments.length === 3) return true;
+      if (segments.length === 4) return segments[3] === 'date';
+      if (segments.length === 5) return segments[3] === 'date' && /^v.+/.test(segments[4]);
+      return false;
+    }
+
+    if (segments[2] === 'range') {
+      if (segments.length === 3) return true;
+      if (segments.length === 4) return segments[3] === 'date';
+      if (segments.length === 5) return segments[3] === 'date' && /^v.+/.test(segments[4]);
+      if (segments.length === 6) return segments[3] === 'date' && /^v.+/.test(segments[4]) && /^v.+/.test(segments[5]);
+      return false;
+    }
+
+    return false;
+  }
+
+  return false;
+}
+
+function withDatePrefix(pathSegments: string[]): string[] {
+  if (pathSegments[0] === 'date') {
+    return pathSegments;
+  }
+  return ['date', ...pathSegments];
+}
+
+function toCtxDateExpression(pathSegments: string[]): string {
+  const segs = withDatePrefix(pathSegments);
+  return `{{ ctx.${segs.join('.')} }}`;
+}
+
+function utf8ToBase64(input: string): string {
+  const globalBuffer = (globalThis as any)?.Buffer;
+  if (globalBuffer && typeof globalBuffer.from === 'function') {
+    return globalBuffer.from(input, 'utf8').toString('base64');
+  }
+
+  if (typeof btoa === 'function') {
+    const encoded = encodeURIComponent(input).replace(/%([0-9A-F]{2})/g, (_m, p1) =>
+      String.fromCharCode(parseInt(p1, 16)),
+    );
+    return btoa(encoded);
+  }
+
+  throw new Error('No base64 encoder available');
+}
+
+function base64ToUtf8(input: string): string {
+  const globalBuffer = (globalThis as any)?.Buffer;
+  if (globalBuffer && typeof globalBuffer.from === 'function') {
+    return globalBuffer.from(input, 'base64').toString('utf8');
+  }
+
+  if (typeof atob === 'function') {
+    const binary = atob(input);
+    const encoded = Array.from(binary)
+      .map((char) => `%${char.charCodeAt(0).toString(16).padStart(2, '0')}`)
+      .join('');
+    return decodeURIComponent(encoded);
+  }
+
+  throw new Error('No base64 decoder available');
+}
+
+function normalizeToString(value: any): string | undefined {
+  if (value == null) return undefined;
+  if (typeof value === 'string') {
+    const trimmed = value.trim();
+    return trimmed.length ? trimmed : undefined;
+  }
+  if (dayjs.isDayjs(value)) {
+    return value.toISOString();
+  }
+  if (value instanceof Date) {
+    return dayjs(value).toISOString();
+  }
+  if (typeof value === 'number' || typeof value === 'boolean') {
+    return String(value);
+  }
+  return undefined;
+}
+
+function parseNumberToken(token: string): number | undefined {
+  const match = String(token || '').match(/^n(\d+)$/);
+  if (!match) return undefined;
+  const parsed = Number(match[1]);
+  if (!Number.isFinite(parsed) || parsed <= 0) return undefined;
+  return parsed;
+}
+
+function startOfIsoWeek(date: dayjs.Dayjs): dayjs.Dayjs {
+  const day = date.day();
+  const offset = day === 0 ? -6 : 1 - day;
+  return date.add(offset, 'day').startOf('day');
+}
+
+function startOfQuarter(date: dayjs.Dayjs): dayjs.Dayjs {
+  const month = date.month();
+  const quarterStartMonth = Math.floor(month / 3) * 3;
+  return date.month(quarterStartMonth).startOf('month');
+}
+
+export function encodeBase64Url(input: string): string {
+  const base64 = utf8ToBase64(String(input || ''));
+  return base64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/g, '');
+}
+
+export function decodeBase64Url(input: string): string | undefined {
+  try {
+    const raw = String(input || '').replace(/=+$/g, '');
+    if (!raw) return undefined;
+    if (!/^[A-Za-z0-9_-]+$/.test(raw)) return undefined;
+
+    const normalized = raw.replace(/-/g, '+').replace(/_/g, '/');
+    const padLength = normalized.length % 4 === 0 ? 0 : 4 - (normalized.length % 4);
+    const padded = `${normalized}${'='.repeat(padLength)}`;
+    const decoded = base64ToUtf8(padded);
+
+    if (encodeBase64Url(decoded) !== raw) return undefined;
+    return decoded;
+  } catch (_error) {
+    return undefined;
+  }
+}
+
+export function isCtxDateExpression(value: unknown): value is string {
+  if (typeof value !== 'string') return false;
+  return CTX_DATE_REGEX.test(value.trim());
+}
+
+export function isCompleteCtxDatePath(pathSegments: string[]): boolean {
+  if (!isCtxDatePathPrefix(pathSegments)) return false;
+  const segments = withDatePrefix((pathSegments || []).map((seg) => String(seg)));
+  if (segments[0] !== 'date') return false;
+
+  if (segments[1] === 'preset') {
+    return segments.length === 3 && PRESET_KEYS.has(segments[2]);
+  }
+
+  if (segments[1] === 'relative') {
+    if (segments.length !== 5) return false;
+    return (
+      RELATIVE_DIRECTIONS.has(segments[2]) &&
+      RELATIVE_UNITS.has(segments[3]) &&
+      typeof parseNumberToken(segments[4]) === 'number'
+    );
+  }
+
+  if (segments[1] === 'exact' && segments[2] === 'single' && segments[3] === 'date') {
+    return segments.length === 5 && /^v.+/.test(segments[4]);
+  }
+
+  if (segments[1] === 'exact' && segments[2] === 'range' && segments[3] === 'date') {
+    return segments.length === 6 && /^v.+/.test(segments[4]) && /^v.+/.test(segments[5]);
+  }
+
+  return false;
+}
+
+export function parseCtxDateExpression(value: unknown): any {
+  if (!isCtxDateExpression(value)) return undefined;
+  const segments = withDatePrefix(parseCtxDateSegments(value as string) || []);
+
+  if (segments[1] === 'preset' && segments.length === 3 && PRESET_KEYS.has(segments[2])) {
+    return { type: segments[2] };
+  }
+
+  if (
+    segments[1] === 'relative' &&
+    segments.length === 5 &&
+    RELATIVE_DIRECTIONS.has(segments[2]) &&
+    RELATIVE_UNITS.has(segments[3])
+  ) {
+    const amount = parseNumberToken(segments[4]);
+    if (typeof amount === 'number') {
+      return { type: segments[2], unit: segments[3], number: amount };
+    }
+    return undefined;
+  }
+
+  if (segments[1] === 'exact' && segments[2] === 'single' && segments[3] === 'date' && segments.length === 5) {
+    const raw = String(segments[4] || '');
+    if (!raw.startsWith('v')) return undefined;
+    return decodeBase64Url(raw.slice(1));
+  }
+
+  if (segments[1] === 'exact' && segments[2] === 'range' && segments[3] === 'date' && segments.length === 6) {
+    const leftRaw = String(segments[4] || '');
+    const rightRaw = String(segments[5] || '');
+    if (!leftRaw.startsWith('v') || !rightRaw.startsWith('v')) return undefined;
+    const left = decodeBase64Url(leftRaw.slice(1));
+    const right = decodeBase64Url(rightRaw.slice(1));
+    if (typeof left === 'undefined' || typeof right === 'undefined') return undefined;
+    return [left, right];
+  }
+
+  return undefined;
+}
+
+export function serializeCtxDateValue(value: unknown): string | undefined {
+  if (isCtxDateExpression(value)) {
+    return String(value).trim();
+  }
+
+  if (value == null || value === '') {
+    return undefined;
+  }
+
+  if (Array.isArray(value)) {
+    const start = normalizeToString(value[0]);
+    const end = normalizeToString(value[1]);
+    if (start && end) {
+      return toCtxDateExpression([
+        'date',
+        'exact',
+        'range',
+        'date',
+        `v${encodeBase64Url(start)}`,
+        `v${encodeBase64Url(end)}`,
+      ]);
+    }
+    if (start) {
+      return toCtxDateExpression(['date', 'exact', 'single', 'date', `v${encodeBase64Url(start)}`]);
+    }
+    return undefined;
+  }
+
+  if (typeof value === 'object' && value) {
+    const typed = value as { type?: unknown; unit?: unknown; number?: unknown };
+    const type = typeof typed.type === 'string' ? typed.type : '';
+
+    if (type === 'past' || type === 'next') {
+      const unit = typeof typed.unit === 'string' && RELATIVE_UNITS.has(typed.unit) ? typed.unit : 'day';
+      const rawNumber = Number(typed.number);
+      const number = Number.isFinite(rawNumber) && rawNumber > 0 ? Math.floor(rawNumber) : 1;
+      return toCtxDateExpression(['date', 'relative', type, unit, `n${number}`]);
+    }
+
+    if (PRESET_KEYS.has(type)) {
+      return toCtxDateExpression(['date', 'preset', type]);
+    }
+  }
+
+  const single = normalizeToString(value);
+  if (single) {
+    return toCtxDateExpression(['date', 'exact', 'single', 'date', `v${encodeBase64Url(single)}`]);
+  }
+  return undefined;
+}
+
+export function resolveCtxDatePath(pathSegments: string[]): any {
+  const segments = withDatePrefix((pathSegments || []).map((seg) => String(seg)));
+  if (segments[0] !== 'date') return undefined;
+
+  if (segments[1] === 'preset' && segments.length === 3) {
+    const key = segments[2];
+    if (key === 'now') {
+      return dayjs().toISOString();
+    }
+
+    const now = dayjs();
+
+    if (key === 'today') return now.format('YYYY-MM-DD');
+    if (key === 'yesterday') return now.add(-1, 'day').format('YYYY-MM-DD');
+    if (key === 'tomorrow') return now.add(1, 'day').format('YYYY-MM-DD');
+
+    if (key === 'thisWeek') return startOfIsoWeek(now).format('YYYY-MM-DD');
+    if (key === 'lastWeek') return startOfIsoWeek(now.add(-1, 'week')).format('YYYY-MM-DD');
+    if (key === 'nextWeek') return startOfIsoWeek(now.add(1, 'week')).format('YYYY-MM-DD');
+
+    if (key === 'thisMonth') return now.startOf('month').format('YYYY-MM-DD');
+    if (key === 'lastMonth') return now.add(-1, 'month').startOf('month').format('YYYY-MM-DD');
+    if (key === 'nextMonth') return now.add(1, 'month').startOf('month').format('YYYY-MM-DD');
+
+    if (key === 'thisQuarter') return startOfQuarter(now).format('YYYY-MM-DD');
+    if (key === 'lastQuarter') return startOfQuarter(now.add(-3, 'month')).format('YYYY-MM-DD');
+    if (key === 'nextQuarter') return startOfQuarter(now.add(3, 'month')).format('YYYY-MM-DD');
+
+    if (key === 'thisYear') return now.startOf('year').format('YYYY-MM-DD');
+    if (key === 'lastYear') return now.add(-1, 'year').startOf('year').format('YYYY-MM-DD');
+    if (key === 'nextYear') return now.add(1, 'year').startOf('year').format('YYYY-MM-DD');
+
+    return undefined;
+  }
+
+  if (
+    segments[1] === 'relative' &&
+    segments.length === 5 &&
+    RELATIVE_DIRECTIONS.has(segments[2]) &&
+    RELATIVE_UNITS.has(segments[3])
+  ) {
+    const amount = parseNumberToken(segments[4]);
+    if (typeof amount !== 'number') return undefined;
+    const direction = segments[2] === 'past' ? -1 : 1;
+    const unit = segments[3] as dayjs.ManipulateType;
+    return dayjs()
+      .add(direction * amount, unit)
+      .format('YYYY-MM-DD');
+  }
+
+  if (segments[1] === 'exact' && segments[2] === 'single' && segments[3] === 'date' && segments.length === 5) {
+    const token = String(segments[4] || '');
+    if (!token.startsWith('v')) return undefined;
+    return decodeBase64Url(token.slice(1));
+  }
+
+  if (segments[1] === 'exact' && segments[2] === 'range' && segments[3] === 'date' && segments.length === 6) {
+    const leftToken = String(segments[4] || '');
+    const rightToken = String(segments[5] || '');
+    if (!leftToken.startsWith('v') || !rightToken.startsWith('v')) return undefined;
+    const left = decodeBase64Url(leftToken.slice(1));
+    const right = decodeBase64Url(rightToken.slice(1));
+    if (typeof left === 'undefined' || typeof right === 'undefined') return undefined;
+    return [left, right];
+  }
+
+  return undefined;
+}

package/src/utils/exceptions.ts

@@ -34,3 +34,14 @@ export class FlowExitAllException extends Error {
     this.modelUid = modelUid;
   }
 }
+
+/**
+ * 取消当前保存但保持设置弹窗打开
+ * 用于“保存前确认”场景，用户取消时不应关闭弹窗也不应提示错误
+ */
+export class FlowCancelSaveException extends Error {
+  constructor(message = 'Flow settings save cancelled.') {
+    super(message);
+    this.name = 'FlowCancelSaveException';
+  }
+}

package/src/utils/index.ts

@@ -22,7 +22,7 @@ export {
 export { escapeT, getT, tExpr } from './translation';
 
 // 异常类
-export { FlowExitException } from './exceptions';
+export { FlowCancelSaveException, FlowExitAllException, FlowExitException } from './exceptions';
 
 // 流程定义相关
 export { defineAction } from './flow-definitions';
@@ -34,7 +34,14 @@ export { isInheritedFrom } from './inheritance';
 export { resolveCreateModelOptions, resolveDefaultParams, resolveExpressions } from './params-resolvers';
 
 // Schema 工具
-export { compileUiSchema, resolveStepUiSchema, resolveUiMode, shouldHideStepInSettings } from './schema-utils';
+export {
+  compileUiSchema,
+  resolveStepUiSchema,
+  resolveStepDisabledInSettings,
+  resolveUiMode,
+  shouldHideEventInSettings,
+  shouldHideStepInSettings,
+} from './schema-utils';
 
 // Runtime Context Steps 设置
 export { setupRuntimeContextSteps } from './setupRuntimeContextSteps';
@@ -59,9 +66,34 @@ export { extractPropertyPath, formatPathToVariable, isVariableExpression } from
 
 export { clearAutoFlowError, getAutoFlowError, setAutoFlowError, type AutoFlowError } from './autoFlowError';
 export { parsePathnameToViewParams, type ViewParam } from './parsePathnameToViewParams';
+export {
+  decodeBase64Url,
+  encodeBase64Url,
+  isCompleteCtxDatePath,
+  isCtxDatePathPrefix,
+  isCtxDateExpression,
+  parseCtxDateExpression,
+  resolveCtxDatePath,
+  serializeCtxDateValue,
+} from './dateVariable';
 
 // 安全全局对象（window/document）
-export { createSafeDocument, createSafeWindow, createSafeNavigator } from './safeGlobals';
+export {
+  createSafeDocument,
+  createSafeWindow,
+  createSafeNavigator,
+  createSafeRunJSGlobals,
+  runjsWithSafeGlobals,
+} from './safeGlobals';
+
+// RunJS value helpers
+export { isRunJSValue, normalizeRunJSValue, extractUsedVariablePathsFromRunJS, type RunJSValue } from './runjsValue';
+
+// RunJS helpers
+export { resolveRunJSObjectValues } from './resolveRunJSObjectValues';
+
+// RunJS 代码兼容预处理（{{ }}）与 JSX 编译
+export { prepareRunJsCode, preprocessRunJsTemplates } from './runjsTemplateCompat';
 
 // Ephemeral context helper（用于临时注入属性/方法，避免污染父级 ctx）
 export { createEphemeralContext } from './createEphemeralContext';
@@ -69,3 +101,6 @@ export { createEphemeralContext } from './createEphemeralContext';
 // Filter helpers
 export { pruneFilter } from './pruneFilter';
 export { isBeforeRenderFlow } from './flows';
+
+// Module URL resolver
+export { resolveModuleUrl, isCssFile } from './resolveModuleUrl';

package/src/utils/params-resolvers.ts

@@ -409,8 +409,13 @@ export async function preprocessExpression(expression: string, ctx: FlowContext)
 async function compileExpression<TModel extends FlowModel = FlowModel>(expression: string, ctx: FlowContext) {
   // 仅点号路径匹配：ctx.a.b.c（不支持括号/函数/索引），用于数组聚合取值
   const matchDotOnly = (expr: string): string | null => {
-    const m = expr.trim().match(/^ctx\.([a-zA-Z_$][a-zA-Z0-9_$]*(?:\.[a-zA-Z_$][a-zA-Z0-9_$]*)*)$/);
-    return m ? m[1] : null;
+    // 顶层变量名仍使用 JS 标识符规则（与 ctx.defineProperty 保持一致）；
+    // 子路径允许包含 '-'（例如 formValues.oho-test.o2m-users）。
+    const m = expr
+      .trim()
+      .match(/^ctx\.([a-zA-Z_$][a-zA-Z0-9_$]*)(?:\.([a-zA-Z_$][a-zA-Z0-9_$-]*(?:\.[a-zA-Z_$][a-zA-Z0-9_$-]*)*))?$/);
+    if (!m) return null;
+    return m[2] ? `${m[1]}.${m[2]}` : m[1];
   };
 
   // 基于 getValuesByPath 的聚合取值：支持数组扁平化，仅支持 '.' 访问
@@ -423,6 +428,20 @@ async function compileExpression<TModel extends FlowModel = FlowModel>(expressio
     return getValuesByPath(base as object, segs.join('.'));
   };
 
+  const resolveInnerExpression = async (innerExpr: string): Promise<any> => {
+    const dotPath = matchDotOnly(innerExpr);
+    if (dotPath) {
+      const resolved = await resolveDotOnlyPath(dotPath);
+      // 当 dotPath 含 '-' 时可能与减号运算符存在歧义，例如：ctx.aa.bb-ctx.cc。
+      // 若按 path 解析未取到值，则回退到 JS 表达式解析，尽量保持兼容。
+      if (resolved === undefined && dotPath.includes('-')) {
+        return await processExpression(innerExpr, ctx);
+      }
+      return resolved;
+    }
+    return await processExpression(innerExpr, ctx);
+  };
+
   /**
    * 单个表达式模式匹配
    *
@@ -443,11 +462,7 @@ async function compileExpression<TModel extends FlowModel = FlowModel>(expressio
   const singleMatch = expression.match(/^\s*\{\{\s*([^{}]+?)\s*\}\}\s*$/);
   if (singleMatch) {
     const inner = singleMatch[1];
-    const dotPath = matchDotOnly(inner);
-    if (dotPath) {
-      return await resolveDotOnlyPath(dotPath);
-    }
-    return await processExpression(inner, ctx);
+    return await resolveInnerExpression(inner);
   }
 
   /**
@@ -470,8 +485,7 @@ async function compileExpression<TModel extends FlowModel = FlowModel>(expressio
   let result = expression;
 
   for (const [fullMatch, innerExpr] of matches) {
-    const dotPath = matchDotOnly(innerExpr);
-    const value = dotPath ? await resolveDotOnlyPath(dotPath) : await processExpression(innerExpr, ctx);
+    const value = await resolveInnerExpression(innerExpr);
     if (value !== undefined) {
       const replacement = typeof value === 'object' && value !== null ? JSON.stringify(value) : String(value);
       result = result.replace(fullMatch, replacement);

package/src/utils/parsePathnameToViewParams.ts

@@ -116,8 +116,8 @@ export const parsePathnameToViewParams = (pathname: string): ViewParam[] => {
               // 解析失败，按字符串保留
               parsed = decoded;
             }
-          } else if (decoded && decoded.includes('=') && decoded.includes('&')) {
-            // 形如 a=b&c=d 的整体段
+          } else if (decoded && /^[^=&]+=[^=&]*(?:&[^=&]+=[^=&]*)*$/.test(decoded)) {
+            // 形如 a=b 或 a=b&c=d 的整体段
             parsed = parseKeyValuePairs(decoded);
           }
           currentView.filterByTk = parsed;

package/src/utils/resolveModuleUrl.ts

@@ -0,0 +1,91 @@
+/**
+ * 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.
+ */
+
+/**
+ * 解析模块 URL，将相对路径转换为完整的 CDN URL
+ *
+ * @param url - 模块地址（支持相对路径或完整 URL）
+ * @param options - 可选配置
+ * @param options.addSuffix - 是否添加 ESM_CDN_SUFFIX 后缀（如 `+esm`），默认为 `true`
+ * @returns 解析后的完整 URL
+ *
+ * @example
+ * ```ts
+ * // 相对路径会被拼接上 CDN 前缀和后缀（默认添加）
+ * // 如果使用 esm.sh（默认），不需要后缀
+ * resolveModuleUrl('vue@3.4.0')
+ * // => 'https://esm.sh/vue@3.4.0'
+ *
+ * // 如果使用 jsdelivr，需要配置 ESM_CDN_SUFFIX='/+esm'
+ * // resolveModuleUrl('vue@3.4.0') => 'https://cdn.jsdelivr.net/npm/vue@3.4.0/+esm'
+ *
+ * // 不添加后缀（适用于 UMD 库或 CSS 文件）
+ * resolveModuleUrl('vue@3.4.0', { addSuffix: false })
+ * // => 'https://esm.sh/vue@3.4.0' (即使配置了 suffix 也不会添加)
+ *
+ * // 原始 URL（适用于 UMD 库）
+ * resolveModuleUrl('lodash@4.17.21/lodash.js', { raw: true })
+ * // => 'https://esm.sh/lodash@4.17.21/lodash.js?raw' (即使配置了 suffix 也不会添加)
+ *
+ * // 完整 URL 保持不变
+ * resolveModuleUrl('https://cdn.jsdelivr.net/npm/vue@3.4.0')
+ * // => 'https://cdn.jsdelivr.net/npm/vue@3.4.0'
+ * ```
+ */
+export function resolveModuleUrl(url: string, options?: { addSuffix?: boolean; raw?: boolean }): string {
+  if (!url || typeof url !== 'string') {
+    throw new Error('invalid url');
+  }
+
+  const u = url.trim();
+
+  // 如果是完整 URL（http:// 或 https://），直接返回
+  if (u.startsWith('http://') || u.startsWith('https://')) {
+    return u;
+  }
+
+  // 相对路径：拼接 CDN 前缀和后缀
+  const ESM_CDN_BASE_URL = (window as any)['__esm_cdn_base_url__'] || 'https://esm.sh';
+  const ESM_CDN_SUFFIX = options?.addSuffix ? (window as any)['__esm_cdn_suffix__'] || '' : '';
+
+  // 移除 base URL 末尾的斜杠，移除相对路径开头的斜杠
+  const base = ESM_CDN_BASE_URL.replace(/\/$/, '');
+  const path = u.replace(/^\//, '');
+
+  if (options?.raw) {
+    const sep = path.includes('?') ? '&' : '?';
+    return `${base}/${path}${sep}raw`;
+  }
+
+  return `${base}/${path}${ESM_CDN_SUFFIX}`;
+}
+
+/**
+ * 判断 URL 是否为 CSS 文件
+ *
+ * @param url - 文件 URL（支持带 query 和 hash，如 `example.css?v=123`）
+ * @returns 如果是 CSS 文件返回 `true`，否则返回 `false`
+ *
+ * @example
+ * ```ts
+ * isCssFile('style.css') // => true
+ * isCssFile('style.css?v=123') // => true
+ * isCssFile('style.css#section') // => true
+ * isCssFile('script.js') // => false
+ * ```
+ */
+export function isCssFile(url: string): boolean {
+  if (!url || typeof url !== 'string') {
+    return false;
+  }
+
+  // 去掉 query 和 hash 后判断文件扩展名
+  const pathPart = url.split('?')[0].split('#')[0];
+  return pathPart.endsWith('.css');
+}

package/src/utils/resolveRunJSObjectValues.ts

@@ -0,0 +1,46 @@
+/**
+ * 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 { isRunJSValue, normalizeRunJSValue } from './runjsValue';
+import { runjsWithSafeGlobals } from './safeGlobals';
+
+/**
+ * Resolve an object's values, executing any RunJSValue entries via ctx.runjs.
+ *
+ * - Skips `undefined` values
+ * - Skips empty RunJS code (treated as not configured)
+ * - Throws when a RunJS execution fails
+ */
+export async function resolveRunJSObjectValues(ctx: unknown, raw: unknown): Promise<Record<string, any>> {
+  const out: Record<string, any> = {};
+
+  if (!raw || typeof raw !== 'object') return out;
+  if (Array.isArray(raw)) return out;
+
+  for (const [key, value] of Object.entries(raw as Record<string, any>)) {
+    if (typeof value === 'undefined') continue;
+
+    if (isRunJSValue(value)) {
+      const { code, version } = normalizeRunJSValue(value);
+      if (!code.trim()) continue;
+      const ret = await runjsWithSafeGlobals(ctx, code, { version });
+      if (!ret?.success) {
+        throw new Error(`RunJS execution failed for "${key}"`);
+      }
+      if (typeof ret.value !== 'undefined') {
+        out[key] = ret.value;
+      }
+      continue;
+    }
+
+    out[key] = value;
+  }
+
+  return out;
+}