@oscarpalmer/atoms 0.161.0 → 0.162.0

package/dist/array/index.js

@@ -11,8 +11,9 @@ import { indexOf } from "../internal/array/index-of.js";
 import { shuffle } from "../internal/array/shuffle.js";
 import { insert } from "./insert.js";
 import { intersection } from "./intersection.js";
-import { partition } from "./partition.js";
 import { endsWithArray, getArrayPosition, includesArray, indexOfArray, startsWithArray } from "./position.js";
+import { move } from "./move.js";
+import { partition } from "./partition.js";
 import { push } from "./push.js";
 import { select } from "./select.js";
 import { drop, slice, take } from "./slice.js";
@@ -23,4 +24,4 @@ import { toSet } from "./to-set.js";
 import { toggle } from "./toggle.js";
 import { union } from "./union.js";
 import { update } from "./update.js";
-export { chunk, compact, difference, drop, endsWithArray, exists, filter, find, flatten, getArray, getArrayPosition, includesArray, indexOf, indexOfArray, insert, intersection, partition, push, range, select, shuffle, slice, sort, splice, startsWithArray, swap, take, times, toSet, toggle, union, update };
+export { chunk, compact, difference, drop, endsWithArray, exists, filter, find, flatten, getArray, getArrayPosition, includesArray, indexOf, indexOfArray, insert, intersection, move, partition, push, range, select, shuffle, slice, sort, splice, startsWithArray, swap, take, times, toSet, toggle, union, update };

package/dist/array/move.js

@@ -0,0 +1,64 @@
+import { arraysOverlap } from "../internal/array/overlap.js";
+import { indexOfArray } from "./position.js";
+//#region src/array/move.ts
+function move(array, from, to, key) {
+	if (!Array.isArray(array)) return [];
+	const firstArray = Array.isArray(from) ? from : [from];
+	const secondArray = Array.isArray(to) ? to : [to];
+	if (firstArray.length === 0 || secondArray.length === 0) return array;
+	const firstPosition = indexOfArray(array, firstArray, key);
+	const secondPosition = indexOfArray(array, secondArray, key);
+	if (firstPosition === -1 || secondPosition === -1 || firstPosition === secondPosition) return array;
+	const { overlap } = arraysOverlap({
+		array: firstArray,
+		index: firstPosition
+	}, {
+		array: secondArray,
+		index: secondPosition
+	});
+	if (overlap) return array;
+	array.splice(firstPosition, firstArray.length);
+	const next = secondPosition < firstPosition ? secondPosition : secondPosition + secondArray.length - firstArray.length;
+	if (next >= array.length) array.push(...firstArray);
+	else array.splice(next, 0, ...firstArray);
+	return array;
+}
+move.indices = moveIndices;
+move.toIndex = moveToIndex;
+/**
+* Move an item from one index to another within an array
+*
+* If the from index is out of bounds, the array will be returned unchanged
+* @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)_
+*/
+function moveIndices(array, from, to) {
+	if (!Array.isArray(array)) return [];
+	const { length } = array;
+	if (length === 0 || typeof from !== "number" || typeof to !== "number") return array;
+	const fromIndex = from < 0 ? length + from : from;
+	const toIndex = to < 0 ? length + to : to;
+	if (fromIndex === toIndex || fromIndex >= length || toIndex >= length) return array;
+	const spliced = array.splice(fromIndex, 1);
+	if (toIndex >= array.length) array.push(...spliced);
+	else array.splice(toIndex, 0, ...spliced);
+	return array;
+}
+function moveToIndex(array, value, index, key) {
+	if (!Array.isArray(array)) return [];
+	const { length } = array;
+	if (length === 0 || typeof index !== "number") return array;
+	const next = index < 0 ? length + index : index;
+	if (next >= length) return array;
+	const values = Array.isArray(value) ? value : [value];
+	const position = indexOfArray(array, values, key);
+	if (position === -1 || position === next) return array;
+	array.splice(position, values.length);
+	if (next >= array.length) array.push(...values);
+	else array.splice(next, 0, ...values);
+	return array;
+}
+//#endregion
+export { move };

package/dist/array/swap.js

@@ -1,5 +1,6 @@
 import { getArrayCallback } from "../internal/array/callbacks.js";
 import { indexOf } from "../internal/array/index-of.js";
+import { arraysOverlap } from "../internal/array/overlap.js";
 import { indexOfArray } from "./position.js";
 //#region src/array/swap.ts
 function swap(array, first, second, third) {
@@ -15,14 +16,16 @@ function swapArrays(array, from, to, key) {
 	const fromIndex = indexOfArray(array, from, key);
 	const toIndex = indexOfArray(array, to, key);
 	if (fromIndex === -1 || toIndex === -1) return array;
-	const first = fromIndex < toIndex ? from : to;
-	const second = fromIndex < toIndex ? to : from;
-	const firstIndex = first === from ? fromIndex : toIndex;
-	const secondIndex = first === from ? toIndex : fromIndex;
-	const firstEnd = firstIndex + first.length - 1;
-	if (firstIndex <= secondIndex + second.length - 1 && firstEnd >= secondIndex) return array;
-	array.splice(firstIndex, first.length, ...second);
-	array.splice(secondIndex, second.length, ...first);
+	const { first, second, overlap } = arraysOverlap({
+		array: from,
+		index: fromIndex
+	}, {
+		array: to,
+		index: toIndex
+	});
+	if (overlap) return array;
+	array.splice(first.index, first.array.length, ...second.array);
+	array.splice(second.index + (second.array.length - first.array.length), second.array.length, ...first.array);
 	return array;
 }
 /**

package/dist/atoms.full.js

@@ -367,9 +367,23 @@ function insert(array, indexOrItems, items) {
 function intersection(first, second, key) {
 	return compareSets(COMPARE_SETS_INTERSECTION, first, second, key);
 }
-function partition(array, ...parameters) {
-	const { matched, notMatched } = findValues("all", array, parameters);
-	return [matched, notMatched];
+function arraysOverlap(first, second) {
+	const firstArray = first.index < second.index ? first.array : second.array;
+	const secondArray = first.index < second.index ? second.array : first.array;
+	const firstIndex = firstArray === first.array ? first.index : second.index;
+	const secondIndex = firstArray === first.array ? second.index : first.index;
+	const firstEnd = firstIndex + firstArray.length - 1;
+	return {
+		overlap: firstIndex <= secondIndex + secondArray.length - 1 && firstEnd >= secondIndex,
+		first: {
+			array: firstArray,
+			index: firstIndex
+		},
+		second: {
+			array: secondArray,
+			index: secondIndex
+		}
+	};
 }
 function endsWithArray(haystack, needle, key) {
 	return endings.has(getPosition(haystack, needle, key)[1]);
@@ -425,6 +439,69 @@ 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]);
+function move(array, from, to, key) {
+	if (!Array.isArray(array)) return [];
+	const firstArray = Array.isArray(from) ? from : [from];
+	const secondArray = Array.isArray(to) ? to : [to];
+	if (firstArray.length === 0 || secondArray.length === 0) return array;
+	const firstPosition = indexOfArray(array, firstArray, key);
+	const secondPosition = indexOfArray(array, secondArray, key);
+	if (firstPosition === -1 || secondPosition === -1 || firstPosition === secondPosition) return array;
+	const { overlap } = arraysOverlap({
+		array: firstArray,
+		index: firstPosition
+	}, {
+		array: secondArray,
+		index: secondPosition
+	});
+	if (overlap) return array;
+	array.splice(firstPosition, firstArray.length);
+	const next = secondPosition < firstPosition ? secondPosition : secondPosition + secondArray.length - firstArray.length;
+	if (next >= array.length) array.push(...firstArray);
+	else array.splice(next, 0, ...firstArray);
+	return array;
+}
+move.indices = moveIndices;
+move.toIndex = moveToIndex;
+/**
+* Move an item from one index to another within an array
+*
+* If the from index is out of bounds, the array will be returned unchanged
+* @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)_
+*/
+function moveIndices(array, from, to) {
+	if (!Array.isArray(array)) return [];
+	const { length } = array;
+	if (length === 0 || typeof from !== "number" || typeof to !== "number") return array;
+	const fromIndex = from < 0 ? length + from : from;
+	const toIndex = to < 0 ? length + to : to;
+	if (fromIndex === toIndex || fromIndex >= length || toIndex >= length) return array;
+	const spliced = array.splice(fromIndex, 1);
+	if (toIndex >= array.length) array.push(...spliced);
+	else array.splice(toIndex, 0, ...spliced);
+	return array;
+}
+function moveToIndex(array, value, index, key) {
+	if (!Array.isArray(array)) return [];
+	const { length } = array;
+	if (length === 0 || typeof index !== "number") return array;
+	const next = index < 0 ? length + index : index;
+	if (next >= length) return array;
+	const values = Array.isArray(value) ? value : [value];
+	const position = indexOfArray(array, values, key);
+	if (position === -1 || position === next) return array;
+	array.splice(position, values.length);
+	if (next >= array.length) array.push(...values);
+	else array.splice(next, 0, ...values);
+	return array;
+}
+function partition(array, ...parameters) {
+	const { matched, notMatched } = findValues("all", array, parameters);
+	return [matched, notMatched];
+}
 /**
 * Push items into an array _(at the end)_
 * @param array Original array
@@ -774,14 +851,16 @@ function swapArrays(array, from, to, key) {
 	const fromIndex = indexOfArray(array, from, key);
 	const toIndex = indexOfArray(array, to, key);
 	if (fromIndex === -1 || toIndex === -1) return array;
-	const first = fromIndex < toIndex ? from : to;
-	const second = fromIndex < toIndex ? to : from;
-	const firstIndex = first === from ? fromIndex : toIndex;
-	const secondIndex = first === from ? toIndex : fromIndex;
-	const firstEnd = firstIndex + first.length - 1;
-	if (firstIndex <= secondIndex + second.length - 1 && firstEnd >= secondIndex) return array;
-	array.splice(firstIndex, first.length, ...second);
-	array.splice(secondIndex, second.length, ...first);
+	const { first, second, overlap } = arraysOverlap({
+		array: from,
+		index: fromIndex
+	}, {
+		array: to,
+		index: toIndex
+	});
+	if (overlap) return array;
+	array.splice(first.index, first.array.length, ...second.array);
+	array.splice(second.index + (second.array.length - first.array.length), second.array.length, ...first.array);
 	return array;
 }
 /**
@@ -4144,4 +4223,4 @@ var SizedSet = class extends Set {
 		}
 	}
 };
-export { CancelablePromise, PromiseTimeoutError, QueueError, RetryError, SizedMap, SizedSet, attempt, attemptPromise, average, beacon, between, camelCase, cancelable, capitalize, ceil, chunk, clamp, clone, compact, compare, count, debounce, delay, diff, difference, drop, endsWith, endsWithArray, equal, error, exists, filter, find, flatten, floor, flow, toResult as fromPromise, toResult, fromQuery, toPromise as fromResult, toPromise, getArray, getArrayPosition, getColor, getForegroundColor, getHexColor, getHexaColor, getHslColor, getHslaColor, getNormalizedHex, getNumber, getRandomBoolean, getRandomCharacters, getRandomColor, getRandomFloat, getRandomHex, getRandomInteger, getRandomItem, getRandomItems, getRgbColor, getRgbaColor, getString, getUuid, getValue, groupBy, hasValue, hexToHsl, hexToHsla, hexToRgb, hexToRgba, hslToHex, hslToRgb, hslToRgba, ignoreKey, includes, includesArray, indexOf, indexOfArray, insert, intersection, isArrayOrPlainObject, isColor, isConstructor, isEmpty, isError, isFulfilled, isHexColor, isHslColor, isHslLike, isHslaColor, isInstanceOf, isKey, isNonNullable, isNullable, isNullableOrEmpty, isNullableOrWhitespace, isNumber, isNumerical, isObject, isOk, isPlainObject, isPrimitive, isRejected, isResult, isRgbColor, isRgbLike, isRgbaColor, isTypedArray, join, kebabCase, logger, lowerCase, max, median, memoize, merge, min, noop, ok, omit, once, parse, partition, pascalCase, pick, pipe, promises, push, queue, range, retry, rgbToHex, rgbToHsl, rgbToHsla, round, select, setValue, shuffle, slice, smush, snakeCase, sort, splice, startsWith, startsWithArray, sum, swap, take, template, throttle, timed, times, titleCase, toMap, toQuery, toRecord, toSet, toggle, trim, truncate, tryDecode, tryEncode, union, unique, unsmush, unwrap, update, upperCase, words };
+export { CancelablePromise, PromiseTimeoutError, QueueError, RetryError, SizedMap, SizedSet, attempt, attemptPromise, average, beacon, between, camelCase, cancelable, capitalize, ceil, chunk, clamp, clone, compact, compare, count, debounce, delay, diff, difference, drop, endsWith, endsWithArray, equal, error, exists, filter, find, flatten, floor, flow, toResult as fromPromise, toResult, fromQuery, toPromise as fromResult, toPromise, getArray, getArrayPosition, getColor, getForegroundColor, getHexColor, getHexaColor, getHslColor, getHslaColor, getNormalizedHex, getNumber, getRandomBoolean, getRandomCharacters, getRandomColor, getRandomFloat, getRandomHex, getRandomInteger, getRandomItem, getRandomItems, getRgbColor, getRgbaColor, getString, getUuid, getValue, groupBy, hasValue, hexToHsl, hexToHsla, hexToRgb, hexToRgba, hslToHex, hslToRgb, hslToRgba, ignoreKey, includes, includesArray, indexOf, indexOfArray, insert, intersection, isArrayOrPlainObject, isColor, isConstructor, isEmpty, isError, isFulfilled, isHexColor, isHslColor, isHslLike, isHslaColor, isInstanceOf, isKey, isNonNullable, isNullable, isNullableOrEmpty, isNullableOrWhitespace, isNumber, isNumerical, isObject, isOk, isPlainObject, isPrimitive, isRejected, isResult, isRgbColor, isRgbLike, isRgbaColor, isTypedArray, join, kebabCase, logger, lowerCase, max, median, memoize, merge, min, move, noop, ok, omit, once, parse, partition, pascalCase, pick, pipe, promises, push, queue, range, retry, rgbToHex, rgbToHsl, rgbToHsla, round, select, setValue, shuffle, slice, smush, snakeCase, sort, splice, startsWith, startsWithArray, sum, swap, take, template, throttle, timed, times, titleCase, toMap, toQuery, toRecord, toSet, toggle, trim, truncate, tryDecode, tryEncode, union, unique, unsmush, unwrap, update, upperCase, words };

package/dist/index.js

@@ -14,8 +14,9 @@ import { getRandomFloat, getRandomInteger } from "./internal/random.js";
 import { shuffle } from "./internal/array/shuffle.js";
 import { insert } from "./array/insert.js";
 import { intersection } from "./array/intersection.js";
-import { partition } from "./array/partition.js";
 import { endsWithArray, getArrayPosition, includesArray, indexOfArray, startsWithArray } from "./array/position.js";
+import { move } from "./array/move.js";
+import { partition } from "./array/partition.js";
 import { push } from "./array/push.js";
 import { select } from "./array/select.js";
 import { drop, slice, take } from "./array/slice.js";
@@ -79,4 +80,4 @@ import { fromQuery, toQuery } from "./query.js";
 import { QueueError, queue } from "./queue.js";
 import { getRandomBoolean, getRandomCharacters, getRandomColor, getRandomHex, getRandomItem, getRandomItems } from "./random.js";
 import { SizedSet } from "./sized/set.js";
-export { CancelablePromise, PromiseTimeoutError, QueueError, RetryError, SizedMap, SizedSet, attempt, attemptPromise, average, beacon, between, camelCase, cancelable, capitalize, ceil, chunk, clamp, clone, compact, compare, count, debounce, delay, diff, difference, drop, endsWith, endsWithArray, equal, error, exists, filter, find, flatten, floor, flow, toResult as fromPromise, fromQuery, toPromise as fromResult, getArray, getArrayPosition, getColor, getForegroundColor, getHexColor, getHexaColor, getHslColor, getHslaColor, getNormalizedHex, getNumber, getRandomBoolean, getRandomCharacters, getRandomColor, getRandomFloat, getRandomHex, getRandomInteger, getRandomItem, getRandomItems, getRgbColor, getRgbaColor, getString, getUuid, getValue, groupBy, hasValue, hexToHsl, hexToHsla, hexToRgb, hexToRgba, hslToHex, hslToRgb, hslToRgba, ignoreKey, includes, includesArray, indexOf, indexOfArray, insert, intersection, isArrayOrPlainObject, isColor, isConstructor, isEmpty, isError, isFulfilled, isHexColor, isHslColor, isHslLike, isHslaColor, isInstanceOf, isKey, isNonNullable, isNullable, isNullableOrEmpty, isNullableOrWhitespace, isNumber, isNumerical, isObject, isOk, isPlainObject, isPrimitive, isRejected, isResult, isRgbColor, isRgbLike, isRgbaColor, isTypedArray, join, kebabCase, logger, lowerCase, max, median, memoize, merge, min, noop, ok, omit, once, parse, partition, pascalCase, pick, pipe, promises, push, queue, range, retry, rgbToHex, rgbToHsl, rgbToHsla, round, select, setValue, shuffle, slice, smush, snakeCase, sort, splice, startsWith, startsWithArray, sum, swap, take, template, throttle, timed, times, titleCase, toMap, toPromise, toQuery, toRecord, toResult, toSet, toggle, trim, truncate, tryDecode, tryEncode, union, unique, unsmush, unwrap, update, upperCase, words };
+export { CancelablePromise, PromiseTimeoutError, QueueError, RetryError, SizedMap, SizedSet, attempt, attemptPromise, average, beacon, between, camelCase, cancelable, capitalize, ceil, chunk, clamp, clone, compact, compare, count, debounce, delay, diff, difference, drop, endsWith, endsWithArray, equal, error, exists, filter, find, flatten, floor, flow, toResult as fromPromise, fromQuery, toPromise as fromResult, getArray, getArrayPosition, getColor, getForegroundColor, getHexColor, getHexaColor, getHslColor, getHslaColor, getNormalizedHex, getNumber, getRandomBoolean, getRandomCharacters, getRandomColor, getRandomFloat, getRandomHex, getRandomInteger, getRandomItem, getRandomItems, getRgbColor, getRgbaColor, getString, getUuid, getValue, groupBy, hasValue, hexToHsl, hexToHsla, hexToRgb, hexToRgba, hslToHex, hslToRgb, hslToRgba, ignoreKey, includes, includesArray, indexOf, indexOfArray, insert, intersection, isArrayOrPlainObject, isColor, isConstructor, isEmpty, isError, isFulfilled, isHexColor, isHslColor, isHslLike, isHslaColor, isInstanceOf, isKey, isNonNullable, isNullable, isNullableOrEmpty, isNullableOrWhitespace, isNumber, isNumerical, isObject, isOk, isPlainObject, isPrimitive, isRejected, isResult, isRgbColor, isRgbLike, isRgbaColor, isTypedArray, join, kebabCase, logger, lowerCase, max, median, memoize, merge, min, move, noop, ok, omit, once, parse, partition, pascalCase, pick, pipe, promises, push, queue, range, retry, rgbToHex, rgbToHsl, rgbToHsla, round, select, setValue, shuffle, slice, smush, snakeCase, sort, splice, startsWith, startsWithArray, sum, swap, take, template, throttle, timed, times, titleCase, toMap, toPromise, toQuery, toRecord, toResult, toSet, toggle, trim, truncate, tryDecode, tryEncode, union, unique, unsmush, unwrap, update, upperCase, words };

package/dist/internal/array/overlap.js

@@ -0,0 +1,21 @@
+//#region src/internal/array/overlap.ts
+function arraysOverlap(first, second) {
+	const firstArray = first.index < second.index ? first.array : second.array;
+	const secondArray = first.index < second.index ? second.array : first.array;
+	const firstIndex = firstArray === first.array ? first.index : second.index;
+	const secondIndex = firstArray === first.array ? second.index : first.index;
+	const firstEnd = firstIndex + firstArray.length - 1;
+	return {
+		overlap: firstIndex <= secondIndex + secondArray.length - 1 && firstEnd >= secondIndex,
+		first: {
+			array: firstArray,
+			index: firstIndex
+		},
+		second: {
+			array: secondArray,
+			index: secondIndex
+		}
+	};
+}
+//#endregion
+export { arraysOverlap };

package/package.json

@@ -5,11 +5,11 @@
 	},
 	"description": "Atomic utilities for making your JavaScript better.",
 	"devDependencies": {
-		"@types/node": "^25.3",
+		"@types/node": "^25.4",
 		"@vitest/coverage-istanbul": "^4",
 		"jsdom": "^28.1",
-		"oxfmt": "^0.36",
-		"oxlint": "^1.51",
+		"oxfmt": "^0.38",
+		"oxlint": "^1.53",
 		"rolldown": "1.0.0-rc.8",
 		"tslib": "^2.8",
 		"typescript": "^5.9",
@@ -184,5 +184,5 @@
 	},
 	"type": "module",
 	"types": "./types/index.d.ts",
-	"version": "0.161.0"
+	"version": "0.162.0"
 }

package/src/array/index.ts

@@ -12,6 +12,7 @@ export * from './from';
 export * from './get';
 export * from './insert';
 export * from './intersection';
+export * from './move';
 export * from './partition';
 export * from './position';
 export * from './push';

package/src/array/move.ts

@@ -0,0 +1,228 @@
+import {arraysOverlap} from '../internal/array/overlap';
+import type {PlainObject} from '../models';
+import {indexOfArray} from './position';
+
+/**
+ * Move an item _(or array of items)_ to the position of another item _(or array of items)_ within an array
+ *
+ * When moving to the front of the array, the moved items will be placed __before__ the target item. When moving to the back of the array, the moved items will be placed __after__ the target item.
+ *
+ * If either of values are not present in the array, or if they overlap, the array will be returned unchanged
+ * @param array Array to move within
+ * @param from Item or items to move
+ * @param to Item or items to move to
+ * @param key Key to get an item's value for matching
+ * @returns Original array with items moved _(or unchanged if unable to move)_
+ */
+export function move<Item extends PlainObject, Key extends keyof Item>(
+	array: Item[],
+	from: Item | Item[],
+	to: Item | Item[],
+	key: Key,
+): Item[];
+
+/**
+ * Move an item _(or array of items)_ to the position of another item _(or array of items)_ within an array
+ *
+ * When moving to the front of the array, the moved items will be placed __before__ the target item. When moving to the back of the array, the moved items will be placed __after__ the target item.
+ *
+ * If either of values are not present in the array, or if they overlap, the array will be returned unchanged
+ * @param array Array to move within
+ * @param from Item or items to move
+ * @param to Item or items to move to
+ * @param callback Callback to get an item's value for matching
+ * @returns Original array with items moved _(or unchanged if unable to move)_
+ */
+export function move<Item>(
+	array: Item[],
+	from: Item | Item[],
+	to: Item | Item[],
+	callback: (item: Item, index: number, array: Item[]) => unknown,
+): Item[];
+
+/**
+ * Move an item _(or array of items)_ to the position of another item _(or array of items)_ within an array
+ *
+ * When moving to the front of the array, the moved items will be placed __before__ the target item. When moving to the back of the array, the moved items will be placed __after__ the target item.
+ *
+ * If either of values are not present in the array, or if they overlap, the array will be returned unchanged
+ * @param array Array to move within
+ * @param from Item or items to move
+ * @param to Item or items to move to
+ * @returns Original array with items moved _(or unchanged if unable to move)_
+ */
+export function move<Item>(array: Item[], from: Item | Item[], to: Item | Item[]): Item[];
+
+export function move(array: unknown[], from: unknown, to: unknown, key?: unknown): unknown[] {
+	if (!Array.isArray(array)) {
+		return [];
+	}
+
+	const firstArray = Array.isArray(from) ? from : [from];
+	const secondArray = Array.isArray(to) ? to : [to];
+
+	if (firstArray.length === 0 || secondArray.length === 0) {
+		return array;
+	}
+
+	const firstPosition = indexOfArray(array, firstArray, key as never);
+	const secondPosition = indexOfArray(array, secondArray, key as never);
+
+	if (firstPosition === -1 || secondPosition === -1 || firstPosition === secondPosition) {
+		return array;
+	}
+
+	const {overlap} = arraysOverlap(
+		{
+			array: firstArray,
+			index: firstPosition,
+		},
+		{
+			array: secondArray,
+			index: secondPosition,
+		},
+	);
+
+	if (overlap) {
+		// The arrays overlap, so we can't swap them without losing data
+
+		return array;
+	}
+
+	array.splice(firstPosition, firstArray.length);
+
+	const next =
+		secondPosition < firstPosition
+			? secondPosition
+			: secondPosition + secondArray.length - firstArray.length;
+
+	if (next >= array.length) {
+		array.push(...firstArray);
+	} else {
+		array.splice(next, 0, ...firstArray);
+	}
+
+	return array;
+}
+
+move.indices = moveIndices;
+move.toIndex = moveToIndex;
+
+/**
+ * Move an item from one index to another within an array
+ *
+ * If the from index is out of bounds, the array will be returned unchanged
+ * @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)_
+ */
+function moveIndices<Item>(array: Item[], from: number, to: number): Item[] {
+	if (!Array.isArray(array)) {
+		return [];
+	}
+
+	const {length} = array;
+
+	if (length === 0 || typeof from !== 'number' || typeof to !== 'number') {
+		return array;
+	}
+
+	const fromIndex = from < 0 ? length + from : from;
+	const toIndex = to < 0 ? length + to : to;
+
+	if (fromIndex === toIndex || fromIndex >= length || toIndex >= length) {
+		return array;
+	}
+
+	const spliced = array.splice(fromIndex, 1);
+
+	if (toIndex >= array.length) {
+		array.push(...spliced);
+	} else {
+		array.splice(toIndex, 0, ...spliced);
+	}
+
+	return array;
+}
+
+/**
+ * Move an item _(or array of items)_ to an index within an array
+ *
+ * If the value is not present in the array, or if the index is out of bounds, the array will be returned unchanged
+ * @param array Array to move within
+ * @param value Item or items to move
+ * @param index Index to move to
+ * @param key Key to get an item's value for matching
+ * @returns Original array with items moved _(or unchanged if unable to move)_
+ */
+function moveToIndex<Item extends PlainObject, Key extends keyof Item>(
+	array: Item[],
+	value: Item | Item[],
+	index: number,
+	key: Key,
+): Item[];
+
+/**
+ * Move an item _(or array of items)_ to an index within an array
+ *
+ * If the value is not present in the array, or if the index is out of bounds, the array will be returned unchanged
+ * @param array Array to move within
+ * @param value Item or items to move
+ * @param index Index to move to
+ * @param callback Callback to get an item's value for matching
+ * @returns Original array with items moved _(or unchanged if unable to move)_
+ */
+function moveToIndex<Item>(
+	array: Item[],
+	value: Item | Item[],
+	index: number,
+	callback: (item: Item, index: number, array: Item[]) => unknown,
+): Item[];
+
+/**
+ * Move an item _(or array of items)_ to an index within an array
+ *
+ * If the value is not present in the array, or if the index is out of bounds, the array will be returned unchanged
+ * @param array Array to move within
+ * @param value Item or items to move
+ * @param index Index to move to
+ * @returns Original array with items moved _(or unchanged if unable to move)_
+ */
+function moveToIndex<Item>(array: Item[], value: Item | Item[], index: number): Item[];
+
+function moveToIndex(array: unknown[], value: unknown, index: number, key?: unknown): unknown[] {
+	if (!Array.isArray(array)) {
+		return [];
+	}
+
+	const {length} = array;
+
+	if (length === 0 || typeof index !== 'number') {
+		return array;
+	}
+
+	const next = index < 0 ? length + index : index;
+
+	if (next >= length) {
+		return array;
+	}
+
+	const values = Array.isArray(value) ? value : [value];
+
+	const position = indexOfArray(array, values, key as never);
+
+	if (position === -1 || position === next) {
+		return array;
+	}
+
+	array.splice(position, values.length);
+
+	if (next >= array.length) {
+		array.push(...values);
+	} else {
+		array.splice(next, 0, ...values);
+	}
+
+	return array;
+}

package/src/array/sort.ts

@@ -213,7 +213,7 @@ export function sort(array: unknown[], first?: unknown, second?: unknown): unkno
 	const direction =
 		first === true || second === true ? SORT_DIRECTION_DESCENDING : SORT_DIRECTION_ASCENDING;
 
-		const modifier = direction === SORT_DIRECTION_ASCENDING ? 1 : -1;
+	const modifier = direction === SORT_DIRECTION_ASCENDING ? 1 : -1;
 
 	const sorters = (Array.isArray(first) ? first : [first])
 		.map(item => getSorter(item, modifier))

package/src/array/swap.ts

@@ -1,5 +1,6 @@
 import {getArrayCallback} from '../internal/array/callbacks';
 import {indexOf} from '../internal/array/index-of';
+import {arraysOverlap} from '../internal/array/overlap';
 import type {PlainObject} from '../models';
 import {indexOfArray} from './position';
 
@@ -130,23 +131,30 @@ function swapArrays(array: unknown[], from: unknown[], to: unknown[], key: unkno
 		return array;
 	}
 
-	const first = fromIndex < toIndex ? from : to;
-	const second = fromIndex < toIndex ? to : from;
-
-	const firstIndex = first === from ? fromIndex : toIndex;
-	const secondIndex = first === from ? toIndex : fromIndex;
-
-	const firstEnd = firstIndex + first.length - 1;
-	const secondEnd = secondIndex + second.length - 1;
-
-	if (firstIndex <= secondEnd && firstEnd >= secondIndex) {
+	const {first, second, overlap} = arraysOverlap(
+		{
+			array: from,
+			index: fromIndex,
+		},
+		{
+			array: to,
+			index: toIndex,
+		},
+	);
+
+	if (overlap) {
 		// The arrays overlap, so we can't swap them without losing data
 
 		return array;
 	}
 
-	array.splice(firstIndex, first.length, ...second);
-	array.splice(secondIndex, second.length, ...first);
+	array.splice(first.index, first.array.length, ...second.array);
+
+	array.splice(
+		second.index + (second.array.length - first.array.length),
+		second.array.length,
+		...first.array,
+	);
 
 	return array;
 }

package/src/color/instance.ts

@@ -1,4 +1,4 @@
-import { SPACE_HSL, SPACE_RGB } from './constants';
+import {SPACE_HSL, SPACE_RGB} from './constants';
 import {formatColor} from './misc';
 import {getAlpha} from './misc/alpha';
 import {getState, setHexColor, setHSLColor, setRGBColor} from './misc/state';

package/src/internal/array/overlap.ts

@@ -0,0 +1,35 @@
+type OverlapItem = {
+	array: unknown[];
+	index: number;
+};
+
+type OverlapResult = {
+	first: OverlapItem;
+	second: OverlapItem;
+	overlap: boolean;
+};
+
+export function arraysOverlap(first: OverlapItem, second: OverlapItem): OverlapResult {
+	const firstArray = first.index < second.index ? first.array : second.array;
+	const secondArray = first.index < second.index ? second.array : first.array;
+
+	const firstIndex = firstArray === first.array ? first.index : second.index;
+	const secondIndex = firstArray === first.array ? second.index : first.index;
+
+	const firstEnd = firstIndex + firstArray.length - 1;
+	const secondEnd = secondIndex + secondArray.length - 1;
+
+	const overlap = firstIndex <= secondEnd && firstEnd >= secondIndex;
+
+	return {
+		overlap,
+		first: {
+			array: firstArray,
+			index: firstIndex,
+		},
+		second: {
+			array: secondArray,
+			index: secondIndex,
+		},
+	};
+}

package/src/internal/value/set.ts

@@ -44,12 +44,7 @@ export function setValue<Data extends PlainObject>(
 	ignoreCase?: boolean,
 ): Data;
 
-export function setValue(
-	data: object,
-	path: string,
-	value: unknown,
-	ignoreCase?: boolean,
-): object {
+export function setValue(data: object, path: string, value: unknown, ignoreCase?: boolean): object {
 	if (
 		typeof data !== 'object' ||
 		data === null ||

package/src/promise/helpers.ts

@@ -58,9 +58,7 @@ export function getPromisesOptions(input: unknown): RequiredKeys<PromisesOptions
 	};
 }
 
-export function getResultsFromPromises<Value>(
-	promised: PromisesValue<Value>[],
-): Result<Value>[] {
+export function getResultsFromPromises<Value>(promised: PromisesValue<Value>[]): Result<Value>[] {
 	return promised.map(result =>
 		isFulfilled(result) ? ok(result.value) : error(result.reason),
 	) as Result<Value>[];
@@ -92,9 +90,7 @@ export function isRejected(value: unknown): value is RejectedPromise {
 
 function isType(value: unknown, type: string): boolean {
 	return (
-		typeof value === 'object' &&
-		value !== null &&
-		(value as PromisesValue<unknown>).status === type
+		typeof value === 'object' && value !== null && (value as PromisesValue<unknown>).status === type
 	);
 }
 

package/types/array/index.d.ts

@@ -11,6 +11,7 @@ export * from './from';
 export * from './get';
 export * from './insert';
 export * from './intersection';
+export * from './move';
 export * from './partition';
 export * from './position';
 export * from './push';

package/types/array/move.d.ts

@@ -0,0 +1,86 @@
+import type { PlainObject } from '../models';
+/**
+ * Move an item _(or array of items)_ to the position of another item _(or array of items)_ within an array
+ *
+ * When moving to the front of the array, the moved items will be placed __before__ the target item. When moving to the back of the array, the moved items will be placed __after__ the target item.
+ *
+ * If either of values are not present in the array, or if they overlap, the array will be returned unchanged
+ * @param array Array to move within
+ * @param from Item or items to move
+ * @param to Item or items to move to
+ * @param key Key to get an item's value for matching
+ * @returns Original array with items moved _(or unchanged if unable to move)_
+ */
+export declare function move<Item extends PlainObject, Key extends keyof Item>(array: Item[], from: Item | Item[], to: Item | Item[], key: Key): Item[];
+/**
+ * Move an item _(or array of items)_ to the position of another item _(or array of items)_ within an array
+ *
+ * When moving to the front of the array, the moved items will be placed __before__ the target item. When moving to the back of the array, the moved items will be placed __after__ the target item.
+ *
+ * If either of values are not present in the array, or if they overlap, the array will be returned unchanged
+ * @param array Array to move within
+ * @param from Item or items to move
+ * @param to Item or items to move to
+ * @param callback Callback to get an item's value for matching
+ * @returns Original array with items moved _(or unchanged if unable to move)_
+ */
+export declare function move<Item>(array: Item[], from: Item | Item[], to: Item | Item[], callback: (item: Item, index: number, array: Item[]) => unknown): Item[];
+/**
+ * Move an item _(or array of items)_ to the position of another item _(or array of items)_ within an array
+ *
+ * When moving to the front of the array, the moved items will be placed __before__ the target item. When moving to the back of the array, the moved items will be placed __after__ the target item.
+ *
+ * If either of values are not present in the array, or if they overlap, the array will be returned unchanged
+ * @param array Array to move within
+ * @param from Item or items to move
+ * @param to Item or items to move to
+ * @returns Original array with items moved _(or unchanged if unable to move)_
+ */
+export declare function move<Item>(array: Item[], from: Item | Item[], to: Item | Item[]): Item[];
+export declare namespace move {
+    var indices: typeof moveIndices;
+    var toIndex: typeof moveToIndex;
+}
+/**
+ * Move an item from one index to another within an array
+ *
+ * If the from index is out of bounds, the array will be returned unchanged
+ * @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)_
+ */
+declare function moveIndices<Item>(array: Item[], from: number, to: number): Item[];
+/**
+ * Move an item _(or array of items)_ to an index within an array
+ *
+ * If the value is not present in the array, or if the index is out of bounds, the array will be returned unchanged
+ * @param array Array to move within
+ * @param value Item or items to move
+ * @param index Index to move to
+ * @param key Key to get an item's value for matching
+ * @returns Original array with items moved _(or unchanged if unable to move)_
+ */
+declare function moveToIndex<Item extends PlainObject, Key extends keyof Item>(array: Item[], value: Item | Item[], index: number, key: Key): Item[];
+/**
+ * Move an item _(or array of items)_ to an index within an array
+ *
+ * If the value is not present in the array, or if the index is out of bounds, the array will be returned unchanged
+ * @param array Array to move within
+ * @param value Item or items to move
+ * @param index Index to move to
+ * @param callback Callback to get an item's value for matching
+ * @returns Original array with items moved _(or unchanged if unable to move)_
+ */
+declare function moveToIndex<Item>(array: Item[], value: Item | Item[], index: number, callback: (item: Item, index: number, array: Item[]) => unknown): Item[];
+/**
+ * Move an item _(or array of items)_ to an index within an array
+ *
+ * If the value is not present in the array, or if the index is out of bounds, the array will be returned unchanged
+ * @param array Array to move within
+ * @param value Item or items to move
+ * @param index Index to move to
+ * @returns Original array with items moved _(or unchanged if unable to move)_
+ */
+declare function moveToIndex<Item>(array: Item[], value: Item | Item[], index: number): Item[];
+export {};

package/types/internal/array/overlap.d.ts

@@ -0,0 +1,11 @@
+type OverlapItem = {
+    array: unknown[];
+    index: number;
+};
+type OverlapResult = {
+    first: OverlapItem;
+    second: OverlapItem;
+    overlap: boolean;
+};
+export declare function arraysOverlap(first: OverlapItem, second: OverlapItem): OverlapResult;
+export {};