feat(multiply): Add multiply to compact layer (#930)

* add multiply

* add benchmark

* add test

* update JSDoc

* add docs

* Add compatibility with lodash

* Add compatibility with lodash

---------

Co-authored-by: Sojin Park <[email protected]>

benchmarks/performance/multiply.bench.ts

@@ -0,0 +1,24 @@
+import { bench, describe } from 'vitest';
+import { multiply as multiplyToolkitCompat_ } from 'es-toolkit/compat';
+import { multiply as multiplyLodash_ } from 'lodash';
+
+const multiplyToolkitCompat = multiplyToolkitCompat_;
+const multiplyLodash = multiplyLodash_;
+
+describe('multiply function benchmark', () => {
+  bench('es-toolkit/compat/multiply', () => {
+    multiplyToolkitCompat(3, 4);
+    multiplyToolkitCompat(-3, -4);
+    multiplyToolkitCompat(NaN, 3);
+    multiplyToolkitCompat(3, NaN);
+    multiplyToolkitCompat(NaN, NaN);
+  });
+
+  bench('lodash/multiply', () => {
+    multiplyLodash(3, 4);
+    multiplyLodash(-3, -4);
+    multiplyLodash(NaN, 3);
+    multiplyLodash(3, NaN);
+    multiplyLodash(NaN, NaN);
+  });
+});

docs/ja/reference/compat/math/multiply.md

@@ -0,0 +1,36 @@
+# multiply
+
+::: info
+この関数は互換性のために `es-toolkit/compat` からのみインポートできます。代替可能なネイティブ JavaScript API があるか、まだ十分に最適化されていないためです。
+
+`es-toolkit/compat` からこの関数をインポートすると、[lodash と完全に同じように動作](../../../compatibility.md)します。
+:::
+
+2つの数値を掛け算します。
+
+どちらかの値が `NaN` の場合、`NaN` を返します。
+
+## インターフェース
+
+```typescript
+function multiply(value: number, other: number): number;
+```
+
+### パラメータ
+
+- `value` (`number`): 掛け算の最初の数値。
+- `other` (`number`): 掛け算の2番目の数値。
+
+### 戻り値
+
+(`number`): `value` と `other` の積を返します。どちらかのパラメータが `NaN` の場合は、`NaN` を返します。
+
+## 例
+
+```typescript
+multiply(2, 3); // 6を返します。
+multiply(2, -3); // -6を返します。
+multiply(NaN, 3); // valueがNaNなのでNaNを返します。
+multiply(2, NaN); // otherがNaNなのでNaNを返します。
+multiply(NaN, NaN); // 両方の引数がNaNなのでNaNを返します。
+```

docs/ko/reference/compat/math/multiply.md

@@ -0,0 +1,36 @@
+# subtract
+
+::: info
+이 함수는 호환성을 위한 `es-toolkit/compat` 에서만 가져올 수 있어요. 대체할 수 있는 네이티브 JavaScript API가 있거나, 아직 충분히 최적화되지 않았기 때문이에요.
+
+`es-toolkit/compat`에서 이 함수를 가져오면, [lodash와 완전히 똑같이 동작](../../../compatibility.md)해요.
+:::
+
+두 숫자를 곱하는 함수예요.
+
+둘 중 하나라도 `NaN`이면 `NaN`을 반환해요.
+
+## 인터페이스
+
+```typescript
+function multiply(value: number, other: number): number;
+```
+
+### 파라미터
+
+- `value` (`number`): 곱셈에서 첫 번째 숫자예요.
+- `other` (`number`): 곱셈에서 두 번째 숫자예요.
+
+### 반환 값
+
+(`number`): `value`와 `other`를 곱한 값을 반환해요. 둘 중 하나라도 `NaN`이면 `NaN`을 반환해요.
+
+## 예시
+
+```typescript
+multiply(2, 3); // 6를 반환해요.
+multiply(2, -3); // -6을 반환해요.
+multiply(NaN, 3); // value가 NaN이기 때문에 NaN을 반환해요.
+multiply(2, NaN); // other이 NaN이기 때문에 NaN을 반환해요.
+multiply(NaN, NaN); // 인수가 모두 NaN이기 때문에 NaN을 반환해요.
+```

docs/reference/compat/math/multiply.md

@@ -0,0 +1,36 @@
+# multiply
+
+::: info
+This function is only available in `es-toolkit/compat` for compatibility reasons. It either has alternative native JavaScript APIs or isn’t fully optimized yet.
+
+When imported from `es-toolkit/compat`, it behaves exactly like lodash and provides the same functionalities, as detailed [here](../../../compatibility.md).
+:::
+
+Multiply two numbers.
+
+If either value is `NaN`, it returns `NaN`.
+
+## Signature
+
+```typescript
+function multiply(value: number, other: number): number;
+```
+
+### Parameters
+
+- `value` (`number`): The first number in a multiplication.
+- `other` (`number`): The second number in a multiplication.
+
+### Returns
+
+(`number`): Returns the product of `value` and `other`. If either parameter is `NaN`, it returns `NaN`.
+
+## Examples
+
+```typescript
+multiply(2, 3); // Returns 6.
+multiply(2, -3); // Returns -6.
+multiply(NaN, 3); // Returns NaN because value is NaN.
+multiply(2, NaN); // Returns NaN because other is NaN.
+multiply(NaN, NaN); // Returns NaN because both arguments are NaN.
+```

docs/zh_hans/reference/compat/math/multiply.md

@@ -0,0 +1,37 @@
+# multiply
+
+::: info
+出于兼容性原因，此函数仅在 `es-toolkit/compat` 中提供。它可能具有替代的原生 JavaScript API，或者尚未完全优化。
+
+从 `es-toolkit/compat` 导入时，它的行为与 lodash 完全一致，并提供相同的功能，详情请见 [这里](../../../compatibility.md)。
+
+:::
+
+将两个数字相乘。
+
+如果任意一个值是 `NaN`，则返回 `NaN`。
+
+## 签名
+
+```typescript
+function multiply(value: number, other: number): number;
+```
+
+### 参数
+
+- `value` (`number`): 乘法中的第一个数字。
+- `other` (`number`): 乘法中的第二个数字。
+
+### 返回值
+
+(`number`): 返回 `value` 和 `other` 的乘积。如果任意一个参数为 `NaN`，则返回 `NaN`。
+
+## 示例
+
+```typescript
+multiply(2, 3); // 返回 6。
+multiply(2, -3); // 返回 -6。
+multiply(NaN, 3); // 返回 NaN，因为 value 是 NaN。
+multiply(2, NaN); // 返回 NaN，因为 other 是 NaN。
+multiply(NaN, NaN); // 返回 NaN，因为两个参数都是 NaN。
+```

src/compat/index.ts

@@ -107,6 +107,7 @@ export { floor } from './math/floor.ts';
 export { inRange } from './math/inRange.ts';
 export { max } from './math/max.ts';
 export { min } from './math/min.ts';
+export { multiply } from './math/multiply.ts';
 export { parseInt } from './math/parseInt.ts';
 export { random } from './math/random.ts';
 export { range } from './math/range.ts';

src/compat/math/multiply.spec.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest';
+import { multiply } from './multiply';
+
+describe('multiply', () => {
+  it('should multiply two numbers', () => {
+    expect(multiply(2, 3)).toBe(6);
+    expect(multiply(2, -3)).toBe(-6);
+    expect(multiply(-2, 3)).toBe(-6);
+    expect(multiply(-2, -3)).toBe(6);
+  });
+
+  it('should return the product of two positive numbers', () => {
+    expect(multiply(2, 4)).toBe(8);
+    expect(multiply(3, 4)).toBe(12);
+  });
+
+  it('should return the product when both numbers are negative', () => {
+    expect(multiply(-2, -4)).toBe(8);
+    expect(multiply(-3, -4)).toBe(12);
+  });
+
+  it('should return the product of a negative and a positive number', () => {
+    expect(multiply(-1, 5)).toBe(-5);
+    expect(multiply(5, -1)).toBe(-5);
+  });
+
+  it('should return NaN if the first value is NaN', () => {
+    expect(multiply(NaN, 3)).toBe(NaN);
+  });
+
+  it('should return NaN if the second value is NaN', () => {
+    expect(multiply(3, NaN)).toBe(NaN);
+  });
+
+  it('should return NaN if both values are NaN', () => {
+    expect(multiply(NaN, NaN)).toBe(NaN);
+  });
+
+  it('should multiply two numbers', () => {
+    expect(multiply(6, 4)).toBe(24);
+    expect(multiply(-6, 4)).toBe(-24);
+    expect(multiply(-6, -4)).toBe(24);
+  });
+
+  it('should coerce arguments to numbers', () => {
+    // eslint-disable-next-line
+    // @ts-ignore
+    expect(multiply('6', '4')).toBe(24);
+    // eslint-disable-next-line
+    // @ts-ignore
+    expect(multiply('x', 'y')).toEqual(NaN);
+  });
+});

src/compat/math/multiply.ts

@@ -0,0 +1,37 @@
+import { toString } from '../util/toString.ts';
+
+/**
+ * Multiply two numbers.
+ *
+ * If either of the numbers is `NaN`, the function returns `NaN`.
+ *
+ * @param {number} value The first number in a multiplication
+ * @param {number} other The second number in a multiplication
+ * @returns {number} The product of value and other
+ *
+ * @example
+ * multiply(2, 3); // => 6
+ * multiply(2, NaN); // => NaN
+ * multiply(NaN, 3); // => NaN
+ * multiply(NaN, NaN); // => NaN
+ */
+
+export function multiply(value: number, other: number): number {
+  if (value === undefined && other === undefined) {
+    return 1;
+  }
+
+  if (value === undefined || other === undefined) {
+    return value || other;
+  }
+
+  if (typeof value === 'string' || typeof other === 'string') {
+    value = toString(value) as any;
+    other = toString(other) as any;
+  } else {
+    value = Number(value);
+    other = Number(other);
+  }
+
+  return value * other;
+}