import type GraphNamedObject from "./GraphNamedObject.js";
import type { JSONSupport } from "../../core/JSONSupport.js";
import type { GraphNamedObjectProperties } from "./GraphNamedObject.js";

export interface PathProperties {
  /**
   * Array of [entities](https://developers.arcgis.com/javascript/latest/api-reference/esri-rest-knowledgeGraph-Entity.html) and [relationships](https://developers.arcgis.com/javascript/latest/api-reference/esri-rest-knowledgeGraph-Relationship.html)
   * where the first element is the starting entity of the path, the final element is the ending entity of the path, and intermediary elements are entities and relationships connecting the two.
   */
  path?: GraphNamedObjectProperties[];
}

/**
 * An object containing all [entities](https://developers.arcgis.com/javascript/latest/api-reference/esri-rest-knowledgeGraph-Entity.html) and [relationships](https://developers.arcgis.com/javascript/latest/api-reference/esri-rest-knowledgeGraph-Relationship.html)
 * required to traverse a graph from one entity to another. A path can be restricted by the type and number of relationships used to connect entities.
 * For example, a query that asks for the path between entity `a` and entity `c` would return a `Path` containing the relationships
 * between `a-b` and `b-c` as well as the entities `a`, `b`, and `c`.
 *
 * Sample of the structure of a path object returned from [executeQuery()](https://developers.arcgis.com/javascript/latest/api-reference/esri-rest-knowledgeGraphService.html#executeQuery) using the query `MATCH q = (a)-->()-->(c) RETURN q LIMIT 1` which returns a path with intermediary entity.
 * ```js
 * KnowledgeGraphModule.executeQuery(
 *  knowledgeGraph, //graph
 *  {
 *    //query returning path from `a` to `c` with any intermediary entity
 *    openCypherQuery: "MATCH q = (a)-->()-->(c) RETURN q LIMIT 1",
 *   }).then((queryResult) => {
 *     //do something with the result
 *    //console.log(queryResult.ResultRows)
 * });
 * ```
 *
 * ```js
 * //sample output from the above query
 * [{
 *  "declaredClass": "esri.rest.knowledgeGraph.Path",
 *  "path": [
 *      {// entity `a`
 *       "declaredClass": "esri.rest.knowledgeGraph.Entity",
 *       "properties": {
 *        "name": "ABC Contractors",
 *        "CompanyType": "Construction",
 *      },
 *      "typeName": "Company",
 *      "id": "C1234"
 *    },
 *    { //relationship `a-b`
 *      "declaredClass": "esri.rest.Relationship.Relationship",
 *      "originID": "C1234",
 *      "destinationID": "S444",
 *      "properties": {
 *         "contract_expiration_date": "2025-05-26",
 *         "contact_person": "Jon Doe"
 *      },
 *      "typeName": "supplied_by",
 *      "id": "SB001"
 *    },
 *    { //entity `b`
 *     "declaredClass": "esri.rest.knowledgeGraph.Entity",
 *      "properties": {
 *        "objectid": 1,
 *        "shape": {
 *          "declaredClass": "esri.geometry.Point",
 *          "cache": {},
 *          "hasM": false,
 *          "hasZ": false,
 *          "latitude": 53.589000000000009,
 *          "longitude": -0.9633,
 *          "type": "point",
 *          "extent": null,
 *          "spatialReference": {
 *            "wkid": 4326
 *          },
 *          "x": -0.9633,
 *          "y": 53.589000000000009
 *        },
 *        "Employee_Count": 400,
 *        "Name": "Quality Metal Supply",
 *      },
 *      "typeName": "Supplier",
 *      "id": "S444",
 *    },
 *    { //relationship `b-c`
 *      "declaredClass": "esri.rest.Relationship.Relationship",
 *      "originID": "S444",
 *      "destinationID": "P789",
 *      "properties": {
 *        "frequency": "2 weeks",
 *        "quantity": 125000,
 *      },
 *      "typeName": "buys_part",
 *      "id": "BP456"
 *    },
 *    {// entity `c`
 *      "declaredClass": "esri.rest.knowledgeGraph.Entity",
 *      "properties": {
 *        "Name": "steel plate",
 *        "width": "15cm",
 *        "height": "10cm"
 *      },
 *      "typeName": "Part",
 *      "id": "P789"
 *    }
 *  ]
 * }]
 * ```
 *
 * @since 4.25
 */
export default class Path extends JSONSupport {
  constructor(properties?: PathProperties);
  /**
   * Array of [entities](https://developers.arcgis.com/javascript/latest/api-reference/esri-rest-knowledgeGraph-Entity.html) and [relationships](https://developers.arcgis.com/javascript/latest/api-reference/esri-rest-knowledgeGraph-Relationship.html)
   * where the first element is the starting entity of the path, the final element is the ending entity of the path, and intermediary elements are entities and relationships connecting the two.
   */
  get path(): GraphNamedObject[];
  set path(value: GraphNamedObjectProperties[]);
}