refactor(geocoder): use a more descriptive method to fetch metadata

and set up previous method to be deprecated in next major release

AFFECTS PACKAGES:
@esri/arcgis-rest-geocoder
@esri/arcgis-rest-request

ISSUES CLOSED: #122

more

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

@@ -1,7 +1,12 @@
 /* Copyright (c) 2017 Environmental Systems Research Institute, Inc.
  * Apache-2.0 */
 
-import { request, IRequestOptions, IParams } from "@esri/arcgis-rest-request";
+import {
+  request,
+  IRequestOptions,
+  IParams,
+  warn
+} from "@esri/arcgis-rest-request";
 // import { IAuthenticatedRequestOptions } from "@esri/arcgis-rest-auth";
 
 import {
@@ -368,9 +373,9 @@ export function bulkGeocode(
  * Used to fetch metadata from a geocoding service.
  *
  * ```js
- * import { serviceInfo } from '@esri/arcgis-geocoder';
+ * import { getGeocoderServiceInfo } from '@esri/arcgis-geocoder';
  *
- * serviceInfo()
+ * getGeocoderServiceInfo()
  *   .then((response) => {
  *     response.serviceDescription; // => 'World Geocoder'
  *   });
@@ -379,13 +384,28 @@ export function bulkGeocode(
  * @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(
+export function getGeocoderServiceInfo(
   requestOptions?: IGeocodeRequestOptions
 ): Promise<IGeocodeServiceInfoResponse> {
   const url = (requestOptions && requestOptions.endpoint) || worldGeocoder;
   return request(url, requestOptions);
 }
 
+/**
+ * Deprecated. Please use `getGeocoderServiceInfo()` 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?: IGeocodeRequestOptions
+): Promise<IGeocodeServiceInfoResponse> {
+  warn(
+    "serviceInfo() will be deprecated in the next major release. please use getGeocoderServiceInfo() instead."
+  );
+  return getGeocoderServiceInfo(requestOptions);
+}
+
 export default {
   geocode,
   suggest,

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

@@ -3,7 +3,8 @@ import {
   suggest,
   reverseGeocode,
   bulkGeocode,
-  serviceInfo
+  serviceInfo,
+  getGeocoderServiceInfo
 } from "../src/index";
 
 import * as fetchMock from "fetch-mock";
@@ -343,9 +344,12 @@ describe("geocode", () => {
       });
   });
 
-  it("should retrieve metadata from the World Geocoding Service", done => {
+  it("should retrieve metadata from the World Geocoding Service using the old method name", done => {
     fetchMock.once("*", SharingInfo);
 
+    // intercept deprecation warning
+    console.warn = jasmine.createSpy("warning");
+
     serviceInfo()
       .then(response => {
         expect(fetchMock.called()).toEqual(true);
@@ -367,10 +371,34 @@ describe("geocode", () => {
       });
   });
 
+  it("should retrieve metadata from the World Geocoding Service", done => {
+    fetchMock.once("*", SharingInfo);
+
+    getGeocoderServiceInfo()
+      .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/"
+        );
+        expect(options.method).toBe("POST");
+        expect(options.body).toContain("f=json");
+        // expect(response).toEqual(SharingInfo); // need to fix something in order introspect the whole response
+        expect(response.currentVersion).toEqual(10.41);
+        expect(response.serviceDescription).toEqual(
+          "Sample geocoder for San Diego, California, USA"
+        );
+        done();
+      })
+      .catch(e => {
+        fail(e);
+      });
+  });
+
   it("should make GET request for metadata from the World Geocoding Service", done => {
     fetchMock.once("*", SharingInfo);
 
-    serviceInfo({ httpMethod: "GET" })
+    getGeocoderServiceInfo({ httpMethod: "GET" })
       .then(response => {
         expect(fetchMock.called()).toEqual(true);
         const [url, options]: [string, RequestInit] = fetchMock.lastCall("*");
@@ -394,7 +422,7 @@ describe("geocode", () => {
   it("should retrieve metadata from custom geocoding services", done => {
     fetchMock.once("*", SharingInfo);
 
-    serviceInfo({ endpoint: customGeocoderUrl })
+    getGeocoderServiceInfo({ endpoint: customGeocoderUrl })
       .then(response => {
         expect(fetchMock.called()).toEqual(true);
         const [url, options]: [string, RequestInit] = fetchMock.lastCall("*");

packages/arcgis-rest-request/src/utils/check-for-errors.ts

@@ -54,3 +54,12 @@ export function checkForErrors(
 
   return response;
 }
+
+/**
+ * Method used internally to surface messages to developers.
+ */
+export function warn(message: string) {
+  if (console && console.warn) {
+    console.warn.apply(console, [message]);
+  }
+}

packages/arcgis-rest-request/test/utils/check-for-errors.test.ts

@@ -1,5 +1,6 @@
 import {
   checkForErrors,
+  warn,
   ArcGISRequestError,
   ArcGISAuthError
 } from "../../src/index";
@@ -80,3 +81,19 @@ describe("checkForErrors", () => {
     }).toThrowError(ArcGISAuthError, "GWM_0003: Token Required");
   });
 });
+
+describe("warn", () => {
+  it("should bubble up deprecation warnings", () => {
+    console.warn = jasmine.createSpy("warning");
+    warn("Danger Will Robinson!");
+    expect(console.warn).toHaveBeenCalledWith("Danger Will Robinson!");
+  });
+});
+
+describe("warn", () => {
+  it("should carry on gracefully when no console is available", () => {
+    console.warn = undefined;
+    warn("Danger Will Robinson!");
+    expect(console.warn).toBe(undefined);
+  });
+});