@oscarpalmer/atoms 0.185.0 → 0.186.0

package/dist/value/merge.mjs

@@ -1,8 +1,8 @@
 import { isArrayOrPlainObject } from "../internal/is.mjs";
-import { join } from "../internal/string.mjs";
 //#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
@@ -11,7 +11,7 @@ import { join } from "../internal/string.mjs";
 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) {
@@ -32,59 +32,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
 export { assign, initializeAssigner, initializeMerger, merge };

package/dist/value/transform.d.mts

@@ -28,7 +28,7 @@ declare function initializeTransformer<Value extends PlainObject>(transform: Tra
  *
  * Available as `initializeTransformer` and `transform.initialize`
  * @param transformers Keyed transformer functions
- * @return Transformer
+ * @returns Transformer
  */
 declare function initializeTransformer<Value extends PlainObject>(transformers: TransformCallbacks<Value>): Transformer<Value>;
 /**

package/dist/value/unsmush.d.mts

@@ -1,14 +1,10 @@
-import { PlainObject, Simplify } from "../models.mjs";
+import { PlainObject, Simplify, UnionToIntersection } from "../models.mjs";
 
 //#region src/value/unsmush.d.ts
 /**
  * Thanks, type-fest!
  */
 type KeysOfUnion<ObjectType> = keyof UnionToIntersection<ObjectType extends unknown ? Record<keyof ObjectType, never> : never>;
-/**
- * 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
  */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oscarpalmer/atoms",
-	"version": "0.185.0",
+	"version": "0.186.0",
 	"description": "Atomic utilities for making your JavaScript better.",
 	"keywords": [
 		"helper",
@@ -253,13 +253,13 @@
 		"watch": "npx vite build --watch"
 	},
 	"devDependencies": {
-		"@oxlint/plugins": "^1.62",
+		"@oxlint/plugins": "^1.63",
 		"@types/node": "^25.6",
 		"@vitest/coverage-istanbul": "^4.1",
-		"eslint": "^10.2",
+		"eslint": "^10.3",
 		"jsdom": "^29.1",
-		"tsdown": "^0.21",
-		"typescript": "^5.9",
+		"tsdown": "^0.22",
+		"typescript": "^6",
 		"vite": "npm:@voidzero-dev/vite-plus-core@latest",
 		"vite-plus": "latest",
 		"vitest": "npm:@voidzero-dev/vite-plus-test@latest"

package/src/array/difference.ts

@@ -5,10 +5,20 @@ import type {PlainObject} from '../models';
 
 /**
  * Get the items from the first array that are not in the second array
+ *
  * @param first First array
  * @param second Second array
  * @param callback Callback to get an item's value for comparison
  * @returns Unique values from the first array
+ *
+ * @example
+ * ```typescript
+ * difference(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   [{id: 2}, {id: 4}],
+ *   item => item.id,
+ * ); // => [{id: 1}, {id: 3}]
+ * ```
  */
 export function difference<First, Second>(
 	first: First[],
@@ -18,10 +28,20 @@ export function difference<First, Second>(
 
 /**
  * Get the items from the first array that are not in the second array
+ *
  * @param first First array
  * @param second Second array
  * @param key Key to get an item's value for comparison
  * @returns Unique values from the first array
+ *
+ * @example
+ * ```typescript
+ * difference(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   [{id: 2}, {id: 4}],
+ *   'id',
+ * ); // => [{id: 1}, {id: 3}]
+ * ```
  */
 export function difference<
 	First extends PlainObject,
@@ -31,9 +51,18 @@ export function difference<
 
 /**
  * Get the items from the first array that are not in the second array
+ *
  * @param first First array
  * @param second Second array
  * @returns Unique values from the first array
+ *
+ * @example
+ * ```typescript
+ * difference(
+ *   [1, 2, 3],
+ *   [2, 4],
+ * ); // => [1, 3]
+ * ```
  */
 export function difference<First, Second>(first: First[], second: Second[]): First[];
 

package/src/array/exists.ts

@@ -5,10 +5,20 @@ import type {PlainObject} from '../models';
 
 /**
  * Does an item with a specific value exist in the array?
+ *
  * @param array Array to search in
  * @param callback Callback to get an item's value for matching
  * @param value Value to match against
  * @returns `true` if the item exists in the array, otherwise `false`
+ *
+ * @example
+ * ```typescript
+ * exists(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   item => item.id,
+ *   2,
+ * ); // => true
+ * ```
  */
 export function exists<
 	Item,
@@ -17,10 +27,20 @@ export function exists<
 
 /**
  * Does an item with a specific value exist in the array?
+ *
  * @param array Array to search in
  * @param key Key to get an item's value for matching
  * @param value Value to match against
  * @returns `true` if the item exists in the array, otherwise `false`
+ *
+ * @example
+ * ```typescript
+ * exists(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   'id',
+ *   2,
+ * ); // => true
+ * ```
  */
 export function exists<Item extends PlainObject, ItemKey extends keyof Item>(
 	array: Item[],
@@ -30,9 +50,18 @@ export function exists<Item extends PlainObject, ItemKey extends keyof Item>(
 
 /**
  * Does an item in the array match the filter?
+ *
  * @param array Array to search in
  * @param filter Filter callback to match items
  * @returns `true` if a matching item exists, otherwise `false`
+ *
+ * @example
+ * ```typescript
+ * exists(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   item => item.id === 2,
+ * ); // => true
+ * ```
  */
 export function exists<Item>(
 	array: Item[],
@@ -41,9 +70,15 @@ export function exists<Item>(
 
 /**
  * Does the item exist in the array?
+ *
  * @param array Array to search in
  * @param item Item to search for
  * @returns `true` if the item exists in the array, otherwise `false`
+ *
+ * @example
+ * ```typescript
+ * exists([1, 2, 3], 2); // => true
+ * ```
  */
 export function exists<Item>(array: Item[], item: Item): boolean;
 

package/src/array/filter.ts

@@ -4,13 +4,23 @@ import type {PlainObject} from '../models';
 // #region Functions
 
 /**
- * Get a filtered array of items that do not match the filter
+ * Get a filtered array of items that do not match the value
  *
  * Available as `exclude` and `filter.remove`
+ *
  * @param array Array to search in
  * @param callback Callback to get an item's value for matching
  * @param value Value to match against
  * @returns Filtered array of items that do not match the filter
+ *
+ * @example
+ * ```typescript
+ * exclude(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   item => item.id,
+ *   2,
+ * ); // => [{id: 1}, {id: 3}]
+ * ```
  */
 export function exclude<
 	Item,
@@ -18,13 +28,23 @@ export function exclude<
 >(array: Item[], callback: Callback, value: ReturnType<Callback>): unknown[];
 
 /**
- * Get a filtered array of items that do not match the filter
+ * Get a filtered array of items that do not match the value
  *
  * Available as `exclude` and `filter.remove`
+ *
  * @param array Array to search in
  * @param key Key to get an item's value for matching
  * @param value Value to match against
  * @returns Filtered array of items that do not match the filter
+ *
+ * @example
+ * ```typescript
+ * exclude(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   'id',
+ *   2,
+ * ); // => [{id: 1}, {id: 3}]
+ * ```
  */
 export function exclude<Item extends PlainObject, ItemKey extends keyof Item>(
 	array: Item[],
@@ -36,9 +56,18 @@ export function exclude<Item extends PlainObject, ItemKey extends keyof Item>(
  * Get a filtered array of items that do not match the filter
  *
  * Available as `exclude` and `filter.remove`
+ *
  * @param array Array to search in
  * @param filter Filter callback to match items
  * @returns Filtered array of items that do not match the filter
+ *
+ * @example
+ * ```typescript
+ * exclude(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   item => item.id === 2,
+ * ); // => [{id: 1}, {id: 3}]
+ * ```
  */
 export function exclude<Item>(
 	array: Item[],
@@ -49,9 +78,15 @@ export function exclude<Item>(
  * Get a filtered array of items that do not match the given item
  *
  * Available as `exclude` and `filter.remove`
+ *
  * @param array Array to search in
  * @param item Item to match against
  * @returns Filtered array of items that do not match the given item
+ *
+ * @example
+ * ```typescript
+ * exclude([1, 2, 3], 2); // => [1, 3]
+ * ```
  */
 export function exclude<Item>(array: Item[], item: Item): unknown[];
 
@@ -61,10 +96,20 @@ export function exclude(array: unknown[], ...parameters: unknown[]): unknown[] {
 
 /**
  * Get a filtered array of items
+ *
  * @param array Array to search in
  * @param callback Callback to get an item's value for matching
  * @param value Value to match against
  * @returns Filtered array of items
+ *
+ * @example
+ * ```typescript
+ * filter(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   item => item.id,
+ *   2,
+ * ); // => [{id: 2}]
+ * ```
  */
 export function filter<
 	Item,
@@ -73,10 +118,20 @@ export function filter<
 
 /**
  * Get a filtered array of items
+ *
  * @param array Array to search in
  * @param key Key to get an item's value for matching
  * @param value Value to match against
  * @returns Filtered array of items
+ *
+ * @example
+ * ```typescript
+ * filter(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   'id',
+ *   2,
+ * ); // => [{id: 2}]
+ * ```
  */
 export function filter<Item extends PlainObject, ItemKey extends keyof Item>(
 	array: Item[],
@@ -86,9 +141,18 @@ export function filter<Item extends PlainObject, ItemKey extends keyof Item>(
 
 /**
  * Get a filtered array of items matching the filter
+ *
  * @param array Array to search in
  * @param filter Filter callback to match items
  * @returns Filtered array of items
+ *
+ * @example
+ * ```typescript
+ * filter(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   item => item.id === 2,
+ * ); // => [{id: 2}]
+ * ```
  */
 export function filter<Item>(
 	array: Item[],
@@ -97,9 +161,15 @@ export function filter<Item>(
 
 /**
  * Get a filtered array of items matching the given item
+ *
  * @param array Array to search in
  * @param item Item to match against
  * @returns Filtered array of items
+ *
+ * @example
+ * ```typescript
+ * filter([1, 2, 3], 2); // => [2]
+ * ```
  */
 export function filter<Item>(array: Item[], item: Item): Item[];
 

package/src/array/find.ts

@@ -5,10 +5,20 @@ import type {PlainObject} from '../models';
 
 /**
  * Get the first item matching the given value
+ *
  * @param array Array to search in
  * @param callback Callback to get an item's value for matching
  * @param value Value to match against
  * @returns First item that matches the value, or `undefined` if no match is found
+ *
+ * @example
+ * ```typescript
+ * find(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   item => item.value,
+ *   10,
+ * ); // => {id: 1, value: 10}
+ * ```
  */
 export function find<Item, Callback extends (item: Item, index: number, array: Item[]) => unknown>(
 	array: Item[],
@@ -18,10 +28,20 @@ export function find<Item, Callback extends (item: Item, index: number, array: I
 
 /**
  * Get the first item matching the given value by key
+ *
  * @param array Array to search in
  * @param key Key to get an item's value for matching
  * @param value Value to match against
  * @returns First item that matches the value, or `undefined` if no match is found
+ *
+ * @example
+ * ```typescript
+ * find(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   'value',
+ *   10,
+ * ); // => {id: 1, value: 10}
+ * ```
  */
 export function find<Item extends PlainObject, ItemKey extends keyof Item>(
 	array: Item[],
@@ -31,9 +51,18 @@ export function find<Item extends PlainObject, ItemKey extends keyof Item>(
 
 /**
  * Get the first item matching the filter
+ *
  * @param array Array to search in
  * @param filter Filter callback to match items
  * @returns First item that matches the filter, or `undefined` if no match is found
+ *
+ * @example
+ * ```typescript
+ * find(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   item => item.value === 10,
+ * ); // => {id: 1, value: 10}
+ * ```
  */
 export function find<Item>(
 	array: Item[],
@@ -42,9 +71,15 @@ export function find<Item>(
 
 /**
  * Get the first item matching the given value
+ *
  * @param array Array to search in
  * @param value Value to match against
  * @returns First item that matches the value, or `undefined` if no match is found
+ *
+ * @example
+ * ```typescript
+ * find([1, 2, 3, 2, 1], 1); // => 1
+ * ```
  */
 export function find<Item>(array: Item[], value: Item): Item | undefined;
 
@@ -58,10 +93,20 @@ find.last = findLast;
  * Get the last item matching the given value
  *
  * Available as `findLast` and `find.last`
+ *
  * @param array Array to search in
  * @param callback Callback to get an item's value for matching
  * @param value Value to match against
  * @returns Last item that matches the value, or `undefined` if no match is found
+ *
+ * @example
+ * ```typescript
+ * findLast(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   item => item.value,
+ *   10,
+ * ); // => {id: 3, value: 10}
+ * ```
  */
 export function findLast<
 	Item,
@@ -72,10 +117,20 @@ export function findLast<
  * Get the last item matching the given value by key
  *
  * Available as `findLast` and `find.last`
+ *
  * @param array Array to search in
  * @param key Key to get an item's value for matching
  * @param value Value to match against
  * @returns Last item that matches the value, or `undefined` if no match is found
+ *
+ * @example
+ * ```typescript
+ * findLast(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   'value',
+ *   10,
+ * ); // => {id: 3, value: 10}
+ * ```
  */
 export function findLast<Item extends PlainObject, ItemKey extends keyof Item>(
 	array: Item[],
@@ -87,9 +142,18 @@ export function findLast<Item extends PlainObject, ItemKey extends keyof Item>(
  * Get the last item matching the filter
  *
  * Available as `findLast` and `find.last`
+ *
  * @param array Array to search in
  * @param filter Filter callback to match items
  * @returns Last item that matches the filter, or `undefined` if no match is found
+ *
+ * @example
+ * ```typescript
+ * findLast(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   item => item.value === 10,
+ * ); // => {id: 3, value: 10}
+ * ```
  */
 export function findLast<Item>(
 	array: Item[],
@@ -100,9 +164,15 @@ export function findLast<Item>(
  * Get the last item matching the given value
  *
  * Available as `findLast` and `find.last`
+ *
  * @param array Array to search in
  * @param value Value to match against
  * @returns Last item that matches the value, or `undefined` if no match is found
+ *
+ * @example
+ * ```typescript
+ * findLast([1, 2, 3, 2, 1], 1); // => 1
+ * ```
  */
 export function findLast<Item>(array: Item[], value: Item): Item | undefined;