feat(utils): pull

Signed-off-by: Lexus Drumgold <unicornware@flexdevelopment.llc>

src/utils/__tests__/pull.spec.ts

@@ -0,0 +1,17 @@
+/**
+ * @file Unit Tests - pull
+ * @module tutils/utils/tests/unit/pull
+ */
+
+import testSubject from '../pull'
+
+describe('unit:utils/pull', () => {
+  it('should return array without items in drop', () => {
+    // Arrange
+    const array: number[] = [0, 1, 2, 3, 4, 5]
+    const drop: number[] = [3, 4, 5]
+
+    // Expect
+    expect(testSubject(array, drop, null)).to.deep.equal([0, 1, 2])
+  })
+})

src/utils/index.ts

@@ -48,6 +48,7 @@ export { default as isUndefined } from './is-undefined'
 export { default as isUppercase } from './is-uppercase'
 export { default as lowercase } from './lowercase'
 export { default as passthrough } from './passthrough'
+export { default as pull } from './pull'
 export { default as select } from './select'
 export { default as split } from './split'
 export { default as timeiso } from './timeiso'

src/utils/pull.ts

@@ -0,0 +1,29 @@
+/**
+ * @file Utilities - pull
+ * @module tutils/utils/pull
+ */
+
+import type { Fn, IndexSignature, Nilable, NumberString } from '#src/types'
+import includes from './includes'
+import select from './select'
+
+/**
+ * Removes all items in `drop` from `array` without modifying `array`.
+ *
+ * @template T - Array item type
+ * @template K - Identity key type
+ *
+ * @param {ReadonlyArray<T>} array - Array to evaluate
+ * @param {ReadonlyArray<T>} drop - Items to remove
+ * @param {Nilable<Fn<[T], K>>} [identity] - Identity key function
+ * @return {T[]} New array without items in `drop`
+ */
+function pull<T, K extends IndexSignature = NumberString>(
+  array: readonly T[],
+  drop: readonly T[],
+  identity?: Nilable<Fn<[T], K>>
+): T[] {
+  return select(array, (item: T): boolean => !includes(drop, item, identity))
+}
+
+export default pull