feat: add array move util fn

Author: Thanga-Ganapathy

.changeset/honest-pugs-hope.md

@@ -0,0 +1,5 @@
+---
+"@opentf/utils": minor
+---
+
+Added array move utility fn.

.gitignore

@@ -26,4 +26,5 @@ lib
 
 .parcel-cache
 
-play.js
+play.js
+.turbo

README.md

@@ -52,6 +52,7 @@ await sleep(1000); // It suspends the exection for 1 second.
 - [asyncFilter](https://js-utils.pages.dev/Array/asyncFilter)
 - [groupBy](https://js-utils.pages.dev/Array/groupBy)
 - [range](https://js-utils.pages.dev/Array/range)
+- [move](https://js-utils.pages.dev/Array/move)
 
 ### Maths
 

apps/website/docs/Array/move.mdx

@@ -0,0 +1,24 @@
+> It moves an array element from one index position to another.
+
+## Syntax
+
+```ts
+move(arr: T[], from: number, to: number): T[];
+```
+## Usage
+
+```ts
+import { move } from '@opentf/utils';
+
+move([], 0, 1);
+```
+
+## Examples
+
+```ts
+move([1, 2, 3], 0, 2) //=> [2, 3, 1]
+
+move([1, 2, 3], 0, 5) //=> [2, 3, 1]
+
+move([1, 2, 3], 5, 0) //=> [1, 2, 3]
+```

packages/utils/README.md

@@ -52,6 +52,7 @@ await sleep(1000); // It suspends the exection for 1 second.
 - [asyncFilter](https://js-utils.pages.dev/Array/asyncFilter)
 - [groupBy](https://js-utils.pages.dev/Array/groupBy)
 - [range](https://js-utils.pages.dev/Array/range)
+- [move](https://js-utils.pages.dev/Array/move)
 
 ### Maths
 

packages/utils/__tests__/array/move.spec.ts

@@ -0,0 +1,29 @@
+import { move } from '../../src';
+
+describe('Array > move', () => {
+  test('empty array', () => {
+    expect(move([], 0, 1)).toEqual([]);
+  });
+
+  it('returns same ref', () => {
+    const arr = [1, 5, 8];
+    expect(move(arr, 0, 0)).toBe(arr);
+  });
+
+  it('moves within range', () => {
+    expect(move([1, 2, 3], 0, 2)).toEqual([2, 3, 1]);
+  });
+
+  it('moves the element to the last index if to > length', () => {
+    expect(move([1, 2, 3], 0, 5)).toEqual([2, 3, 1]);
+  });
+
+  it('does not move the element', () => {
+    expect(move([1, 2, 3], 5, 0)).toEqual([1, 2, 3]);
+  });
+
+  test('negative index', () => {
+    expect(move([1, 2, 3, 4, 5], 0, -1)).toEqual([2, 3, 4, 1, 5]);
+    expect(move([1, 2, 3, 4, 5], -1, 2)).toEqual([1, 2, 5, 3, 4]);
+  });
+});

packages/utils/src/array/move.ts

@@ -0,0 +1,19 @@
+/**
+ * It moves an array element from one index position to another.
+ *
+ * Note: It mutates the array.
+ *
+ * @example
+ *
+ * move([1, 2, 3], 0, 2) //=> [2, 3, 1]
+ */
+
+export default function move<T>(arr: T[], from: number, to: number): T[] {
+  if (arr.length === 0 || from === to || from >= arr.length) {
+    return arr;
+  }
+
+  arr.splice(to, 0, arr.splice(from, 1)[0]);
+
+  return arr;
+}

packages/utils/src/index.ts

@@ -11,6 +11,7 @@ export { default as arrayDiff } from './array/arrayDiff';
 export { default as range } from './array/range';
 export { default as asyncFilter } from './array/asyncFilter';
 export { default as groupBy } from './array/groupBy';
+export { default as move } from './array/move';
 
 // Maths
 export { default as percentage } from './maths/percentage';