npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@cahmoraes93/immuter

v1.3.0

Published

Pacote para trabalhar com imutabilidade e clonagem profunda de estruturas de dados

Downloads

34

Readme

Immuter

A biblioteca Immuter fornece utilitários para trabalhar com dados imutáveis em JavaScript e TypeScript. Ela oferece métodos para criar cópias imutáveis de objetos e estruturas de dados complexas, permitindo modificar essas cópias sem afetar os dados originais.

NPM Version > License

Com o Immuter, você pode:

  • Produzir objetos imutáveis com base em um objeto de origem, aplicando modificações através de uma função de produtor, ex: Immuter.produce.
  • Clonar objetos recursivamente de forma imutável, preservando a estrutura e os valores originais.
  • Trabalhar com estruturas de dados complexas, como arrays, mapas, conjuntos e datas, mantendo a imutabilidade em todos os níveis, Immuter.clone.
  • Por padrão, Immuter.produce e Immuter.clone geram clones recursivos e imutáveis com chamadas de Object.freeze, no entanto é possível desligar este comportamento globalmente ou por chamada. Isso pode ser feito por meio de uma interface amigável.
    • Para desligar: Immuter.global.not.freeze().
    • Para ligar: Immuter.global.freeze().
    • Para desligar o comportamento imutável para cada chamada método: Immuter.not.freeze.clone ou Immuter.not.freeze.produce. (Isto faz com que a imutabilidade seja desligada somente na chamada atual, as próximas serão imutáveis, a menos que seja desligado globalmente)

A abordagem imutável traz benefícios significativos para o desenvolvimento de software, como facilitar o rastreamento de alterações, evitar efeitos colaterais indesejados e simplificar o controle de estado em aplicações complexas.

A biblioteca Immuter é fácil de usar e pode ser integrada em projetos JavaScript e TypeScript. Ela fornece uma API intuitiva e flexível para criar e manipular dados imutáveis, oferecendo suporte para objetos, estruturas aninhadas e tipos de dados comuns.

Instalação

npm install @cahmoraes93/immuter

API

Immuter

Método produce

O método produce é uma função fornecida pela biblioteca Immuter para criar uma nova versão imutável de um objeto ou estrutura de dados complexa.

Assinatura

produce<T>(source: T, producer: (draft: Draft<T>) => void): T

Parâmetros

  • source: O objeto ou estrutura de dados base: (Object, Map, Array, Set, Date).
  • producer: Uma função que recebe um rascunho (draft) do objeto de origem e permite realizar modificações nesse rascunho. Essas modificações são usadas para criar a nova versão imutável.

Descrição

O método produce permite criar uma nova versão imutável de um objeto ou estrutura de dados complexa, enquanto mantém a semântica de imutabilidade e evita mutações indesejadas nos dados.

A função producer é chamada com um rascunho (draft) do objeto base de origem. Esse rascunho permite que você faça modificações como se estivesse trabalhando diretamente no objeto original. No entanto, o rascunho é uma cópia isolada e não afeta o objeto original.

const source = {
  name: 'John',
  age: 30,
  hobbies: ['music'],
}

const nextState = Immuter.produce(source, (draft) => {
  draft.age = 31
  draft.hobbies.push('sport')
})

console.log(nextState) // { name: 'John', age: 31, hobbies: ['music', 'sport'] }
console.log(nextState === source) // false

Durante a execução da função producer, você pode modificar o rascunho livremente, aplicando as alterações necessárias. Todas as modificações feitas no rascunho são registradas e usadas para criar uma nova versão imutável do objeto.

O método produce é particularmente útil quando você precisa fazer modificações em objetos complexos, como objetos aninhados, arrays, mapas ou conjuntos, enquanto mantém a imutabilidade dos dados.

const source = {
  name: 'John',
  address: {
    city: 'London',
    country: 'UK',
  },
}

const nextState = Immuter.produce(source, (draft) => {
  draft.address.city = 'Paris'
})

console.log(nextState) // { name: 'John', address: { city: 'Paris', country: 'UK' } }
console.log(nextState === source) // false

O método produce garante que a nova versão imutável seja criada de forma eficiente, aproveitando a estrutura do objeto original e aplicando apenas as alterações necessárias.

É possível configurar o método produce para não realizar a clonagem imutável do resultado. A API Immuter implementa o padrão Fluent API para fornecer uma interface amigável para configurar o comportamento do método produce.

const nextState = Immuter.not.freeze.produce(source, (draft) => {
  draft.address.city = 'Paris'
})

console.log(Object.isFrozen(nextState)) // false

Método clone

O método clone é uma função auxiliar fornecida pela biblioteca Immuter para criar cópias imutáveis de objetos complexos, como objetos, arrays, mapas, conjuntos e datas.

Assinatura

clone<T>(source: T): T

Parâmetros

  • source: O objeto que será clonado.

Descrição

O método clone retorna uma nova cópia imutável do objeto de origem. A cópia é uma réplica exata do objeto original, preservando a estrutura e os valores dos seus elementos. No entanto, a cópia gerada é imutável, o que significa que não é possível realizar modificações nos seus elementos após a criação.

const source = {
  name: 'John',
  age: 30,
}

const clonedObject = Immuter.clone(source)

console.log(clonedObject) // { name: 'John', age: 30 }
console.log(clonedObject === source) // false

O método clone é útil quando você precisa criar cópias imutáveis de objetos para garantir a preservação dos dados originais e evitar mutações acidentais. Ele é particularmente útil em cenários onde a imutabilidade dos dados é crucial, como em aplicativos com arquiteturas baseadas em fluxo de dados unidirecional. Além disso, ao trabalhar com classes, toda a cadeia de protótipo é preservada no clone resultante.

É importante observar que o método clone realiza uma clonagem imutável e profunda de todos os objetos aninhados. Porém, é possível desligar o comportamento imutável utilizando Immuter.not.clone.

const source = {
  name: 'John',
  address: {
    city: 'London',
    country: 'UK',
  },
}

const immutableClonedObject = Immuter.clone(source)
console.log(immutableClonedObject) // { name: 'John', address: { city: 'London', country: 'UK' } }
console.log(immutableClonedObject.address === source.address) // false
console.log(Object.isFrozen(immutableClonedObject.address)) // true

const clonedObject = Immuter.not.freeze.clone(source)
console.log(clonedObject) // { name: 'John', address: { city: 'London', country: 'UK' } }
console.log(clonedObject.address === source.address) // false
console.log(Object.isFrozen(clonedObject.address)) // false

O método clone facilita a criação de cópias imutáveis de objetos complexos, proporcionando um controle refinado sobre a imutabilidade dos dados em sua aplicação.

Licença

Licença da biblioteca: MIT.