@ixfx/components 0.2.4 → 0.2.6

package/dist/dist-By5URG0Y.js

@@ -0,0 +1,1290 @@
+import { C as resultThrow, T as testPlainObjectOrPrimitive, v as integerTest, x as numberTest, y as nullUndefTest } from "./dist-D7kJgnSE.js";
+//#region node_modules/.pnpm/@ixfx+core@0.56.12/node_modules/@ixfx/core/dist/chunk-pbuEa-1d.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+//#endregion
+//#region node_modules/.pnpm/@ixfx+core@0.56.12/node_modules/@ixfx/core/dist/maps-BqikhSVo.js
+const removeCircularReferences = (value, replaceWith = null, seen = /* @__PURE__ */ new WeakSet(), path = ``) => {
+	if (value === null) return value;
+	if (typeof value !== `object`) throw new TypeError(`Param 'value' must be an object. Got type: ${typeof value}`);
+	seen.add(value);
+	const entries = Object.entries(value);
+	for (const entry of entries) {
+		if (entry[1] === null) continue;
+		if (typeof entry[1] !== `object`) continue;
+		if (seen.has(entry[1])) {
+			entry[1] = replaceWith;
+			continue;
+		}
+		entry[1] = removeCircularReferences(entry[1], replaceWith, seen, `${entry[0]}.`);
+	}
+	return Object.fromEntries(entries);
+};
+/**
+* A default converter to string that uses JSON.stringify if its an object, or the thing itself if it's a string
+*/
+const toStringDefault = (itemToMakeStringFor) => typeof itemToMakeStringFor === `string` ? itemToMakeStringFor : JSON.stringify(itemToMakeStringFor);
+/**
+* Converts a value to string form.
+* For simple objects, .toString() is used, other JSON.stringify is used.
+* It is meant for creating debugging output or 'hash' versions of objects, and does
+* not necessarily maintain full fidelity of the input
+* @param value 
+* @returns 
+*/
+const defaultToString = (value) => {
+	if (value === null) return `null`;
+	if (typeof value === `boolean` || typeof value === `number`) return value.toString();
+	if (typeof value === `string`) return value;
+	if (typeof value === `symbol`) throw new TypeError(`Symbol cannot be converted to string`);
+	try {
+		return JSON.stringify(value);
+	} catch (error) {
+		if (typeof value === `object`) return JSON.stringify(removeCircularReferences(value, `(circular)`));
+		else throw error;
+	}
+};
+/**
+* Sort numbers in ascending order.
+*
+* ```js
+* [10, 4, 5, 0].sort(numericComparer);
+* // Yields: [0, 4, 5, 10]
+* [10, 4, 5, 0].sort(comparerInverse(numericComparer));
+* // Yields: [ 10, 5, 4, 0]
+* ```
+* 
+* Returns:
+* * 0: values are equal
+* * negative: `a` should be before `b`
+* * positive: `a` should come after `b`
+* @param a
+* @param b
+* @returns
+*/
+const numericComparer = (a, b) => {
+	if (a === b) return 0;
+	if (a > b) return 1;
+	return -1;
+};
+/**
+* Default sort comparer, following same sematics as Array.sort.
+* Consider using {@link defaultComparer} to get more logical sorting of numbers.
+*
+* Note: numbers are sorted in alphabetical order, eg:
+* ```js
+* [ 10, 20, 5, 100 ].sort(jsComparer); // same as .sort()
+* // Yields: [10, 100, 20, 5]
+* ```
+* 
+* Returns -1 if x is less than y
+* Returns 1 if x is greater than y
+* Returns 0 if x is the same as y
+* @param x
+* @param y
+* @returns
+*/
+const jsComparer = (x, y) => {
+	if (x === void 0 && y === void 0) return 0;
+	if (x === void 0) return 1;
+	if (y === void 0) return -1;
+	const xString = defaultToString(x);
+	const yString = defaultToString(y);
+	if (xString < yString) return -1;
+	if (xString > yString) return 1;
+	return 0;
+};
+/**
+* Compares numbers by numeric value, otherwise uses the default
+* logic of string comparison.
+*
+* Is an ascending sort:
+* * b, a, c -> a, b, c
+* * 10, 5, 100 -> 5, 10, 100
+* 
+* Returns -1 if x is less than y
+* Returns 1 if x is greater than y
+* Returns 0 if x is the same as y
+* @param x
+* @param y
+* @see {@link comparerInverse} Inverted order
+* @returns
+*/
+const defaultComparer = (x, y) => {
+	if (typeof x === `number` && typeof y === `number`) return numericComparer(x, y);
+	return jsComparer(x, y);
+};
+/**
+* If input is a string, it is returned.
+* Otherwise, it returns the result of JSON.stringify() with fields ordered.
+* 
+* This allows for more consistent comparisons when object field orders are different but values the same.
+* @param itemToMakeStringFor 
+* @returns 
+*/
+const toStringOrdered = (itemToMakeStringFor) => {
+	if (typeof itemToMakeStringFor === `string`) return itemToMakeStringFor;
+	const allKeys = /* @__PURE__ */ new Set();
+	JSON.stringify(itemToMakeStringFor, (key, value) => (allKeys.add(key), value));
+	return JSON.stringify(itemToMakeStringFor, [...allKeys].sort());
+};
+/**
+* Default comparer function is equiv to checking `a === b`.
+* Use {@link isEqualValueDefault} to compare by value, via comparing JSON string representation.
+*/
+const isEqualDefault = (a, b) => a === b;
+/**
+* Comparer returns true if string representation of `a` and `b` are equal.
+* Use {@link isEqualDefault} to compare using === semantics
+* Uses `toStringDefault` to generate a string representation (via `JSON.stringify`).
+* 
+* Returns _false_ if the ordering of fields is different, even though values are identical:
+* ```js
+* isEqualValueDefault({ a: 10, b: 20}, { b: 20, a: 10 }); // false
+* ```
+* 
+* Use {@link isEqualValueIgnoreOrder} to ignore order (with an overhead of additional processing).
+* ```js
+* isEqualValueIgnoreOrder({ a: 10, b: 20}, { b: 20, a: 10 }); // true
+* ```
+* 
+* Use {@link isEqualValuePartial} to partially match `b` against `a`.
+* @returns True if the contents of `a` and `b` are equal
+*/
+const isEqualValueDefault = (a, b) => {
+	if (a === b) return true;
+	return toStringDefault(a) === toStringDefault(b);
+};
+/**
+* Comparer returns true if string representation of `a` and `b` are equal, regardless of field ordering.
+* Uses `toStringOrdered` to generate a string representation (via JSON.stringify`).
+* 
+* ```js
+* isEqualValueIgnoreOrder({ a: 10, b: 20}, { b: 20, a: 10 }); // true
+* isEqualValue({ a: 10, b: 20}, { b: 20, a: 10 }); // false, fields are different order
+* ```
+* 
+* There is an overhead to ordering fields. Use {@link isEqualValueDefault} if it's not possible that field ordering will change.
+* @returns True if the contents of `a` and `b` are equal
+* @typeParam T - Type of objects being compared
+*/
+const isEqualValueIgnoreOrder = (a, b) => {
+	if (a === b) return true;
+	return toStringOrdered(a) === toStringOrdered(b);
+};
+/**
+* @inheritDoc getOrGenerate
+* @param map
+* @param fn
+* @returns
+*/
+const getOrGenerateSync = (map, fn) => (key, args) => {
+	let value = map.get(key);
+	if (value !== void 0) return value;
+	value = fn(key, args);
+	map.set(key, value);
+	return value;
+};
+//#endregion
+//#region node_modules/.pnpm/@ixfx+core@0.56.12/node_modules/@ixfx/core/dist/text.js
+/**
+* Given a long string, abbreviates it with ...
+* ```js
+* abbreviate(`This is something`, 7); // `This is...`
+* ```
+* 
+* If `source` is under `maxLength` the original is returned.
+* @param source 
+* @param maxLength Maximum length. Defaults to 20
+* @returns 
+*/
+const abbreviate = (source, maxLength = 15) => {
+	resultThrow(integerTest(maxLength, `aboveZero`, `maxLength`));
+	if (typeof source !== `string`) throw new Error(`Parameter 'source' is not a string`);
+	if (source.length > maxLength && source.length > 3) {
+		if (maxLength > 15) {
+			const chunk = Math.round((maxLength - 2) / 2);
+			return source.slice(0, chunk) + `...` + source.slice(-chunk);
+		}
+		return source.slice(0, maxLength) + `...`;
+	}
+	return source;
+};
+/**
+* Uses JSON.toString() on `source`, but abbreviates result.
+* @param source Object to stringify
+* @param maxLength Default 20
+* @returns 
+*/
+const toStringAbbreviate = (source, maxLength = 20) => {
+	if (source === void 0) return `(undefined)`;
+	if (source === null) return `(null)`;
+	return abbreviate(JSON.stringify(source), maxLength);
+};
+//#endregion
+//#region node_modules/.pnpm/@ixfx+core@0.56.12/node_modules/@ixfx/core/dist/src-rzH1dhIm.js
+const cloneFromFields = (source) => {
+	const entries = [];
+	for (const field in source) {
+		const value = source[field];
+		if (testPlainObjectOrPrimitive(value)) entries.push([field, value]);
+	}
+	return Object.fromEntries(entries);
+};
+/**
+* Maps the keys of an object, returning a transformed object.
+* ```js
+* const input = {
+*  hello: `there`,
+*  chap: `chappie`
+* }
+* 
+* mapObjectKeys(input, key => key.toUppercase());
+* 
+* // Yields: { HELLO: `there`, CHAP: `chappie` }
+* ```
+* @param object 
+* @param mapFunction 
+* @returns 
+*/
+const mapObjectKeys = (object, mapFunction) => {
+	const destinationObject = {};
+	for (const entries of Object.entries(object)) {
+		const key = mapFunction(entries[0]);
+		destinationObject[key] = entries[1];
+	}
+	return destinationObject;
+};
+/**
+* Compares the keys of two objects, returning a set of those in
+* common, and those in either A or B exclusively.
+* ```js
+* const a = { colour: `red`, intensity: 5 };
+* const b = { colour: `pink`, size: 10 };
+* const c = compareObjectKeys(a, b);
+* // c.shared = [ `colour` ]
+* // c.a = [ `intensity` ]
+* // c.b = [ `size`  ]
+* ```
+* @param a 
+* @param b 
+* @returns 
+*/
+const compareObjectKeys = (a, b) => {
+	return compareIterableValuesShallow(Object.keys(a), Object.keys(b));
+};
+/**
+* Returns the changed fields from A -> B. It's assumed that A and B have the same shape.
+* ie. returns an object that only consists of fields which have changed in B compared to A.
+* 
+* ```js
+* const a = { msg: `hi`, v: 10 };
+* 
+* changedProperties(a, { msg: `hi`,   v: 10 }); // {}
+* changedProperties(a, { msg: `hi!!`, v: 10 }); // { msg: `hi!!` }
+* changedProperties(a, { msg: `hi!!` });       // { msg: `hi!!`, v: undefined }
+* ```
+* 
+* If B has additional or removed fields, this is considered an error.
+* 
+* If a field is an array, the whole array is returned, rather than a diff.
+* @param a 
+* @param b 
+*/
+const changedProperties = (a, b) => {
+	const r = compareObjectData(a, b, true);
+	if (Object.entries(r.added).length > 0) throw new Error(`Shape of data has changed`);
+	if (Object.entries(r.removed).length > 0) throw new Error(`Shape of data has changed`);
+	return compareResultToObject(r, b);
+};
+const compareResultToObject = (r, b) => {
+	const output = {};
+	if (r.isArray) return b;
+	for (const entry of Object.entries(r.changed)) output[entry[0]] = entry[1];
+	for (const entry of Object.entries(r.added)) output[entry[0]] = entry[1];
+	for (const childEntry of Object.entries(r.children)) {
+		const childResult = childEntry[1];
+		if (childResult.hasChanged) output[childEntry[0]] = compareResultToObject(childResult, b[childEntry[0]]);
+	}
+	return output;
+};
+/**
+* Produces a {@link CompareChangeSet} between two arrays.
+* 
+* @param a Earlier array to compare
+* @param b Later array to compare
+* @param eq Equality comparison for values
+* @returns Change set.
+*/
+const compareArrays = (a, b, eq = isEqualDefault) => {
+	if (!Array.isArray(a)) throw new Error(`Param 'a' is not an array`);
+	if (!Array.isArray(b)) throw new Error(`Param 'b' is not an array`);
+	const c = compareObjectData(a, b, false, eq);
+	if (!c.isArray) throw new Error(`Change set does not have arrays as parameters`);
+	const convert = (key) => {
+		if (key.startsWith(`_`)) return Number.parseInt(key.slice(1));
+		else throw new Error(`Unexpected key '${key}'`);
+	};
+	return {
+		...c,
+		added: mapObjectKeys(c.added, convert),
+		changed: mapObjectKeys(c.changed, convert),
+		removed: c.removed.map((v) => convert(v)),
+		summary: c.summary.map((value) => {
+			return [
+				value[0],
+				convert(value[1]),
+				value[2]
+			];
+		})
+	};
+};
+/**
+* Compares A to B. Assumes they are simple objects, essentially key-value pairs, where the 
+* values are primitive values or other simple objects. It also works with arrays.
+* 
+* Uses === equality semantics by default.
+* @param a 
+* @param b 
+*/
+const compareObjectData = (a, b, assumeSameShape = false, eq = isEqualDefault) => {
+	a ??= {};
+	b ??= {};
+	const entriesA = Object.entries(a);
+	const entriesB = Object.entries(b);
+	const scannedKeys = /* @__PURE__ */ new Set();
+	const changed = {};
+	const added = {};
+	const children = {};
+	const removed = [];
+	const isArray = Array.isArray(a);
+	const summary = new Array();
+	let hasChanged = false;
+	for (const entry of entriesA) {
+		const outputKey = isArray ? `_${entry[0]}` : entry[0];
+		const aValue = entry[1];
+		const bValue = b[entry[0]];
+		scannedKeys.add(entry[0]);
+		if (bValue === void 0) {
+			hasChanged = true;
+			if (assumeSameShape && !isArray) {
+				changed[outputKey] = bValue;
+				summary.push([
+					`mutate`,
+					outputKey,
+					bValue
+				]);
+			} else {
+				removed.push(outputKey);
+				summary.push([
+					`del`,
+					outputKey,
+					aValue
+				]);
+			}
+			continue;
+		}
+		if (typeof aValue === `object`) {
+			const r = compareObjectData(aValue, bValue, assumeSameShape, eq);
+			if (r.hasChanged) hasChanged = true;
+			children[outputKey] = r;
+			const childSummary = r.summary.map((sum) => {
+				return [
+					sum[0],
+					outputKey + `.` + sum[1],
+					sum[2]
+				];
+			});
+			summary.push(...childSummary);
+		} else if (!eq(aValue, bValue)) {
+			changed[outputKey] = bValue;
+			hasChanged = true;
+			summary.push([
+				`mutate`,
+				outputKey,
+				bValue
+			]);
+		}
+	}
+	if (!assumeSameShape || isArray) for (const entry of entriesB) {
+		const key = isArray ? `_${entry[0]}` : entry[0];
+		if (scannedKeys.has(entry[0])) continue;
+		added[key] = entry[1];
+		hasChanged = true;
+		summary.push([
+			`add`,
+			key,
+			entry[1]
+		]);
+	}
+	return {
+		changed,
+		added,
+		removed,
+		children,
+		hasChanged,
+		isArray,
+		summary
+	};
+};
+/**
+* Returns a copy of `object` with integer numbers as keys instead of whatever it has.
+* ```js
+* keysToNumbers({ '1': true }); // Yields: { 1: true }
+* ```
+* 
+* The `onInvalidKey` sets how to handle keys that cannot be converted to integers.
+* * 'throw' (default): throws an exception
+* * 'ignore': that key & value is ignored
+* * 'keep': uses the string key instead
+* 
+* 
+* ```js
+* keysToNumber({ hello: 'there' }, `ignore`); // Yields: {  }
+* keysToNumber({ hello: 'there' }, `throw`);  // Exception
+* keysToNumber({ hello: 'there' }, `keep`);   // Yields: { hello: 'there' }
+* ```
+* 
+* Floating-point numbers will be converted to integer by rounding.
+* ```js
+* keysToNumbers({ '2.4': 'hello' }); // Yields: { 2: 'hello' }
+* ```
+* @param object 
+* @param onInvalidKey 
+* @returns 
+*/
+const keysToNumbers = (object, onInvalidKey = `throw`) => {
+	const returnObject = {};
+	for (const entry of Object.entries(object)) {
+		const asNumber = Number.parseInt(entry[0]);
+		if (Number.isNaN(asNumber)) switch (onInvalidKey) {
+			case `throw`: throw new TypeError(`Cannot convert key '${entry[0]}' to an integer`);
+			case `ignore`: continue;
+			case `keep`:
+				returnObject[entry[0]] = entry[1];
+				continue;
+			default: throw new Error(`Param 'onInvalidKey' should be: 'throw', 'ignore' or 'keep'.`);
+		}
+		returnObject[asNumber] = entry[1];
+	}
+	return returnObject;
+};
+/**
+* Maps the top-level properties of an object through a map function.
+* That is, run each of the values of an object through a function,
+* setting the result onto the same key structure as original.
+* 
+* It is NOT recursive.
+*
+* The mapping function gets a single args object, consisting of `{ value, field, index }`,
+* where 'value' is the value of the field, 'field' the name, and 'index' a numeric count.
+* @example Double the value of all fields
+* ```js
+* const rect = { width: 100, height: 250 };
+* const doubled = mapObjectShallow(rect, args => {
+*  return args.value*2;
+* });
+* // Yields: { width: 200, height: 500 }
+* ```
+*
+* Since the map callback gets the name of the property, it can do context-dependent things.
+* ```js
+* const rect = { width: 100, height: 250, colour: 'red' }
+* const doubled = mapObjectShallow(rect, args => {
+*  if (args.field === 'width') return args.value*3;
+*  else if (typeof args.value === 'number') return args.value*2;
+*  return args.value;
+* });
+* // Yields: { width: 300, height: 500, colour: 'red' }
+* ```
+* In addition to bulk processing, it allows remapping of property types.
+*
+* In terms of type-safety, the mapped properties are assumed to have the
+* same type.
+*
+* ```js
+* const o = {
+*  x: 10,
+*  y: 20,
+*  width: 200,
+*  height: 200
+* }
+*
+* // Make each property use an averager instead
+* const oAvg = mapObjectShallow(o, args => {
+*  return movingAverage(10);
+* });
+*
+* // Instead of { x:number, y:number... }, we now have { x:movingAverage(), y:movingAverage()... }
+* // Add a value to the averager
+* oAvg.x.add(20);
+* ```
+*/
+const mapObjectShallow = (object, mapFunction) => {
+	const mapped = Object.entries(object).map(([sourceField, sourceFieldValue], index) => [sourceField, mapFunction({
+		value: sourceFieldValue,
+		field: sourceField,
+		index,
+		path: sourceField
+	})]);
+	return Object.fromEntries(mapped);
+};
+/**
+* Maps the contents of `data` using `mapper` as a structured set of map functions.
+* ```js
+* const a = {
+*  person: {
+*    size: 20
+*  }
+*  hello: `there`
+* }
+* mapObjectByObject(a, {
+*  person: {
+*    size: (value, context) => {
+*      return value * 2
+*    }
+*  }
+* });
+* // Yields: { person: { size: 40 }, hello: `there` }
+* ```
+* @param data 
+* @param mapper 
+* @returns 
+*/
+function mapObjectByObject(data, mapper) {
+	const entries = Object.entries(data);
+	for (const entry of entries) if (entry[0] in mapper) {
+		const m = mapper[entry[0]];
+		entry[1] = typeof m === `object` ? mapObjectByObject(entry[1], m) : m(entry[1], data);
+	}
+	return Object.fromEntries(entries);
+}
+/**
+* Merges objects together, the rightmost objects overriding properties of earlier objects.
+* 
+* The return type is the intersection of all properties
+* ```js
+* const a = { name: `jane`, age: 30 };
+* const b = { name: `fred`, age: 31, colour: `blue` };
+* const c = merge(a, b);
+* // Yields:
+* // { name: `fred`, age: 31, colour: `blue` } 
+* ```
+* 
+* Alternatively, use {@link mergeSameShape} if the return shape
+* should be based on the first object.
+* @param a 
+* @returns Merged object
+*/
+function merge(...a) {
+	return Object.assign({}, ...a);
+}
+/**
+* Merges objects together, conforming to the shape of the first object.
+* Properties contained on later objects are ignored if they aren't part of the first.
+* 
+* If a single object is passed in, a copy is returned.
+* 
+* Use {@link merge} for object shape to be a union
+* @param a Object arrays to merge
+* @returns 
+*/
+function mergeSameShape(...a) {
+	const aEntries = Object.entries(a[0]);
+	for (let index = 1; index < a.length; index++) {
+		const bEntries = Object.entries(a[index]);
+		for (const [key, value] of bEntries) {
+			const aEntry = aEntries.find(([aKey]) => aKey === key);
+			if (aEntry) aEntry[1] = value;
+		}
+	}
+	return Object.fromEntries(aEntries);
+}
+/**
+* Returns a new object based on `data` but with all
+* properties prefixed by `prefix`.
+* 
+* ```js
+* prefixProperties({ name: `x`, size: 10 }, `test-`);
+* 
+* // Yields:
+* // { test-name: `x`, test-size: 10 }
+* ```
+* @param data 
+* @param prefix 
+* @returns 
+*/
+function prefixProperties(data, prefix) {
+	const changed = [];
+	for (const d of data) {
+		const entries = Object.entries(d);
+		const changedEntries = [];
+		for (const [key, value] of entries) changedEntries.push([prefix + key, value]);
+		changed.push(Object.fromEntries(changedEntries));
+	}
+	return changed;
+}
+/**
+* Returns _true_ if `value` is number, string, bigint or boolean.
+* Returns _false_ if `value` is an object, null, undefined
+* 
+* Use {@link isPrimitiveOrObject} to also return true if `value` is an object.
+* @param value Value to check
+* @returns _True_ if value is number, string, bigint or boolean.
+*/
+function isPrimitive(value) {
+	if (typeof value === `number`) return true;
+	if (typeof value === `string`) return true;
+	if (typeof value === `bigint`) return true;
+	if (typeof value === `boolean`) return true;
+	return false;
+}
+/**
+* Helper function to get a 'friendly' string representation of an array of {@link RecordEntry}.
+* @param entries
+* @returns
+*/
+function prettyPrintEntries(entries) {
+	if (entries.length === 0) return `(empty)`;
+	let t = ``;
+	for (const [index, entry] of entries.entries()) {
+		t += `  `.repeat(index);
+		t += `${entry.name} = ${JSON.stringify(entry.nodeValue)}\n`;
+	}
+	return t;
+}
+/**
+* Returns a human-friendly debug string for a tree-like structure
+* ```js
+* console.log(Trees.prettyPrint(obj));
+* ```
+* @param indent
+* @param node
+* @param options
+* @returns
+*/
+function recordEntryPrettyPrint(node, indent = 0, options = {}) {
+	resultThrow(nullUndefTest(node, `node`));
+	const entry = getNamedRecordEntry(node, options.name ?? `node`);
+	const t = `${`  `.repeat(indent)} + name: ${entry.name} value: ${JSON.stringify(entry.nodeValue)}`;
+	const childrenAsArray = [...recordChildren(node, options)];
+	return childrenAsArray.length > 0 ? `${t}\n${childrenAsArray.map((d) => recordEntryPrettyPrint(d.nodeValue, indent + 1, {
+		...options,
+		name: d.name
+	})).join(`\n`)}` : t;
+}
+/**
+* Returns the direct children of a tree-like object as a pairing
+* of node name and value. Supports basic objects, Maps and arrays.
+*
+* Sub-children are included as an object blob.
+*
+* @example Simple object
+* ```js
+* const o = {
+*  colour: {
+*    r: 0.5, g: 0.5, b: 0.5
+*  }
+* };
+*
+* const children = [ ...Trees.children(o) ];
+* // Children:
+* // [
+* //  { name: "colour", value: { b: 0.5, g: 0.5, r: 0.5 } }
+* // ]
+* const subChildren = [ ...Trees.children(o.colour) ];
+* // [ { name: "r", value: 0.5 }, { name: "g", value: 0.5 }, { name: "b", value: 0.5 } ]
+* ```
+*
+* Arrays are assigned a name based on index.
+* @example Arrays
+* ```js
+* const colours = [ { r: 1, g: 0, b: 0 }, { r: 0, g: 1, b: 0 }, { r: 0, g: 0, b: 1 } ];
+* // Children:
+* // [
+* //  { name: "array[0]", value: {r:1,g:0,b:0} },
+* //  { name: "array[1]", value: {r:0,g:1,b:0} },
+* //  { name: "array[2]", value: {r:0,g:0,b:1} },
+* // ]
+* ```
+*
+* Pass in `options.name` (eg 'colours') to have names generated as 'colours[0]', etc.
+* Options can also be used to filter children. By default all direct children are returned.
+* @param node
+* @param options
+*/
+function* recordChildren(node, options = {}) {
+	resultThrow(nullUndefTest(node, `node`));
+	const filter = options.filter ?? `none`;
+	const filterByValue = (v) => {
+		if (filter === `none`) return [true, isPrimitive(v)];
+		else if (filter === `leaves` && isPrimitive(v)) return [true, true];
+		else if (filter === `branches` && !isPrimitive(v)) return [true, false];
+		return [false, isPrimitive(v)];
+	};
+	if (Array.isArray(node)) for (const [index, element] of node.entries()) {
+		const f = filterByValue(element);
+		if (f[0]) yield {
+			name: index.toString(),
+			sourceValue: element,
+			nodeValue: f[1] ? element : void 0
+		};
+	}
+	else if (typeof node === `object`) if (options.withPrototype) for (const name in node) {
+		const value = node[name];
+		const f = filterByValue(value);
+		if (f[0]) yield {
+			name,
+			sourceValue: value,
+			nodeValue: f[1] ? value : void 0
+		};
+	}
+	else {
+		const entriesIter = `entries` in node ? node.entries() : Object.entries(node);
+		for (const [name, value] of entriesIter) {
+			const f = filterByValue(value);
+			if (f[0]) yield {
+				name,
+				sourceValue: value,
+				nodeValue: f[1] ? value : void 0
+			};
+		}
+	}
+}
+function* recordEntriesDepthFirst(node, options = {}, ancestors = []) {
+	if (node === null || node === void 0) return;
+	const opts = {
+		filter: options.filter ?? `none`,
+		name: options.name ?? ``,
+		withPrototype: options.withPrototype ?? false,
+		seen: options.seen ?? /* @__PURE__ */ new WeakSet()
+	};
+	if (typeof node === `object`) {
+		if (opts.seen.has(node)) return;
+		opts.seen.add(node);
+	}
+	for (const c of recordChildren(node, opts)) {
+		yield {
+			...c,
+			ancestors: [...ancestors]
+		};
+		yield* recordEntriesDepthFirst(c.sourceValue, opts, [...ancestors, c.name]);
+	}
+}
+/**
+* Finds a given direct child by name
+* @param name
+* @param node
+* @returns
+*/
+function recordEntryChildByName(name, node) {
+	for (const d of recordChildren(node)) if (d.name === name) return d;
+}
+/**
+* Returns the closest matching entry, tracing `path` in an array, Map or simple object.
+* Returns an entry with _undefined_ value at the point where tracing stopped.
+* Use {@link traceRecordEntryByPath} to step through all the segments.
+*
+* ```js
+* const people = {
+*  jane: {
+*   address: {
+*    postcode: 1000,
+*    street: 'West St',
+*    city: 'Blahville'
+*   },
+* colour: 'red'
+*  }
+* }
+* Trees.getByPath('jane.address.postcode', people); // '.' default separator
+* // ['postcode', 1000]
+* Trees.getByPath('jane.address.country.state', people);
+* // ['country', undefined] - since full path could not be resolved.
+* ```
+* @param path Path, eg `jane.address.postcode`
+* @param node Node to look within
+* @param options Options for parsing path. By default '.' is used as a separator
+* @returns
+*/
+function getRecordEntryByPath(path, node, options = {}) {
+	const paths = [...traceRecordEntryByPath(path, node, options)];
+	if (paths.length === 0) throw new Error(`Could not trace path: ${path} `);
+	return paths.at(-1);
+}
+/**
+* Enumerates over children of `node` towards the node named in `path`.
+* This is useful if you want to get the interim steps to the target node.
+*
+* Use {@link getRecordEntryByPath} if you don't care about interim steps.
+*
+* ```js
+* const people = {
+*  jane: {
+*   address: {
+*    postcode: 1000,
+*    street: 'West St',
+*    city: 'Blahville'
+*   },
+* colour: 'red'
+*  }
+* }
+* for (const p of Trees.traceByPath('jane.address.street', people)) {
+* // { name: "jane", value: { address: { postcode: 1000,street: 'West St', city: 'Blahville' }, colour: 'red'} },
+* // { name: "address", value: { postcode: 1000, street: 'West St', city: 'Blahville' } },
+* // { name: "street", value: "West St" } }
+* }
+* ```
+*
+* Results stop when the path can't be followed any further.
+* The last entry will have a name of the last sought path segment, and _undefined_ as its value.
+*
+* @param path Path to traverse
+* @param node Starting node
+* @param options Options for path traversal logic
+* @returns
+*/
+function* traceRecordEntryByPath(path, node, options = {}) {
+	resultThrow(nullUndefTest(path, `path`), nullUndefTest(node, `node`));
+	const separator = options.separator ?? `.`;
+	const pathSplit = path.split(separator);
+	const ancestors = [];
+	for (const p of pathSplit) {
+		const entry = recordEntryChildByName(p, node);
+		if (!entry) {
+			yield {
+				name: p,
+				sourceValue: void 0,
+				nodeValue: void 0,
+				ancestors
+			};
+			return;
+		}
+		node = entry.sourceValue;
+		yield {
+			...entry,
+			ancestors: [...ancestors]
+		};
+		ancestors.push(p);
+	}
+}
+/**
+* Generates a name for a node.
+* Uses the 'name' property if it exists, otherwise uses `defaultName`
+* @param node
+* @param defaultName
+* @returns
+*/
+function getNamedRecordEntry(node, defaultName = ``) {
+	if (`name` in node && `nodeValue` in node && `sourceValue` in node) return node;
+	if (`name` in node) return {
+		name: node.name,
+		nodeValue: node,
+		sourceValue: node
+	};
+	return {
+		name: defaultName,
+		nodeValue: node,
+		sourceValue: node
+	};
+}
+/**
+* Yields numerical values based on the an input of objects and the property to use.
+* 
+* ```js
+* const data = [
+*  { size: 10 },  { size: 20 }, { size: 0 }
+* ]
+* [...enumerateNumericalValues(data, `size`)]; // [ 10, 20, 0 ]
+* ```
+* 
+* If any of objects has a non numerical value for `propertyName`, a TypeError is thrown.
+* @param records 
+* @param propertyName 
+* @returns 
+*/
+function* enumerateNumericalValues(records, propertyName) {
+	for (const rec of records) {
+		const fieldValue = rec[propertyName];
+		if (typeof fieldValue !== `number`) throw new TypeError(`Property value was not a number. Property: ${propertyName} Value: ${fieldValue} Type: ${typeof fieldValue}`);
+		yield fieldValue;
+	}
+}
+/**
+* Merge corresponding objects from arrays. This is assuming objects at the same array indices are connected.
+* 
+* Arrays must be the same length. When merging objects, the properties of later objects override those of earlier objects.
+* 
+* ```js
+* const a = [ { name: `jane`, age: 30 }, { name: `bob`, age: 40 } ];
+* const b = [ { name: `fred`, colour: `red` }, { name: `johanne` } ];
+* const c = [...zip(a, b)];
+* // Yields:
+* // [
+* //   { name: `fred`, age: 30, colour: `red` },
+* //   { name: `johanne`, age: 40 }
+* // ]
+* ```
+* @param toMerge Arrays to merge
+* @throws {TypeError} If either parameter is not an array
+* @throws {TypeError} If the arrays are not of the same length
+* @returns Generator of merged records 
+*/
+function* zip$1(...toMerge) {
+	let len = -1;
+	for (let index = 0; index < toMerge.length; index++) {
+		if (!Array.isArray(toMerge[index])) throw new TypeError(`Value at index ${index} is not an array as expected`);
+		if (len === -1) len = toMerge[index].length;
+		else if (toMerge[index].length !== len) throw new TypeError(`Array length mismatch. Expected: ${len} Actual: ${toMerge[index].length} Array: ${index}`);
+	}
+	for (let index = 0; index < len; index++) yield merge(...toMerge.map((arr) => arr[index]));
+}
+var records_exports = /* @__PURE__ */ __exportAll({
+	changedProperties: () => changedProperties,
+	cloneFromFields: () => cloneFromFields,
+	compareArrays: () => compareArrays,
+	compareObjectData: () => compareObjectData,
+	compareObjectKeys: () => compareObjectKeys,
+	enumerateNumericalValues: () => enumerateNumericalValues,
+	getRecordEntryByPath: () => getRecordEntryByPath,
+	keysToNumbers: () => keysToNumbers,
+	mapObjectByObject: () => mapObjectByObject,
+	mapObjectKeys: () => mapObjectKeys,
+	mapObjectShallow: () => mapObjectShallow,
+	merge: () => merge,
+	mergeSameShape: () => mergeSameShape,
+	prefixProperties: () => prefixProperties,
+	prettyPrintEntries: () => prettyPrintEntries,
+	recordChildren: () => recordChildren,
+	recordEntriesDepthFirst: () => recordEntriesDepthFirst,
+	recordEntryPrettyPrint: () => recordEntryPrettyPrint,
+	removeCircularReferences: () => removeCircularReferences,
+	traceRecordEntryByPath: () => traceRecordEntryByPath,
+	zip: () => zip$1
+});
+/**
+* Returns a {@link Continuously} that continually executes `callback` at `interval` rate.
+* 
+* By default, first the sleep period happens and then the callback happens.
+*
+* Call `start` to begin/reset loop. The looping stops when `cancel` is called, or when `callback` returns _false_.
+*
+* @example
+* Animation loop
+* ```js
+* const draw = () => {
+*  // Draw on canvas
+* }
+*
+* // Run draw() synchronised with monitor refresh rate via `window.requestAnimationFrame`
+* continuously(draw).start();
+* ```
+*
+* @example
+* With delay
+* ```js
+* const fn = () => {
+*  // Runs after one minute
+* }
+* const c = continuously(fn, { mins: 1 } );
+* c.start(); // Runs `fn` every minute
+* ```
+*
+* @example
+* Control a 'continuously'
+* ```js
+* c.cancel();   // Stop the loop, cancelling any up-coming calls to `fn`
+* c.elapsedMs;  // How many milliseconds have elapsed since start
+* c.ticks;      // How many iterations of loop since start
+* c.interval;   // Get/set speed of loop. Change kicks-in at next loop.
+*               // Use .start() to reset to new interval immediately
+* ```
+*
+* Asynchronous callback functions are supported too:
+* ```js
+* continuously(async () => { ..});
+* ```
+*
+* The `callback` function can receive a few arguments:
+* 
+* ```js
+* continuously( (ticks, elapsedMs) => {
+*  // ticks: how many times loop has run
+*  // elapsedMs:  how long since last loop
+* }).start();
+* ```
+*
+* If the callback explicitly returns _false_, the loop will be cancelled.
+* 
+* ```js
+* continuously(ticks => {
+*  // Stop after 100 iterations
+*  if (ticks > 100) return false;
+* }).start();
+* ```
+*
+* You can intercept the logic for calls to `start()` with `onStartCalled`. It can determine
+* whether the `start()` proceeds, if the loop is cancelled, or the whole thing disposed,
+* so it can't run any longer.
+* 
+* ```js
+* continuously(callback, intervalMs, {
+*  onStartCalled:(ticks, elapsedMs) => {
+*    // Cancel the loop after 1000ms has elapsed
+*    if (elapsedMs > 1000) return `cancel`;
+*  }
+* }).start();
+* ```
+*
+* To run `callback` *before* the sleep happens, set `fireBeforeWait`:
+* ```js
+* continuously(callback, intervalMs, { fireBeforeWait: true });
+* ```
+* @param callback - Function to run. If it returns _false_, loop exits.
+* @param options - {@link ContinuouslyOpts ContinuouslyOpts}
+* @param interval - Speed of loop (default: 0)
+* @returns Instance to control looping.
+* @see Flow.timeout if you want to trigger something once.
+*/
+const continuously = (callback, interval = 0, options = {}) => {
+	let intervalMs = intervalToMs(interval, 0);
+	resultThrow(integerTest(intervalMs, `positive`, `interval`));
+	const fireBeforeWait = options.fireBeforeWait ?? false;
+	const onStartCalled = options.onStartCalled;
+	const signal = options.signal;
+	let disposed = false;
+	let runState = `idle`;
+	let startCount = 0;
+	let startCountTotal = 0;
+	let startedAt = performance.now();
+	let intervalUsed = interval ?? 0;
+	let cancelled = false;
+	let currentTimer;
+	const deschedule = () => {
+		if (currentTimer === void 0) return;
+		globalThis.clearTimeout(currentTimer);
+		currentTimer = void 0;
+		startCount = 0;
+		startedAt = NaN;
+	};
+	const schedule = (scheduledCallback) => {
+		if (intervalMs === 0) if (typeof requestAnimationFrame === `undefined`) currentTimer = globalThis.setTimeout(scheduledCallback, 0);
+		else {
+			currentTimer = void 0;
+			requestAnimationFrame(scheduledCallback);
+		}
+		else currentTimer = globalThis.setTimeout(scheduledCallback, intervalMs);
+	};
+	const cancel = () => {
+		if (cancelled) return;
+		cancelled = true;
+		if (runState === `idle`) return;
+		runState = `idle`;
+		deschedule();
+	};
+	const loop = async () => {
+		if (signal?.aborted) runState = `idle`;
+		if (runState === `idle`) return;
+		runState = `running`;
+		startCount++;
+		startCountTotal++;
+		const valueOrPromise = callback(startCount, performance.now() - startedAt);
+		const value = typeof valueOrPromise === `object` ? await valueOrPromise : valueOrPromise;
+		if (cancelled) return;
+		runState = `scheduled`;
+		if (value !== void 0 && !value) {
+			cancel();
+			return;
+		}
+		if (cancelled) return;
+		schedule(loop);
+	};
+	const start = () => {
+		if (disposed) throw new Error(`Disposed`);
+		cancelled = false;
+		if (onStartCalled !== void 0) switch (onStartCalled(startCount, performance.now() - startedAt)) {
+			case `cancel`:
+				cancel();
+				return;
+			case `reset`:
+				reset();
+				return;
+			case `dispose`:
+				disposed = true;
+				cancel();
+				return;
+		}
+		if (runState === `idle`) {
+			startCount = 0;
+			startedAt = performance.now();
+			runState = `scheduled`;
+			if (fireBeforeWait) loop();
+			else schedule(loop);
+		}
+	};
+	const reset = () => {
+		if (disposed) throw new Error(`Disposed`);
+		cancelled = false;
+		startCount = 0;
+		startedAt = NaN;
+		if (runState !== `idle`) cancel();
+		start();
+	};
+	return {
+		start,
+		reset,
+		cancel,
+		get interval() {
+			return intervalUsed;
+		},
+		get runState() {
+			return runState;
+		},
+		get startCountTotal() {
+			return startCountTotal;
+		},
+		get startCount() {
+			return startCount;
+		},
+		set interval(interval) {
+			const ms = intervalToMs(interval, 0);
+			resultThrow(integerTest(ms, `positive`, `interval`));
+			intervalMs = ms;
+			intervalUsed = interval;
+		},
+		get isDisposed() {
+			return disposed;
+		},
+		get elapsedMs() {
+			return performance.now() - startedAt;
+		}
+	};
+};
+/**
+* Compares the values of two iterables, returning a list
+* of items they have in common and those unique in `a` or `b`.
+* Ignores ordering of values, and is NOT recursive.
+*
+* ```js
+* const a = ['apples', 'oranges', 'pears' ]
+* const b = ['pears', 'kiwis', 'bananas' ];
+*
+* const r = compareValuesShallow(a, b);
+* r.shared;  // [ 'pears' ]
+* r.a;       // [ 'apples', 'oranges' ]
+* r.b;       // [ 'kiwis', 'bananas' ]
+* ```
+* 
+* By default uses === semantics for comparison.
+* @param a
+* @param b
+* @param eq
+* @returns
+*/
+const compareIterableValuesShallow = (a, b, eq = isEqualDefault) => {
+	const shared = [];
+	const aUnique = [];
+	const bUnique = [];
+	for (const elementOfA of a) {
+		let seenInB = false;
+		for (const elementOfB of b) if (eq(elementOfA, elementOfB)) {
+			seenInB = true;
+			break;
+		}
+		if (seenInB) shared.push(elementOfA);
+		else aUnique.push(elementOfA);
+	}
+	for (const elementOfB of b) {
+		let seenInA = false;
+		for (const elementOfA of a) if (eq(elementOfB, elementOfA)) seenInA = true;
+		if (!seenInA) bUnique.push(elementOfB);
+	}
+	return {
+		shared,
+		isSame: aUnique.length === 0 && bUnique.length === 0,
+		a: aUnique,
+		b: bUnique
+	};
+};
+/**
+* Return the millisecond value of an Interval.
+* 
+* ```js
+* intervalToMs(100); // 100
+* intervalToMs({ millis: 100 }); // 100
+* ```
+*
+* Use `defaultNumber` to return a default in the case of
+* _undefined_ or invalid input.
+*
+* ```js
+* intervalToMs(undefined);      // throws error
+* intervalToMs(undefined, 100); // 100
+* ```
+*
+* If no default is provided, an exception is thrown.
+* @param interval Interval
+* @param defaultNumber Default value if `interval` is _undefined_ or invalid
+* @returns Milliseconds
+*/
+function intervalToMs(interval, defaultNumber) {
+	if (isInterval(interval)) {
+		if (typeof interval === `number`) return interval;
+		let ms = interval.millis ?? 0;
+		ms += (interval.hours ?? 0) * 60 * 60 * 1e3;
+		ms += (interval.mins ?? 0) * 60 * 1e3;
+		ms += (interval.secs ?? 0) * 1e3;
+		return ms;
+	} else {
+		if (typeof defaultNumber !== `undefined`) return defaultNumber;
+		throw new Error(`Not a valid interval: ${JSON.stringify(interval)}`);
+	}
+}
+/**
+* Returns _true_ if `interval` matches the {@link Interval} type.
+* @param interval 
+* @returns _True_ if `interval` is an {@link Interval}.
+*/
+function isInterval(interval) {
+	if (typeof interval === `undefined`) return false;
+	if (interval === null) return false;
+	if (typeof interval === `number`) {
+		if (Number.isNaN(interval)) return false;
+		if (!Number.isFinite(interval)) return false;
+		return true;
+	}
+	if (typeof interval !== `object`) return false;
+	const hasMillis = `millis` in interval;
+	const hasSecs = `secs` in interval;
+	const hasMins = `mins` in interval;
+	const hasHours = `hours` in interval;
+	if (hasMillis && !numberTest(interval.millis).success) return false;
+	if (hasSecs && !numberTest(interval.secs).success) return false;
+	if (hasMins && !numberTest(interval.mins).success) return false;
+	if (hasHours && !numberTest(interval.hours).success) return false;
+	if (hasMillis || hasSecs || hasHours || hasMins) return true;
+	return false;
+}
+/**
+* Returns a function that resolves `object`.
+*
+* Use {@link resolveFields} to resolve an object directly.
+* @param object
+* @returns
+*/
+if (typeof window === `undefined` || !(`requestAnimationFrame` in window)) {
+	if (typeof window === `undefined`) globalThis.requestAnimationFrame = (callback) => {
+		setTimeout(callback, 1);
+	};
+}
+//#endregion
+export { toStringAbbreviate as a, isEqualDefault as c, records_exports as i, isEqualValueDefault as l, intervalToMs as n, defaultComparer as o, isPrimitive as r, getOrGenerateSync as s, continuously as t, isEqualValueIgnoreOrder as u };
+
+//# sourceMappingURL=dist-By5URG0Y.js.map