def-props
v1.0.0
Published
Defines multiple object properties all at once, optionally with shared settings.
Downloads
6,139
Maintainers
Readme
def-props
Defines multiple object properties all at once, optionally with shared settings.
Read more about property descriptor settings at Object.defineProperty()
.
Installation
Requires Node.js 8.3.0 or above.
npm i def-props
API
The module exports a single function.
Parameters
obj
(object): The object (or function) to which you want to add properties.props
(object): This must be one of the following:- An object whose keys are property names and whose values are property descriptors for the new object.
- An array (or other iterable) of key-value pairs for the object.
- An array (or other iterable) of key-descriptor pairs for the object’s properties (if
descs
is set totrue
).
- Optional: Object argument:
descDefaults
(plain object): A collection of descriptor settings (namely,configurable
,enumerable
, and/orwritable
) that will be applied to every property created on the new object. If you would like all these settings to be undefined, provide an empty object. Omit this option if you have specified complete descriptors inprops
or if you want the module to use simple assignment. If you provided property descriptors inprops
, the contents ofdescDefaults
will serve as default values for those descriptors. If you specifywritable
indescDefaults
, it will be skipped automatically for descriptors that contain getters or setters, since such descriptors cannot containwritable
.descs
(boolean): Used to disambiguate the purpose of the values inprops
. If set totrue
, the values inprops
will be interpreted as property descriptor objects. If set tofalse
, the values inprops
will be used as values for the new object. Defaults tofalse
ifprops
is an iterable; otherwise defaults totrue
.throwIfEquivKeys
(Error, string, or boolean): Only applies ifprops
is an array. Set this to throw an error if aprops
array contains keys that would be considered duplicates in the context of an object. For example: a Map can have keys that are objects, but those keys will all likely evaluate to[object Object]
and overwrite each other if made property keys in an object. Similarly, whereas a Map can have distinct1
(number) and'1'
(string) keys, these would be considered the same in an object context. If such a conflict exists and if this option is set to an Error object, the provided Error will be thrown as-is. An error message string will be used to construct aTypeError
. A value oftrue
will throw aTypeError
with a default error message. A value offalse
is the same as the default behavior, which is that later equivalent keys will silently overwrite the earlier ones.
Return Value
Returns the modified obj
.
Examples
Object of Key-Descriptor Pairs
In this example, we define two getters on an object.
const defProps = require('def-props')
const obj = {}
defProps(obj, {
a: {get: () => 1},
b: {get: () => 2},
})
obj.a // 1
obj.b // 2
Supplementing Descriptors with Default Settings
Whenever you’re using the module in a property descriptor mode, you can specify settings to be applied to all property descriptors using descDefaults
.
const defProps = require('def-props')
const obj = {}
defProps(obj, {
a: {get: () => 1}, // `writable` (below) will be ignored for this property
b: {value: 2},
}, {
descDefaults: {configurable: true, writable: true},
})
Since trying to set writable
in a descriptor that also specifies a getter or setter will throw an error, the module will ignore the value of writable
in descDefaults
when creating the descriptor for a get/set property, such as the a
property in the example above.
Array of Key-Value Pairs
You can also use this module together with an entries array. For example, this snippet defines key-value pairs on an object as read-only properties.
const defProps = require('def-props')
const obj = {}
defProps(
obj,
[['a', 1], ['b', 2]],
{descDefaults: {writable: false}}
)
obj.a // 1
obj.b // 2
obj.a = 123 // TypeError: Cannot set property a of #<Object> which has only a getter
Array of Key-Descriptor Pairs
In addition to providing an array of key-value pairs as in the two examples above, you can also provide an array of keys paired with object property descriptors, if descs
is set to true
.
const defProps = require('def-props')
const obj = {}
defProps(
obj,
[
['a', {get: () => 1}],
['b', {get: () => 2}],
],
{descs: true}
)
obj.a // 1
obj.b // 2
obj.a = 123 // TypeError: Cannot set property a of #<Object> which has only a getter
Related
- new-object: Same as this module, but creates a new object instead of modifying an existing one.