@ethersproject/properties

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

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

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 }

/**
 * 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;

/**
 * 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;

/**
 * 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>;

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" }

/**
 * 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;

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
}

/**
 * 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;

/**
 * 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;

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 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] });
}

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

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

/**
 * 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]>;
};