@360works/fmpromise/dist/index.d.ts

A modern JS toolkit for FileMaker Web Viewers, including a dev server and type generation.

import { DataAPICreateRequest, DataAPICreateResponse, DataAPIDeleteRequest, DataAPIDeleteResponse, DataAPIMetaDataRequest, DataAPIMetaDataResponse, DataAPIReadRequest, DataAPIReadResponse, DataAPIRecordArray, DataAPIRequest, DataAPIResponse, DataAPIUpdateRequest, DataAPIUpdateResponse } from './types';
export type { DataAPICreateRequest, DataAPICreateResponse, DataAPIDeleteRequest, DataAPIDeleteResponse, DataAPIMetaDataRequest, DataAPIMetaDataResponse, DataAPIReadRequest, DataAPIReadResponse, DataAPIUpdateRequest, DataAPIUpdateResponse, DataAPIRecord, DataAPIRecordArray, DataAPIRequest, DataAPIResponse } from './types';
export type FMPromiseScriptRunningOption = 0 | 1 | 2 | 3 | 4 | 5;
/** Options for the `performScript` call, mirroring FileMaker's `Perform Script with Option`. */
export interface PerformScriptOptions {
    /** If true, the promise will always resolve with a string, bypassing automatic JSON parsing. */
    alwaysReturnString?: boolean;
    /** Specifies how to handle a currently running FileMaker script. 0: Continue (default); 1: Halt; 2: Exit; 3: Resume; 4: Pause; 5: Interrupt. */
    runningScript?: FMPromiseScriptRunningOption;
    /** If performScript will cause the WebViewer to go away, pass `true` here to avoid errors about "Unable to locate web viewer named…" */
    ignoreResult?: boolean;
}
export declare class FMPromiseService {
    /** The name of the web viewer object in FileMaker. */
    get webViewerName(): string;
    /**
     * Performs a FileMaker script and returns a Promise.
     * @template T The expected type of the script result.
     * @param {string} scriptName - The name of the FileMaker script to perform.
     * @param {any} [scriptParameter=null] - The parameter to pass to the script. Non-string values will be JSON stringified.
     * @param {PerformScriptOptions} [options={}] - Options for the script call.
     * @returns {Promise<T>} A promise that resolves with the script result, or rejects with an FMPromiseError.
     */
    performScript<T = any>(scriptName: string, scriptParameter?: any, options?: PerformScriptOptions): Promise<T>;
    /**
     * Evaluates an expression in FileMaker, optionally within the context of `Let` variables.
     * @template T The expected type of the evaluated result.
     * @param {string} expression - The calculation expression to evaluate.
     * @param {Object<string, any>} [letVars={}] - Key-value pairs for a `Let()` function.
     * @param {PerformScriptOptions} [options={}] - Options for the script call.
     * @returns {Promise<T>} A promise that resolves with the evaluated result.
     */
    evaluate<T = any>(expression: string, letVars?: Record<string, any>, options?: PerformScriptOptions): Promise<T>;
    /**
     * Creates a new record in a FileMaker layout.
     * @param params The complete request object, including `action: 'create'`.
     * @returns A promise that resolves with the new record's recordId and modId.
     */
    dataCreate(params: DataAPICreateRequest): Promise<DataAPICreateResponse>;
    /**
     * Finds records in a FileMaker layout.
     * @template T The expected type shape of the records' fieldData.
     * @param params The complete request object, including `action: 'read'`.
     * @returns A promise that resolves with the find response, including a `.toRecords()` helper.
     */
    dataRead<T = Record<string, any>>(params: DataAPIReadRequest): Promise<DataAPIReadResponse<T>>;
    /**
     * Updates an existing record in a FileMaker layout.
     * @param params The complete request object, including `action: 'update'`.
     * @returns A promise that resolves with the record's new modId.
     */
    dataUpdate(params: DataAPIUpdateRequest): Promise<DataAPIUpdateResponse>;
    /**
     * Deletes a record from a FileMaker layout.
     * @param params The complete request object, including `action: 'delete'`.
     * @returns A promise that resolves with an empty response object upon success.
     */
    dataDelete(params: DataAPIDeleteRequest): Promise<DataAPIDeleteResponse>;
    /**
     * Retrieves metadata about layouts or tables.
     * @param params The complete request object, including `action: 'metaData'`.
     * @returns A promise that resolves with the requested metadata.
     */
    dataMeta(params: DataAPIMetaDataRequest): Promise<DataAPIMetaDataResponse>;
    /**
     * The original, overloaded method for executing any FileMaker Data API command.
     *
     * **Note:** For a superior developer experience with better autocompletion and type-checking in modern IDEs,
     * it is **highly recommended** to use the more specific methods instead:
     * - `fmPromise.dataRead()`
     * - `fmPromise.dataCreate()`
     * - `fmPromise.dataUpdate()`
     * - `fmPromise.dataDelete()`
     * - `fmPromise.dataMeta()`
     *
     * This method is preserved for backwards compatibility and for advanced cases where the
     * `action` property is determined dynamically at runtime.
     *
     * @template T The expected type shape of the records' `fieldData` when performing a 'read' action.
     * @param {DataAPIRequest} params The complete Data API request object. The `action` property within this object determines which Data API type is returned.
     * @returns {Promise<DataAPIResponse<T>>} A promise that resolves with a response object specific to the request's `action`.
     * @throws {FMPromiseError} If the Data API returns an error message.
     * @see {@link dataRead}
     * @see {@link dataCreate}
     * @see {@link dataUpdate}
     * @see {@link dataDelete}
     * @see {@link dataMeta}
     */ executeFileMakerDataAPI<T = Record<string, any>>(params: DataAPIRequest): Promise<DataAPIResponse<T>>;
    /**
     * A convenience method which calls `fmPromise.dataRead({ action: 'read', ... })` and the `.toRecords()` method on the response.
     */
    executeFileMakerDataAPIRecords<T>(params: DataAPIReadRequest): Promise<DataAPIRecordArray<T>>;
    /**
     * Executes a SQL query using FileMaker's `ExecuteSQL` function.
     * Can be called as a standard function or as a tagged template literal.
     * @param {TemplateStringsArray | string} sqlOrStrings - The SQL query string or template literal strings.
     * @param {...any} bindings - Values to bind to the `?` placeholders.
     * @returns {Promise<string[][]>} A promise resolving to an array of rows, where each row is an array of strings.
     */
    executeSql(sqlOrStrings: TemplateStringsArray | string, ...bindings: any[]): Promise<string[][]>;
    /**
     * Calls a FileMaker script to perform an "Insert from URL" script step.
     * @param {string} url - The URL to fetch/post to.
     * @param {string} [curlOptions=''] - cURL options for the request.
     * @returns {Promise<string>} The response body.
     */
    insertFromUrl(url: string, curlOptions?: string): Promise<string>;
    /**
     * Calls a FileMaker script to set a field's value by its fully qualified name.
     * @param {string} fmFieldNameToSet - The name of the field (e.g., "MyTable::MyField").
     * @param {any} value - The value to set.
     * @returns {Promise<any>}
     */
    setFieldByName(fmFieldNameToSet: string, value: any): Promise<any>;
    /**
     * Shows a custom dialog in FileMaker.
     * @param {string} title - The dialog title.
     * @param {string} body - The dialog message.
     * @param {string} [btn1='OK'] - The label for the first button (default).
     * @param {string} [btn2=''] - The label for the second button (optional).
     * @param {string} [btn3=''] - The label for the third button (optional).
     * @returns {Promise<number>} A promise resolving to the 1-based index of the button clicked.
     */
    showCustomDialog(title: string, body: string, btn1?: string, btn2?: string, btn3?: string): Promise<number>;
    /** @internal */
    private _resolve;
    /** @internal */
    private _reject;
}
declare global {
    interface Window {
        fmPromise: typeof FMPromiseService;
        fmPromise_Resolve: (promiseId: number, result: any) => void;
        fmPromise_Reject: (promiseId: number, errorString: string) => void;
        FMPROMISE_WEB_VIEWER_NAME?: string;
        FMPROMISE_CONFIG?: any;
    }
}
declare const fmPromise: FMPromiseService;
export default fmPromise;