propertize Module

The propertize module exposes semantically named wrappers for the ECMAScript standard Object.defineProperty function.

API Overview

Update a single property descriptor

• value: set value
• configurable: set configurable/non-configurable
• enumerable: set enumerable/non-enumerable
• writable: set writable/non-writable
• get: define get
• set: define set

Update all property descriptors

• attribute: set enumerable, non-configurable, non-writable; set value; wipe get/set
• basic: set configurable, enumerable, writable; set value; wipe get/set
• field: set enumerable, writable, non-configurable; set value; wipe get/set
• hidden: set configurable, writable, non-enumerable; set value; wipe get/set
• internal: set configurable, non-enumerable, non-writable; set value; wipe get/set
• locked: set non-configurable, non-enumerable, non-writable; set value; wipe get/set
• readonly: set configurable, enumerable, non-writable; set value; wipe get/set
• setting: set writable, non-configurable, non-enumerable; set value; wipe get/set

Common use cases for getters/setters

• derived: set non-enumerable; define get; wipe set
• managed: set non-enumerable; define get/set
• normalized: set enumerable; define get/set
• triggered: set non-enumerable; define get/set
• validated: set enumerable; define get/set

Utility

• describe: return effective property descriptor

API Documentation

All propertize functions accept a target object or function. When a function is provided, the function's prototype will be updated rather than the function itself.

attribute(target, prop, [val])

Define an enumerable, non-configurable, non-writable property on an object. If no value is provided, use the existing value. Clear any getter or setter.

basic(target, prop, [val])

Define a configurable, enumerable, writable property on an object. If no value is provided, use the existing value. Clear any getter or setter.

configurable(target, prop, [flag])

Add or update the configurable descriptor for an object property. If no flag is provided, default to true. Note: it is not possible to set this flag to true once it has been set to false. This is by design. Once a property's configuration has been removed, it cannot be undone.

derived(target, prop, derive)

Define a non-enumerable property with a getter used to derive the value. The derive function's scope will be set to the object.

Example

var derived = require("propertize").derived,
    target = {fname: "Muhammad", lname: "Li"};

// configure a "name" property to be the concatenation of fname and lname
derived(target, "name", function() {
    return this.fname + " " + this.lname;
});

// "name" is now a derived property
assert(target.name === "Muhammad Li");

describe(target, prop)

Return the effective property descriptor for an object property. This may be the same descriptor as Object.getOwnPropertyDescriptor or it may be from a prototype.

Example

var desc = require("proprtize").describe({foo:42}, "foo");

assert(desc.value === 42);
assert(desc.writable === true);

enumerable(target, prop, [flag])

Add or update the enumerable descriptor for an object property. If no flag is provided, default to true.

field(target, prop, [val])

Define an enumerable, writable, non-configurable property on an object. If no value is provided, use the existing value. Clear any getter or setter.

get(target, prop, getter)

Update an object property getter.

hidden(target, prop, [val])

Define a configurable, writable, non-enumerable property on an object. If no value is provided, use the existing value. Clear any getter or setter.

internal(target, prop, [val])

Define a configurable, non-enumerable, non-writable property on an object. If no value is provided, use the existing value. Clear any getter or setter.

locked(target, prop, [val])

Define a non-configurable, non-enumerable, non-writable property on an object. If no value is provided, use the existing value. Clear any getter or setter.

managed(target, prop, set, get)

Define a non-enumerable property with a getter and setter. The set and get functions' scopes will be set to the object.

Example

var managed = require("propertize").managed,
    target = {data: {}};

// proxy the "id" property to/from the object's data
managed(target, "id", function(val) {
    this.data.id = val;
}, function() {
    return this.data.id;
});

normalized(target, prop, [val], normalize)

Define an enumerable property with a setter which normalizes values to a particular form before updating. If an optional value is passed, the value will skip normalization.

Example

var normalized = require("propertize").normalized,
    target = {};

// configure a "foo" property which normalizes values to int before updating.
normalized(target, "foo", function(val) {
    var intVal = parseInt(val);
    return isNaN(intVal) ? this.foo : intVal;
});

// set a string value
target.foo = "42";
assert(target.foo === 42);

// set a float value
target.foo = 42.24;
assert(target.foo === 42);

readonly(target, prop, [val])

Define a configurable, enumerable, non-writable property on an object. If no value is provided, use the existing value. Clear any getter or setter.

set(target, prop, setter)

Update an object property setter.

setting(target, prop, [val])

Define a writable, non-configurable, non-enumerable property on an object. If no value is provided, use the existing value. Clear any getter or setter.

triggered(target, prop, trigger)

Define a non-enumerable property which triggers a callback whenever the property is set.

Example

var triggered = require("propertize").triggered,
    target = {};

// call function whenever "foo" property is changed
triggered(target, "foo", function(is, was) {
    console.log("object foo changed from", was, "to", is);
});

validated(target, prop, [val], validate)

Define an enumerable property which rejects invalid updates. When attempting to set an invalid value, the update is silently ignored. If an optional value is passed, this initial value will be set without any validation.

Example

var validated = require("propertize").validated,
    target = {};

// configure a "foo" property which only acceptes string values
validated(target, "foo", function(val) {
    return typeof val === "string";
});

// set the "foo" property
target.foo = "Foo";
assert(target.foo === "Foo");

// attempt to set an invalid value
target.foo = 42;
assert(target.foo === "Foo");

value(target, prop, val)

Update an object property value, even if it's non-writable. Remove any get/set defined for the property.

writable(target, prop, [flag])

Add or update the writable descriptor for an object property. If no flag is provided, default to true.