object

The maximum depth that a collapse will go to

Applies a target value onto a source object in-place safely - using dot-notation paths.

This can be as simple as safely applying a value even if targetObj may be null

targetObj = { id: 1, city: 'Seattle',  month: 'Aug', precip: 0.87 };
utils.object.applyPropertyValue(targetObj, 'state', 'WA');
// { id: 1, city: 'Seattle',  month: 'Aug', precip: 0.87, state: 'WA };

working with deeply nested objects

targetObj = { name: 'john smith', class: { name: 'ECON_101', professor: { last_name: 'Winklemeyer' }} };
utils.object.applyPropertyValue(targetObj, 'class.professor.first_name', 'René');
// { name: 'john smith', class: { name: 'ECON_101', professor: { last_name: 'Winklemeyer', first_name: 'René' }} };

or safely working with arrays of values

targetObj = { name: 'john smith', classes: [{ name: 'ECON_101' }] };
utils.object.applyPropertyValue(targetObj, 'classes[0].grade', 'A');
// { name: 'john smith', classes: [{ name: 'ECON_101', grade: 'A' }] };

Opposite of the extractObjectProperty, this takes a value / set of values and applies them along a given path on each of the target objects.

for example:

weather = [{ id: 1, city: 'Seattle',  month: 'Aug', precip: 0.87 },
  { id: 3, city: 'New York', month: 'Apr', precip: 3.94 },
  { id: 6, city: 'Chicago',  month: 'Apr', precip: 3.62 }];

cities = utils.object.extractObjectProperty('city');
// ['Seattle', 'New York', 'Chicago'];

//-- async process to geocode
geocodedCities = geocodeCity(cities);
// [{ city: 'Seattle', state: 'WA', country: 'USA' },
// { city: 'New York', state: 'NY', country: 'USA' },
// { city: 'Chicago', state: 'IL', country: 'USA' }]

utils.applyPropertyValues(weather, 'geo', geocodedCities);
 [{ id: 1, city: 'Seattle',  month: 'Aug', precip: 0.87, geo: { city: 'Seattle', state: 'WA', country: 'USA' } },
  { id: 3, city: 'New York', month: 'Apr', precip: 3.94, geo: { city: 'New York', state: 'NY', country: 'USA' } },
  { id: 6, city: 'Chicago',  month: 'Apr', precip: 3.62, geo: { city: 'Chicago', state: 'IL', country: 'USA' } }];

Note that traditional [Array.map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map)
works best for if you are working with objects completely in memory.

But this helps quite a bit if the action of mapping / transforming values
needs to be separate from the extraction / application of values back.

Assign a property to an object and return object (allowing for functional programming assignments)

Assigns multiple object entities [[property, value], [property, value], ...];

Runs a map over a collection, and adds properties the the objects.

Appends values to a collection of objects, where if the value undefined is provided, then it "remembers" or "inherits" the value previously used.

This is VERY useful for converting a 1 dimensional list, into a hierarchical tree structure.

For example, say we got this from a previous successful scrape:

source = [
  { text: '# Overview' },
  { text: 'This entire list is a hierarchy of data.' },
  { text: '# Section A' },
  { text: 'This describes section A' },
  { text: '## SubSection 1' },
  { text: 'With a subsection belonging to Section A' },
  { text: '# Section B' },
  { text: 'With an entirely unrelated section B, that is sibling to Section A' }
];

We would like to know which heading1 and heading2 the texts belong to:

const isHeader1 = (str) => str.startsWith('# ');
const isHeader2 = (str) => str.startsWith('## ');

//-- note, return undefined for any property you don't want to have inherited.
inheritFn = (entry) => ({
  section: isHeader1(entry.text) ? entry.text.replace(/#+\s+/, '') : undefined,
  subSection: isHeader2(entry.text) ? entry.text.replace(/#+\s+/, '') : undefined
});

results = utils.object.augmentInherit(source, inheritFn);

So we pass the collection of results as the source, and an augment function, that returns the heading 1 value - that is then kept until the next heading 1. (Similar for subSection using heading 2)

Cleans all the properties of the array of objects in place (does not make Copies)

NOTE: This is faster than cleanProperties2, but the standard order of the properties (using Object.keys) will be altered.

Cleans properties on clones of objects.

Additionally, this returns a mapping of what the properties used to be named, as this can be helpful for rendering out tables.

Cleans an individual property

Cleans the list of object keys - likely from a CSV

Collapse an object tree into a single object with all the properties.

The inverse of Flatten - this takes an object with dot notation properties, and creates the sub-objects as necessary to contain the properties defined.

Example:

flattenedObj = {
  first: 'john', last: 'doe',
  'friend.first': 'jane', 'friend.last': 'doe',
  'course.id': 'econ-101',
    'course.professor.id': 10101, 'course.professor.first': 'jim', 'course.professor.last': 'gifford'
};

expandedObj = utils.object.expand(flattenedObj);
// {
//  first: 'john', last: 'doe',
//  friend: { first: 'jane', last: 'doe' },
//  course: { id: 'econ-101', professor: { id: 10101, first: 'jim', last: 'gifford' }}
// };

Similar to object.extractObjectProperty - this extracts out multiple property/vectors at a time.

Note that unlike numpy, there is a key preserved in the result - to better keep track of what the values were intended to represent.

weather = [
  { id: 1, city: 'Seattle',  month: 'Aug', precip: 0.87 },
  null,
  { id: 3, city: 'New York', month: 'Apr', precip: 3.94 },
  { id: 6, city: 'Chicago',  month: 'Apr', precip: 3.62 }
];

utils.object.extractObjectProperties(weather, ['city', 'month']);
// { 
//   city: [ 'Seattle', 'New York', 'Chicago'],
//   month: ['Aug', 'Apr', 'Apr']
// }

Keys will be the the dot notation of the path used ex: prop[index].value or can be explicitly set through a [key, accessor] pair

utils.object.extractObjectProperties(weather, ['city', ['Month', 'month'], ['precipitation', r => r.precip]]);
// { 
//   city: [ 'Seattle', 'New York', 'Chicago'],
//   month: ['Aug', 'Apr', 'Apr'],
//   precipitation: [0.87, 3.94, 3.62]
// }

However, this can be helpful to extract values safely from deeply nested values

data = [{
   category_id: 'c884a636628bca341e', menu_item_id: 'mi88dc7bb31bc6104f1',
   item_sizes: [{ id: 'mio882f48820281cf4b6', price: 16.09 }]
},
{
   category_id: 'c884a636628bca341e', menu_item_id: 'mi8802b942e737df40d',
   item_sizes: [{ id: 'mio88b60bcd7dd202481', price: 17.09 }]
},
{
   category_id: 'c884a636628bca341e', menu_item_id: 'mi88ff22662b0c0644a',
   item_sizes: [{ id: 'mio88645e98cd8ffc42e', price: 14.99 }]
}];

utils.object.extractObjectProperty(data, ['menu_item_id', 'item_sizes[0].price']);
// {
//   menu_item_id: ['mi88dc7bb31bc6104f1', 'mi8802b942e737df40d', 'mi88ff22662b0c0644a'],
//   'item_sizes[0].price': [ 16.09, 17.09, 14.99 ]
// }

Note that this can also work with maps of properties / paths or functions

// note you can also pass maps with property name strings, or functions.
extractionMap = new Map();
extractionMap.set('city', null); // default the property by the key name
extractionMap.set('city2', 'city'); // specify the property to use
extractionMap.set('city3', (r) => r.city); // specify a function

utils.object.extractObjectProperties(weather, extractionMap);
// {
//   city: ['Seattle', 'New York', 'Chicago'],
//   city2: ['Seattle', 'New York', 'Chicago'],
//   city3: ['Seattle', 'New York', 'Chicago']
// };

Similar to a transpose, this finds all the values of a particular property within a list of objects.

weather = [
  { id: 1, city: 'Seattle',  month: 'Aug', precip: 0.87 },
  null,
  { id: 3, city: 'New York', month: 'Apr', precip: 3.94 },
  { id: 6, city: 'Chicago',  month: 'Apr', precip: 3.62 }
];

utils.object.extractObjectProperty(weather, 'city');
// [ 'Seattle', 'New York', 'Chicago'];

However, this can be helpful to extract values safely from deeply nested values

data = [{
   category_id: 'c884a636628bca341e', menu_item_id: 'mi88dc7bb31bc6104f1',
   item_sizes: [{ id: 'mio882f48820281cf4b6', price: 16.09 }]
},
{
   category_id: 'c884a636628bca341e', menu_item_id: 'mi8802b942e737df40d',
   item_sizes: [{ id: 'mio88b60bcd7dd202481', price: 17.09 }]
},
{
   category_id: 'c884a636628bca341e', menu_item_id: 'mi88ff22662b0c0644a',
   item_sizes: [{ id: 'mio88645e98cd8ffc42e', price: 14.99 }]
}];

utils.object.extractObjectProperty(data, 'item_sizes[0].price');
// [ 16.09, 17.09, 14.99 ]

Fetches multiple properties from an object or list of objects.

testObj = {
 name: 'john',
 courses: [{ name: 'econ-101' }]
}
utils.object.fetchObjectProperty(testObj,
 { 'courseName': 'courses[0].?name', personName: 'name' });
// { courseName: 'econ-101', personName: 'john' }

Accesses a property using a string

testObj = {
 name: 'john',
 courses: [{ name: 'econ-101' }]
}
utils.object.fetchObjectProperty(testObj, 'courses[0].?name');
// 'econ-101'

note that the options allow for safe property access

testObj = {
 name: 'john',
 courses: [{ name: 'econ-101' }]
}
utils.object.fetchObjectProperty(testObj, 'courses[0].courseId');
// throws an error

utils.object.fetchObjectProperty(testObj, 'courses[0].?courseId');
// null - because of optional condition operator

utils.object.fetchObjectProperty(testObj, 'courses[0].courseId', { safeAccess: true });
// null - because of the safe access option

Removes specific properties on an object or list of objects

Finds objects that have any of the properties specified.

This can be very helpful when working with datasets that include mixed data (such as JSON)

const students = [
  { first: 'john', last: 'doe' }, { first: 'jane', last: 'doe' }, { first: 'jack', last: 'white', failure: 401 }
];

utils.findWithProperties(students, 'failure');
// { first: 'jack', last: 'white', failure: 401 }

Please note, that we can check a single object:

utils.findWithProperties({ first: 'john', last: 'doe' }, 'failure');
// []

Finds objects that do not have ALL the properties specified.

This can be very helpful in ensuring all objects actually meet a specification and are not missing values.

const students = [
  { first: 'john', last: 'doe', age: 23 }, { first: 'jane', last: 'doe', age: 23 }, { first: 'jack', last: 'white', failure: 401 }
];

utils.findWithoutProperties(students, 'first', 'last', 'age');
// [{ first: 'jack', last: 'white', failure: 401 }]

utils.findWithoutProperties(students, 'failure');
// [{ first: 'john', last: 'doe', age: 23 }, { first: 'jane', last: 'doe', age: 23 }] 

Please note, that we can check a single object:

utils.findWithoutProperties(students[0], 'failure');
// []

Flattens an object and sub-objects into dot notation - to have easier time understanding schemas and explainations.

example:

student = {
 first: 'john', last: 'doe',
 friend: { first: 'jane', last: 'doe' },
 course: { id: 'econ-101', professor: { id: 10101, first: 'jim', last: 'gifford' }}
};

flattenedObj = utils.object.flatten(student);
// {
//   first: 'john', last: 'doe',
//   'friend.first': 'jane', 'friend.last': 'doe',
//   'course.id': 'econ-101',
//     'course.professor.id': 10101, 'course.professor.first': 'jim', 'course.professor.last': 'gifford'
// };

While originally intended as a sub-implementation for Flatten, this was exposed in case additional cases ever arose.

Example:

student = { first: 'john', last: 'doe' };
friend = { first: 'jane', last: 'doe' };
course = { id: 'econ-101', professor: { id: 10101, first: 'jim', last: 'gifford' }};
flattenedObj = {};
flattenedObj = utils.object.flattenObjectOntoAnother(student, flattenedObj);
// { first: 'john', last: 'doe' }
flattenedObj = utils.object.flattenObjectOntoAnother(friend, flattenedObj, 'friend.');
// { first: 'john', last: 'doe', 'friend.first': 'jane', 'friend.last': 'doe' };
flattenedObj = utils.object.flattenObjectOntoAnother(course, flattenedObj, 'course.');
// { first: 'john', last: 'doe', 'friend.first': 'jane', 'friend.last': 'doe', 'course.id': 'econ-101',
//   'course.professor.id': 10101, 'course.professor.first': 'jim', 'course.professor.last': 'gifford' };

See flatten for a an alternative to achieve the same result.

Translates specific properties to a new value on an object, or collection of objects.

The properties defined in the propertyTranslations argument is then the property to be updated. (All other properties remain the same)

You can either provide a function accepting the current value and returning the new value (any) => any

Or you can provide one of the common shorthands:

• 'string'
• 'float' or 'number'
• 'int' or 'integer'
• 'boolean'

data = [
  {station: 'A', isFahreinheit: 'true', offset: '0', temp: 98, type: 'F', descr: '0123'},
  {station: 'A', isFahreinheit: 'TRUE', offset: '2', temp: 99, type: 'F', descr: '0123456'},
  {station: 'A', isFahreinheit: 'false', offset: '3', temp: 100, type: 'F', descr: '0123456789'}
];

utils.object.format(data, ({
  //-- to a literal value
  type: 'C',
  //-- convert it to 'string', 'number' || 'float', 'int' || 'integer', 'boolean'
  offset: 'number',
  isFahreinheit: 'boolean',
  //-- or convert the value with a function accepting the current value
  //-- and returning the new value
  temp: (val) => (val - 32) * 0.5556
}));

// [
//   { station: 'A', isFahreinheit: true, offset: 0, temp: 36.669599999999996, type: 'C', descr: '0123' },
//   { station: 'A', isFahreinheit: true, offset: 2, temp: 37.2252, type: 'C', descr: '0123456' },
//   { station: 'A', isFahreinheit: false, offset: 3, temp: 37.7808, type: 'C', descr: '0123456789' }
// ];

Please note, you can pass a single object to be cleaned,
but it will be returned as an array of one object.

data = [{station: 'A', isFahreinheit: 'TRUE', offset: '2', temp: 99, type: 'F', descr: '0123456'}];

utils.object.format(data, ({
  //-- convert it to 'string', 'number' || 'float', 'int' || 'integer', 'boolean'
  offset: 'number',
  isFahreinheit: 'boolean'
}));

// [{station: 'A', isFahreinheit: true, offset: 2, temp: 99, type: 'F', descr: '0123456'}];

Generates a JSON schema for an object

returns a map of the types of fields stored

Determines whether a value is an Object and not an Array or a Date

Join values from an objectArray to a JavaScript Map.

For example:

weather = [
  { id: 1, city: 'Seattle',  month: 'Aug', precip: 0.87 },
  null,
  { id: 3, city: 'New York', month: 'Apr', precip: 3.94 },
  { id: 6, city: 'Chicago',  month: 'Apr', precip: 3.62 }
];

cityLocations = new Map([
  ['Chicago', { locationId: 1, city: 'Chicago', lat: 41.8781, lon: 87.6298 }],
  ['New York', { locationId: 2, city: 'New York', lat: 40.7128, lon: 74.0060 }],
  ['Seattle', { locationId: 3, city: 'Seattle', lat: 47.6062, lon: 122.3321 }]
]);

utils.object.join(weather, 'city', cityLocations, (weather, city) => ({...weather, ...city}));
// [
//    {id:1, city:'Seattle',  month:'Aug', precip:0.87, locationId:3, lat:47.6062, lon:122.3321 },
//    null,
//    {id:3, city:'New York', month:'Apr', precip:3.94, locationId:2, lat:40.7128, lon:74.006 },
//    {id:6, city:'Chicago',  month:'Apr', precip:3.62, locationId:1, lat:41.8781, lon:87.6298 }
// ]

or join by lookup:

utils.object.join(weather, 'city', cityLocations, (weather, city) => ({...weather, city}));
[
  { id: 1, city: 'Seattle',  month: 'Aug', precip: 0.87, city:
    { city: 'Seattle', locationId: 3, lat: 47.6062, lon: 122.3321 }
  },
  null,
  { id: 3, city: 'New York', month: 'Apr', precip: 3.94, city:
    { city: 'New York', locationId: 2, lat: 40.7128, lon: 74.006 }
  },
  { id: 6, city: 'Chicago',  month: 'Apr', precip: 3.62, city:
    { city: 'Chicago', locationId: 1, lat: 41.8781, lon: 87.6298 }
  }
];

or performing a translation / calculate the index instead of a property:

const indexingFn = (weather) => `${weather.country}_${weather.city}`;
utils.object.join(weather, indexingFn, cityLocations, (weather, city) => ({...weather, ...city}));
// ...

The signature for the indexingFunction is (sourceObj:Object): {any} - providing the index to use against the map.

The signature for the mapping function is (sourceObj:Object, mappedObject:Object) => {Object}.

If the mappedObject could not be found by that index (left join), then mappedObject will be null.

As the results of the functions are mapped, you can either modify in-line (directly on the object), or on a clone of the object (ex: {...sourceObj})

Note, performing a JavaScript .map() call may be more performant in some cases, so consider it for more complex options.

Note: indexField can be either a string name of the field to join, or a function to be passed the object and generate the index

For cases where we simply want to pull values from one object to another.

For example:

weather = [
  { id: 1, city: 'Seattle',  month: 'Aug', precip: 0.87 },
  null,
  { id: 3, city: 'New York', month: 'Apr', precip: 3.94 },
  { id: 6, city: 'Chicago',  month: 'Apr', precip: 3.62 }
];

cityLocations = new Map([
  ['Chicago', { locationId: 1, city: 'Chicago', lat: 41.8781, lon: 87.6298 }],
  ['New York', { locationId: 2, city: 'New York', lat: 40.7128, lon: 74.0060 }],
  ['Seattle', { locationId: 3, city: 'Seattle', lat: 47.6062, lon: 122.3321 }]
]);

utils.object.joinProperties(weather, 'city', cityLocations, 'lat', 'lon'));
// [
//    {id:1, city:'Seattle',  month:'Aug', precip:0.87, lat:47.6062, lon:122.3321 },
//    null,
//    {id:3, city:'New York', month:'Apr', precip:3.94, lat:40.7128, lon:74.006 },
//    {id:6, city:'Chicago',  month:'Apr', precip:3.62, lat:41.8781, lon:87.6298 }
// ]

Safely gets the keys from an object or array of objects NOTE: much faster on object, as it will assume it needs to check all items in the array.

This can be quite helpful to understand a list of objects that are not uniform in properties.

Creates a map of a list of objects based on a specific property

Applies a function to a set of properties on an object, or collection.

This is shorthand for a mapping function, but useful if doing the same operation (like converting to compactNumbers, converting to string, etc)

For example, the two are equivalent:

const list = [
 { id: '100', age: '21', name: 'p1' },
 { id: '200', age: '22', name: 'p2' },
 { id: '300', age: '23', name: 'p3' },
 { id: '400', age: '24', name: 'p4' },
 { id: '500', age: '25', name: 'p5' }
];

const numToString = (val) => String(val);

const listMapProperties = utils.object.mapProperties(list, numToString, 'id', 'val');

const listMap = list.map((obj) => ({
 ...obj,
 id: numToString(obj.val),
 age: numToString(obj.val)
}));

Maps an array of values to a single property.

For example:

const data = [{ record: 'jobA', val: 1 }, { record: 'jobA', val: 2 },
 { record: 'jobA', val: 3 }, { record: 'jobA', val: 4 },
 { record: 'jobA', val: 5 }, { record: 'jobA', val: 6 },
 { record: 'jobA', val: 7 }, { record: 'jobA', val: 8 },
 { record: 'jobA', val: 9 }, { record: 'jobA', val: 10 }
];

utils.object.propertyFromList(data, 'val')
//-- [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];

utils.object.propertyFromList(data, (r) => r.val);
//-- [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];

Copies values from one record to the next or "inherits" the value previously used if the current value is undefined.

For example:

source = [
 { header: 'Section 1', text: 'A' },
 { header: undefined, text: 'B' },
 { header: undefined, text: 'C' },
 { header: 'Section 2', text: 'D' },
 { header: undefined, text: 'E' },
 { header: undefined, text: 'F' }
];
utils.object.propertyInherit(source, 'header');
// [
//  { header: 'Section 1', text: 'A' },
//  { header: 'Section 1', text: 'B' },
//  { header: 'Section 1', text: 'C' },
//  { header: 'Section 2', text: 'D' },
//  { header: 'Section 2', text: 'E' },
//  { header: 'Section 2', text: 'F' }
// ];

Finds all the properties for objects in a collection, and provides the first 'non-empty' value found of each property.

Non-Empty means:

• not null
• not undefined
• not an empty string
• not an empty array

This can be especially helpful for heterogeneous collections and can be much faster than something like danfojs.describe

Property Reassign - either against a single object or an array of objects

Keeps only specific properties on an object or list of objects

Sets values for objects that don't currently have the property

This is very helpful for ensuring that all objects have a property, or setting a value to make it easier to identify that it is 'N/A'

Note, that only the ownProperties on the default object are checked.

And values are applied to the target object, only if the property is not on the object (property is undefined)

Unites the properties of two collections of objects.

For example:

source1 = [
 { first: 'john' },
 { first: 'jane' }
];
source2 = [
 { last: 'doe' },
 { last: 'dough' }
];
utils.object.union(source1, source2);
// [{ first: 'john', last: 'doe' },
//  { first: 'jane', last: 'dough' }];

Note that you can also pass a single object, to have it union to multiple.

source1 = [
 { first: 'john' },
 { first: 'jane' }
];
//-- same object to be applied to all
source2 = { last: 'doe' };

utils.object.union(source1, source2);
// [{ first: 'john', last: 'doe' },
//  { first: 'jane', last: 'doe' }];

Adds all items into a set

Labels and Values from object.cleanProperties2

{
  labels: { date: 'date', kind: 'kind', num: 'num' },
  values: [
    { date: ' 2021-07-11T22:23:07+0100', kind: ' s', num: '192' },
    { date: ' 2021-07-09T19:54:48+0100', kind: ' c', num: '190' },
    { date: ' 2021-07-08T17:00:32+0100', kind: ' s', num: '190' }
  ]
};

Options for fetching object properties