structure-verifier 0.0.17 → 1.0.0

package/README.md

@@ -2,32 +2,33 @@
 
 Libreria de validacion para TypeScript orientada a esquemas declarativos, tipado inferido y errores detallados por ruta.
 
-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.
+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
 
@@ -42,11 +43,11 @@ import { Verifiers as V, VerificationError } from "structure-verifier";
 
 const userVerifier = V.ObjectNotNull(
   {
-    id: V.UUIDNotNull({ version: 4 }),
-    name: V.StringNotNull({ minLength: 2 }),
+    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),
+    tags: V.ArrayNotNull(V.StringNotNull(), { minLength: 1 }),
   },
   {
     strictMode: true,
@@ -56,48 +57,64 @@ const userVerifier = V.ObjectNotNull(
 try {
   const user = userVerifier.check({
     id: "550e8400-e29b-41d4-a716-446655440000",
-    name: "Ana",
+    name: "  Ana  ",
     age: "31",
     active: "true",
     tags: ["admin"],
   });
 
   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.message);
-    console.log(error.errors);
-    console.log(error.errorsObj);
+    console.error(error.message);
+    console.error(error.errors);
+    console.error(error.errorsObj);
   }
 }
 ```
 
-## Conceptos base
+## Conceptos clave
 
 ### 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().
+- `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) Reglas comunes
+### 2) Inmutabilidad de reglas
 
-Muchos validadores comparten estas opciones:
+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
 
-- 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.
+Muchos validadores comparten estas opciones:
 
-### 3) Mensajes personalizados
+- `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.
 
-Las reglas aceptan mensajes de estas formas:
+### 4) Mensajes personalizados
 
-- String fijo.
-- Funcion callback con el objeto de valores de la regla.
-- Objeto con estructura val + message.
+Puedes pasar mensajes como:
 
-Ejemplo:
+- `string` fijo.
+- callback usando el valor de la regla.
+- objeto `{ val, message }`.
 
 ```ts
 const age = V.NumberNotNull().min(18, (v) => `Edad minima: ${v.min}`);
@@ -105,7 +122,13 @@ 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 {
@@ -133,17 +156,17 @@ import {
 } from "structure-verifier";
 ```
 
-Tambien se exportan los tipos de condiciones:
+Tambien se exportan estos tipos de condiciones:
 
-- VAnyConditions
-- VArrayConditions
-- VBooleanConditions
-- VDateConditions
-- VNumberConditions
-- VObjectConditions
-- VObjectConditionsNotNull
-- VStringConditions
-- VUUIDConditions
+- `VAnyConditions`
+- `VArrayConditions`
+- `VBooleanConditions`
+- `VDateConditions`
+- `VNumberConditions`
+- `VObjectConditions`
+- `VObjectConditionsNotNull`
+- `VStringConditions`
+- `VUUIDConditions`
 
 ## Estilos de uso
 
@@ -163,281 +186,186 @@ import { VStringNotNull } from "structure-verifier";
 const nameV = new VStringNotNull({ minLength: 3 });
 ```
 
-### Callable constructors
+### Callable constructors en `Verifiers`
 
-En Verifiers puedes usar los miembros como funcion o con new.
+Los miembros de `Verifiers` aceptan llamada normal o `new`.
 
 ```ts
 const a = V.NumberNotNull({ min: 1 });
 const b = new V.NumberNotNull({ min: 1 });
 ```
 
-## Referencia completa de validadores
-
-### Number y NumberNotNull
-
-Retorno:
-
-- VNumber: number | null
-- VNumberNotNull: number
-
-Condiciones:
-
-- min
-- max
-- in
-- notIn
-- maxDecimalPlaces
-- minDecimalPlaces
-- isRequired
-- emptyAsNull
-- defaultValue
-- badTypeMessage
-
-Comportamiento clave:
-
-- Convierte el valor usando Number(data).
-- Rechaza string vacio y NaN.
-
-Ejemplo:
-
-```ts
-const priceV = V.NumberNotNull().min(0).maxDecimalPlaces(2);
-const price = priceV.check("25.99");
-```
-
-### String y StringNotNull
-
-Retorno:
+## Validadores disponibles
 
-- VString: string | null
-- VStringNotNull: string
+### Number / NumberNotNull
 
-Condiciones:
+Salida:
 
-- minLength
-- maxLength
-- regex
-- notRegex
-- in
-- notIn
-- strictMode
-- ignoreCase
-- isRequired
-- emptyAsNull
-- defaultValue
-- badTypeMessage
+- `VNumber`: `number | null`
+- `VNumberNotNull`: `number`
 
-Comportamiento clave:
+Reglas:
 
-- En modo normal convierte con String(data).
-- En strictMode exige string real.
-- ignoreCase afecta in y notIn.
+- `min`
+- `max`
+- `in`
+- `notIn`
+- `maxDecimalPlaces`
+- `minDecimalPlaces`
+- reglas transversales (`isRequired`, `emptyAsNull`, `defaultValue`, `badTypeMessage`)
 
-Ejemplo:
-
-```ts
-const roleV = V.StringNotNull()
-  .ignoreCase()
-  .in(["admin", "user", "guest"])
-  .trim()
-  .toLowerCase();
+Comportamiento importante:
 
-const role = roleV.check(" ADMIN ");
-```
+- Convierte con `Number(data)`.
+- Rechaza `""` y valores `NaN`.
 
-### Boolean y BooleanNotNull
+### String / StringNotNull
 
-Retorno:
+Salida:
 
-- VBoolean: boolean | null
-- VBooleanNotNull: boolean
+- `VString`: `string | null`
+- `VStringNotNull`: `string`
 
-Condiciones:
+Reglas:
 
-- strictMode
-- isRequired
-- emptyAsNull
-- defaultValue
-- badTypeMessage
+- `minLength`
+- `maxLength`
+- `regex`
+- `notRegex`
+- `in`
+- `notIn`
+- `strictMode`
+- `ignoreCase`
+- reglas transversales
 
-Comportamiento clave:
+Comportamiento importante:
 
-- En modo normal acepta: true, false, 1, 0, "1", "0", "true", "false".
-- En strictMode solo acepta boolean.
+- En modo normal convierte con `String(data)`.
+- En `strictMode` exige tipo string real.
+- `ignoreCase` aplica a reglas `in` y `notIn`.
 
-Ejemplo:
+### Boolean / BooleanNotNull
 
-```ts
-const active = V.BooleanNotNull().check("true");
-const strictActive = V.BooleanNotNull().strictMode().check(true);
-```
+Salida:
 
-### UUID y UUIDNotNull
+- `VBoolean`: `boolean | null`
+- `VBooleanNotNull`: `boolean`
 
-Retorno:
+Reglas:
 
-- VUUID: string | null
-- VUUIDNotNull: string
+- `strictMode`
+- reglas transversales
 
-Condiciones:
+Comportamiento importante:
 
-- version (1 | 2 | 3 | 4 | 5)
-- allowNoHyphens
-- strictMode
-- isRequired
-- emptyAsNull
-- defaultValue
-- badTypeMessage
+- Modo normal acepta: `true`, `false`, `1`, `0`, `"1"`, `"0"`, `"true"`, `"false"`.
+- `strictMode` acepta solo boolean real.
 
-Comportamiento clave:
+### UUID / UUIDNotNull
 
-- Normaliza salida a minusculas y formato con guiones.
-- Si allowNoHyphens no esta activo, exige formato 8-4-4-4-12.
+Salida:
 
-Ejemplo:
+- `VUUID`: `string | null`
+- `VUUIDNotNull`: `string`
 
-```ts
-const uuidV = V.UUIDNotNull().version(4);
-const id = uuidV.check("550E8400E29B41D4A716446655440000");
-```
+Reglas:
 
-### Date y DateNotNull
+- `version` (`1 | 2 | 3 | 4 | 5`)
+- `allowNoHyphens`
+- `strictMode`
+- reglas transversales
 
-Retorno:
+Comportamiento importante:
 
-- VDate: datetime.Dayjs | null
-- VDateNotNull: datetime.Dayjs
+- Normaliza salida a minusculas con formato `8-4-4-4-12`.
+- Si `allowNoHyphens` es `false`, exige UUID con guiones.
 
-Condiciones:
+### Date / DateNotNull
 
-- format
-- timeZone
-- maxDate
-- minDate
-- isRequired
-- emptyAsNull
-- defaultValue
-- badTypeMessage
+Salida:
 
-Comportamiento clave:
+- `VDate`: `datetime.Dayjs | null`
+- `VDateNotNull`: `datetime.Dayjs`
 
-- 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.
+Reglas:
 
-Ejemplo:
+- `format`
+- `timeZone`
+- `maxDate`
+- `minDate`
+- reglas transversales
 
-```ts
-import { Verifiers as V, datetime } from "structure-verifier";
+Comportamiento importante:
 
-const dateV = V.DateNotNull()
-  .format("YYYY-MM-DD")
-  .timeZone("America/Mexico_City")
-  .minDate(datetime("2024-01-01"));
+- 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.
 
-const d = dateV.check("2025-05-10");
-```
+### Array / ArrayNotNull
 
-### Array y ArrayNotNull
+Salida:
 
-Firma:
+- `VArray`: `ReturnType<T["check"]>[] | null`
+- `VArrayNotNull`: `ReturnType<T["check"]>[]`
 
-```ts
-const tagsV = V.Array(V.StringNotNull(), { minLength: 1 });
-const tagsRequiredV = V.ArrayNotNull(V.StringNotNull(), { minLength: 1 });
-```
+Reglas:
 
-Retorno:
+- `minLength`
+- `maxLength`
+- reglas transversales
 
-- VArray: ReturnType<T["check"]>[] | null
-- VArrayNotNull: ReturnType<T["check"]>[]
-
-Condiciones:
-
-- minLength
-- maxLength
-- isRequired
-- emptyAsNull
-- defaultValue
-- badTypeMessage
-
-Comportamiento clave:
+Comportamiento importante:
 
 - Valida item por item con el verificador interno.
-- En errores anidados agrega rutas como [0], [1].name.
-
-### Object y ObjectNotNull
+- En errores anidados agrega rutas como `[0]`, `[1].name`, etc.
 
-Firma:
-
-```ts
-const userV = V.Object(
-  {
-    name: V.StringNotNull(),
-    age: V.Number(),
-  },
-  {
-    strictMode: true,
-    ignoreCase: false,
-    takeAllValues: false,
-  },
-);
-```
+### Object / ObjectNotNull
 
-Retorno:
+Salida:
 
-- VObject: objeto tipado | null
-- VObjectNotNull: objeto tipado
+- `VObject`: objeto tipado o `null`
+- `VObjectNotNull`: objeto tipado
 
-Condiciones:
+Reglas:
 
-- invalidPropertyMessage
-- strictMode
-- ignoreCase
-- takeAllValues
-- conds
-- isRequired
-- emptyAsNull
-- defaultValue
-- badTypeMessage
+- `invalidPropertyMessage`
+- `strictMode`
+- `ignoreCase`
+- `takeAllValues`
+- `conds`
+- reglas transversales
 
-Comportamiento clave:
+Comportamiento importante:
 
-- 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.
+- `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
 
-Retorno:
+Salida:
 
-- VAny: any | null
+- `VAny`: `any | null`
 
-Condiciones:
+Reglas:
 
-- isRequired
-- emptyAsNull
-- defaultValue
-- badTypeMessage
+- reglas transversales
 
-## Transformaciones de valores
+## Transformaciones
 
-La clase base Verifier incluye transform(mapper), que permite postprocesar la salida validada sin perder la validacion previa.
+La clase base `Verifier` incluye `transform(mapper)` para postprocesar salida validada.
 
-String y StringNotNull incluyen helpers listos:
+`VString` y `VStringNotNull` incluyen helpers:
 
-- trim
-- trimStart
-- trimEnd
-- toLowerCase
-- toUpperCase
-- removeAccents
-- padStart
-- padEnd
-
-Ejemplo:
+- `trim`
+- `trimStart`
+- `trimEnd`
+- `toLowerCase`
+- `toUpperCase`
+- `removeAccents`
+- `padStart`
+- `padEnd`
 
 ```ts
 const usernameV = V.StringNotNull({ minLength: 3 })
@@ -475,39 +403,53 @@ type NumberRequired = InferFactoryType<typeof V.NumberNotNull>;
 
 ## Manejo de errores
 
-Cuando una validacion falla se lanza VerificationError.
+Cuando una validacion falla se lanza `VerificationError`.
 
-Propiedades principales:
+Campos principales:
 
-- message: todos los errores concatenados por punto y coma.
-- errors: arreglo de mensajes planos.
-- errorsObj: arreglo de objetos con key, message y metadatos.
+- `message`: string unico con errores concatenados por `;`.
+- `errors`: arreglo de mensajes planos.
+- `errorsObj`: arreglo con `key`, `message` y metadatos.
 
 Ejemplo:
 
 ```ts
+import { Verifiers as V, VerificationError } from "structure-verifier";
+
 try {
-  V.ObjectNotNull({
-    name: V.StringNotNull({ minLength: 3 }),
-    tags: V.ArrayNotNull(V.StringNotNull(), { minLength: 1 }),
-  }).check({ name: "Al", tags: [] });
+  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);
   }
 }
 ```
 
-## datetime (dayjs)
+Posible salida en `errorsObj`:
 
-La libreria exporta dayjs como datetime con plugins activados:
+```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" },
+];
+```
 
-- utc
-- timezone
-- customParseFormat
+## datetime (dayjs)
 
-Ejemplo:
+La libreria exporta `dayjs` como `datetime` con plugins habilitados:
+
+- `utc`
+- `timezone`
+- `customParseFormat`
 
 ```ts
 import { datetime } from "structure-verifier";
@@ -517,53 +459,14 @@ const utc = now.tz("UTC").format();
 console.log(utc);
 ```
 
-## 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
+## Buenas practicas para v1.0.0
 
-```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
-```
+- 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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "structure-verifier",
-  "version": "0.0.17",
+  "version": "1.0.0",
   "description": "",
   "main": "dist/index.js",
   "repository": {