structure-verifier 0.0.16 → 1.0.0

package/README.md

@@ -1,8 +1,34 @@
-# structure-verifier 0.0.16
+# structure-verifier
 
-Libreria TypeScript para validar estructuras de datos con tipado inferido.
+Libreria de validacion para TypeScript orientada a esquemas declarativos, tipado inferido y errores detallados por ruta.
 
-Permite validar valores simples y estructuras anidadas (objetos y arrays), con errores detallados por ruta (por ejemplo: name, items[0], address.city).
+Ideal para validar payloads de API, formularios, configuraciones y estructuras anidadas.
+
+## Objetivo de esta documentacion
+
+Este README está diseñado para ayudarte a:
+
+- Comprender rápidamente cómo funciona la librería.
+- Integrarla de forma sencilla en un proyecto real.
+- Conocer el contrato público de la API antes de utilizarla en producción.
+- Explorar ejemplos prácticos de validación y tipado.
+- Entender las decisiones de diseño y el enfoque de la librería.
+
+## Tabla de contenido
+
+- [Instalacion](#instalacion)
+- [Inicio rapido](#inicio-rapido)
+- [Conceptos clave](#conceptos-clave)
+- [API publica](#api-publica)
+- [Estilos de uso](#estilos-de-uso)
+- [Validadores disponibles](#validadores-disponibles)
+- [Transformaciones](#transformaciones)
+- [Tipado inferido](#tipado-inferido)
+- [Manejo de errores](#manejo-de-errores)
+- [datetime (dayjs)](#datetime-dayjs)
+- [Buenas practicas para v1.0.0](#buenas-practicas-para-v100)
+- [Scripts de desarrollo](#scripts-de-desarrollo)
+- [Licencia](#licencia)
 
 ## Instalacion
 
@@ -15,34 +41,94 @@ npm install structure-verifier
 ```ts
 import { Verifiers as V, VerificationError } from "structure-verifier";
 
-const userValidator = V.ObjectNotNull({
-  id: V.UUIDNotNull({ version: 4 }),
-  name: V.StringNotNull({ minLength: 2 }),
-  age: V.Number({ min: 0 }),
-  active: V.BooleanNotNull(),
-});
+const userVerifier = V.ObjectNotNull(
+  {
+    id: V.UUID({ version: 4 }).required(),
+    name: V.StringNotNull({ minLength: 2 }).trim(),
+    age: V.Number({ min: 0 }),
+    active: V.BooleanNotNull(),
+    tags: V.ArrayNotNull(V.StringNotNull(), { minLength: 1 }),
+  },
+  {
+    strictMode: true,
+  },
+);
 
 try {
-  const user = userValidator.check({
+  const user = userVerifier.check({
     id: "550e8400-e29b-41d4-a716-446655440000",
-    name: "Ana",
-    age: 31,
+    name: "  Ana  ",
+    age: "31",
     active: "true",
+    tags: ["admin"],
   });
 
-  // user queda tipado con los tipos inferidos de cada propiedad
   console.log(user);
+  // {
+  //   id: "550e8400-e29b-41d4-a716-446655440000",
+  //   name: "Ana",
+  //   age: 31,
+  //   active: true,
+  //   tags: ["admin"]
+  // }
 } catch (error) {
   if (error instanceof VerificationError) {
-    console.log(error.errors); // mensajes planos
-    console.log(error.errorsObj); // mensajes con key y metadatos
+    console.error(error.message);
+    console.error(error.errors);
+    console.error(error.errorsObj);
   }
 }
 ```
 
+## Conceptos clave
+
+### 1) Nullable vs NotNull
+
+- `VNumber`, `VString`, `VBoolean`, `VDate`, `VUUID`, `VArray`, `VObject` y `VAny` pueden devolver `null`.
+- Las variantes `NotNull` devuelven siempre tipo requerido.
+- En validadores nullable puedes promover a requerido con `.required()`.
+
+### 2) Inmutabilidad de reglas
+
+Cada metodo de regla devuelve una nueva instancia del validador.
+
+```ts
+const base = V.StringNotNull();
+const withMin = base.minLength(3);
+
+// base no cambia
+```
+
+### 3) Reglas transversales
+
+Muchos validadores comparten estas opciones:
+
+- `isRequired`: fuerza existencia del valor.
+- `emptyAsNull`: transforma `""` a `null` antes de validar.
+- `defaultValue`: valor por defecto para `undefined` y ciertos casos de `null`.
+- `badTypeMessage`: reemplaza mensaje de tipo invalido.
+
+### 4) Mensajes personalizados
+
+Puedes pasar mensajes como:
+
+- `string` fijo.
+- callback usando el valor de la regla.
+- objeto `{ val, message }`.
+
+```ts
+const age = V.NumberNotNull().min(18, (v) => `Edad minima: ${v.min}`);
+```
+
 ## API publica
 
-Import principal:
+Import principal recomendado:
+
+```ts
+import { Verifiers as V } from "structure-verifier";
+```
+
+Import completo disponible:
 
 ```ts
 import {
@@ -52,345 +138,336 @@ import {
   InferType,
   InferFactoryType,
   VAny,
-  VAnyConditions,
   VArray,
   VArrayNotNull,
-  VArrayConditions,
   VBoolean,
   VBooleanNotNull,
-  VBooleanConditions,
   VDate,
   VDateNotNull,
-  VDateConditions,
   VNumber,
   VNumberNotNull,
-  VNumberConditions,
   VObject,
   VObjectNotNull,
-  VObjectConditions,
-  VObjectConditionsNotNull,
   VString,
   VStringNotNull,
-  VStringConditions,
   VUUID,
   VUUIDNotNull,
-  VUUIDConditions,
   datetime,
 } from "structure-verifier";
 ```
 
-## Formas de uso
+Tambien se exportan estos tipos de condiciones:
 
-La libreria soporta dos estilos:
+- `VAnyConditions`
+- `VArrayConditions`
+- `VBooleanConditions`
+- `VDateConditions`
+- `VNumberConditions`
+- `VObjectConditions`
+- `VObjectConditionsNotNull`
+- `VStringConditions`
+- `VUUIDConditions`
 
-1. API recomendada con Verifiers (callable, con o sin new)
-2. Clases directas (new VString(...), new VObject(...), etc.)
+## Estilos de uso
 
-Ejemplo con Verifiers:
+### API de fabrica (recomendada)
 
 ```ts
 import { Verifiers as V } from "structure-verifier";
 
-const a = V.StringNotNull({ minLength: 3 });
-const b = new V.StringNotNull({ minLength: 3 });
+const nameV = V.StringNotNull({ minLength: 3 });
+```
 
-console.log(a.check("hola"));
-console.log(b.check("hola"));
+### Clases directas
+
+```ts
+import { VStringNotNull } from "structure-verifier";
+
+const nameV = new VStringNotNull({ minLength: 3 });
 ```
 
-## Inferencia de tipos
+### Callable constructors en `Verifiers`
 
-### InferType
+Los miembros de `Verifiers` aceptan llamada normal o `new`.
 
 ```ts
-import { InferType, Verifiers as V } from "structure-verifier";
+const a = V.NumberNotNull({ min: 1 });
+const b = new V.NumberNotNull({ min: 1 });
+```
 
-const v = V.ObjectNotNull({
-  id: V.UUIDNotNull(),
-  tags: V.ArrayNotNull(V.StringNotNull()),
-});
+## Validadores disponibles
 
-type User = InferType<typeof v>;
-```
+### Number / NumberNotNull
 
-### InferFactoryType
+Salida:
 
-Funciona con funciones que retornan un Verifier (por ejemplo, miembros callable de Verifiers).
+- `VNumber`: `number | null`
+- `VNumberNotNull`: `number`
 
-```ts
-import { InferFactoryType, Verifiers as V } from "structure-verifier";
+Reglas:
 
-type NullableNumber = InferFactoryType<typeof V.Number>; // number | null
-type RequiredNumber = InferFactoryType<typeof V.NumberNotNull>; // number
-```
+- `min`
+- `max`
+- `in`
+- `notIn`
+- `maxDecimalPlaces`
+- `minDecimalPlaces`
+- reglas transversales (`isRequired`, `emptyAsNull`, `defaultValue`, `badTypeMessage`)
 
-## Manejo de errores
+Comportamiento importante:
 
-Cuando una validacion falla se lanza VerificationError.
+- Convierte con `Number(data)`.
+- Rechaza `""` y valores `NaN`.
 
-```ts
-try {
-  V.NumberNotNull({ min: 10 }).check(5);
-} catch (error) {
-  if (error instanceof VerificationError) {
-    console.log(error.errors); // ["debe ser mayor o igual a 10"]
-    console.log(error.errorsObj); // [{ key: "", message: "..." }]
-  }
-}
-```
+### String / StringNotNull
 
-## Opciones comunes
+Salida:
 
-Muchos validadores comparten estas opciones:
+- `VString`: `string | null`
+- `VStringNotNull`: `string`
 
-- isRequired: fuerza que el valor exista.
-- emptyAsNull: si llega string vacio, se convierte a null antes de validar.
-- defaultValue: valor por defecto si llega undefined (y en algunos flujos tambien null).
-- badTypeMessage: mensaje personalizado de tipo invalido.
+Reglas:
 
-Puedes pasar mensajes simples o mensajes dinamicos con estructura:
+- `minLength`
+- `maxLength`
+- `regex`
+- `notRegex`
+- `in`
+- `notIn`
+- `strictMode`
+- `ignoreCase`
+- reglas transversales
 
-```ts
-{ val: valorReal, message: (values) => "mensaje" }
-```
+Comportamiento importante:
 
-## Validadores
+- En modo normal convierte con `String(data)`.
+- En `strictMode` exige tipo string real.
+- `ignoreCase` aplica a reglas `in` y `notIn`.
 
-### Number / NumberNotNull
+### Boolean / BooleanNotNull
 
-```ts
-const n1 = V.Number();
-const n2 = V.NumberNotNull();
-```
+Salida:
 
-Condiciones:
+- `VBoolean`: `boolean | null`
+- `VBooleanNotNull`: `boolean`
 
-- min
-- max
-- in
-- notIn
-- maxDecimalPlaces
-- minDecimalPlaces
-- isRequired
-- emptyAsNull
-- defaultValue
-- badTypeMessage
+Reglas:
 
-Notas:
+- `strictMode`
+- reglas transversales
 
-- Convierte con Number(data), por lo que acepta strings numericos como "42".
-- "" y NaN fallan.
+Comportamiento importante:
 
-### String / StringNotNull
+- Modo normal acepta: `true`, `false`, `1`, `0`, `"1"`, `"0"`, `"true"`, `"false"`.
+- `strictMode` acepta solo boolean real.
 
-```ts
-const s1 = V.String();
-const s2 = V.StringNotNull();
-```
+### UUID / UUIDNotNull
 
-Condiciones:
+Salida:
 
-- minLength
-- maxLength
-- regex
-- notRegex
-- in
-- notIn
-- strictMode
-- ignoreCase
-- isRequired
-- emptyAsNull
-- defaultValue
-- badTypeMessage
+- `VUUID`: `string | null`
+- `VUUIDNotNull`: `string`
 
-Notas:
+Reglas:
 
-- En modo no estricto convierte con String(data).
-- En strictMode exige typeof data === "string".
-- ignoreCase afecta in y notIn.
+- `version` (`1 | 2 | 3 | 4 | 5`)
+- `allowNoHyphens`
+- `strictMode`
+- reglas transversales
 
-### Boolean / BooleanNotNull
+Comportamiento importante:
 
-```ts
-const b1 = V.Boolean();
-const b2 = V.BooleanNotNull();
-```
+- Normaliza salida a minusculas con formato `8-4-4-4-12`.
+- Si `allowNoHyphens` es `false`, exige UUID con guiones.
 
-Condiciones:
+### Date / DateNotNull
 
-- strictMode
-- isRequired
-- emptyAsNull
-- defaultValue
-- badTypeMessage
+Salida:
 
-Notas:
+- `VDate`: `datetime.Dayjs | null`
+- `VDateNotNull`: `datetime.Dayjs`
 
-- En modo no estricto acepta: true, false, 1, 0, "1", "0", "true", "false" (case-insensitive).
-- En strictMode solo acepta boolean real.
+Reglas:
 
-### UUID / UUIDNotNull
+- `format`
+- `timeZone`
+- `maxDate`
+- `minDate`
+- reglas transversales
 
-```ts
-const u1 = V.UUID();
-const u2 = V.UUIDNotNull();
-```
+Comportamiento importante:
 
-Condiciones:
+- Soporta entrada `number`, `string`, `Date` y `datetime.Dayjs`.
+- Si no defines `timeZone`, usa `UTC`.
+- Si el `format` no incluye zona horaria, aplica la zona configurada.
 
-- version (1 | 2 | 3 | 4 | 5)
-- allowNoHyphens
-- strictMode
-- isRequired
-- emptyAsNull
-- defaultValue
-- badTypeMessage
+### Array / ArrayNotNull
 
-Notas:
+Salida:
 
-- Devuelve UUID normalizado en minusculas y con guiones.
-- Si allowNoHyphens es false, exige formato 8-4-4-4-12.
+- `VArray`: `ReturnType<T["check"]>[] | null`
+- `VArrayNotNull`: `ReturnType<T["check"]>[]`
 
-### Date / DateNotNull
+Reglas:
 
-```ts
-import { Verifiers as V, datetime } from "structure-verifier";
-
-const d1 = V.Date();
-const d2 = V.DateNotNull({
-  format: "YYYY-MM-DD",
-  timeZone: "UTC",
-  minDate: datetime("2024-01-01"),
-  maxDate: datetime("2026-12-31"),
-});
-```
+- `minLength`
+- `maxLength`
+- reglas transversales
+
+Comportamiento importante:
+
+- Valida item por item con el verificador interno.
+- En errores anidados agrega rutas como `[0]`, `[1].name`, etc.
+
+### Object / ObjectNotNull
+
+Salida:
+
+- `VObject`: objeto tipado o `null`
+- `VObjectNotNull`: objeto tipado
 
-Condiciones:
+Reglas:
 
-- format
-- timeZone
-- minDate
-- maxDate
-- default
-- isRequired
-- emptyAsNull
-- defaultValue
-- badTypeMessage
+- `invalidPropertyMessage`
+- `strictMode`
+- `ignoreCase`
+- `takeAllValues`
+- `conds`
+- reglas transversales
 
-Notas:
+Comportamiento importante:
 
-- Retorna instancias dayjs (re-exportado como datetime).
-- Inputs soportados: number, string, Date y datetime.Dayjs.
-- timeZone por defecto: UTC.
+- `strictMode`: rechaza propiedades no declaradas.
+- `ignoreCase`: permite mapear llaves sin distinguir mayusculas/minusculas.
+- `takeAllValues`: conserva propiedades extra en la salida.
+- `conds`: ejecuta validacion de negocio final sobre el objeto ya validado.
 
 ### Any
 
-```ts
-const anyVal = V.Any();
-```
+Salida:
 
-Condiciones:
+- `VAny`: `any | null`
 
-- isRequired
-- emptyAsNull
-- defaultValue
-- badTypeMessage
+Reglas:
 
-### Array / ArrayNotNull
+- reglas transversales
+
+## Transformaciones
 
-Firma:
+La clase base `Verifier` incluye `transform(mapper)` para postprocesar salida validada.
+
+`VString` y `VStringNotNull` incluyen helpers:
+
+- `trim`
+- `trimStart`
+- `trimEnd`
+- `toLowerCase`
+- `toUpperCase`
+- `removeAccents`
+- `padStart`
+- `padEnd`
 
 ```ts
-const arr1 = V.Array(verifier, conditions?);
-const arr2 = V.ArrayNotNull(verifier, conditions?);
+const usernameV = V.StringNotNull({ minLength: 3 })
+  .trim()
+  .toLowerCase()
+  .removeAccents();
 ```
 
-Ejemplo:
+## Tipado inferido
+
+### InferType
 
 ```ts
-const numbers = V.ArrayNotNull(V.NumberNotNull(), {
-  minLength: 1,
-  maxLength: 5,
+import { InferType, Verifiers as V } from "structure-verifier";
+
+const schema = V.ObjectNotNull({
+  id: V.UUIDNotNull(),
+  profile: V.ObjectNotNull({
+    name: V.StringNotNull(),
+    age: V.Number(),
+  }),
 });
+
+type User = InferType<typeof schema>;
 ```
 
-Condiciones:
+### InferFactoryType
 
-- minLength
-- maxLength
-- isRequired
-- emptyAsNull
-- defaultValue
-- badTypeMessage
+```ts
+import { InferFactoryType, Verifiers as V } from "structure-verifier";
 
-Notas:
+type NumberMaybe = InferFactoryType<typeof V.Number>;
+type NumberRequired = InferFactoryType<typeof V.NumberNotNull>;
+```
 
-- Valida item por item con el verificador interno.
-- En errores anidados utiliza claves como [0], [1].name, etc.
+## Manejo de errores
 
-### Object / ObjectNotNull
+Cuando una validacion falla se lanza `VerificationError`.
 
-Firma:
+Campos principales:
 
-```ts
-const o1 = V.Object(properties, conditions?);
-const o2 = V.ObjectNotNull(properties, conditions?);
-```
+- `message`: string unico con errores concatenados por `;`.
+- `errors`: arreglo de mensajes planos.
+- `errorsObj`: arreglo con `key`, `message` y metadatos.
 
 Ejemplo:
 
 ```ts
-const user = V.ObjectNotNull(
-  {
-    name: V.StringNotNull({ minLength: 3 }),
-    age: V.NumberNotNull({ min: 18 }),
-  },
-  {
-    strictMode: true,
-    ignoreCase: true,
-    takeAllValues: false,
-  },
-);
-```
-
-Condiciones:
+import { Verifiers as V, VerificationError } from "structure-verifier";
 
-- invalidPropertyMessage
-- strictMode
-- ignoreCase
-- takeAllValues
-- conds
-- isRequired
-- emptyAsNull
-- defaultValue
-- badTypeMessage
+try {
+  V.ObjectNotNull(
+    {
+      name: V.StringNotNull({ minLength: 3 }),
+      tags: V.ArrayNotNull(V.StringNotNull(), { minLength: 1 }),
+    },
+    { strictMode: true },
+  ).check({ name: "Al", tags: [], extra: true });
+} catch (error) {
+  if (error instanceof VerificationError) {
+    console.log(error.message);
+    console.log(error.errors);
+    console.log(error.errorsObj);
+  }
+}
+```
 
-Notas:
+Posible salida en `errorsObj`:
 
-- strictMode rechaza propiedades extra.
-- ignoreCase permite mapear propiedades sin importar mayusculas/minusculas.
-- takeAllValues conserva propiedades no definidas en el esquema.
-- conds ejecuta una validacion adicional al final con el objeto ya tipado.
+```ts
+[
+  { key: "name", message: "debe tener una longitud minima de 3" },
+  { key: "tags", message: "debe tener al menos 1 elementos" },
+  { key: "extra", message: "no es una propiedad valida" },
+];
+```
 
 ## datetime (dayjs)
 
-La libreria re-exporta dayjs como datetime con plugins:
+La libreria exporta `dayjs` como `datetime` con plugins habilitados:
 
-- utc
-- timezone
-- customParseFormat
-
-Ejemplo:
+- `utc`
+- `timezone`
+- `customParseFormat`
 
 ```ts
 import { datetime } from "structure-verifier";
 
 const now = datetime();
-console.log(now.tz("UTC").format());
+const utc = now.tz("UTC").format();
+console.log(utc);
 ```
 
-## Ejecutar tests del proyecto
+## Buenas practicas para v1.0.0
 
-```bash
-npm test
-```
+- Define siempre `strictMode: true` en payloads de entrada externa.
+- Usa variantes `NotNull` en campos de negocio obligatorios.
+- Agrega reglas semanticas con `conds` para validaciones cruzadas.
+- Encadena normalizaciones (`trim`, `toLowerCase`, etc.) para salida consistente.
+- Centraliza mensajes custom cuando quieras UX de errores uniforme.
+- Cubre cada esquema critico con pruebas de casos validos e invalidos.
+
+## Licencia
+
+ISC