docs: Add missing docs

.scripts/docs/deno.json

@@ -1,9 +1,9 @@
 {
   "imports": {
     "@deno/doc": "jsr:@deno/doc@^0.148.0",
-    "@es-toolkit/es-toolkit": "jsr:@es-toolkit/es-toolkit@^1.17.0",
+    "@es-toolkit/es-toolkit": "jsr:@es-toolkit/es-toolkit@^1.19.0",
     "@std/dotenv": "jsr:@std/dotenv@^0.225.2",
     "clipanion": "npm:clipanion@^3.2.1",
     "openai": "npm:openai@^4.58.1"
   }
-}
+}

.scripts/docs/deno.lock

@@ -6,7 +6,7 @@
       "jsr:@deno/doc@^0.148.0": "jsr:@deno/doc@0.148.0",
       "jsr:@deno/graph@0.82": "jsr:@deno/graph@0.82.1",
       "jsr:@deno/graph@^0.73.1": "jsr:@deno/graph@0.73.1",
-      "jsr:@es-toolkit/es-toolkit@^1.17.0": "jsr:@es-toolkit/es-toolkit@1.17.0",
+      "jsr:@es-toolkit/es-toolkit@^1.19.0": "jsr:@es-toolkit/es-toolkit@1.19.0",
       "jsr:@std/assert@^0.223.0": "jsr:@std/assert@0.223.0",
       "jsr:@std/bytes@^0.223.0": "jsr:@std/bytes@0.223.0",
       "jsr:@std/dotenv@^0.225.2": "jsr:@std/dotenv@0.225.2",
@@ -42,8 +42,8 @@
       "@deno/graph@0.82.1": {
         "integrity": "ce5ccb325b1c84f65000eddb6d1922cfb43545beabd4f395648ad541c1cd987c"
       },
-      "@es-toolkit/es-toolkit@1.17.0": {
-        "integrity": "dfbefedc4c821c97dbbfe33a716b4b34d486f2c214dce3b7c3f8161344d2e72a"
+      "@es-toolkit/es-toolkit@1.19.0": {
+        "integrity": "d792dcfe879d6b3a0586026f3e2f887074254418b5358a767506285c21af09dd"
       },
       "@std/assert@0.223.0": {
         "integrity": "eb8d6d879d76e1cc431205bd346ed4d88dc051c6366365b1af47034b0670be24"
@@ -316,7 +316,7 @@
   "workspace": {
     "dependencies": [
       "jsr:@deno/doc@^0.148.0",
-      "jsr:@es-toolkit/es-toolkit@^1.17.0",
+      "jsr:@es-toolkit/es-toolkit@^1.19.0",
       "jsr:@std/dotenv@^0.225.2",
       "npm:clipanion@^3.2.1",
       "npm:openai@^4.58.1"

benchmarks/performance/isNumber.bench.ts

@@ -1,5 +1,5 @@
 import { bench, describe } from 'vitest';
-import { isNumber as isNumberToolkit } from 'es-toolkit';
+import { isNumber as isNumberToolkit } from 'es-toolkit/compat';
 import { isNumber as isNumberLodash } from 'lodash';
 
 describe('isNumber', () => {

docs/ja/reference/compat/predicate/isNaN.md

@@ -0,0 +1,33 @@
+# isNaN
+
+::: info
+この関数は互換性のために `es-toolkit/compat` からのみインポートできます。代替可能なネイティブ JavaScript API が存在するか、まだ十分に最適化されていないためです。
+
+`es-toolkit/compat` からこの関数をインポートすると、[lodash と完全に同じように動作](../../../compatibility.md)します。
+:::
+
+値が`NaN`かどうかを確認します。
+
+## インターフェース
+
+```typescript
+function isNaN(value: unknown): value is typeof NaN;
+```
+
+### パラメータ
+
+- `value` (`unknown`): 確認する値。
+
+### 戻り値
+
+(`value is typeof NaN`): 値がNaNの場合は`true`、それ以外の場合は`false`。
+数値配列。
+
+## 例
+
+```typescript
+isNaN(NaN); // true
+isNaN(0); // false
+isNaN('NaN'); // false
+isNaN(undefined); // false
+```

docs/ja/reference/compat/predicate/isNumber.md

@@ -0,0 +1,37 @@
+# isNumber
+
+::: info
+この関数は互換性のために `es-toolkit/compat` からのみインポートできます。代替可能なネイティブ JavaScript API があるか、まだ十分に最適化されていないためです。
+
+`es-toolkit/compat` からこの関数をインポートすると、[lodash と完全に同じように動作](../../../compatibility.md)します。
+:::
+
+与えられた値が数値かどうかをチェックします。
+
+この関数はTypeScriptで型述語としても機能し、引数の型を `number` に狭めます。
+
+## インターフェース
+
+```typescript
+function isNumber(value?: unknown): value is number;
+```
+
+### パラメータ
+
+- `value` (`unknown`): 数値かどうかをチェックする値。
+
+### 戻り値
+
+(`value is number`): `value` が数値の場合は `true` を、それ以外の場合は `false` を返します。
+
+## 例
+
+```typescript
+const value1 = 123;
+const value2 = 'abc';
+const value3 = true;
+
+console.log(isNumber(value1)); // true
+console.log(isNumber(value2)); // false
+console.log(isNumber(value3)); // false
+```

docs/ko/reference/compat/predicate/isNaN.md

@@ -1,6 +1,12 @@
 # isNaN
 
-주어진 값이 NaN인지 확인해요.
+::: info
+이 함수는 호환성을 위한 `es-toolkit/compat` 에서만 가져올 수 있어요. 대체할 수 있는 네이티브 JavaScript API가 있거나, 아직 충분히 최적화되지 않았기 때문이에요.
+
+`es-toolkit/compat`에서 이 함수를 가져오면, [lodash와 완전히 똑같이 동작](../../../compatibility.md)해요.
+:::
+
+주어진 값이 `NaN`인지 확인해요.
 
 TypeScript의 타입 가드로 사용할 수 있어요. 파라미터로 주어진 값의 타입을 `NaN`으로 좁혀요.
 

docs/ko/reference/compat/predicate/isNumber.md

@@ -0,0 +1,37 @@
+# isNumber
+
+::: info
+이 함수는 호환성을 위한 `es-toolkit/compat` 에서만 가져올 수 있어요. 대체할 수 있는 네이티브 JavaScript API가 있거나, 아직 충분히 최적화되지 않았기 때문이에요.
+
+`es-toolkit/compat`에서 이 함수를 가져오면, [lodash와 완전히 똑같이 동작](../../../compatibility.md)해요.
+:::
+
+주어진 값이 숫자인지 확인해요.
+
+TypeScript의 타입 가드로 사용할 수 있어요. 파라미터로 주어진 값의 타입을 `number`으로 좁혀요.
+
+## 인터페이스
+
+```typescript
+function isNumber(value?: unknown): value is number;
+```
+
+### 파라미터
+
+- `value` (`unknown`): 숫자인지 확인할 값.
+
+### 반환 값
+
+(`value is number`): `값`이 숫자이면 `true`, 그렇지 않으면 `false`.
+
+## 예시
+
+```typescript
+const value1 = 123;
+const value2 = 'abc';
+const value3 = true;
+
+console.log(isNumber(value1)); // true
+console.log(isNumber(value2)); // false
+console.log(isNumber(value3)); // false
+```

docs/reference/compat/predicate/isNaN.md

@@ -1,8 +1,14 @@
 # isNaN
 
-Check if the given value is NaN.
+::: 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.
 
-This function can also serve as a type predicate in TypeScript, narrowing the type of the argument to NaN.
+When imported from `es-toolkit/compat`, it behaves exactly like lodash and provides the same functionalities, as detailed [here](../../../compatibility.md).
+:::
+
+Check if the given value is `NaN`.
+
+This function can also serve as a type predicate in TypeScript, narrowing the type of the argument to `NaN`.
 
 ## Signature
 

docs/reference/compat/predicate/isNumber.md

@@ -0,0 +1,37 @@
+# isNumber
+
+::: 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).
+:::
+
+Checks if a given value is a number.
+
+This function can also serve as a type predicate in TypeScript, narrowing the type of the argument to `number`.
+
+## Signature
+
+```typescript
+function isNumber(value?: unknown): value is number;
+```
+
+### Parameters
+
+- `value` (`unknown`): The value to check if it is a number.
+
+### Returns
+
+(`value is number`): Returns `true` if `value` is a number, else `false`.
+
+## Examples
+
+```typescript
+const value1 = 123;
+const value2 = 'abc';
+const value3 = true;
+
+console.log(isNumber(value1)); // true
+console.log(isNumber(value2)); // false
+console.log(isNumber(value3)); // false
+```

docs/zh_hans/reference/compat/predicate/isNaN.md

@@ -0,0 +1,32 @@
+# isNaN
+
+::: info
+出于兼容性原因，此函数仅在 `es-toolkit/compat` 中提供。它可能具有替代的原生 JavaScript API，或者尚未完全优化。
+
+从 `es-toolkit/compat` 导入时，它的行为与 lodash 完全一致，并提供相同的功能，详情请见 [这里](../../../compatibility.md)。
+:::
+
+检查值是否为`NaN`。
+
+## 签名
+
+```typescript
+function isNaN(value: unknown): value is typeof NaN;
+```
+
+### 参数
+
+- `value` (`unknown`): 要检查的值。
+
+### 返回值
+
+(`value is typeof NaN`): 如果值是NaN，则为`true`，否则为`false`。
+
+## 示例
+
+```typescript
+isNaN(NaN); // true
+isNaN(0); // false
+isNaN('NaN'); // false
+isNaN(undefined); // false
+```

docs/zh_hans/reference/compat/predicate/isNumber.md

@@ -0,0 +1,37 @@
+# isNumber
+
+::: info
+出于兼容性原因，此函数仅在 `es-toolkit/compat` 中提供。它可能具有替代的原生 JavaScript API，或者尚未完全优化。
+
+从 `es-toolkit/compat` 导入时，它的行为与 lodash 完全一致，并提供相同的功能，详情请见 [这里](../../../compatibility.md)。
+:::
+
+检查给定值是否为数字。
+
+此函数还可以作为TypeScript中的类型谓词，将参数的类型缩小为`number`。
+
+## 签名
+
+```typescript
+function isNumber(value?: unknown): value is number;
+```
+
+### 参数
+
+- `value` (`unknown`): 要检查是否为数字的值。
+
+### 返回值
+
+(`value is number`): 如果`value`是数字，则返回`true`，否则返回`false`。
+
+## 示例
+
+```typescript
+const value1 = 123;
+const value2 = 'abc';
+const value3 = true;
+
+console.log(isNumber(value1)); // true
+console.log(isNumber(value2)); // false
+console.log(isNumber(value3)); // false
+```

src/array/initial.ts

@@ -54,6 +54,19 @@ export function initial<T, U>(arr: readonly [...T[], U]): T[];
  */
 export function initial<T>(arr: readonly T[]): T[];
 
+/**
+ * Returns a new array containing all elements except the last one from the input array.
+ * If the input array is empty or has only one element, the function returns an empty array.
+ *
+ * @template T The type of elements in the array.
+ * @param {T[]} arr - The input array.
+ * @returns {T[]} A new array containing all but the last element of the input array.
+ *
+ * @example
+ * const arr = [1, 2, 3, 4];
+ * const result = initial(arr);
+ * // result will be [1, 2, 3]
+ */
 export function initial<T>(arr: readonly T[]): T[] {
   return arr.slice(0, -1);
 }

src/compat/array/findLastIndex.ts

@@ -78,10 +78,8 @@ export function findLastIndex<T>(arr: readonly T[], propertyToCheck: string, fro
  * Finds the index of the first item in an array that has a specific property, where the property name is provided as a string.
  *
  * @template T
- * @param {readonly T[]} arr - The array to search through.
- * @param {string} propertyToCheck - The property name to check.
- * @param source
- * @param doesMatch
+ * @param {T[]} arr - The array to search through.
+ * @param {((item: T, index: number, arr: any) => unknown) | Partial<T> | [keyof T, unknown] | string} doesMatch - The property name to check.
  * @param {number} [fromIndex=arr.length - 1] - The index to start the search from, defaults to the last index of the array.
  * @returns {number} - The index of the first item that has the specified property, or `undefined` if no match is found.
  *
@@ -92,34 +90,34 @@ export function findLastIndex<T>(arr: readonly T[], propertyToCheck: string, fro
  * console.log(result); // 1
  */
 export function findLastIndex<T>(
-  source: readonly T[],
+  arr: readonly T[],
   doesMatch: ((item: T, index: number, arr: any) => unknown) | Partial<T> | [keyof T, unknown] | string,
-  fromIndex: number = source.length - 1
+  fromIndex: number = arr.length - 1
 ): number {
   if (fromIndex < 0) {
-    fromIndex = Math.max(source.length + fromIndex, 0);
+    fromIndex = Math.max(arr.length + fromIndex, 0);
   } else {
-    fromIndex = Math.min(fromIndex, source.length - 1);
+    fromIndex = Math.min(fromIndex, arr.length - 1);
   }
 
-  source = source.slice(0, fromIndex + 1);
+  arr = arr.slice(0, fromIndex + 1);
 
   switch (typeof doesMatch) {
     case 'function': {
-      return source.findLastIndex(doesMatch);
+      return arr.findLastIndex(doesMatch);
     }
     case 'object': {
       if (Array.isArray(doesMatch) && doesMatch.length === 2) {
         const key = doesMatch[0];
         const value = doesMatch[1];
 
-        return source.findLastIndex(matchesProperty(key, value));
+        return arr.findLastIndex(matchesProperty(key, value));
       } else {
-        return source.findLastIndex(matches(doesMatch));
+        return arr.findLastIndex(matches(doesMatch));
       }
     }
     case 'string': {
-      return source.findLastIndex(property(doesMatch));
+      return arr.findLastIndex(property(doesMatch));
     }
   }
 }

src/compat/array/some.ts

@@ -75,7 +75,6 @@ export function some<T>(arr: readonly T[], doesMatch: Partial<T>): boolean;
  * @param {T[]} arr The array to iterate over.
  * @param {((item: T, index: number, arr: any) => unknown) | Partial<T> | [keyof T, unknown] | string} [predicate=identity] The function invoked per iteration.
  * If a property name or an object is provided it will be used to create a predicate function.
- * @param guard
  * @returns {boolean} Returns `true` if any element passes the predicate check, else `false`.
  *
  * @example
@@ -105,7 +104,6 @@ export function some<T>(
  * @param {T[]} arr The array to iterate over.
  * @param {((item: T, index: number, arr: any) => unknown) | Partial<T> | [keyof T, unknown] | string} [predicate=identity] The function invoked per iteration.
  * If a property name or an object is provided it will be used to create a predicate function.
- * @param guard
  * @returns {boolean} Returns `true` if any element passes the predicate check, else `false`.
  *
  * @example

src/compat/function/throttle.ts

@@ -19,6 +19,36 @@ interface ThrottleOptions {
   trailing?: boolean;
 }
 
+/**
+ * Creates a throttled function that only invokes the provided function at most once
+ * per every `throttleMs` milliseconds. Subsequent calls to the throttled function
+ * within the wait time will not trigger the execution of the original function.
+ *
+ * @template F - The type of function.
+ * @param {F} func - The function to throttle.
+ * @param {number} throttleMs - The number of milliseconds to throttle executions to.
+ * @param {ThrottleOptions} options - The options object
+ * @param {AbortSignal} options.signal - An optional AbortSignal to cancel the throttled function.
+ * @param {boolean} options.leading - If `true`, the function will be invoked on the leading edge of the timeout.
+ * @param {boolean} options.trailing - If `true`, the function will be invoked on the trailing edge of the timeout.
+ * @returns {(...args: Parameters<F>) => void} A new throttled function that accepts the same parameters as the original function.
+ *
+ * @example
+ * const throttledFunction = throttle(() => {
+ *   console.log('Function executed');
+ * }, 1000);
+ *
+ * // Will log 'Function executed' immediately
+ * throttledFunction();
+ *
+ * // Will not log anything as it is within the throttle time
+ * throttledFunction();
+ *
+ * // After 1 second
+ * setTimeout(() => {
+ *   throttledFunction(); // Will log 'Function executed'
+ * }, 1000);
+ */
 export function throttle<F extends (...args: any[]) => any>(
   func: F,
   throttleMs: number = 0,

src/compat/index.ts

@@ -89,6 +89,8 @@ export { conforms } from './predicate/conforms.ts';
 export { conformsTo } from './predicate/conformsTo.ts';
 export { isInteger } from './predicate/isInteger.ts';
 export { isSafeInteger } from './predicate/isSafeInteger.ts';
+export { isNumber } from './predicate/isNumber.ts';
+export { isNaN } from './predicate/isNaN.ts';
 
 export { camelCase } from './string/camelCase.ts';
 export { kebabCase } from './string/kebabCase.ts';

src/compat/object/pick.ts

@@ -63,7 +63,7 @@ export function pick<
  *
  * @template T - The type of object.
  * @param {T | null | undefined} obj - The object to pick keys from.
- * @param {...any} keysArr
+ * @param {...any} keysArr - An array of keys to be picked from the object. received keysgoes through a flattening process before being used.
  * @param {PropertyKey | PropertyKey[] | ProperyKey[][]}} keys - An array of keys to be picked from the object. received keysgoes through a flattening process before being used.
  * @returns {Partial<T, K>} A new object with the specified keys picked.
  *

src/compat/predicate/isNumber.spec.ts

@@ -0,0 +1,57 @@
+import { describe, it, expect } from 'vitest';
+import { isNumber } from './isNumber';
+import { falsey } from '../_internal/falsey';
+import { args } from '../_internal/args';
+import { slice } from '../_internal/slice';
+import { symbol } from '../_internal/symbol';
+
+describe('isNumber', () => {
+  it('should return true for number values', () => {
+    expect(isNumber(0)).toBe(true);
+    expect(isNumber(1)).toBe(true);
+    expect(isNumber(-1)).toBe(true);
+    expect(isNumber(1.5)).toBe(true);
+    expect(isNumber(Infinity)).toBe(true);
+    expect(isNumber(-Infinity)).toBe(true);
+  });
+
+  it('should return false for non-number values', () => {
+    expect(isNumber('123')).toBe(false);
+    expect(isNumber(true)).toBe(false);
+    expect(isNumber(false)).toBe(false);
+    expect(isNumber(null)).toBe(false);
+    expect(isNumber(undefined)).toBe(false);
+    expect(isNumber({})).toBe(false);
+    expect(isNumber([])).toBe(false);
+    expect(isNumber(() => {})).toBe(false);
+  });
+
+  it('should return true for NaN', () => {
+    expect(isNumber(NaN)).toBe(true);
+  });
+
+  it('should return `true` for numbers', () => {
+    expect(isNumber(0)).toBe(true);
+    expect(isNumber(Object(0))).toBe(true);
+    expect(isNumber(NaN)).toBe(true);
+  });
+
+  it('should return `false` for non-numbers', () => {
+    const expected = falsey.map(value => typeof value === 'number');
+
+    const actual = falsey.map((value, index) => (index ? isNumber(value) : isNumber()));
+
+    expect(actual).toEqual(expected);
+
+    expect(isNumber(args)).toBe(false);
+    expect(isNumber([1, 2, 3])).toBe(false);
+    expect(isNumber(true)).toBe(false);
+    expect(isNumber(new Date())).toBe(false);
+    expect(isNumber(new Error())).toBe(false);
+    expect(isNumber(slice)).toBe(false);
+    expect(isNumber({ a: 1 })).toBe(false);
+    expect(isNumber(/x/)).toBe(false);
+    expect(isNumber('a')).toBe(false);
+    expect(isNumber(symbol)).toBe(false);
+  });
+});

src/compat/predicate/isNumber.ts

@@ -1,3 +1,5 @@
+import { getTag } from '../_internal/getTag';
+
 /**
  * Checks if a given value is a number.
  *
@@ -15,6 +17,10 @@
  * console.log(isNumber(value2)); // false
  * console.log(isNumber(value3)); // false
  */
-export function isNumber(value: unknown): value is number {
+export function isNumber(value?: unknown): value is number {
+  if (typeof value === 'object' && value != null && getTag(value) === '[object Number]') {
+    return true;
+  }
+
   return typeof value === 'number';
 }

src/compat/string/trim.ts

@@ -5,7 +5,6 @@ import { trim as trimToolkit } from '../../string/trim.ts';
  *
  * @param {string} str - The string from which leading and trailing characters will be trimmed.
  * @param {string | string[]} chars - The character(s) to remove from the end of the string. Defaults to `" "`.
- * @param guard
  * @returns {string} - The resulting string after the specified leading and trailing characters have been removed.
  *
  * @example

src/compat/string/trimEnd.ts

@@ -5,7 +5,6 @@ import { trimEnd as trimEndToolkit } from '../../string/trimEnd.ts';
  *
  * @param {string} str - The string from which trailing characters will be trimmed.
  * @param {string | string[]} chars - The character(s) to remove from the end of the string. Defaults to `" "`.
- * @param guard
  * @returns {string} - The resulting string after the specified trailing character has been removed.
  *
  * @example

src/compat/string/trimStart.ts

@@ -5,7 +5,6 @@ import { trimStart as trimStartToolkit } from '../../string/trimStart.ts';
  *
  * @param {string} str - The string from which leading characters will be trimmed.
  * @param {string | string[]} chars - The character(s) to remove from the end of the string. Defaults to `" "`.
- * @param guard
  * @returns {string} - The resulting string after the specified leading character has been removed.
  *
  * @example

src/predicate/index.ts

@@ -1,6 +1,5 @@
 export { isDate } from './isDate.ts';
 export { isEqual } from './isEqual.ts';
-export { isNaN } from './isNaN.ts';
 export { isNil } from './isNil.ts';
 export { isNotNil } from './isNotNil.ts';
 export { isNull } from './isNull.ts';
@@ -16,4 +15,3 @@ export { isSymbol } from './isSymbol.ts';
 export { isString } from './isString.ts';
 export { isWeakMap } from './isWeakMap.ts';
 export { isWeakSet } from './isWeakSet.ts';
-export { isNumber } from './isNumber.ts';

src/predicate/isNumber.spec.ts

@@ -1,28 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { isNumber } from './isNumber';
-
-describe('isNumber', () => {
-  it('should return true for number values', () => {
-    expect(isNumber(0)).toBe(true);
-    expect(isNumber(1)).toBe(true);
-    expect(isNumber(-1)).toBe(true);
-    expect(isNumber(1.5)).toBe(true);
-    expect(isNumber(Infinity)).toBe(true);
-    expect(isNumber(-Infinity)).toBe(true);
-  });
-
-  it('should return false for non-number values', () => {
-    expect(isNumber('123')).toBe(false);
-    expect(isNumber(true)).toBe(false);
-    expect(isNumber(false)).toBe(false);
-    expect(isNumber(null)).toBe(false);
-    expect(isNumber(undefined)).toBe(false);
-    expect(isNumber({})).toBe(false);
-    expect(isNumber([])).toBe(false);
-    expect(isNumber(() => {})).toBe(false);
-  });
-
-  it('should return true for NaN', () => {
-    expect(isNumber(NaN)).toBe(true);
-  });
-});