Deep Tools

Uma robusta biblioteca utilitária TypeScript para acessar e pesquisar com segurança dentro de objetos e arrays profundamente aninhados em JavaScript.

Características

• Deep Get (deepGet): Recupera valores com segurança de objetos/arrays aninhados usando notação de caminho por ponto ou array. Alimentado por lodash.get para confiabilidade e flexibilidade. Suporta valores padrão.
• Deep Find by Key (deepFindByKey): Encontra o valor da primeira ocorrência de uma chave específica dentro de uma estrutura aninhada usando Busca em Largura (BFS).
• Deep Find by Value (deepFindByValue): Encontra todos os caminhos onde um valor específico ocorre dentro de uma estrutura aninhada usando Busca em Profundidade (DFS). Suporta funções de comparação personalizadas.
• Robusto: Lida graciosamente com entradas nulas/indefinidas, caminhos inexistentes e referências circulares.
• Seguro para Tipos: Escrito em TypeScript com definições de tipo incluídas. Usa unknown para encorajar uso mais seguro.
• Bem Testado: Inclui uma suíte de testes Jest abrangente.
• Documentado: Fornece comentários TypeDoc claros para documentação da API.

Instalação

npm install deep-tools

Funcionalidades

deepGet

Acessa propriedades aninhadas de objetos de forma segura usando path em string ou array.

import { deepGet } from 'deep-tools';

const obj = {
  a: {
    b: [
      { c: 1 }
    ]
  }
};

// Usando path string
const value1 = deepGet(obj, 'a.b[0].c'); // retorna 1

// Usando array path
const value2 = deepGet(obj, ['a', 'b', 0, 'c']); // retorna 1

// Com valor default
const value3 = deepGet(obj, 'x.y.z', 'default'); // retorna 'default'

deepFindByValue

Procura recursivamente por um valor dentro de um objeto e retorna o caminho completo até ele.

import { deepFindByValue } from 'deep-tools';

const obj = {
  a: {
    b: [
      { c: 123 },
      { d: 456 }
    ]
  }
};

const path = deepFindByValue(obj, 456); // retorna 'a.b[1].d'

API

deepGet(obj, path, defaultValue?)

Recupera o valor em um caminho específico dentro de um objeto.

• obj: O objeto a ser consultado
• path: O caminho para a propriedade (string ou array)
• defaultValue: Valor retornado se o caminho não existir
• Retorna: O valor encontrado ou o defaultValue

deepFindByValue(obj, value, compareFn?)

Encontra um valor em um objeto e retorna seu caminho.

• obj: O objeto a ser pesquisado
• value: O valor a ser encontrado
• compareFn: Função opcional de comparação customizada
• Retorna: O caminho como string ou undefined se não encontrado

TypeScript

A biblioteca é totalmente escrita em TypeScript e inclui definições de tipo.

import { deepGet } from 'deep-tools';

interface MyType {
  prop: {
    nested: string;
  }
}

const obj: MyType = {
  prop: {
    nested: "value"
  }
};

const value = deepGet<string>(obj, 'prop.nested');

Desenvolvimento

1. Clone o repositório

git clone https://github.com/kaikygr/deep-tools.git

2. Instale as dependências

npm install

3. Execute os testes

npm test

4. Build

npm run build

Scripts Disponíveis

• npm run build - Compila o código TypeScript
• npm test - Executa os testes
• npm run test:watch - Executa os testes em modo watch

Dependências

• lodash: ^4.17.21

Dependências de Desenvolvimento

• @types/jest: ^29.5.0
• @types/lodash: ^4.17.16
• jest: ^29.5.0
• ts-jest: ^29.1.0
• typedoc: ^0.28.2
• typescript: ^5.0.0

Licença

Este projeto está sob licença MIT.

Contribuindo

1. Faça o fork do projeto
2. Crie sua feature branch (git checkout -b feature/MinhaFeature)
3. Commit suas mudanças (git commit -m 'Adiciona nova feature')
4. Push para a branch (git push origin feature/MinhaFeature)
5. Abra um Pull Request

Autor

Kaiky Brito - github.com/kaikygr

Agradecimentos

• Lodash pelos utilitários
• Toda a comunidade open source