@vertigis/arcgis-extensions 54.14.6 → 54.15.0

package/utilities/arcade.d.ts

@@ -1,11 +1,25 @@
 import type EsriMap from "@arcgis/core/Map";
+import * as Arcade from "@arcgis/core/arcade.js";
 import type SpatialReference from "@arcgis/core/geometry/SpatialReference";
 import type Layer from "@arcgis/core/layers/Layer";
 import type Sublayer from "@arcgis/core/layers/support/Sublayer";
 import type { Feature } from "../data/Feature.js";
 /**
- * Parameters for the {@link runArcadeExpression} and
- * {@link runAsyncArcadeExpression} functions.
+ * A custom Arcade variable value tagged with an explicit Arcade Variable type
+ * definition (excluding its `name`, which is inferred from its key in the
+ * `vars` object). Use this to attach values to the `vars` parameter of
+ * {@link runAsyncExpression} and {@link runSyncExpression} that are not plain
+ * JSON-compatible values (e.g. a FeatureSet, a Dictionary, or an Array of
+ * Features). Values in `vars` that are not created with this function are
+ * assumed to be plain JSON-compatible values and are declared using the "json"
+ * Arcade variable type.
+ */
+export type ArcadeVariable = {
+    value: unknown;
+} & (Omit<Arcade.SimpleVariable, "name"> | Omit<Arcade.DictionaryVariable, "name"> | Omit<Arcade.ArrayVariable, "name">);
+/**
+ * Parameters for the {@link runArcadeExpression}, {@link runSyncExpression},
+ * {@link runAsyncExpression}, and {@link runAsyncArcadeExpression} functions.
  */
 export interface RunArcadeExpressionParams {
     /**
@@ -28,27 +42,59 @@ export interface RunArcadeExpressionParams {
      */
     layer?: Layer | Sublayer;
     /**
-     * Additional Arcade arguments to attach to the script when run.
+     * Additional Arcade arguments to attach to the script when run. Values are
+     * assumed to be plain JSON-compatible values (declared using the "json"
+     * Arcade variable type) unless created with {@link toArcadeVariable} to
+     * specify an explicit Arcade variable type.
      */
     vars?: Record<string, unknown>;
     /**
      * Emit an error when the script is missing referenced variables. Defaults
      * to 'true'.
+     *
+     * @deprecated When using the {@link runAsyncExpression} or
+     *   {@link runSyncExpression} function, this parameter is no longer used and
+     *   the function will throw if any required parameters are missing.
      */
     emitErrorOnMissingVariables?: boolean;
 }
+/**
+ * Creates and returns an ArcadeExecutor object for the given expression. This
+ * should primarily be used for executing Arcade expressions in a sync context
+ * with {@link runSyncExpression}. If you are executing an expression in an async
+ * context, you should use the {@link runAsyncExpression} function instead. Sync
+ * Arcade expressions cannot be run without first creating an executor
+ * asynchronously.
+ *
+ * @param expression The Arcade expression string.
+ * @param profile The profile definition used to execute the given expression.
+ *   If not provided, a generic profile with all primary variable types will be
+ *   used.
+ */
+export declare function createExecutorForExpression(expression: string, profile?: Arcade.Profile): Promise<Arcade.ArcadeExecutor>;
+/**
+ * Detect if the arcade expression requires an async evaluation.
+ *
+ * @param expression The Arcade expression string.
+ */
+export declare function isExpressionAsyncOnly(expression: string): Promise<boolean>;
 /**
  * Detect if the arcade expression requires an async evaluation.
  *
+ * @deprecated Use {@link isExpressionAsyncOnly} instead. This function will be
+ *   removed in a future release.
  * @param expression The Arcade expression string.
  * @param spatialReference Optionally the spatial reference for the expressions.
  */
 export declare function isArcadeScriptAsync(expression: string, spatialReference?: SpatialReference): boolean;
 /**
- * Execute an synchronous arcade expression string, and return the unformatted
+ * Execute a synchronous arcade expression string, and return the unformatted
  * result. You must call 'enableGeometrySupport' prior to evaluating any
  * expressions that might require the geometry engine.
  *
+ * @deprecated Create an executor using {@link createExecutorForExpression} and
+ *   then call {@link runSyncExpression} instead. This function will be removed
+ *   in a future release.
  * @param expression The arcade expression string.
  * @param params The parameters.
  */
@@ -57,7 +103,55 @@ export declare function runArcadeExpression(expression: string, params: RunArcad
  * Execute an asynchronous arcade expression string, and return the unformatted
  * result.
  *
+ * @deprecated Use runAsyncExpression instead. This function will be removed in
+ *   a future release.
  * @param expression The arcade expression string.
  * @param params The parameters.
  */
 export declare function runAsyncArcadeExpression(expression: string, params: RunArcadeExpressionParams): Promise<unknown>;
+/**
+ * Execute a synchronous arcade expression string, and return the unformatted
+ * result.
+ *
+ * @param expression The arcade expression string.
+ * @param params The parameters.
+ * @param executor The ArcadeExecutor to use for executing the expression. The
+ *   executor should be created using the {@link createExecutorForExpression}
+ *   function.
+ */
+export declare function runSyncExpression(expression: string, params: RunArcadeExpressionParams, executor: Arcade.ArcadeExecutor): unknown;
+/**
+ * Execute an asynchronous arcade expression string, and return the unformatted
+ * result.
+ *
+ * @param expression The arcade expression string.
+ * @param params The parameters.
+ */
+export declare function runAsyncExpression(expression: string, params: RunArcadeExpressionParams): Promise<unknown>;
+/**
+ * Constructs an Arcade profile based on the provided parameters.
+ *
+ * @param params The parameters.
+ */
+export declare function constructProfile(params: RunArcadeExpressionParams): Arcade.Profile;
+/**
+ * Tags a value with an explicit Arcade Variable type definition so it can be
+ * passed through the `vars` parameter of {@link runAsyncExpression} and
+ * {@link runSyncExpression} without being assumed to be a plain JSON-compatible
+ * value.
+ *
+ * @example
+ *     ```
+ *     await runAsyncExpression("Count($features)", {
+ *         vars: {
+ *             $features: toArcadeVariable(featureSet, { type: "featureSet" }),
+ *         },
+ *     });
+ *     ```;
+ *
+ * @param value The value of the variable.
+ * @param definition The Arcade variable type definition (excluding `name`) to
+ *   declare the value as (e.g. `{ type: "featureSet" }` for a FeatureSet
+ *   object).
+ */
+export declare function toArcadeVariable(value: unknown, definition: Omit<Arcade.SimpleVariable, "name"> | Omit<Arcade.DictionaryVariable, "name"> | Omit<Arcade.ArrayVariable, "name">): ArcadeVariable;

package/utilities/arcade.js

@@ -1 +1 @@
-import*as e from"@arcgis/core/arcade/arcade.js";import*as r from"@arcgis/core/support/arcadeUtils.js";import{checkArg as a}from"./checkArg.js";const t=new Map;export function isArcadeScriptAsync(a,t){const s=i(a,t);return["$datastore","$map","$layer"].some(e=>r.hasVariable(s,e))||e.scriptIsAsync({...s,isAsync:void 0,usesFeatureSet:void 0,usesGeometry:void 0},void 0)}export function arcadeScriptUsesGeometry(e,r){return!!i(e,r).usesGeometry}export async function enableGeometrySupportIfNeeded(r){const{spatialReference:a}=r.geometry??{},t=r.source?.layer?.elevationInfo?.featureExpressionInfo?.expression;t&&arcadeScriptUsesGeometry(t,a)&&await e.enableGeometrySupport()}export function runArcadeExpression(t,s){const{map:o,layer:n,vars:c,feature:p,spatialReference:u,emitErrorOnMissingVariables:f=!0}=s;a("$map and $layer parameters are not supported in synchronous arcade",s).satisfies(()=>!o&&!n);const l=r.getViewInfo({spatialReference:u}),m=r.createExecContext(p?.toGraphic(),l);if(c)for(const e of Object.keys(c))m.vars[e]=c[e];const y=i(t,u);if(r.hasVariable(y,"$feature"))if(f)a("params.feature",p).isNotMissing();else if(!p)return;return e.executeScript(y,m)}export async function runAsyncArcadeExpression(t,s){const{map:o,layer:n,vars:c,feature:p,spatialReference:u,emitErrorOnMissingVariables:f=!0}=s,l={...i(t,u)},m=["$datastore","$map","$layer"].filter(e=>r.hasVariable(l,e));await r.loadScriptDependencies(l,!0,m);const y=r.getViewInfo({spatialReference:u}),d=r.createExecContext(p?.toGraphic(),y);if(l.isAsync=!0,l.usesFeatureSet=!0,await Promise.all([e.enableAsyncSupport(),(async()=>{await import("@arcgis/core/arcade/functions/featuresetbase.js"),await e.enableFeatureSetSupport()})(),l.usesGeometry&&e.enableGeometrySupport()]),!r.hasVariable(l,"$feature")||(f&&a("params.feature",p).isNotMissing(),p)){if(m.includes("$map")){if(f&&a("params.map",o).isNotMissing(),!o)return;d.vars.$map=r.convertMapToFeatureSetCollection({map:o,spatialReference:u})}if(m.includes("$layer")){if(f&&a("params.layer",n).isNotMissing(),!n)return;d.vars.$layer=r.convertFeatureLayerToFeatureSet({layer:n,spatialReference:u})}if(m.includes("$datastore")){f&&a("params.layer",n).isNotMissing();const e=n?.url;if(!e)return;d.vars.$datastore=r.convertServiceUrlToWorkspace({url:e,spatialReference:u})}if(c)for(const e of Object.keys(c))d.vars[e]=c[e];return r.createFunction(l,d)(d)}}const s=["__proto__"];function i(r,a){const i=`${r}-${a?.wkid}`;if(t.has(i))return t.get(i);const o=s.filter(e=>r.includes(e));if(0!==o.length)throw new Error(`Invalid Arcade expression tokens: ${o.join()}`);const n=e.parseScript(r,a);return t.set(i,n),n}
+import*as e from"@arcgis/core/arcade/arcade.js";import*as r from"@arcgis/core/arcade.js";import*as t from"@arcgis/core/support/arcadeUtils.js";import{checkArg as a}from"./checkArg.js";const n=new Map,s=r.createArcadeCache(),o=["__proto__"],i={variables:[{name:"$feature",type:"feature"},{name:"$map",type:"featureSetCollection"},{name:"$layer",type:"featureSet"},{name:"$datastore",type:"featureSetCollection"},{name:"$view",type:"featureSetCollection"}]};export async function createExecutorForExpression(e,t){return await r.createArcadeExecutor(e,t??i)}export async function isExpressionAsyncOnly(e){return(await createExecutorForExpression(e)).isAsync}export function isArcadeScriptAsync(r,a){const n=c(r,a);return["$datastore","$map","$layer"].some(e=>t.hasVariable(n,e))||e.scriptIsAsync({...n,isAsync:void 0,usesFeatureSet:void 0,usesGeometry:void 0},void 0)}export function runArcadeExpression(r,n){const{map:s,layer:o,vars:i,feature:p,spatialReference:u,emitErrorOnMissingVariables:f=!0}=n;a("$map and $layer parameters are not supported in synchronous arcade",n).satisfies(()=>!s&&!o);const l=t.getViewInfo({spatialReference:u}),y=t.createExecContext(p?.toGraphic(),l);if(i)for(const e of Object.keys(i))y.vars[e]=i[e];const m=c(r,u);if(t.hasVariable(m,"$feature"))if(f)a("params.feature",p).isNotMissing();else if(!p)return;return e.executeScript(m,y)}export async function runAsyncArcadeExpression(r,n){const{map:s,layer:o,vars:i,feature:p,spatialReference:u,emitErrorOnMissingVariables:f=!0}=n,l={...c(r,u)},y=["$datastore","$map","$layer"].filter(e=>t.hasVariable(l,e));await t.loadScriptDependencies(l,!0,y);const m=t.getViewInfo({spatialReference:u}),d=t.createExecContext(p?.toGraphic(),m);if(l.isAsync=!0,l.usesFeatureSet=!0,await Promise.all([e.enableAsyncSupport(),(async()=>{await import("@arcgis/core/arcade/functions/featuresetbase.js"),await e.enableFeatureSetSupport()})(),l.usesGeometry&&e.enableGeometrySupport()]),!t.hasVariable(l,"$feature")||(f&&a("params.feature",p).isNotMissing(),p)){if(y.includes("$map")){if(f&&a("params.map",s).isNotMissing(),!s)return;d.vars.$map=t.convertMapToFeatureSetCollection({map:s,spatialReference:u})}if(y.includes("$layer")){if(f&&a("params.layer",o).isNotMissing(),!o)return;d.vars.$layer=t.convertFeatureLayerToFeatureSet({layer:o,spatialReference:u})}if(y.includes("$datastore")){f&&a("params.layer",o).isNotMissing();const e=o?.url;if(!e)return;d.vars.$datastore=t.convertServiceUrlToWorkspace({url:e,spatialReference:u})}if(i)for(const e of Object.keys(i))d.vars[e]=i[e];return t.createFunction(l,d)(d)}}export function runSyncExpression(e,r,t){a("$map and $layer parameters are not supported in synchronous arcade",r).satisfies(()=>!r.map&&!r.layer);const n=p(e);if(n.length)throw new Error(`Invalid Arcade expression tokens: ${n.join()}`);const s=u(r),o=f(r);return t.execute(s,o)}export async function runAsyncExpression(e,r){const t=p(e);if(t.length)throw new Error(`Invalid Arcade expression tokens: ${t.join()}`);const a=constructProfile(r),n=u(r),s=f(r),o=await createExecutorForExpression(e,a);return await o.executeAsync(n,s)}export function constructProfile(e){const{feature:r,map:t,layer:a,vars:n}=e,s=[];if(n)for(const e of Object.keys(n)){const r=n[e];l(r)?s.push(y(e,r)):s.push({name:e,type:"json"})}return r&&s.push({name:"$feature",type:"feature"}),t&&s.push({name:"$map",type:"featureSetCollection"}),a&&(s.push({name:"$layer",type:"featureSet"}),s.push({name:"$datastore",type:"featureSetCollection"})),{variables:s}}export function toArcadeVariable(e,r){return{value:e,...r}}function c(r,t){const a=`${r}-${t?.wkid}`;if(n.has(a))return n.get(a);const s=p(r);if(s.length)throw new Error(`Invalid Arcade expression tokens: ${s.join()}`);const o=e.parseScript(r,t);return n.set(a,o),o}function p(e){return o.filter(r=>e.includes(r))}function u(e){const{feature:r,map:t,layer:a,vars:n}=e,s={};if(n)for(const e of Object.keys(n)){const r=n[e];s[e]=l(r)?r.value:r}return r&&(s.$feature=r.toGraphic()),t&&(s.$map=t),a&&(s.$layer=a,s.$datastore=a?.url),s}function f(e){const{spatialReference:r}=e;return{cache:s,spatialReference:r}}function l(e){return"object"==typeof e&&null!==e&&"value"in e&&"type"in e&&"string"==typeof e.type}function y(e,r){return"dictionary"===r.type?{name:e,type:"dictionary",properties:r.properties}:"array"===r.type?{name:e,type:"array",elementType:r.elementType}:{name:e,type:r.type}}

package/version.d.ts

@@ -1,4 +1,4 @@
 /**
  * The current version of the Geocortex ArcGIS Extensions API.
  */
-export declare const version = "54.14.6";
+export declare const version = "54.15.0";

package/version.js

@@ -1 +1 @@
-export const version="54.14.6";
+export const version="54.15.0";