Datoteca — API Reference

Datoteca

Librería TypeScript para generar datos de prueba realistas y localizados de Chile — determinística por seed.

Tabla de contenidos

Sobre el proyecto
Construido con
Getting Started
- Prerequisites
- Installation
Uso
Roadmap
Contributing
License
Contact

Sobre el proyecto

Datoteca es un monorepo de librerías TypeScript para generar datos de prueba realistas y culturalmente correctos por país, empezando por Chile (@datoteca/cl). El nombre evita deliberadamente acoplarse a una región geográfica tipo "latam" — cada país es un paquete propio (@datoteca/cl, y en el futuro @datoteca/pe, @datoteca/ar, @datoteca/es...) sobre una base compartida (@datoteca/core).

¿Por qué existe? Porque generar datos de prueba "parecidos" a los reales no alcanza en dominios donde el formato importa — sobre todo en fintech y banca:

Un RUT no es solo un número con guion: necesita un dígito verificador matemáticamente válido (módulo 11), o los formularios y validaciones que lo consumen lo van a rechazar.
Una comuna no puede ser inventada: direccion.comuna() solo devuelve comunas reales, tomadas de la división político-administrativa oficial (SUBDERE).
El dinero se muestra como se muestra en Chile: $45.000, UF 1.234,56, vía Intl.NumberFormat('es-CL').

Y determinístico por seed: misma seed + mismo orden de llamadas → mismos resultados, para tests reproducibles.

¿Por qué no usar directamente @faker-js/faker y su locale es_CL? No es un reemplazo, es un complemento. Faker es excelente para datos genéricos multi-locale (nombres, lorem, internet, etc.), pero no baja al detalle de un dato específico de un país como el RUT chileno con su algoritmo de verificación, o un listado exhaustivo y real de comunas. Datoteca se enfoca en ese detalle local que un generador generalista no puede cubrir bien para todos los países a la vez.

La referencia completa de la API (clases, métodos y tipos de @datoteca/core y @datoteca/cl) está publicada en johansneirap.github.io/datoteca.

(back to top)

Construido con

TypeScript en modo strict + noUncheckedIndexedAccess
tsup — build a ESM + CJS + .d.ts por paquete
Vitest — tests de formato y determinismo por generador
Commander — parsing de argumentos de @datoteca/cli
pnpm workspaces — monorepo
Changesets — versionado y publicación

(back to top)

Getting Started

Prerequisites

Node.js >= 18
pnpm (el repo usa pnpm@9.12.0 vía packageManager)

Installation

npm install @datoteca/cl

o con pnpm:

pnpm add @datoteca/cl

@datoteca/core es una dependencia interna de @datoteca/cl (PRNG y helpers compartidos) y se instala automáticamente — no hace falta agregarlo a mano.

¿No querís escribir código? Usa el CLI directo con npx, sin instalar nada:

npx @datoteca/cli person --seed 42 --count 3

(back to top)

Uso

Instancia Datoteca con una seed. Sin estado global: la misma seed, en el mismo orden de llamadas, siempre produce el mismo resultado.

import { Datoteca } from '@datoteca/cl';

const dl = new Datoteca({ seed: 123 });

dl.rut(); // "12345678-9"
dl.persona.nombreCompleto(); // "María González Soto"
dl.direccion.direccionCompleta(); // "Los Aromos 482, Providencia"
dl.telefono.movil(); // "+56 9 1234 5678"
dl.dinero.clp(); // "$45.000"

RUT con distintas opciones de formato:

dl.rut(); // "12345678-9"    (format: 'dash', default)
dl.rut({ format: 'dots' }); // "12.345.678-9"
dl.rut({ format: 'raw' }); // "123456789"
dl.rut({ dv: false }); // "12345678"     (sin dígito verificador)

rut() en la raíz genera RUT de persona natural. Si necesitas distinguir explícitamente entre persona natural y empresa (el SII asigna RUT de personas jurídicas desde el 50.000.000), usa los generadores por namespace:

dl.persona.rut(); // "12345678-9"    (rango persona natural: 1.000.000-25.000.000)
dl.empresa.rut(); // "76543210-K"    (rango empresa: 50.000.000-99.999.999)

Ambos aceptan las mismas opciones (format, dv) que rut().

Dígito verificador de forma independiente (método estático, no requiere seed) y dinero con rango personalizado:

Datoteca.calcularDV(12345678); // "5"

dl.dinero.clp({ min: 10_000, max: 200_000 });
dl.dinero.uf(); // "UF 1.234,56"

dinero.clp()/dinero.uf() devuelven el string ya formateado; si necesitas operar el valor (sumar, comparar, etc.), usa la variante numérica:

dl.dinero.clpNumero(); // 45000        (number, sin formatear)
dl.dinero.ufNumero(); // 1234.56      (number, hasta 2 decimales)

Namespaces disponibles en el MVP: persona, direccion, telefono, dinero, banco, empresa, más rut() en la raíz por ser el dato más emblemático.

CLI

@datoteca/cli expone los mismos generadores desde la terminal — pensado para poblar fixtures rápido, generar CSV/JSON para QA, o usarlo desde stacks no-JS (Go, Python, etc.), sin escribir código:

npx @datoteca/cli rut --seed 42 --count 5
npx @datoteca/cli money --seed 42 --currency UF --min 10 --max 500 --format csv > fixtures.csv

Un subcomando por generador (rut, person, address, phone, money, company), formatos json/csv/ndjson, y la misma garantía de determinismo por seed. Ver el README de @datoteca/cli para la referencia completa de comandos y flags.

(back to top)

Roadmap

MVP v0.x — implementado

[x] @datoteca/core: PRNG determinístico (mulberry32) + helpers (pickOne, pickWeighted, intBetween, arrayOf)
[x] rut() con formatos dash/dots/raw, dígito verificador módulo 11, y Datoteca.calcularDV() estático — más persona.rut()/empresa.rut() como generadores separados por rango
[x] persona — nombre, apellido, nombre completo
[x] direccion — comuna (dataset real SUBDERE), calle, dirección completa
[x] telefono — móvil, fijo
[x] dinero — CLP, UF (formateados en es-CL), más clpNumero()/ufNumero() para quien necesite operar los valores
[x] banco — nombre, cuenta
[x] empresa — razón social, giro
[x] Build (tsup ESM+CJS+d.ts), Changesets, CI y release workflows en GitHub Actions
[x] Golden dataset de seeds documentadas para snapshot testing (ver docs/determinism.md)
[x] @datoteca/cli (npx @datoteca/cli ...) — un subcomando por generador, formatos json/csv/ndjson

Backlog — fuera del MVP

[ ] Otros países/locales (@datoteca/pe, @datoteca/ar, @datoteca/es, ...)

(back to top)

Contributing

Las contribuciones son bienvenidas.

Haz fork del proyecto
Crea tu rama de feature (git checkout -b feat/mi-generador)
Haz commit de tus cambios siguiendo Conventional Commits con scope de paquete cuando aplique (git commit -m 'feat(cl): agrega generador de X')
Verifica antes de subir: pnpm build, pnpm test, pnpm lint, pnpm typecheck
Push a tu rama (git push origin feat/mi-generador)
Abre un Pull Request

Prefijos usados en este repo: feat, fix, chore, docs, ci, build, test, con scope entre paréntesis (core, cl) cuando el cambio es específico de un paquete.

(back to top)