or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-ethersproject--properties

Property utility functions for the ethers.js ecosystem, providing object property management and manipulation capabilities.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@ethersproject/properties@5.8.x

To install, run

npx @tessl/cli install tessl/npm-ethersproject--properties@5.8.0

index.mddocs/

@ethersproject/properties

@ethersproject/properties provides essential property utility functions for the ethers.js ecosystem, focusing on object property management and manipulation. It offers core utilities for defining read-only properties, resolving asynchronous properties in objects, performing shallow and deep copying operations with immutability guarantees, and validating object properties against defined schemas.

Package Information

  • Package Name: @ethersproject/properties
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @ethersproject/properties

Core Imports

import { 
  defineReadOnly, 
  getStatic, 
  resolveProperties, 
  checkProperties, 
  shallowCopy, 
  deepCopy, 
  Description,
  type Deferrable 
} from "@ethersproject/properties";

For CommonJS:

const { 
  defineReadOnly, 
  getStatic, 
  resolveProperties, 
  checkProperties, 
  shallowCopy, 
  deepCopy, 
  Description 
} = require("@ethersproject/properties");

Basic Usage

import { defineReadOnly, deepCopy, resolveProperties, type Deferrable } from "@ethersproject/properties";

// Define read-only properties
const obj = {};
defineReadOnly(obj, "version", "1.0");
// obj.version is now "1.0" and cannot be changed

// Deep copy with immutability
const original = { users: [{ name: "Alice" }], count: 42 };
const copy = deepCopy(original);
// copy is a frozen deep copy, original is unchanged

// Resolve promise properties
const asyncData: Deferrable<{ name: string; age: number }> = {
  name: Promise.resolve("Bob"),
  age: Promise.resolve(25)
};
const resolved = await resolveProperties(asyncData);
// resolved = { name: "Bob", age: 25 }

Capabilities

Property Definition

Create read-only properties on objects with proper enumerable configuration.

/**
 * Defines a read-only property on an object
 * @param object - Target object to define property on
 * @param name - Property name (must be a key of the object type)
 * @param value - Property value
 */
function defineReadOnly<T, K extends keyof T>(object: T, name: K, value: T[K]): void;

Static Method Resolution

Crawl up the constructor chain to find static methods, useful for prototype chain traversal.

/**
 * Crawls up constructor chain to find a static method
 * @param ctor - Constructor function to search
 * @param key - Static method name to find
 * @returns The static method or null if not found
 */
function getStatic<T>(ctor: any, key: string): T | null;

Asynchronous Property Resolution

Resolve all promise properties in an object, converting deferred values to their resolved forms.

/**
 * Resolves all promise properties in an object
 * @param object - Object with potentially promised properties
 * @returns Promise resolving to object with all promises resolved
 */
async function resolveProperties<T>(object: Readonly<Deferrable<T>>): Promise<T>;

Usage Example:

const deferredUser: Deferrable<{ id: number; name: string; email: string }> = {
  id: 123,
  name: fetchUserName(123),
  email: fetchUserEmail(123)
};

const user = await resolveProperties(deferredUser);
// All promises resolved: { id: 123, name: "Alice", email: "alice@example.com" }

Property Validation

Validate object properties against a defined schema, throwing errors for invalid properties.

/**
 * Validates object properties against a schema
 * @param object - Object to validate
 * @param properties - Schema defining valid property names
 * @throws ArgumentError if object is invalid or contains unknown properties
 */
function checkProperties(object: any, properties: { [name: string]: boolean }): void;

Usage Example:

const transaction = { to: "0x123", value: "100", gasLimit: "21000", extra: "invalid" };
const validProps = { to: true, value: true, gasLimit: true, gasPrice: true };

try {
  checkProperties(transaction, validProps);
} catch (error) {
  // Throws: invalid object key - extra
}

Shallow Copying

Create a shallow copy of an object, copying only the first level of properties.

/**
 * Creates a shallow copy of an object
 * @param object - Object to copy
 * @returns Shallow copy with same property values
 */
function shallowCopy<T>(object: T): T;

Deep Copying

Create a deep copy of an object with immutability guarantees. The resulting copy is frozen and handles circular references.

/**
 * Creates a deep copy of an object with immutability guarantees
 * @param object - Object to deep copy
 * @returns Frozen deep copy of the object
 */
function deepCopy<T>(object: T): T;

Usage Example:

const complex = {
  metadata: { version: 1, tags: ["prod", "v2"] },
  data: [{ id: 1, active: true }, { id: 2, active: false }],
  config: { timeout: 5000 }
};

const copy = deepCopy(complex);
// copy is completely independent and frozen
// changing original.data[0].active won't affect copy

Immutable Data Descriptors

Create immutable data descriptor objects that deep copy all provided properties.

/**
 * Immutable data descriptor class
 * Deep copies all properties during construction
 */
class Description<T = any> {
  /**
   * Creates a new Description with deep-copied properties
   * @param info - Object containing properties to copy
   */
  constructor(info: { [K in keyof T]: T[K] });
}

Usage Example:

const userInfo = {
  profile: { name: "Charlie", preferences: { theme: "dark" } },
  settings: { notifications: true }
};

const userDescription = new Description(userInfo);
// All properties are deep copied and immutable

Types

/**
 * Utility type where each property can be either the value or a Promise of the value
 * Used with resolveProperties to handle asynchronous property resolution
 */
type Deferrable<T> = {
  [K in keyof T]: T[K] | Promise<T[K]>;
};