flit-string-utils/README.md

Funciones utilitarias para strings y validaciones comunes en Colombia.

# flit-string-utils

Utilidades para trabajar con strings y validaciones comunes en Colombia, como validación de placas, correos electrónicos, NIT y tipos de documento.

## 📦 Instalación

```bash
npm install flit-string-utils
```

O con Yarn:

```bash
yarn add flit-string-utils
```

---

## 🧪 Test
```bash
npx tsc test/test.ts --outDir test-dist
```

---

## 🛠️ Uso

### TypeScript

```ts
import { calculateVD, validPlate, validEmail, validDocumentType } from "flit-string-utils";

const vd = calculateVD("900373912"); // → 7
const isPlateValid = validPlate("ABC123"); // → true
const isEmailValid = validEmail("correo@dominio.com"); // → true
const isDocTypeValid = validDocumentType("CC"); // → true
```

### JavaScript (CommonJS)

```js
const { calculateVD, validPlate, validEmail, validDocumentType } = require("flit-string-utils");

const vd = calculateVD("900373912");
const isPlateValid = validPlate("ABC123");
const isEmailValid = validEmail("correo@dominio.com");
const isDocTypeValid = validDocumentType("CC");
```

---

## 📚 Funciones disponibles

### `calculateVD(nit: string | number): number | null`

Calcula el dígito de verificación (DV) de un NIT colombiano.

- **Parámetros:**
  - `nit`: Número del NIT sin el dígito de verificación.
- **Retorna:** `number` entre 0 y 9, o `null` si el NIT es inválido.

**Ejemplo:**

```ts
calculateVD("900373912"); // → 7
```

---

### `validPlate(value?: string): boolean`

Valida si una placa de vehículo es válida en Colombia. Soporta:

- Placas de carro: `ABC123`
- Placas de moto: `ABC12A`
- Maquinaria: `AB123456`
- Remolques: `A12345`
- Motocarros: `123ABC`

**Ejemplo:**

```ts
validPlate("ABC123"); // → true
validPlate("ZZ999ZZ"); // → false
```

---

### `validEmail(value?: string): boolean`

Valida si un string tiene formato de correo electrónico válido.

**Ejemplo:**

```ts
validEmail("ejemplo@correo.com"); // → true
validEmail("sin-arroba"); // → false
```

---

### `validDocumentType(value?: string): boolean`

Valida si el tipo de documento está entre los permitidos:

- `CC` (Cédula de ciudadanía)
- `NIT` (Número de identificación tributaria)
- `CE` (Cédula de extranjería)
- `PA` (Pasaporte)
- `RC` (Registro civil)

**Ejemplo:**

```ts
validDocumentType("CC"); // → true
validDocumentType("TI"); // → false
```

---

## 📝 Licencia

MIT © [Mateo Grisales González](https://github.com/teoGonz)