Registers a synchronous JavaScript function that formulas in store can
call, then recalculates every formula. Registering a name again replaces the
function. The function receives each argument as a scalar, or as row arrays
for a block of more than one cell, and returns a number, text, boolean, or
null for an empty result. A thrown error or any other result shows
#VALUE!. The function must not read calculated cells or change the store:
calls that need the engine throw a blocked error. Snapshots keep only
formula text, so register the function after loading.
interface StoreinterfaceStoreinterfaceStoreColumnar workbook storage, query, transaction, and subscription contract.API reference →function registerFunction(store: Store, metadata: FormulaFunctionMetadata, implementation: FormulaFunction): voidfunctionregisterFunction(store:Store,metadata:FormulaFunctionMetadata,implementation:FormulaFunction,):voidfunctionregisterFunction(store:Store,metadata:FormulaFunctionMetadata,implementation:FormulaFunction,):voidRegisters a synchronous JavaScript function that formulas in store can call, then recalculates every formula. Registering a name again replaces the function. The function receives each argument as a scalar, or as row arrays for a block of more than one cell, and returns a number, text, boolean, or null for an empty result. A thrown error or any other result shows #VALUE!. The function must not read calculated cells or change the store: calls that need the engine throw a blocked error. Snapshots keep only formula text, so register the function after loading.@throws {SheetwriteError} invalid-function when the store is not a SheetwriteStore, when the name is a built-in function, a cell reference, or not a function name, or when the metadata is malformed; blocked when a host function calls it; optional-backend-unavailable on the default engine, because only the full engine (@sheetwrite/formulas) has host functions.Exampleimporttype { Store } from"@sheetwrite/core";import { registerFunction } from"@sheetwrite/core/functions";functionaddTaxRate(store:Store) {registerFunction(store,{name: "TAXRATE",description: "Sales tax rate of a region.",arguments: [{ name: "region", types: ["text"] }],returnKind: "number",},(region) => (region ==="EU"?0.2:0.07),);}See also/docs/features/formulas/custom-functions/API reference →function addTaxRate(store: Store): voidfunctionaddTaxRate(store:Store):voidfunctionaddTaxRate(store:Store,):voidAPI reference →store: Storelet store:Storelet store:StoreAPI reference →FormulaFunctionMetadata.name: stringinterfaceFormulaFunctionMetadata {name:string;}interfaceFormulaFunctionMetadata {name:string;}User-facing caption.API reference →FormulaFunctionMetadata.description: stringinterfaceFormulaFunctionMetadata {description:string;}interfaceFormulaFunctionMetadata {description:string;}API reference →FormulaFunctionMetadata.arguments: readonly FormulaArgumentMetadata[]interfaceFormulaFunctionMetadata {arguments:readonlyFormulaArgumentMetadata[];}interfaceFormulaFunctionMetadata {arguments:readonlyFormulaArgumentMetadata[];}FormulaArgumentMetadata.name: stringinterfaceFormulaArgumentMetadata {name:string;}interfaceFormulaArgumentMetadata {name:string;}User-facing caption.API reference →FormulaArgumentMetadata.types: readonly string[]interfaceFormulaArgumentMetadata {types:readonlystring[];}interfaceFormulaArgumentMetadata {types:readonlystring[];}API reference →FormulaFunctionMetadata.returnKind: stringinterfaceFormulaFunctionMetadata {returnKind:string;}interfaceFormulaFunctionMetadata {returnKind:string;}API reference →region: FormulaArgumentlet region:FormulaArgumentlet region:FormulaArgumentAPI reference →interface Store {
getWorkbook(): Workbook;
getCell(addr: CellAddress): ResolvedCell;
getFormula(addr: CellAddress): string | null;
getSpillAnchor(addr: CellAddress): CellAddress | null;
getRefTarget(addr: CellAddress): CellAddress | null;
recalculateVolatile(now?: Date): void;
getVisibleWindow(
sheet: SheetId,
rows: { start: number; end: number },
cols: readonly number[],
): VisibleWindowView;
getDataWindow?(
sheet: SheetId,
rows: { start: number; end: number },
// … 27 more lines — see the API reference
}interfaceStore {getWorkbook():Workbook;getCell(addr:CellAddress):ResolvedCell;getFormula(addr:CellAddress):string|null;getSpillAnchor(addr:CellAddress):CellAddress|null;getRefTarget(addr:CellAddress):CellAddress|null;recalculateVolatile(now?:Date):void;getVisibleWindow(sheet:SheetId,rows: { start:number; end:number },cols:readonlynumber[],):VisibleWindowView;getDataWindow?(sheet:SheetId,rows: { start:number; end:number },// … 27 more lines — see the API reference}interfaceStore {getWorkbook():Workbook;getCell(addr:CellAddress,):ResolvedCell;getFormula(addr:CellAddress,):string|null;getSpillAnchor(addr:CellAddress,):CellAddress|null;getRefTarget(addr:CellAddress,):CellAddress|null;recalculateVolatile(now?:Date,):void;getVisibleWindow(sheet:SheetId,// … 60 more lines — see the API reference}Columnar workbook storage, query, transaction, and subscription contract.API reference →interface FormulaFunctionMetadata {
readonly name: string;
readonly description: string;
readonly arguments: readonly FormulaArgumentMetadata[];
readonly returnKind: string;
readonly examples?: readonly string[];
readonly volatile?: boolean;
}interfaceFormulaFunctionMetadata {readonlyname:string;readonlydescription:string;readonlyarguments:readonlyFormulaArgumentMetadata[];readonlyreturnKind:string;readonlyexamples?:readonlystring[];readonlyvolatile?:boolean;}interfaceFormulaFunctionMetadata {readonlyname:string;readonlydescription:string;readonlyarguments:readonlyFormulaArgumentMetadata[];readonlyreturnKind:string;readonlyexamples?:readonlystring[];readonlyvolatile?:boolean;}One metadata format for built-in and host functions.API reference →type FormulaFunction = (
...arguments_: readonly FormulaArgument[]
) => FormulaScalar;typeFormulaFunction= (...arguments_:readonlyFormulaArgument[]) =>FormulaScalar;typeFormulaFunction= (...arguments_:readonlyFormulaArgument[]) =>FormulaScalar;A synchronous host function. Promises and other non-scalar results become #VALUE!.API reference →