feat(isSubsetWith): isSubsetWith implementation

benchmarks/performance/isSubsetWith.bench.ts

@@ -0,0 +1,22 @@
+import { bench, describe } from 'vitest';
+import { isSubsetWith } from 'es-toolkit';
+
+const areItemsEqual = (a: { id: number }, b: { id: number }) => a.id === b.id;
+
+describe('isSubsetWith', () => {
+  const superset = [{ id: 1 }, { id: 2 }, { id: 3 }];
+  const subset = [{ id: 1 }, { id: 2 }];
+
+  bench('es-toolkit/isSubsetWith', () => {
+    isSubsetWith(superset, subset, areItemsEqual);
+  });
+});
+
+describe('isSubsetWith/largeArray', () => {
+  const largeArray = Array.from({ length: 1000000 }, (_, index) => ({ id: index }));
+  const subset = Array.from({ length: 2500 }, (_, index) => ({ id: index * 2 }));
+
+  bench('es-toolkit/isSubsetWith', () => {
+    isSubsetWith(largeArray, subset, areItemsEqual);
+  });
+});

docs/ja/reference/array/isSubsetWith.md

@@ -0,0 +1,39 @@
+# isSubsetWith
+
+`subset` 配列が `superset`配列のサブセットであるかどうかを確認します。
+
+この関数は、2つの配列と比較関数を受け取ります。比較関数は、要素が等しいかどうかを判断するために使用されます。関数は、サブセットのすべての要素がスーパセットに存在する場合に`true`を返し、そうでない場合は`false`を返します。
+
+## インターフェース
+
+```typescript
+function isSubsetWith<T>(superset: T[], subset: T[], areItemsEqual: (x: T, y: T) => boolean): boolean;
+```
+
+### パラメータ
+
+- `superset` (`T[]`): サブセットのすべての要素を含む可能性のある配列です。
+- `subset` (`T[]`): スーパーセット配列に含まれているかどうかを比較する配列です。
+- `areItemsEqual` (`(x: T, y: T) => boolean`): 2つの要素が等しいかどうかを判定する関数。
+
+### 戻り値
+
+(`boolean`): `subset` 配列が `superset` 配列にすべて含まれている場合は `true` を返します。
+
+## 例
+
+```typescript
+const superset = [{ id: 1 }, { id: 2 }, { id: 3 }];
+const subset = [{ id: 2 }, { id: 1 }];
+const areItemsEqual = (a, b) => a.id === b.id;
+
+isSubsetWith(superset1, subset1, areItemsEqual);
+// true を返します。
+
+const superset = [{ id: 1 }, { id: 2 }, { id: 3 }];
+const subset = [{ id: 4 }];
+const areItemsEqual = (a, b) => a.id === b.id;
+
+isSubsetWith(superset2, subset2, areItemsEqual);
+// false を返します。
+```

docs/ko/reference/array/isSubsetWith.md

@@ -0,0 +1,39 @@
+# isSubsetWith
+
+`subset` 배열이 `superset` 배열의 하위 집합인지 확인해요.
+
+이 함수는 두 개의 배열과 비교 함수를 받아요. 비교 함수는 요소가 같은지를 판단하는 데 사용돼요. 이 함수는 서브셋의 모든 요소가 슈퍼셋에 존재할 경우 `true`를 반환하고, 그렇지 않으면 `false`를 반환해요.
+
+## 인터페이스
+
+```typescript
+function isSubsetWith<T>(superset: T[], subset: T[], areItemsEqual: (x: T, y: T) => boolean): boolean;
+```
+
+### 파라미터
+
+- `superset` (`T[]`): 하위 집합의 모든 요소를 포함 할 수 있는 배열이에요.
+- `subset` (`T[]`): 상위 집합 배열에 포함되어 있는지 비교 할 배열이에요.
+- `areItemsEqual` (`(x: T, y: T) => boolean`): 두 요소가 동일한지 결정할 함수에요.
+
+### 반환 값
+
+(`boolean`): `subset` 배열이 `superset` 배열에 모두 포함되면 `true`를 반환해요.
+
+## 예시
+
+```typescript
+const superset = [{ id: 1 }, { id: 2 }, { id: 3 }];
+const subset = [{ id: 2 }, { id: 1 }];
+const areItemsEqual = (a, b) => a.id === b.id;
+
+isSubsetWith(superset1, subset1, areItemsEqual);
+// true를 반환해요.
+
+const superset = [{ id: 1 }, { id: 2 }, { id: 3 }];
+const subset = [{ id: 4 }];
+const areItemsEqual = (a, b) => a.id === b.id;
+
+isSubsetWith(superset2, subset2, areItemsEqual);
+// false를 반환해요.
+```

docs/reference/array/isSubsetWith.md

@@ -0,0 +1,39 @@
+# isSubsetWith
+
+Checks if the `subset` array is entirely contained within the `superset` array.
+
+This function takes two arrays and a comparison function as arguments. The comparison function is used to determine whether the elements are equal. The function returns `true` if all elements of the subset exist in the superset, and `false` otherwise.
+
+## Signature
+
+```typescript
+function isSubsetWith<T>(superset: T[], subset: T[], areItemsEqual: (x: T, y: T) => boolean): boolean;
+```
+
+### Parameters
+
+- `superset` (`T[]`): The array that may contain all elements of the subset.
+- `subset` (`T[]`): The array to check against the superset.
+- `areItemsEqual` (`(x: T, y: T) => boolean`): A function to determine if two items are equal.
+
+### Returns
+
+(`boolean`): Returns `true` if all elements of the `subset` are present in the `superset`, otherwise returns `false`.
+
+## Examples
+
+```typescript
+const superset = [{ id: 1 }, { id: 2 }, { id: 3 }];
+const subset = [{ id: 2 }, { id: 1 }];
+const areItemsEqual = (a, b) => a.id === b.id;
+
+isSubsetWith(superset1, subset1, areItemsEqual);
+// Return true
+
+const superset = [{ id: 1 }, { id: 2 }, { id: 3 }];
+const subset = [{ id: 4 }];
+const areItemsEqual = (a, b) => a.id === b.id;
+
+isSubsetWith(superset2, subset2, areItemsEqual);
+// Return false
+```

docs/zh_hans/reference/array/isSubsetWith.md

@@ -0,0 +1,39 @@
+# isSubsetWith
+
+检查 `subset` 数组是否完全包含在 `superset` 数组中。
+
+这个函数接受两个数组和一个比较函数。比较函数用于判断元素是否相等。如果子集的所有元素都存在于超集内，则函数返回`true`，否则返回`false`。
+
+## 签名
+
+```typescript
+function isSubsetWith<T>(superset: T[], subset: T[], areItemsEqual: (x: T, y: T) => boolean): boolean;
+```
+
+### 参数
+
+- `superset` (`T[]`): 可能包含子集所有元素的数组。
+- `subset` (`T[]`): 要与超集进行检查的数组。
+- `areItemsEqual` (`(x: T, y: T) => boolean`): 用于确定两个项是否相等的函数。
+
+### 返回值
+
+(`boolean`): 如果 `subset` 中的所有元素都存在于 `superset` 中，则返回 `true`，否则返回 `false`。
+
+## 示例
+
+```typescript
+const superset = [{ id: 1 }, { id: 2 }, { id: 3 }];
+const subset = [{ id: 2 }, { id: 1 }];
+const areItemsEqual = (a, b) => a.id === b.id;
+
+isSubsetWith(superset1, subset1, areItemsEqual);
+// 返回 true
+
+const superset = [{ id: 1 }, { id: 2 }, { id: 3 }];
+const subset = [{ id: 4 }];
+const areItemsEqual = (a, b) => a.id === b.id;
+
+isSubsetWith(superset2, subset2, areItemsEqual);
+// 返回 false
+```

src/array/index.ts

@@ -22,6 +22,7 @@ export { intersection } from './intersection.ts';
 export { intersectionBy } from './intersectionBy.ts';
 export { intersectionWith } from './intersectionWith.ts';
 export { isSubset } from './isSubset.ts';
+export { isSubsetWith } from './isSubsetWith.ts';
 export { keyBy } from './keyBy.ts';
 export { last } from './last.ts';
 export { maxBy } from './maxBy.ts';

src/array/isSubsetWith.spec.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from 'vitest';
+import { isSubsetWith } from './isSubsetWith';
+
+describe('isSubsetWith', () => {
+  it('should return true if the subset is entirely contained within the superset using the `areItemsEqual` function', () => {
+    const superset = [{ id: 1 }, { id: 2 }, { id: 3 }];
+    const subset = [{ id: 2 }, { id: 1 }];
+    const areItemsEqual = (x: { id: number }, y: { id: number }) => x.id === y.id;
+
+    expect(isSubsetWith(superset, subset, areItemsEqual)).toBeTruthy();
+  });
+
+  it('should return false if the subset is not entirely contained within the superset', () => {
+    const superset = [{ id: 1 }, { id: 2 }, { id: 3 }];
+    const subset = [{ id: 4 }];
+    const areItemsEqual = (x: { id: number }, y: { id: number }) => x.id === y.id;
+
+    expect(isSubsetWith(superset, subset, areItemsEqual)).toBeFalsy();
+  });
+
+  it('should handle empty arrays correctly', () => {
+    const superset = [1, 2, 3];
+    const emptySubset: number[] = [];
+    const areItemsEqual = (x: number, y: number) => x === y;
+
+    expect(isSubsetWith(superset, emptySubset, areItemsEqual)).toBeTruthy();
+
+    const emptySuperset: number[] = [];
+    const subset = [1];
+    expect(isSubsetWith(emptySuperset, subset, areItemsEqual)).toBeFalsy();
+  });
+
+  it('should handle duplicates correctly', () => {
+    const superset = [1, 2, 2, 3];
+    const subset = [2, 2];
+    const areItemsEqual = (x: number, y: number) => x === y;
+
+    expect(isSubsetWith(superset, subset, areItemsEqual)).toBeTruthy();
+
+    const subsetWithExtra = [2, 2, 4];
+    expect(isSubsetWith(superset, subsetWithExtra, areItemsEqual)).toBeFalsy();
+  });
+});

src/array/isSubsetWith.ts

@@ -0,0 +1,39 @@
+/**
+ * Checks if the `subset` array is entirely contained within the `superset` array based on a custom equality function.
+ *
+ * This function takes two arrays and a custom comparison function. It returns a boolean indicating
+ * whether all elements in the subset array are present in the superset array, as determined by the provided
+ * custom equality function.
+ *
+ * @template T - The type of elements contained in the arrays.
+ * @param {T[]} superset - The array that may contain all elements of the subset.
+ * @param {T[]} subset - The array to check against the superset.
+ * @param {(x: T, y: T) => boolean} areItemsEqual - A function to determine if two items are equal.
+ * @returns {boolean} - Returns `true` if all elements of the subset are present in the superset
+ * according to the custom equality function, otherwise returns `false`.
+ *
+ * @example
+ * ```typescript
+ * const superset = [{ id: 1 }, { id: 2 }, { id: 3 }];
+ * const subset = [{ id: 2 }, { id: 1 }];
+ * const areItemsEqual = (a, b) => a.id === b.id;
+ * isSubsetWith(superset, subset, areItemsEqual); // true
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const superset = [{ id: 1 }, { id: 2 }, { id: 3 }];
+ * const subset = [{ id: 4 }];
+ * const areItemsEqual = (a, b) => a.id === b.id;
+ * isSubsetWith(superset, subset, areItemsEqual); // false
+ * ```
+ */
+export function isSubsetWith<T>(
+  superset: readonly T[],
+  subset: readonly T[],
+  areItemsEqual: (x: T, y: T) => boolean
+): boolean {
+  return subset.every(subsetItem => {
+    return superset.some(supersetItem => areItemsEqual(supersetItem, subsetItem));
+  });
+}