@ethersproject/properties

What is @ethersproject/properties?

@ethersproject/properties is a utility library that is part of the ethers.js library suite. It provides a set of tools for defining and managing properties in JavaScript objects, particularly useful in the context of Ethereum and blockchain development. The package helps in creating immutable objects, defining properties with specific characteristics, and managing the metadata of objects.

What are @ethersproject/properties's main functionalities?

Defining Immutable Properties

This feature allows you to define properties on an object that cannot be changed once set. This is particularly useful for creating constants or ensuring that certain values remain unchanged throughout the lifecycle of an object.

const { defineReadOnly } = require('@ethersproject/properties');

const obj = {};
defineReadOnly(obj, 'immutableProperty', 42);
console.log(obj.immutableProperty); // 42
obj.immutableProperty = 100; // Error: Cannot assign to read only property 'immutableProperty'

Defining Properties with Metadata

This feature allows you to define properties with specific characteristics such as enumerability and writability. This is useful for creating more complex objects where you need fine-grained control over property behavior.

const { defineProperty } = require('@ethersproject/properties');

const obj = {};
defineProperty(obj, 'propertyWithMetadata', 42, { enumerable: true, writable: true });
console.log(obj.propertyWithMetadata); // 42
obj.propertyWithMetadata = 100;
console.log(obj.propertyWithMetadata); // 100

Shallow Copying Objects

This feature allows you to create a shallow copy of an object. This is useful when you need to duplicate an object but do not want to affect the original object when making changes to the copy.

const { shallowCopy } = require('@ethersproject/properties');

const obj = { a: 1, b: 2 };
const copy = shallowCopy(obj);
console.log(copy); // { a: 1, b: 2 }
copy.a = 3;
console.log(obj.a); // 1

Other packages similar to @ethersproject/properties

lodash

Lodash is a modern JavaScript utility library delivering modularity, performance, and extras. It provides a wide range of utility functions for common programming tasks, including object manipulation, which can be used to achieve similar functionalities as @ethersproject/properties. However, Lodash is more general-purpose and not specifically tailored for Ethereum development.

immutable

Immutable.js provides persistent immutable data structures. It is particularly useful for managing state in applications where immutability is a key concern. While it offers more comprehensive immutability features compared to @ethersproject/properties, it is not specifically designed for Ethereum or blockchain development.

object-assign

Object.assign is a simple utility for copying the values of all enumerable own properties from one or more source objects to a target object. It is a native JavaScript method and can be used to achieve shallow copying similar to the shallowCopy function in @ethersproject/properties. However, it lacks the additional property management features provided by @ethersproject/properties.

README

Property Utilities

This sub-module is part of the ethers project.

It contains several useful utility methods for managing simple objects with defined properties.

For more information, see the documentation.

Importing

Most users will prefer to use the umbrella package, but for those with more specific needs, individual components can be imported.

const {

    defineReadOnly,

    getStatic,

    resolveProperties,
    checkProperties,

    shallowCopy,
    deepCopy,

    Description,

    // Types

    Deferrable

} = require("@ethersproject/properties");

License

MIT License