@hkdigital/lib-core 0.3.8 → 0.3.10

package/dist/util/iterate/index.js

@@ -5,6 +5,10 @@ import { smallestFirst, largestFirst } from '../compare/index.js';
 
 import IterableTree from '../../classes/data/IterableTree.js';
 
+/**
+ * @typedef {import('../../classes/data/typedef.js').IterableTreeOptions} IterableTreeOptions
+ */
+
 /* ------------------------------------------------------------------ Exports */
 
 /**
@@ -52,30 +56,34 @@ export function* map(iterable, transformFn) {
  * 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} obj - Object to iterate
  *
- * @param {Object} [options] - Iteration options
+ * @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]
+ * @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 {object} [options.outputIntermediateNodes=false]
+ * @param {boolean} [options.outputIntermediateNodes=false]
  *   If true, intermediate object nodes (not leaves) will be outputted too
  *
- * @param {object} [options.ignoreEmptyObjectLeaves=false]
+ * @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;
+	const depthFirst =
+		undefined === options.depthFirst ? true : options.depthFirst;
 
 	options = Object.assign({}, options);
 
@@ -99,30 +107,16 @@ export function iterateObjectEntries(obj, options = {}) {
  * 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
+ * @param {object} obj - Object to iterate
+ * @param {IterableTreeOptions & { depthFirst: boolean}} [options]
  *
  * @return {Iterator} iterator object
  */
-export function iterateObjectPaths(obj, options = {}) {
+export function iterateObjectPaths(obj, options) {
 	let objectIterator;
 
-	const depthFirst = undefined === options.depthFirst ? true : options.depthFirst;
+	const depthFirst =
+		undefined === options.depthFirst ? true : options.depthFirst;
 
 	options = Object.assign({}, options);
 
@@ -132,9 +126,6 @@ export function iterateObjectPaths(obj, options = {}) {
 		objectIterator = new IterableTree(obj, options);
 	} else {
 		throw new Error('NOT IMPLEMENTED YET');
-
-		// objectIterator
-		//   = new hk.iterate._BreadthFirstIterableTree( obj, options );
 	}
 
 	return objectIterator.paths();
@@ -146,23 +137,8 @@ export function iterateObjectPaths(obj, options = {}) {
  * 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
+ * @param {object} obj - Object to iterate
+ * @param {IterableTreeOptions} [options] - Iteration options
  *
  * @return {Iterator} iterator object
  */
@@ -177,23 +153,17 @@ export function iterateObjectValues(obj, options) {
 /**
  * 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
+ * @param {object} _
+ * @param {Iterable} _.it - Iterable items
+ * @param {function} _.getValueFn
  *   Function that gets the value from the iterated objects
- *
- * @param {boolean} [reversed=false]
+ * @param {boolean} [_.reversed=false]
  *   Sort in reversed order
  *
- *
- * @returns {array} objects outputted in sorted order
+ * @returns {Promise<array>} objects outputted in sorted order
  */
 export async function sortObjects({ it, getValueFn, reversed = false }) {
 	expect.iterable(it);

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: ".";