@hkdigital/lib-core 0.3.9 → 0.3.11

package/dist/util/is/index.js

@@ -1,140 +1,147 @@
-/** Internals */
-
-//
-// @see https://developer.mozilla.org/
-//    en-US/docs/Web/JavaScript/Reference/Global_Objects/AsyncFunction
-//
-const AsyncFunction = Object.getPrototypeOf(async () => {}).constructor;
-const objectToString = Object.prototype.toString;
-
-/** Exports */
-
-/**
- * Check if a value looks like an array
- *
- * @param {any} item - Item to check
- *
- * @return {boolean} true if the value looks like an array
- */
-export function isArrayLike(item) {
-	if (!(item instanceof Object)) {
-		return false;
-	}
-
-	if ('length' in item) {
-		return true;
-	}
-
-	return false;
-}
-
-/**
- * Check if a value is an Arguments object
- *
- * @param {any} value
- *
- * @returns {boolean} true if the value is an Arguments object
- */
-export function isArguments(value) {
-	return objectToString.call(value) === '[object Arguments]';
-}
-
-/**
- * Check if a value is an array that only contains primitives
- * - A primitive is a not-object value
- *
- * @param {any} value - value to check
- *
- * @return {boolean} true if the value is an array of primitives
- */
-export function isArrayOfPrimitives(arr) {
-	if (!Array.isArray(arr)) {
-		return false;
-	}
-
-	for (let j = 0, n = arr.length; j < n; j = j + 1) {
-		if (arr[j] instanceof Object) {
-			// current value is not a primitive
-			return false;
-		}
-	}
-
-	return true;
-}
-
-/**
- * Check if the supplied value is async iterable
- * - Aync iterable objects must implement the "@@asyncIterator" method
- *
- * @param {any} value
- *
- * @returns {boolean} true if the value is async iterable
- */
-export function isAsyncIterator(value) {
-	if (!(value instanceof Object) || typeof value[Symbol.asyncIterator] !== 'function') {
-		return false;
-	}
-
-	return true;
-}
-
-/**
- * Check if the supplied value is an async function
- * - Returns true for functions declared as "async function" or
- *   async () => {}
- *
- * @warning this function does not return [true] for (sync) functions that
- *   return a promise.
- *
- * @param {any} value
- *
- * @returns {boolean} true if the value is an async function
- */
-export function isAsyncFunction(value) {
-	if (value instanceof AsyncFunction) {
-		return true;
-	}
-
-	return false;
-}
-
-/**
- * Check if the supplied value is iterable
- * - Iterable objects must implement the "@@iterator" method
- * - Generators are also iterable
- *
- * @param {any} value
- *
- * @returns {boolean} true if the value is (not async) iterable
- */
-export function isIterable(value) {
-	if (!(value instanceof Object) || typeof value[Symbol.iterator] !== 'function') {
-		return false;
-	}
-
-	return true;
-}
-
-/**
- * Check if the supplied value is an object bu not a promise
- * - Promises return false
- * - Arrays return true
- *
- * @param {any} value
- *
- * @returns {boolean} true if the value is an Object, but not a Promise
- */
-export function isObject(value) {
-	if (!(value instanceof Object)) {
-		if (value && typeof value === 'object') {
-			// e.g. obj = Object.create(null);
-			return true;
-		}
-
-		return false;
-	} else if (value instanceof Promise) {
-		return false;
-	}
-
-	return true;
-}
+/** Internals */
+
+//
+// @see https://developer.mozilla.org/
+//    en-US/docs/Web/JavaScript/Reference/Global_Objects/AsyncFunction
+//
+const AsyncFunction = Object.getPrototypeOf(async () => {}).constructor;
+const objectToString = Object.prototype.toString;
+
+/** Exports */
+
+/**
+ * Check if a value looks like an array
+ *
+ * @param {any} item - Item to check
+ *
+ * @return {boolean} true if the value looks like an array
+ */
+export function arrayLike(item) {
+	if (!(item instanceof Object)) {
+		return false;
+	}
+
+	if ('length' in item) {
+		return true;
+	}
+
+	return false;
+}
+
+/**
+ * Check if a value is an Arguments object
+ *
+ * @param {any} value
+ *
+ * @returns {boolean} true if the value is an Arguments object
+ */
+function argumentsCheck(value) {
+	return objectToString.call(value) === '[object Arguments]';
+}
+export { argumentsCheck as arguments };
+
+/**
+ * Check if a value is an array that only contains primitives
+ * - A primitive is a not-object value
+ *
+ * @param {any} value - value to check
+ *
+ * @return {boolean} true if the value is an array of primitives
+ */
+export function arrayOfPrimitives(value) {
+	if (!Array.isArray(value)) {
+		return false;
+	}
+
+	for (let j = 0, n = value.length; j < n; j = j + 1) {
+		if (value[j] instanceof Object) {
+			// current value is not a primitive
+			return false;
+		}
+	}
+
+	return true;
+}
+
+/**
+ * Check if the supplied value is async iterable
+ * - Aync iterable objects must implement the "@@asyncIterator" method
+ *
+ * @param {any} value
+ *
+ * @returns {boolean} true if the value is async iterable
+ */
+export function asyncIterator(value) {
+	if (
+		!(value instanceof Object) ||
+		typeof value[Symbol.asyncIterator] !== 'function'
+	) {
+		return false;
+	}
+
+	return true;
+}
+
+/**
+ * Check if the supplied value is an async function
+ * - Returns true for functions declared as "async function" or
+ *   async () => {}
+ *
+ * @warning this function does not return [true] for (sync) functions that
+ *   return a promise.
+ *
+ * @param {any} value
+ *
+ * @returns {boolean} true if the value is an async function
+ */
+export function asyncFunction(value) {
+	if (value instanceof AsyncFunction) {
+		return true;
+	}
+
+	return false;
+}
+
+/**
+ * Check if the supplied value is iterable
+ * - Iterable objects must implement the "@@iterator" method
+ * - Generators are also iterable
+ *
+ * @param {any} value
+ *
+ * @returns {boolean} true if the value is (not async) iterable
+ */
+export function iterable(value) {
+	if (
+		!(value instanceof Object) ||
+		typeof value[Symbol.iterator] !== 'function'
+	) {
+		return false;
+	}
+
+	return true;
+}
+
+/**
+ * Check if the supplied value is an object bu not a promise
+ * - Promises return false
+ * - Arrays return true
+ *
+ * @param {any} value
+ *
+ * @returns {boolean} true if the value is an Object, but not a Promise
+ */
+export function object(value) {
+	if (!(value instanceof Object)) {
+		if (value && typeof value === 'object') {
+			// e.g. obj = Object.create(null);
+			return true;
+		}
+
+		return false;
+	} else if (value instanceof Promise) {
+		return false;
+	}
+
+	return true;
+}

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

@@ -1,3 +1,6 @@
+/**
+ * @typedef {import('../../classes/data/typedef.js').IterableTreeOptions} IterableTreeOptions
+ */
 /**
  * Filter all iterated elements
  *
@@ -21,111 +24,76 @@ export function map(iterable: Iterable<any>, transformFn: Function): Generator;
  * 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: any, options?: {
+export function iterateObjectEntries(obj: object, options?: {
     walkArrays?: boolean;
-    expandPathKeys?: object;
-    outputIntermediateNodes?: object;
-    ignoreEmptyObjectLeaves?: object;
+    expandPathKeys?: boolean;
+    outputIntermediateNodes?: boolean;
+    ignoreEmptyObjectLeaves?: boolean;
+    depthFirst?: boolean;
 }): Iterator<any, any, any>;
 /**
  * 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} obj - Object to iterate
+ * @param {IterableTreeOptions & { depthFirst: boolean}} [options]
  *
- * @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
+ * @return {Iterable<string[]>} iterable object that yields path arrays
  */
-export function iterateObjectPaths(obj: any, options?: {
-    walkArrays?: boolean;
-    expandPathKeys?: object;
-    outputIntermediateNodes?: object;
-    ignoreEmptyObjectLeaves?: object;
-}): Iterator<any, any, any>;
+export function iterateObjectPaths(obj: object, options?: IterableTreeOptions & {
+    depthFirst: boolean;
+}): Iterable<string[]>;
 /**
  * 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 {object} obj - Object to iterate
+ * @param {IterableTreeOptions} [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
+ * @return {Iterable<any>} iterator object
  */
-export function iterateObjectValues(obj: any, options?: {
-    walkArrays?: boolean;
-    expandPathKeys?: object;
-    outputIntermediateNodes?: object;
-    ignoreEmptyObjectLeaves?: object;
-}): Iterator<any, any, any>;
+export function iterateObjectValues(obj: object, options?: IterableTreeOptions): Iterable<any>;
 /**
  * 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 function sortObjects({ it, getValueFn, reversed }: Iterable<any>): any[];
+export function sortObjects({ it, getValueFn, reversed }: {
+    it: Iterable<any>;
+    getValueFn: Function;
+    reversed?: boolean;
+}): Promise<any[]>;
+export type IterableTreeOptions = import("../../classes/data/typedef.js").IterableTreeOptions;