datera 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alessandra Vieira
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,132 @@
+<p align="center">
+  <img src="docs/assets/datera-banner.png" alt="Datera: dados bagunçados entrando de um lado e saindo organizados do outro">
+</p>
+
+<p align="center">Ferramenta pra limpar e juntar dados bagunçados de planilha, banco e arquivo.</p>
+
+<p align="center">
+  <a href="https://github.com/alessandravieiradev-blip/datera/actions/workflows/ci.yml"><img src="https://github.com/alessandravieiradev-blip/datera/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+</p>
+
+<p align="center">
+  <a href="docs/gestores.md"><img src="https://img.shields.io/badge/Para%20gestores-2563EB?style=for-the-badge" alt="Guia para gestores"></a>
+  <a href="docs/devs.md"><img src="https://img.shields.io/badge/Para%20devs-16181D?style=for-the-badge" alt="Guia para devs"></a>
+</p>
+
+## O que é
+
+O Datera é um ETL que eu fiz em TypeScript. Ele lê dados de banco, planilha ou arquivo, arruma o que dá e escreve o resultado organizado em outro lugar:
+
+```mermaid
+flowchart LR
+    subgraph fontes["Lê de"]
+        direction TB
+        B["Bancos<br/>MySQL · PostgreSQL<br/>SQL Server · SQLite"]
+        P1["Planilhas<br/>Google Sheets · Excel"]
+        A1["Arquivos<br/>CSV · JSON<br/>XML · Parquet"]
+    end
+    subgraph destinos["Escreve em"]
+        direction TB
+        P2["Planilhas<br/>Google Sheets · Excel"]
+        A2["Arquivos<br/>CSV · JSON<br/>XML · Parquet"]
+    end
+    B --> D((Datera))
+    P1 --> D
+    A1 --> D
+    D --> P2
+    D --> A2
+    classDef datera fill:#2563EB,stroke:#2563EB,color:#ffffff
+    class D datera
+```
+
+Ele começou bem simples, era só pra copiar uma tabela do MySQL pra uma planilha. Só que aí eu fui vendo que dado de verdade vem uma bagunça: a mesma pessoa cadastrada duas vezes, e-mail com maiúscula num lugar e minúscula no outro, campo vazio, informação espalhada em várias colunas. Então fui colocando coisa nova até conseguir resolver quase tudo mexendo só no `config.json`.
+
+## A ideia
+
+Quem mais sofre com planilha bagunçada normalmente não é quem programa. É quem precisa da lista certinha pra mandar um e-mail, fechar um relatório ou ligar pra alguém. E essa pessoa não deveria ter que pedir ajuda toda vez que precisa dos dados limpos.
+
+Então o Datera funciona assim: as regras ficam num arquivo de configuração (o `config.json`), que pode ser montado com calma uma vez só. Depois disso qualquer pessoa roda com um clique e recebe duas coisas: o resultado organizado e uma lista separada do que precisa de alguém dar uma olhada, com o motivo escrito do lado. Nada some sem explicação.
+
+Por isso ele tem três jeitos de usar, todos com o mesmo motor e a mesma configuração:
+
+| Jeito          | Pra quem                                      | O que tem                                                                 |
+| -------------- | --------------------------------------------- | ------------------------------------------------------------------------- |
+| **Datera**     | quem cuida dos dados mas não programa         | app com tela, passo a passo, regras em frases, gráficos e histórico       |
+| **Datera Dev** | quem programa                                 | app escuro com editor da config, prévia na hora, log e paleta de comandos |
+| **Terminal**   | quem quer automatizar ou usar em outro código | o comando `datera`, `--dry-run` e a função `runEtl`                       |
+
+## Como funciona
+
+```text
+fonte ──► prepara ──► separa o que tem problema ──► tira ou junta repetidos ──► destino
+                               │
+                               └──► pendências (com o motivo de cada uma)
+```
+
+1. **Fonte:** lê de onde os dados estão.
+2. **Prepara:** preenche célula vazia e junta colunas, se você pedir.
+3. **Pendências:** as linhas que quebram alguma regra (e-mail inválido, campo vazio, valor fora da lista...) vão pra uma aba ou arquivo à parte.
+4. **Repetidos:** deixa como está, tira as linhas repetidas ou junta as linhas da mesma pessoa sem perder nada.
+5. **Destino:** escreve o resultado onde você escolheu.
+
+Hoje ele consegue:
+
+- tirar linhas repetidas (`dedupe`) ou juntar as linhas da mesma pessoa sem perder nada (`merge`)
+- usar normalizadores pra `Lia@Email.com` e ` lia@email.com` contarem como a mesma pessoa
+- ter regras diferentes dependendo do tipo da chave
+- decidir o que fazer com as linhas que não têm chave, sem elas sumirem nem se misturarem
+- espalhar valores em várias colunas sem jogar nenhum fora
+- ler e escrever em formatos diferentes sem mudar nada das regras
+
+## Escolha o seu caminho
+
+<table>
+<tr>
+<td width="50%" valign="top">
+
+### Para gestores
+
+Você quer usar o app com tela: instalar, escolher de onde vêm os dados, montar as regras em frases e exportar. Não precisa saber programar.
+
+<a href="https://github.com/alessandravieiradev-blip/datera/releases/latest"><img src="https://img.shields.io/badge/Baixar%20o%20Datera-2563EB?style=for-the-badge" alt="Baixar o Datera"></a>
+<a href="docs/gestores.md"><img src="https://img.shields.io/badge/Abrir%20o%20guia-475569?style=for-the-badge" alt="Abrir o guia para gestores"></a>
+
+</td>
+<td width="50%" valign="top">
+
+### Para devs
+
+Você quer rodar pelo terminal, usar o Datera Dev, escrever a config na mão, criar normalizadores ou chamar o Datera de dentro de outro código.
+
+<a href="docs/devs.md"><img src="https://img.shields.io/badge/Abrir%20o%20guia%20para%20devs-16181D?style=for-the-badge" alt="Abrir o guia para devs"></a>
+<a href="docs/api.md"><img src="https://img.shields.io/badge/Comandos%20e%20API-475569?style=for-the-badge" alt="Comandos e API"></a>
+
+</td>
+</tr>
+</table>
+
+## Todos os guias
+
+| Guia                                                       | O que tem                                                            |
+| ---------------------------------------------------------- | -------------------------------------------------------------------- |
+| [Para gestores](docs/gestores.md)                          | instalar e usar o app com tela                                       |
+| [Para devs](docs/devs.md)                                  | teste em 1 minuto, terminal, Datera Dev, uso em código e testes      |
+| [Comandos e API](docs/api.md)                              | os comandos do terminal e as funções pra usar no seu código          |
+| [Configuração](docs/configuracao.md)                       | todos os campos do `config.json`, os modos e as estratégias do merge |
+| [Fontes e destinos](docs/fontes-e-destinos.md)             | cada formato que ele lê e escreve, e como criar o seu                |
+| [Exemplos](docs/exemplos.md)                               | dez configs, do mais simples ao mais completo                        |
+| [Preparação e pendências](docs/preparacao-e-pendencias.md) | `fillEmpty`, `combineColumns`, `distribute` e `validation`           |
+| [Normalizadores](docs/normalizadores.md)                   | os prontos e como criar o seu                                        |
+| [Estrutura do projeto](docs/estrutura.md)                  | o que tem em cada pasta                                              |
+
+## Contribuir e licença
+
+Se quiser ajudar, o jeito de rodar, testar e mandar mudanças está no [CONTRIBUTING.md](CONTRIBUTING.md). O código é aberto, sob a [licença MIT](LICENSE).
+
+## Próximos passos
+
+A ideia é chegar num instalador de um clique pra quem não programa e numa biblioteca no npm pra quem programa.
+
+O que eu quero fazer fica nas [issues](https://github.com/alessandravieiradev-blip/datera/issues), agrupadas em etapas nos [milestones](https://github.com/alessandravieiradev-blip/datera/milestones). Lá dá pra ver o que já foi feito e o que falta, e tudo se atualiza sozinho conforme eu vou fazendo.
+
+Se quiser saber no que eu tô trabalhando agora, me chama no Instagram ou aqui no GitHub. Os dois estão no [meu perfil](https://github.com/alessandravieiradev-blip).

package/dist/api/clean.d.ts

@@ -0,0 +1,138 @@
+import { z } from "zod";
+import { etlConfigSchema } from "../config";
+import { mergeColumnSchema } from "../config/mergeSchema";
+import { combineColumnsSchema, fillEmptySchema } from "../config/prepareSchema";
+import { validationSchema } from "../config/validationSchema";
+import { PendingReason, StepReport } from "../pipeline";
+import { TableRow } from "../types";
+export declare const rulesSchema: z.ZodObject<{
+    fillEmpty: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        column: z.ZodString;
+        fallbackColumns: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        default: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    combineColumns: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        into: z.ZodString;
+        columns: z.ZodArray<z.ZodString>;
+        separator: z.ZodOptional<z.ZodString>;
+        keepSources: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>>;
+    validation: z.ZodOptional<z.ZodObject<{
+        rules: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            message: z.ZodOptional<z.ZodString>;
+            column: z.ZodString;
+            rule: z.ZodLiteral<"required">;
+        }, z.core.$strip>, z.ZodObject<{
+            message: z.ZodOptional<z.ZodString>;
+            column: z.ZodString;
+            rule: z.ZodLiteral<"pattern">;
+            pattern: z.ZodString;
+            flags: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            message: z.ZodOptional<z.ZodString>;
+            column: z.ZodString;
+            rule: z.ZodLiteral<"oneOf">;
+            values: z.ZodArray<z.ZodString>;
+            ignoreCase: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>, z.ZodObject<{
+            message: z.ZodOptional<z.ZodString>;
+            column: z.ZodString;
+            rule: z.ZodLiteral<"normalizer">;
+            normalizer: z.ZodString;
+        }, z.core.$strip>], "rule">>;
+        pendingSheet: z.ZodOptional<z.ZodString>;
+        reasonColumn: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    dedupe: z.ZodOptional<z.ZodObject<{
+        column: z.ZodString;
+        keep: z.ZodOptional<z.ZodEnum<{
+            first: "first";
+            last: "last";
+        }>>;
+        normalizer: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    merge: z.ZodOptional<z.ZodObject<{
+        key: z.ZodString;
+        columns: z.ZodArray<z.ZodObject<{
+            column: z.ZodString;
+            strategy: z.ZodEnum<{
+                concat: "concat";
+                "extra-column": "extra-column";
+                overwrite: "overwrite";
+            }>;
+            separator: z.ZodOptional<z.ZodString>;
+            distribute: z.ZodOptional<z.ZodObject<{
+                columns: z.ZodArray<z.ZodString>;
+                overflowInto: z.ZodOptional<z.ZodString>;
+                sources: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            }, z.core.$strip>>;
+            byGroup: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+                strategy: z.ZodEnum<{
+                    concat: "concat";
+                    "extra-column": "extra-column";
+                    overwrite: "overwrite";
+                }>;
+                separator: z.ZodOptional<z.ZodString>;
+                into: z.ZodOptional<z.ZodString>;
+                distribute: z.ZodOptional<z.ZodObject<{
+                    columns: z.ZodArray<z.ZodString>;
+                    overflowInto: z.ZodOptional<z.ZodString>;
+                    sources: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>>>;
+            unkeyed: z.ZodOptional<z.ZodObject<{
+                strategy: z.ZodEnum<{
+                    "collapse-column": "collapse-column";
+                }>;
+                into: z.ZodOptional<z.ZodString>;
+                separator: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+        normalizer: z.ZodOptional<z.ZodString>;
+        emptyKeyLabel: z.ZodOptional<z.ZodString>;
+        rejectedKeyLabel: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type Rules = z.input<typeof rulesSchema>;
+export type ConfigInput = z.input<typeof etlConfigSchema>;
+export interface CleanOptions {
+    onStep?: ((report: StepReport) => void) | undefined;
+}
+export interface CleanResult {
+    rows: TableRow[];
+    pending: TableRow[];
+    pendingByReason: PendingReason[];
+    steps: StepReport[];
+    durationMs: number;
+}
+export declare function defineConfig(config: ConfigInput): ConfigInput;
+export declare function defineRules(rules: Rules): Rules;
+export declare function clean(rows: TableRow[], rules?: Rules, options?: CleanOptions): CleanResult;
+type FillEmptyRule = z.input<typeof fillEmptySchema>;
+type CombineRule = z.input<typeof combineColumnsSchema>;
+type Validation = z.input<typeof validationSchema>;
+type ValidationRule = Validation["rules"][number];
+type MergeColumn = z.input<typeof mergeColumnSchema>;
+export declare function fillEmpty(rows: TableRow[], rules: FillEmptyRule[]): TableRow[];
+export declare function combineColumns(rows: TableRow[], rules: CombineRule[]): TableRow[];
+export declare function validate(rows: TableRow[], rules: ValidationRule[] | Validation): {
+    valid: TableRow[];
+    pending: TableRow[];
+};
+export interface DedupeOptions {
+    keep?: "first" | "last" | undefined;
+    normalizer?: string | undefined;
+}
+export declare function dedupe(rows: TableRow[], column: string, options?: DedupeOptions): TableRow[];
+export interface MergeOptions {
+    columns?: MergeColumn[] | undefined;
+    normalizer?: string | undefined;
+    separator?: string | undefined;
+    overwrite?: string[] | undefined;
+    extraColumn?: string[] | undefined;
+    emptyKeyLabel?: string | undefined;
+    rejectedKeyLabel?: string | undefined;
+}
+export declare function mergeColumnsFor(rows: TableRow[], key: string, options?: MergeOptions): MergeColumn[];
+export declare function merge(rows: TableRow[], key: string, options?: MergeOptions): TableRow[];
+export {};

package/dist/api/clean.js

@@ -0,0 +1,138 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rulesSchema = void 0;
+exports.defineConfig = defineConfig;
+exports.defineRules = defineRules;
+exports.clean = clean;
+exports.fillEmpty = fillEmpty;
+exports.combineColumns = combineColumns;
+exports.validate = validate;
+exports.dedupe = dedupe;
+exports.mergeColumnsFor = mergeColumnsFor;
+exports.merge = merge;
+const zod_1 = require("zod");
+const mergeSchema_1 = require("../config/mergeSchema");
+const prepareSchema_1 = require("../config/prepareSchema");
+const validationSchema_1 = require("../config/validationSchema");
+const normalizers_1 = require("../normalizers");
+const pipeline_1 = require("../pipeline");
+const parse_1 = require("./parse");
+exports.rulesSchema = zod_1.z
+    .object({
+    fillEmpty: zod_1.z.array(prepareSchema_1.fillEmptySchema).optional(),
+    combineColumns: zod_1.z.array(prepareSchema_1.combineColumnsSchema).optional(),
+    validation: validationSchema_1.validationSchema.optional(),
+    dedupe: zod_1.z
+        .object({
+        column: zod_1.z.string().min(1),
+        keep: zod_1.z.enum(["first", "last"]).optional(),
+        normalizer: zod_1.z.string().optional(),
+    })
+        .optional(),
+    merge: zod_1.z
+        .object({
+        key: zod_1.z.string().min(1),
+        columns: zod_1.z.array(mergeSchema_1.mergeColumnSchema).min(1),
+        normalizer: zod_1.z.string().optional(),
+        emptyKeyLabel: zod_1.z.string().optional(),
+        rejectedKeyLabel: zod_1.z.string().optional(),
+    })
+        .optional(),
+})
+    .refine((rules) => !(rules.dedupe && rules.merge), {
+    message: "Escolha dedupe ou merge, os dois juntos não dá.",
+    path: ["merge"],
+});
+function defineConfig(config) {
+    return config;
+}
+function defineRules(rules) {
+    return rules;
+}
+function configOf(rules) {
+    const mode = rules.merge ? "merge" : rules.dedupe ? "dedupe" : "raw";
+    const config = {
+        mode,
+        fillEmpty: rules.fillEmpty,
+        combineColumns: rules.combineColumns,
+        validation: rules.validation,
+        dedupeColumn: rules.dedupe?.column,
+        dedupeStrategy: rules.dedupe?.keep === "last" ? "keep-last" : "keep-first",
+        dedupeKeyNormalizer: rules.dedupe?.normalizer,
+        mergeKeyColumn: rules.merge?.key,
+        mergeColumns: rules.merge?.columns,
+        mergeKeyNormalizer: rules.merge?.normalizer,
+        mergeEmptyKeyLabel: rules.merge?.emptyKeyLabel,
+        mergeRejectedKeyLabel: rules.merge?.rejectedKeyLabel,
+    };
+    return { config, mode };
+}
+function clean(rows, rules = {}, options = {}) {
+    const startedAt = Date.now();
+    const parsed = (0, parse_1.parseWith)(exports.rulesSchema, rules, "As regras");
+    (0, normalizers_1.registerBuiltinKeyNormalizers)();
+    const { config, mode } = configOf(parsed);
+    const result = (0, pipeline_1.applySteps)((0, pipeline_1.buildSteps)(config, mode), rows, options.onStep);
+    return {
+        rows: result.rows,
+        pending: result.pending,
+        pendingByReason: (0, pipeline_1.countPendingReasons)(result.pending, parsed.validation?.reasonColumn),
+        steps: result.steps,
+        durationMs: Date.now() - startedAt,
+    };
+}
+function fillEmpty(rows, rules) {
+    return clean(rows, { fillEmpty: rules }).rows;
+}
+function combineColumns(rows, rules) {
+    return clean(rows, { combineColumns: rules }).rows;
+}
+function validate(rows, rules) {
+    const validation = Array.isArray(rules) ? { rules } : rules;
+    const result = clean(rows, { validation });
+    return { valid: result.rows, pending: result.pending };
+}
+function dedupe(rows, column, options = {}) {
+    return clean(rows, {
+        dedupe: {
+            column,
+            ...(options.keep ? { keep: options.keep } : {}),
+            ...(options.normalizer ? { normalizer: options.normalizer } : {}),
+        },
+    }).rows;
+}
+function mergeColumnsFor(rows, key, options = {}) {
+    const names = new Set();
+    for (const row of rows) {
+        for (const name of Object.keys(row))
+            names.add(name);
+    }
+    names.delete(key);
+    return [...names].map((column) => options.overwrite?.includes(column)
+        ? { column, strategy: "overwrite" }
+        : options.extraColumn?.includes(column)
+            ? { column, strategy: "extra-column" }
+            : {
+                column,
+                strategy: "concat",
+                separator: options.separator ?? " | ",
+            });
+}
+function merge(rows, key, options = {}) {
+    const columns = options.columns ?? mergeColumnsFor(rows, key, options);
+    if (columns.length === 0)
+        return rows;
+    return clean(rows, {
+        merge: {
+            key,
+            columns,
+            ...(options.normalizer ? { normalizer: options.normalizer } : {}),
+            ...(options.emptyKeyLabel
+                ? { emptyKeyLabel: options.emptyKeyLabel }
+                : {}),
+            ...(options.rejectedKeyLabel
+                ? { rejectedKeyLabel: options.rejectedKeyLabel }
+                : {}),
+        },
+    }).rows;
+}

package/dist/api/formats.d.ts

@@ -0,0 +1,19 @@
+import { DestinationConfig, SourceConfig } from "../config/ioSchema";
+export type FileFormat = "csv" | "json" | "xml" | "excel" | "parquet" | "sqlite";
+export interface ReadOptions {
+    table?: string | undefined;
+    sheet?: string | undefined;
+    recordsPath?: string | undefined;
+    delimiter?: string | undefined;
+    encoding?: "utf-8" | "latin1" | undefined;
+}
+export interface WriteOptions {
+    sheet?: string | undefined;
+    delimiter?: string | undefined;
+    bom?: boolean | undefined;
+    root?: string | undefined;
+    record?: string | undefined;
+}
+export declare function detectFormat(filePath: string): FileFormat;
+export declare function sourceFromPath(filePath: string, options?: ReadOptions): SourceConfig;
+export declare function destinationFromPath(filePath: string, options?: WriteOptions): DestinationConfig;

package/dist/api/formats.js

@@ -0,0 +1,106 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectFormat = detectFormat;
+exports.sourceFromPath = sourceFromPath;
+exports.destinationFromPath = destinationFromPath;
+const path_1 = __importDefault(require("path"));
+const EXTENSIONS = {
+    ".csv": "csv",
+    ".tsv": "csv",
+    ".txt": "csv",
+    ".json": "json",
+    ".xml": "xml",
+    ".xlsx": "excel",
+    ".parquet": "parquet",
+    ".db": "sqlite",
+    ".sqlite": "sqlite",
+    ".sqlite3": "sqlite",
+};
+function defined(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, inner]) => inner !== undefined));
+}
+function detectFormat(filePath) {
+    const extension = path_1.default.extname(filePath).toLowerCase();
+    const format = EXTENSIONS[extension];
+    if (!format) {
+        throw new Error(`Não sei qual é o formato de "${filePath}" pela extensão. As que eu conheço: ${Object.keys(EXTENSIONS).join(", ")}.`);
+    }
+    return format;
+}
+function sourceFromPath(filePath, options = {}) {
+    const format = detectFormat(filePath);
+    switch (format) {
+        case "csv":
+            return defined({
+                type: "csv",
+                path: filePath,
+                delimiter: options.delimiter ??
+                    (path_1.default.extname(filePath).toLowerCase() === ".tsv"
+                        ? "\t"
+                        : undefined),
+                encoding: options.encoding,
+            });
+        case "json":
+            return defined({
+                type: "json",
+                path: filePath,
+                recordsPath: options.recordsPath,
+            });
+        case "xml":
+            return defined({
+                type: "xml",
+                path: filePath,
+                recordsPath: options.recordsPath,
+            });
+        case "excel":
+            return defined({
+                type: "excel",
+                path: filePath,
+                sheet: options.sheet,
+            });
+        case "parquet":
+            return { type: "parquet", path: filePath };
+        case "sqlite":
+            if (!options.table) {
+                throw new Error(`Pra ler o SQLite "${filePath}", diga qual tabela (table).`);
+            }
+            return { type: "sqlite", path: filePath, table: options.table };
+    }
+}
+function destinationFromPath(filePath, options = {}) {
+    const format = detectFormat(filePath);
+    switch (format) {
+        case "csv":
+            return defined({
+                type: "csv",
+                path: filePath,
+                delimiter: options.delimiter ??
+                    (path_1.default.extname(filePath).toLowerCase() === ".tsv"
+                        ? "\t"
+                        : undefined),
+                bom: options.bom,
+            });
+        case "json":
+            return { type: "json", path: filePath };
+        case "xml":
+            return defined({
+                type: "xml",
+                path: filePath,
+                root: options.root,
+                record: options.record,
+            });
+        case "excel":
+            return defined({
+                type: "excel",
+                path: filePath,
+                sheet: options.sheet,
+            });
+        case "parquet":
+            return { type: "parquet", path: filePath };
+        case "sqlite":
+            throw new Error("Ainda não dá pra gravar em SQLite. Escolha outro formato pra saída.");
+    }
+}

package/dist/api/index.d.ts

@@ -0,0 +1,8 @@
+export { detectFormat, sourceFromPath, destinationFromPath } from "./formats";
+export type { FileFormat, ReadOptions, WriteOptions } from "./formats";
+export { readRows, writeRows, convert, DEFAULT_PENDING_NAME } from "./rows";
+export type { Input, Output, ReadRowsOptions, WriteRowsOptions, ConvertOptions, } from "./rows";
+export { clean, fillEmpty, combineColumns, validate, dedupe, merge, mergeColumnsFor, defineConfig, defineRules, rulesSchema, } from "./clean";
+export type { Rules, ConfigInput, CleanOptions, CleanResult, DedupeOptions, MergeOptions, } from "./clean";
+export { describeColumns, listNormalizers, normalize } from "./inspect";
+export type { ColumnInfo, ColumnKind } from "./inspect";

package/dist/api/index.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalize = exports.listNormalizers = exports.describeColumns = exports.rulesSchema = exports.defineRules = exports.defineConfig = exports.mergeColumnsFor = exports.merge = exports.dedupe = exports.validate = exports.combineColumns = exports.fillEmpty = exports.clean = exports.DEFAULT_PENDING_NAME = exports.convert = exports.writeRows = exports.readRows = exports.destinationFromPath = exports.sourceFromPath = exports.detectFormat = void 0;
+var formats_1 = require("./formats");
+Object.defineProperty(exports, "detectFormat", { enumerable: true, get: function () { return formats_1.detectFormat; } });
+Object.defineProperty(exports, "sourceFromPath", { enumerable: true, get: function () { return formats_1.sourceFromPath; } });
+Object.defineProperty(exports, "destinationFromPath", { enumerable: true, get: function () { return formats_1.destinationFromPath; } });
+var rows_1 = require("./rows");
+Object.defineProperty(exports, "readRows", { enumerable: true, get: function () { return rows_1.readRows; } });
+Object.defineProperty(exports, "writeRows", { enumerable: true, get: function () { return rows_1.writeRows; } });
+Object.defineProperty(exports, "convert", { enumerable: true, get: function () { return rows_1.convert; } });
+Object.defineProperty(exports, "DEFAULT_PENDING_NAME", { enumerable: true, get: function () { return rows_1.DEFAULT_PENDING_NAME; } });
+var clean_1 = require("./clean");
+Object.defineProperty(exports, "clean", { enumerable: true, get: function () { return clean_1.clean; } });
+Object.defineProperty(exports, "fillEmpty", { enumerable: true, get: function () { return clean_1.fillEmpty; } });
+Object.defineProperty(exports, "combineColumns", { enumerable: true, get: function () { return clean_1.combineColumns; } });
+Object.defineProperty(exports, "validate", { enumerable: true, get: function () { return clean_1.validate; } });
+Object.defineProperty(exports, "dedupe", { enumerable: true, get: function () { return clean_1.dedupe; } });
+Object.defineProperty(exports, "merge", { enumerable: true, get: function () { return clean_1.merge; } });
+Object.defineProperty(exports, "mergeColumnsFor", { enumerable: true, get: function () { return clean_1.mergeColumnsFor; } });
+Object.defineProperty(exports, "defineConfig", { enumerable: true, get: function () { return clean_1.defineConfig; } });
+Object.defineProperty(exports, "defineRules", { enumerable: true, get: function () { return clean_1.defineRules; } });
+Object.defineProperty(exports, "rulesSchema", { enumerable: true, get: function () { return clean_1.rulesSchema; } });
+var inspect_1 = require("./inspect");
+Object.defineProperty(exports, "describeColumns", { enumerable: true, get: function () { return inspect_1.describeColumns; } });
+Object.defineProperty(exports, "listNormalizers", { enumerable: true, get: function () { return inspect_1.listNormalizers; } });
+Object.defineProperty(exports, "normalize", { enumerable: true, get: function () { return inspect_1.normalize; } });

package/dist/api/inspect.d.ts

@@ -0,0 +1,13 @@
+import { TableRow } from "../types";
+export type ColumnKind = "número" | "texto" | "misto" | "vazio";
+export interface ColumnInfo {
+    name: string;
+    filled: number;
+    empty: number;
+    distinct: number;
+    kind: ColumnKind;
+    examples: string[];
+}
+export declare function describeColumns(rows: TableRow[]): ColumnInfo[];
+export declare function listNormalizers(): string[];
+export declare function normalize(name: string, value: string | number): string | number | null;

package/dist/api/inspect.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeColumns = describeColumns;
+exports.listNormalizers = listNormalizers;
+exports.normalize = normalize;
+const header_1 = require("../io/header");
+const normalizers_1 = require("../normalizers");
+const registry_1 = require("../normalizers/registry");
+const EXAMPLES = 3;
+function isEmpty(value) {
+    return value === null || value === undefined || value === "";
+}
+function kindOf(values) {
+    if (values.length === 0)
+        return "vazio";
+    const numbers = values.filter((value) => typeof value === "number").length;
+    if (numbers === values.length)
+        return "número";
+    return numbers === 0 ? "texto" : "misto";
+}
+function describeColumns(rows) {
+    return (0, header_1.buildHeader)(rows).map((name) => {
+        const present = rows
+            .map((row) => row[name])
+            .filter((value) => !isEmpty(value));
+        const distinct = new Set(present.map((value) => String(value)));
+        return {
+            name,
+            filled: present.length,
+            empty: rows.length - present.length,
+            distinct: distinct.size,
+            kind: kindOf(present),
+            examples: [...distinct].slice(0, EXAMPLES),
+        };
+    });
+}
+function listNormalizers() {
+    (0, normalizers_1.registerBuiltinKeyNormalizers)();
+    return (0, registry_1.listKeyNormalizers)();
+}
+function normalize(name, value) {
+    (0, normalizers_1.registerBuiltinKeyNormalizers)();
+    return (0, registry_1.getKeyNormalizer)(name)(value)?.key ?? null;
+}

package/dist/api/parse.d.ts

@@ -0,0 +1,2 @@
+import { z } from "zod";
+export declare function parseWith<T extends z.ZodType>(schema: T, value: unknown, label: string): z.infer<T>;