structure-verifier 0.0.16 → 0.0.17

package/README.md

@@ -1,8 +1,33 @@
-# 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 complejas.
+
+Version actual: 0.0.17
+
+## Contenido
+
+- Caracteristicas
+- Instalacion
+- Inicio rapido
+- Conceptos base
+- API publica
+- Referencia completa de validadores
+- Transformaciones de valores
+- Tipado inferido
+- Manejo de errores
+- Ejemplos avanzados
+- Scripts de desarrollo
+
+## Caracteristicas
+
+- Validadores para number, string, boolean, uuid, date, array, object y any.
+- Soporte para estructuras anidadas con errores por ruta.
+- API fluida por clases y API de fabrica mediante Verifiers.
+- Tipado inferido en compile-time para mantener consistencia del dominio.
+- Personalizacion de mensajes por regla y por validador.
+- Integracion con dayjs (exportado como datetime) para manejo de fechas.
 
 ## Instalacion
 
@@ -15,31 +40,69 @@ 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.UUIDNotNull({ version: 4 }),
+    name: V.StringNotNull({ minLength: 2 }),
+    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,
+    age: "31",
     active: "true",
+    tags: ["admin"],
   });
 
-  // user queda tipado con los tipos inferidos de cada propiedad
   console.log(user);
 } catch (error) {
   if (error instanceof VerificationError) {
-    console.log(error.errors); // mensajes planos
-    console.log(error.errorsObj); // mensajes con key y metadatos
+    console.log(error.message);
+    console.log(error.errors);
+    console.log(error.errorsObj);
   }
 }
 ```
 
+## Conceptos base
+
+### 1) Nullable vs NotNull
+
+- VNumber, VString, VBoolean, VDate, VUUID, VArray y VObject retornan tipo nullable.
+- Sus versiones NotNull retornan el tipo requerido.
+- Tambien puedes promover un validador nullable a requerido con required().
+
+### 2) Reglas comunes
+
+Muchos validadores comparten estas opciones:
+
+- isRequired: fuerza que el valor exista.
+- emptyAsNull: transforma string vacio a null antes de validar.
+- defaultValue: valor por defecto para undefined y, en algunos casos, null.
+- badTypeMessage: reemplaza el mensaje de tipo invalido.
+
+### 3) Mensajes personalizados
+
+Las reglas aceptan mensajes de estas formas:
+
+- String fijo.
+- Funcion callback con el objeto de valores de la regla.
+- Objeto con estructura val + message.
+
+Ejemplo:
+
+```ts
+const age = V.NumberNotNull().min(18, (v) => `Edad minima: ${v.min}`);
+```
+
 ## API publica
 
 Import principal:
@@ -52,116 +115,71 @@ 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 los 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 });
-
-console.log(a.check("hola"));
-console.log(b.check("hola"));
+const nameV = V.StringNotNull({ minLength: 3 });
 ```
 
-## Inferencia de tipos
-
-### InferType
+### Clases directas
 
 ```ts
-import { InferType, Verifiers as V } from "structure-verifier";
-
-const v = V.ObjectNotNull({
-  id: V.UUIDNotNull(),
-  tags: V.ArrayNotNull(V.StringNotNull()),
-});
+import { VStringNotNull } from "structure-verifier";
 
-type User = InferType<typeof v>;
+const nameV = new VStringNotNull({ minLength: 3 });
 ```
 
-### InferFactoryType
+### Callable constructors
 
-Funciona con funciones que retornan un Verifier (por ejemplo, miembros callable de Verifiers).
+En Verifiers puedes usar los miembros como funcion o con new.
 
 ```ts
-import { InferFactoryType, Verifiers as V } from "structure-verifier";
-
-type NullableNumber = InferFactoryType<typeof V.Number>; // number | null
-type RequiredNumber = InferFactoryType<typeof V.NumberNotNull>; // number
+const a = V.NumberNotNull({ min: 1 });
+const b = new V.NumberNotNull({ min: 1 });
 ```
 
-## Manejo de errores
+## Referencia completa de validadores
 
-Cuando una validacion falla se lanza VerificationError.
+### Number y NumberNotNull
 
-```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: "..." }]
-  }
-}
-```
-
-## Opciones comunes
-
-Muchos validadores comparten estas opciones:
-
-- 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.
+Retorno:
 
-Puedes pasar mensajes simples o mensajes dinamicos con estructura:
-
-```ts
-{ val: valorReal, message: (values) => "mensaje" }
-```
-
-## Validadores
-
-### Number / NumberNotNull
-
-```ts
-const n1 = V.Number();
-const n2 = V.NumberNotNull();
-```
+- VNumber: number | null
+- VNumberNotNull: number
 
 Condiciones:
 
@@ -176,18 +194,25 @@ Condiciones:
 - defaultValue
 - badTypeMessage
 
-Notas:
+Comportamiento clave:
 
-- Convierte con Number(data), por lo que acepta strings numericos como "42".
-- "" y NaN fallan.
+- Convierte el valor usando Number(data).
+- Rechaza string vacio y NaN.
 
-### String / StringNotNull
+Ejemplo:
 
 ```ts
-const s1 = V.String();
-const s2 = V.StringNotNull();
+const priceV = V.NumberNotNull().min(0).maxDecimalPlaces(2);
+const price = priceV.check("25.99");
 ```
 
+### String y StringNotNull
+
+Retorno:
+
+- VString: string | null
+- VStringNotNull: string
+
 Condiciones:
 
 - minLength
@@ -203,19 +228,31 @@ Condiciones:
 - defaultValue
 - badTypeMessage
 
-Notas:
+Comportamiento clave:
 
-- En modo no estricto convierte con String(data).
-- En strictMode exige typeof data === "string".
+- En modo normal convierte con String(data).
+- En strictMode exige string real.
 - ignoreCase afecta in y notIn.
 
-### Boolean / BooleanNotNull
+Ejemplo:
 
 ```ts
-const b1 = V.Boolean();
-const b2 = V.BooleanNotNull();
+const roleV = V.StringNotNull()
+  .ignoreCase()
+  .in(["admin", "user", "guest"])
+  .trim()
+  .toLowerCase();
+
+const role = roleV.check(" ADMIN ");
 ```
 
+### Boolean y BooleanNotNull
+
+Retorno:
+
+- VBoolean: boolean | null
+- VBooleanNotNull: boolean
+
 Condiciones:
 
 - strictMode
@@ -224,18 +261,25 @@ Condiciones:
 - defaultValue
 - badTypeMessage
 
-Notas:
+Comportamiento clave:
 
-- En modo no estricto acepta: true, false, 1, 0, "1", "0", "true", "false" (case-insensitive).
-- En strictMode solo acepta boolean real.
+- En modo normal acepta: true, false, 1, 0, "1", "0", "true", "false".
+- En strictMode solo acepta boolean.
 
-### UUID / UUIDNotNull
+Ejemplo:
 
 ```ts
-const u1 = V.UUID();
-const u2 = V.UUIDNotNull();
+const active = V.BooleanNotNull().check("true");
+const strictActive = V.BooleanNotNull().strictMode().check(true);
 ```
 
+### UUID y UUIDNotNull
+
+Retorno:
+
+- VUUID: string | null
+- VUUIDNotNull: string
+
 Condiciones:
 
 - version (1 | 2 | 3 | 4 | 5)
@@ -246,73 +290,68 @@ Condiciones:
 - defaultValue
 - badTypeMessage
 
-Notas:
+Comportamiento clave:
 
-- Devuelve UUID normalizado en minusculas y con guiones.
-- Si allowNoHyphens es false, exige formato 8-4-4-4-12.
+- Normaliza salida a minusculas y formato con guiones.
+- Si allowNoHyphens no esta activo, exige formato 8-4-4-4-12.
 
-### Date / DateNotNull
+Ejemplo:
 
 ```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"),
-});
+const uuidV = V.UUIDNotNull().version(4);
+const id = uuidV.check("550E8400E29B41D4A716446655440000");
 ```
 
+### Date y DateNotNull
+
+Retorno:
+
+- VDate: datetime.Dayjs | null
+- VDateNotNull: datetime.Dayjs
+
 Condiciones:
 
 - format
 - timeZone
-- minDate
 - maxDate
-- default
+- minDate
 - isRequired
 - emptyAsNull
 - defaultValue
 - badTypeMessage
 
-Notas:
+Comportamiento clave:
 
-- Retorna instancias dayjs (re-exportado como datetime).
-- Inputs soportados: number, string, Date y datetime.Dayjs.
-- timeZone por defecto: UTC.
+- Entradas soportadas: number, string, Date y datetime.Dayjs.
+- Si no defines timeZone usa UTC por defecto.
+- Si format no incluye zona horaria, se aplica la zona configurada.
 
-### Any
+Ejemplo:
 
 ```ts
-const anyVal = V.Any();
-```
+import { Verifiers as V, datetime } from "structure-verifier";
 
-Condiciones:
+const dateV = V.DateNotNull()
+  .format("YYYY-MM-DD")
+  .timeZone("America/Mexico_City")
+  .minDate(datetime("2024-01-01"));
 
-- isRequired
-- emptyAsNull
-- defaultValue
-- badTypeMessage
+const d = dateV.check("2025-05-10");
+```
 
-### Array / ArrayNotNull
+### Array y ArrayNotNull
 
 Firma:
 
 ```ts
-const arr1 = V.Array(verifier, conditions?);
-const arr2 = V.ArrayNotNull(verifier, conditions?);
+const tagsV = V.Array(V.StringNotNull(), { minLength: 1 });
+const tagsRequiredV = V.ArrayNotNull(V.StringNotNull(), { minLength: 1 });
 ```
 
-Ejemplo:
+Retorno:
 
-```ts
-const numbers = V.ArrayNotNull(V.NumberNotNull(), {
-  minLength: 1,
-  maxLength: 5,
-});
-```
+- VArray: ReturnType<T["check"]>[] | null
+- VArrayNotNull: ReturnType<T["check"]>[]
 
 Condiciones:
 
@@ -323,36 +362,34 @@ Condiciones:
 - defaultValue
 - badTypeMessage
 
-Notas:
+Comportamiento clave:
 
 - Valida item por item con el verificador interno.
-- En errores anidados utiliza claves como [0], [1].name, etc.
+- En errores anidados agrega rutas como [0], [1].name.
 
-### Object / ObjectNotNull
+### Object y ObjectNotNull
 
 Firma:
 
 ```ts
-const o1 = V.Object(properties, conditions?);
-const o2 = V.ObjectNotNull(properties, conditions?);
-```
-
-Ejemplo:
-
-```ts
-const user = V.ObjectNotNull(
+const userV = V.Object(
   {
-    name: V.StringNotNull({ minLength: 3 }),
-    age: V.NumberNotNull({ min: 18 }),
+    name: V.StringNotNull(),
+    age: V.Number(),
   },
   {
     strictMode: true,
-    ignoreCase: true,
+    ignoreCase: false,
     takeAllValues: false,
   },
 );
 ```
 
+Retorno:
+
+- VObject: objeto tipado | null
+- VObjectNotNull: objeto tipado
+
 Condiciones:
 
 - invalidPropertyMessage
@@ -365,16 +402,106 @@ Condiciones:
 - defaultValue
 - badTypeMessage
 
-Notas:
+Comportamiento clave:
+
+- strictMode rechaza propiedades no declaradas.
+- ignoreCase permite mapear llaves sin distinguir mayusculas.
+- takeAllValues conserva propiedades extra en la salida.
+- conds ejecuta una validacion final con el objeto ya validado.
+
+### Any
+
+Retorno:
+
+- VAny: any | null
+
+Condiciones:
+
+- isRequired
+- emptyAsNull
+- defaultValue
+- badTypeMessage
+
+## Transformaciones de valores
+
+La clase base Verifier incluye transform(mapper), que permite postprocesar la salida validada sin perder la validacion previa.
+
+String y StringNotNull incluyen helpers listos:
+
+- trim
+- trimStart
+- trimEnd
+- toLowerCase
+- toUpperCase
+- removeAccents
+- padStart
+- padEnd
+
+Ejemplo:
+
+```ts
+const usernameV = V.StringNotNull({ minLength: 3 })
+  .trim()
+  .toLowerCase()
+  .removeAccents();
+```
+
+## Tipado inferido
+
+### InferType
+
+```ts
+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>;
+```
+
+### InferFactoryType
+
+```ts
+import { InferFactoryType, Verifiers as V } from "structure-verifier";
+
+type NumberMaybe = InferFactoryType<typeof V.Number>;
+type NumberRequired = InferFactoryType<typeof V.NumberNotNull>;
+```
+
+## Manejo de errores
+
+Cuando una validacion falla se lanza VerificationError.
+
+Propiedades principales:
 
-- 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.
+- message: todos los errores concatenados por punto y coma.
+- errors: arreglo de mensajes planos.
+- errorsObj: arreglo de objetos con key, message y metadatos.
+
+Ejemplo:
+
+```ts
+try {
+  V.ObjectNotNull({
+    name: V.StringNotNull({ minLength: 3 }),
+    tags: V.ArrayNotNull(V.StringNotNull(), { minLength: 1 }),
+  }).check({ name: "Al", tags: [] });
+} catch (error) {
+  if (error instanceof VerificationError) {
+    console.log(error.errors);
+    console.log(error.errorsObj);
+  }
+}
+```
 
 ## datetime (dayjs)
 
-La libreria re-exporta dayjs como datetime con plugins:
+La libreria exporta dayjs como datetime con plugins activados:
 
 - utc
 - timezone
@@ -386,11 +513,58 @@ Ejemplo:
 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
+## Ejemplos avanzados
+
+### Validacion de payload API
+
+```ts
+const createOrderV = V.ObjectNotNull(
+  {
+    customerId: V.UUIDNotNull({ version: 4 }),
+    items: V.ArrayNotNull(
+      V.ObjectNotNull({
+        sku: V.StringNotNull({ minLength: 1 }),
+        quantity: V.NumberNotNull({ min: 1 }),
+      }),
+      { minLength: 1 },
+    ),
+    createdAt: V.DateNotNull().timeZone("UTC"),
+  },
+  {
+    strictMode: true,
+  },
+);
+```
+
+### conds para reglas de negocio
+
+```ts
+const personV = V.ObjectNotNull(
+  {
+    age: V.NumberNotNull({ min: 0 }),
+    hasParentalConsent: V.Boolean(),
+  },
+  {
+    conds: (value) => {
+      if (value.age < 18 && value.hasParentalConsent !== true) {
+        throw new Error("Parental consent is required for minors");
+      }
+    },
+  },
+);
+```
+
+## Scripts de desarrollo
 
 ```bash
 npm test
+npm run dev
 ```
+
+## Licencia
+
+ISC