es-toolkit 0.0.1 → 1.0.0-dev.19

package/dist/math/clamp.d.ts

@@ -1,11 +1,19 @@
 /**
- * @name clamp
- * @description Checks if `value` is within the bounds, if not return the closest bound (bound1: min, bound2: max)
- * function clamp(value: number, bound1: number, bound2?: number): number
+ * Clamps a number within the inclusive lower and upper bounds.
+ *
+ * This function takes a number and two bounds, and returns the number clamped within the specified bounds.
+ * If only one bound is provided, it returns the minimum of the value and the bound.
+ *
+ * @param {number} value - The number to clamp.
+ * @param {number} minimum - The minimum bound to clamp the number.
+ * @param {number} maximum - The maximum bound to clamp the number.
+ * @returns {number} The clamped number within the specified bounds.
+ *
  * @example
- * clamp(3, 1) // 3
- * clamp(3, 1, 5) // 3
- * clamp(3, 5) // 5
- * clamp(7, 3, 5) // 5
+ *  * const result1 = clamp(10, 5); // result1 will be 5, as 10 is clamped to the bound 5
+ * const result2 = clamp(10, 5, 15); // result2 will be 10, as it is within the bounds 5 and 15
+ * const result3 = clamp(2, 5, 15); // result3 will be 5, as 2 is clamped to the lower bound 5
+ * const result4 = clamp(20, 5, 15); // result4 will be 15, as 20 is clamped to the upper bound 15
  */
-export declare function clamp(value: number, bound1: number, bound2?: number): number;
+export declare function clamp(value: number, maximum: number): number;
+export declare function clamp(value: number, minimum: number, maximum: number): number;

package/dist/math/index.js

@@ -3,15 +3,23 @@
 Object.defineProperty(exports, '__esModule', { value: true });
 
 /**
- * @name clamp
- * @description Checks if `value` is within the bounds, if not return the closest bound (bound1: min, bound2: max)
- * function clamp(value: number, bound1: number, bound2?: number): number
+ * Clamps a number within the inclusive lower and upper bounds.
+ *
+ * This function takes a number and two bounds, and returns the number clamped within the specified bounds.
+ * If only one bound is provided, it returns the minimum of the value and the bound.
+ *
+ * @param {number} value - The number to clamp.
+ * @param {number} minimum - The minimum bound to clamp the number.
+ * @param {number} maximum - The maximum bound to clamp the number.
+ * @returns {number} The clamped number within the specified bounds.
+ *
  * @example
- * clamp(3, 1) // 3
- * clamp(3, 1, 5) // 3
- * clamp(3, 5) // 5
- * clamp(7, 3, 5) // 5
+ *  * const result1 = clamp(10, 5); // result1 will be 5, as 10 is clamped to the bound 5
+ * const result2 = clamp(10, 5, 15); // result2 will be 10, as it is within the bounds 5 and 15
+ * const result3 = clamp(2, 5, 15); // result3 will be 5, as 2 is clamped to the lower bound 5
+ * const result4 = clamp(20, 5, 15); // result4 will be 15, as 20 is clamped to the upper bound 15
  */
+
 function clamp(value, bound1, bound2) {
   if (bound2 == null) {
     return Math.min(value, bound1);
@@ -20,16 +28,19 @@ function clamp(value, bound1, bound2) {
 }
 
 /**
- * @name round
- * @description Rounds given number to given precision
- * ```typescript
- * function round(value: number, precision: number = 0): number
- * ```
+ * Rounds a number to a specified precision.
  * 
+ * This function takes a number and an optional precision value, and returns the number rounded 
+ * to the specified number of decimal places.
+ *
+ * @param {number} value - The number to round.
+ * @param {number} [precision=0] - The number of decimal places to round to. Defaults to 0.
+ * @returns {number} The rounded number.
+ *
  * @example
- * round(1.2) === 1
- * round(3.9) === 4
- * round(8.5) === 9
+ *  * const result1 = round(1.2345); // result1 will be 1
+ * const result2 = round(1.2345, 2); // result2 will be 1.23
+ * const result3 = round(1.2345, 3); // result3 will be 1.235
  */
 function round(value) {
   var precision = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 0;
@@ -37,25 +48,99 @@ function round(value) {
   return Math.round(value * multiplier) / multiplier;
 }
 
+function _unsupportedIterableToArray(o, minLen) {
+  if (!o) return;
+  if (typeof o === "string") return _arrayLikeToArray(o, minLen);
+  var n = Object.prototype.toString.call(o).slice(8, -1);
+  if (n === "Object" && o.constructor) n = o.constructor.name;
+  if (n === "Map" || n === "Set") return Array.from(o);
+  if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _arrayLikeToArray(o, minLen);
+}
+function _arrayLikeToArray(arr, len) {
+  if (len == null || len > arr.length) len = arr.length;
+  for (var i = 0, arr2 = new Array(len); i < len; i++) arr2[i] = arr[i];
+  return arr2;
+}
+function _createForOfIteratorHelper(o, allowArrayLike) {
+  var it = typeof Symbol !== "undefined" && o[Symbol.iterator] || o["@@iterator"];
+  if (!it) {
+    if (Array.isArray(o) || (it = _unsupportedIterableToArray(o)) || allowArrayLike && o && typeof o.length === "number") {
+      if (it) o = it;
+      var i = 0;
+      var F = function () {};
+      return {
+        s: F,
+        n: function () {
+          if (i >= o.length) return {
+            done: true
+          };
+          return {
+            done: false,
+            value: o[i++]
+          };
+        },
+        e: function (e) {
+          throw e;
+        },
+        f: F
+      };
+    }
+    throw new TypeError("Invalid attempt to iterate non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
+  }
+  var normalCompletion = true,
+    didErr = false,
+    err;
+  return {
+    s: function () {
+      it = it.call(o);
+    },
+    n: function () {
+      var step = it.next();
+      normalCompletion = step.done;
+      return step;
+    },
+    e: function (e) {
+      didErr = true;
+      err = e;
+    },
+    f: function () {
+      try {
+        if (!normalCompletion && it.return != null) it.return();
+      } finally {
+        if (didErr) throw err;
+      }
+    }
+  };
+}
+
 /**
- * @name sum
- * @description Return the sum of given values.
- * ```typescript
- * function sum(...nums: number[] | number[][]): number;
- * ```
+ * Calculates the sum of an array of numbers.
+ * 
+ * This function takes an array of numbers and returns the sum of all the elements in the array.
+ *
+ * @param {number[]} nums - An array of numbers to be summed.
+ * @returns {number} The sum of all the numbers in the array.
  *
  * @example
- * sum(1, 2, 3) === 6
- * sum(...[1, 2, 3]) === 6
- * sum([1, 2, 3]) === 6
+ *  * const numbers = [1, 2, 3, 4, 5];
+ * const result = sum(numbers);
+ * // result will be 15
  */
-function sum() {
-  for (var _len = arguments.length, nums = new Array(_len), _key = 0; _key < _len; _key++) {
-    nums[_key] = arguments[_key];
+function sum(nums) {
+  var result = 0;
+  var _iterator = _createForOfIteratorHelper(nums),
+    _step;
+  try {
+    for (_iterator.s(); !(_step = _iterator.n()).done;) {
+      var num = _step.value;
+      result += num;
+    }
+  } catch (err) {
+    _iterator.e(err);
+  } finally {
+    _iterator.f();
   }
-  return nums.flat().reduce(function (acc, curr) {
-    return acc + curr;
-  }, 0);
+  return result;
 }
 
 exports.clamp = clamp;

package/dist/math/round.d.ts

@@ -1,13 +1,16 @@
 /**
- * @name round
- * @description Rounds given number to given precision
- * ```typescript
- * function round(value: number, precision: number = 0): number
- * ```
+ * Rounds a number to a specified precision.
+ *
+ * This function takes a number and an optional precision value, and returns the number rounded
+ * to the specified number of decimal places.
+ *
+ * @param {number} value - The number to round.
+ * @param {number} [precision=0] - The number of decimal places to round to. Defaults to 0.
+ * @returns {number} The rounded number.
  *
  * @example
- * round(1.2) === 1
- * round(3.9) === 4
- * round(8.5) === 9
+ *  * const result1 = round(1.2345); // result1 will be 1
+ * const result2 = round(1.2345, 2); // result2 will be 1.23
+ * const result3 = round(1.2345, 3); // result3 will be 1.235
  */
 export declare function round(value: number, precision?: number): number;

package/dist/math/sum.d.ts

@@ -1,13 +1,14 @@
 /**
- * @name sum
- * @description Return the sum of given values.
- * ```typescript
- * function sum(...nums: number[] | number[][]): number;
- * ```
+ * Calculates the sum of an array of numbers.
+ *
+ * This function takes an array of numbers and returns the sum of all the elements in the array.
+ *
+ * @param {number[]} nums - An array of numbers to be summed.
+ * @returns {number} The sum of all the numbers in the array.
  *
  * @example
- * sum(1, 2, 3) === 6
- * sum(...[1, 2, 3]) === 6
- * sum([1, 2, 3]) === 6
+ *  * const numbers = [1, 2, 3, 4, 5];
+ * const result = sum(numbers);
+ * // result will be 15
  */
-export declare function sum(...nums: number[] | number[][]): number;
+export declare function sum(nums: number[]): number;

package/dist/object/index.js

@@ -2,6 +2,33 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
+function _iterableToArrayLimit(r, l) {
+  var t = null == r ? null : "undefined" != typeof Symbol && r[Symbol.iterator] || r["@@iterator"];
+  if (null != t) {
+    var e,
+      n,
+      i,
+      u,
+      a = [],
+      f = !0,
+      o = !1;
+    try {
+      if (i = (t = t.call(r)).next, 0 === l) {
+        if (Object(t) !== t) return;
+        f = !1;
+      } else for (; !(f = (e = i.call(t)).done) && (a.push(e.value), a.length !== l); f = !0);
+    } catch (r) {
+      o = !0, n = r;
+    } finally {
+      try {
+        if (!f && null != t.return && (u = t.return(), Object(u) !== u)) return;
+      } finally {
+        if (o) throw n;
+      }
+    }
+    return a;
+  }
+}
 function ownKeys(e, r) {
   var t = Object.keys(e);
   if (Object.getOwnPropertySymbols) {
@@ -51,6 +78,12 @@ function _defineProperty(obj, key, value) {
   }
   return obj;
 }
+function _slicedToArray(arr, i) {
+  return _arrayWithHoles(arr) || _iterableToArrayLimit(arr, i) || _unsupportedIterableToArray(arr, i) || _nonIterableRest();
+}
+function _arrayWithHoles(arr) {
+  if (Array.isArray(arr)) return arr;
+}
 function _unsupportedIterableToArray(o, minLen) {
   if (!o) return;
   if (typeof o === "string") return _arrayLikeToArray(o, minLen);
@@ -64,6 +97,9 @@ function _arrayLikeToArray(arr, len) {
   for (var i = 0, arr2 = new Array(len); i < len; i++) arr2[i] = arr[i];
   return arr2;
 }
+function _nonIterableRest() {
+  throw new TypeError("Invalid attempt to destructure non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
+}
 function _createForOfIteratorHelper(o, allowArrayLike) {
   var it = typeof Symbol !== "undefined" && o[Symbol.iterator] || o["@@iterator"];
   if (!it) {
@@ -117,10 +153,19 @@ function _createForOfIteratorHelper(o, allowArrayLike) {
 }
 
 /**
- * @name omit
- * Omit properties from an object.
- * @param obj The object to omit properties from
- * @param keys The keys to omit from an object
+ * Creates a new object with specified keys omitted.
+ *
+ * This function takes an object and an array of keys, and returns a new object that 
+ * excludes the properties corresponding to the specified keys.
+ *
+ * @param {T} obj - The object to omit keys from.
+ * @param {K[]} keys - An array of keys to be omitted from the object.
+ * @returns {Omit<T, K>} A new object with the specified keys omitted.
+ *
+ * @example
+ *  * const obj = { a: 1, b: 2, c: 3 };
+ * const result = omit(obj, ['b', 'c']);
+ * // result will be { a: 1 }
  */
 function omit(obj, keys) {
   var result = _objectSpread2({}, obj);
@@ -139,15 +184,52 @@ function omit(obj, keys) {
   return result;
 }
 
-function omitBy() {
-  throw new Error('Not implemented');
+/**
+ * Creates a new object composed of the properties that do not satisfy the predicate function.
+ *
+ * This function takes an object and a predicate function, and returns a new object that 
+ * includes only the properties for which the predicate function returns false.
+ *
+ * @param {T} obj - The object to omit properties from.
+ * @param {(value: T[string], key: string) => boolean} shouldOmit - A predicate function that determines 
+ * whether a property should be omitted. It takes the property's key and value as arguments and returns `true` 
+ * if the property should be omitted, and `false` otherwise.
+ * @returns {Partial<T>} A new object with the properties that do not satisfy the predicate function.
+ *
+ * @example
+ * const obj = { a: 1, b: 'omit', c: 3 };
+ * const shouldOmit = (key, value) => typeof value === 'string';
+ * const result = omitBy(obj, shouldOmit);
+ * // result will be { a: 1, c: 3 }
+ */
+function omitBy(obj, shouldOmit) {
+  var result = {};
+  for (var _i = 0, _Object$entries = Object.entries(obj); _i < _Object$entries.length; _i++) {
+    var _Object$entries$_i = _slicedToArray(_Object$entries[_i], 2),
+      key = _Object$entries$_i[0],
+      value = _Object$entries$_i[1];
+    if (shouldOmit(value, key)) {
+      continue;
+    }
+    result[key] = value;
+  }
+  return result;
 }
 
 /**
- * @name pick
- * Pick properties from an given object.
- * @param obj The object to pick properties from
- * @param keys The keys to pick from an object
+ * Creates a new object composed of the picked object properties.
+ *
+ * This function takes an object and an array of keys, and returns a new object that 
+ * includes only the properties corresponding to the specified keys.
+ *
+ * @param {T} obj - The object to pick keys from.
+ * @param {K[]} keys - An array of keys to be picked from the object.
+ * @returns {Pick<T, K>} A new object with the specified keys picked.
+ *
+ * @example
+ *  * const obj = { a: 1, b: 2, c: 3 };
+ * const result = pick(obj, ['a', 'c']);
+ * // result will be { a: 1, c: 3 }
  */
 function pick(obj, keys) {
   var result = {};
@@ -166,8 +248,36 @@ function pick(obj, keys) {
   return result;
 }
 
-function pickBy() {
-  throw new Error('Not implemented');
+/**
+ * Creates a new object composed of the properties that satisfy the predicate function.
+ *
+ * This function takes an object and a predicate function, and returns a new object that 
+ * includes only the properties for which the predicate function returns true.
+ *
+ * @param {T} obj - The object to pick properties from.
+ * @param {(value: T[keyof T], key: string) => boolean} shouldPick - A predicate function that determines 
+ * whether a property should be picked. It takes the property's key and value as arguments and returns `true` 
+ * if the property should be picked, and `false` otherwise.
+ * @returns {Partial<T>} A new object with the properties that satisfy the predicate function.
+ *
+ * @example
+ * const obj = { a: 1, b: 'pick', c: 3 };
+ * const shouldPick = (value) => typeof value === 'string';
+ * const result = pickBy(obj, shouldPick);
+ * // result will be { b: 'pick' }
+ */
+function pickBy(obj, shouldPick) {
+  var result = {};
+  for (var _i = 0, _Object$entries = Object.entries(obj); _i < _Object$entries.length; _i++) {
+    var _Object$entries$_i = _slicedToArray(_Object$entries[_i], 2),
+      key = _Object$entries$_i[0],
+      value = _Object$entries$_i[1];
+    if (!shouldPick(value, key)) {
+      continue;
+    }
+    result[key] = value;
+  }
+  return result;
 }
 
 exports.omit = omit;

package/dist/object/omit.d.ts

@@ -1,7 +1,16 @@
 /**
- * @name omit
- * Omit properties from an object.
- * @param obj The object to omit properties from
- * @param keys The keys to omit from an object
+ * Creates a new object with specified keys omitted.
+ *
+ * This function takes an object and an array of keys, and returns a new object that
+ * excludes the properties corresponding to the specified keys.
+ *
+ * @param {T} obj - The object to omit keys from.
+ * @param {K[]} keys - An array of keys to be omitted from the object.
+ * @returns {Omit<T, K>} A new object with the specified keys omitted.
+ *
+ * @example
+ *  * const obj = { a: 1, b: 2, c: 3 };
+ * const result = omit(obj, ['b', 'c']);
+ * // result will be { a: 1 }
  */
 export declare function omit<T, K extends keyof T>(obj: T, keys: K[]): Omit<T, K>;

package/dist/object/omitBy.d.ts

@@ -1 +1,19 @@
-export declare function omitBy(): void;
+/**
+ * Creates a new object composed of the properties that do not satisfy the predicate function.
+ *
+ * This function takes an object and a predicate function, and returns a new object that
+ * includes only the properties for which the predicate function returns false.
+ *
+ * @param {T} obj - The object to omit properties from.
+ * @param {(value: T[string], key: string) => boolean} shouldOmit - A predicate function that determines
+ * whether a property should be omitted. It takes the property's key and value as arguments and returns `true`
+ * if the property should be omitted, and `false` otherwise.
+ * @returns {Partial<T>} A new object with the properties that do not satisfy the predicate function.
+ *
+ * @example
+ * const obj = { a: 1, b: 'omit', c: 3 };
+ * const shouldOmit = (key, value) => typeof value === 'string';
+ * const result = omitBy(obj, shouldOmit);
+ * // result will be { a: 1, c: 3 }
+ */
+export declare function omitBy<T extends Record<string, any>>(obj: T, shouldOmit: (value: T[keyof T], key: string) => boolean): Partial<T>;

package/dist/object/omitBy.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/object/pick.d.ts

@@ -1,7 +1,16 @@
 /**
- * @name pick
- * Pick properties from an given object.
- * @param obj The object to pick properties from
- * @param keys The keys to pick from an object
+ * Creates a new object composed of the picked object properties.
+ *
+ * This function takes an object and an array of keys, and returns a new object that
+ * includes only the properties corresponding to the specified keys.
+ *
+ * @param {T} obj - The object to pick keys from.
+ * @param {K[]} keys - An array of keys to be picked from the object.
+ * @returns {Pick<T, K>} A new object with the specified keys picked.
+ *
+ * @example
+ *  * const obj = { a: 1, b: 2, c: 3 };
+ * const result = pick(obj, ['a', 'c']);
+ * // result will be { a: 1, c: 3 }
  */
 export declare function pick<T, K extends keyof T>(obj: T, keys: K[]): Pick<T, K>;

package/dist/object/pickBy.d.ts

@@ -1 +1,19 @@
-export declare function pickBy(): void;
+/**
+ * Creates a new object composed of the properties that satisfy the predicate function.
+ *
+ * This function takes an object and a predicate function, and returns a new object that
+ * includes only the properties for which the predicate function returns true.
+ *
+ * @param {T} obj - The object to pick properties from.
+ * @param {(value: T[keyof T], key: string) => boolean} shouldPick - A predicate function that determines
+ * whether a property should be picked. It takes the property's key and value as arguments and returns `true`
+ * if the property should be picked, and `false` otherwise.
+ * @returns {Partial<T>} A new object with the properties that satisfy the predicate function.
+ *
+ * @example
+ * const obj = { a: 1, b: 'pick', c: 3 };
+ * const shouldPick = (value) => typeof value === 'string';
+ * const result = pickBy(obj, shouldPick);
+ * // result will be { b: 'pick' }
+ */
+export declare function pickBy<T extends Record<string, any>>(obj: T, shouldPick: (value: T[keyof T], key: string) => boolean): Partial<T>;

package/dist/object/pickBy.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/predicate/index.js

@@ -3,42 +3,90 @@
 Object.defineProperty(exports, '__esModule', { value: true });
 
 /**
- * @name isNil
- * Checks if the given value is null or undefined.
- * @param x The value to test if it is null or undefined
+ * Checks if a given value is null or undefined.
+ * 
+ * This function tests whether the provided value is either `null` or `undefined`. 
+ * It returns `true` if the value is `null` or `undefined`, and `false` otherwise.
+ * 
+ * This function can also serve as a type predicate in TypeScript, narrowing the type of the argument to `null` or `undefined`.
+ *
+ * @param {unknown} x - The value to test for null or undefined.
+ * @returns {boolean} `true` if the value is null or undefined, `false` otherwise.
+ *
+ * @example
+ *  * const value1 = null;
+ * const value2 = undefined;
+ * const value3 = 42;
+ * const result1 = isNil(value1); // true
+ * const result2 = isNil(value2); // true
+ * const result3 = isNil(value3); // false
  */
 function isNil(x) {
   return x == null || x == undefined;
 }
 
 /**
- * @name isNotNil
  * Checks if the given value is not null nor undefined.
- * The main use of this function is to used with TypeScript as a type predicate.
- * @param x The value to test if it is not null nor undefined
+ * 
+ * The main use of this function is to be used with TypeScript as a type predicate.
+ *
+ * @param {T | null | undefined} x - The value to test if it is not null nor undefined.
+ * @returns {x is T} True if the value is not null nor undefined, false otherwise.
+ *
  * @example
  * // Here the type of `arr` is (number | undefined)[]
  * const arr = [1, undefined, 3];
  * // Here the type of `result` is number[]
  * const result = arr.filter(isNotNil);
+ * // result will be [1, 3]
  */
 function isNotNil(x) {
   return x != null && x != undefined;
 }
 
 /**
- * @name isNull
  * Checks if the given value is null.
- * @param x The value to test if it is null
+ *
+ * This function tests whether the provided value is strictly equal to `null`. 
+ * It returns `true` if the value is `null`, and `false` otherwise.
+ *
+ * This function can also serve as a type predicate in TypeScript, narrowing the type of the argument to `null`.
+ * 
+ * @param {unknown} x - The value to test if it is null.
+ * @returns {x is null} True if the value is null, false otherwise.
+ *
+ * @example
+ *  * const value1 = null;
+ * const value2 = undefined;
+ * const value3 = 42;
+ * 
+ * console.log(isNull(value1)); // true
+ * console.log(isNull(value2)); // false
+ * console.log(isNull(value3)); // false
  */
 function isNull(x) {
   return x === null;
 }
 
 /**
- * @name isUndefined
  * Checks if the given value is undefined.
- * @param x The value to test if it is undefined
+ *
+ * This function tests whether the provided value is strictly equal to `undefined`. 
+ * It returns `true` if the value is `undefined`, and `false` otherwise.
+ * 
+ * This function can also serve as a type predicate in TypeScript, narrowing the type of the argument to `undefined`.
+ *
+ * @param {unknown} x - The value to test if it is undefined.
+ * @returns {x is undefined} true if the value is undefined, false otherwise.
+ *
+ * @example
+ *  * const value1 = undefined;
+ * const value2 = null;
+ * const value3 = 42;
+ * 
+ * console.log(isUndefined(value1)); // true
+ * console.log(isUndefined(value2)); // false
+ * console.log(isUndefined(value3)); // false
  */
 function isUndefined(x) {
   return x === undefined;

package/dist/predicate/isNil.d.ts

@@ -1,6 +1,20 @@
 /**
- * @name isNil
- * Checks if the given value is null or undefined.
- * @param x The value to test if it is null or undefined
+ * Checks if a given value is null or undefined.
+ *
+ * This function tests whether the provided value is either `null` or `undefined`.
+ * It returns `true` if the value is `null` or `undefined`, and `false` otherwise.
+ *
+ * This function can also serve as a type predicate in TypeScript, narrowing the type of the argument to `null` or `undefined`.
+ *
+ * @param {unknown} x - The value to test for null or undefined.
+ * @returns {boolean} `true` if the value is null or undefined, `false` otherwise.
+ *
+ * @example
+ *  * const value1 = null;
+ * const value2 = undefined;
+ * const value3 = 42;
+ * const result1 = isNil(value1); // true
+ * const result2 = isNil(value2); // true
+ * const result3 = isNil(value3); // false
  */
 export declare function isNil(x: unknown): x is null | undefined;

package/dist/predicate/isNotNil.d.ts

@@ -1,12 +1,16 @@
 /**
- * @name isNotNil
  * Checks if the given value is not null nor undefined.
- * The main use of this function is to used with TypeScript as a type predicate.
- * @param x The value to test if it is not null nor undefined
+ *
+ * The main use of this function is to be used with TypeScript as a type predicate.
+ *
+ * @param {T | null | undefined} x - The value to test if it is not null nor undefined.
+ * @returns {x is T} True if the value is not null nor undefined, false otherwise.
+ *
  * @example
  * // Here the type of `arr` is (number | undefined)[]
  * const arr = [1, undefined, 3];
  * // Here the type of `result` is number[]
  * const result = arr.filter(isNotNil);
+ * // result will be [1, 3]
  */
 export declare function isNotNil<T>(x: T | null | undefined): x is T;