Merge pull request #262 from wellwelwel/master

feat(index.d.ts): flexible `AvailableProviders` and minimal documentation

Author: lucianopf

index.d.ts

@@ -1,28 +1,78 @@
-declare module 'cep-promise' {
+declare module "cep-promise" {
+  /** Represents the result of a CEP search */
   export interface CEP {
-    cep: string,
-    state: string,
-    city: string,
-    street: string,
-    neighborhood: string,
-    service: string
-  }
-
-  export enum AvailableProviders {
-    brasilapi = "brasilapi",
-    correios = "correios",
-    correiosAlt = "correios-alt",
-    viacep = "viacep",
-    widenet = "widenet"
+    /** The retrieved CEP number */
+    cep: string;
+    /** The state associated with the CEP */
+    state: string;
+    /** The city associated with the CEP */
+    city: string;
+    /** The street associated with the CEP */
+    street: string;
+    /** The neighborhood associated with the CEP */
+    neighborhood: string;
+    /** The provider which returned the result */
+    service: string;
   }
 
+  /**
+   * Available providers:
+   *
+   * | Provider     | Browser | Node.js |
+   * | ------------ | ------- | ------- |
+   * | brasilapi    | ✅      | ✅      |
+   * | viacep       | ✅      | ✅      |
+   * | widenet      | ✅      | ✅      |
+   * | correios     | ❌      | ✅      |
+   * | correios-alt | ❌      | ✅      |
+   */
+  export const AvailableProviders: {
+    /** Supported in both **Node.js** and **Browser** environments. */
+    readonly brasilapi: "brasilapi";
+    /** Supported in both **Node.js** and **Browser** environments. */
+    readonly viacep: "viacep";
+    /** Supported in both **Node.js** and **Browser** environments. */
+    readonly widenet: "widenet";
+    /** Supported only in **Node.js** environment. */
+    readonly correios: "correios";
+    /** Supported only in **Node.js** environment. */
+    readonly correiosAlt: "correios-alt";
+  };
 
+  /** Configuration options to customize the CEP search, by selecting specific providers and/or setting a timeout */
   export interface Configurations {
-    providers?: AvailableProviders[],
-    timeout?: number
+    /** Specifies the providers to be used for CEP searches, otherwise all available providers will be used.
+     *
+     * ---
+     *
+     * Available providers:
+     *
+     * | Provider     | Browser | Node.js |
+     * | ------------ | ------- | ------- |
+     * | brasilapi    | ✅      | ✅      |
+     * | viacep       | ✅      | ✅      |
+     * | widenet      | ✅      | ✅      |
+     * | correios     | ❌      | ✅      |
+     * | correios-alt | ❌      | ✅      |
+     */
+    providers?: (typeof AvailableProviders)[keyof typeof AvailableProviders][];
+    /** Timeout (in milliseconds) after which the CEP search will be cancelled. */
+    timeout?: number;
   }
 
-  export function cep(cep: string | number, configurations?: Configurations): Promise<CEP>
+  /**
+   * Searches for CEP directly integrated with the services of Correios, ViaCEP, and WideNet (Node.js and Browser).
+   *
+   * ---
+   *
+   * @param cep The CEP (postal code) to search for.
+   * @param configurations Optional configurations to customize the CEP search.
+   * @returns A promise that resolves with the CEP details.
+   */
+  export function cep(
+    cep: string | number,
+    configurations?: Configurations
+  ): Promise<CEP>;
 
-  export default cep
+  export default cep;
 }

test/e2e/cep-promise.spec.js

@@ -62,7 +62,7 @@ describe('[e2e] cep-promise', () => {
                 service: 'correios'
               },
               {
-                message: 'CEP não encontrado na base dos Correios.',
+                message: 'Erro ao se conectar com o serviço dos Correios Alt.',
                 service: 'correios-alt'
               },
               {
@@ -102,4 +102,4 @@ describe('[e2e] cep-promise', () => {
       })
     })
   })
-})
+})