@univerjs/sheets-formula 0.5.2 → 0.5.3-experimental.20250106-e3b7a39

package/lib/types/facade/f-formula.d.ts

@@ -1,5 +1,6 @@
-import { CalculationMode } from '@univerjs/sheets-formula';
-import { FFormula } from '@univerjs/engine-formula';
+import { IDisposable, ILocales } from '@univerjs/core';
+import { IFunctionInfo, FFormula } from '@univerjs/engine-formula';
+import { CalculationMode, IRegisterAsyncFunction, IRegisterFunction } from '@univerjs/sheets-formula';
 export interface IFFormulaSheetsMixin {
     /**
      * Update the calculation mode of the formula.
@@ -7,9 +8,160 @@ export interface IFFormulaSheetsMixin {
      * @returns
      */
     setInitialFormulaComputing(calculationMode: CalculationMode): void;
+    /**
+     * Register a custom synchronous formula function.
+     * @param name - The name of the function to register. This will be used in formulas (e.g., =MYFUNC())
+     * @param func - The implementation of the function
+     * @param description - A string describing the function's purpose and usage
+     * @returns A disposable object that will unregister the function when disposed
+     * @example
+     * ```js
+     * univerAPI.getFormula().registerFunction('HELLO', (name) => `Hello, ${name}!`, 'A simple greeting function');
+     *
+     * // Use the function in a cell
+     * univerAPI.getActiveWorkbook().getActiveSheet().getRange('A1').setValue('World');
+     * univerAPI.getActiveWorkbook().getActiveSheet().getRange('A2').setValue({ f: '=HELLO(A1)' });
+     * // A2 will display: "Hello, World!"
+     * ```
+     * @example
+     * ```js
+     * univerAPI.getFormula().registerFunction(
+     *   'DISCOUNT',
+     *   (price, discountPercent) => price * (1 - discountPercent / 100),
+     *   'Calculates final price after discount'
+     * );
+     *
+     * // Use in cell
+     * univerAPI.getActiveWorkbook().getActiveSheet().getRange('A1').setValue(100);
+     * univerAPI.getActiveWorkbook().getActiveSheet().getRange('A2').setValue({ f: '=DISCOUNT(A1, 20)' });
+     * // A2 will display: 80
+     * ```
+     */
+    registerFunction(name: string, func: IRegisterFunction, description?: string): IDisposable;
+    /**
+     * Register a custom synchronous formula function with localization support.
+     * @param name - The name of the function to register. This will be used in formulas (e.g., =MYFUNC())
+     * @param func - The implementation of the function
+     * @param options - Object containing locales and description
+     * @returns A disposable object that will unregister the function when disposed
+     * @example
+     * ```js
+     * univerAPI.getFormula().registerFunction('HELLO',
+     *   (name) => {
+     *     return `Hello, ${name}!`;
+     *   },
+     *   {
+     *     description: 'customFunction.HELLO.description',
+     *     locales: {
+     *       'zhCN': {
+     *         'customFunction' : {
+     *           'HELLO' : {
+     *             'description': '一个简单的问候函数'
+     *           }
+     *         }
+     *       },
+     *       'enUS': {
+     *         'customFunction' : {
+     *           'HELLO' : {
+     *             'description': 'A simple greeting function'
+     *           }
+     *         }
+     *       }
+     *     }
+     *   }
+     * );
+     *
+     * // Use in cell
+     * univerAPI.getActiveWorkbook().getActiveSheet().getRange('A1').setValue({ f: '=HELLO("John")' });
+     * // A1 will display: "Hello, John!"
+     * ```
+     */
+    registerFunction(name: string, func: IRegisterFunction, { locales, description }: {
+        locales?: ILocales;
+        description?: string | IFunctionInfo;
+    }): IDisposable;
+    /**
+     * Register a custom asynchronous formula function.
+     * @param name - The name of the function to register. This will be used in formulas (e.g., =ASYNCFUNC())
+     * @param func - The async implementation of the function
+     * @returns A disposable object that will unregister the function when disposed
+     * @example
+     * ```js
+     * univerAPI.getFormula().registerAsyncFunction('RANDOM_DELAYED',
+     *   async () => {
+     *     await new Promise(resolve => setTimeout(resolve, 500));
+     *     return Math.random();
+     *   },
+     *   'Mock a random number generation function'
+     * );
+     *
+     * // Use in cell
+     * univerAPI.getActiveWorkbook().getActiveSheet().getRange('A1').setValue({ f: '=RANDOM_DELAYED()' });
+     * // After 0.5 second, A1 will display a random number
+     * ```
+     */
+    registerAsyncFunction(name: string, func: IRegisterAsyncFunction, description?: string): IDisposable;
+    /**
+     * Register a custom asynchronous formula function with description.
+     * @param name - The name of the function to register. This will be used in formulas (e.g., =ASYNCFUNC())
+     * @param func - The async implementation of the function
+     * @param description - A string describing the function's purpose and usage
+     * @returns A disposable object that will unregister the function when disposed
+     * @example
+     * ```js
+     * // Mock a user score fetching function
+     * univerAPI.getFormula().registerAsyncFunction('FETCH_USER_SCORE',
+     *   async (userId) => {
+     *     await new Promise(resolve => setTimeout(resolve, 1000));
+     *     // Mock fetching user score from database
+     *     return userId * 10 + Math.floor(Math.random() * 20);
+     *   },
+     *   {
+     *     description: 'customFunction.description.FETCH_USER_SCORE',
+     *     locales: {
+     *       'zhCN': {
+     *          'customFunction': {
+     *              'description': {
+     *                  'FETCH_USER_SCORE': '从数据库中获取用户分数'
+     *              }
+     *          }
+     *       },
+     *       'enUS': {
+     *          'customFunction': {
+     *              'description': {
+     *                  'FETCH_USER_SCORE': 'Mock fetching user score from database'
+     *              }
+     *          }
+     *       }
+     *     }
+     *   }
+     * );
+     *
+     * // Use in cell
+     * univerAPI.getActiveWorkbook().getActiveSheet().getRange('A1').setValue({ f: '=FETCH_USER_SCORE(42)' });
+     * // After 1 second, A1 will display a score
+     * ```
+     */
+    registerAsyncFunction(name: string, func: IRegisterAsyncFunction, { locales, description }: {
+        locales?: ILocales;
+        description?: string | IFunctionInfo;
+    }): IDisposable;
 }
 export declare class FFormulaSheetsMixin extends FFormula implements IFFormulaSheetsMixin {
+    /**
+     * RegisterFunction may be executed multiple times, triggering multiple formula forced refreshes.
+     */
+    private _debouncedFormulaCalculation;
+    /**
+     * Initialize the FUniver instance.
+     * @private
+     */
+    _initialize(): void;
     setInitialFormulaComputing(calculationMode: CalculationMode): void;
+    registerFunction(name: string, func: IRegisterFunction): IDisposable;
+    registerFunction(name: string, func: IRegisterFunction, description: string): IDisposable;
+    registerAsyncFunction(name: string, func: IRegisterAsyncFunction): IDisposable;
+    registerAsyncFunction(name: string, func: IRegisterAsyncFunction, description: string): IDisposable;
 }
 declare module '@univerjs/engine-formula' {
     interface FFormula extends IFFormulaSheetsMixin {

package/lib/types/facade/f-univer.d.ts

@@ -3,7 +3,7 @@ import { IRegisterFunctionParams } from '@univerjs/sheets-formula';
 export interface IFUniverSheetsFormulaMixin {
     /**
      * Register a function to the spreadsheet.
-     *
+     * @deprecated Use `univerAPI.getFormula().registerFunction` instead.
      * @param {IRegisterFunctionParams} config The configuration of the function.
      * @returns {IDisposable} The disposable instance.
      */
@@ -11,12 +11,11 @@ export interface IFUniverSheetsFormulaMixin {
 }
 export declare class FUniverSheetsFormulaMixin extends FUniver implements IFUniverSheetsFormulaMixin {
     /**
-     * registerFunction may be executed multiple times, triggering multiple formula forced refreshes
+     * RegisterFunction may be executed multiple times, triggering multiple formula forced refreshes.
      */
     private _debouncedFormulaCalculation;
     /**
      * Initialize the FUniver instance.
-     *
      * @private
      */
     _initialize(): void;

package/lib/types/index.d.ts

@@ -18,6 +18,7 @@ export { OtherFormulaMarkDirty } from './commands/mutations/formula.mutation';
 export { UpdateDefinedNameController } from './controllers/update-defined-name.controller';
 export { TriggerCalculationController } from './controllers/trigger-calculation.controller';
 export { CalculationMode, type IUniverSheetsFormulaBaseConfig, PLUGIN_CONFIG_KEY_BASE } from './controllers/config.schema';
+export type { IRegisterAsyncFunction, IRegisterFunction, ISingleFunctionRegisterParams } from './services/register-function.service';
 export { UpdateFormulaController } from './controllers/update-formula.controller';
 export { DescriptionService, IDescriptionService, type ISearchItem } from './services/description.service';
 export type { IFormulaInfo, IOtherFormulaResult } from './services/formula-common';

package/lib/types/services/register-function.service.d.ts

@@ -1,8 +1,9 @@
 import { IDisposable, ILocales, Disposable, LocaleService } from '@univerjs/core';
-import { IFunctionInfo, PrimitiveValueType, IFunctionService } from '@univerjs/engine-formula';
+import { FormulaFunctionValueType, IFunctionInfo, IFunctionService } from '@univerjs/engine-formula';
 import { IDescriptionService } from './description.service';
 import { IRemoteRegisterFunctionService } from './remote/remote-register-function.service';
-export type IRegisterFunction = (...arg: Array<PrimitiveValueType | PrimitiveValueType[][]>) => PrimitiveValueType | PrimitiveValueType[][];
+export type IRegisterFunction = (...arg: Array<FormulaFunctionValueType>) => FormulaFunctionValueType;
+export type IRegisterAsyncFunction = (...arg: Array<FormulaFunctionValueType>) => Promise<FormulaFunctionValueType>;
 export type IRegisterFunctionList = [[IRegisterFunction, string, string?]];
 export interface IFormulaCustomFunctionService {
     /**
@@ -50,15 +51,50 @@ export interface IRegisterFunctionService {
      * @param params
      */
     registerFunctions(params: IRegisterFunctionParams): IDisposable;
+    /**
+     * register a single function
+     * @param params
+     */
+    registerFunction(params: ISingleFunctionRegisterParams): IDisposable;
+    /**
+     * register a single async function
+     * @param params
+     */
+    registerAsyncFunction(params: ISingleFunctionRegisterParams): IDisposable;
 }
 export declare const IRegisterFunctionService: import('@wendellhu/redi').IdentifierDecorator<IRegisterFunctionService>;
+export interface ISingleFunctionRegisterParams {
+    /**
+     * function name
+     */
+    name: string;
+    /**
+     * function calculation
+     */
+    func: IRegisterFunction | IRegisterAsyncFunction;
+    /**
+     * function description
+     */
+    description: string | IFunctionInfo;
+    /**
+     * function locales
+     */
+    locales?: ILocales;
+    /**
+     * function async
+     */
+    async?: boolean;
+}
 export declare class RegisterFunctionService extends Disposable implements IRegisterFunctionService {
     private readonly _localeService;
     private readonly _descriptionService;
     private readonly _functionService;
     private readonly _remoteRegisterFunctionService?;
     constructor(_localeService: LocaleService, _descriptionService: IDescriptionService, _functionService: IFunctionService, _remoteRegisterFunctionService?: IRemoteRegisterFunctionService | undefined);
+    registerFunction(params: ISingleFunctionRegisterParams): IDisposable;
+    registerAsyncFunction(params: ISingleFunctionRegisterParams): IDisposable;
     registerFunctions(params: IRegisterFunctionParams): IDisposable;
+    private _registerSingleFunction;
     private _registerLocalExecutors;
     private _registerRemoteExecutors;
 }

package/lib/types/services/remote/remote-register-function.service.d.ts

@@ -1,6 +1,7 @@
 import { IFunctionService } from '@univerjs/engine-formula';
 export interface IRemoteRegisterFunctionService {
     registerFunctions(serializedFuncs: Array<[string, string]>): Promise<void>;
+    registerAsyncFunctions(serializedFuncs: Array<[string, string]>): Promise<void>;
     unregisterFunctions(names: string[]): Promise<void>;
 }
 export declare const RemoteRegisterFunctionServiceName = "sheets-formula.remote-register-function.service";
@@ -12,5 +13,6 @@ export declare class RemoteRegisterFunctionService implements IRemoteRegisterFun
     private readonly _functionService;
     constructor(_functionService: IFunctionService);
     registerFunctions(serializedFuncs: Array<[string, string]>): Promise<void>;
+    registerAsyncFunctions(serializedFuncs: Array<[string, string]>): Promise<void>;
     unregisterFunctions(names: string[]): Promise<void>;
 }

package/lib/umd/facade.js

@@ -1 +1 @@
-(function(e,i){typeof exports=="object"&&typeof module<"u"?i(require("@univerjs/core"),require("@univerjs/engine-formula"),require("@univerjs/sheets-formula")):typeof define=="function"&&define.amd?define(["@univerjs/core","@univerjs/engine-formula","@univerjs/sheets-formula"],i):(e=typeof globalThis<"u"?globalThis:e||self,i(e.UniverCore,e.UniverEngineFormula,e.UniverSheetsFormula))})(this,function(e,i,t){"use strict";class s extends e.FUniver{_initialize(){this._debouncedFormulaCalculation=e.debounce(()=>{this._commandService.executeCommand(i.SetFormulaCalculationStartMutation.id,{commands:[],forceCalculation:!0},{onlyLocal:!0})},10)}registerFunction(r){let n=this._injector.get(t.IRegisterFunctionService);n||(this._injector.add([t.IRegisterFunctionService,{useClass:t.RegisterFunctionService}]),n=this._injector.get(t.IRegisterFunctionService));const c=n.registerFunctions(r);return this._debouncedFormulaCalculation(),c}}e.FUniver.extend(s);class u extends i.FFormula{setInitialFormulaComputing(r){const c=this._injector.get(e.LifecycleService).stage,a=this._injector.get(e.ILogService),f=this._injector.get(e.IConfigService);c>e.LifecycleStages.Starting&&a.warn("[FFormula]","CalculationMode is called after the Starting lifecycle and will take effect the next time the Univer Sheet is constructed. If you want it to take effect when the Univer Sheet is initialized this time, consider calling it before the Ready lifecycle or using configuration.");const o=f.getConfig(t.PLUGIN_CONFIG_KEY_BASE);o&&(o.initialFormulaComputing=r)}}i.FFormula.extend(u)});
+(function(i,c){typeof exports=="object"&&typeof module<"u"?c(require("@univerjs/core"),require("@univerjs/engine-formula"),require("@univerjs/sheets-formula")):typeof define=="function"&&define.amd?define(["@univerjs/core","@univerjs/engine-formula","@univerjs/sheets-formula"],c):(i=typeof globalThis<"u"?globalThis:i||self,c(i.UniverCore,i.UniverEngineFormula,i.UniverSheetsFormula))})(this,function(i,c,t){"use strict";class l extends i.FUniver{_initialize(){this._debouncedFormulaCalculation=i.debounce(()=>{this._commandService.executeCommand(c.SetFormulaCalculationStartMutation.id,{commands:[],forceCalculation:!0},{onlyLocal:!0})},10)}registerFunction(o){let r=this._injector.get(t.IRegisterFunctionService);r||(this._injector.add([t.IRegisterFunctionService,{useClass:t.RegisterFunctionService}]),r=this._injector.get(t.IRegisterFunctionService));const e=r.registerFunctions(o);return this._debouncedFormulaCalculation(),e}}i.FUniver.extend(l);class d extends c.FFormula{_initialize(){this._debouncedFormulaCalculation=i.debounce(()=>{this._commandService.executeCommand(c.SetFormulaCalculationStartMutation.id,{commands:[],forceCalculation:!0},{onlyLocal:!0})},10)}setInitialFormulaComputing(o){const e=this._injector.get(i.LifecycleService).stage,n=this._injector.get(i.ILogService),s=this._injector.get(i.IConfigService);e>i.LifecycleStages.Starting&&n.warn("[FFormula]","CalculationMode is called after the Starting lifecycle and will take effect the next time the Univer Sheet is constructed. If you want it to take effect when the Univer Sheet is initialized this time, consider calling it before the Ready lifecycle or using configuration.");const u=s.getConfig(t.PLUGIN_CONFIG_KEY_BASE);u&&(u.initialFormulaComputing=o)}registerFunction(o,r,e){var a;let n=this._injector.get(t.IRegisterFunctionService);n||(this._injector.add([t.IRegisterFunctionService,{useClass:t.RegisterFunctionService}]),n=this._injector.get(t.IRegisterFunctionService));const s={name:o,func:r,description:typeof e=="string"?e:(a=e==null?void 0:e.description)!=null?a:"",locales:typeof e=="object"?e.locales:void 0},u=n.registerFunction(s);return this._debouncedFormulaCalculation(),u}registerAsyncFunction(o,r,e){var a;let n=this._injector.get(t.IRegisterFunctionService);n||(this._injector.add([t.IRegisterFunctionService,{useClass:t.RegisterFunctionService}]),n=this._injector.get(t.IRegisterFunctionService));const s={name:o,func:r,description:typeof e=="string"?e:(a=e==null?void 0:e.description)!=null?a:"",locales:typeof e=="object"?e.locales:void 0},u=n.registerAsyncFunction(s);return this._debouncedFormulaCalculation(),u}}c.FFormula.extend(d)});