Add isZipCode validator (#3)

* Add isZipCode validator

* Add doc strings to all the functions

* Release 1.2.0

README.md

@@ -1,6 +1,8 @@
 # validator-ec
 
-**validator-ec** es una colección de validadores de datos para Ecuador desarrollada en TypeScript. Actualmente, cuenta con validadores para cédulas de identidad ecuatorianas y números de RUC (Registro Único de Contribuyentes).
+Colección de validadores de datos comunes en Ecuador desarrollada en TypeScript.
+
+Actualmente, cuenta con validadores para cédulas de identidad ecuatorianas, números de RUC (Registro Único de Contribuyentes) y códigos postales.
 
 ## Características
 
@@ -32,10 +34,11 @@ npm install validator-ec
 
 ## Validadores
 
-| Validador                           | Descripción                                                                                                               | Ejemplo                  |
-| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
-| `isCedula(cedula: string): boolean` | Valida una cédula de identidad ecuatoriana. Devuelve `true` si la cédula es válida, de lo contrario `false`.              | `isCedula('1710034065')` |
-| `isRUC(ruc: string): boolean`       | Valida un número de RUC (Registro Único de Contribuyentes). Devuelve `true` si el RUC es válido, de lo contrario `false`. | `isRUC('1790016919001')` |
+| Validador                             | Descripción                                                                                                               | Ejemplo                  |
+| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| `isCedula(cedula: string): boolean`   | Valida una cédula de identidad ecuatoriana. Devuelve `true` si la cédula es válida, de lo contrario `false`.              | `isCedula('1710034065')` |
+| `isRUC(ruc: string): boolean`         | Valida un número de RUC (Registro Único de Contribuyentes). Devuelve `true` si el RUC es válido, de lo contrario `false`. | `isRUC('1790016919001')` |
+| `isZipCode(zipCode: string): boolean` | Valida un código postal ecuatoriano. Devuelve `true` si el código postal es válido, de lo contrario `false`.              | `isZipCode('131401')`    |
 
 ## Uso
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "validator-ec",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "type": "module",
   "author": "Victor Bayas",
   "license": "Apache-2.0",

src/helpers/isDigits.ts

@@ -1,4 +1,7 @@
-// Helper para validar que una cadena contenga únicamente dígitos.
+/**
+ * @param {string} value La cadena de texto a validar.
+ * @returns {boolean} Devuelve `true si la cadena de texto contiene únicamente dígitos, de lo contrario devuelve `false`.
+ */
 export default function isDigits(value: string): boolean {
   return /^\d+$/.test(value);
 }

src/index.ts

@@ -1,4 +1,5 @@
 import isCedula from "./lib/isCedula";
 import isRUC from "./lib/isRUC";
+import isZipCode from "./lib/isZipCode";
 
-export { isCedula, isRUC };
+export { isCedula, isRUC, isZipCode };

src/lib/isCedula.ts

@@ -1,5 +1,10 @@
 import isDigits from "../helpers/isDigits";
 
+/**
+ *
+ * @param {string} cedula La cédula a validar.
+ * @returns {boolean} Devuelve `true` si la cédula es válida, de lo contrario devuelve `false`.
+ */
 export default function isCedula(cedula: string): boolean {
   // Validamos que la cédula tenga 10 dígitos
   if (cedula.length !== 10) {
@@ -54,9 +59,6 @@ export default function isCedula(cedula: string): boolean {
     return false;
   }
 
-  if (validatorDigit == lastDigit) {
-    return true;
-  }
-
-  return false;
+  // Si el dígito verificador es igual al último dígito de la cédula, la cédula es válida
+  return validatorDigit === lastDigit;
 }

src/lib/isRUC.ts

@@ -1,6 +1,12 @@
 import isDigits from "../helpers/isDigits";
 import isCedula from "./isCedula";
 
+/**
+ * Valida un RUC ecuatoriano.
+ *
+ * @param {string} ruc El RUC a validar.
+ * @returns {boolean} Devuelve `true` si el RUC es válido, de lo contrario devuelve `false`.
+ */
 export default function isRUC(ruc: string): boolean {
   // Verificamos que el RUC tenga 13 dígitos
   if (ruc.length !== 13) {

src/lib/isZipCode.ts

@@ -0,0 +1,29 @@
+import isDigits from "../helpers/isDigits";
+
+/**
+ * Valida un código postal ecuatoriano.
+ *
+ * @param {string} zipCode El código postal a validar.
+ * @returns {boolean} Devuelve `true` si el código postal es válido, de lo contrario devuelve `false`.
+ */
+export default function isZipCode(zipCode: string): boolean {
+  // Verificamos que el código postal tenga 6 dígitos
+  if (zipCode.length !== 6) {
+    return false;
+  }
+
+  // Verificamos que todos los caracteres sean dígitos
+  if (!isDigits(zipCode)) {
+    return false;
+  }
+
+  // Extraemos el código de provincia
+  const provinceCode = parseInt(zipCode[0] + zipCode[1], 10);
+
+  // Verificamos que el código de provincia sea válido
+  if (provinceCode < 1 || provinceCode > 24) {
+    return false;
+  }
+
+  return true;
+}

tests/index.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { isCedula, isRUC } from "../src";
+import { isCedula, isRUC, isZipCode } from "../src";
 
 describe("Validador isCedula", () => {
   it("debería retornar true para una cédula válida", () => {
@@ -99,3 +99,37 @@ describe("Validador isRUC", () => {
     expect(isRUC("1710034065000")).toBe(false);
   });
 });
+
+describe("Función isZipCode", () => {
+  it("debería retornar true para un código postal válido", () => {
+    expect(isZipCode("170150")).toBe(true); // Código postal válido de Pichincha
+    expect(isZipCode("090112")).toBe(true); // Código postal válido de Guayas
+    expect(isZipCode("010203")).toBe(true); // Código postal válido de Azuay
+    expect(isZipCode("240205")).toBe(true); // Código postal válido de Santa Elena
+    expect(isZipCode("220202")).toBe(true); // Código postal válido de Orellana
+  });
+
+  it("debería retornar false si el código postal no tiene 6 dígitos", () => {
+    expect(isZipCode("17015")).toBe(false);
+    expect(isZipCode("1701500")).toBe(false);
+    expect(isZipCode("1701")).toBe(false);
+  });
+
+  it("debería retornar false si el código postal contiene caracteres no numéricos", () => {
+    expect(isZipCode("17A150")).toBe(false);
+    expect(isZipCode("17015X")).toBe(false);
+    expect(isZipCode("170-50")).toBe(false);
+    expect(isZipCode("17 150")).toBe(false);
+    expect(isZipCode("17.150")).toBe(false);
+  });
+
+  it("debería retornar false para códigos postales con código de provincia inválido", () => {
+    expect(isZipCode("000150")).toBe(false);
+    expect(isZipCode("250150")).toBe(false);
+    expect(isZipCode("990150")).toBe(false);
+  });
+
+  it("debería retornar false para una cadena vacía", () => {
+    expect(isZipCode("")).toBe(false);
+  });
+});