Descriptors

JavaScript provides a number of functions that work with descriptors:

• Object.defineProperty()
• Object.defineProperties()
• Object.getOwnPropertyDescriptor()
• Object.getOwnPropertyDescriptors()

This module contains a collection of helpers to simplify some common tasks with descriptors.

The sister module aliases.js provides a set of helpers to alias existing properties using utilities from this module.

descriptors.js

Legend for tables

• API
  • descriptor — a property descriptor.
  • getter — a function with no arguments that returns a value.
  • setter — a function with one argument that sets a value.
  • initDescriptor — a descriptor that is used to set default values for getters/setters. Defaults to {enumerable: false, configurable: true}, which is available as the defaultDescriptor.
  • target — an object that will receive the descriptor.
  • source — an object that contains the descriptor.
  • force — if truthy, the descriptor will be added even if it already exists in the target.
  • names — an array of names as strings or symbols, a symbol, or a string containing a comma-separated list of names.

The following utilities are available:

Function	Return value	Description
makeGetter(getter, initDescriptor)	descriptor	Creates a getter descriptor.
makeSetter(setter, initDescriptor)	descriptor	Creates a setter descriptor.
makeAccessors(getter, setter, initDescriptor)	descriptor	Creates a getter and setter descriptor.
addDescriptor(target, names, descriptor, force)	target	Adds a descriptor to an object.
addDescriptors(target, dict, force)	target	Adds multiple descriptors to an object.
addAccessor(target, names, getter, setter, force)	target	Adds an accessor (getter and setter) to an object.
addGetter(target, names, getter, force)	target	Adds a getter to an object.
addGetters(target, dict, force)	target	Adds multiple getters to an object.
addProtoGetter(Class, names, getter, force)	Class.prototype	Adds a getter on a class's prototype.
addProtoGetters(Class, dict, force)	Class.prototype	Adds multiple getters on a class's prototype.
copyDescriptors(target, source, names, force)	target	Copies multiple descriptors from one object to another.

addDescriptors() uses descriptor objects organized as a dictionary. Its keys can be symbols or strings. Strings are treated as comma-separated lists of names.

addGetter() is the singular counterpart of addGetters() — it adds a single getter under one or more names (the names argument accepts the same forms as addDescriptor()).

addGetters() are similar to addDescriptors(), but instead of adding descriptors, descriptors are generated from functions. Internally, descriptors are created from those functions using makeGetter() with default values.

addProtoGetter() and addProtoGetters() are class-prototype-aware sugar — addProtoGetter(Foo, 'name', fn) is equivalent to addGetter(Foo.prototype, 'name', fn). Use these when targeting a class's prototype directly.

copyDescriptors() copies descriptors from one object to another (it can be the same object). names can be one of the following:

• A string containing a comma-separated list of names.
• A symbol.
• An array of symbols or strings.
• An object with keys as symbols or strings denoting a name of a descriptor from the source object. An associated value is a value suitable as the names argument of addDescriptor().

defaultDescriptor is a descriptor that is used to set default values for getters/setters. It is available as an export from this module so it can be modified globally if needed.

Examples

import {addGetters, copyDescriptors} from 'meta-toolkit/descriptors.js';

class Foo {
  constructor() {
    this.value = 0;
  }
  get triple() {
    return this.value * 3;
  }
}

addGetters(Foo.prototype, {
  half() {
    return this.value / 2;
  },
  double() {
    return this.value * 2;
  }
});

class Bar {
  constructor() {
    this.value = 0;
  }
}

copyDescriptors(Bar.prototype, Foo.prototype, 'triple, double');

class Baz {
  constructor() {
    this.value = 0;
  }
}

copyDescriptors(Baz.prototype, Foo.prototype, {
  double: 'x2',
  triple: 'x3'
});

Exports

All functions are exported by their names. There is no default export.