@sheetxl/scripting/types/index.d.ts

Scripting - Scripting engine for Macros and formulas; includes TypeScript and EsBuild.

import { IFormulaContext } from '@sheetxl/primitives';
import { IFunction } from '@sheetxl/primitives';

/**
 * Represents a compile collections of functions.
 *
 */
export declare interface CompiledModule {
    /**
     * An array of `Declaration` and `Description pairs describing the functions within the script.
     *
     * @remarks
     * This array can be empty. It is possible that a script might contain only comments or other non-executable code.
     */
    functions: [IFunction.DeclarationJSON, IFunction.DescriptorJSON][];
    /**
     * The human-readable source code of the script.
     *
     * @remarks
     * If this property is missing, the script will not be displayed but the 'actions' will still be available if `compiled` is present.
     */
    source?: string;
    /**
     * The compiled or pre-processed version of the script, ready for execution.
     *
     * @remarks
     * If this property is missing, the script will be compiled on demand if possible.
     */
    compiled?: string;
    /**
     * The language the function is written in.
     *
     * @defaultValue typescript
     */
    language?: string;
    /**
     * The name of the module.
     */
    name?: string;
    /**
     * A unique identifier for the function (e.g., a Git commit ID).
     * // https://stackoverflow.com/questions/29106996/what-is-a-git-commit-id
     */
    commitId?: string;
    /**
     * The name of the function to run automatically when the script is loaded.
     */
    autoRun?: string;
    /**
     * ** NOT IMPLEMENTED **
     * Available in functions via the 'this' value.
     * Will auto persist values on save.
     *
     * TODO - this doesn't belong here.
     * Create a new interface for session state.
     * TODO - rename to sessionData
     */
    scope?: any;
}

/**
 * Options for compiling a script module.
 */
export declare interface CompileOptions {
    /**
     * The source code of the script module to compile.
     */
    source: string;
    /**
     * If true, this will not include the bundle in the compiled module.
     *
     * @remarks
     * This is useful for validation
     */
    disableBundle?: boolean;
    /**
     * If true, this will not include the source map in the compiled module.
     */
    disableSourceMap?: boolean;
    /**
     * For validation
     */
    declarationsOnly?: boolean;
    /**
     * The commit ID for the compilation.
     */
    commitId?: string;
}

/**
 * The return type for Compile.
 */
export declare interface CompileResults {
    module: CompiledModule;
    errors: any;
}

/**
 * Converts a typescript string into a `CompiledModule`.
 *
 * @param options Optional compilation options
 */
declare function compileTypescript(options: CompileOptions): Promise<CompiledModule>;

export declare interface DescriptorModule {
    default: MinifiedDescriptors;
}

export declare type DynamicDescriptors = () => Promise<DescriptorModule>;

/**
 * Type for bind signature for typed functions.
 */
export declare interface FunctionBinder {
    (mapBind: Map<string, IFunction>, getContext: () => IFormulaContext, implementations: Implementations, declarations: MinifiedDeclarations, getDynamicDescriptors?: DynamicDescriptors, defaultCategory?: string): void;
}

export declare interface Implementations {
    [functionName: string]: (...args: any) => any;
}

/**
 * The function declaration needed to autoMarshall and execute.
 */
export declare interface MinifiedDeclaration {
    fn?: string;
    c?: boolean;
    p?: MinifiedParameter[];
}

export declare type MinifiedDeclarations = {
    [name: string]: MinifiedDeclaration;
};

/**
 * The descriptor used for a function
 */
export declare interface MinifiedDescriptor {
    s?: string;
    c?: string;
    p?: Record<string, any>;
    h?: string | boolean;
    l?: [url: string, text?: string][];
}

export declare interface MinifiedDescriptors {
    [name: string]: MinifiedDescriptor;
}

/**
 * Minified params.
 */
export declare interface MinifiedParameter {
    n: string;
    s?: string;
    r?: 'r' | 'l' | 'a';
    d?: number;
    m?: '?' | '...';
    e?: string[];
}

export declare const ScriptingUtils: Readonly<{
    compileTypescript: typeof compileTypescript;
}>;

export { }