q-type 0.1.2

package/README.md

@@ -0,0 +1,312 @@
+# Qtype
+
+> Librería para parsear y serializar protocolos de mensajería basados en delimitadores (pipes, punto y coma, clave:valor). Inferencia de tipos TypeScript completa desde la definición del esquema.
+
+---
+
+## Descripción
+
+Qtype es una librería de schemas runtime que permite definir la estructura de un mensaje posicional (como los usados en protocolos bancarios, fiscales o de middleware) y obtener automáticamente:
+
+- **Parseo tipado**: de string crudo a objetos TypeScript con tipos inferidos.
+- **Serialización**: de objetos tipados de vuelta al formato wire.
+- **Errores descriptivos**: con ruta, clave y valor crudo para depuración.
+
+Está pensada para mensajes delimitados por `|` (pipes) donde cada campo ocupa una posición fija, con soporte para sub-estructuras dentro de un mismo segmento (arreglos, objetos clave:valor, tuplas).
+
+---
+
+## Tecnologías
+
+| Tecnología | Versión | Propósito                           |
+| ---------- | ------- | ----------------------------------- |
+| TypeScript | 7.x     | Lenguaje, inferencia de tipos       |
+| Bun        | 1.3+    | Runtime, test runner y bundler      |
+| bunup      | 0.16    | Empaquetado ESM/CJS + declaraciones |
+
+La librería **no tiene dependencias de runtime**. Solo requiere TypeScript como peerDependency para la inferencia de tipos.
+
+---
+
+## Instalación
+
+```bash
+bun add qtype
+```
+
+O con npm/pnpm:
+
+```bash
+npm install qtype
+pnpm add qtype
+```
+
+---
+
+## Uso rápido
+
+```ts
+import { q, type Static } from "qtype";
+
+const Mensaje = q.Schema({
+  tipo: q.String(),
+  subTipo: q.String(),
+  status: q.Integer(),
+  cuenta: q.String(),
+});
+
+type Mensaje = Static<typeof Mensaje>;
+// { tipo: string; subTipo: string; status: number; cuenta: string }
+
+const parsed = Mensaje.parse("105|00|10|412345678912345678");
+// { tipo: "105", subTipo: "00", status: 10, cuenta: "412345678912345678" }
+
+Mensaje.serialize(parsed);
+// "105|00|10|412345678912345678"
+```
+
+---
+
+## API de referencia
+
+Toda la API pública se accede mediante el namespace `q`. Cada factory retorna una instancia de `QType<T>` que expone los métodos `parse`, `safeParse` y `serialize`.
+
+### Primitivos
+
+| Factory              | Tipo TS          | Descripción                                                                        |
+| -------------------- | ---------------- | ---------------------------------------------------------------------------------- |
+| `q.String()`         | `string`         | String requerido. Vacío lanza error.                                               |
+| `q.Number()`         | `number`         | Número de punto flotante.                                                          |
+| `q.Integer(radix?)`  | `number`         | Entero en base `radix` (por defecto 10).                                           |
+| `q.Boolean(truthy?)` | `boolean`        | `true` si el valor está en la lista truthy. Por defecto `["1", "true", "Y", "y"]`. |
+| `q.Date(format?)`    | `Date`           | Fecha en formato `"iso"` (por defecto) o `"yyyyMMdd"`.                             |
+| `q.Literal(value)`   | `typeof value`   | Solo acepta el valor literal exacto.                                               |
+| `q.Enum(values)`     | `values[number]` | Restringe a un conjunto finito de strings.                                         |
+
+```ts
+q.String(); // string
+q.Number(); // number
+q.Integer(16); // entero hexadecimal
+q.Boolean(["S", "s"]); // true para "S" o "s"
+q.Date("yyyyMMdd"); // formato compacto de 8 dígitos
+q.Literal("00"); // solo "00"
+q.Enum(["alta", "baja"]); // "alta" | "baja"
+```
+
+### Combinadores
+
+| Factory                               | Tipo TS          | Descripción                                 |
+| ------------------------------------- | ---------------- | ------------------------------------------- |
+| `q.Optional(schema)`                  | `T \| undefined` | Vacío produce `undefined`.                  |
+| `q.Nullable(schema)`                  | `T \| null`      | Vacío produce `null`.                       |
+| `q.Default(schema, value)`            | `T`              | Vacío produce `value`. No ensancha el tipo. |
+| `q.Transform(schema, decode, encode)` | `B`              | Transforma wire ↔ app bidireccionalmente.   |
+| `q.at(index, schema)`                 | `T`              | Asigna posición explícita en un `q.Schema`. |
+
+```ts
+q.Optional(q.String()); // string | undefined
+q.Nullable(q.Integer()); // number | null
+q.Default(q.String(), "N/A"); // string (nunca undefined)
+q.Transform(
+  q.Number(),
+  (cents) => cents / 100, // wire → app
+  (dollars) => dollars * 100, // app → wire
+);
+q.at(3, q.String()); // ocupa la posición 3
+```
+
+### Compuestos
+
+Estos esquemas operan sobre un **mismo segmento** usando sub-delimitadores.
+
+| Factory                  | Tipo TS         | Descripción                                               |
+| ------------------------ | --------------- | --------------------------------------------------------- |
+| `q.Array(schema, opts?)` | `T[]`           | Lista homogénea. Separador por defecto `";"`.             |
+| `q.Object(props, opts?)` | `{ [K]: T[K] }` | Pares clave:valor. Separadores por defecto `";"` y `":"`. |
+| `q.Tuple(items, opts?)`  | `[T0, T1, ...]` | Lista posicional de largo fijo con tipos heterogéneos.    |
+
+```ts
+q.Array(q.String(), { sep: ";" });
+// "a;b;c" → ["a", "b", "c"]
+
+q.Object({ name: q.String(), age: q.Integer() }, { sep: ";", kvSep: ":" });
+// "name:John;age:30" → { name: "John", age: 30 }
+
+q.Tuple([q.String(), q.Integer(), q.String()], { sep: ";" });
+// "John;30;NYC" → ["John", 30, "NYC"]
+```
+
+### Schema (mensaje completo)
+
+`q.Schema(props, opts?)` es el tipo principal. Define un mensaje completo donde cada campo ocupa una posición fija separada por `delimiter` (por defecto `"|"`).
+
+**Posiciones automáticas** — se asignan según el orden de las claves:
+
+```ts
+const Msg = q.Schema({
+  tipo: q.String(), // posición 0
+  monto: q.Number(), // posición 1
+  ref: q.String(), // posición 2
+});
+Msg.parse("105|150.00|REF-001");
+```
+
+**Posiciones explícitas con `q.at`** — layouts sparse (solo declaras los campos que te interesan):
+
+```ts
+const Sparse = q.Schema({
+  tipo: q.at(0, q.String()),
+  monto: q.at(45, q.Number()), // salta 44 posiciones
+  uuid: q.at(199, q.String()), // salta otras 153
+});
+// Solo 3 campos declarados, TypeScript solo infiere esos 3
+```
+
+**Anidamiento** — los compuestos pueden anidarse dentro de un Schema:
+
+```ts
+const Msg = q.Schema({
+  tipo: q.String(),
+  items: q.Array(q.String(), { sep: ";" }),
+  persona: q.Object(
+    { nombre: q.String(), edad: q.Integer() },
+    { sep: ",", kvSep: ":" },
+  ),
+});
+Msg.parse("105|a;b;c|nombre:Juan,edad:30");
+```
+
+### Uniones
+
+`q.Union(variants, opts?)` prueba cada variante en orden y retorna la primera que decodifique correctamente.
+
+```ts
+const Msg = q.Union([
+  q.Schema({ tipo: q.Literal("00"), id: q.String() }),
+  q.Schema({ tipo: q.Literal("01"), id: q.String(), status: q.String() }),
+]);
+
+Msg.parse("00|CPN-1"); // variante 00
+Msg.parse("01|CPN-2|ok"); // variante 01
+```
+
+**Unión discriminada con `match()`**:
+
+```ts
+const Msg = q.Union([...], { discriminator: "tipo" });
+
+const variant = Msg.match("00");  // QSchema | undefined
+if (variant) {
+  variant.parse("00|CPN-1|a;b;c");
+}
+```
+
+---
+
+## Manejo de errores
+
+### `parse` — lanza excepción
+
+```ts
+try {
+  schema.parse(raw);
+} catch (err) {
+  if (err instanceof QtypeParseError) {
+    console.log(err.message); // "[Qtype] $.status: required segment is empty (got \"\")"
+    console.log(err.path); // "status"
+    console.log(err.rawValue); // ""
+  }
+}
+```
+
+### `safeParse` — no lanza
+
+```ts
+const result = schema.safeParse(raw);
+if (result.success) {
+  console.log(result.data);
+} else {
+  console.log(result.error.message);
+}
+```
+
+---
+
+## Scripts
+
+| Script                    | Descripción                         |
+| ------------------------- | ----------------------------------- |
+| `bun run build`           | Compila ESM + CJS + tipos a `dist/` |
+| `bun test`                | Ejecuta los tests                   |
+| `bun run src/examples.ts` | Corre los 12 ejemplos de patrones   |
+
+---
+
+## Estructura del proyecto
+
+```
+src/
+├── types.ts        # QType<T>, DecodeContext, EncodeOptions, Static<T>, SchemaProps
+├── errors.ts       # QtypeParseError, SafeResult<T>
+├── primitives.ts   # QString, QNumber, QInteger, QBoolean, QDate, QLiteral, QEnum
+├── combinators.ts  # QOptional, QNullable, QDefault, QTransform, QPositioned
+├── compound.ts     # QArray, QObject, QTuple, QSchema
+├── union.ts        # QUnion (discriminada y no discriminada)
+├── index.ts        # API pública: exports + namespace q
+└── examples.ts     # 12 ejemplos ejecutables que cubren todos los patrones
+```
+
+---
+
+## Patrones comunes
+
+### Layout sparse — declarar solo los campos necesarios
+
+```ts
+const Sparse = q.Schema({
+  tipo: q.at(0, q.String()),
+  cuenta: q.at(12, q.String()),
+  monto: q.at(45, q.Number()),
+  fecha: q.at(67, q.Date("yyyyMMdd")),
+  uuid: q.at(199, q.String()),
+});
+// Infiere solo { tipo, cuenta, monto, fecha, uuid }
+// Las 194 posiciones restantes se ignoran
+```
+
+### Discriminación por código de mensaje
+
+```ts
+const registry = {
+  "00": q.Schema({ code: q.at(0, q.Literal("00")), id: q.at(1, q.String()) }),
+  "01": q.Schema({
+    code: q.at(0, q.Literal("01")),
+    id: q.at(1, q.String()),
+    status: q.at(2, q.String()),
+  }),
+} as const;
+
+function dispatch(code: keyof typeof registry, raw: string) {
+  return registry[code].parse(raw);
+}
+```
+
+### Transformación wire ↔ app
+
+```ts
+const Amount = q.Transform(
+  q.Number(),
+  (cents) => cents / 100, // wire "150000" → app 1500.00
+  (dollars) => dollars * 100, // app 1500.00 → wire "150000"
+);
+```
+
+### Objetos anidados con separadores personalizados
+
+```ts
+const Persona = q.Object(
+  { nombre: q.String(), edad: q.Integer(), ciudad: q.Optional(q.String()) },
+  { sep: ",", kvSep: ":" },
+);
+// "nombre:Ana,edad:28,ciudad:Bogotá" → { nombre: "Ana", edad: 28, ciudad: "Bogotá" }
+```