feat(Array): add intersperse fn

.changeset/shy-buttons-pump.md

@@ -0,0 +1,5 @@
+---
+"@opentf/std": minor
+---
+
+Added array intersperse fn.

README.md

@@ -100,6 +100,7 @@ await sleep(1000); // It suspends the exection for 1 second.
 - [drop](https://js-std.pages.dev/Array/drop)
 - [groupBy](https://js-std.pages.dev/Array/groupBy)
 - [intersection](https://js-std.pages.dev/Array/intersection)
+- [intersperse](https://js-std.pages.dev/Array/intersperse)
 - [max](https://js-std.pages.dev/Array/max)
 - [min](https://js-std.pages.dev/Array/min)
 - [move](https://js-std.pages.dev/Array/move)

apps/docs/pages/Array/_meta.json

@@ -10,6 +10,7 @@
   "drop": "drop",
   "groupBy": "groupBy",
   "intersection": "intersection",
+  "intersperse": "intersperse",
   "max": "max",
   "min": "min",
   "move": "move",

apps/docs/pages/Array/intersperse.mdx

@@ -0,0 +1,87 @@
+import { Callout } from "nextra/components";
+import REPL from "../../components/REPL";
+
+> Inserts a separator between the elements of its list argument.
+
+<Callout type="info">
+The list can be an Array or String.
+</Callout>
+
+## Syntax
+
+```ts copy
+import { intersperse } from '@opentf/std';
+
+intersperse(
+  list: string | unknown[] = [],
+  sep: ((index: number) => unknown) | unknown
+): string | unknown[]
+```
+
+## Examples
+
+```ts
+const arr = [1, 2, 3];
+intersperse(arr, '&') // => [1, '&', 2, '&', 3]
+
+const arr = ['Home', 'Menu', 'Sub Menu'];
+intersperse(arr, '>') 
+// => [
+//  'Home',
+//  '>',
+//  'Menu',
+//  '>',
+//  'Sub Menu',
+// ]
+
+intersperse('Hello', '-') // => 'H-e-l-l-o'
+
+const items = [
+  { type: 'div', text: 'Apple' },
+  { type: 'div', text: 'Orange' },
+  { type: 'div', text: 'Mango' },
+];
+intersperse(items, { type: 'br' }) 
+// => [
+//   {
+//     type: 'div',
+//     text: 'Apple',
+//   },
+//   {
+//     type: 'br',
+//   },
+//   {
+//     type: 'div',
+//     text: 'Orange',
+//   },
+//   {
+//     type: 'br',
+//   },
+//   {
+//     type: 'div',
+//     text: 'Mango',
+//   },
+// ]
+
+intersperse(['a', 'b', 'c'], (i) => `<span key="sep-${i}"> , </span>`)
+// [
+//   'a',
+//   '<span key="sep-0"> , </span>',
+//   'b',
+//   '<span key="sep-1"> , </span>',
+//   'c',
+// ]
+```
+
+## Try
+
+<REPL code={`const { intersperse } = require('@opentf/std');
+
+const arr = [1, 2, 3];
+log(intersperse(arr, '&'))
+
+const arr2 = ['Home', 'Menu', 'Sub Menu'];
+log(intersperse(arr2, '>'))
+
+intersperse('Hello', '-')
+`} />

packages/std/README.md

@@ -100,6 +100,7 @@ await sleep(1000); // It suspends the exection for 1 second.
 - [drop](https://js-std.pages.dev/Array/drop)
 - [groupBy](https://js-std.pages.dev/Array/groupBy)
 - [intersection](https://js-std.pages.dev/Array/intersection)
+- [intersperse](https://js-std.pages.dev/Array/intersperse)
 - [max](https://js-std.pages.dev/Array/max)
 - [min](https://js-std.pages.dev/Array/min)
 - [move](https://js-std.pages.dev/Array/move)

packages/std/__tests__/array/intersperse.spec.ts

@@ -0,0 +1,69 @@
+import { intersperse } from '../../src';
+
+describe('Array > intersperse', () => {
+  test('invalid & empty array', () => {
+    expect(intersperse()).toEqual([]);
+    expect(intersperse([])).toEqual([]);
+    expect(intersperse([], '&')).toEqual([]);
+  });
+
+  test('array with string separator', () => {
+    const arr = [1, 2, 3];
+    expect(intersperse(arr, '&')).toEqual([1, '&', 2, '&', 3]);
+  });
+
+  test('array of strings with separator', () => {
+    const arr = ['Home', 'Menu', 'Sub Menu'];
+    expect(intersperse(arr, '>')).toEqual([
+      'Home',
+      '>',
+      'Menu',
+      '>',
+      'Sub Menu',
+    ]);
+  });
+
+  test('string as list', () => {
+    expect(intersperse('Hello', '-')).toEqual('H-e-l-l-o');
+  });
+
+  test('seperator cb fn', () => {
+    expect(
+      intersperse(['a', 'b', 'c'], (i) => `<span key="sep-${i}"> , </span>`)
+    ).toEqual([
+      'a',
+      '<span key="sep-0"> , </span>',
+      'b',
+      '<span key="sep-1"> , </span>',
+      'c',
+    ]);
+  });
+
+  test('React like list', () => {
+    const items = [
+      { type: 'div', text: 'Apple' },
+      { type: 'div', text: 'Orange' },
+      { type: 'div', text: 'Mango' },
+    ];
+    expect(intersperse(items, { type: 'br' })).toEqual([
+      {
+        type: 'div',
+        text: 'Apple',
+      },
+      {
+        type: 'br',
+      },
+      {
+        type: 'div',
+        text: 'Orange',
+      },
+      {
+        type: 'br',
+      },
+      {
+        type: 'div',
+        text: 'Mango',
+      },
+    ]);
+  });
+});

packages/std/src/array/intersperse.ts

@@ -0,0 +1,28 @@
+import isFn from '../types/isFn';
+import isStr from '../types/isStr';
+import drop from './drop';
+
+/**
+ * Inserts a separator between the elements of its list argument.
+ *
+ * @example
+ *
+ * const arr = [1, 2, 3];
+ * intersperse(arr, '*') //=> [1, '*', 2, '*', 3]
+ *
+ * intersperse('Hello', '-') //=> H-e-l-l-o
+ */
+export default function intersperse(
+  list: string | unknown[] = [],
+  sep: ((index: number) => unknown) | unknown
+): string | unknown[] {
+  const a = isStr(list) ? Array.from(list) : list;
+  const res = drop(
+    a.reduce((acc: unknown[], cur, index) => {
+      acc.push(isFn(sep) ? sep(index - 1) : sep, cur);
+      return acc;
+    }, [])
+  );
+
+  return isStr(list) ? (res.join('') as string) : res;
+}

packages/std/src/index.ts

@@ -29,6 +29,7 @@ export { default as min } from './array/min';
 export { default as bounds } from './array/bounds';
 export { default as take } from './array/take';
 export { default as drop } from './array/drop';
+export { default as intersperse } from './array/intersperse';
 
 // Async
 export { default as asyncFilter } from './async/asyncFilter';