JSPM

@designliquido/delegua-dados

0.0.0
  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 12
  • Score
    100M100P100Q53073F
  • License MIT

Biblioteca para análise de dados, baseada na biblioteca Pandas do Python, adaptada para o ambiente de Delégua.

Package Exports

    This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@designliquido/delegua-dados) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

    Readme

    📊 delegua-dados

    Biblioteca de análise de dados para TypeScript/JavaScript, inspirada em Pandas e integrada com o interpretador Delégua.

    Status Tests Browser Compatible Zero Dependencies License


    📋 Visão Geral

    delegua-dados é uma biblioteca TypeScript que implementa as funcionalidades principais de Pandas para análise de dados no interpretador Delégua.

    ✨ Características Principais

    • 100% TypeScript - Type-safe, sem qualquer código JavaScript
    • Zero Dependências - Apenas TypeScript nativo
    • Browser Compatible - Funciona em Node.js, navegadores, web workers, Electron
    • Platform-Agnostic - APIs agnósticas à plataforma para máxima compatibilidade
    • Nomes em Português - API totalmente em português
    • 380 Testes - Cobertura completa com Jest
    • 6 Fases Completas - Implementação full de todas as funcionalidades

    🚀 Início Rápido

    Instalação

    npm install @designliquido/delegua-dados

    Exemplo Básico

    import { RecorteDados, analisarCSV } from '@designliquido/delegua-dados';
    
    // Criar tabela
    const rd = new RecorteDados({
        nome: ['Alice', 'Bob', 'Charlie'],
        idade: [25, 30, 35],
        salario: [3000, 3500, 4000]
    });
    
    // Visualizar
    console.log(rd.cabeca());           // Primeiras 5 linhas
    console.log(rd.descrever());        // Estatísticas
    
    // Selecionar coluna
    const nomes = rd.selecionarColuna('nome');
    
    // Filtrar
    const maiores30 = rd.filtrar([false, true, true]);
    
    // Agrupar
    const porDept = rd.agruparPor('departamento').soma();
    
    // Análise agnóstica à plataforma
    const csv = `nome,idade,salario
    Alice,25,3000
    Bob,30,3500`;
    const rd2 = analisarCSV(csv);

    📚 Estrutura de Dados Principais

    Classes Fundamentais

    Classe Descrição Uso
    Indice Rótulos para linhas/colunas Indexação de dados
    Serie Array 1D com rótulos Colunas de dados
    RecorteDados Tabela 2D (também chamado de Data Frame) Dados estruturados
    IndiceTemporal Índice com datas/tempos Séries temporais
    Reamostrador Reamostragem de dados Upsampling/downsampling

    Exemplos de Criação

    // Serie
    const s = new Serie([1, 2, 3, 4, 5], {
        indice: ['a', 'b', 'c', 'd', 'e'],
        nome: 'Vendas'
    });
    
    // RecorteDados - Objeto com colunas
    const rd1 = new RecorteDados({
        'nome': ['Alice', 'Bob', 'Charlie'],
        'idade': [25, 30, 35],
        'salario': [3000, 3500, 4000]
    });
    
    // RecorteDados - Array de objetos
    const rd2 = new RecorteDados([
        { nome: 'Alice', idade: 25, salario: 3000 },
        { nome: 'Bob', idade: 30, salario: 3500 }
    ]);
    
    // RecorteDados - Cópia
    const rd3 = new RecorteDados(rd1);

    🎯 Operações Principais

    Visualização

    rd.cabeca(5);              // Primeiras N linhas
    rd.cauda(3);               // Últimas N linhas
    rd.paraTexto();            // String formatada
    rd.paraArrayObjetos();     // Array de objetos
    rd.info();                 // Informações de colunas
    rd.descrever();            // Estatísticas resumidas

    Seleção de Dados

    // Colunas
    rd.selecionarColuna('nome');              // Retorna Serie
    rd.selecionarColunas(['id', 'nome']);     // Retorna RecorteDados
    
    // Por posição (pos) - em desenvolvimento
    rd.pos[0];                 // Primeira linha
    rd.pos[0, 1];              // Célula específica
    
    // Por rótulo (rot) - em desenvolvimento
    rd.rot[0];                 // Linha com índice 0

    Modificação

    // Adicionar coluna
    rd.adicionarColuna('bônus', [300, 350, 400]);
    
    // Remover colunas
    rd.remover(['coluna_inutil']);
    
    // Renomear
    rd.renomear({ 'velho_nome': 'novo_nome' });
    
    // Ordenar
    rd.ordenarPor('idade');
    rd.ordenarPor('salario', false);  // Decrescente

    Limpeza de Dados

    // Valores nulos
    rd.temNulo();              // Detecta nulos
    rd.removerNulo();          // Remove linhas com nulos
    rd.preencherNulo(0);       // Preenche nulos
    
    // Duplicatas
    rd.removerDuplicatas();    // Remove linhas idênticas

    Transformações

    // Filtro
    const mascara = [true, false, true];
    rd.filtrar(mascara);
    
    // Aplicar função
    rd.aplicar((coluna) => {
        return new Serie(coluna.dados.map(x => x * 2));
    });
    
    // Operações vetorizadas
    const serie = rd.selecionarColuna('salario');
    const aumentado = serie.aplicar(x => x * 1.1);

    👥 GroupBy: Agrupamento e Agregação

    // Agrupamento simples
    const grupos = rd.agruparPor('departamento');
    
    // Múltiplas colunas
    const grupos = rd.agruparPor(['departamento', 'turno']);
    
    // Agregações
    grupos.soma();             // Sum
    grupos.media();            // Mean
    grupos.mediana();          // Median
    grupos.desvio();           // Std Dev
    grupos.minimo();           // Min
    grupos.maximo();           // Max
    grupos.contar();           // Count
    
    // Agregações múltiplas
    grupos.agregar({
        'salario': ['soma', 'media', 'desvio'],
        'idade': ['minimo', 'maximo']
    });

    🔄 I/O: Entrada e Saída

    CSV - Platform-Agnostic (Funciona em qualquer lugar)

    import { analisarCSV, paraCSV } from '@designliquido/delegua-dados';
    
    // Análise de string CSV (browser, Node.js, web workers, etc.)
    const csv = `produto,vendas,lucro
    A,1000,200
    B,800,150
    C,1500,300`;
    
    const rd = analisarCSV(csv);
    const stats = rd.descrever();
    
    // Conversão de volta para CSV
    const csvSaida = paraCSV(rd);
    const csvComIndice = paraCSV(rd, { indice: true });

    CSV - Node.js File-Based (Node.js apenas)

    import { lerCSV, escreverCSV } from '@designliquido/delegua-dados';
    
    // Ler arquivo
    const rd = lerCSV('dados.csv', {
        delimitador: ',',
        temCabecalho: true,
        colunas: ['id', 'nome', 'idade']
    });
    
    // Escrever arquivo
    escreverCSV(rd, 'saida.csv', {
        delimitador: ';',
        indice: true
    });

    CSV - Custom Filesystem (Qualquer plataforma com implementação custom)

    import { lerCSVComSistema, escreverCSVComSistema } from '@designliquido/delegua-dados';
    
    // Implementação customizada (ex: localStorage, URL fetch, etc.)
    const sistemaArquivos = {
        async lerArquivo(chave) {
            return localStorage.getItem(chave) || '';
        },
        async escreverArquivo(chave, conteudo) {
            localStorage.setItem(chave, conteudo);
        },
        async existeArquivo(chave) {
            return localStorage.getItem(chave) !== null;
        }
    };
    
    // Usar com sistema customizado
    const rd = await lerCSVComSistema('dados', sistemaArquivos);
    await escreverCSVComSistema(rd, 'resultado', sistemaArquivos);

    📈 Estatísticas

    const rd = lerCSV('dados.csv');
    
    // Valores únicos
    rd.selecionarColuna('categoria').unico();
    
    // Contagem de valores
    rd.selecionarColuna('status').contagemValores();
    
    // Operações estatísticas
    rd.descrever();        // Resumo estatístico
    rd.media();            // Média de colunas numéricas
    rd.soma();             // Soma
    rd.desvio();           // Desvio padrão
    rd.variancia();        // Variância
    rd.minimo();           // Valor mínimo
    rd.maximo();           // Valor máximo
    rd.mediana();          // Mediana

    ⏰ Séries Temporais

    import { 
        IndiceTemporal, 
        criarIntervaloDatas, 
        Resampler 
    } from '@designliquido/delegua-dados';
    
    // Criar índice temporal
    const datas = criarIntervaloDatas('2024-01-01', '2024-12-31', 'D');
    const ts = new Serie(valores, { indice: datas });
    
    // Parsing de datas
    const data = compreenderData('2024-01-15');
    const formatado = formatarData(data, 'yyyy-MM-dd');
    
    // Diferenças temporais
    const dias = diferencaDias(data1, data2);
    const horas = diferencaHoras(data1, data2);
    
    // Reamostragem
    const reamostrador = ts.reamostrar('M');  // Para mensal
    const media_mensal = reamostrador.media();
    const soma_mensal = reamostrador.soma();

    🔗 Merge, Concat, Join

    // Concatenação vertical (append)
    const combinado = concatenar([rd1, rd2]);
    
    // Concatenação horizontal
    const largo = concatenar([rd1, rd2], { axis: 1 });
    
    // Merge (SQL-like join)
    const resultado = mesclar(rd1, rd2, {
        on: 'id',
        tipo: 'inner'  // ou 'left', 'right', 'outer'
    });
    
    // Join por índice
    const juntado = rd1.juntar(rd2);

    🔀 Reshape: Transformação de Forma

    // Transpor
    const transposto = rd.transpor();
    
    // Pivot (wide para long)
    const dinamizado = rd.repivotar({
        indice: 'data',
        colunas: 'categoria',
        valores: 'valor'
    });
    
    // Melt (wide para long)
    const alongado = derreter(rd, {
        variaveisIds: ['id', 'nome'],
        variaveisValores: ['jan', 'fev', 'mar']
    });
    
    // Stack/Unstack
    const empilhado = rd.empilhar();
    const desempilhado = rd.desempilhar();

    💡 Exemplos Práticos

    Exemplo 1: Análise de Vendas

    import { lerCSV } from '@designliquido/delegua-dados';
    
    // 1. Carregar
    const vendas = lerCSV('vendas.csv');
    
    // 2. Limpeza
    const limpo = vendas
        .removerNulo()
        .removerDuplicatas();
    
    // 3. Análise
    const porRegiao = limpo
        .agruparPor('regiao')
        .agregar({
            'valor': ['soma', 'media'],
            'quantidade': ['sum'],
            'id': 'count'
        });
    
    // 4. Top 5
    const top5 = porRegiao
        .ordenarPor('valor_soma', false)
        .cabeca(5);
    
    // 5. Salvar
    escreverCSV(top5, 'resultado.csv');

    Exemplo 2: Processamento com CSV Agnóstico

    import { analisarCSV, paraCSV } from '@designliquido/delegua-dados';
    
    // Dados CSV como string (funciona em qualquer lugar)
    const csv = `produto,quantidade,preco
    Maçã,10,2.5
    Banana,15,1.2
    Laranja,8,3.0`;
    
    // Processar
    const rd = analisarCSV(csv);
    const rd2 = rd.adicionarColuna('total', 
        rd.selecionarColuna('quantidade').dados.map((q, i) => 
            q * rd.selecionarColuna('preco').dados[i]
        )
    );
    
    // Converter de volta
    const resultado = paraCSV(rd2);
    console.log(resultado);  // String CSV

    Exemplo 3: Séries Temporais

    import { criarIntervaloDatas } from '@designliquido/delegua-dados';
    
    // Gerar datas
    const datas = criarIntervaloDatas('2024-01-01', '2024-12-31', 'D');
    const temperaturas = [15.5, 16.2, 14.8, 17.1, 18.3];
    
    // Criar série temporal
    const ts = new Serie(temperaturas, { indice: datas });
    
    // Reamostragem para média diária
    const media_diaria = ts.reamostrar('D').media();

    🌐 Compatibilidade com Browser

    delegua-dados funciona nativamente em qualquer ambiente JavaScript. Use as funções agnósticas à plataforma:

    • Node.js - Funciona completamente
    • Navegador - Funciona (sem fs)
    • VSCode Web Extensions - Funciona
    • Web Workers - Funciona
    • Electron - Funciona

    Veja BROWSER_COMPATIBILITY.md para detalhes completos.


    🧪 Testes

    # Executar todos os testes
    npm run testes-unitarios
    
    # Modo watch (desenvolvimento)
    npm run testes-unitarios:assistidos
    
    # Cobertura
    npm run testes-unitarios -- --coverage

    Status Atual:

    • ✅ 380 testes passando (100%)
    • ✅ 15/15 test suites passando
    • ✅ Todas as funcionalidades cobertas

    📦 Estrutura do Projeto

    delegua-dados/
    ├── fontes/                          # Código principal
    │   ├── index.ts                     # Classe Indice
    │   ├── serie.ts                     # Classe Serie
    │   ├── recorte-dados.ts             # Classe RecorteDados
    │   ├── agrupamentos.ts              # GroupBy
    │   ├── transformacoes/              # Reshape, Merge, etc.
    │   ├── operacoes/                   # Operações vetorizadas
    │   ├── entrada-saida/               # I/O (CSV, JSON, Excel)
    │   ├── indice-temporal.ts           # IndiceTemporal
    │   ├── reamostrador.ts              # Reamostragem
    │   └── index.ts                     # Exports principais
    ├── testes/                          # 15 test suites, 380 testes
    ├── delegua-modulo.ts                # Exportação para Delégua
    ├── package.json
    ├── tsconfig.json
    └── jest.config.ts

    🎯 Fases Implementadas

    ✅ Fase 1: Core Data Structures

    • Classes Indice, Serie, RecorteDados
    • Seleção básica (rot, pos)
    • CSV I/O
    • Operações básicas

    ✅ Fase 2: Transformações

    • Reshape (pivot, melt, stack, unstack)
    • Merge/Concat/Join
    • Operações vetorizadas
    • Data cleaning (dropna, fillna)

    ✅ Fase 3: Análise

    • GroupBy com agregações
    • Estatísticas (mean, sum, std, var)
    • Rolling windows
    • Correlação/covariância

    ✅ Fase 4: I/O Avançado

    • JSON I/O
    • Excel I/O
    • SQL I/O
    • Otimizações

    ✅ Fase 5: Séries Temporais

    • IndiceTemporal (DatetimeIndex)
    • Reamostragem (upsampling/downsampling)
    • Funções de data/hora
    • Suporte a timezones

    ✅ Fase 6: Integração Delégua

    • delegua-modulo.ts completo
    • Metadata de tipos
    • Documentação em português
    • API pronta para uso

    💻 Desenvolvimento

    Requisitos

    • Node.js 18+
    • TypeScript 5.3+
    • npm 9+ ou yarn

    Setup

    # Instalar dependências
    npm install
    
    # Verificar TypeScript
    npm run testes-unitarios
    
    # Build
    npm run build

    Estrutura de Código

    • 100% TypeScript (strict mode)
    • JSDoc para todas as APIs públicas
    • Nomes em português
    • Sem dependências externas

    🏗️ Arquitetura

    Padrão de Três Camadas para I/O

    ┌─────────────────────────────────────────┐
    │  Aplicação (Browser/Node/Custom)        │
    ├─────────────────────────────────────────┤
    │  Dependency Injection (SistemaArquivos) │
    ├─────────────────────────────────────────┤
    │  Platform-Agnostic (analisarCSV/paraCSV)│
    ├─────────────────────────────────────────┤
    │  Platform Adapters (lerCSV/escreverCSV) │
    └─────────────────────────────────────────┘

    Isso garante compatibilidade com:

    • Node.js (com fs)
    • Navegadores (sem fs)
    • Implementações customizadas (dependency injection)

    📊 Comparação com Pandas

    Funcionalidade Pandas delegua-dados
    DataFrames
    Series
    Seleção (loc/iloc) ✅ (rot/pos)
    GroupBy
    Merge/Join
    Reshape
    CSV I/O
    JSON I/O
    Séries Temporais
    Browser Compat

    🤝 Contribuindo

    Contribuições são bem-vindas! Veja [CONTRIBUTING.MD] para mais informações.


    📄 Licença

    MIT © 2026 Design Líquido


    delegua-dados • Pandas-like data analysis for TypeScript and Delégua 🚀

    Desenvolvido para o interpretador Delégua