[mod] Update incorrect type definitions with function overloading (#53)

* [mod] Update incorrect type definitions with function overloading

* [mod] type definition update for What3wordsService interface

* [mod] type definitions when not format provided

Author: c5haw

.gitignore

@@ -210,3 +210,5 @@ $RECYCLE.BIN/
 
 # Snyk cacke
 .dccache
+
+pacts/

package.json

@@ -1,7 +1,7 @@
 {
   "private": false,
   "name": "@what3words/api",
-  "version": "4.0.6",
+  "version": "4.0.7",
   "description": "what3words JavaScript API",
   "homepage": "https://github.com/what3words/w3w-node-wrapper#readme",
   "main": "dist/index.js",

src/client/convert-to-3wa.ts

@@ -2,6 +2,7 @@ import { ApiClient } from '../lib';
 import type { ApiClientConfiguration, Transport } from '../lib';
 import type {
   Coordinates,
+  FeatureCollectionResponse,
   LocationGeoJsonResponse,
   LocationJsonResponse,
 } from './response.model';
@@ -13,8 +14,9 @@ export type ConvertTo3waOptions = {
 };
 
 export class ConvertTo3waClient extends ApiClient<
-  LocationGeoJsonResponse | LocationJsonResponse,
-  ConvertTo3waOptions
+  LocationJsonResponse,
+  ConvertTo3waOptions,
+  FeatureCollectionResponse<LocationGeoJsonResponse>
 > {
   protected readonly method = 'get';
   protected readonly url = '/convert-to-3wa';

src/client/convert-to-coordinates.ts

@@ -1,6 +1,7 @@
 import { ApiClient } from '../lib';
 import type { ApiClientConfiguration, Transport } from '../lib';
 import type {
+  FeatureCollectionResponse,
   LocationGeoJsonResponse,
   LocationJsonResponse,
 } from './response.model';
@@ -11,8 +12,9 @@ export type ConvertToCoordinatesOptions = {
 };
 
 export class ConvertToCoordinatesClient extends ApiClient<
-  LocationJsonResponse | LocationGeoJsonResponse,
-  ConvertToCoordinatesOptions
+  LocationJsonResponse,
+  ConvertToCoordinatesOptions,
+  FeatureCollectionResponse<LocationGeoJsonResponse>
 > {
   protected readonly method = 'get';
   protected readonly url = '/convert-to-coordinates';

src/client/grid-section.ts

@@ -1,6 +1,6 @@
 import { ApiClient, boundsToString } from '../lib';
 import type { ApiClientConfiguration, Transport } from '../lib';
-import type { Coordinates } from './response.model';
+import type { Coordinates, FeatureCollectionResponse } from './response.model';
 
 export interface GridSectionJsonResponse {
   lines: {
@@ -23,8 +23,9 @@ export type GridSectionOptions = {
 };
 
 export class GridSectionClient extends ApiClient<
-  GridSectionJsonResponse | GridSectionGeoJsonResponse,
-  GridSectionOptions
+  GridSectionJsonResponse,
+  GridSectionOptions,
+  FeatureCollectionResponse<GridSectionGeoJsonResponse>
 > {
   protected readonly method = 'get';
   protected readonly url = '/grid-section';

src/client/response.model.ts

@@ -36,3 +36,8 @@ export interface LocationGeoJsonResponse {
 export interface RequestOptions {
   [x: string]: string;
 }
+
+export interface FeatureCollectionResponse<LocationResponse> {
+  features: LocationResponse[];
+  type: 'FeatureCollection';
+}

src/lib/client/abstract.ts

@@ -7,14 +7,18 @@ import {
 } from '../transport';
 import { HEADERS } from '../constants';
 
-export abstract class ApiClient<Response, Params = undefined> {
+export abstract class ApiClient<
+  JsonResponse,
+  Params = undefined,
+  GeoJsonResponse = JsonResponse
+> {
   protected abstract url: string;
   protected abstract method: 'get' | 'post';
+  protected _config: ApiClientConfiguration;
   private static DEFAULT_CONFIG = {
     host: 'https://api.what3words.com',
     apiVersion: ApiVersion.Version3,
   };
-  private _config: ApiClientConfiguration;
   private transport: Transport;
 
   constructor(
@@ -44,7 +48,14 @@ export abstract class ApiClient<Response, Params = undefined> {
     return this._config;
   }
 
-  public async run(options?: Params): Promise<Response> {
+  public async run(options?: Params): Promise<JsonResponse>;
+  public async run(
+    options?: Params & { format?: 'json' }
+  ): Promise<JsonResponse>;
+  public async run(
+    options?: Params & { format: 'geojson' }
+  ): Promise<GeoJsonResponse>;
+  public async run(options?: Params): Promise<JsonResponse | GeoJsonResponse> {
     const validation = await this.validate(options);
     if (!validation.valid) {
       throw new Error(
@@ -57,11 +68,9 @@ export abstract class ApiClient<Response, Params = undefined> {
       body: this.body(options),
       query: this.query(options),
     };
-    const response = await this.makeClientRequest<Response>(
-      this.method,
-      this.url,
-      params
-    );
+    const response = await this.makeClientRequest<
+      JsonResponse | GeoJsonResponse
+    >(this.method, this.url, params);
     if (!response.body) throw new Error('No response body set');
     return response.body;
   }

src/service.ts

@@ -3,6 +3,7 @@ import {
   AvailableLanguagesClient,
   ConvertTo3waClient,
   ConvertToCoordinatesClient,
+  FeatureCollectionResponse,
   GridSectionClient,
 } from './client';
 import type {
@@ -21,29 +22,43 @@ import type {
 import { ApiClientConfiguration } from './lib';
 import type { Transport } from './lib';
 
-export type What3wordsService = {
+export interface What3wordsService {
   clients: {
     autosuggest: AutosuggestClient;
     availableLanguages: AvailableLanguagesClient;
     convertTo3wa: ConvertTo3waClient;
     convertToCoordinates: ConvertToCoordinatesClient;
     gridSection: GridSectionClient;
   };
-  setApiKey: (key: string) => void;
-  setConfig: (config: ApiClientConfiguration) => void;
-  autosuggest: (options: AutosuggestOptions) => Promise<AutosuggestResponse>;
-  autosuggestSelection: (options: AutosuggestSuggestion) => Promise<void>;
-  availableLanguages: () => Promise<AvailableLanguagesResponse>;
-  convertTo3wa: (
-    options: ConvertTo3waOptions
-  ) => Promise<LocationGeoJsonResponse | LocationJsonResponse>;
-  convertToCoordinates: (
+  setApiKey(key: string): void;
+  setConfig(config: ApiClientConfiguration): void;
+  autosuggest(options: AutosuggestOptions): Promise<AutosuggestResponse>;
+  autosuggestSelection(options: AutosuggestSuggestion): Promise<void>;
+  availableLanguages(): Promise<AvailableLanguagesResponse>;
+  convertTo3wa(options: ConvertTo3waOptions): Promise<LocationJsonResponse>;
+  convertTo3wa(
+    options: ConvertTo3waOptions & { format?: 'json' }
+  ): Promise<LocationJsonResponse>;
+  convertTo3wa(
+    options: ConvertTo3waOptions & { format: 'geojson' }
+  ): Promise<FeatureCollectionResponse<LocationGeoJsonResponse>>;
+  convertToCoordinates(
     options: ConvertToCoordinatesOptions
-  ) => Promise<LocationJsonResponse | LocationGeoJsonResponse>;
-  gridSection: (
-    options: GridSectionOptions
-  ) => Promise<GridSectionJsonResponse | GridSectionGeoJsonResponse>;
-};
+  ): Promise<LocationJsonResponse>;
+  convertToCoordinates(
+    options: ConvertToCoordinatesOptions & { format?: 'json' }
+  ): Promise<LocationJsonResponse>;
+  convertToCoordinates(
+    options: ConvertToCoordinatesOptions & { format: 'geojson' }
+  ): Promise<FeatureCollectionResponse<LocationGeoJsonResponse>>;
+  gridSection(options: GridSectionOptions): Promise<GridSectionJsonResponse>;
+  gridSection(
+    options: GridSectionOptions & { format?: 'json' }
+  ): Promise<GridSectionJsonResponse>;
+  gridSection(
+    options: GridSectionOptions & { format: 'geojson' }
+  ): Promise<FeatureCollectionResponse<GridSectionGeoJsonResponse>>;
+}
 
 export function what3words(
   apiKey?: string,

test/service.spec.ts

@@ -1,11 +1,13 @@
 import 'should';
 import nock from 'nock';
 import { Chance } from 'chance';
+import { SinonSpy, spy } from 'sinon';
 import what3words, {
   ApiClientConfiguration,
   ApiVersion,
   searchParams,
   axiosTransport,
+  Transport,
 } from '../src';
 import { What3wordsService } from '../src/service';
 
@@ -22,6 +24,8 @@ describe('what3words', () => {
   let apiVersion: ApiVersion;
   let apiKey: string;
   let config: ApiClientConfiguration;
+  let transportSpy: SinonSpy;
+  let transport: Transport;
 
   beforeEach(() => {
     apiKey = CHANCE.string({ length: 8 });
@@ -35,6 +39,15 @@ describe('what3words', () => {
       apiVersion,
       headers: {},
     };
+    transportSpy = spy();
+    transport = async (...args) => {
+      transportSpy(...args);
+      return {
+        status: 200,
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        body: {} as any,
+      };
+    };
   });
 
   describe('Service', () => {