es-toolkit 0.0.1 → 1.0.0-dev.24

package/esm/predicate/isNil.mjs

@@ -1,7 +1,21 @@
 /**
- * @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;

package/esm/predicate/isNotNil.mjs

@@ -1,13 +1,17 @@
 /**
- * @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;

package/esm/predicate/isNull.mjs

@@ -1,7 +1,22 @@
 /**
- * @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;

package/esm/predicate/isUndefined.mjs

@@ -1,7 +1,22 @@
 /**
- * @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/esm/promise/delay.mjs

@@ -1,7 +1,20 @@
 /**
- * @name delay
- * Pause the execution of a function for given milliseconds.
- * @param ms The amount of time to delay the function.
+ * Delays the execution of code for a specified number of milliseconds.
+ * 
+ * This function returns a Promise that resolves after the specified delay, allowing you to use it 
+ * with async/await to pause execution.
+ *
+ * @param {number} ms - The number of milliseconds to delay.
+ * @returns {Promise<void>} A Promise that resolves after the specified delay.
+ *
+ * @example
+ * async function foo() {
+ *   console.log('Start');
+ *   await delay(1000); // Delays execution for 1 second
+ *   console.log('End');
+ * }
+ * 
+ * foo();
  */
 function delay(ms) {
   return new Promise(function (resolve) {

package/package.json

@@ -1,7 +1,10 @@
 {
   "name": "es-toolkit",
-  "description": "A state-of-the-art, high-performance JavaScript utility library featuring robust type annotations and straightforward implementations.",
-  "version": "0.0.1",
+  "description": "A state-of-the-art, high-performance JavaScript utility library with a small bundle size and strong type annotations.",
+  "version": "1.0.0-dev.24+7203b563",
+  "workspaces": [
+    "docs"
+  ],
   "packageManager": "yarn@4.2.2",
   "exports": {
     ".": {
@@ -34,6 +37,10 @@
     },
     "./package.json": "./package.json"
   },
+  "files": [
+    "dist/**/*",
+    "esm/**/*"
+  ],
   "publishConfig": {
     "access": "public",
     "exports": {
@@ -72,14 +79,21 @@
     "@babel/core": "^7.24.5",
     "@babel/preset-env": "^7.24.5",
     "@babel/preset-typescript": "^7.24.1",
-    "@toss/rollup-config": "^0.2.0",
+    "@changesets/changelog-github": "^0.5.0",
+    "@changesets/cli": "^2.27.1",
+    "@toss/rollup-config": "0.2.0-canary.0",
     "@types/babel__core": "^7",
     "@types/babel__preset-env": "^7",
+    "@types/broken-link-checker": "^0",
+    "@types/lodash": "^4",
     "@types/node": "^20.12.11",
     "@typescript-eslint/eslint-plugin": "^7.7.1",
     "@typescript-eslint/parser": "^7.7.1",
     "@vitest/coverage-istanbul": "^1.5.2",
+    "broken-link-checker": "^0.7.8",
     "eslint": "^8.56.0",
+    "eslint-config-prettier": "^8.5.0",
+    "lodash": "^4.17.21",
     "prettier": "^3.2.5",
     "rollup": "^2.78.0",
     "typescript": "^5.4.5",

package/.vscode/extensions.json

@@ -1,7 +0,0 @@
-{
-  "recommendations": [
-    "arcanis.vscode-zipfs",
-    "dbaeumer.vscode-eslint",
-    "esbenp.prettier-vscode"
-  ]
-}

package/.vscode/settings.json

@@ -1,10 +0,0 @@
-{
-  "search.exclude": {
-    "**/.yarn": true,
-    "**/.pnp.*": true
-  },
-  "eslint.nodePath": ".yarn/sdks",
-  "prettier.prettierPath": ".yarn/sdks/prettier/index.cjs",
-  "typescript.tsdk": ".yarn/sdks/typescript/lib",
-  "typescript.enablePromptUseWorkspaceTsdk": true
-}

package/.yarn/sdks/eslint/bin/eslint.js

@@ -1,20 +0,0 @@
-#!/usr/bin/env node
-
-const {existsSync} = require(`fs`);
-const {createRequire} = require(`module`);
-const {resolve} = require(`path`);
-
-const relPnpApiPath = "../../../../.pnp.cjs";
-
-const absPnpApiPath = resolve(__dirname, relPnpApiPath);
-const absRequire = createRequire(absPnpApiPath);
-
-if (existsSync(absPnpApiPath)) {
-  if (!process.versions.pnp) {
-    // Setup the environment to be able to require eslint/bin/eslint.js
-    require(absPnpApiPath).setup();
-  }
-}
-
-// Defer to the real eslint/bin/eslint.js your application uses
-module.exports = absRequire(`eslint/bin/eslint.js`);

package/.yarn/sdks/eslint/lib/api.js

@@ -1,20 +0,0 @@
-#!/usr/bin/env node
-
-const {existsSync} = require(`fs`);
-const {createRequire} = require(`module`);
-const {resolve} = require(`path`);
-
-const relPnpApiPath = "../../../../.pnp.cjs";
-
-const absPnpApiPath = resolve(__dirname, relPnpApiPath);
-const absRequire = createRequire(absPnpApiPath);
-
-if (existsSync(absPnpApiPath)) {
-  if (!process.versions.pnp) {
-    // Setup the environment to be able to require eslint
-    require(absPnpApiPath).setup();
-  }
-}
-
-// Defer to the real eslint your application uses
-module.exports = absRequire(`eslint`);

package/.yarn/sdks/eslint/lib/unsupported-api.js

@@ -1,20 +0,0 @@
-#!/usr/bin/env node
-
-const {existsSync} = require(`fs`);
-const {createRequire} = require(`module`);
-const {resolve} = require(`path`);
-
-const relPnpApiPath = "../../../../.pnp.cjs";
-
-const absPnpApiPath = resolve(__dirname, relPnpApiPath);
-const absRequire = createRequire(absPnpApiPath);
-
-if (existsSync(absPnpApiPath)) {
-  if (!process.versions.pnp) {
-    // Setup the environment to be able to require eslint/use-at-your-own-risk
-    require(absPnpApiPath).setup();
-  }
-}
-
-// Defer to the real eslint/use-at-your-own-risk your application uses
-module.exports = absRequire(`eslint/use-at-your-own-risk`);

package/.yarn/sdks/eslint/package.json

@@ -1,14 +0,0 @@
-{
-  "name": "eslint",
-  "version": "8.57.0-sdk",
-  "main": "./lib/api.js",
-  "type": "commonjs",
-  "bin": {
-    "eslint": "./bin/eslint.js"
-  },
-  "exports": {
-    "./package.json": "./package.json",
-    ".": "./lib/api.js",
-    "./use-at-your-own-risk": "./lib/unsupported-api.js"
-  }
-}

package/.yarn/sdks/integrations.yml

@@ -1,5 +0,0 @@
-# This file is automatically generated by @yarnpkg/sdks.
-# Manual changes might be lost!
-
-integrations:
-  - vscode

package/.yarn/sdks/prettier/bin/prettier.cjs

@@ -1,20 +0,0 @@
-#!/usr/bin/env node
-
-const {existsSync} = require(`fs`);
-const {createRequire} = require(`module`);
-const {resolve} = require(`path`);
-
-const relPnpApiPath = "../../../../.pnp.cjs";
-
-const absPnpApiPath = resolve(__dirname, relPnpApiPath);
-const absRequire = createRequire(absPnpApiPath);
-
-if (existsSync(absPnpApiPath)) {
-  if (!process.versions.pnp) {
-    // Setup the environment to be able to require prettier/bin/prettier.cjs
-    require(absPnpApiPath).setup();
-  }
-}
-
-// Defer to the real prettier/bin/prettier.cjs your application uses
-module.exports = absRequire(`prettier/bin/prettier.cjs`);

package/.yarn/sdks/prettier/index.cjs

@@ -1,20 +0,0 @@
-#!/usr/bin/env node
-
-const {existsSync} = require(`fs`);
-const {createRequire} = require(`module`);
-const {resolve} = require(`path`);
-
-const relPnpApiPath = "../../../.pnp.cjs";
-
-const absPnpApiPath = resolve(__dirname, relPnpApiPath);
-const absRequire = createRequire(absPnpApiPath);
-
-if (existsSync(absPnpApiPath)) {
-  if (!process.versions.pnp) {
-    // Setup the environment to be able to require prettier
-    require(absPnpApiPath).setup();
-  }
-}
-
-// Defer to the real prettier your application uses
-module.exports = absRequire(`prettier`);

package/.yarn/sdks/prettier/package.json

@@ -1,7 +0,0 @@
-{
-  "name": "prettier",
-  "version": "3.2.5-sdk",
-  "main": "./index.cjs",
-  "type": "commonjs",
-  "bin": "./bin/prettier.cjs"
-}

package/.yarn/sdks/typescript/bin/tsc

@@ -1,20 +0,0 @@
-#!/usr/bin/env node
-
-const {existsSync} = require(`fs`);
-const {createRequire} = require(`module`);
-const {resolve} = require(`path`);
-
-const relPnpApiPath = "../../../../.pnp.cjs";
-
-const absPnpApiPath = resolve(__dirname, relPnpApiPath);
-const absRequire = createRequire(absPnpApiPath);
-
-if (existsSync(absPnpApiPath)) {
-  if (!process.versions.pnp) {
-    // Setup the environment to be able to require typescript/bin/tsc
-    require(absPnpApiPath).setup();
-  }
-}
-
-// Defer to the real typescript/bin/tsc your application uses
-module.exports = absRequire(`typescript/bin/tsc`);

package/.yarn/sdks/typescript/bin/tsserver

@@ -1,20 +0,0 @@
-#!/usr/bin/env node
-
-const {existsSync} = require(`fs`);
-const {createRequire} = require(`module`);
-const {resolve} = require(`path`);
-
-const relPnpApiPath = "../../../../.pnp.cjs";
-
-const absPnpApiPath = resolve(__dirname, relPnpApiPath);
-const absRequire = createRequire(absPnpApiPath);
-
-if (existsSync(absPnpApiPath)) {
-  if (!process.versions.pnp) {
-    // Setup the environment to be able to require typescript/bin/tsserver
-    require(absPnpApiPath).setup();
-  }
-}
-
-// Defer to the real typescript/bin/tsserver your application uses
-module.exports = absRequire(`typescript/bin/tsserver`);

package/.yarn/sdks/typescript/lib/tsc.js

@@ -1,20 +0,0 @@
-#!/usr/bin/env node
-
-const {existsSync} = require(`fs`);
-const {createRequire} = require(`module`);
-const {resolve} = require(`path`);
-
-const relPnpApiPath = "../../../../.pnp.cjs";
-
-const absPnpApiPath = resolve(__dirname, relPnpApiPath);
-const absRequire = createRequire(absPnpApiPath);
-
-if (existsSync(absPnpApiPath)) {
-  if (!process.versions.pnp) {
-    // Setup the environment to be able to require typescript/lib/tsc.js
-    require(absPnpApiPath).setup();
-  }
-}
-
-// Defer to the real typescript/lib/tsc.js your application uses
-module.exports = absRequire(`typescript/lib/tsc.js`);

package/.yarn/sdks/typescript/lib/tsserver.js

@@ -1,225 +0,0 @@
-#!/usr/bin/env node
-
-const {existsSync} = require(`fs`);
-const {createRequire} = require(`module`);
-const {resolve} = require(`path`);
-
-const relPnpApiPath = "../../../../.pnp.cjs";
-
-const absPnpApiPath = resolve(__dirname, relPnpApiPath);
-const absRequire = createRequire(absPnpApiPath);
-
-const moduleWrapper = tsserver => {
-  if (!process.versions.pnp) {
-    return tsserver;
-  }
-
-  const {isAbsolute} = require(`path`);
-  const pnpApi = require(`pnpapi`);
-
-  const isVirtual = str => str.match(/\/(\$\$virtual|__virtual__)\//);
-  const isPortal = str => str.startsWith("portal:/");
-  const normalize = str => str.replace(/\\/g, `/`).replace(/^\/?/, `/`);
-
-  const dependencyTreeRoots = new Set(pnpApi.getDependencyTreeRoots().map(locator => {
-    return `${locator.name}@${locator.reference}`;
-  }));
-
-  // VSCode sends the zip paths to TS using the "zip://" prefix, that TS
-  // doesn't understand. This layer makes sure to remove the protocol
-  // before forwarding it to TS, and to add it back on all returned paths.
-
-  function toEditorPath(str) {
-    // We add the `zip:` prefix to both `.zip/` paths and virtual paths
-    if (isAbsolute(str) && !str.match(/^\^?(zip:|\/zip\/)/) && (str.match(/\.zip\//) || isVirtual(str))) {
-      // We also take the opportunity to turn virtual paths into physical ones;
-      // this makes it much easier to work with workspaces that list peer
-      // dependencies, since otherwise Ctrl+Click would bring us to the virtual
-      // file instances instead of the real ones.
-      //
-      // We only do this to modules owned by the the dependency tree roots.
-      // This avoids breaking the resolution when jumping inside a vendor
-      // with peer dep (otherwise jumping into react-dom would show resolution
-      // errors on react).
-      //
-      const resolved = isVirtual(str) ? pnpApi.resolveVirtual(str) : str;
-      if (resolved) {
-        const locator = pnpApi.findPackageLocator(resolved);
-        if (locator && (dependencyTreeRoots.has(`${locator.name}@${locator.reference}`) || isPortal(locator.reference))) {
-          str = resolved;
-        }
-      }
-
-      str = normalize(str);
-
-      if (str.match(/\.zip\//)) {
-        switch (hostInfo) {
-          // Absolute VSCode `Uri.fsPath`s need to start with a slash.
-          // VSCode only adds it automatically for supported schemes,
-          // so we have to do it manually for the `zip` scheme.
-          // The path needs to start with a caret otherwise VSCode doesn't handle the protocol
-          //
-          // Ref: https://github.com/microsoft/vscode/issues/105014#issuecomment-686760910
-          //
-          // 2021-10-08: VSCode changed the format in 1.61.
-          // Before | ^zip:/c:/foo/bar.zip/package.json
-          // After  | ^/zip//c:/foo/bar.zip/package.json
-          //
-          // 2022-04-06: VSCode changed the format in 1.66.
-          // Before | ^/zip//c:/foo/bar.zip/package.json
-          // After  | ^/zip/c:/foo/bar.zip/package.json
-          //
-          // 2022-05-06: VSCode changed the format in 1.68
-          // Before | ^/zip/c:/foo/bar.zip/package.json
-          // After  | ^/zip//c:/foo/bar.zip/package.json
-          //
-          case `vscode <1.61`: {
-            str = `^zip:${str}`;
-          } break;
-
-          case `vscode <1.66`: {
-            str = `^/zip/${str}`;
-          } break;
-
-          case `vscode <1.68`: {
-            str = `^/zip${str}`;
-          } break;
-
-          case `vscode`: {
-            str = `^/zip/${str}`;
-          } break;
-
-          // To make "go to definition" work,
-          // We have to resolve the actual file system path from virtual path
-          // and convert scheme to supported by [vim-rzip](https://github.com/lbrayner/vim-rzip)
-          case `coc-nvim`: {
-            str = normalize(resolved).replace(/\.zip\//, `.zip::`);
-            str = resolve(`zipfile:${str}`);
-          } break;
-
-          // Support neovim native LSP and [typescript-language-server](https://github.com/theia-ide/typescript-language-server)
-          // We have to resolve the actual file system path from virtual path,
-          // everything else is up to neovim
-          case `neovim`: {
-            str = normalize(resolved).replace(/\.zip\//, `.zip::`);
-            str = `zipfile://${str}`;
-          } break;
-
-          default: {
-            str = `zip:${str}`;
-          } break;
-        }
-      } else {
-        str = str.replace(/^\/?/, process.platform === `win32` ? `` : `/`);
-      }
-    }
-
-    return str;
-  }
-
-  function fromEditorPath(str) {
-    switch (hostInfo) {
-      case `coc-nvim`: {
-        str = str.replace(/\.zip::/, `.zip/`);
-        // The path for coc-nvim is in format of /<pwd>/zipfile:/<pwd>/.yarn/...
-        // So in order to convert it back, we use .* to match all the thing
-        // before `zipfile:`
-        return process.platform === `win32`
-          ? str.replace(/^.*zipfile:\//, ``)
-          : str.replace(/^.*zipfile:/, ``);
-      } break;
-
-      case `neovim`: {
-        str = str.replace(/\.zip::/, `.zip/`);
-        // The path for neovim is in format of zipfile:///<pwd>/.yarn/...
-        return str.replace(/^zipfile:\/\//, ``);
-      } break;
-
-      case `vscode`:
-      default: {
-        return str.replace(/^\^?(zip:|\/zip(\/ts-nul-authority)?)\/+/, process.platform === `win32` ? `` : `/`)
-      } break;
-    }
-  }
-
-  // Force enable 'allowLocalPluginLoads'
-  // TypeScript tries to resolve plugins using a path relative to itself
-  // which doesn't work when using the global cache
-  // https://github.com/microsoft/TypeScript/blob/1b57a0395e0bff191581c9606aab92832001de62/src/server/project.ts#L2238
-  // VSCode doesn't want to enable 'allowLocalPluginLoads' due to security concerns but
-  // TypeScript already does local loads and if this code is running the user trusts the workspace
-  // https://github.com/microsoft/vscode/issues/45856
-  const ConfiguredProject = tsserver.server.ConfiguredProject;
-  const {enablePluginsWithOptions: originalEnablePluginsWithOptions} = ConfiguredProject.prototype;
-  ConfiguredProject.prototype.enablePluginsWithOptions = function() {
-    this.projectService.allowLocalPluginLoads = true;
-    return originalEnablePluginsWithOptions.apply(this, arguments);
-  };
-
-  // And here is the point where we hijack the VSCode <-> TS communications
-  // by adding ourselves in the middle. We locate everything that looks
-  // like an absolute path of ours and normalize it.
-
-  const Session = tsserver.server.Session;
-  const {onMessage: originalOnMessage, send: originalSend} = Session.prototype;
-  let hostInfo = `unknown`;
-
-  Object.assign(Session.prototype, {
-    onMessage(/** @type {string | object} */ message) {
-      const isStringMessage = typeof message === 'string';
-      const parsedMessage = isStringMessage ? JSON.parse(message) : message;
-
-      if (
-        parsedMessage != null &&
-        typeof parsedMessage === `object` &&
-        parsedMessage.arguments &&
-        typeof parsedMessage.arguments.hostInfo === `string`
-      ) {
-        hostInfo = parsedMessage.arguments.hostInfo;
-        if (hostInfo === `vscode` && process.env.VSCODE_IPC_HOOK) {
-          const [, major, minor] = (process.env.VSCODE_IPC_HOOK.match(
-            // The RegExp from https://semver.org/ but without the caret at the start
-            /(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/
-          ) ?? []).map(Number)
-
-          if (major === 1) {
-            if (minor < 61) {
-              hostInfo += ` <1.61`;
-            } else if (minor < 66) {
-              hostInfo += ` <1.66`;
-            } else if (minor < 68) {
-              hostInfo += ` <1.68`;
-            }
-          }
-        }
-      }
-
-      const processedMessageJSON = JSON.stringify(parsedMessage, (key, value) => {
-        return typeof value === 'string' ? fromEditorPath(value) : value;
-      });
-
-      return originalOnMessage.call(
-        this,
-        isStringMessage ? processedMessageJSON : JSON.parse(processedMessageJSON)
-      );
-    },
-
-    send(/** @type {any} */ msg) {
-      return originalSend.call(this, JSON.parse(JSON.stringify(msg, (key, value) => {
-        return typeof value === `string` ? toEditorPath(value) : value;
-      })));
-    }
-  });
-
-  return tsserver;
-};
-
-if (existsSync(absPnpApiPath)) {
-  if (!process.versions.pnp) {
-    // Setup the environment to be able to require typescript/lib/tsserver.js
-    require(absPnpApiPath).setup();
-  }
-}
-
-// Defer to the real typescript/lib/tsserver.js your application uses
-module.exports = moduleWrapper(absRequire(`typescript/lib/tsserver.js`));