@suns-echoes/object-utils

About project

The library of useful utilities for objects manipulations.

⮝

Installation using npm:

Using npm:

npm i @suns-echoes/object-utils

npm i --save-dev @suns-echoes/object-utils

⮝

Usage

As Node.js module (CJS):

// Default import of the entire library:
const ArrayUtils = require('@suns-echoes/object-utils/cjs');
// Named import of the entire library:
const { ArrayUtils } = require('@suns-echoes/object-utils/cjs/object-utils');

// Import single util:
const { diff } = require('@suns-echoes/object-utils/cjs/utils/compare/diff');

As ES6 module (ESM):

// Default import of the entire library:
import ArrayUtils from '@suns-echoes/object-utils/esm/index.js';
// Named import of the entire library:
import { ArrayUtils } from '@suns-echoes/object-utils/esm/object-utils.js';

// Import single util:
import { diff } from '@suns-echoes/object-utils/esm/utils/compare/diff.js';

⮝

Module content

For a more comprehensive description of the methods please check the corresponding source files.

Method variants

• The generic methods (ones that does not end with *-ex nor *-strict) treats arrays as generic object and checks for own enumerable properties rather than iterable items.
• The *-ex functions are exclusive for objects. Arrays will be treated like primitive values and will not be traversed. Generic objects and arrays will overwrite each other on assignment or merge.
• The *-strict functions distinguish between arrays and objects and treat them as different types. Arrays will be checked only for iterable items. Generic objects and arrays will overwrite each other on assignment or merge.

The constants

• Missing - symbol used by diff method to indicate that element is missing;
• Same - symbol used by diff method to indicate that element did not change.

The check/ methods

• isCyclic - checks if object has cyclic references;
• isObjectLike - checks if entity is like object.

The compare/ methods

• diff - finds the shallow difference between two entities;
• diffDeep - finds the deep difference between two entities;
• diffDeepEx - similar to diff, see: *-ex method variant;
• diffDeepStrict - similar to diffDeep, see: *-strict method variant;
• eql - performs shallow equality check of two entities;
• eqlDeep - performs deep equality check of two entities;
• eqlDeepEx - similar to eqlDeep, see: *-ex method variant;
• eqlDeepStrict - similar to eqlDeep, see: *-strict method variant.

The create/ methods

• cloneDeep - creates deep clone of the object;
• cloneDeepEx - similar to cloneDeep, see: *-ex method variant;
• cloneDeepStrict - similar to cloneDeep, see: *-strict method variant;
• filter - creates a new object with filtered properties from source object;
• flat - creates a new object with flattened properties and sub-properties from the source object;
• flatEx - similar to flat, see: *-ex method variant;
• fromKV - creates a new object with properties matching the given key-value iterable;
• fromKVArray - creates a new object with properties matching the given key-value array;
• fromPath - creates a new nested object with sub-keys matching the given path;
• map - creates a new object with all property values rewritten by provided function;
• of - creates a new object using list of different sources;
• partial - creates new object with selected keys from the source object;
• squash - creates squashed copy of the object and its prototypes (from the oldest prototype to root);
• squashReverse - creates squashed copy of the object and its prototypes (from root to the oldest prototype);
• template - creates new object without properties other than sub-objects based on the template object structure;
• templateEx - similar to template, see: *-ex method variant.

The debug/ methods

• freezeDeep - deeply freezes the target object;
• invariableProxy - creates object proxy which will throw an error on any modification attempt on top level;
• invariableProxyDeep - creates object proxy which will throw an error on any modification attempt on any level.

The destroy/ methods

• blackhole - breaks all references and set all properties to undefined (this method is circular reference safe).

The extract/ methods

• entriesDeep - returns an array of [key, value] pairs of the object own enumerable properties including nested ones;
• entriesDeepEx - similar to entriesDeep, see: *-ex method variant;
• entriesDeepStrict - similar to entriesDeep, see: *-strict method variant;
• valuesDeep - returns an array of the object own enumerable properties including nested ones;
• valuesDeepEx - similar to valuesDeep, see: *-ex method variant;
• valuesDeepStrict - similar to valuesDeep, see: *-strict method variant.

The find/ methods

• any - finds if object has property that pass the test implemented by the provided function;
• every - finds if all object properties pass the test implemented by the provided function;
• find - finds the property in the object that pass the test implemented by the provided function;
• findAll - finds all properties in the object that pass the test implemented by the provided function;
• findKey - finds the key of the property in the object that pass the test implemented by the provided function;
• findAllKeys - finds all keys of the properties in the object that pass the test implemented by the provided function;
• getAllKeys - returns the list of all keys in the objects;
• goto - returns the property at the given "path";
• includes - finds if object has property that matches the search value;
• keyOf - finds the key of the first property in the object that matches the search value;
• some - finds if object has property that pass the test implemented by the provided function.

The iterate/ methods

• forEach - executes the provided function once for each property;
• forEachDeep - executes the provided function once for each property including nested ones;
• forEachDeepEx - similar to forEachDeep, see: *-ex method variant;
• forEachDeepStrict - similar to forEachDeep, see: *-strict method variant;
• getOwnPropertyIteratorDeep - creates iterator that traverse all properties and sub-properties;
• getOwnPropertyIteratorDeepEx - similar to getOwnPropertyIteratorDeep, see: *-ex method variant;
• getOwnPropertyIteratorDeepStrict - similar to getOwnPropertyIteratorDeep, see: *-strict method variant.

The modify/ methods

• assignDeep¹ - performs deep copy of all enumerable own properties and sub-properties from one or more source objects to the target object;
• assignDeepEx¹ - similar to assignDeep, see: *-ex method variant;
• assignDeepStrict¹ - similar to assignDeep, see: *-strict method variant;
• assignDeepCloneDiff¹ - assigns cloned differences between target and source to the target and return assigned changes as diff tree;
• assignDeepCloneDiffEx¹ - similar to assignDeepCloneDiff, see: *-ex method variant;
• assignDeepCloneDiffStrict¹ - similar to assignDeepCloneDiff, see: *-strict method variant;
• defineInternalProperties - creates and assigns new object to the given context object;
• mergeDeep² - performs deep copy of all enumerable own properties and sub-properties from one or more source objects to the target object;
• mergeDeepEx² - similar to mergeDeep, see: *-ex method variant;
• mergeDeepStrict² - similar to mergeDeep, see: *-strict method variant;

¹ The assign-* methods allows the target property to be overwritten by "undefined" value from source property.

² The merge-* methods prevents target property from being overwritten by "undefined" value from source property.

⮝

Version history

1.1.0 [Current release]

Update README with list of exported methods and short description. Clarify many methods comments.

New methods:

• findAll
• findAllKeys
• getOwnPropertyIteratorDeep
• getOwnPropertyIteratorDeepEx
• getOwnPropertyIteratorDeepStrict

Other:

• VSCode debugger configuration for entire project.

1.0.0

The first stable release of this library.

⮝

License

Licensed under MIT

Copyright (c) 2021-2022 Aneta Suns