@hkdigital/lib-core 0.3.1

package/dist/util/image/index.js

@@ -0,0 +1,86 @@
+/**
+ * Returns the unchanged image meta object or the last item of
+ * an array of ImageMeta objects. This is assumed to be a list
+ * of sorted responsive image formats, so it should be the
+ * largest image.
+ *
+ * @param {ImageMeta|ImageMeta[]} imageMeta
+ */
+export function toSingleImageMeta(imageMeta) {
+  if (Array.isArray(imageMeta)) {
+    if (!imageMeta.length) {
+      throw new Error('List of ImageMeta objects is empty');
+    }
+    imageMeta = imageMeta[imageMeta.length - 1];
+  }
+
+  if (typeof imageMeta === 'object') {
+    return imageMeta;
+  } else if (!imageMeta) {
+    throw new Error('Missing [imageMeta]');
+  }
+
+  throw new Error('Invalid value for parameter [imageMeta]');
+}
+
+/**
+ * Calculate effective width based on container dimensions and fit mode
+ *
+ * @param {object} params
+ * @param {number} [params.containerWidth] Container width in pixels
+ * @param {number} [params.containerHeight] Container height in pixels
+ * @param {number} params.imageAspectRatio Original image aspect ratio (width/height)
+ * @param {'cover'|'contain'|'fill'} [params.fit='contain'] Fit mode
+ * @returns {number} Effective width needed
+ */
+export function calculateEffectiveWidth({
+  containerWidth,
+  containerHeight,
+  imageAspectRatio,
+  fit = 'contain'
+}) {
+  if (containerWidth && !containerHeight) {
+    // If only width is provided, use it
+
+    return containerWidth;
+  }
+
+  if (!containerWidth && containerHeight) {
+    // If only height is provided, calculate width based on aspect ratio
+
+    return containerHeight * imageAspectRatio;
+  }
+
+  if (containerWidth && containerHeight) {
+    // If both dimensions are provided, calculate based on fit mode
+
+    const containerAspectRatio = containerWidth / containerHeight;
+
+    switch (fit) {
+      case 'fill':
+        return containerWidth;
+
+      case 'contain':
+        if (containerAspectRatio > imageAspectRatio) {
+          // Height constrained, scale width accordingly
+
+          return containerHeight * imageAspectRatio;
+        }
+        return containerWidth;
+
+      case 'cover':
+        if (containerAspectRatio < imageAspectRatio) {
+          // Height constrained, scale width accordingly
+
+          return containerHeight * imageAspectRatio;
+        }
+        return containerWidth;
+
+      default:
+        return containerWidth;
+    }
+  }
+
+  // Fallback if neither dimension is provided
+  throw new Error('Either containerWidth or containerHeight must be provided');
+}

package/dist/util/index.d.ts

@@ -0,0 +1,3 @@
+export * as exceptions from "./exceptions/index.js";
+export * as expect from "./expect/index.js";
+export * as singleton from "./singleton/index.js";

package/dist/util/index.js

@@ -0,0 +1,3 @@
+export * as exceptions from './exceptions/index.js';
+export * as expect from './expect/index.js';
+export * as singleton from './singleton/index.js';

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

@@ -0,0 +1,68 @@
+/** 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: any): boolean;
+/**
+ * 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: any): boolean;
+/**
+ * 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: any): boolean;
+/**
+ * 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: any): boolean;
+/**
+ * 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: any): boolean;
+/**
+ * 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: any): boolean;
+/**
+ * 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: any): boolean;

package/dist/util/is/index.js

@@ -0,0 +1,140 @@
+/** 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;
+}

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

@@ -0,0 +1,131 @@
+/**
+ * Filter all iterated elements
+ *
+ * @param {Iterable} iterable
+ * @param {function} filterFn
+ *
+ * @returns {Generator} generator that produces items that pass the filter
+ */
+export function filter(iterable: Iterable<any>, filterFn: Function): Generator;
+/**
+ * Map all iterated items
+ * - Outputs transformed items
+ *
+ * @param {Iterable} iterable
+ * @param {function} transformFn
+ *
+ * @returns {Generator} generator that produces transformed items
+ */
+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} [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: any, options?: {
+    walkArrays?: boolean;
+    expandPathKeys?: object;
+    outputIntermediateNodes?: object;
+    ignoreEmptyObjectLeaves?: object;
+}): 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} [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: any, options?: {
+    walkArrays?: boolean;
+    expandPathKeys?: object;
+    outputIntermediateNodes?: object;
+    ignoreEmptyObjectLeaves?: object;
+}): Iterator<any, any, any>;
+/**
+ * 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: any, options?: {
+    walkArrays?: boolean;
+    expandPathKeys?: object;
+    outputIntermediateNodes?: object;
+    ignoreEmptyObjectLeaves?: object;
+}): Iterator<any, any, 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
+ *   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 function sortObjects({ it, getValueFn, reversed }: Iterable<any>): any[];

package/dist/util/iterate/index.js

@@ -0,0 +1,234 @@
+/* ------------------------------------------------------------------ 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;
+}