@oscarpalmer/atoms 0.185.0 → 0.186.0

package/src/internal/array/index-of.ts

@@ -5,10 +5,20 @@ import type {PlainObject} from '../../models';
 
 /**
  * Get the index of the first matching item by callback
+ *
  * @param array Array to search in
  * @param callback Callback to get an item's value
  * @param value Value to match against
  * @returns Index of the first matching item, or `-1` if no match is found
+ *
+ * @example
+ * ```typescript
+ * indexOf(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   item => item.id,
+ *   2,
+ * ); // => 1
+ * ```
  */
 export function indexOf<
 	Item,
@@ -17,10 +27,20 @@ export function indexOf<
 
 /**
  * Get the index of the first matching item by key
+ *
  * @param array Array to search in
  * @param key Key to match items by
  * @param value Value to match against
  * @returns Index of the first matching item, or `-1` if no match is found
+ *
+ * @example
+ * ```typescript
+ * indexOf(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   'id',
+ *   2,
+ * ); // => 1
+ * ```
  */
 export function indexOf<Item extends PlainObject, ItemKey extends keyof Item>(
 	array: Item[],
@@ -30,9 +50,18 @@ export function indexOf<Item extends PlainObject, ItemKey extends keyof Item>(
 
 /**
  * Get the index of the first item matching the filter
+ *
  * @param array Array to search in
  * @param filter Filter callback to match items
  * @returns Index of the first matching item, or `-1` if no match is found
+ *
+ * @example
+ * ```typescript
+ * indexOf(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   item => item.id === 2,
+ * ); // => 1
+ * ```
  */
 export function indexOf<Item>(
 	array: Item[],
@@ -41,9 +70,15 @@ export function indexOf<Item>(
 
 /**
  * Get the index of the first item matching the given item
+ *
  * @param array Array to search in
  * @param item Item to match against
  * @returns Index of the first matching item, or `-1` if no match is found
+ *
+ * @example
+ * ```typescript
+ * indexOf([1, 2, 3, 4, 5], 3); // => 2
+ * ```
  */
 export function indexOf<Item>(array: Item[], item: Item): number;
 
@@ -57,10 +92,20 @@ indexOf.last = lastIndexOf;
  * Get the index of the last matching item by callback
  *
  * Available as `lastIndexOf` and `indexOf.last`
+ *
  * @param array Array to search in
  * @param callback Callback to get an item's value
  * @param value Value to match against
  * @returns Index of the last matching item, or `-1` if no match is found
+ *
+ * @example
+ * ```typescript
+ * lastIndexOf(
+ *   [{id: 1}, {id: 2}, {id: 3}, {id: 2}],
+ *   item => item.id,
+ *   2,
+ * ); // => 3
+ * ```
  */
 export function lastIndexOf<
 	Item,
@@ -71,10 +116,20 @@ export function lastIndexOf<
  * Get the index of the last matching item by key
  *
  * Available as `lastIndexOf` and `indexOf.last`
+ *
  * @param array Array to search in
  * @param key Key to match items by
  * @param value Value to match against
  * @returns Index of the last matching item, or `-1` if no match is found
+ *
+ * @example
+ * ```typescript
+ * lastIndexOf(
+ *   [{id: 1}, {id: 2}, {id: 3}, {id: 2}],
+ *   'id',
+ *   2,
+ * ); // => 3
+ * ```
  */
 export function lastIndexOf<Item extends PlainObject, ItemKey extends keyof Item>(
 	array: Item[],
@@ -86,9 +141,18 @@ export function lastIndexOf<Item extends PlainObject, ItemKey extends keyof Item
  * Get the index of the last item matching the filter
  *
  * Available as `lastIndexOf` and `indexOf.last`
+ *
  * @param array Array to search in
  * @param filter Filter callback to match items
  * @returns Index of the last matching item, or `-1` if no match is found
+ *
+ * @example
+ * ```typescript
+ * lastIndexOf(
+ *   [{id: 1}, {id: 2}, {id: 3}, {id: 2}],
+ *   item => item.id === 2,
+ * ); // => 3
+ * ```
  */
 export function lastIndexOf<Item>(
 	array: Item[],
@@ -99,9 +163,15 @@ export function lastIndexOf<Item>(
  * Get the index of the last item matching the given item
  *
  * Available as `lastIndexOf` and `indexOf.last`
+ *
  * @param array Array to search in
  * @param item Item to match against
  * @returns Index of the last matching item, or `-1` if no match is found
+ *
+ * @example
+ * ```typescript
+ * lastIndexOf([1, 2, 3, 2, 1], 2); // => 3
+ * ```
  */
 export function lastIndexOf<Item>(array: Item[], item: Item): number;
 

package/src/internal/math/aggregate.ts

@@ -66,6 +66,17 @@ export function getAggregateCallback(key: unknown): Function | undefined {
 
 /**
  * Get the maximum value from a list of items
+ *
+ * @example
+ * ```typescript
+ * max(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}],
+ *   item => item.value,
+ * ); // 20
+ *
+ * max([], item => item.value); // Number.NaN
+ * ```
+ *
  * @param items List of items
  * @param callback Callback to get an item's value
  * @returns Maximum value, or `NaN` if no maximum can be found
@@ -77,6 +88,17 @@ export function max<Item>(
 
 /**
  * Get the maximum value from a list of items
+ *
+ * @example
+ * ```typescript
+ * max(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}],
+ *   'value',
+ * ); // 20
+ *
+ * max([], 'value'); // Number.NaN
+ * ```
+ *
  * @param items List of items
  * @param key Key to use for value
  * @returns Maximum value, or `NaN` if no maximum can be found
@@ -88,6 +110,13 @@ export function max<Item extends PlainObject, ItemKey extends keyof NumericalVal
 
 /**
  * Get the maximum value from a list of numbers
+ *
+ * @example
+ * ```typescript
+ * max([10, 20]); // 20
+ * max([]);       // Number.NaN
+ * ```
+ *
  * @param values List of numbers
  * @returns Maximum value, or `NaN` if no maximum can be found
  */

package/src/internal/string.ts

@@ -19,11 +19,9 @@ export function getString(value: unknown): string {
 	}
 
 	if (typeof value !== 'object') {
-		// oxlint-disable-next-line typescript/no-base-to-string: the whole point of this function is to get a string representation of any value, so calling `String` on it is fine
 		return String(value);
 	}
 
-	// oxlint-disable-next-line typescript/no-base-to-string: ditto
 	const asString = String(value.valueOf?.() ?? value);
 
 	return asString.startsWith('[object ') ? JSON.stringify(value) : asString;

package/src/internal/value/get.ts

@@ -6,8 +6,19 @@ import {getNestedValue} from './misc';
 
 /**
  * Get the value from an object using a known path
+ *
+ * @example
+ * ```typescript
+ * const data = {foo: {bar: {baz: 42}}};
+ *
+ * getValue(data, 'foo');         // {bar: {baz: 42}}
+ * getValue(data, 'foo.bar');     // {baz: 42}
+ * getValue(data, 'foo.bar.baz'); // 42
+ * getValue(data, 'foo.nope');    // undefined
+ * ```
+ *
  * @param data Object to get value from
- * @param path Path for value, e.g., `foo.bar.baz`
+ * @param path Path for value
  * @returns Found value, or `undefined`
  */
 export function getValue<Data extends PlainObject, Path extends NestedKeys<Data>>(
@@ -17,9 +28,20 @@ export function getValue<Data extends PlainObject, Path extends NestedKeys<Data>
 
 /**
  * Get the value from an object using an unknown path
+ *
+ * @example
+ * ```typescript
+ * const data = {foo: {bar: {baz: 42}}};
+ *
+ * getValue(data, 'foo');               // {bar: {baz: 42}}
+ * getValue(data, 'foo.bar');           // {baz: 42}
+ * getValue(data, 'Foo.Bar.Baz', true); // 42
+ * getValue(data, 'foo.nope');          // undefined
+ * ```
+ *
  * @param data Object to get value from
- * @param path Path for value, e.g., `foo.bar.baz`
- * @param ignoreCase If `true`, the path matching is case-insensitive
+ * @param path Path for value
+ * @param ignoreCase If `true`, path matching is case-insensitive
  * @returns Found value, or `undefined`
  */
 export function getValue<Data extends PlainObject>(

package/src/internal/value/has.ts

@@ -8,7 +8,7 @@ import {getNestedValue} from './misc';
  * Check if a nested property is defined in an object
  * @param data Object to check in
  * @param path Path for property
- * @return `true` if the property exists, `false` otherwise
+ * @returns `true` if the property exists, `false` otherwise
  */
 export function hasValue<Data extends PlainObject, Path extends NestedKeys<Data>>(
 	data: Data,
@@ -20,7 +20,7 @@ export function hasValue<Data extends PlainObject, Path extends NestedKeys<Data>
  * @param data Object to check in
  * @param path Path for property
  * @param ignoreCase If `true`, the path matching is case-insensitive
- * @return `true` if the property exists, `false` otherwise
+ * @returns `true` if the property exists, `false` otherwise
  */
 export function hasValue<Data extends PlainObject>(
 	data: Data,
@@ -41,7 +41,7 @@ hasValue.get = hasValueResult;
  * @param data Object to check in
  * @param path Path for property
  * @param ignoreCase If `true`, the path matching is case-insensitive
- * @return Result object
+ * @returns Result object
  */
 export function hasValueResult<Data extends PlainObject, Path extends NestedKeys<Data>>(
 	data: Data,
@@ -56,7 +56,7 @@ export function hasValueResult<Data extends PlainObject, Path extends NestedKeys
  * @param data Object to check in
  * @param path Path for property
  * @param ignoreCase If `true`, the path matching is case-insensitive
- * @return Result object
+ * @returns Result object
  */
 export function hasValueResult<Data extends PlainObject>(
 	data: Data,

package/src/models.ts

@@ -260,4 +260,22 @@ export type TypedArray =
 	| BigInt64Array
 	| BigUint64Array;
 
+/**
+ * Converts a union type to an intersection type
+ *
+ * @example
+ * ```typescript
+ * type A = {a: string};
+ * type B = {b: number};
+ * type C = UnionToIntersection<A | B>; // {a: string} & {b: number}
+ * ```
+ *
+ * Thanks, type-fest!
+ */
+export type UnionToIntersection<Union> = (
+	Union extends unknown ? (distributedUnion: Union) => void : never
+) extends (mergedIntersection: infer Intersection) => void
+	? Intersection & Union
+	: never;
+
 // #endregion

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/transform.ts

@@ -75,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
 
@@ -16,15 +16,6 @@ type OrderedKey = {
 	value: string;
 };
 
-/**
- * Thanks, type-fest!
- */
-type UnionToIntersection<Union> = (
-	Union extends unknown ? (distributedUnion: Union) => void : never
-) extends (mergedIntersection: infer Intersection) => void
-	? Intersection & Union
-	: never;
-
 /**
  * An unsmushed object, with all dot notation keys turned into nested keys
  */