@oscarpalmer/atoms 0.184.2 → 0.186.0

package/dist/value/merge.d.mts

@@ -1,17 +1,20 @@
-import { ArrayOrPlainObject, NestedPartial } from "../models.mjs";
+import { ArrayOrPlainObject, NestedPartial, PlainObject, UnionToIntersection } from "../models.mjs";
 
 //#region src/value/merge.d.ts
 /**
  * Options for assigning values
  */
 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
- */
-type Assigner<Model extends ArrayOrPlainObject = ArrayOrPlainObject> = (to: NestedPartial<Model>, from: NestedPartial<Model>[]) => Model;
+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
  */
@@ -45,20 +48,24 @@ type MergeOptions = {
    */
   skipNullableInArrays?: boolean;
 };
+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]>;
+};
 /**
- * Merge multiple arrays or objects into a single one
- * @param values Values to merge
- * @returns Merged value
- */
-type Merger<Model extends ArrayOrPlainObject = ArrayOrPlainObject> = (values: NestedPartial<Model>[]) => Model;
-/**
- * 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
  */
-declare function assign<Model extends ArrayOrPlainObject>(to: NestedPartial<Model>, from: NestedPartial<Model>[], options?: AssignOptions): Model;
+declare function assign<To extends PlainObject, From extends PlainObject[]>(to: To, from: [...From], options?: AssignOptions): To & UnionToIntersection<From[number]>;
 declare namespace assign {
   var initialize: typeof initializeAssigner;
 }
@@ -66,32 +73,28 @@ declare namespace assign {
  * Create an assigner with predefined options
  *
  * Available as `initializeAssigner` and `assign.initialize`
+ *
  * @param options Assigning options
  * @returns Assigner function
  */
-declare function initializeAssigner<Model extends ArrayOrPlainObject>(options?: AssignOptions): Assigner<Model>;
+declare function initializeAssigner(options?: AssignOptions): Assigner;
 /**
  * Create a merger with predefined options
  *
  * Available as `initializeMerger` and `merge.initialize`
+ *
  * @param options Merging options
  * @returns Merger function
  */
 declare function initializeMerger(options?: MergeOptions): Merger;
 /**
  * Merge multiple arrays or objects into a single one
+ *
  * @param values Values to merge
  * @param options Merging options
  * @returns Merged value
  */
-declare 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
- */
-declare function merge(values: NestedPartial<ArrayOrPlainObject>[], options?: MergeOptions): ArrayOrPlainObject;
+declare function merge<Values extends ArrayOrPlainObject[]>(values: [...Values], options?: MergeOptions): UnionToIntersection<Values[number]>;
 declare namespace merge {
   var initialize: typeof initializeMerger;
 }

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/shake.d.mts

@@ -1,6 +1,9 @@
 import { PlainObject } from "../models.mjs";
 
 //#region src/value/shake.d.ts
+/**
+ * A shaken object, without any `undefined` values
+ */
 type Shaken<Value extends PlainObject> = { [Key in keyof Value]: Value[Key] extends undefined ? never : Value[Key] };
 /**
  * Shake an object, removing all keys with `undefined` values

package/dist/value/smush.d.mts

@@ -1,6 +1,9 @@
 import { NestedKeys, NestedValue, PlainObject, Simplify, ToString } from "../models.mjs";
 
 //#region src/value/smush.d.ts
+/**
+ * A smushed object, with all nested objects flattened into a single level, using dot notation keys
+ */
 type Smushed<Value extends PlainObject> = Simplify<{ [NestedKey in NestedKeys<Value>]: NestedValue<Value, ToString<NestedKey>> }>;
 /**
  * Smush an object into a flat object that uses dot notation keys

package/dist/value/transform.d.mts

@@ -1,8 +1,17 @@
 import { PlainObject } from "../models.mjs";
 
 //#region src/value/transform.d.ts
+/**
+ * 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
+ */
 type Transformer<Value extends PlainObject> = {
   (value: Value): Value;
 };
@@ -19,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,4 +1,4 @@
-import { PlainObject, Simplify } from "../models.mjs";
+import { PlainObject, Simplify, UnionToIntersection } from "../models.mjs";
 
 //#region src/value/unsmush.d.ts
 /**
@@ -6,9 +6,8 @@ import { PlainObject, Simplify } from "../models.mjs";
  */
 type KeysOfUnion<ObjectType> = keyof UnionToIntersection<ObjectType extends unknown ? Record<keyof ObjectType, never> : never>;
 /**
- * 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;
 type Unsmushed<Value extends PlainObject> = Simplify<Omit<{ [UnionKey in KeysOfUnion<Value>]: Value[UnionKey] }, `${string}.${string}`>>;
 /**
  * Unsmush a smushed object _(turning dot notation keys into nested keys)_

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oscarpalmer/atoms",
-	"version": "0.184.2",
+	"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.61",
+		"@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

@@ -1,12 +1,24 @@
 import {COMPARE_SETS_DIFFERENCE, compareSets} from '../internal/array/sets';
 import type {PlainObject} from '../models';
 
+// #region Functions
+
 /**
  * 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[],
@@ -16,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,
@@ -29,12 +51,23 @@ 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[];
 
 export function difference(first: unknown[], second: unknown[], key?: unknown): unknown[] {
 	return compareSets(COMPARE_SETS_DIFFERENCE, first, second, key);
 }
+
+// #endregion

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[];