@oscarpalmer/atoms 0.184.2 → 0.186.0

package/src/result/work/pipe.ts

@@ -17,7 +17,7 @@ type WrapValue<Value> = Result<UnwrapValue<Value>>;
 /**
  * Attempt to pipe a value through a function
  *
- * Available as `attemptAsyncPipe` and `attempt.pipe.async`
+ * Available as `attemptAsyncPipe` and `attemptPipe.async`
  * @param initial Initial value
  * @returns Piped result
  */
@@ -29,7 +29,7 @@ export async function attemptAsyncPipe<Initial, Piped>(
 /**
  * Attempt to pipe a value through a series of functions
  *
- * Available as `attemptAsyncPipe` and `attempt.pipe.async`
+ * Available as `attemptAsyncPipe` and `attemptPipe.async`
  * @param initial Initial value
  * @returns Piped result
  */
@@ -42,7 +42,7 @@ export async function attemptAsyncPipe<Initial, First, Second>(
 /**
  * Attempt to pipe a value through a series of functions
  *
- * Available as `attemptAsyncPipe` and `attempt.pipe.async`
+ * Available as `attemptAsyncPipe` and `attemptPipe.async`
  * @param initial Initial value
  * @returns Piped result
  */
@@ -56,7 +56,7 @@ export async function attemptAsyncPipe<Initial, First, Second, Third>(
 /**
  * Attempt to pipe a value through a series of functions
  *
- * Available as `attemptAsyncPipe` and `attempt.pipe.async`
+ * Available as `attemptAsyncPipe` and `attemptPipe.async`
  * @param initial Initial value
  * @returns Piped result
  */
@@ -71,7 +71,7 @@ export async function attemptAsyncPipe<Initial, First, Second, Third, Fourth>(
 /**
  * Attempt to pipe a value through a series of functions
  *
- * Available as `attemptAsyncPipe` and `attempt.pipe.async`
+ * Available as `attemptAsyncPipe` and `attemptPipe.async`
  * @param initial Initial value
  * @returns Piped result
  */
@@ -87,7 +87,7 @@ export async function attemptAsyncPipe<Initial, First, Second, Third, Fourth, Fi
 /**
  * Attempt to pipe a value through a series of functions
  *
- * Available as `attemptAsyncPipe` and `attempt.pipe.async`
+ * Available as `attemptAsyncPipe` and `attemptPipe.async`
  * @param initial Initial value
  * @returns Piped result
  */
@@ -104,7 +104,7 @@ export async function attemptAsyncPipe<Initial, First, Second, Third, Fourth, Fi
 /**
  * Attempt to pipe a value through a series of functions
  *
- * Available as `attemptAsyncPipe` and `attempt.pipe.async`
+ * Available as `attemptAsyncPipe` and `attemptPipe.async`
  * @param initial Initial value
  * @returns Piped result
  */
@@ -131,7 +131,7 @@ export async function attemptAsyncPipe<
 /**
  * Attempt to pipe a value through a series of functions
  *
- * Available as `attemptAsyncPipe` and `attempt.pipe.async`
+ * Available as `attemptAsyncPipe` and `attemptPipe.async`
  * @param initial Initial value
  * @returns Piped result
  */
@@ -160,7 +160,7 @@ export async function attemptAsyncPipe<
 /**
  * Attempt to pipe a value through a series of functions
  *
- * Available as `attemptAsyncPipe` and `attempt.pipe.async`
+ * Available as `attemptAsyncPipe` and `attemptPipe.async`
  * @param initial Initial value
  * @returns Piped result
  */
@@ -191,7 +191,7 @@ export async function attemptAsyncPipe<
 /**
  * Attempt to pipe a value through a series of functions
  *
- * Available as `attemptAsyncPipe` and `attempt.pipe.async`
+ * Available as `attemptAsyncPipe` and `attemptPipe.async`
  * @param initial Initial value
  * @returns Piped result
  */
@@ -224,7 +224,7 @@ export async function attemptAsyncPipe<
 /**
  * Attempt to pipe a result through a series of functions
  *
- * Available as `attemptAsyncPipe` and `attempt.pipe.async`
+ * Available as `attemptAsyncPipe` and `attemptPipe.async`
  * @param initial Initial result
  * @returns Piped result
  */
@@ -265,8 +265,6 @@ export async function attemptAsyncPipe(
 
 /**
  * Attempt to pipe a value through a function
- *
- * Available as `attemptPipe` and `attempt.pipe`
  * @param initial Initial value
  * @returns Piped result
  */
@@ -277,8 +275,6 @@ export function attemptPipe<Initial, Pipe>(
 
 /**
  * Attempt to pipe a value through a series of functions
- *
- * Available as `attemptPipe` and `attempt.pipe`
  * @param initial Initial value
  * @returns Piped result
  */
@@ -290,8 +286,6 @@ export function attemptPipe<Initial, First, Second>(
 
 /**
  * Attempt to pipe a value through a series of functions
- *
- * Available as `attemptPipe` and `attempt.pipe`
  * @param initial Initial value
  * @returns Piped result
  */
@@ -304,8 +298,6 @@ export function attemptPipe<Initial, First, Second, Third>(
 
 /**
  * Attempt to pipe a value through a series of functions
- *
- * Available as `attemptPipe` and `attempt.pipe`
  * @param initial Initial value
  * @returns Piped result
  */
@@ -319,8 +311,6 @@ export function attemptPipe<Initial, First, Second, Third, Fourth>(
 
 /**
  * Attempt to pipe a value through a series of functions
- *
- * Available as `attemptPipe` and `attempt.pipe`
  * @param initial Initial value
  * @returns Piped result
  */
@@ -335,8 +325,6 @@ export function attemptPipe<Initial, First, Second, Third, Fourth, Fifth>(
 
 /**
  * Attempt to pipe a value through a series of functions
- *
- * Available as `attemptPipe` and `attempt.pipe`
  * @param initial Initial value
  * @returns Piped result
  */
@@ -352,8 +340,6 @@ export function attemptPipe<Initial, First, Second, Third, Fourth, Fifth, Sixth>
 
 /**
  * Attempt to pipe a value through a series of functions
- *
- * Available as `attemptPipe` and `attempt.pipe`
  * @param initial Initial value
  * @returns Piped result
  */
@@ -370,8 +356,6 @@ export function attemptPipe<Initial, First, Second, Third, Fourth, Fifth, Sixth,
 
 /**
  * Attempt to pipe a value through a series of functions
- *
- * Available as `attemptPipe` and `attempt.pipe`
  * @param initial Initial value
  * @returns Piped result
  */
@@ -389,8 +373,6 @@ export function attemptPipe<Initial, First, Second, Third, Fourth, Fifth, Sixth,
 
 /**
  * Attempt to pipe a value through a series of functions
- *
- * Available as `attemptPipe` and `attempt.pipe`
  * @param initial Initial value
  * @returns Piped result
  */
@@ -420,8 +402,6 @@ export function attemptPipe<
 
 /**
  * Attempt to pipe a value through a series of functions
- *
- * Available as `attemptPipe` and `attempt.pipe`
  * @param initial Initial value
  * @returns Piped result
  */
@@ -453,8 +433,6 @@ export function attemptPipe<
 
 /**
  * Attempt to pipe a result through a series of functions
- *
- * Available as `attemptPipe` and `attempt.pipe`
  * @param initial Initial result
  * @returns Piped result
  */

package/src/sized/set.ts

@@ -1,10 +1,11 @@
 import {getSizedMaximum} from '../internal/sized';
 
-// #region Types and classes
+// #region Types
 
 /**
- * - 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
  */
 export class SizedSet<Value = unknown> extends Set<Value> {
 	/**

package/src/value/collection.ts

@@ -13,7 +13,7 @@ export function inMap<Value>(map: Map<unknown, Value>, value: Value): boolean;
  * @param map Map to check in
  * @param value Value to check for
  * @param key To return the key for the value
- * @return The key for the value if it exists, otherwise `undefined`
+ * @returns The key for the value if it exists, otherwise `undefined`
  */
 export function inMap<Key, Value>(map: Map<Key, Value>, value: Value, key: true): Key;
 

package/src/value/merge.ts

@@ -1,6 +1,5 @@
 import {isArrayOrPlainObject} from '../internal/is';
-import {join} from '../internal/string';
-import type {ArrayOrPlainObject, NestedPartial, PlainObject} from '../models';
+import type {ArrayOrPlainObject, NestedPartial, PlainObject, UnionToIntersection} from '../models';
 
 // #region Types
 
@@ -9,16 +8,19 @@ import type {ArrayOrPlainObject, NestedPartial, PlainObject} from '../models';
  */
 export type AssignOptions = Omit<MergeOptions, 'assignValues'>;
 
-/**
- * Assign values from multiple arrays or objects to the first one
- * @param to Value to assign to
- * @param from Values to assign
- * @returns Assigned value
- */
-export type Assigner<Model extends ArrayOrPlainObject = ArrayOrPlainObject> = (
-	to: NestedPartial<Model>,
-	from: NestedPartial<Model>[],
-) => Model;
+export type Assigner = {
+	/**
+	 * Assign values from one or more objects to the first one
+	 *
+	 * @param to Value to assign to
+	 * @param from Values to assign
+	 * @returns Assigned value
+	 */
+	<To extends PlainObject, From extends PlainObject[]>(
+		to: To,
+		from: [...From],
+	): To & UnionToIntersection<From[number]>;
+};
 
 /**
  * Options for merging values
@@ -54,14 +56,17 @@ export type MergeOptions = {
 	skipNullableInArrays?: boolean;
 };
 
-/**
- * Merge multiple arrays or objects into a single one
- * @param values Values to merge
- * @returns Merged value
- */
-export type Merger<Model extends ArrayOrPlainObject = ArrayOrPlainObject> = (
-	values: NestedPartial<Model>[],
-) => Model;
+export type Merger = {
+	/**
+	 * Merge multiple arrays or objects into a single one
+	 *
+	 * @param values Values to merge
+	 * @returns Merged value
+	 */
+	<Values extends ArrayOrPlainObject[]>(
+		values: NestedPartial<Values[number]>[],
+	): UnionToIntersection<Values[number]>;
+};
 
 type Options = {
 	assignValues: boolean;
@@ -77,22 +82,23 @@ type ReplaceableObjectsCallback = (name: string) => boolean;
 // #region Functions
 
 /**
- * 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
  * @returns Assigned value
  */
-export function assign<Model extends ArrayOrPlainObject>(
-	to: NestedPartial<Model>,
-	from: NestedPartial<Model>[],
+export function assign<To extends PlainObject, From extends PlainObject[]>(
+	to: To,
+	from: [...From],
 	options?: AssignOptions,
-): Model {
+): To & UnionToIntersection<From[number]> {
 	const actual = getMergeOptions(options);
 
 	actual.assignValues = true;
 
-	return mergeValues([to, ...from], actual, true) as Model;
+	return mergeValues([to, ...from], actual) as To & UnionToIntersection<From[number]>;
 }
 
 assign.initialize = initializeAssigner;
@@ -129,69 +135,50 @@ function getReplaceableObjects(value: unknown): ReplaceableObjectsCallback | und
 	}
 }
 
-function handleMerge(values: ArrayOrPlainObject[], options: Options): ArrayOrPlainObject {
-	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
  */
-export function initializeAssigner<Model extends ArrayOrPlainObject>(
-	options?: AssignOptions,
-): Assigner<Model> {
+export function initializeAssigner(options?: AssignOptions): Assigner {
 	const actual = getMergeOptions(options);
 
 	actual.assignValues = true;
 
-	return ((to: ArrayOrPlainObject, from: NestedPartial<ArrayOrPlainObject>[]): ArrayOrPlainObject =>
-		mergeValues([to, ...from], actual, true)) as Assigner<Model>;
+	return ((to: PlainObject, from: PlainObject[]): PlainObject =>
+		mergeValues([to, ...from], actual) as PlainObject) as Assigner;
 }
 
 /**
  * Create a merger with predefined options
  *
  * Available as `initializeMerger` and `merge.initialize`
+ *
  * @param options Merging options
  * @returns Merger function
  */
 export function initializeMerger(options?: MergeOptions): Merger {
 	const actual = getMergeOptions(options);
 
-	return <Model extends ArrayOrPlainObject>(values: NestedPartial<Model>[]): Model =>
-		handleMerge(values, actual) as Model;
+	return ((values: NestedPartial<ArrayOrPlainObject>[]): ArrayOrPlainObject =>
+		mergeValues(values, actual)) as Merger;
 }
 
 /**
  * Merge multiple arrays or objects into a single one
+ *
  * @param values Values to merge
  * @param options Merging options
  * @returns Merged value
  */
-export function merge<Model extends ArrayOrPlainObject>(
-	values: NestedPartial<Model>[],
-	options?: MergeOptions,
-): Model;
-
-/**
- * Merge multiple arrays or objects into a single one
- * @param values Values to merge
- * @param options Merging options
- * @returns Merged value
- */
-export function merge(
-	values: NestedPartial<ArrayOrPlainObject>[],
+export function merge<Values extends ArrayOrPlainObject[]>(
+	values: [...Values],
 	options?: MergeOptions,
-): ArrayOrPlainObject;
-
-export function merge(
-	values: NestedPartial<ArrayOrPlainObject>[],
-	options?: MergeOptions,
-): ArrayOrPlainObject {
-	return handleMerge(values, getMergeOptions(options));
+): UnionToIntersection<Values[number]> {
+	return mergeValues(values, getMergeOptions(options)) as UnionToIntersection<Values[number]>;
 }
 
 merge.initialize = initializeMerger;
@@ -199,20 +186,23 @@ merge.initialize = initializeMerger;
 function mergeObjects(
 	values: ArrayOrPlainObject[],
 	options: Options,
+	destination?: ArrayOrPlainObject,
 	prefix?: string,
 ): ArrayOrPlainObject {
 	const {length} = values;
-	const isArray = values.every(Array.isArray);
-	const merged = (options.assignValues ? values[0] : isArray ? [] : {}) as PlainObject;
 
-	for (let outerIndex = 0; outerIndex < length; outerIndex += 1) {
+	const isArray = Array.isArray(destination ?? values[0]);
+	const merged = (destination ?? (isArray ? [] : {})) as PlainObject;
+
+	const offset = destination == null ? 0 : 1;
+
+	for (let outerIndex = offset; outerIndex < length; outerIndex += 1) {
 		const item = values[outerIndex] as PlainObject;
 		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];
@@ -221,12 +211,20 @@ function mergeObjects(
 				continue;
 			}
 
+			const full =
+				options.replaceableObjects == null ? undefined : prefix == null ? key : `${prefix}.${key}`;
+
 			if (
 				isArrayOrPlainObject(next) &&
 				isArrayOrPlainObject(previous) &&
-				!(options.replaceableObjects?.(full) ?? false)
+				!(options.replaceableObjects?.(full!) ?? false)
 			) {
-				merged[key] = mergeValues([previous, next], options, false, full);
+				merged[key] = mergeObjects(
+					[previous, next],
+					options,
+					(destination == null ? undefined : merged[key]) as ArrayOrPlainObject,
+					full,
+				);
 			} else {
 				merged[key] = next;
 			}
@@ -239,12 +237,36 @@ function mergeObjects(
 function mergeValues(
 	values: ArrayOrPlainObject[],
 	options: Options,
-	validate: boolean,
 	prefix?: string,
 ): ArrayOrPlainObject {
-	const actual = validate ? values.filter(isArrayOrPlainObject) : values;
+	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] : undefined, prefix);
+	}
 
-	return actual.length > 1 ? mergeObjects(actual, options, prefix) : (actual[0] ?? {});
+	return options.assignValues
+		? actual[0]
+		: Array.isArray(actual[0])
+			? actual[0].slice()
+			: {...actual[0]};
 }
 
 // #endregion

package/src/value/shake.ts

@@ -3,6 +3,9 @@ import type {PlainObject} from '../models';
 
 // #region Types
 
+/**
+ * A shaken object, without any `undefined` values
+ */
 export type Shaken<Value extends PlainObject> = {
 	[Key in keyof Value]: Value[Key] extends undefined ? never : Value[Key];
 };

package/src/value/smush.ts

@@ -11,6 +11,9 @@ import type {
 
 // #region Types
 
+/**
+ * A smushed object, with all nested objects flattened into a single level, using dot notation keys
+ */
 export type Smushed<Value extends PlainObject> = Simplify<{
 	[NestedKey in NestedKeys<Value>]: NestedValue<Value, ToString<NestedKey>>;
 }>;

package/src/value/transform.ts

@@ -3,15 +3,24 @@ import type {GenericCallback, PlainObject} from '../models';
 
 // #region Types
 
+/**
+ * A callback transform an object's properties
+ */
 type TransformCallback<Value extends PlainObject, Key extends keyof Value> = (
 	key: Key,
 	value: Value[Key],
 ) => Value[Key];
 
+/**
+ * A collection of keyed callbacks to transform an object's properties
+ */
 type TransformCallbacks<Value extends PlainObject> = Partial<{
 	[Key in keyof Value]: (value: Value[Key]) => Value[Key];
 }>;
 
+/**
+ * A transformer function for an object, with predefined callbacks for transforming its properties
+ */
 export type Transformer<Value extends PlainObject> = {
 	(value: Value): Value;
 };
@@ -66,7 +75,7 @@ export function initializeTransformer<Value extends PlainObject>(
  *
  * Available as `initializeTransformer` and `transform.initialize`
  * @param transformers Keyed transformer functions
- * @return Transformer
+ * @returns Transformer
  */
 export function initializeTransformer<Value extends PlainObject>(
 	transformers: TransformCallbacks<Value>,

package/src/value/unsmush.ts

@@ -1,6 +1,6 @@
 import {isArrayOrPlainObject} from '../internal/is';
 import {setValue} from '../internal/value/set';
-import type {PlainObject, Simplify} from '../models';
+import type {PlainObject, Simplify, UnionToIntersection} from '../models';
 
 // #region Types
 
@@ -17,14 +17,8 @@ type OrderedKey = {
 };
 
 /**
- * Thanks, type-fest!
+ * An unsmushed object, with all dot notation keys turned into nested keys
  */
-type UnionToIntersection<Union> = (
-	Union extends unknown ? (distributedUnion: Union) => void : never
-) extends (mergedIntersection: infer Intersection) => void
-	? Intersection & Union
-	: never;
-
 export type Unsmushed<Value extends PlainObject> = Simplify<
 	Omit<
 		{