feat(utils): excludeElements (#182)

* feat: exclude 메서드 구현

* test: exclude 메서드의 테스트코드 작성

* fix: 메서드 이름을 exclude -> excludeElements로 변경

* fix: 컴포넌트명 변경에 따른 폴더명 수정

* fix: excludeElements가 2개의 제네릭을 사용할 수 있도록 매개변수 타입 수정

* test: excludeElements 로직 수정에 의한 테스트 코드 수정

* docs: excludeElements 문서 작성

docs/docs/utils/array/excludeElements.md

@@ -0,0 +1,64 @@
+# excludeElements
+
+1번째 매개변수로 전달된 배열에서, 2번째 이후의 값을 제외하여 반환하는 유틸 함수입니다.
+
+원시값의 경우 명확한 타입체크를 위해 `as const` 사용을 권장드립니다.  
+원시값이 아닌 `object` 타입인 경우 `JSON.stringify`를 통해 동등성을 비교합니다.
+
+
+<br />
+
+## Code
+[🔗 실제 구현 코드 확인](https://github.com/modern-agile-team/modern-kit/blob/main/packages/utils/src/array/excludeElements/index.ts)
+
+## Interface
+```ts title="typescript"
+const excludeElements = <E, U extends E>(
+  array: ReadonlyArray<E> | Array<E>,
+  ...args: ReadonlyArray<U> | Array<U>
+) => Array<E>
+```
+
+## Usage
+```ts title="typescript"
+import { excludeElements } from '@modern-kit/utils';
+
+const array = [1, 2, 3, 4];
+const excluded = [3, 4]
+
+excludeElements(array, ...excluded); // [1, 2]
+```
+
+```ts title="typescript"
+import { excludeElements } from '@modern-kit/utils';
+
+const array = ['a', 'b', 'c', 'd'];
+const excluded = ['a']
+
+excludeElements(array, ...excluded); // ['b', 'c', 'd']
+```
+
+```ts title="typescript"
+import { excludeElements } from '@modern-kit/utils';
+
+const array = [[3, 'a'], [4, 'b']];
+const excluded = [[3, 'a']]
+
+excludeElements(array, ...excluded); // [4, 'b']
+```
+
+```ts title="typescript"
+import { excludeElements } from '@modern-kit/utils';
+
+const array = [
+  { name: 'kim', address: { city: 'Seoul' } },
+  { name: 'lee', address: { city: 'NewYork' } },
+];
+const excluded = [{ name: 'kim', address: { city: 'Seoul' } }];
+
+excludeElements(array, ...excluded); // { name: 'lee', address: { city: 'NewYork' } }
+```
+
+## Caveats
+
+- 2번째 이후의 매개변수의 형태는 `이터러블` 혹은 `리스트(1, 2, 3..)` 형태입니다.

packages/utils/src/array/excludeElements/excludeElements.spec.ts

@@ -0,0 +1,44 @@
+import { excludeElements } from '.';
+
+describe('excludeElements', () => {
+  it('filter after second parameter values from first parameter.', () => {
+    const array = [1, 2, 3, 4, 5, 6];
+    const excludedElements = [1, 3];
+
+    expect(excludeElements(array, ...excludedElements)).toEqual([2, 4, 5, 6]);
+  });
+
+  it('should filter boolean.', () => {
+    const array = [true, false, false, true];
+    const excludedElements = [true];
+
+    expect(excludeElements(array, ...excludedElements)).toEqual([false, false]);
+  });
+
+  it('should filter string.', () => {
+    const array = ['name', 'value', 'value', 'key'];
+    const excludedElements = ['value'];
+
+    expect(excludeElements(array, ...excludedElements)).toEqual([
+      'name',
+      'key',
+    ]);
+  });
+
+  it('should filter object.', () => {
+    const excludePerson = { name: 'kim', address: { city: 'Seoul' } };
+    const notExcludePerson = { name: 'lee', address: { city: 'NewYork' } };
+
+    const people = [excludePerson];
+
+    expect(excludeElements(people, excludePerson)).toEqual([]);
+    expect(excludeElements(people, notExcludePerson)).toEqual(people);
+  });
+
+  it('should filter tuple.', () => {
+    const array = [[3, 'a']];
+    const excludedElements = [3, 'a'];
+
+    expect(excludeElements(array, excludedElements)).toEqual([]);
+  });
+});

packages/utils/src/array/excludeElements/index.ts

@@ -0,0 +1,8 @@
+export const excludeElements = <E, U extends E>(
+  array: ReadonlyArray<E> | Array<E>,
+  ...args: ReadonlyArray<U> | Array<U>
+): Array<E> => {
+  const excludeSet = new Set(args.map((arg) => JSON.stringify(arg)));
+
+  return array.filter((element) => !excludeSet.has(JSON.stringify(element)));
+};

packages/utils/src/array/index.ts

@@ -1 +1,2 @@
 export * from './countOccurrencesInArray';
+export * from './excludeElements';