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

babel-plugin-elsa

v2.3.1

Published

A babel plugin for replacing object and array literals with immutable versions

Downloads

21

Readme

Elsa

Mutability is dangerous, let it go!

Babel plugin that replaces object and array literals with immutable versions… that have super powers!

Build Status

Usage

Elsa is a babel plugin, to make use of it, you need to install it:

npm install --save babel-plugin-elsa

Add elsa as a plugin to your .babelrc config file (or babel section of package.json):

{
  "plugins": ["babel-plugin-elsa"]
}

Purpose

Immutability is cool these days. By never altering the contents of an object or array, and instead cloning them when you want to make a change, you avoid common bugs. It's especially popular in React development, but by no means exclusive to React.

There are great libraries out there like Immutable.js that provide a bunch of classes for making immutable objects, but wouldn't it be frosty to turn the default object and arrays into immutable objects?

Don't worry, there are no more puns past this point, they've been put on ice.

Elsa does two things:

  • It turns each object literal into a FrozenObject.
  • It changes each [array literal](array into a FrozenArray.

Both FrozenObjects and FrozenArrays are immutable classes included with Elsa. If you try to change their contents, they'll raise a TypeError since they've been frozen with Object.freeze. Assuming you have strict mode enabled (which you ought to do).

Elsa will:

// Turn this:
const person = {
  name: 'Jon',
  skills: ['ruby', 'javascript']
};

// into:
const person = new FrozenObject({
  name: 'Jon',
  skills: new FrozenArray('ruby', 'javascript')
});

Why create these new classes instead of just calling Object.freeze? To give them super powers, read on!

FrozenArray

Elsa turns all array literals (e.g. const coolNumbers = [1,5,-4,20];) into instances of FrozenArray.

FrozenArray inherits from JavaScript's built-in Array. This means it has a .length, is an instance of Array, and any of the methods that you'd expect like .forEach and .map.

The methods on Array that would typically mutate the array are reimplemented onFrozenArray to instead return a fresh instance of FrozenArray with changes applied. This includes push, pop, unshift, shift, sort, reverse, splice, and fill.

slice, map, and other methods that already return new arrays are still available, but return FrozenArray instances instead of a normal mutable array.

pop and shift return both the modified arrays and the shifted/popped values as two elements inside an array. That way you can do: [arr, poppedVal] = arr.pop().

Examples:

  • push: new FrozenArray(1,2,3).push(5) -> [1, 2, 3, 5]
  • pop: new FrozenArray(1,2,3).pop() -> [[1, 2], 3]
  • unshift: new FrozenArray(1,2,3).shift(0) -> [0,1,2,3]
  • shift: new FrozenArray(1,2,3).shift() -> [[2,3], 1]
  • sort: new FrozenArray(2,1,3).sort((a,b) => a - b) -> [1,2,3] Note: Return values are all instances of FrozenArray

FrozenObject

Elsa turns all object literals (e.g. const dog = { name: 'Loki', age: 4 };) into instances of FrozenObject.

FrozenObject is identical to a normal JavaScript object, but it has been frozen by Object.freeze and has a special method called update, provided by immutability-helper.

To see all the ways you can get a clone, with changes applied, using update see the immutability-helper docs: https://github.com/kolodny/immutability-helper

One example:

const dog = { name: 'Loki', age: 4, friends: ['Waffles', 'Mochi'] };
const dogClone = dog.update({ name: { $set: 'Loki 2.0' }, friends: { $push: ['Seamus'] } });
// dogClone now contains { name: 'Loki 2.0', age: 4, friends: ['Waffles', 'Mochi', 'Seamus'] }

Opting out of FrozenArray and FrozenObject

Elsa will ignore arrays created with new Array(1,2,3) or Array.of(1,2,3), which will produce old fashioned mutable arrays.

To create mutable objects, you can do new Object({ name: 'Loki' }), which Elsa will skip over, resulting in old fashioned mutable objects.

Gotchas and tips

  • Elsa will only alter object and array literals. If you create an object using a function of new constructor, it won't be frozen (at least not by Elsa). Only […] and {…} are frozen by Elsa.
  • Some libraries expect to receive mutable objects as their parameters. If you receive type errors in libraries that you use, try sending in an object created with new Object({…}).
  • Elsa only converts your code. Babel, and therefore Elsa, doesn't convert 3rd party modules. This means that any objects produced by libraries won't be frozen.
  • You can freeze objects returned by libraries by wrapping it with new FrozenObject(…).
  • If you don't use Elsa as a Baebl plugin, you can still use FrozenArray and FrozenObject with your code. Just do import FrozenArray from 'babel-plugin-elsa/frozen_array' and/or import FrozenObject from 'babel-plugin-elsa/frozen_object'.

Sample App

I've written a very basic todo app (of course) that makes use of Elsa.

License

ISC