https://github.com/mearns/build-object-better
JavaScript utilities for building out object from properties
https://github.com/mearns/build-object-better
build-object javascript node nodejs npm object-builder
Last synced: about 1 month ago
JSON representation
JavaScript utilities for building out object from properties
- Host: GitHub
- URL: https://github.com/mearns/build-object-better
- Owner: mearns
- License: mit
- Created: 2018-11-09T18:31:09.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2023-03-04T02:58:06.000Z (about 2 years ago)
- Last Synced: 2025-03-07T04:46:58.717Z (about 2 months ago)
- Topics: build-object, javascript, node, nodejs, npm, object-builder
- Language: TypeScript
- Homepage: https://mearns.github.io/build-object-better/
- Size: 721 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# build-object-better
A javascript package for building objects from their properties. Meant to be a replacement for all of your:
```javascript
const object = keys.reduce((o, k) => {
o[k] = figureOutValue(k);
return o;
}, {});
```
Instead:
```javascript
const object = buildObject(keys, figureOutValue);
```
- [Detailed API docs](https://mearns.github.io/build-object-better/globals.html#buildobject)
- [Find the code on github](https://github.com/mearns/build-object-better/)
- [Find the package on npm](https://www.npmjs.com/package/build-object-better)
## Overview
The general form of the call is `buildObject(iterable, [[keySupplier], valueSupplier])`; in order to generate
the keys and values of the generated object, the iterable is iterated over and for each element, the `keySupplier`
and `valueSupplier` are invoked to generate the respective components of one key/value pair which will be
added as a property on the generated object.
Each supplier can either be a function to generate the value, an array of values corresponding to the order
of the `iterable`, or an `object` of properties that will supply the values. In addition, the `valueSupplier`
can be a primitive value which will be used as the value for all built properties. Details for each of these
options are described below.
Invoked with two arguments, the `valueSupplier` is provided by the caller, but a default `keySupplier` is used,
which simply uses the element from the `iterable` as a key. In other words, the `iterable` is treated as the
complete list of keys.
The function can also be invoked with a single argument. If this argument is an iterable object,
then the elements of the iterable define the properties of the built object, either as an array of two
elements (`[key, value]`), or as an object with a `key` property and a `value` property.
If the single argument is a non-iterable `object`, then it is shallow copied.
### Key Suppliers
When invoked with 3 arguments, the second argument is called the _key supplier_ and is used to generate
the keys, or property names, of the generated object.
| Key Supplier | Type of arg `K` | Description | Defined for arg `K` over `iterable` |
| ----------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------- |
| supplier function | function(elem:\*, idx:number, iterable:Iterable):string | A function that is invoked for each element in the `iterable` (first argument) to generate a corresponding key/property-name for the generated object. | `keySupplier = (elem, idx) => K(elem, idx, iterable)` |
| key list | Array.<string> | An array of keys/property-names corresponding to the ordered elements of `iterable`. | `keySupplier = (elem, idx) => K[idx]` |
| key map | Object | An object whose properties map the elements of the `iterable` to keys/property-names of the generated object. | `keySupplier = (elem) => K[elem]` |
### Value Suppliers
When invoked with 2 or 3 arguments, the last argument is called the _value supplier_ and is used to generate
the property values of the generated object.
| ValueSupplier | Type of arg `V` | Description | Defined for arg `V` over `iterable` |
| ----------------- | --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| supplier function | function(key:string, idx: number, keys:Iterable.<string>, elem:\*, iterable:Iterable):string | A function that is invoked for each element in the `iterable` (first argument), along with the corresponding key, to generate a corresponding property value for the generated object. | `valueSupplier = (elem, idx) => V(/* key */ keySupplier(elem, idx, iterable), idx, /* keys */ iterable.map(keySupplier), elem, iterable)` |
| value list | Array.<\*> | An array of values corresponding to the ordered elements of `iterable`. | `valueSupplier = (elem, idx) => V[idx]` |
| value source | Object | An object from which properties named by the keys will be copied. | `valueSupplier = (elem, idx) => V[keySupplier(elem, idx, iterable)]` |
| constant value | (string\|number\|boolean\|null\|undefined\|symbol) | A fixed value that will be used as the value for all properties installed on the build object | `valueSupplier = () => V` |
## API
_For more details on the API, see the [detailed API docs](https://mearns.github.io/build-object-better/globals.html#buildobject)_
### `buildObject(iterable, keySupplier, valueSupplier)`
Build an object from an iterable, with suppliers to generate the keys and values of the object's properties.
See above for an explanation of the different options for the `keySupplier` and `valueSupplier`.
### `buildObject(keys, valueSupplier)`
Build an object from an iterable of keys/property-names and a function to generate corresponding property values for each one.
See above for an explanation of the different options for the `valueSupplier`.
### `buildObject(entries)`
Build an object from an iterable of entries, each giving the name and value of one property in the object (e.g., as returned by `Object.entries`).
| Param | Type | Description |
| ------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| entries | Iterable<(Array\|{key, value})> | An iterable of entries, each entry specifying both the name and value of a property for your object. Each entry can be an Array, or an object.
If an Array, then the first item (index 0) in the Array is the name of the property (the "key"), and the second item (index 1) is the property value.
If the entry is not an array, then it is assumed to be an Object with a "key" property specifying the property name, and a "value" property specifying its value. |
### `buildObject(source)`
Build an object as a shallow-clone of another object. The returned object will have all the same _own_ properties as the provided
source, with the same value. Values are not cloned, but copied directly, thus non-primitive objects (such as Arrays and Objects)
will actually be references to the same in-memory value.
| Param | Type | Description |
| ------ | ------------------- | -------------------- |
| source | Object | The object to clone. |