q-type 0.1.2

package/dist/index.d.cts

@@ -0,0 +1,612 @@
+/**
+* Clase base abstracta para todo esquema de Qtype.
+*
+* Cada esquema concreto (QString, QNumber, QSchema, etc.) extiende esta clase
+* e implementa {@link decode} y {@link encode}.
+*
+* @typeParam T - El tipo TypeScript que representa este esquema.
+*/
+declare abstract class QType<T> {
+	/** Discriminante de runtime que identifica el tipo de esquema. */
+	abstract readonly kind: string;
+	/**
+	* Decodifica un string crudo en el valor tipado {@link T}.
+	*
+	* @throws {QtypeParseError} si el string no es válido.
+	*/
+	abstract decode(raw: string, ctx: DecodeContext): T;
+	/**
+	* Codifica un valor tipado {@link T} de vuelta a su representación en string.
+	*/
+	abstract encode(value: T, opts?: EncodeOptions): string;
+}
+/** Contexto que se propaga durante la decodificación para generar mensajes de error precisos. */
+interface DecodeContext {
+	readonly key: string;
+	readonly path: string;
+	readonly raw: string;
+}
+/** Opciones de codificación compartidas por todos los esquemas. */
+interface EncodeOptions {
+	/** Extiende la salida a al menos N segmentos (solo aplica en {@link QSchema}). */
+	length?: number;
+}
+/**
+* Extrae el tipo TypeScript a partir de una instancia de esquema.
+*
+* @example
+* ```ts
+* const Name = q.String();
+* type Name = Static<typeof Name>; // string
+* ```
+*/
+type Static<T extends QType<any>> = T extends QType<infer U> ? U : never;
+/** Mapa de propiedades que define la forma de un {@link QObject} o {@link QSchema}. */
+type SchemaProps = Record<string, QType<any>>;
+/**
+* Desenvuelve {@link QPositioned}`<T>` → `T`.
+*
+* Para cualquier otro esquema se comporta como {@link Static}.
+*
+* @internal — Usado por {@link FilterAt}.
+*/
+type UnwrapAt<T extends QType<any>> = T extends {
+	kind: "positioned";
+	decode(raw: string, ctx: DecodeContext): infer U;
+} ? U : Static<T>;
+/**
+* Tipo resultante de un {@link QSchema}: un objeto cuyas claves son las
+* propiedades declaradas y cuyos valores son los tipos decodificados.
+*/
+type FilterAt<T extends SchemaProps> = { [K in keyof T] : UnwrapAt<T[K]> };
+/**
+* Error lanzado cuando el parseo de un segmento falla.
+*
+* Incluye el contexto completo (key, path, rawValue) para facilitar el debug.
+*/
+declare class QtypeParseError extends Error {
+	readonly key: string;
+	readonly path: string;
+	readonly rawValue: string;
+	constructor(message: string, ctx: DecodeContext);
+}
+/**
+* Resultado de {@link QSchema.safeParse} y {@link QUnion.safeParse}.
+*
+* `success: true` con `data`, o `success: false` con `error`.
+*/
+type SafeResult<T> = {
+	success: true;
+	data: T;
+} | {
+	success: false;
+	error: QtypeParseError;
+};
+/**
+* Esquema para strings.
+*
+* Lanza {@link QtypeParseError} si el segmento está vacío.
+* Para permitir strings vacíos usa {@link QOptional} o {@link QDefault}.
+*/
+declare class QString extends QType<string> {
+	readonly kind = "string";
+	decode(raw: string, ctx: DecodeContext): string;
+	encode(value: string, _opts?: EncodeOptions): string;
+}
+/**
+* Esquema para números de punto flotante.
+*
+* Acepta cualquier string que `Number()` pueda parsear.
+* Lanza {@link QtypeParseError} si está vacío o no es un número válido.
+*/
+declare class QNumber extends QType<number> {
+	readonly kind = "number";
+	decode(raw: string, ctx: DecodeContext): number;
+	encode(value: number, _opts?: EncodeOptions): string;
+}
+/**
+* Esquema para números enteros.
+*
+* Usa {@link parseInt} con la base especificada (por defecto 10).
+*
+* @example
+* ```ts
+* q.Integer()       // base 10, decimal
+* q.Integer(16)     // base 16, hexadecimal
+* ```
+*/
+declare class QInteger extends QType<number> {
+	readonly kind = "integer";
+	private readonly radix;
+	constructor(radix?: number);
+	decode(raw: string, ctx: DecodeContext): number;
+	encode(value: number, _opts?: EncodeOptions): string;
+}
+/**
+* Esquema para valores booleanos.
+*
+* Por defecto reconoce `"1"`, `"true"`, `"Y"`, `"y"` como `true`.
+* Cualquier otro valor (incluyendo vacío) es `false`.
+* La lista de valores truthy es configurable.
+*
+* @example
+* ```ts
+* q.Boolean()                        // truthy: ["1", "true", "Y", "y"]
+* q.Boolean(["S", "s", "SI", "si"])  // truthy personalizado
+* ```
+*/
+declare class QBoolean extends QType<boolean> {
+	readonly kind = "boolean";
+	private readonly truthy;
+	constructor(truthy?: readonly string[]);
+	decode(raw: string, ctx: DecodeContext): boolean;
+	encode(value: boolean, _opts?: EncodeOptions): string;
+}
+/**
+* Esquema para fechas.
+*
+* Soporta dos formatos:
+* - `"iso"` (por defecto): usa `new Date(str)` y serializa con `toISOString()`.
+* - `"yyyyMMdd"`: parsea y serializa manualmente en zona horaria local.
+*
+* @example
+* ```ts
+* q.Date()              // formato ISO
+* q.Date("yyyyMMdd")    // formato compacto de 8 dígitos
+* ```
+*/
+declare class QDate extends QType<Date> {
+	readonly kind = "date";
+	private readonly format;
+	constructor(format?: "iso" | "yyyyMMdd");
+	decode(raw: string, ctx: DecodeContext): Date;
+	encode(value: Date, _opts?: EncodeOptions): string;
+}
+/**
+* Esquema que solo acepta un valor literal exacto.
+*
+* Útil como discriminador en uniones (ver {@link QUnion.match}).
+*
+* @example
+* ```ts
+* q.Literal("00")   // solo acepta el string "00"
+* q.Literal(42)     // solo acepta el número 42
+* ```
+*/
+declare class QLiteral<T extends string | number> extends QType<T> {
+	readonly kind = "literal";
+	readonly value: T;
+	constructor(value: T);
+	decode(raw: string, ctx: DecodeContext): T;
+	encode(value: T, _opts?: EncodeOptions): string;
+}
+/**
+* Esquema que restringe el valor a un conjunto finito de strings.
+*
+* @example
+* ```ts
+* q.Enum(["pendiente", "procesado", "rechazado"])
+* ```
+*/
+declare class QEnum<T extends readonly string[]> extends QType<T[number]> {
+	readonly kind = "enum";
+	readonly values: T;
+	constructor(values: T);
+	decode(raw: string, ctx: DecodeContext): T[number];
+	encode(value: T[number], _opts?: EncodeOptions): string;
+}
+/**
+* Convierte un esquema en opcional.
+*
+* Un segmento vacío (`""`) se decodifica como `undefined`.
+* Al codificar, `undefined` se serializa como `""`.
+*/
+declare class QOptional<T extends QType<any>> extends QType<Static<T> | undefined> {
+	readonly kind = "optional";
+	readonly inner: T;
+	constructor(schema: T);
+	decode(raw: string, ctx: DecodeContext): Static<T> | undefined;
+	encode(value: Static<T> | undefined, _opts?: EncodeOptions): string;
+}
+/**
+* Convierte un esquema en nullable.
+*
+* Un segmento vacío (`""`) se decodifica como `null`.
+* Al codificar, `null` se serializa como `""`.
+*/
+declare class QNullable<T extends QType<any>> extends QType<Static<T> | null> {
+	readonly kind = "nullable";
+	readonly inner: T;
+	constructor(schema: T);
+	decode(raw: string, ctx: DecodeContext): Static<T> | null;
+	encode(value: Static<T> | null, _opts?: EncodeOptions): string;
+}
+/**
+* Asigna un valor por defecto cuando el segmento está vacío.
+*
+* A diferencia de {@link QOptional}, el tipo de salida **no** incluye `undefined`.
+* Si el segmento no está vacío, se decodifica normalmente con el esquema interno.
+*/
+declare class QDefault<T extends QType<any>> extends QType<Static<T>> {
+	readonly kind = "default";
+	readonly inner: T;
+	readonly defaultValue: Static<T>;
+	constructor(schema: T, defaultValue: Static<T>);
+	decode(raw: string, ctx: DecodeContext): Static<T>;
+	encode(value: Static<T>, _opts?: EncodeOptions): string;
+}
+/**
+* Aplica una transformación bidireccional sobre otro esquema.
+*
+* Permite convertir entre la representación en el wire y el tipo en la app.
+*
+* @typeParam A - Esquema de entrada (tipo wire).
+* @typeParam B - Tipo de salida en la app.
+*
+* @example
+* ```ts
+* // wire: centavos (entero), app: dólares (flotante)
+* q.Transform(q.Number(), cents => cents / 100, dollars => dollars * 100)
+* ```
+*/
+declare class QTransform<
+	A extends QType<any>,
+	B
+> extends QType<B> {
+	readonly kind = "transform";
+	readonly inner: A;
+	private readonly decodeFn;
+	private readonly encodeFn;
+	constructor(schema: A, decodeFn: (a: Static<A>) => B, encodeFn: (b: B) => Static<A>);
+	decode(raw: string, ctx: DecodeContext): B;
+	encode(value: B, opts?: EncodeOptions): string;
+}
+/**
+* Asigna una posición explícita a un campo dentro de un {@link QSchema}.
+*
+* Se crea mediante {@link q.at}.
+* A nivel de tipos es transparente: el tipo de salida es el del esquema interno.
+*/
+declare class QPositioned<T extends QType<any>> extends QType<Static<T>> {
+	readonly kind = "positioned";
+	readonly index: number;
+	readonly inner: T;
+	constructor(index: number, schema: T);
+	decode(raw: string, ctx: DecodeContext): Static<T>;
+	encode(value: Static<T>, opts?: EncodeOptions): string;
+}
+/**
+* Verifica en runtime si un esquema es una instancia de {@link QPositioned}.
+*/
+declare function isPositioned(schema: QType<any>): schema is QPositioned<any>;
+/**
+* Lista delimitada de elementos homogéneos dentro de un mismo segmento.
+*
+* El separador por defecto es `";"`.
+* Un segmento vacío (`""`) produce un arreglo vacío `[]`.
+*
+* @example
+* ```ts
+* q.Array(q.String(), { sep: ";" })
+* // "a;b;c" → ["a", "b", "c"]
+* ```
+*/
+declare class QArray<T extends QType<any>> extends QType<Static<T>[]> {
+	readonly kind = "array";
+	readonly element: T;
+	private readonly sep;
+	constructor(schema: T, opts?: {
+		sep?: string;
+	});
+	decode(raw: string, ctx: DecodeContext): Static<T>[];
+	encode(value: Static<T>[], _opts?: EncodeOptions): string;
+}
+/**
+* Pares clave:valor delimitados dentro de un mismo segmento.
+*
+* Los separadores por defecto son:
+* - Entre pares: `";"`
+* - Entre clave y valor: `":"`
+*
+* Las claves no declaradas en el esquema producen error.
+* Las claves declaradas pero ausentes se decodifican con string vacío
+* (permitiendo que {@link QOptional}, {@link QNullable} y {@link QDefault}
+* manejen el caso).
+*
+* @example
+* ```ts
+* q.Object({ name: q.String(), age: q.Integer() }, { sep: ";", kvSep: ":" })
+* // "name:John;age:30" → { name: "John", age: 30 }
+* ```
+*/
+declare class QObject<T extends SchemaProps> extends QType<{ [K in keyof T] : Static<T[K]> }> {
+	readonly kind = "object";
+	readonly properties: T;
+	private readonly sep;
+	private readonly kvSep;
+	constructor(properties: T, opts?: {
+		sep?: string;
+		kvSep?: string;
+	});
+	decode(raw: string, ctx: DecodeContext): { [K in keyof T] : Static<T[K]> };
+	encode(value: { [K in keyof T] : Static<T[K]> }, _opts?: EncodeOptions): string;
+}
+/**
+* Lista posicional de largo fijo con esquemas heterogéneos.
+*
+* Cada posición tiene su propio esquema. El número de elementos en el wire
+* debe ser al menos igual al número de esquemas declarados.
+* El separador por defecto es `";"`.
+*
+* @example
+* ```ts
+* q.Tuple([q.String(), q.Integer(), q.String()], { sep: ";" })
+* // "John;30;NYC" → ["John", 30, "NYC"]
+* ```
+*/
+declare class QTuple<T extends QType<any>[]> extends QType<{ [K in keyof T] : Static<T[K]> }> {
+	readonly kind = "tuple";
+	readonly items: T;
+	private readonly sep;
+	constructor(items: [...T], opts?: {
+		sep?: string;
+	});
+	decode(raw: string, ctx: DecodeContext): { [K in keyof T] : Static<T[K]> };
+	encode(value: { [K in keyof T] : Static<T[K]> }, _opts?: EncodeOptions): string;
+}
+/**
+* Esquema principal: protocolo delimitado por pipes de nivel superior.
+*
+* Es el tipo de esquema más común. Define un mensaje completo donde cada
+* campo ocupa una posición fija separada por `delimiter` (por defecto `"|"`).
+*
+* ### Posiciones
+*
+* Por defecto, las posiciones se asignan secuencialmente según el orden de
+* las claves. Usa {@link q.at} para asignar posiciones explícitas y crear
+* layouts sparse (ej. declarar 7 campos de 200 posiciones).
+*
+* ### Métodos de conveniencia
+*
+* - {@link parse}: decodifica un string crudo, lanza {@link QtypeParseError} si falla.
+* - {@link safeParse}: igual que `parse` pero retorna `{ success, data/error }` sin lanzar.
+* - {@link serialize}: codifica un objeto de vuelta a string.
+*
+* @example
+* ```ts
+* const Msg = q.Schema({
+*   tipo: q.String(),
+*   monto: q.Number(),
+* });
+*
+* Msg.parse("105|150.00");              // { tipo: "105", monto: 150 }
+* Msg.serialize({ tipo: "105", monto: 150 }); // "105|150"
+* ```
+*/
+declare class QSchema<T extends SchemaProps> extends QType<FilterAt<T>> {
+	readonly kind = "schema";
+	readonly properties: T;
+	private readonly delimiter;
+	private readonly positions;
+	constructor(properties: T, opts?: {
+		delimiter?: string;
+		strictLength?: boolean;
+	});
+	/**
+	* Decodifica un mensaje completo.
+	*
+	* @throws {QtypeParseError} si el mensaje no es válido.
+	*/
+	parse(raw: string): FilterAt<T>;
+	/**
+	* Decodifica un mensaje completo sin lanzar excepciones.
+	*
+	* Retorna `{ success: true, data }` o `{ success: false, error }`.
+	*/
+	safeParse(raw: string): SafeResult<FilterAt<T>>;
+	decode(raw: string, ctx: DecodeContext): FilterAt<T>;
+	encode(value: FilterAt<T>, opts?: EncodeOptions): string;
+	/**
+	* Alias de {@link encode} para mayor claridad semántica.
+	*/
+	serialize(value: FilterAt<T>, opts?: EncodeOptions): string;
+}
+/**
+* Unión de esquemas: prueba cada variante en orden y retorna la primera
+* que decodifique correctamente.
+*
+* ### Modo no discriminado (por defecto)
+*
+* Prueba cada variante secuencialmente al decodificar. La primera que no
+* lance error gana.
+*
+* ### Modo discriminado
+*
+* Cuando se provee `discriminator`, {@link match} permite seleccionar la
+* variante correcta antes de decodificar, según el valor de un campo
+* {@link QLiteral} o {@link QEnum} en el {@link QSchema}.
+*
+* @example
+* ```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
+* ```
+*/
+declare class QUnion<T extends QType<any>[]> extends QType<Static<T[number]>> {
+	readonly kind = "union";
+	readonly variants: [...T];
+	private readonly discriminator?;
+	constructor(variants: [...T], opts?: {
+		discriminator?: string;
+	});
+	/**
+	* Decodifica un mensaje probando cada variante en orden.
+	*
+	* @throws {QtypeParseError} si ninguna variante coincide.
+	*/
+	parse(raw: string): Static<T[number]>;
+	/**
+	* Versión segura de {@link parse} que no lanza excepciones.
+	*/
+	safeParse(raw: string): {
+		success: true;
+		data: Static<T[number]>;
+	} | {
+		success: false;
+		error: QtypeParseError;
+	};
+	decode(raw: string, ctx: DecodeContext): Static<T[number]>;
+	encode(value: Static<T[number]>, opts?: EncodeOptions): string;
+	/**
+	* Alias de {@link encode} para mayor claridad semántica.
+	*/
+	serialize(value: Static<T[number]>, opts?: EncodeOptions): string;
+	/**
+	* Para uniones discriminadas, retorna la variante cuyo campo discriminador
+	* coincide con `value`.
+	*
+	* El discriminador debe ser un {@link QLiteral} o {@link QEnum} dentro de
+	* un {@link QSchema}.
+	*
+	* @returns La variante coincidente, o `undefined` si no hay coincidencia.
+	*/
+	match(value: string): QType<any> | undefined;
+}
+/**
+* Namespace `q` — fábrica de esquemas.
+*
+* Cada método retorna una instancia de esquema lista para usar en
+* {@link QSchema.parse}, {@link QSchema.serialize}, etc.
+*
+* @example
+* ```ts
+* import { q, type Static } from "qtype";
+*
+* const Msg = q.Schema({
+*   tipo: q.String(),
+*   monto: q.Number(),
+*   activo: q.Boolean(),
+* });
+*
+* type Msg = Static<typeof Msg>;
+* // { tipo: string; monto: number; activo: boolean }
+* ```
+*/
+declare const q: {
+	/** Esquema para strings. El segmento vacío lanza error. */
+	String: () => QString;
+	/** Esquema para números de punto flotante. */
+	Number: () => QNumber;
+	/**
+	* Esquema para números enteros.
+	*
+	* @param radix - Base numérica (por defecto 10).
+	*/
+	Integer: (radix?: number) => QInteger;
+	/**
+	* Esquema para booleanos.
+	*
+	* @param truthy - Lista de strings que se interpretan como `true`.
+	*                 Por defecto `["1", "true", "Y", "y"]`.
+	*/
+	Boolean: (truthy?: readonly string[]) => QBoolean;
+	/**
+	* Esquema para fechas.
+	*
+	* @param format - `"iso"` (por defecto) o `"yyyyMMdd"`.
+	*/
+	Date: (format?: "iso" | "yyyyMMdd") => QDate;
+	/** Esquema que solo acepta un valor literal exacto. */
+	Literal: <T extends string | number>(value: T) => QLiteral<T>;
+	/** Esquema que restringe el valor a un conjunto de strings. */
+	Enum: <T extends readonly string[]>(values: T) => QEnum<T>;
+	/**
+	* Lista delimitada de elementos homogéneos.
+	*
+	* @param schema - Esquema de cada elemento.
+	* @param opts.sep - Separador entre elementos (por defecto `";"`).
+	*/
+	Array: <T extends QType<any>>(schema: T, opts?: {
+		sep?: string;
+	}) => QArray<T>;
+	/**
+	* Pares clave:valor delimitados.
+	*
+	* @param props - Definición de las propiedades.
+	* @param opts.sep - Separador entre pares (por defecto `";"`).
+	* @param opts.kvSep - Separador clave-valor (por defecto `":"`).
+	*/
+	Object: <T extends SchemaProps>(props: T, opts?: {
+		sep?: string;
+		kvSep?: string;
+	}) => QObject<T>;
+	/**
+	* Tupla posicional de largo fijo con esquemas heterogéneos.
+	*
+	* @param items - Arreglo de esquemas, uno por posición.
+	* @param opts.sep - Separador entre elementos (por defecto `";"`).
+	*/
+	Tuple: <T extends QType<any>[]>(items: [...T], opts?: {
+		sep?: string;
+	}) => QTuple<T>;
+	/**
+	* Esquema principal: mensaje delimitado por pipes.
+	*
+	* @param props - Definición de los campos del mensaje.
+	* @param opts.delimiter - Separador entre campos (por defecto `"|"`).
+	*/
+	Schema: <T extends SchemaProps>(props: T, opts?: {
+		delimiter?: string;
+		strictLength?: boolean;
+	}) => QSchema<T>;
+	/** Convierte un esquema en opcional. Vacío → `undefined`. */
+	Optional: <T extends QType<any>>(schema: T) => QOptional<T>;
+	/** Convierte un esquema en nullable. Vacío → `null`. */
+	Nullable: <T extends QType<any>>(schema: T) => QNullable<T>;
+	/**
+	* Asigna un valor por defecto cuando el segmento está vacío.
+	*
+	* A diferencia de {@link Optional}, el tipo de salida no incluye `undefined`.
+	*/
+	Default: <T extends QType<any>>(schema: T, defaultValue: Static<T>) => QDefault<T>;
+	/**
+	* Aplica una transformación bidireccional sobre otro esquema.
+	*
+	* @param schema - Esquema base (tipo wire).
+	* @param decode - Función de decodificación (wire → app).
+	* @param encode - Función de codificación (app → wire).
+	*
+	* @example
+	* ```ts
+	* // wire: centavos (entero), app: dólares (flotante)
+	* q.Transform(q.Number(), cents => cents / 100, dollars => dollars * 100)
+	* ```
+	*/
+	Transform: <
+		A extends QType<any>,
+		B
+	>(schema: A, decode: (a: Static<A>) => B, encode: (b: B) => Static<A>) => QTransform<A, B>;
+	/**
+	* Asigna una posición explícita a un campo dentro de un {@link QSchema}.
+	*
+	* Los campos sin `q.at` reciben posiciones secuenciales automáticamente,
+	* saltando las posiciones ya ocupadas por campos explícitos.
+	*/
+	at: <T extends QType<any>>(index: number, schema: T) => QPositioned<T>;
+	/**
+	* Unión de esquemas. Prueba cada variante en orden.
+	*
+	* @param variants - Lista de esquemas variantes.
+	* @param opts.discriminator - Campo {@link QLiteral} o {@link QEnum} usado
+	*   para seleccionar la variante correcta con {@link QUnion.match}.
+	*/
+	Union: <T extends QType<any>[]>(variants: [...T], opts?: {
+		discriminator?: string;
+	}) => QUnion<T>;
+};
+export { q, isPositioned, Static, SchemaProps, SafeResult, QtypeParseError, QUnion, QType, QTuple, QTransform, QString, QSchema, QPositioned, QOptional, QObject, QNumber, QNullable, QLiteral, QInteger, QEnum, QDefault, QDate, QBoolean, QArray, FilterAt, EncodeOptions, DecodeContext };