@oscarpalmer/atoms 0.184.2 → 0.186.0

package/dist/index.mjs

@@ -143,9 +143,15 @@ function groupArraysBy(array, first, second) {
 //#region src/internal/array/chunk.ts
 /**
 * Chunk an array into smaller arrays
+*
 * @param array Array to chunk
 * @param size Size of each chunk _(minimum is `1`, maximum is `5000`; defaults to `5000`)_
 * @returns Array of arrays
+*
+* @example
+* ```typescript
+* chunk([1, 2, 3, 4, 5], 2); // => [[1, 2], [3, 4], [5]]
+* ```
 */
 function chunk(array, size) {
 	if (!Array.isArray(array)) return [];
@@ -441,8 +447,14 @@ function findLast(array, ...parameters) {
 //#region src/array/flatten.ts
 /**
 * Flatten an array _(using native `flat` and maximum depth)_
+*
 * @param array Array to flatten
 * @returns Flattened array
+*
+* @example
+* ```typescript
+* flatten([1, [2, [3, 4], 5], 6]); // => [1, 2, 3, 4, 5, 6]
+* ```
 */
 function flatten(array) {
 	return Array.isArray(array) ? array.flat(Number.POSITIVE_INFINITY) : [];
@@ -525,16 +537,16 @@ function partition(array, ...parameters) {
 	return [matched, notMatched];
 }
 //#endregion
-//#region src/array/position.ts
+//#region src/array/match.ts
 function endsWithArray(haystack, needle, key) {
 	return endings.has(getPosition(haystack, needle, key)[1]);
 }
-function getArrayPosition(haystack, needle, key) {
+function getArrayComparison(haystack, needle, key) {
 	return getPosition(haystack, needle, key)[1];
 }
 function getName(start, haystack, needle) {
-	if (start === 0) return haystack === needle ? POSITION_SAME : POSITION_START;
-	return start + needle === haystack ? POSITION_END : POSITION_INSIDE;
+	if (start === 0) return haystack === needle ? COMPARISON_SAME : COMPARISON_START;
+	return start + needle === haystack ? COMPARISON_END : COMPARISON_INSIDE;
 }
 function getPosition(haystack, needle, key) {
 	if (!Array.isArray(haystack) || !Array.isArray(needle)) return invalid;
@@ -569,24 +581,32 @@ function indexOfArray(haystack, needle, key) {
 function startsWithArray(haystack, needle, key) {
 	return starts.has(getPosition(haystack, needle, key)[1]);
 }
-const POSITION_END = "end";
-const POSITION_INSIDE = "inside";
-const POSITION_INVALID = "invalid";
-const POSITION_OUTSIDE = "outside";
-const POSITION_SAME = "same";
-const POSITION_START = "start";
-const endings = new Set([POSITION_END, POSITION_SAME]);
-const invalid = [-1, POSITION_INVALID];
-const outside = [-1, POSITION_OUTSIDE];
-const outsides = new Set([POSITION_INVALID, POSITION_OUTSIDE]);
-const starts = new Set([POSITION_START, POSITION_SAME]);
+const COMPARISON_END = "end";
+const COMPARISON_INSIDE = "inside";
+const COMPARISON_INVALID = "invalid";
+const COMPARISON_OUTSIDE = "outside";
+const COMPARISON_SAME = "same";
+const COMPARISON_START = "start";
+const endings = new Set([COMPARISON_END, COMPARISON_SAME]);
+const invalid = [-1, COMPARISON_INVALID];
+const outside = [-1, COMPARISON_OUTSIDE];
+const outsides = new Set([COMPARISON_INVALID, COMPARISON_OUTSIDE]);
+const starts = new Set([COMPARISON_START, COMPARISON_SAME]);
 //#endregion
 //#region src/array/push.ts
 /**
 * Push items into an array _(at the end)_
+*
+* _(Uses chunking to avoid call stack size being exceeded)_
+*
 * @param array Original array
 * @param pushed Pushed items
 * @returns New length of the array
+*
+* @example
+* ```typescript
+* push([1, 2, 3], [4, 5]); // => 5 (new length); array becomes [1, 2, 3, 4, 5]
+* ```
 */
 function push(array, pushed) {
 	return insertValues(INSERT_TYPE_PUSH, array, pushed, array.length, 0);
@@ -595,6 +615,7 @@ function push(array, pushed) {
 //#region src/array/reverse.ts
 /**
 * Reverse the order of items in an array
+*
 * @param array Array to reverse
 * @returns Reversed array
 */
@@ -678,7 +699,8 @@ const EXTRACT_TAKE = "take";
 //#endregion
 //#region src/array/splice.ts
 function splice(array, start, deleteCountOrItems, items) {
-	return insertValues(INSERT_TYPE_SPLICE, array, typeof deleteCountOrItems === "number" ? items : deleteCountOrItems, start, typeof deleteCountOrItems === "number" ? deleteCountOrItems : 0);
+	const deleteCountIsNumber = typeof deleteCountOrItems === "number";
+	return insertValues(INSERT_TYPE_SPLICE, array, deleteCountIsNumber ? items : deleteCountOrItems, start, deleteCountIsNumber ? deleteCountOrItems : 0);
 }
 //#endregion
 //#region src/array/to-set.ts
@@ -795,10 +817,20 @@ move.toIndex = moveToIndex;
 * If the from index is out of bounds, the array will be returned unchanged
 *
 * Available as `moveIndices` and `move.indices`
+*
 * @param array Array to move within
 * @param from Index to move from
 * @param to Index to move to
 * @returns Original array with item moved _(or unchanged if unable to move)_
+*
+* @example
+* ```typescript
+* const array = [1, 2, 3, 4];
+*
+* moveIndices(array, 0, 2);  // => [2, 3, 1, 4]
+* moveIndices(array, -1, 0); // => [4, 2, 3, 1]
+* moveIndices(array, 5, 1);  // => [4, 2, 3, 1] (unchanged)
+* ```
 */
 function moveIndices(array, from, to) {
 	if (!Array.isArray(array)) return [];
@@ -1196,7 +1228,7 @@ function sortArray(array, sorters) {
 	const { length } = sorters;
 	return array.length > 1 ? array.sort((first, second) => getComparisonValue(first, second, sorters, length)) : array;
 }
-sort.index = getSortedIndex;
+sort.getIndex = getSortedIndex;
 sort.initialize = initializeSorter;
 sort.is = isSorted;
 const SORT_PEEK_PERCENTAGE = 10;
@@ -1240,6 +1272,7 @@ function swapArrays(array, from, to, key) {
 * If either index is out of bounds, the array will be returned unchanged
 *
 * Available as `swapIndices` and `swap.indices`
+*
 * @param array Array of items to swap
 * @param first First index _(can be negative to count from the end)_
 * @param second Second index _(can be negative to count from the end)_
@@ -1299,12 +1332,132 @@ function toRecordArrays(array, first, second) {
 	return groupValues(array, first, second, true);
 }
 //#endregion
+//#region src/internal/result.ts
+function _isResult(value, okValue) {
+	if (isNonPlainObject(value)) return false;
+	return value.ok === okValue && (okValue ? PROPERTY_VALUE : PROPERTY_ERROR) in value;
+}
+function isError(value, extended) {
+	return _isResult(value, false) && (extended === true ? value.original instanceof Error : true);
+}
+/**
+* Is the result ok?
+* @param result Result to check
+* @returns `true` if the result is ok, `false` otherwise
+*/
+function isOk(value) {
+	return _isResult(value, true);
+}
+/**
+* Is the value a result?
+* @param value Value to check
+* @returns `true` if the value is a result, `false` otherwise
+*/
+function isResult(value) {
+	return _isResult(value, true) || _isResult(value, false);
+}
+const PROPERTY_ERROR = "error";
+const PROPERTY_VALUE = "value";
+//#endregion
+//#region src/result/misc.ts
+function error(value, original) {
+	return getError(value, original);
+}
+function getError(value, original) {
+	const errorResult = {
+		error: value,
+		ok: false
+	};
+	if (original instanceof Error) errorResult.original = original;
+	return errorResult;
+}
+/**
+* Creates an ok result
+* @param value Value
+* @returns Ok result
+*/
+function ok(value) {
+	return {
+		ok: true,
+		value
+	};
+}
+/**
+* Converts a result to a promise
+*
+* Resolves if ok, rejects for error
+* @param result Result to convert
+* @returns Promised result
+*/
+async function toPromise(result) {
+	const actual = typeof result === "function" ? result() : result;
+	if (!isResult(actual)) return Promise.reject(new Error(MESSAGE_PROMISE_RESULT));
+	return isOk(actual) ? Promise.resolve(actual.value) : Promise.reject(actual.error);
+}
+function unwrap(value, defaultValue) {
+	return isOk(value) ? value.value : defaultValue;
+}
+const MESSAGE_PROMISE_RESULT = "toPromise expected to receive a Result";
+//#endregion
+//#region src/internal/value/misc.ts
+function findKey(needle, haystack) {
+	const keys = Object.keys(haystack);
+	const index = keys.map((key) => key.toLowerCase()).indexOf(needle.toLowerCase());
+	return index > -1 ? keys[index] : needle;
+}
+function getNestedValue(data, path, ignoreCase) {
+	if (typeof data !== "object" || data === null) return error(NESTED_MESSAGE_INPUT);
+	if (typeof path !== "string" || path.trim().length === 0) return error(NESTED_MESSAGE_PATH);
+	const shouldIgnoreCase = ignoreCase === true;
+	const paths = getPaths(path, shouldIgnoreCase);
+	if (typeof paths === "string") return handleValue(data, paths, null, true, shouldIgnoreCase);
+	const { length } = paths;
+	let current = data;
+	for (let index = 0; index < length; index += 1) {
+		const part = paths[index];
+		const handled = handleValue(current, part, null, true, shouldIgnoreCase);
+		if (!handled.ok) return handled;
+		current = handled.value;
+	}
+	return ok(current);
+}
+function getPaths(path, lowercase) {
+	const normalized = lowercase ? path.toLowerCase() : path;
+	if (!EXPRESSION_NESTED.test(normalized)) return normalized;
+	return normalized.replace(EXPRESSION_BRACKET, ".$1").replace(EXPRESSION_DOTS, "").split(".");
+}
+function handleValue(data, path, value, get, ignoreCase) {
+	if (typeof data === "object" && data !== null) {
+		if (ignoreKey(path)) return error(NESTED_MESSAGE_UNSAFE);
+		const key = ignoreCase ? findKey(path, data) : path;
+		if (get) return key in data ? ok(data[key]) : error(NESTED_MESSAGE_MISSING);
+		data[key] = typeof value === "function" ? value(data[key]) : value;
+	}
+	if (get) return error(NESTED_MESSAGE_MISSING);
+}
+const EXPRESSION_BRACKET = /\[(\w+)\]/g;
+const EXPRESSION_DOTS = /^\.|\.$/g;
+const EXPRESSION_NESTED = /\.|\[\w+\]/;
+const NESTED_MESSAGE_INPUT = "Expected data to be an object";
+const NESTED_MESSAGE_MISSING = "Expected property to exist in object";
+const NESTED_MESSAGE_PATH = "Expected path to be a string";
+const NESTED_MESSAGE_UNSAFE = "Access to this property is not allowed";
+//#endregion
+//#region src/internal/value/has.ts
+function hasValue(data, path, ignoreCase) {
+	return getNestedValue(data, path, ignoreCase === true).ok;
+}
+hasValue.get = hasValueResult;
+function hasValueResult(data, path, ignoreCase) {
+	return getNestedValue(data, path, ignoreCase === true);
+}
+//#endregion
 //#region src/function/assert.ts
 /**
 * Asserts that a condition is true, throwing an error if it is not
 * @param condition Condition to assert
 * @param message Error message
-* @param error Error constructor
+* @param error Error constructor _(defaults to `Error`)_
 */
 function assert(condition, message, error) {
 	if (!condition()) throw new (error ?? Error)(message);
@@ -1313,13 +1466,14 @@ assert.condition = assertCondition;
 assert.defined = assertDefined;
 assert.instanceOf = assertInstanceOf;
 assert.is = assertIs;
+assert.property = assertProperty;
 /**
 * Creates an asserter that asserts a condition is true, throwing an error if it is not
 *
 * Available as `assertCondition` and `assert.condition`
 * @param condition Condition to assert
 * @param message Error message
-* @param error Error constructor
+* @param error Error constructor _(defaults to `Error`)_
 * @returns Asserter
 */
 function assertCondition(condition, message, error) {
@@ -1328,14 +1482,15 @@ function assertCondition(condition, message, error) {
 	};
 }
 /**
-* Asserts that a value is defined throwing an error if it is not
+* Asserts that a value is defined, throwing an error if it is not
 *
 * Available as `assertDefined` and `assert.defined`
 * @param value Value to assert
 * @param message Error message
+* @param error Error constructor _(defaults to `Error`)_
 */
-function assertDefined(value, message) {
-	assert(() => value != null, message ?? MESSAGE_VALUE_DEFINED);
+function assertDefined(value, message, error) {
+	assert(() => value != null, message ?? MESSAGE_VALUE_DEFINED, error);
 }
 /**
 * Creates an asserter that asserts a value is an instance of a constructor, throwing an error if it is not
@@ -1343,7 +1498,7 @@ function assertDefined(value, message) {
 * Available as `assertInstanceOf` and `assert.instanceOf`
 * @param constructor Constructor to check against
 * @param message Error message
-* @param error Error constructor
+* @param error Error constructor _(defaults to `Error`)_
 * @returns Asserter
 */
 function assertInstanceOf(constructor, message, error) {
@@ -1357,7 +1512,7 @@ function assertInstanceOf(constructor, message, error) {
 * Available as `assertIs` and `assert.is`
 * @param condition Type guard function to check the value
 * @param message Error message
-* @param error Error constructor
+* @param error Error constructor _(defaults to `Error`)_
 * @returns Asserter
 */
 function assertIs(condition, message, error) {
@@ -1365,6 +1520,24 @@ function assertIs(condition, message, error) {
 		assert(() => condition(value), message, error);
 	};
 }
+/**
+* Creates an asserter that asserts a property of a value exists and satisfies a condition, throwing an error if it does not
+*
+* Available as `assertProperty` and `assert.property`
+* @param path Path to the property to check, e.g., `foo.bar.baz` for a nested property
+* @param condition Condition to assert for the property
+* @param message Error message
+* @param error Error constructor _(defaults to `Error`)_
+* @returns Asserter
+*/
+function assertProperty(path, condition, message, error) {
+	return (value) => {
+		assert(() => {
+			const result = hasValueResult(value, path, false);
+			return result.ok && condition(result.value);
+		}, message, error);
+	};
+}
 const MESSAGE_VALUE_DEFINED = "Expected value to be defined";
 //#endregion
 //#region src/internal/function/misc.ts
@@ -1500,6 +1673,9 @@ var SizedMap = class extends Map {
 };
 //#endregion
 //#region src/function/memoize.ts
+/**
+* A memoized function, caching and retrieving results based on the its parameters _(or a custom cache key)_
+*/
 var Memoized = class {
 	#state;
 	/**
@@ -1833,7 +2009,11 @@ const ONCE_MESSAGE_CLEARED = "Once has been cleared";
 const ONCE_MESSAGE_EXPECTATION = "Once expected a function";
 //#endregion
 //#region src/function/retry.ts
+/**
+* An error thrown when a retry fails
+*/
 var RetryError = class extends Error {
+	original;
 	constructor(message, original) {
 		super(message);
 		this.original = original;
@@ -1912,33 +2092,6 @@ const RETRY_ERROR_NAME = "RetryError";
 const RETRY_MESSAGE_EXPECTATION = "Retry expected a function";
 const RETRY_MESSAGE_FAILED = "Retry failed";
 //#endregion
-//#region src/internal/result.ts
-function _isResult(value, okValue) {
-	if (isNonPlainObject(value)) return false;
-	return value.ok === okValue && (okValue ? PROPERTY_VALUE : PROPERTY_ERROR) in value;
-}
-function isError(value, extended) {
-	return _isResult(value, false) && (extended === true ? value.original instanceof Error : true);
-}
-/**
-* Is the result ok?
-* @param result Result to check
-* @returns `true` if the result is ok, `false` otherwise
-*/
-function isOk(value) {
-	return _isResult(value, true);
-}
-/**
-* Is the value a result?
-* @param value Value to check
-* @returns `true` if the value is a result, `false` otherwise
-*/
-function isResult(value) {
-	return _isResult(value, true) || _isResult(value, false);
-}
-const PROPERTY_ERROR = "error";
-const PROPERTY_VALUE = "value";
-//#endregion
 //#region src/function/work.ts
 function asyncFlow(...fns) {
 	assertFlowFunctions(fns);
@@ -2169,98 +2322,11 @@ const ERROR_PROPERTIES = ["name", "message"];
 const EXPRESSION_PROPERTIES = ["source", "flags"];
 const MINIMUM_LENGTH_FOR_SET = 16;
 //#endregion
-//#region src/result/misc.ts
-function error(value, original) {
-	return getError(value, original);
-}
-function getError(value, original) {
-	const errorResult = {
-		error: value,
-		ok: false
-	};
-	if (original instanceof Error) errorResult.original = original;
-	return errorResult;
-}
-/**
-* Creates an ok result
-* @param value Value
-* @returns Ok result
-*/
-function ok(value) {
-	return {
-		ok: true,
-		value
-	};
-}
-/**
-* Converts a result to a promise
-*
-* Resolves if ok, rejects for error
-* @param result Result to convert
-* @returns Promised result
-*/
-async function toPromise(result) {
-	const actual = typeof result === "function" ? result() : result;
-	if (!isResult(actual)) return Promise.reject(new Error(MESSAGE_PROMISE_RESULT));
-	return isOk(actual) ? Promise.resolve(actual.value) : Promise.reject(actual.error);
-}
-function unwrap(value, defaultValue) {
-	return isOk(value) ? value.value : defaultValue;
-}
-const MESSAGE_PROMISE_RESULT = "toPromise expected to receive a Result";
-//#endregion
-//#region src/internal/value/misc.ts
-function findKey(needle, haystack) {
-	const keys = Object.keys(haystack);
-	const index = keys.map((key) => key.toLowerCase()).indexOf(needle.toLowerCase());
-	return index > -1 ? keys[index] : needle;
-}
-function getNestedValue(data, path, ignoreCase) {
-	if (typeof data !== "object" || data === null || typeof path !== "string" || path.trim().length === 0) return error(void 0);
-	const shouldIgnoreCase = ignoreCase === true;
-	const paths = getPaths(path, shouldIgnoreCase);
-	if (typeof paths === "string") return handleValue(data, paths, null, true, shouldIgnoreCase);
-	const { length } = paths;
-	let current = data;
-	for (let index = 0; index < length; index += 1) {
-		const part = paths[index];
-		const handled = handleValue(current, part, null, true, shouldIgnoreCase);
-		if (!handled.ok) return handled;
-		current = handled.value;
-	}
-	return ok(current);
-}
-function getPaths(path, lowercase) {
-	const normalized = lowercase ? path.toLowerCase() : path;
-	if (!EXPRESSION_NESTED.test(normalized)) return normalized;
-	return normalized.replace(EXPRESSION_BRACKET, ".$1").replace(EXPRESSION_DOTS, "").split(".");
-}
-function handleValue(data, path, value, get, ignoreCase) {
-	if (typeof data === "object" && data !== null && !ignoreKey(path)) {
-		const key = ignoreCase ? findKey(path, data) : path;
-		if (get) return key in data ? ok(data[key]) : error(void 0);
-		data[key] = typeof value === "function" ? value(data[key]) : value;
-	}
-	if (get) return error(void 0);
-}
-const EXPRESSION_BRACKET = /\[(\w+)\]/g;
-const EXPRESSION_DOTS = /^\.|\.$/g;
-const EXPRESSION_NESTED = /\.|\[\w+\]/;
-//#endregion
 //#region src/internal/value/get.ts
 function getValue(data, path, ignoreCase) {
 	return getNestedValue(data, path, ignoreCase === true).value;
 }
 //#endregion
-//#region src/internal/value/has.ts
-function hasValue(data, path, ignoreCase) {
-	return getNestedValue(data, path, ignoreCase === true).ok;
-}
-hasValue.get = hasValueResult;
-function hasValueResult(data, path, ignoreCase) {
-	return getNestedValue(data, path, ignoreCase === true);
-}
-//#endregion
 //#region src/internal/value/set.ts
 function setValue(data, path, value, ignoreCase) {
 	if (typeof data !== "object" || data === null || typeof path !== "string" || path.trim().length === 0) return data;
@@ -3481,7 +3547,8 @@ function unsmush(value) {
 //#endregion
 //#region src/value/merge.ts
 /**
-* Assign values from multiple arrays or objects to the first one
+* Assign values from one or more objects to the first one
+*
 * @param to Value to assign to
 * @param from Values to assign
 * @param options Assigning options
@@ -3490,7 +3557,7 @@ function unsmush(value) {
 function assign(to, from, options) {
 	const actual = getMergeOptions(options);
 	actual.assignValues = true;
-	return mergeValues([to, ...from], actual, true);
+	return mergeValues([to, ...from], actual);
 }
 assign.initialize = initializeAssigner;
 function getMergeOptions(options) {
@@ -3511,59 +3578,70 @@ function getReplaceableObjects(value) {
 	const items = (Array.isArray(value) ? value : [value]).filter((item) => typeof item === "string" || item instanceof RegExp);
 	if (items.length > 0) return (name) => items.some((item) => typeof item === "string" ? item === name : item.test(name));
 }
-function handleMerge(values, options) {
-	return !Array.isArray(values) || values.length === 0 ? {} : mergeValues(values, options, true);
-}
 /**
 * Create an assigner with predefined options
 *
 * Available as `initializeAssigner` and `assign.initialize`
+*
 * @param options Assigning options
 * @returns Assigner function
 */
 function initializeAssigner(options) {
 	const actual = getMergeOptions(options);
 	actual.assignValues = true;
-	return ((to, from) => mergeValues([to, ...from], actual, true));
+	return ((to, from) => mergeValues([to, ...from], actual));
 }
 /**
 * Create a merger with predefined options
 *
 * Available as `initializeMerger` and `merge.initialize`
+*
 * @param options Merging options
 * @returns Merger function
 */
 function initializeMerger(options) {
 	const actual = getMergeOptions(options);
-	return (values) => handleMerge(values, actual);
+	return ((values) => mergeValues(values, actual));
 }
+/**
+* Merge multiple arrays or objects into a single one
+*
+* @param values Values to merge
+* @param options Merging options
+* @returns Merged value
+*/
 function merge(values, options) {
-	return handleMerge(values, getMergeOptions(options));
+	return mergeValues(values, getMergeOptions(options));
 }
 merge.initialize = initializeMerger;
-function mergeObjects(values, options, prefix) {
+function mergeObjects(values, options, destination, prefix) {
 	const { length } = values;
-	const isArray = values.every(Array.isArray);
-	const merged = options.assignValues ? values[0] : isArray ? [] : {};
-	for (let outerIndex = 0; outerIndex < length; outerIndex += 1) {
+	const isArray = Array.isArray(destination ?? values[0]);
+	const merged = destination ?? (isArray ? [] : {});
+	const offset = destination == null ? 0 : 1;
+	for (let outerIndex = offset; outerIndex < length; outerIndex += 1) {
 		const item = values[outerIndex];
 		const keys = Object.keys(item);
 		const size = keys.length;
 		for (let innerIndex = 0; innerIndex < size; innerIndex += 1) {
 			const key = keys[innerIndex];
-			const full = join([prefix, key], ".");
 			const next = item[key];
 			const previous = merged[key];
 			if (next == null && (options.skipNullableAny || isArray && options.skipNullableInArrays)) continue;
-			if (isArrayOrPlainObject(next) && isArrayOrPlainObject(previous) && !(options.replaceableObjects?.(full) ?? false)) merged[key] = mergeValues([previous, next], options, false, full);
+			const full = options.replaceableObjects == null ? void 0 : prefix == null ? key : `${prefix}.${key}`;
+			if (isArrayOrPlainObject(next) && isArrayOrPlainObject(previous) && !(options.replaceableObjects?.(full) ?? false)) merged[key] = mergeObjects([previous, next], options, destination == null ? void 0 : merged[key], full);
 			else merged[key] = next;
 		}
 	}
 	return merged;
 }
-function mergeValues(values, options, validate, prefix) {
-	const actual = validate ? values.filter(isArrayOrPlainObject) : values;
-	return actual.length > 1 ? mergeObjects(actual, options, prefix) : actual[0] ?? {};
+function mergeValues(values, options, prefix) {
+	if (!Array.isArray(values)) return {};
+	const actual = values.filter(isArrayOrPlainObject);
+	if (actual.length === 0) return {};
+	if (options.assignValues && actual.length === 2 && !Array.isArray(actual[0]) && Object.keys(actual[0]).length === 0) return Object.assign(actual[0], actual[1]);
+	if (actual.length > 1) return mergeObjects(actual, options, options.assignValues ? actual[0] : void 0, prefix);
+	return options.assignValues ? actual[0] : Array.isArray(actual[0]) ? actual[0].slice() : { ...actual[0] };
 }
 //#endregion
 //#region src/value/transform.ts
@@ -3603,6 +3681,9 @@ function transformValue(value, transformer) {
 }
 //#endregion
 //#region src/beacon.ts
+/**
+* A beacon is a lighthouse, holding an observable value that can be subscribed to and emitted from
+*/
 var Beacon = class {
 	#options;
 	#state;
@@ -3673,6 +3754,9 @@ var Beacon = class {
 		if (finish === true) finishBeacon(this.#state, true);
 	}
 };
+/**
+* An observable holds a value and allows observers to subscribe to changes in that value
+*/
 var Observable = class {
 	#state;
 	constructor(instance, observers) {
@@ -3697,6 +3781,9 @@ var Observable = class {
 		return instance;
 	}
 };
+/**
+* A subscription represents an active subscription to an observable, holding its state and allowing it to be destroyed or unsubscribed from
+*/
 var Subscription = class {
 	#state;
 	constructor(state) {
@@ -4317,6 +4404,9 @@ function setRGBColor(state, value, alpha) {
 }
 //#endregion
 //#region src/color/instance.ts
+/**
+* A color that is represented in multiple color formats
+*/
 var Color = class {
 	#state;
 	/**
@@ -4438,6 +4528,11 @@ function getColor(value) {
 }
 //#endregion
 //#region src/logger.ts
+/**
+* A logger that can be used to log messages to the console
+*
+* _(Logging can be enabled or disabled by setting the `enabled` property)_
+*/
 var Logger = class {
 	/**
 	* Log any number of values at the "debug" log level
@@ -4508,10 +4603,16 @@ var Logger = class {
 		return new Time(label);
 	}
 };
+/**
+* A named timer that can be used to log durations to the console
+*/
 var Time = class {
 	#logger;
 	#stopper;
 	#state;
+	/**
+	* Is the timer active? _(i.e. has it been started and not stopped, and is logging enabled?)_
+	*/
 	get active() {
 		return this.#state.started && !this.#state.stopped && enabled;
 	}
@@ -4624,6 +4725,9 @@ function sum(array, key) {
 }
 //#endregion
 //#region src/promise/models.ts
+/**
+* A promise that can be canceled
+*/
 var CancelablePromise = class extends Promise {
 	#rejector;
 	constructor(executor) {
@@ -4642,6 +4746,9 @@ var CancelablePromise = class extends Promise {
 		this.#rejector(reason);
 	}
 };
+/**
+* An error thrown when a promise times out
+*/
 var PromiseTimeoutError = class extends Error {
 	constructor() {
 		super(PROMISE_MESSAGE_TIMEOUT);
@@ -4941,6 +5048,9 @@ const TYPES = new Set([
 ]);
 //#endregion
 //#region src/queue.ts
+/**
+* A queue that can be used to manage (a)synchronous tasks with a specific key
+*/
 var KeyedQueue = class {
 	#callback;
 	#options;
@@ -5090,6 +5200,9 @@ var KeyedQueue = class {
 		for (const queue of queues) queue[type]();
 	}
 };
+/**
+* A queue that can be used to manage (a)synchronous tasks
+*/
 var Queue = class {
 	#callback;
 	#handled = [];
@@ -5267,6 +5380,9 @@ var Queue = class {
 		this.#runners -= 1;
 	}
 };
+/**
+* An error thrown by the Queue when an operation fails
+*/
 var QueueError = class extends Error {
 	constructor(message) {
 		super(message);
@@ -5374,6 +5490,25 @@ const BOOLEAN_MODIFIER = .5;
 const HEX_CHARACTERS = "0123456789ABCDEF";
 const HEX_MAXIMUM = 15;
 //#endregion
+//#region src/result/index.ts
+async function asyncAttempt(value, err) {
+	try {
+		let result = typeof value === "function" ? value() : await value;
+		if (result instanceof Promise) result = await result;
+		return ok(result);
+	} catch (thrown) {
+		return getError(err ?? thrown, err == null ? void 0 : thrown);
+	}
+}
+function attempt(callback, err) {
+	try {
+		return ok(callback());
+	} catch (thrown) {
+		return getError(err ?? thrown, err == null ? void 0 : thrown);
+	}
+}
+attempt.async = asyncAttempt;
+//#endregion
 //#region src/result/match.ts
 async function asyncMatchResult(result, first, error) {
 	let value;
@@ -5441,33 +5576,11 @@ function attemptPipe(initial, first, ...seconds) {
 }
 attemptPipe.async = attemptAsyncPipe;
 //#endregion
-//#region src/result/index.ts
-async function asyncAttempt(value, err) {
-	try {
-		let result = typeof value === "function" ? value() : await value;
-		if (result instanceof Promise) result = await result;
-		return ok(result);
-	} catch (thrown) {
-		return getError(err ?? thrown, err == null ? void 0 : thrown);
-	}
-}
-function attempt(callback, err) {
-	try {
-		return ok(callback());
-	} catch (thrown) {
-		return getError(err ?? thrown, err == null ? void 0 : thrown);
-	}
-}
-attempt.async = asyncAttempt;
-attempt.flow = attemptFlow;
-attempt.match = matchResult;
-attempt.pipe = attemptPipe;
-attempt.promise = attemptPromise;
-//#endregion
 //#region src/sized/set.ts
 /**
-* - A Set with a maximum size
-* - Behavior is similar to a _LRU_-cache, where the oldest values are removed
+* A Set with a maximum size
+*
+* Behavior is similar to a _LRU_-cache, where the oldest values are removed
 */
 var SizedSet = class extends Set {
 	/**
@@ -5518,4 +5631,4 @@ var SizedSet = class extends Set {
 	}
 };
 //#endregion
-export { CancelablePromise, PROMISE_ABORT_EVENT, PROMISE_ABORT_OPTIONS, PROMISE_ERROR_NAME, PROMISE_MESSAGE_EXPECTATION_ATTEMPT, PROMISE_MESSAGE_EXPECTATION_RESULT, PROMISE_MESSAGE_EXPECTATION_TIMED, PROMISE_MESSAGE_TIMEOUT, PROMISE_STRATEGY_ALL, PROMISE_STRATEGY_DEFAULT, PROMISE_TYPE_FULFILLED, PROMISE_TYPE_REJECTED, PromiseTimeoutError, RetryError, SORT_DIRECTION_ASCENDING, SORT_DIRECTION_DESCENDING, SizedMap, SizedSet, assert, assertCondition, assertDefined, assertInstanceOf, assertIs, assign, asyncAttempt, asyncDebounce, asyncFlow, asyncMatchResult, asyncOnce, asyncPipe, asyncThrottle, attempt, attemptAsyncFlow, attemptAsyncPipe, attemptFlow, attemptPipe, attemptPromise, average, beacon, between, camelCase, cancelable, capitalize, ceil, chunk, clamp, clone, compact, compare, count, debounce, deburr, dedent, delay, deregisterCloner, deregisterComparator, deregisterEqualizer, diff, difference, drop, endsWith, endsWithArray, equal, error, exclude, exists, filter, find, findLast, first, firstOrDefault, flatten, floor, flow, freeze, fromQuery, toPromise as fromResult, toPromise, fuzzy, fuzzyMatch, getArray, getArrayPosition, getColor, getError, getForegroundColor, getHexColor, getHexaColor, getHslColor, getHslaColor, getNormalizedHex, getNumber, getRandomBoolean, getRandomCharacters, getRandomColor, getRandomFloat, getRandomHex, getRandomInteger, getRandomItem, getRandomItems, getRgbColor, getRgbaColor, getSortedIndex, getString, getTimedPromise, getUuid, getValue, groupArraysBy, groupBy, handleResult, hasValue, hexToHsl, hexToHsla, hexToRgb, hexToRgba, hslToHex, hslToRgb, hslToRgba, ignoreKey, inMap, inSet, includes, includesArray, indexOf, indexOfArray, initializeAssigner, initializeEqualizer, initializeMerger, initializeNormalizer, initializeSorter, initializeTemplater, initializeTransformer, insert, intersection, isArrayOrPlainObject, isColor, isConstructor, isEmpty, isError, isFulfilled, isHexColor, isHslColor, isHslLike, isHslaColor, isInstanceOf, isKey, isNonArrayOrPlainObject, isNonConstructor, isNonEmpty, isNonInstanceOf, isNonKey, isNonNullable, isNonNullableOrEmpty, isNonNullableOrWhitespace, isNonNumber, isNonNumerical, isNonObject, isNonPlainObject, isNonPrimitive, isNonTypedArray, isNullable, isNullableOrEmpty, isNullableOrWhitespace, isNumber, isNumerical, isObject, isOk, isPlainObject, isPrimitive, isRejected, isResult, isRgbColor, isRgbLike, isRgbaColor, isSorted, isTypedArray, join, kalas, kebabCase, keyedQueue, last, lastIndexOf, lastOrDefault, logger, lowerCase, matchResult, max, median, memoize, merge, min, move, moveIndices, moveToIndex, noop, normalize, ok, omit, once, parse, partition, pascalCase, pick, pipe, promises, push, queue, range, registerCloner, registerComparator, registerEqualizer, resultPromises, retry, reverse, rgbToHex, rgbToHsl, rgbToHsla, round, select, setValue, settlePromise, shake, shuffle, single, slice, smush, snakeCase, sort, splice, startsWith, startsWithArray, sum, swap, take, template, throttle, timed, times, titleCase, toMap, toMapArrays, toQuery, toRecord, toRecordArrays, toResult, toSet, toggle, transform, trim, truncate, tryDecode, tryEncode, union, unique, unsmush, unwrap, update, upperCase, words };
+export { CancelablePromise, PROMISE_ABORT_EVENT, PROMISE_ABORT_OPTIONS, PROMISE_ERROR_NAME, PROMISE_MESSAGE_EXPECTATION_ATTEMPT, PROMISE_MESSAGE_EXPECTATION_RESULT, PROMISE_MESSAGE_EXPECTATION_TIMED, PROMISE_MESSAGE_TIMEOUT, PROMISE_STRATEGY_ALL, PROMISE_STRATEGY_DEFAULT, PROMISE_TYPE_FULFILLED, PROMISE_TYPE_REJECTED, PromiseTimeoutError, RetryError, SORT_DIRECTION_ASCENDING, SORT_DIRECTION_DESCENDING, SizedMap, SizedSet, assert, assertCondition, assertDefined, assertInstanceOf, assertIs, assertProperty, assign, asyncAttempt, asyncDebounce, asyncFlow, asyncMatchResult, asyncOnce, asyncPipe, asyncThrottle, attempt, attemptAsyncFlow, attemptAsyncPipe, attemptFlow, attemptPipe, attemptPromise, average, beacon, between, camelCase, cancelable, capitalize, ceil, chunk, clamp, clone, compact, compare, count, debounce, deburr, dedent, delay, deregisterCloner, deregisterComparator, deregisterEqualizer, diff, difference, drop, endsWith, endsWithArray, equal, error, exclude, exists, filter, find, findLast, first, firstOrDefault, flatten, floor, flow, freeze, fromQuery, toPromise as fromResult, toPromise, fuzzy, fuzzyMatch, getArray, getArrayComparison, getColor, getError, getForegroundColor, getHexColor, getHexaColor, getHslColor, getHslaColor, getNormalizedHex, getNumber, getRandomBoolean, getRandomCharacters, getRandomColor, getRandomFloat, getRandomHex, getRandomInteger, getRandomItem, getRandomItems, getRgbColor, getRgbaColor, getSortedIndex, getString, getTimedPromise, getUuid, getValue, groupArraysBy, groupBy, handleResult, hasValue, hasValueResult, hexToHsl, hexToHsla, hexToRgb, hexToRgba, hslToHex, hslToRgb, hslToRgba, ignoreKey, inMap, inSet, includes, includesArray, indexOf, indexOfArray, initializeAssigner, initializeEqualizer, initializeMerger, initializeNormalizer, initializeSorter, initializeTemplater, initializeTransformer, insert, intersection, isArrayOrPlainObject, isColor, isConstructor, isEmpty, isError, isFulfilled, isHexColor, isHslColor, isHslLike, isHslaColor, isInstanceOf, isKey, isNonArrayOrPlainObject, isNonConstructor, isNonEmpty, isNonInstanceOf, isNonKey, isNonNullable, isNonNullableOrEmpty, isNonNullableOrWhitespace, isNonNumber, isNonNumerical, isNonObject, isNonPlainObject, isNonPrimitive, isNonTypedArray, isNullable, isNullableOrEmpty, isNullableOrWhitespace, isNumber, isNumerical, isObject, isOk, isPlainObject, isPrimitive, isRejected, isResult, isRgbColor, isRgbLike, isRgbaColor, isSorted, isTypedArray, join, kalas, kebabCase, keyedQueue, last, lastIndexOf, lastOrDefault, logger, lowerCase, matchResult, max, median, memoize, merge, min, move, moveIndices, moveToIndex, noop, normalize, ok, omit, once, parse, partition, pascalCase, pick, pipe, promises, push, queue, range, registerCloner, registerComparator, registerEqualizer, resultPromises, retry, reverse, rgbToHex, rgbToHsl, rgbToHsla, round, select, setValue, settlePromise, shake, shuffle, single, slice, smush, snakeCase, sort, splice, startsWith, startsWithArray, sum, swap, take, template, throttle, timed, times, titleCase, toMap, toMapArrays, toQuery, toRecord, toRecordArrays, toResult, toSet, toggle, transform, trim, truncate, tryDecode, tryEncode, union, unique, unsmush, unwrap, update, upperCase, words };