@arcgis/core 5.0.0-next.122 → 5.0.0-next.124

package/core/sql/types.d.ts

@@ -1,34 +1,100 @@
-/** @since 5.0 */
+/**
+ * A module for importing types used in [sql](https://developers.arcgis.com/javascript/latest/references/core/core/sql/) and [WhereClause](https://developers.arcgis.com/javascript/latest/references/core/core/sql/WhereClause/) modules.
+ *
+ * @since 5.0
+ */
+
+/**
+ * The position in the original SQL expression string for a SQL node in the parse tree returned by
+ * [WhereClause.parseTree](https://developers.arcgis.com/javascript/latest/references/core/core/sql/WhereClause/#parseTree).
+ *
+ * @see [WhereClause.parseTree](https://developers.arcgis.com/javascript/latest/references/core/core/sql/WhereClause/#parseTree)
+ * @since 5.0
+ */
 export interface SourcePosition {
-  /** @since 5.0 */
+  /**
+   * The 0-based character offset in the original SQL string where the node starts.
+   *
+   * Together with `line` and `column`, this allows precise mapping
+   * of the parse tree node back to its position in the source.
+   *
+   * @since 5.0
+   */
   offset: number;
-  /** @since 5.0 */
+  /**
+   * The 1-based line number in the original SQL string at which the node starts.
+   *
+   * @since 5.0
+   */
   line: number;
-  /** @since 5.0 */
+  /**
+   * The 1-based column number in the original SQL string at which the node starts.
+   *
+   * @since 5.0
+   */
   column: number;
 }
 
-/** @since 5.0 */
+/**
+ * A source location range in the original SQL string.
+ *
+ * The location spans from [SQLSourceLocation](https://developers.arcgis.com/javascript/latest/references/core/core/sql/types/#SQLSourceLocation-start) (inclusive) to
+ * [SQLSourceLocation](https://developers.arcgis.com/javascript/latest/references/core/core/sql/types/#SQLSourceLocation-end) (exclusive).
+ *
+ * @since 5.0
+ */
 export interface SQLSourceLocation {
   /** @since 5.0 */
   source?: unknown;
-  /** @since 5.0 */
+  /**
+   * The inclusive start position of the range.
+   *
+   * @since 5.0
+   */
   start: SourcePosition;
-  /** @since 5.0 */
+  /**
+   * The exclusive end position of the range.
+   *
+   * @since 5.0
+   */
   end: SourcePosition;
 }
 
-/** @since 5.0 */
+/**
+ * Error thrown when a SQL expression cannot be [parsed](https://developers.arcgis.com/javascript/latest/references/core/core/sql/WhereClause/#parseTree).
+ *
+ * @since 5.0
+ */
 export interface SQLSyntaxError extends Error {
-  /** @since 5.0 */
+  /**
+   * The syntax error name. It is always `"SyntaxError"`.
+   *
+   * @since 5.0
+   */
   name: "SyntaxError";
-  /** @since 5.0 */
+  /**
+   * A description of the parse error.
+   *
+   * @since 5.0
+   */
   message: string;
-  /** @since 5.0 */
+  /**
+   * The location in the original SQL string associated with the parse error.
+   *
+   * @since 5.0
+   */
   location: SQLSourceLocation;
 }
 
-/** @since 5.0 */
+/**
+ * A minimal feature/attributes object used by [WhereClause.calculateValue()](https://developers.arcgis.com/javascript/latest/references/core/core/sql/WhereClause/#calculateValue) or [WhereClause.testFeature()](https://developers.arcgis.com/javascript/latest/references/core/core/sql/WhereClause/#testFeature).
+ * The where clause evaluator can read attribute values from either:
+ * - A plain object (for example, `{ POPULATION: 300000 }`), or
+ * - An object containing an `attributes` property (for example,
+ *   `{ attributes: { POPULATION: 300000 } }`, such as a [Graphic](https://developers.arcgis.com/javascript/latest/references/core/Graphic/)).
+ *
+ * @since 5.0
+ */
 export type SimpleAttributes = { attributes: Record<string, unknown>; } | Record<string, any>;
 
 /**
@@ -39,39 +105,59 @@ export type SimpleAttributes = { attributes: Record<string, unknown>; } | Record
 export type SQLNode = BinaryNode | BoolNode | ColumnNode | CurrentTimeNode | CurrentUserNode | DataTypeNode | DateNode | FunctionNode | IntervalNode | IntervalPeriodNode | IntervalQualifierNode | ListNode | NullNode | NumberNode | ParamNode | SearchedCaseNode | SimpleCaseNode | StringNode | TimeNode | TimeStampNode | UnaryNode | WhenNode;
 
 /**
- * Simple case expression node.
- * Case expressions provide a decoding capability that allows one expression to be transformed into another.
- * Case expressions can appear anywhere that other forms of expressions can be used.
+ * A simple case expression node. This represents expressions of the form:
+ *
+ * `CASE <operand> WHEN <whenOperand> THEN <result> ... [ELSE <elseResult>] END`
+ *
+ * During evaluation, the `operand` value is compared to each
+ * `WHEN` operand using equality. The first matching clause determines the result. If no clause matches,
+ * the `ELSE` expression is used when present, otherwise the result is `null`.
  *
  * @since 4.24
  */
 export interface SimpleCaseNode {
-  /** @since 5.0 */
+  /**
+   * SQL node type.
+   *
+   * @since 5.0
+   */
   type: "case-expression";
-  /** @since 5.0 */
+  /**
+   * Location of the full `CASE ... END` expression.
+   *
+   * @since 5.0
+   */
   location: SQLSourceLocation;
-  /** @since 5.0 */
+  /**
+   * The case expression format. Value for this property is always `"simple"`.
+   *
+   * @since 5.0
+   */
   format: "simple";
   /**
-   * When nodes.
+   * Ordered `WHEN ... THEN ...` clauses.
+   * Each clause's [WhenNode.operand](https://developers.arcgis.com/javascript/latest/references/core/core/sql/types/#WhenNode) is compared against the
+   * SimpleCaseNode's `operand`, and the matching clause's
+   * [WhenNode.value](https://developers.arcgis.com/javascript/latest/references/core/core/sql/types/#WhenNode) determines the result.
    *
    * @since 5.0
    */
   clauses: WhenNode[];
   /**
-   * SQL node.
+   * The expression following the `CASE` keyword.
+   * This value is compared to each clause operand.
    *
    * @since 5.0
    */
   operand: SQLNode;
   /**
-   * else sql node.
+   * The `ELSE` result expression, or `null` if the `ELSE` clause is not present.
    *
    * @since 5.0
    */
   else: SQLNode | null;
   /**
-   * Present if `else` is non-null and includes the location of the `ELSE` keyword and result expression.
+   * Location of the `ELSE` keyword and result expression, or `null` if the `ELSE` clause is not present.
    *
    * @since 5.0
    */
@@ -79,35 +165,53 @@ export interface SimpleCaseNode {
 }
 
 /**
- * Node that contains case expression.
+ * A searched `CASE` expression node.
+ * Represents expressions of the form:
+ *
+ * `CASE WHEN <condition> THEN <result> ... [ELSE <elseResult>] END`
+ *
+ * During evaluation, each `WHEN` condition is evaluated in order.
+ * The result of the first condition that evaluates to `true` is returned.
+ * If no condition matches, the `ELSE` expression is evaluated if present; otherwise, the result is `null`.
  *
  * @since 4.24
  */
 export interface SearchedCaseNode {
-  /** @since 5.0 */
+  /**
+   * SQL node type.
+   *
+   * @since 5.0
+   */
   type: "case-expression";
-  /** @since 5.0 */
+  /**
+   * Location of the full `CASE ... END` expression.
+   *
+   * @since 5.0
+   */
   location: SQLSourceLocation;
   /**
-   * Case expression format. Value for this property is always `searched`.
+   * The case expression format. Value for this property is always `"searched"`.
    *
    * @since 5.0
    */
   format: "searched";
   /**
-   * When clauses.
+   * Ordered `WHEN ... THEN ...` clauses.
+   *
+   * Each clause's [WhenNode.operand](https://developers.arcgis.com/javascript/latest/references/core/core/sql/types/#WhenNode) is evaluated as a condition, and the
+   * first clause whose condition evaluates to `true` determines the result.
    *
    * @since 5.0
    */
   clauses: WhenNode[];
   /**
-   * Else SQL node.
+   * The `ELSE` result expression, or `null` if the `ELSE` clause is not present.
    *
    * @since 5.0
    */
   else: SQLNode | null;
   /**
-   * Present if `else` is non-null and includes the location of the `ELSE` keyword and result expression.
+   * Location of the `ELSE` keyword and result expression, or `null` if the `ELSE` clause is not present.
    *
    * @since 5.0
    */
@@ -115,23 +219,40 @@ export interface SearchedCaseNode {
 }
 
 /**
- * Node that contains when clause.
+ * A `WHEN ... THEN ...` clause in a `CASE` expression.
+ * This node is used by both [SimpleCaseNode](https://developers.arcgis.com/javascript/latest/references/core/core/sql/types/#SimpleCaseNode) and
+ * [SearchedCaseNode](https://developers.arcgis.com/javascript/latest/references/core/core/sql/types/#SearchedCaseNode):
+ * - In a simple case expression, WhenNode's `operand` is compared against the simple case operand.
+ * - In a searched case expression, WhenNode's `operand` is evaluated as a condition.
+ *
+ * When the clause matches, WhenNode's `value` determines the result.
  *
  * @since 4.24
  */
 export interface WhenNode {
-  /** @since 5.0 */
+  /**
+   * SQL node type.
+   *
+   * @since 5.0
+   */
   type: "when-clause";
-  /** @since 5.0 */
+  /**
+   * Location of the full `WHEN ... THEN ...` clause.
+   *
+   * @since 5.0
+   */
   location: SQLSourceLocation;
   /**
-   * operand.
+   * The expression following the `WHEN` keyword.
+   * In simple case expressions, this expression is compared against the case operand.
+   * In searched case expressions, this expression is evaluated as a condition.
    *
    * @since 5.0
    */
   operand: SQLNode;
   /**
-   * value.
+   * The expression following the `THEN` keyword.
+   * This expression determines the result when the clause matches.
    *
    * @since 5.0
    */
@@ -139,31 +260,55 @@ export interface WhenNode {
 }
 
 /**
- * ParamNode.
+ * A parameter reference node. Parameter references use the `@name` syntax in SQL expressions.
  *
  * @since 4.24
  */
 export interface ParamNode {
-  /** @since 5.0 */
+  /**
+   * SQL node type.
+   *
+   * @since 5.0
+   */
   type: "parameter";
-  /** @since 5.0 */
+  /**
+   * Location of the full `@name` parameter reference.
+   *
+   * @since 5.0
+   */
   location: SQLSourceLocation;
-  /** @since 5.0 */
+  /**
+   * The parameter name without the leading `@`.
+   * The name is matched against parameters using a case-insensitive lookup.
+   *
+   * @since 5.0
+   */
   value: string;
 }
 
 /**
- * A node that contains a list.
+ * An ordered list of SQL expressions.
+ * This node is commonly produced for parenthesized expression lists (for example, function call
+ * arguments or `IN (<expr>, <expr>, ...)` lists). It is also used for other constructs that naturally
+ * form an ordered set of expressions (for example, `BETWEEN <begin> AND <end>`).
  *
  * @since 4.24
  */
 export interface ListNode {
-  /** @since 5.0 */
+  /**
+   * SQL node type.
+   *
+   * @since 5.0
+   */
   type: "expression-list";
-  /** @since 5.0 */
+  /**
+   * Location of the full list expression.
+   *
+   * @since 5.0
+   */
   location: SQLSourceLocation;
   /**
-   * SQL expressions for the list.
+   * The expressions in the list, in source order.
    *
    * @since 5.0
    */
@@ -177,11 +322,23 @@ export interface ListNode {
  * @since 4.24
  */
 export interface UnaryNode {
-  /** @since 5.0 */
+  /**
+   * SQL node type.
+   *
+   * @since 5.0
+   */
   type: "unary-expression";
-  /** @since 5.0 */
+  /**
+   * Location of the full unary node.
+   *
+   * @since 5.0
+   */
   location: SQLSourceLocation;
-  /** @since 5.0 */
+  /**
+   * The unary operator. Value for this property is always `"NOT"` since it is the only unary operator supported in SQL expressions.
+   *
+   * @since 5.0
+   */
   operator: "NOT";
   /**
    * The sql node.
@@ -199,13 +356,20 @@ export interface UnaryNode {
  * @since 4.24
  */
 export interface BinaryNode {
-  /** @since 5.0 */
+  /**
+   * SQL node type.
+   *
+   * @since 5.0
+   */
   type: "binary-expression";
-  /** @since 5.0 */
+  /**
+   * Location of the full binary node.
+   *
+   * @since 5.0
+   */
   location: SQLSourceLocation;
   /**
-   * Defines the way two expressions are combined
-   * to yield a single result.
+   * Defines the way two expressions are combined to yield a single result.
    *
    * @since 5.0
    */
@@ -236,9 +400,17 @@ export interface BinaryNode {
  * @since 4.24
  */
 export interface NullNode {
-  /** @since 5.0 */
+  /**
+   * SQL node type.
+   *
+   * @since 5.0
+   */
   type: "null";
-  /** @since 5.0 */
+  /**
+   * Location of the `NULL` literal in the original SQL string.
+   *
+   * @since 5.0
+   */
   location: SQLSourceLocation;
   /**
    * Null value.
@@ -254,9 +426,17 @@ export interface NullNode {
  * @since 4.24
  */
 export interface BoolNode {
-  /** @since 5.0 */
+  /**
+   * SQL node type.
+   *
+   * @since 5.0
+   */
   type: "boolean";
-  /** @since 5.0 */
+  /**
+   * Location of the boolean literal in the original SQL string.
+   *
+   * @since 5.0
+   */
   location: SQLSourceLocation;
   /**
    * Values are `true` or `false`.
@@ -272,9 +452,17 @@ export interface BoolNode {
  * @since 4.24
  */
 export interface StringNode {
-  /** @since 5.0 */
+  /**
+   * SQL node type.
+   *
+   * @since 5.0
+   */
   type: "string";
-  /** @since 5.0 */
+  /**
+   * Location of the string literal in the original SQL string.
+   *
+   * @since 5.0
+   */
   location: SQLSourceLocation;
   /**
    * The string value.
@@ -290,9 +478,17 @@ export interface StringNode {
  * @since 4.24
  */
 export interface NumberNode {
-  /** @since 5.0 */
+  /**
+   * SQL node type.
+   *
+   * @since 5.0
+   */
   type: "number";
-  /** @since 5.0 */
+  /**
+   * Location of the number literal in the original SQL string.
+   *
+   * @since 5.0
+   */
   location: SQLSourceLocation;
   /**
    * Numeric value.
@@ -308,9 +504,17 @@ export interface NumberNode {
  * @since 4.24
  */
 export interface DateNode {
-  /** @since 5.0 */
+  /**
+   * SQL node type.
+   *
+   * @since 5.0
+   */
   type: "date";
-  /** @since 5.0 */
+  /**
+   * Location of the date literal in the original SQL string.
+   *
+   * @since 5.0
+   */
   location: SQLSourceLocation;
   /**
    * The date value.
@@ -326,9 +530,17 @@ export interface DateNode {
  * @since 4.24
  */
 export interface TimeNode {
-  /** @since 5.0 */
+  /**
+   * SQL node type.
+   *
+   * @since 5.0
+   */
   type: "time";
-  /** @since 5.0 */
+  /**
+   * Location of the time literal in the original SQL string.
+   *
+   * @since 5.0
+   */
   location: SQLSourceLocation;
   /**
    * The time value.
@@ -344,9 +556,17 @@ export interface TimeNode {
  * @since 4.24
  */
 export interface TimeStampNode {
-  /** @since 5.0 */
+  /**
+   * SQL node type.
+   *
+   * @since 5.0
+   */
   type: "timestamp";
-  /** @since 5.0 */
+  /**
+   * Location of the timestamp literal in the original SQL string.
+   *
+   * @since 5.0
+   */
   location: SQLSourceLocation;
   /**
    * String date value.
@@ -362,9 +582,17 @@ export interface TimeStampNode {
  * @since 4.24
  */
 export interface ColumnNode {
-  /** @since 5.0 */
+  /**
+   * SQL node type.
+   *
+   * @since 5.0
+   */
   type: "column-reference";
-  /** @since 5.0 */
+  /**
+   * Location of the column name in the original SQL string.
+   *
+   * @since 5.0
+   */
   location: SQLSourceLocation;
   /**
    * Column or field name.
@@ -380,9 +608,17 @@ export interface ColumnNode {
  * @since 4.24
  */
 export interface CurrentTimeNode {
-  /** @since 5.0 */
+  /**
+   * SQL node type.
+   *
+   * @since 5.0
+   */
   type: "current-time";
-  /** @since 5.0 */
+  /**
+   * Location of the current time function in the original SQL string.
+   *
+   * @since 5.0
+   */
   location: SQLSourceLocation;
   /**
    * The current time node mode.
@@ -398,9 +634,17 @@ export interface CurrentTimeNode {
  * @since 4.31
  */
 export interface CurrentUserNode {
-  /** @since 5.0 */
+  /**
+   * SQL node type.
+   *
+   * @since 5.0
+   */
   type: "current-user";
-  /** @since 5.0 */
+  /**
+   * Location of the current user function in the original SQL string.
+   *
+   * @since 5.0
+   */
   location: SQLSourceLocation;
 }
 
@@ -411,9 +655,17 @@ export interface CurrentUserNode {
  * @since 4.24
  */
 export interface IntervalNode {
-  /** @since 5.0 */
+  /**
+   * SQL node type.
+   *
+   * @since 5.0
+   */
   type: "interval";
-  /** @since 5.0 */
+  /**
+   * Location of the interval expression in the original SQL string.
+   *
+   * @since 5.0
+   */
   location: SQLSourceLocation;
   /**
    * Interval node value.
@@ -443,13 +695,29 @@ export interface IntervalNode {
  * @since 4.24
  */
 export interface IntervalQualifierNode {
-  /** @since 5.0 */
+  /**
+   * SQL node type.
+   *
+   * @since 5.0
+   */
   type: "interval-qualifier";
-  /** @since 5.0 */
+  /**
+   * Location of the interval qualifier in the original SQL string.
+   *
+   * @since 5.0
+   */
   location: SQLSourceLocation;
-  /** @since 5.0 */
+  /**
+   * The start interval node period.
+   *
+   * @since 5.0
+   */
   start: IntervalPeriodNode;
-  /** @since 5.0 */
+  /**
+   * The end interval node period.
+   *
+   * @since 5.0
+   */
   end: IntervalPeriodNode;
 }
 
@@ -459,9 +727,17 @@ export interface IntervalQualifierNode {
  * @since 4.24
  */
 export interface IntervalPeriodNode {
-  /** @since 5.0 */
+  /**
+   * SQL node type.
+   *
+   * @since 5.0
+   */
   type: "interval-period";
-  /** @since 5.0 */
+  /**
+   * Location of the interval period in the original SQL string.
+   *
+   * @since 5.0
+   */
   location: SQLSourceLocation;
   /**
    * Interval node periods.
@@ -489,9 +765,17 @@ export interface IntervalPeriodNode {
  * @since 4.24
  */
 export interface FunctionNode {
-  /** @since 5.0 */
+  /**
+   * SQL node type.
+   *
+   * @since 5.0
+   */
   type: "function";
-  /** @since 5.0 */
+  /**
+   * Location of the SQL function in the original SQL string.
+   *
+   * @since 5.0
+   */
   location: SQLSourceLocation;
   /**
    * Name of the SQL function.
@@ -507,23 +791,51 @@ export interface FunctionNode {
   args: ListNode;
 }
 
-/** @since 5.0 */
+/**
+ * A binary operator that defines the way two expressions are combined to yield a single result.
+ *
+ * @since 5.0
+ */
 export type BinaryOperator = "AND" | "OR" | "IS" | "ISNOT" | "IN" | "NOT IN" | "BETWEEN" | "NOTBETWEEN" | "LIKE" | "NOT LIKE" | "<>" | "<" | ">" | ">=" | "<=" | "=" | "*" | "-" | "+" | "/" | "||";
 
-/** @since 4.26 */
+/**
+ * A node that contains data type. It is used in CAST expressions.
+ *
+ * @since 4.26
+ */
 export interface DataTypeNode {
-  /** @since 5.0 */
+  /**
+   * SQL node type.
+   *
+   * @since 5.0
+   */
   type: "data-type";
-  /** @since 5.0 */
+  /**
+   * Location of the data type in the original SQL string.
+   *
+   * @since 5.0
+   */
   location: SQLSourceLocation;
   /** @since 5.0 */
   value: DataTypeNodeValue;
 }
 
-/** @since 5.0 */
+/**
+ * Data type node value. It contains the name of the data type and an optional size for character types.
+ *
+ * @since 5.0
+ */
 export interface DataTypeNodeValue {
-  /** @since 5.0 */
+  /**
+   * The name of the data type.
+   *
+   * @since 5.0
+   */
   type: "integer" | "real" | "smallint" | "float" | "date" | "timestamp" | "varchar" | "time";
-  /** @since 5.0 */
+  /**
+   * Size of the data type. It is applicable for character types such as `varchar`.
+   *
+   * @since 5.0
+   */
   size?: number;
 }