delectusnon 1.0.0

package/packages/arcgis-rest-geocoder/src/bulk.ts

@@ -0,0 +1,102 @@
+/* Copyright (c) 2017-2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { request } from "@esri/arcgis-rest-request";
+
+import { ISpatialReference, IPoint } from "@esri/arcgis-rest-common-types";
+
+import { worldGeocoder, IEndpointRequestOptions } from "./helpers";
+
+// it'd be better if doc didnt display these properties in alphabetical order
+export interface IAddressBulk {
+  /**
+   * A unique id must be passed along for each individual address.
+   */
+  OBJECTID: number;
+  address?: string;
+  address2?: string;
+  address3?: string;
+  neighborhood?: string;
+  city?: string;
+  subregion?: string;
+  /**
+   * The World Geocoding Service considers US states regions.
+   */
+  region?: string;
+  postal?: number;
+  postalExt?: number;
+  countryCode?: string;
+}
+
+export interface IBulkGeocodeRequestOptions extends IEndpointRequestOptions {
+  addresses: IAddressBulk[];
+}
+
+export interface IBulkGeocodeResponse {
+  spatialReference: ISpatialReference;
+  locations: Array<{
+    address: string;
+    location: IPoint;
+    score: number;
+    attributes: object;
+  }>;
+}
+
+/**
+ * Used to geocode a [batch](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-geocode-addresses.htm) of addresses.
+ *
+ * ```js
+ * import { bulkGeocode } from '@esri/arcgis-rest-geocoder';
+ * import { ApplicationSession } from '@esri/arcgis-rest-auth';
+ *
+ * const addresses = [
+ *   { "OBJECTID": 1, "SingleLine": "380 New York Street 92373" },
+ *   { "OBJECTID": 2, "SingleLine": "1 World Way Los Angeles 90045" }
+ * ];
+ *
+ * bulkGeocode({ addresses, authentication: session })
+ *   .then((response) => {
+ *     response.locations[0].location; // => { x: -117, y: 34, spatialReference: { wkid: 4326 } }
+ *   });
+ * ```
+ *
+ * @param requestOptions - Request options to pass to the geocoder, including an array of addresses and authentication session.
+ * @returns A Promise that will resolve with the data from the response.
+ */
+export function bulkGeocode(
+  requestOptions: IBulkGeocodeRequestOptions // must POST
+) {
+  const options: IBulkGeocodeRequestOptions = {
+    endpoint: worldGeocoder,
+    params: {
+      forStorage: true,
+      addresses: { records: [] }
+    },
+    ...requestOptions
+  };
+
+  requestOptions.addresses.forEach(address => {
+    options.params.addresses.records.push({ attributes: address });
+  });
+
+  // the SAS service doesnt support anonymous requests
+  if (!requestOptions.authentication && options.endpoint === worldGeocoder) {
+    return Promise.reject(
+      "bulk geocoding using the ArcGIS service requires authentication"
+    );
+  }
+
+  return request(options.endpoint + "geocodeAddresses", options).then(
+    response => {
+      const sr = response.spatialReference;
+      response.locations.forEach(function(address: { location: IPoint }) {
+        address.location.spatialReference = sr;
+      });
+      return response;
+    }
+  );
+}
+
+export default {
+  bulkGeocode
+};

package/packages/arcgis-rest-geocoder/src/geocode.ts

@@ -0,0 +1,117 @@
+/* Copyright (c) 2017-2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { request, IParams } from "@esri/arcgis-rest-request";
+
+import {
+  IExtent,
+  ISpatialReference,
+  IPoint
+} from "@esri/arcgis-rest-common-types";
+
+import { worldGeocoder, IEndpointRequestOptions } from "./helpers";
+
+export interface IGeocodeParams extends IParams {
+  /**
+   * You can create an autocomplete experience by making a call to suggest with partial text and then passing through the magicKey and complete address that are returned to geocode.
+   * ```js
+   * import { suggest, geocode } from '@esri/arcgis-rest-geocoder';
+   * suggest("LAX")
+   *   .then((response) => {
+   *     response.suggestions[2].magicKey; // =>  "dHA9MCNsb2M9Mjk3ODc2MCNsbmc9MzMjcGw9ODkxNDg4I2xicz0xNDoxNDc4MTI1MA=="
+   *   });
+   * geocode("LAX, 1 World Way, Los Angeles, CA, 90045, USA", {magicKey: "dHA9MCN..."})
+   * ```
+   */
+  magicKey?: string;
+}
+
+export interface IGeocodeRequestOptions extends IEndpointRequestOptions {
+  address?: string;
+  address2?: string;
+  address3?: string;
+  neighborhood?: string;
+  city?: string;
+  subregion?: string;
+  /**
+   * The World Geocoding Service expects US states to be passed in as a 'region'.
+   */
+  region?: string;
+  postal?: number;
+  postalExt?: number;
+  countryCode?: string;
+}
+
+export interface IGeocodeResponse {
+  spatialReference: ISpatialReference;
+  candidates: Array<{
+    address: string;
+    location: IPoint;
+    extent: IExtent;
+    attributes: object;
+  }>;
+}
+
+/**
+ * Used to determine the [location](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm)  of a single address or point of interest.
+ *
+ * ```js
+ * import { geocode } from '@esri/arcgis-rest-geocoder';
+ *
+ * geocode("LAX")
+ *   .then((response) => {
+ *     response.candidates[0].location; // => { x: -118.409, y: 33.943, spatialReference: { wkid: 4326 }  }
+ *   });
+ *
+ * geocode({
+ *   params: {
+ *     address: "1600 Pennsylvania Ave",
+ *     postal: 20500,
+ *     countryCode: "USA"
+ *   }
+ * })
+ *   .then((response) => {
+ *     response.candidates[0].location; // => { x: -77.036533, y: 38.898719, spatialReference: { wkid: 4326 } }
+ *   });
+ * ```
+ *
+ * @param address String representing the address or point of interest or RequestOptions to pass to the endpoint.
+ * @returns A Promise that will resolve with address candidates for the request.
+ */
+export function geocode(
+  address: string | IGeocodeRequestOptions
+): Promise<IGeocodeResponse> {
+  let options: IGeocodeRequestOptions = {
+    endpoint: worldGeocoder,
+    params: {}
+  };
+
+  if (typeof address === "string") {
+    options.params.singleLine = address;
+  } else {
+    options.endpoint = address.endpoint || worldGeocoder;
+    options = {
+      ...options,
+      ...address
+    };
+  }
+
+  // add spatialReference property to individual matches
+  return request(options.endpoint + "findAddressCandidates", options).then(
+    response => {
+      const sr = response.spatialReference;
+      response.candidates.forEach(function(candidate: {
+        location: IPoint;
+        extent: IExtent;
+      }) {
+        candidate.location.spatialReference = sr;
+        candidate.extent.spatialReference = sr;
+      });
+      return response;
+    }
+  );
+}
+
+export default {
+  geocode
+};

package/packages/arcgis-rest-geocoder/src/helpers.ts

@@ -0,0 +1,79 @@
+/* Copyright (c) 2017 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { request, IRequestOptions, warn } from "@esri/arcgis-rest-request";
+
+// https always
+export const worldGeocoder =
+  "https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/";
+
+export interface ILocation {
+  latitude?: number;
+  longitude?: number;
+  lat?: number;
+  long?: number;
+}
+
+// nice to have: verify custom endpoints contain 'GeocodeServer' and end in a '/'
+export interface IEndpointRequestOptions extends IRequestOptions {
+  /**
+   * Any ArcGIS Geocoding service (example: http://sampleserver6.arcgisonline.com/arcgis/rest/services/Locators/SanDiego/GeocodeServer )
+   */
+  endpoint?: string;
+}
+
+export interface IGetGeocodeServiceResponse {
+  currentVersion: number;
+  serviceDescription: string;
+  addressFields: any[];
+  countries: string[];
+  capabilities: string;
+}
+
+/**
+ * Used to fetch metadata from a geocoding service.
+ *
+ * ```js
+ * import { getGeocoderServiceInfo } from '@esri/arcgis-rest-geocoder';
+ *
+ * getGeocoderServiceInfo()
+ *   .then((response) => {
+ *     response.serviceDescription; // => 'World Geocoder'
+ *   });
+ * ```
+ *
+ * @param requestOptions - Request options can contain a custom geocoding service to fetch metadata from.
+ * @returns A Promise that will resolve with the data from the response.
+ */
+export function getGeocodeService(
+  requestOptions?: IEndpointRequestOptions
+): Promise<IGetGeocodeServiceResponse> {
+  const url = (requestOptions && requestOptions.endpoint) || worldGeocoder;
+
+  const options: IEndpointRequestOptions = {
+    httpMethod: "GET",
+    maxUrlLength: 2000,
+    ...requestOptions
+  };
+
+  return request(url, options);
+}
+
+/**
+ * Deprecated. Please use [`getGeocodeService()`](../getGeocodeService/) instead.
+ *
+ * @param requestOptions - Request options can contain a custom geocoding service to fetch metadata from.
+ * @returns A Promise that will resolve with the data from the response.
+ */
+export function serviceInfo(
+  requestOptions?: IEndpointRequestOptions
+): Promise<IGetGeocodeServiceResponse> {
+  warn(
+    "serviceInfo() will be deprecated in the next major release. please use getGeocoderServiceInfo() instead."
+  );
+  return getGeocodeService(requestOptions);
+}
+
+export default {
+  getGeocodeService
+};

package/packages/arcgis-rest-geocoder/src/index.ts

@@ -0,0 +1,8 @@
+/* Copyright (c) 2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+export * from "./geocode";
+export * from "./suggest";
+export * from "./reverse";
+export * from "./bulk";
+export * from "./helpers";

package/packages/arcgis-rest-geocoder/src/reverse.ts

@@ -0,0 +1,84 @@
+/* Copyright (c) 2017-2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { request } from "@esri/arcgis-rest-request";
+
+import { IPoint } from "@esri/arcgis-rest-common-types";
+
+import { worldGeocoder, ILocation, IEndpointRequestOptions } from "./helpers";
+
+export interface IReverseGeocodeResponse {
+  address: {
+    [key: string]: any;
+  };
+  location: IPoint;
+}
+
+function isLocationArray(
+  coords: ILocation | IPoint | [number, number]
+): coords is [number, number] {
+  return (coords as [number, number]).length === 2;
+}
+
+function isLocation(
+  coords: ILocation | IPoint | [number, number]
+): coords is ILocation {
+  return (
+    (coords as ILocation).latitude !== undefined ||
+    (coords as ILocation).lat !== undefined
+  );
+}
+
+/**
+ * Used to determine the address of a [location](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-reverse-geocode.htm).
+ *
+ * ```js
+ * import { reverseGeocode } from '@esri/arcgis-rest-geocoder';
+ *
+ * // long, lat
+ * reverseGeocode([-118.409,33.943 ])
+ *   .then((response) => {
+ *     response.address.PlaceName; // => "LA Airport"
+ *   });
+ *
+ * // or
+ * reverseGeocode({ long: -118.409, lat: 33.943 })
+ * reverseGeocode({ latitude: 33.943, latitude: -118.409 })
+ * reverseGeocode({ x: -118.409, y: 33.9425 }) // wgs84 is assumed
+ * reverseGeocode({ x: -13181226, y: 4021085, spatialReference: { wkid: 3857 })
+ * ```
+ *
+ * @param coordinates - the location you'd like to associate an address with.
+ * @param requestOptions - Additional options for the request including authentication.
+ * @returns A Promise that will resolve with the data from the response.
+ */
+export function reverseGeocode(
+  coords: IPoint | ILocation | [number, number],
+  requestOptions?: IEndpointRequestOptions
+): Promise<IReverseGeocodeResponse> {
+  const options: IEndpointRequestOptions = {
+    endpoint: worldGeocoder,
+    params: {},
+    ...requestOptions
+  };
+
+  if (isLocationArray(coords)) {
+    options.params.location = coords.join();
+  } else if (isLocation(coords)) {
+    if (coords.lat) {
+      options.params.location = coords.long + "," + coords.lat;
+    }
+    if (coords.latitude) {
+      options.params.location = coords.longitude + "," + coords.latitude;
+    }
+  } else {
+    // if input is a point, we can pass it straight through, with or without a spatial reference
+    options.params.location = coords;
+  }
+
+  return request(options.endpoint + "reverseGeocode", options);
+}
+
+export default {
+  reverseGeocode
+};

package/packages/arcgis-rest-geocoder/src/suggest.ts

@@ -0,0 +1,72 @@
+/* Copyright (c) 2017-2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { request } from "@esri/arcgis-rest-request";
+
+import { worldGeocoder, IEndpointRequestOptions } from "./helpers";
+
+export interface ISuggestRequestOptions extends IEndpointRequestOptions {
+  /**
+   * You can create an autocomplete experience by making a call to suggest with partial text and then passing through the magicKey and complete address that are returned to geocode.
+   * ```js
+   * import { suggest, geocode } from '@esri/arcgis-rest-geocoder';
+   * suggest("LAX")
+   *   .then((response) => {
+   *     response.suggestions[2].magicKey; // =>  "dHA9MCNsb2M9Mjk3ODc2MCNsbmc9MzMjcGw9ODkxNDg4I2xicz0xNDoxNDc4MTI1MA=="
+   *   });
+   * geocode("LAX, 1 World Way, Los Angeles, CA, 90045, USA", {magicKey: "dHA9MCN..."})
+   * ```
+   */
+  magicKey?: string;
+}
+
+export interface ISuggestResponse {
+  suggestions: Array<{
+    text: string;
+    magicKey: string;
+    isCollection: boolean;
+  }>;
+}
+
+/**
+ * Used to return a placename [suggestion]((https://developers.arcgis.com/rest/geocode/api-reference/geocoding-suggest.htm) for a partial string.
+ *
+ * ```js
+ * import { suggest } from '@esri/arcgis-rest-geocoder';
+ *
+ * suggest("Starb")
+ *   .then((response) => {
+ *     response.address.PlaceName; // => "Starbucks"
+ *   });
+ * ```
+ *
+ * @param requestOptions - Options for the request including authentication and other optional parameters.
+ * @returns A Promise that will resolve with the data from the response.
+ */
+export function suggest(
+  partialText: string,
+  requestOptions?: ISuggestRequestOptions
+): Promise<ISuggestResponse> {
+  const options: ISuggestRequestOptions = {
+    endpoint: worldGeocoder,
+    params: {},
+    ...requestOptions
+  };
+
+  // is this the most concise way to mixin these optional parameters?
+  if (requestOptions && requestOptions.params) {
+    options.params = requestOptions.params;
+  }
+
+  if (requestOptions && requestOptions.magicKey) {
+    options.params.magicKey = requestOptions.magicKey;
+  }
+
+  options.params.text = partialText;
+
+  return request(options.endpoint + "suggest", options);
+}
+
+export default {
+  suggest
+};

package/packages/arcgis-rest-geocoder/test/bulk.test.ts

@@ -0,0 +1,113 @@
+/* Copyright (c) 2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { bulkGeocode } from "../src/bulk";
+
+import * as fetchMock from "fetch-mock";
+
+import { GeocodeAddresses } from "./mocks/responses";
+
+const addresses = [
+  {
+    OBJECTID: 1,
+    SingleLine: "380 New York St. Redlands 92373"
+  },
+  {
+    OBJECTID: 2,
+    SingleLine: "1 World Way Los Angeles 90045"
+  }
+];
+
+describe("geocode", () => {
+  afterEach(fetchMock.restore);
+
+  it("should make a bulk geocoding request", done => {
+    fetchMock.once("*", GeocodeAddresses);
+
+    const MOCK_AUTH = {
+      getToken() {
+        return Promise.resolve("token");
+      },
+      portal: "https://mapsdev.arcgis.com"
+    };
+
+    bulkGeocode({ addresses, authentication: MOCK_AUTH })
+      .then(response => {
+        expect(fetchMock.called()).toEqual(true);
+        const [url, options]: [string, RequestInit] = fetchMock.lastCall("*");
+        expect(url).toEqual(
+          "https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/geocodeAddresses"
+        );
+        expect(options.method).toBe("POST");
+        expect(options.body).toContain("f=json");
+        expect(options.body).toContain(
+          `addresses=${encodeURIComponent(
+            '{"records":[{"attributes":{"OBJECTID":1,"SingleLine":"380 New York St. Redlands 92373"}},{"attributes":{"OBJECTID":2,"SingleLine":"1 World Way Los Angeles 90045"}}]}'
+          )}`
+        );
+        expect(options.body).toContain("token=token");
+        expect(response.spatialReference.latestWkid).toEqual(4326);
+        expect(response.locations[0].address).toEqual(
+          "380 New York St, Redlands, California, 92373"
+        );
+        expect(response.locations[0].location.x).toEqual(-117.19567031799994);
+        // the only property this lib tacks on
+        expect(response.locations[0].location.spatialReference.wkid).toEqual(
+          4326
+        );
+        done();
+      })
+      .catch(e => {
+        fail(e);
+      });
+  });
+
+  it("should throw an error when a bulk geocoding request is made without a token", done => {
+    fetchMock.once("*", GeocodeAddresses);
+
+    bulkGeocode({ addresses })
+      // tslint:disable-next-line
+      .catch(e => {
+        expect(e).toEqual(
+          "bulk geocoding using the ArcGIS service requires authentication"
+        );
+        done();
+      });
+  });
+
+  it("should send a bulk geocoding request to a custom url without a token", done => {
+    fetchMock.once("*", GeocodeAddresses);
+
+    bulkGeocode({
+      addresses,
+      endpoint:
+        "https://customer.gov/arcgis/rest/services/CompositeGeocoder/GeocodeServer/"
+    })
+      // tslint:disable-next-line
+      .then(response => {
+        expect(fetchMock.called()).toEqual(true);
+        const [url, options]: [string, RequestInit] = fetchMock.lastCall("*");
+        expect(url).toEqual(
+          "https://customer.gov/arcgis/rest/services/CompositeGeocoder/GeocodeServer/geocodeAddresses"
+        );
+        expect(options.method).toBe("POST");
+        expect(options.body).toContain("f=json");
+        expect(options.body).toContain(
+          `addresses=${encodeURIComponent(
+            '{"records":[{"attributes":{"OBJECTID":1,"SingleLine":"380 New York St. Redlands 92373"}},{"attributes":{"OBJECTID":2,"SingleLine":"1 World Way Los Angeles 90045"}}]}'
+          )}`
+        );
+        // expect(options.body).toContain("token=token");
+        expect(response.spatialReference.latestWkid).toEqual(4326);
+        expect(response.locations[0].address).toEqual(
+          "380 New York St, Redlands, California, 92373"
+        );
+        expect(response.locations[0].location.x).toEqual(-117.19567031799994);
+        // the only property this lib tacks on
+        expect(response.locations[0].location.spatialReference.wkid).toEqual(
+          4326
+        );
+        done();
+      });
+  });
+});

package/packages/arcgis-rest-geocoder/test/geocode.test.ts

@@ -0,0 +1,121 @@
+/* Copyright (c) 2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { geocode } from "../src/geocode";
+
+import * as fetchMock from "fetch-mock";
+
+import { FindAddressCandidates } from "./mocks/responses";
+
+const customGeocoderUrl =
+  "https://foo.com/arcgis/rest/services/Custom/GeocodeServer/";
+
+describe("geocode", () => {
+  afterEach(fetchMock.restore);
+
+  it("should make a simple, single geocoding request", done => {
+    fetchMock.once("*", FindAddressCandidates);
+
+    geocode("LAX")
+      .then(response => {
+        expect(fetchMock.called()).toEqual(true);
+        const [url, options]: [string, RequestInit] = fetchMock.lastCall("*");
+        expect(url).toEqual(
+          "https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates"
+        );
+        expect(options.method).toBe("POST");
+        expect(options.body).toContain("f=json");
+        expect(options.body).toContain("singleLine=LAX");
+        // the only property this lib tacks on
+        expect(response.spatialReference.wkid).toEqual(4326);
+        done();
+      })
+      .catch(e => {
+        fail(e);
+      });
+  });
+
+  it("should make a simple, single geocoding request with a custom parameter", done => {
+    fetchMock.once("*", FindAddressCandidates);
+
+    geocode({ params: { singleLine: "LAX", countryCode: "USA" } })
+      .then(response => {
+        expect(fetchMock.called()).toEqual(true);
+        const [url, options]: [string, RequestInit] = fetchMock.lastCall("*");
+        expect(url).toEqual(
+          "https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates"
+        );
+        expect(options.method).toBe("POST");
+        expect(options.body).toContain("f=json");
+        expect(options.body).toContain("singleLine=LAX");
+        expect(options.body).toContain("countryCode=USA");
+        // the only property this lib tacks on
+        expect(response.spatialReference.wkid).toEqual(4326);
+        done();
+      })
+      .catch(e => {
+        fail(e);
+      });
+  });
+
+  it("should make a single geocoding request to a custom geocoding service", done => {
+    fetchMock.once("*", FindAddressCandidates);
+
+    geocode({
+      endpoint: customGeocoderUrl,
+      params: {
+        outSr: 3857,
+        address: "380 New York St",
+        postal: 92373
+      }
+    })
+      .then(response => {
+        expect(fetchMock.called()).toEqual(true);
+        const [url, options]: [string, RequestInit] = fetchMock.lastCall("*");
+        expect(url).toEqual(
+          "https://foo.com/arcgis/rest/services/Custom/GeocodeServer/findAddressCandidates"
+        );
+        expect(options.method).toBe("POST");
+        expect(options.body).toContain("f=json");
+        expect(options.body).toContain(
+          `address=${encodeURIComponent("380 New York St")}`
+        );
+        expect(options.body).toContain("postal=92373");
+        expect(options.body).toContain("outSr=3857");
+        // the only property this lib tacks on
+        expect(response.spatialReference.wkid).toEqual(4326);
+        done();
+      })
+      .catch(e => {
+        fail(e);
+      });
+  });
+
+  it("should pass through all requestOptions when making a geocoding request", done => {
+    fetchMock.once("*", FindAddressCandidates);
+
+    geocode({
+      endpoint: customGeocoderUrl,
+      params: {
+        outSr: 3857,
+        address: "380 New York St",
+        postal: 92373
+      },
+      httpMethod: "GET"
+    })
+      .then(response => {
+        expect(fetchMock.called()).toEqual(true);
+        const [url, options]: [string, RequestInit] = fetchMock.lastCall("*");
+        expect(url).toEqual(
+          "https://foo.com/arcgis/rest/services/Custom/GeocodeServer/findAddressCandidates?f=json&outSr=3857&address=380%20New%20York%20St&postal=92373"
+        );
+        expect(options.method).toBe("GET");
+        // the only property this lib tacks on
+        expect(response.spatialReference.wkid).toEqual(4326);
+        done();
+      })
+      .catch(e => {
+        fail(e);
+      });
+  });
+});