@nocobase/flow-engine 2.0.0-alpha.2

package/lib/flowContext.d.ts

@@ -0,0 +1,215 @@
+/**
+ * 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 { ISchema } from '@formily/json-schema';
+import { APIClient } from '@nocobase/sdk';
+import type { Router } from '@remix-run/router';
+import { MessageInstance } from 'antd/es/message/interface';
+import type { HookAPI } from 'antd/es/modal/useModal';
+import { NotificationInstance } from 'antd/es/notification/interface';
+import pino from 'pino';
+import React from 'react';
+import type { Location } from 'react-router-dom';
+import { DataSourceManager } from './data-source';
+import { FlowEngine } from './flowEngine';
+import { JSRunner, JSRunnerOptions } from './JSRunner';
+import { FlowModel, ForkFlowModel } from './models';
+import { FlowResource, FlowSQLRepository } from './resources';
+import type { ActionDefinition, EventDefinition, ResourceType } from './types';
+import { JSONValue } from './utils/params-resolvers';
+import type { RecordRef } from './utils/serverContextParams';
+import { FlowView, FlowViewer } from './views/FlowView';
+type Getter<T = any> = (ctx: FlowContext) => T | Promise<T>;
+export interface MetaTreeNode {
+    name: string;
+    title: string;
+    type: string;
+    interface?: string;
+    uiSchema?: ISchema;
+    render?: (props: any) => JSX.Element;
+    paths: string[];
+    parentTitles?: string[];
+    disabled?: boolean | (() => boolean);
+    disabledReason?: string | (() => string | undefined);
+    children?: MetaTreeNode[] | (() => Promise<MetaTreeNode[]>);
+}
+export interface PropertyMeta {
+    type: string;
+    title: string;
+    interface?: string;
+    uiSchema?: ISchema;
+    render?: (props: any) => JSX.Element;
+    sort?: number;
+    properties?: Record<string, PropertyMeta> | (() => Promise<Record<string, PropertyMeta>>);
+    disabled?: boolean | (() => boolean);
+    disabledReason?: string | (() => string | undefined);
+    buildVariablesParams?: (ctx: FlowContext) => RecordRef | Record<string, any> | Promise<RecordRef | Record<string, any> | undefined> | undefined;
+}
+export type PropertyMetaFactory = {
+    (): PropertyMeta | Promise<PropertyMeta | null> | null;
+    /**
+     * 仅作为“是否可能存在子节点”的提示，不影响 meta 工厂本身的惰性特性。
+     * - true（默认）：视为可能有 children，节点会提供 children 懒加载器（用于级联展开加载子级）。
+     * - false：视为没有 children，不渲染展开箭头，且不提供 children 懒加载器；
+     *          但节点本身的 meta 工厂仍保持惰性（在需要时仍可解析出 title/type 等信息）。
+     */
+    hasChildren?: boolean;
+    title?: string;
+    sort?: number;
+};
+export type PropertyMetaOrFactory = PropertyMeta | PropertyMetaFactory;
+export interface PropertyOptions {
+    value?: any;
+    once?: boolean;
+    get?: Getter;
+    cache?: boolean;
+    observable?: boolean;
+    meta?: PropertyMetaOrFactory;
+    resolveOnServer?: boolean | ((subPath: string) => boolean);
+}
+type RouteOptions = {
+    name?: string;
+    path?: string;
+    params?: Record<string, any>;
+    pathname?: string;
+};
+export declare class FlowContext {
+    #private;
+    _props: Record<string, PropertyOptions>;
+    _methods: Record<string, (...args: any[]) => any>;
+    protected _cache: Record<string, any>;
+    protected _observableCache: Record<string, any>;
+    protected _delegates: FlowContext[];
+    protected _pending: Record<string, Promise<any>>;
+    [key: string]: any;
+    private _metaNodeCache;
+    createProxy(): FlowContext;
+    constructor();
+    defineProperty(key: string, options: PropertyOptions): void;
+    defineMethod(name: string, fn: (...args: any[]) => any, des?: string): void;
+    removeCache(key: string): boolean;
+    delegate(ctx: FlowContext): void;
+    addDelegate(ctx: FlowContext): void;
+    clearDelegates(): void;
+    removeDelegate(ctx: FlowContext): void;
+    /**
+     * 清除特定 meta 对象的缓存
+     */
+    private _clearMetaNodeCacheFor;
+    has(key: string): boolean;
+    /**
+     * 获取属性元数据树
+     * 返回的 MetaTreeNode 中可能包含异步的延迟加载逻辑
+     * @param value 可选参数，指定要获取的属性路径，格式: "{{ ctx.propertyName }}"
+     * @returns MetaTreeNode[] 根级属性的元数据树，或指定路径的子树
+     *
+     * @example
+     * // 同步调用，获取完整 meta tree
+     * const metaTree = flowContext.getPropertyMetaTree();
+     *
+     * // 获取指定属性的子树
+     * const subTree = flowContext.getPropertyMetaTree("{{ ctx.user }}");
+     *
+     * // 获取多层级属性的子树
+     * const profileTree = flowContext.getPropertyMetaTree("{{ ctx.user.profile }}");
+     */
+    getPropertyMetaTree(value?: string, options?: {
+        flatten?: boolean;
+    }): MetaTreeNode[];
+    _getPropertiesMeta(): Record<string, PropertyMetaOrFactory>;
+    protected _getOwnProperty(key: string, currentContext: any): any;
+    protected _getOwnMethod(key: string, flowContext?: FlowContext): any;
+    _findPropertyInDelegates(delegates: FlowContext[], key: string): PropertyOptions | undefined;
+    _findInDelegates(delegates: FlowContext[], key: string): any;
+    _hasInDelegates(delegates: FlowContext[], key: string): boolean;
+    /**
+     * 获取属性定义选项（包含代理链）。
+     *
+     * - 优先查找当前上下文自身通过 defineProperty 注册的属性定义
+     * - 若自身不存在，则沿委托链（delegates）向上查找第一个命中的定义
+     *
+     * @param key 顶层属性名（例如 'user'、'view'）
+     * @returns 属性定义选项，或 undefined（未定义）
+     */
+    getPropertyOptions(key: string): PropertyOptions | undefined;
+}
+export declare class FlowRunjsContext extends FlowContext {
+    constructor(delegate: FlowContext);
+}
+declare class BaseFlowEngineContext extends FlowContext {
+    router: Router;
+    dataSourceManager: DataSourceManager;
+    requireAsync: (url: string) => Promise<any>;
+    createJSRunner: (options?: JSRunnerOptions) => JSRunner;
+    /**
+     * @deprecated use `resolveJsonTemplate` instead
+     */
+    renderJson: (template: JSONValue) => Promise<any>;
+    resolveJsonTemplate: (template: JSONValue) => Promise<any>;
+    runjs: (code: string, variables?: Record<string, any>, options?: JSRunnerOptions) => Promise<any>;
+    copyToClipboard: (text: string) => Promise<void>;
+    getAction: <TModel extends FlowModel = FlowModel, TCtx extends FlowContext = FlowContext>(name: string) => ActionDefinition<TModel, TCtx> | undefined;
+    getActions: <TModel extends FlowModel = FlowModel, TCtx extends FlowContext = FlowContext>() => Map<string, ActionDefinition<TModel, TCtx>>;
+    getEvents: <TModel extends FlowModel = FlowModel, TCtx extends FlowContext = FlowContext>() => Map<string, EventDefinition<TModel, TCtx>>;
+    runAction: (actionName: string, params?: Record<string, any>) => Promise<any> | any;
+    engine: FlowEngine;
+    api: APIClient;
+    viewer: FlowViewer;
+    view: FlowView;
+    modal: HookAPI;
+    message: MessageInstance;
+    notification: NotificationInstance;
+    route: RouteOptions;
+    location: Location;
+    sql: FlowSQLRepository;
+    logger: pino.Logger;
+}
+declare class BaseFlowModelContext extends BaseFlowEngineContext {
+    model: FlowModel;
+    ref: React.RefObject<HTMLDivElement>;
+    getAction: <TModel extends FlowModel = FlowModel, TCtx extends FlowContext = FlowContext>(name: string) => ActionDefinition<TModel, TCtx> | undefined;
+    getActions: <TModel extends FlowModel = FlowModel, TCtx extends FlowContext = FlowContext>() => Map<string, ActionDefinition<TModel, TCtx>>;
+    getEvents: <TModel extends FlowModel = FlowModel, TCtx extends FlowContext = FlowContext>() => Map<string, EventDefinition<TModel, TCtx>>;
+    runAction: (actionName: string, params?: Record<string, any>) => Promise<any> | any;
+    createResource: <T extends FlowResource = FlowResource>(resourceType: ResourceType<T>) => T;
+}
+export declare class FlowEngineContext extends BaseFlowEngineContext {
+    engine: FlowEngine;
+    constructor(engine: FlowEngine);
+}
+export declare class FlowModelContext extends BaseFlowModelContext {
+    constructor(model: FlowModel);
+}
+export declare class FlowForkModelContext extends BaseFlowModelContext {
+    master: FlowModel;
+    fork: ForkFlowModel;
+    constructor(master: FlowModel, fork: ForkFlowModel);
+}
+export declare class FlowRuntimeContext<TModel extends FlowModel = FlowModel, TMode extends 'runtime' | 'settings' = any> extends BaseFlowModelContext {
+    model: TModel;
+    flowKey: string;
+    protected _mode: TMode;
+    steps: Record<string, {
+        params: Record<string, any>;
+        uiSchema?: any;
+        result?: any;
+    }>;
+    stepResults: Record<string, any>;
+    useResource: (className: 'APIResource' | 'SingleRecordResource' | 'MultiRecordResource') => void;
+    getStepParams: (stepKey: string) => Record<string, any>;
+    setStepParams: (stepKey: string, params?: any) => void;
+    getStepResults: (stepKey: string) => any;
+    runAction: (actionName: string, params?: Record<string, any>) => Promise<any> | any;
+    constructor(model: TModel, flowKey: string, _mode?: TMode);
+    protected _getOwnProperty(key: string): any;
+    exit(): void;
+    exitAll(): void;
+    get mode(): TMode;
+}
+export type FlowSettingsContext<TModel extends FlowModel = FlowModel> = FlowRuntimeContext<TModel, 'settings'>;
+export {};