@hkdigital/lib-core 0.3.9 → 0.3.11

package/dist/util/iterate/index.js

@@ -1,234 +1,204 @@
-/* ------------------------------------------------------------------ Imports */
-
-import * as expect from '../expect/index.js';
-import { smallestFirst, largestFirst } from '../compare/index.js';
-
-import IterableTree from '../../classes/data/IterableTree.js';
-
-/* ------------------------------------------------------------------ Exports */
-
-/**
- * Filter all iterated elements
- *
- * @param {Iterable} iterable
- * @param {function} filterFn
- *
- * @returns {Generator} generator that produces items that pass the filter
- */
-export function* filter(iterable, filterFn) {
-	expect.iterable(iterable);
-	expect.function(filterFn);
-
-	for (const value of iterable) {
-		if (filterFn(value)) {
-			yield value;
-		}
-	}
-}
-
-// ---------------------------------------------------------------------- Method
-
-/**
- * Map all iterated items
- * - Outputs transformed items
- *
- * @param {Iterable} iterable
- * @param {function} transformFn
- *
- * @returns {Generator} generator that produces transformed items
- */
-export function* map(iterable, transformFn) {
-	expect.iterable(iterable);
-	expect.function(transformFn);
-
-	for (const value of iterable) {
-		yield transformFn(value);
-	}
-}
-
-// ---------------------------------------------------------------------- Method
-
-/**
- * Get an Iterator object that can be used to iterate over all
- * [ path, value ] entries in the object
- *
- * @param {Object} obj - Object to iterate
- *
- * @param {Object} [options] - Iteration options
- *
- * @param {boolean} [options.walkArrays=false]
- *   If set to true, the iterator will also iterate through Array objects
- *
- * @param {object} [options.expandPathKeys=false]
- *   If true, keys in the root object like "some.path.to" will be interpreted
- *   as paths in the object
- *
- * @param {object} [options.outputIntermediateNodes=false]
- *   If true, intermediate object nodes (not leaves) will be outputted too
- *
- * @param {object} [options.ignoreEmptyObjectLeaves=false]
- *   If true, no output will be generated for empty objects at the leaves of
- *   the object tree
- *
- * @return {Iterator} iterator object
- */
-export function iterateObjectEntries(obj, options = {}) {
-	let objectIterator;
-
-	const depthFirst = undefined === options.depthFirst ? true : options.depthFirst;
-
-	options = Object.assign({}, options);
-
-	delete options.depthFirst;
-
-	if (depthFirst) {
-		objectIterator = new IterableTree(obj, options);
-	} else {
-		throw new Error('NOT IMPLEMENTED YET');
-
-		// objectIterator
-		//   = new hk.iterate._BreadthFirstIterableTree( obj, options );
-	}
-
-	return objectIterator.entries(); /* entry = [ arrPath, value ] */
-}
-
-// ---------------------------------------------------------------------- Method
-
-/**
- * Get an Iterator object that can be used to iterate over all paths in
- * the object
- *
- * @param {Object} obj - Object to iterate
- *
- * @param {Object} [options] - Iteration options
- *
- * @param {boolean} [options.walkArrays=false]
- *   If set to true, the iterator will also iterate through Array objects
- *
- * @param {object} [options.expandPathKeys=false]
- *   If true, keys in the root object like "some.path.to" will be interpreted
- *   as paths in the object
- *
- * @param {object} [options.outputIntermediateNodes=false]
- *   If true, intermediate object nodes (not leaves) will be outputted too
- *
- * @param {object} [options.ignoreEmptyObjectLeaves=false]
- *   If true, no output will be generated for empty objects at the leaves of
- *   the object tree
- *
- * @return {Iterator} iterator object
- */
-export function iterateObjectPaths(obj, options = {}) {
-	let objectIterator;
-
-	const depthFirst = undefined === options.depthFirst ? true : options.depthFirst;
-
-	options = Object.assign({}, options);
-
-	delete options.depthFirst;
-
-	if (depthFirst) {
-		objectIterator = new IterableTree(obj, options);
-	} else {
-		throw new Error('NOT IMPLEMENTED YET');
-
-		// objectIterator
-		//   = new hk.iterate._BreadthFirstIterableTree( obj, options );
-	}
-
-	return objectIterator.paths();
-}
-
-// ---------------------------------------------------------------------- Method
-
-/**
- * Get an Iterator object that can be used to iterate over all values in
- * the object (at the leaves of the object tree)
- *
- * @param {Object} obj - Object to iterate
- *
- * @param {Object} [options] - Iteration options
- *
- * @param {boolean} [options.walkArrays=false]
- *   If set to true, the iterator will also iterate through Array objects
- *
- * @param {object} [options.expandPathKeys=false]
- *   If true, keys in the root object like "some.path.to" will be interpreted
- *   as paths in the object
- *
- * @param {object} [options.outputIntermediateNodes=false]
- *   If true, intermediate object nodes (not leaves) will be outputted too
- *
- * @param {object} [options.ignoreEmptyObjectLeaves=false]
- *   If true, no output will be generated for empty objects at the leaves of
- *   the object tree
- *
- * @return {Iterator} iterator object
- */
-export function iterateObjectValues(obj, options) {
-	const objectIterator = new IterableTree(obj, options);
-
-	return objectIterator.values();
-}
-
-// ---------------------------------------------------------------------- Method
-
-/**
- * Get a list of objects returned by an iterator in sorted order
- *
- * --
- *
- * @note Sorting requires that all values are evaluated, so all items must be
- *       iterated
- *
- * --
- *
- * @param {Iterable} it - Iterable items
- *
- * @param {function} getValueFn
- *   Function that gets the value from the iterated objects
- *
- * @param {boolean} [reversed=false]
- *   Sort in reversed order
- *
- *
- * @returns {array} objects outputted in sorted order
- */
-export async function sortObjects({ it, getValueFn, reversed = false }) {
-	expect.iterable(it);
-	expect.function(getValueFn);
-
-	const allItems = [];
-	const valuesByItem = new WeakMap();
-
-	// -- Gather all items and sort values in arrays
-
-	for (const item of it) {
-		allItems.push(item);
-		valuesByItem.set(item, getValueFn(item));
-	}
-
-	// console.log( { sortValues } );
-
-	// -- Sort all items using sortValues
-
-	let compareFn;
-
-	if (!reversed) {
-		compareFn = smallestFirst;
-	} else {
-		compareFn = largestFirst;
-	}
-
-	allItems.sort((itemA, itemB) => {
-		const valueA = valuesByItem.get(itemA);
-		const valueB = valuesByItem.get(itemB);
-
-		return compareFn(valueA, valueB);
-	});
-
-	// -- Return result
-
-	return allItems;
-}
+/* ------------------------------------------------------------------ Imports */
+
+import * as expect from '../expect/index.js';
+import { smallestFirst, largestFirst } from '../compare/index.js';
+
+import IterableTree from '../../classes/data/IterableTree.js';
+
+/**
+ * @typedef {import('../../classes/data/typedef.js').IterableTreeOptions} IterableTreeOptions
+ */
+
+/* ------------------------------------------------------------------ Exports */
+
+/**
+ * Filter all iterated elements
+ *
+ * @param {Iterable} iterable
+ * @param {function} filterFn
+ *
+ * @returns {Generator} generator that produces items that pass the filter
+ */
+export function* filter(iterable, filterFn) {
+	expect.iterable(iterable);
+	expect.function(filterFn);
+
+	for (const value of iterable) {
+		if (filterFn(value)) {
+			yield value;
+		}
+	}
+}
+
+// ---------------------------------------------------------------------- Method
+
+/**
+ * Map all iterated items
+ * - Outputs transformed items
+ *
+ * @param {Iterable} iterable
+ * @param {function} transformFn
+ *
+ * @returns {Generator} generator that produces transformed items
+ */
+export function* map(iterable, transformFn) {
+	expect.iterable(iterable);
+	expect.function(transformFn);
+
+	for (const value of iterable) {
+		yield transformFn(value);
+	}
+}
+
+// ---------------------------------------------------------------------- Method
+
+/**
+ * Get an Iterator object that can be used to iterate over all
+ * [ path, value ] entries in the object
+ *
+ * @param {object} obj - Object to iterate
+ *
+ * @param {object} [options] - Iteration options
+ *
+ * @param {boolean} [options.walkArrays=false]
+ *   If set to true, the iterator will also iterate through Array objects
+ *
+ * @param {boolean} [options.expandPathKeys=false]
+ *   If true, keys in the root object like "some.path.to" will be interpreted
+ *   as paths in the object
+ *
+ * @param {boolean} [options.outputIntermediateNodes=false]
+ *   If true, intermediate object nodes (not leaves) will be outputted too
+ *
+ * @param {boolean} [options.ignoreEmptyObjectLeaves=false]
+ *   If true, no output will be generated for empty objects at the leaves of
+ *   the object tree
+ *
+ * @param {boolean} [options.depthFirst=true]
+ *   If true, use depth-first traversal, otherwise breadth-first
+ *
+ * @return {Iterator} iterator object
+ */
+export function iterateObjectEntries(obj, options = {}) {
+	let objectIterator;
+
+	const depthFirst =
+		undefined === options.depthFirst ? true : options.depthFirst;
+
+	options = Object.assign({}, options);
+
+	delete options.depthFirst;
+
+	if (depthFirst) {
+		objectIterator = new IterableTree(obj, options);
+	} else {
+		throw new Error('NOT IMPLEMENTED YET');
+
+		// objectIterator
+		//   = new hk.iterate._BreadthFirstIterableTree( obj, options );
+	}
+
+	return objectIterator.entries(); /* entry = [ arrPath, value ] */
+}
+
+// ---------------------------------------------------------------------- Method
+
+/**
+ * Get an Iterator object that can be used to iterate over all paths in
+ * the object
+ *
+ * @param {object} obj - Object to iterate
+ * @param {IterableTreeOptions & { depthFirst: boolean}} [options]
+ *
+ * @return {Iterable<string[]>} iterable object that yields path arrays
+ */
+export function iterateObjectPaths(obj, options) {
+	let objectIterator;
+
+	const depthFirst =
+		undefined === options.depthFirst ? true : options.depthFirst;
+
+	options = Object.assign({}, options);
+
+	delete options.depthFirst;
+
+	if (depthFirst) {
+		objectIterator = new IterableTree(obj, options);
+	} else {
+		throw new Error('NOT IMPLEMENTED YET');
+	}
+
+	return objectIterator.paths();
+}
+
+// ---------------------------------------------------------------------- Method
+
+/**
+ * Get an Iterator object that can be used to iterate over all values in
+ * the object (at the leaves of the object tree)
+ *
+ * @param {object} obj - Object to iterate
+ * @param {IterableTreeOptions} [options] - Iteration options
+ *
+ * @return {Iterable<any>} iterator object
+ */
+export function iterateObjectValues(obj, options) {
+	const objectIterator = new IterableTree(obj, options);
+
+	return objectIterator.values();
+}
+
+// ---------------------------------------------------------------------- Method
+
+/**
+ * Get a list of objects returned by an iterator in sorted order
+ *
+ * @note Sorting requires that all values are evaluated, so all items must be
+ *       iterated
+ *
+ * @param {object} _
+ * @param {Iterable} _.it - Iterable items
+ * @param {function} _.getValueFn
+ *   Function that gets the value from the iterated objects
+ * @param {boolean} [_.reversed=false]
+ *   Sort in reversed order
+ *
+ * @returns {Promise<array>} objects outputted in sorted order
+ */
+export async function sortObjects({ it, getValueFn, reversed = false }) {
+	expect.iterable(it);
+	expect.function(getValueFn);
+
+	const allItems = [];
+	const valuesByItem = new WeakMap();
+
+	// -- Gather all items and sort values in arrays
+
+	for (const item of it) {
+		allItems.push(item);
+		valuesByItem.set(item, getValueFn(item));
+	}
+
+	// console.log( { sortValues } );
+
+	// -- Sort all items using sortValues
+
+	let compareFn;
+
+	if (!reversed) {
+		compareFn = smallestFirst;
+	} else {
+		compareFn = largestFirst;
+	}
+
+	allItems.sort((itemA, itemB) => {
+		const valueA = valuesByItem.get(itemA);
+		const valueB = valuesByItem.get(itemB);
+
+		return compareFn(valueA, valueB);
+	});
+
+	// -- Return result
+
+	return allItems;
+}

package/dist/util/object/index.d.ts

@@ -1,23 +1,23 @@
 /**
  * Returns true
- * - if the object has no (iterable) key value pairs
+ * - if the object has no enumerable key value pairs
  * - if the object is an empty array
  *
  * @param {object} obj
  *
  * @return {boolean}
  *   true if the object has no key value pairs or the supplied object
- *   is `falsey`
+ *   is falsy
  */
 export function isEmpty(obj: object): boolean;
 /**
- * Get the number of (iterable) key value pairs in the specified object
+ * Get the number of enumerable key value pairs in the specified object
  *
  * @param {object} obj
  *
- * @return {number} number of iterable key value pairs
+ * @return {number} number of enumerable key value pairs
  */
-export function objectSize(obj: object): number;
+export function size(obj: object): number;
 /**
  * Returns a shallow copy of the object without the properties that
  * have the value [null] or [undefined]
@@ -31,19 +31,30 @@ export function objectSize(obj: object): number;
  */
 export function exportNotNull(obj: object, onlyKeys?: string[]): object;
 /**
- * Returns a shallow copy of the object without the properties that
- * are `private`
- * - Private properties are properties that start with an underscore
- *   `_`.
+ * Create a shallow copy of the object's public properties. Properties that
+ * start with an underscore are considered 'internal' properties and are not
+ * exported.
+ * - This method can e.g. be used to export a data object without it's
+ *   'internal' properties
  *
  * @param {object} obj
  *
  * @param {string[]} [keepKeys]
- *   If specified, the sprecified private keys will be exported (e.g. `_id`)
+ *   If specified, the specified private keys will be exported (e.g. `_id`)
  *
- * @returns {object} new object without the null properties
+ * @returns {object} new object without properties that start with an underscore
+ */
+export function exportPublic(obj: object, keepKeys?: string[]): object;
+/**
+ * Creates a copy of an object or array that contains only primitive values
+ * - Nested objects and arrays are completely removed
+ * - Only string, number, boolean, null, undefined values are kept
+ *
+ * @param {object|array} objectOrArray
+ *
+ * @returns {object|array} new object or array with only primitive values
  */
-export function exportNotPrivate(obj: object, keepKeys?: string[]): object;
+export function exportNotNested(objectOrArray: object | any[]): object | any[];
 /**
  * Keep only the specified keys in the object
  * - deletes all other key-value pairs in the object
@@ -220,26 +231,22 @@ export function getPrototypeNames(obj: object): string[];
  *        { someArray.0.name: 1 }
  *
  * @param {object} [options]
- * @param {object} [options.shallowLeaves=false]
- *   If set to true, the values of the leaves of the tree will be converted
- *   to shallow objects if the leaves are nested objects.
+ * @param {boolean} [options.shallowLeaves=false]
+ *   If true, when extracted leaf values are objects, they are filtered to
+ *   contain only primitive properties. Nested objects and arrays within
+ *   the leaves are removed.
+ *
+ *   Example: { profile: { name: "John", settings: {...} } }
+ *   becomes: { profile: { name: "John" } }
  *
  * @return {object}
  *   nested object with the values that were found or defaultValues
  */
 export function getTree(obj: object, tree: object, options?: {
-    shallowLeaves?: object;
+    shallowLeaves?: boolean;
 }): object;
 /**
  * Deep clone an object or any kind of other variable
- * - Recursively clone all nested properties
- * - Properties in the prototype chain are cloned too, but all copied into a
- *   single prototype object
- * - This method works on objects, but also on any other JS variable type
- * - If a value cannot be cloned, a reference is returned. o.a. for
- *   - Error objects
- *   - Browser objects
- *   - Functions
  *
  * @param {any} objectToBeCloned - Variable to clone
  *
@@ -254,14 +261,6 @@ export function clone(objectToBeCloned: any, _seenObjects: any): any;
  * @param {any} value - Value to set
  */
 export function setReadOnlyProperty(obj: object, propertyName: string, value: any): void;
-/**
- * Returns a clone of a (nested) object that has a maximum depth
- *
- * @param {object|array} obj
- *
- * @returns {object|array} shallow object or array
- */
-export function shallowClone(objectOrArray: any): object | any[];
 /**
  * Update an object
  * - Sets the path-value pairs from the updateData in the object
@@ -271,7 +270,10 @@ export function shallowClone(objectOrArray: any): object | any[];
  *
  * @param {object} [obj] - Input object
  *
- * @param {object|iterable} updateData - Data to update
+ * @param {object|Iterable} updateData - Data to update
+ *
+ * @param {Object} [options]
+ * @param {boolean} [options.replaceArrays=false]
  *
  * Note that if using path-value pairs, the order of the pairs is relevant:
  *   {
@@ -282,7 +284,9 @@ export function shallowClone(objectOrArray: any): object | any[];
  *
  * @returns {object} updated object
  */
-export function updateObject(obj?: object, updateData: object | iterable, options: any): object;
+export function updateObject(obj?: object, updateData?: object | Iterable<any>, options?: {
+    replaceArrays?: boolean;
+}): object;
 /**
  * Copy own properties from an object to another object if they do not
  * exist yet.
@@ -300,27 +304,4 @@ export function copyOwnProperties(from: object, to: object): void;
  * @returns {string[]} list of path values
  */
 export function ensureArrayPath(path: string | string[]): string[];
-/**
- * Create all parent objects on the object path if they do not yet exist yet
- * - This method will throw an exception if there is a non-object node in
- *   the path
- *
- * @param {object} obj
- *   Object to create the parent objects in
- *
- * @param {string[]} arrPath
- *   The path that specified which parent oobjects to create
- *
- * @returns {object} the input object with the created object properties
- */
-export function _ensureParent(obj: object, arrPath: string[]): object;
-/**
- * Get parent object at the specified path
- *
- * @param {object}   obj - Object to work in
- * @param {string[]} arrPath - Path to get the parent object for
- *
- * @returns {object|array|null} parent object or null if not found
- */
-export function _getParent(obj: object, arrPath: string[]): object | any[] | null;
 export const PATH_SEPARATOR: ".";