@arcgis/core/smartMapping/statistics/support/ageUtils.d.ts

ArcGIS Maps SDK for JavaScript: A complete 2D and 3D mapping and data visualization API

/**
 * Provides utility functions for generating [Arcade](https://developers.arcgis.com/javascript/latest/arcade/) expressions
 * intended for use in an [age renderer](https://developers.arcgis.com/javascript/latest/references/core/smartMapping/renderers/color/#createAgeRenderer).
 *
 * @since 4.13
 * @see [colorRendererCreator.createAgeRenderer](https://developers.arcgis.com/javascript/latest/references/core/smartMapping/renderers/color/#createAgeRenderer)
 * @see [sizeRendererCreator.createAgeRenderer](https://developers.arcgis.com/javascript/latest/references/core/smartMapping/renderers/size/#createAgeRenderer)
 */
import type { DateProperties } from "../../../intl/date.js";
import type { SmartMappingTimeUnit } from "../../types.js";
import type { FeatureLikeLayerOrAdapter } from "../../support/adapters/types.js";

/**
 * Returns an [Arcade](https://developers.arcgis.com/javascript/latest/arcade/) expression for visualizing the age of a feature based
 * on a given start time and end time.
 *
 * @param params - The function parameters.
 * @returns Returns an instance of [AgeExpressionsResult](https://developers.arcgis.com/javascript/latest/references/core/smartMapping/statistics/support/ageUtils/#AgeExpressionsResult).
 * @example
 * const ageExpressions = ageUtils.getAgeExpressions({
 *   layer: featureLayer,
 *   startTime: "Created_Date",
 *   endTime: Date.now(),
 *   unit: "days"
 * });
 *
 * console.log(`value expression: ${ageExpressions.valueExpression}`);
 */
export function getAgeExpressions(params: AgeExpressionsParameters): AgeExpressionsResult;

export interface AgeExpressionsParameters {
  /** The layer from which to generate age statistics for the given `startTime` and `endTime`. */
  layer: FeatureLikeLayerOrAdapter;
  /**
   * The start time for the age calculation. This can be a field name or a date
   *   value, such as `Date.now()`. If a `Date` is provided, then the `endTime` parameter must be a field name.
   */
  startTime: DateProperties;
  /**
   * The end time for the age calculation. This can be a field name or a date
   *   value, such as `Date.now()`. If a `Date` is provided, then the `startTime` parameter must be a field name.
   */
  endTime: DateProperties;
  /** The desired units of the age result. */
  unit?: SmartMappingTimeUnit | null;
}

/** The result object returned from the [getAgeExpressions()](https://developers.arcgis.com/javascript/latest/references/core/smartMapping/statistics/support/ageUtils/#getAgeExpressions) method. */
export interface AgeExpressionsResult {
  /**
   * An [Arcade](https://developers.arcgis.com/javascript/latest/arcade/) expression following
   * the specification defined by the [Arcade Visualization Profile](https://developers.arcgis.com/javascript/latest/arcade/#visualization).
   * The expression should be used to calculate the age of a feature
   * based on the difference between the end time and the start time. It may reference field values using the `$feature`
   * profile variable and must return a number.
   */
  valueExpression: string;
  /** A SQL expression and where clause that matches the generated `valueExpression` used to query statistics from the layer. */
  statisticsQuery: any;
  /** A SQL expression and where clause that matches the generated `valueExpression` used to query for a histogram from the layer. */
  histogramQuery: any;
}