@vertigis/viewer-spec/messaging/registry/arcade.d.ts

VertiGIS Viewer Specification

import type { Operation } from "../Operation.js";
import { OperationRegistry } from "../OperationRegistry.js";
import type { HasFeatures, HasLayers, HasMaps, ModelRef } from "../common.js";
/**
 * The arguments for the arcade.run operation.
 */
export interface RunArcadeArgs extends HasMaps, HasLayers, HasFeatures {
    /**
     * The stringified Arcade script to run. If this property is included, the
     * operation will return the result of the script.
     */
    executeScript?: string;
    /**
     * The stringified Arcade script used to determine whether or not the
     * executeScript can/should be run. If no executeScript is provided and the
     * canExecuteScript returns a truthy value, the operation will return its
     * input arguments; otherwise, if the canExecuteScript returns a falsy
     * value, it will throw a {@link Cancellation}.
     */
    canExecuteScript?: string;
    /**
     * An arguments object that provides named variables and associated values,
     * which can be referenced from within the executeScript and
     * canExecuteScript. Note that context variables will be passed in if
     * available under the well known arcade variable names: $feature,
     * $features, $map, and $layer and $featuremap a constructed arcade
     * dictionary that exposes a feature mapping dictionary keyed via feature
     * source ID with the following values: id, title and features.
     *
     * NOTE: All variable keys must consist of only lowercase letters;
     * camel-cased context variables will break the script when they are
     * referenced at runtime.
     */
    arguments?: Record<string, unknown | ItemPropertyPath>;
    /**
     * Whether to pass the operation context object into the script. If
     * included, the context object uses the variable name $context.
     */
    includeContext?: boolean;
    /**
     * Whether to pass the current workflow application state into the script.
     * If included, the application state object uses the variable name
     * $workflowdata.
     */
    includeWorkflowApplicationData?: boolean;
    /**
     * Properties used to set a series of watch handles and/or event listeners
     * on an item that will trigger the canExecuteChanged event for the
     * 'arcade.run' operation.
     */
    watchHandles?: WatchEventHandleProperties[];
}
/**
 * An object containing a propertyPath that used to retrieve a property value
 * from the given item.
 */
export interface ItemPropertyPath {
    /**
     * The item from which to access a property value.
     */
    item: ModelRef;
    /**
     * The path to a property on an item.
     */
    propertyPath: string;
}
export declare class ArcadeOperations extends OperationRegistry {
    protected readonly _prefix = "arcade";
    /**
     * Runs a stringified Arcade script.
     *
     * - If only a string is passed in as an argument, it is interpreted as an
     *   executeScript.
     * - If an executeScript is provided, the operation will return its result.
     * - If only a canExecute script is provided and it returns a truthy result,
     *   the operation will return its input arguments.
     * - If a canExecuteScript returns a falsy value, the operation will throw a
     *   `Cancellation`.
     *
     * **Example:** Use an Arcade script to query a portal for a featureset, and
     * return the area in square kilometers of the first feature. The output
     * type of this operation is determined by the Arcade script, see
     * https://developers.arcgis.com/arcade/function-reference/ for more
     * information.
     *
     * ```
     * {
     *     "executeScript": "Area(First(FeatureSetByPortalItem(Portal(\"https://www.arcgis.com\"),\"6200db0b80de4341ae8ee2b62d606e67\",0,[\"*\"],true)),\"square-kilometers\");"
     * }
     * ```
     *
     * @webOnly
     */
    get run(): Operation<RunArcadeArgs | string, unknown>;
}
/**
 * Properties used to set a series of watch handles and/or event listeners on an
 * item.
 */
export interface WatchEventHandleProperties {
    /**
     * The item whose properties will be watched for changes and/or events.
     */
    item: ModelRef;
    /**
     * One or more properties on the item that will be watched for changes
     * and/or events. Any strings will be used as propertyPaths that will be
     * watched for changes; for this to work, the item and all properties
     * referenced within the path (except for the last) must implement
     * {@link Observable}.
     */
    watch: string | WatchEventProperty | (string | WatchEventProperty)[];
}
/**
 * Properties on an item to watch, with an optional event name to listen for.
 */
export interface WatchEventProperty {
    /**
     * The path used to target a property on an item that will be watched for
     * events. The watched property must implement {@link Evented}; this will
     * effectively do `item[propertyPath].on(eventName)`.
     */
    propertyPath?: string;
    /**
     * The name of the event to listen for. If no propertyPath is included, the
     * listener will go directly on the watched item.
     */
    eventName: string;
}