From b6f7ba7f16c0ddc6901b2b1270d886c3b6af30e1 Mon Sep 17 00:00:00 2001 From: Andrei L <1881266+unrevised6419@users.noreply.github.com> Date: Mon, 5 Oct 2026 07:36:29 +0300 Subject: [PATCH 1/2] docs: import process and Buffer instead of using globals Examples in docs and micro-utility snippets now import `process` from `node:process` and `Buffer` from `node:buffer` rather than relying on Node.js globals. Also adds a `nodeFeatureId` to `process.loadEnvFile`. Refs #1144 Co-Authored-By: Claude Opus 5.5 --- docs/modules/cli-builders.md | 1 + docs/modules/dotenv.md | 1 + docs/modules/fast-glob.md | 1 + docs/modules/get-stream.md | 4 ++++ docs/modules/globby.md | 1 + docs/modules/is-path-in-cwd.md | 1 + docs/modules/node-telegram-bot-api.md | 1 + docs/modules/parseargs.md | 2 ++ docs/modules/resolve.md | 1 + docs/modules/stream-buffers.md | 2 ++ manifests/micro-utilities.json | 26 +++++++++++++------------- manifests/preferred.json | 4 ++++ 12 files changed, 32 insertions(+), 13 deletions(-) diff --git a/docs/modules/cli-builders.md b/docs/modules/cli-builders.md index 949e000b..1159b47f 100644 --- a/docs/modules/cli-builders.md +++ b/docs/modules/cli-builders.md @@ -9,6 +9,7 @@ description: Modern alternatives to packages for building CLI applications [`sade`](https://github.com/lukeed/sade) is a small but powerful tool for building CLI applications for Node.js ```ts +import process from 'node:process' import sade from 'sade' const prog = sade('my-cli') diff --git a/docs/modules/dotenv.md b/docs/modules/dotenv.md index cda27969..c2c1c804 100644 --- a/docs/modules/dotenv.md +++ b/docs/modules/dotenv.md @@ -12,6 +12,7 @@ It throws if the file is missing. Defaults to `.env` in the current working dire ```ts import dotenv from 'dotenv' // [!code --] +import process from 'node:process' // [!code ++] dotenv.config({ path: '.env' }) // [!code --] process.loadEnvFile('.env') // [!code ++] diff --git a/docs/modules/fast-glob.md b/docs/modules/fast-glob.md index 870a714d..376bb2d3 100644 --- a/docs/modules/fast-glob.md +++ b/docs/modules/fast-glob.md @@ -15,6 +15,7 @@ Example: ```ts import fg from 'fast-glob' // [!code --] import { glob } from 'tinyglobby' // [!code ++] +import process from 'node:process' const files = await fg('**/*.ts', { // [!code --] const files = await glob('**/*.ts', { // [!code ++] diff --git a/docs/modules/get-stream.md b/docs/modules/get-stream.md index e1809a1c..91b910da 100644 --- a/docs/modules/get-stream.md +++ b/docs/modules/get-stream.md @@ -9,6 +9,8 @@ description: Modern alternatives to the get-stream package You can convert a stream to a string by using `Buffer.from` and a `for await`: ```ts +import { Buffer } from 'node:buffer' + async function streamToString(stream) { const chunks = [] for await (const chunk of stream) { @@ -41,6 +43,8 @@ async function streamToArray(stream) { You can convert a stream to a `Buffer` using [`Array.fromAsync`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/fromAsync) with a mapper: ```ts +import { Buffer } from 'node:buffer' + async function streamToBuffer(stream) { const chunks = await Array.fromAsync(stream, (chunk) => Buffer.from(chunk)) return Buffer.concat(chunks) diff --git a/docs/modules/globby.md b/docs/modules/globby.md index 950319ad..3001d4b0 100644 --- a/docs/modules/globby.md +++ b/docs/modules/globby.md @@ -14,6 +14,7 @@ If you don’t need `.gitignore` handling, prefer [`tinyglobby`](https://github. ```ts import { execSync } from 'node:child_process' +import process from 'node:process' import { glob, escapePath } from 'tinyglobby' async function globWithGitignore(patterns, options = {}) { diff --git a/docs/modules/is-path-in-cwd.md b/docs/modules/is-path-in-cwd.md index 24d7ff41..0e38962a 100644 --- a/docs/modules/is-path-in-cwd.md +++ b/docs/modules/is-path-in-cwd.md @@ -8,6 +8,7 @@ description: Native alternatives to the is-path-in-cwd package for checking whet ```ts import path from 'node:path' +import process from 'node:process' const isPathInside = (childPath, parentPath) => { const relation = path.relative(parentPath, childPath) diff --git a/docs/modules/node-telegram-bot-api.md b/docs/modules/node-telegram-bot-api.md index a4546ff0..200f7a47 100644 --- a/docs/modules/node-telegram-bot-api.md +++ b/docs/modules/node-telegram-bot-api.md @@ -11,6 +11,7 @@ description: Modern alternatives to the node-telegram-bot-api package Example: ```ts +import process from 'node:process' import { Bot } from 'grammy' const bot = new Bot(process.env.TOKEN) diff --git a/docs/modules/parseargs.md b/docs/modules/parseargs.md index c3a942d4..d9ca943d 100644 --- a/docs/modules/parseargs.md +++ b/docs/modules/parseargs.md @@ -11,6 +11,7 @@ description: Modern alternatives to CLI argument parsing packages using Node.js Example: ```ts +import process from 'node:process' import { parseArgs } from 'node:util' const { values, positionals } = parseArgs({ @@ -33,6 +34,7 @@ const { values, positionals } = parseArgs({ Example: ```ts +import process from 'node:process' import mri from 'mri' const options = mri(process.argv.slice(2), { diff --git a/docs/modules/resolve.md b/docs/modules/resolve.md index b1203382..24f36ec3 100644 --- a/docs/modules/resolve.md +++ b/docs/modules/resolve.md @@ -29,6 +29,7 @@ const path = resolveModulePath('my-module') [`oxc-resolver`](https://github.com/oxc-project/oxc-resolver) ```ts +import process from 'node:process' import { ResolverFactory } from 'oxc-resolver' const resolver = new ResolverFactory() diff --git a/docs/modules/stream-buffers.md b/docs/modules/stream-buffers.md index 35e065ff..516a5324 100644 --- a/docs/modules/stream-buffers.md +++ b/docs/modules/stream-buffers.md @@ -43,6 +43,7 @@ Push data over time example: ```ts import streamBuffers from 'stream-buffers' // [!code --] +import { Buffer } from 'node:buffer' import { Readable } from 'node:stream' // [!code ++] const rs = new streamBuffers.ReadableStreamBuffer() // [!code --] @@ -62,6 +63,7 @@ Control chunk size and frequency example: ```ts +import { Buffer } from 'node:buffer' import streamBuffers from 'stream-buffers' // [!code --] import { Readable } from 'node:stream' // [!code ++] import { setTimeout } from 'node:timers/promises' // [!code ++] diff --git a/manifests/micro-utilities.json b/manifests/micro-utilities.json index 04d3f09c..1280f1d1 100644 --- a/manifests/micro-utilities.json +++ b/manifests/micro-utilities.json @@ -142,7 +142,7 @@ "id": "snippet::has-argv", "type": "simple", "description": "You can use the `includes` method on the `process.argv` array to check if a flag is present.", - "example": "process.argv.includes('--flag')" + "example": "import process from 'node:process'\n\nprocess.argv.includes('--flag')" }, "snippet::indent-string": { "id": "snippet::indent-string", @@ -178,7 +178,7 @@ "id": "snippet::is-aws-lambda", "type": "simple", "description": "You can check if the current environment is an AWS Lambda by checking if the `LAMBDA_TASK_ROOT` environment variables are set.", - "example": "Boolean(process.env.LAMBDA_TASK_ROOT)" + "example": "import process from 'node:process'\n\nBoolean(process.env.LAMBDA_TASK_ROOT)" }, "snippet::is-bigint": { "id": "snippet::is-bigint", @@ -196,7 +196,7 @@ "id": "snippet::is-ci", "type": "simple", "description": "Every major CI provider sets a `CI` environment variable that you can use to detect if you're running in a CI environment.", - "example": "Boolean(process.env.CI)" + "example": "import process from 'node:process'\n\nBoolean(process.env.CI)" }, "snippet::is-date": { "id": "snippet::is-date", @@ -280,13 +280,13 @@ "id": "snippet::is-in-ssh", "type": "simple", "description": "You can check if the current environment is SSH by checking if the `SSH_CONNECTION` environment variable is set.", - "example": "Boolean(process.env.SSH_CONNECTION)" + "example": "import process from 'node:process'\n\nBoolean(process.env.SSH_CONNECTION)" }, "snippet::is-interactive": { "id": "snippet::is-interactive", "type": "simple", "description": "You can check if the current environment is interactive using `process.stdout.isTTY` and checking that it is not running in CI.", - "example": "Boolean(stream?.isTTY && !process.env.CI)" + "example": "import process from 'node:process'\n\nBoolean(stream?.isTTY && !process.env.CI)" }, "snippet::is-jpg-buffer": { "id": "snippet::is-jpg-buffer", @@ -328,7 +328,7 @@ "id": "snippet::is-npm", "type": "simple", "description": "If the current environment is npm the `npm_config_user_agent` environment variable will be set and start with `\"npm\"`.", - "example": "const isNpm = process.env.npm_config_user_agent?.startsWith(\"npm\")" + "example": "import process from 'node:process'\n\nconst isNpm = process.env.npm_config_user_agent?.startsWith(\"npm\")" }, "snippet::is-null": { "id": "snippet::is-null", @@ -364,7 +364,7 @@ "id": "snippet::is-path-equal-cwd", "type": "simple", "description": "You can check if a path equals the current working directory using `path.relative`.", - "example": "import { relative } from 'node:path'\n\nconst isPathCwd = (p) => !relative(p, process.cwd())" + "example": "import { relative } from 'node:path'\nimport process from 'node:process'\n\nconst isPathCwd = (p) => !relative(p, process.cwd())" }, "snippet::is-png-buffer": { "id": "snippet::is-png-buffer", @@ -394,7 +394,7 @@ "id": "snippet::is-root-user", "type": "simple", "description": "You can use `process.getuid?.()` to check if a user is a root user.", - "example": "const isRootUser = process.getuid?.() === 0" + "example": "import process from 'node:process'\n\nconst isRootUser = process.getuid?.() === 0" }, "snippet::is-set": { "id": "snippet::is-set", @@ -436,7 +436,7 @@ "id": "snippet::is-travis", "type": "simple", "description": "You can check if the current environment is Travis CI by checking if the `TRAVIS` environment variable is set.", - "example": "Boolean(process.env.TRAVIS)" + "example": "import process from 'node:process'\n\nBoolean(process.env.TRAVIS)" }, "snippet::is-typed-array": { "id": "snippet::is-typed-array", @@ -478,7 +478,7 @@ "id": "snippet::is-windows", "type": "simple", "description": "You can check if the current environment is Windows by checking if `process.platform` is equal to \"win32\".", - "example": "const isWindows = () => process.platform === \"win32\";" + "example": "import process from 'node:process'\n\nconst isWindows = () => process.platform === \"win32\";" }, "snippet::is-word-character": { "id": "snippet::is-word-character", @@ -490,7 +490,7 @@ "id": "snippet::is-wsl", "type": "simple", "description": "You can check if the current environment is WSL by checking if the `WSL_DISTRO_NAME` environment variable is set.", - "example": "Boolean(process.env.WSL_DISTRO_NAME)" + "example": "import process from 'node:process'\n\nBoolean(process.env.WSL_DISTRO_NAME)" }, "snippet::json-file": { "id": "snippet::json-file", @@ -556,7 +556,7 @@ "id": "snippet::path-key", "type": "simple", "description": "You can use `Object.keys` with `Array.prototype.findLast` to find the case-insensitive `PATH` environment variable key.", - "example": "const pathKey = Object.keys(process.env).findLast((k) => k.toUpperCase() === 'PATH') ?? 'PATH';" + "example": "import process from 'node:process'\n\nconst pathKey = Object.keys(process.env).findLast((k) => k.toUpperCase() === 'PATH') ?? 'PATH';" }, "snippet::path-root": { "id": "snippet::path-root", @@ -622,7 +622,7 @@ "id": "snippet::typed-array-to-buffer", "type": "simple", "description": "You can use `Buffer.from` to convert a Typed Array to `Buffer` and `ArrayBuffer.isView` to avoid a copy.", - "example": "ArrayBuffer.isView(arr)\n ? Buffer.from(arr.buffer, arr.byteOffset, arr.byteLength)\n : Buffer.from(arr)" + "example": "import { Buffer } from 'node:buffer'\n\nArrayBuffer.isView(arr)\n ? Buffer.from(arr.buffer, arr.byteOffset, arr.byteLength)\n : Buffer.from(arr)" }, "snippet::typeof": { "id": "snippet::typeof", diff --git a/manifests/preferred.json b/manifests/preferred.json index d2a7ce40..e8671446 100644 --- a/manifests/preferred.json +++ b/manifests/preferred.json @@ -3666,6 +3666,10 @@ "process.loadEnvFile": { "id": "process.loadEnvFile", "type": "native", + "nodeFeatureId": { + "moduleName": "node:process", + "exportName": "loadEnvFile" + }, "url": {"type": "node", "id": "api/process.html#processloadenvfilepath"} }, "react-helmet-async": { From 50a99fe9a401f4c442597f380238f7ea60248e1d Mon Sep 17 00:00:00 2001 From: Andrei L <1881266+unrevised6419@users.noreply.github.com> Date: Mon, 5 Oct 2026 11:12:05 +0300 Subject: [PATCH 2/2] docs: keep micro-utility snippets as short hints Per review, the micro-utility examples are meant as hints for tools like npmx or ESLint output, so they keep using the globals. Co-Authored-By: Claude Opus 5.5 --- manifests/micro-utilities.json | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/manifests/micro-utilities.json b/manifests/micro-utilities.json index 1280f1d1..04d3f09c 100644 --- a/manifests/micro-utilities.json +++ b/manifests/micro-utilities.json @@ -142,7 +142,7 @@ "id": "snippet::has-argv", "type": "simple", "description": "You can use the `includes` method on the `process.argv` array to check if a flag is present.", - "example": "import process from 'node:process'\n\nprocess.argv.includes('--flag')" + "example": "process.argv.includes('--flag')" }, "snippet::indent-string": { "id": "snippet::indent-string", @@ -178,7 +178,7 @@ "id": "snippet::is-aws-lambda", "type": "simple", "description": "You can check if the current environment is an AWS Lambda by checking if the `LAMBDA_TASK_ROOT` environment variables are set.", - "example": "import process from 'node:process'\n\nBoolean(process.env.LAMBDA_TASK_ROOT)" + "example": "Boolean(process.env.LAMBDA_TASK_ROOT)" }, "snippet::is-bigint": { "id": "snippet::is-bigint", @@ -196,7 +196,7 @@ "id": "snippet::is-ci", "type": "simple", "description": "Every major CI provider sets a `CI` environment variable that you can use to detect if you're running in a CI environment.", - "example": "import process from 'node:process'\n\nBoolean(process.env.CI)" + "example": "Boolean(process.env.CI)" }, "snippet::is-date": { "id": "snippet::is-date", @@ -280,13 +280,13 @@ "id": "snippet::is-in-ssh", "type": "simple", "description": "You can check if the current environment is SSH by checking if the `SSH_CONNECTION` environment variable is set.", - "example": "import process from 'node:process'\n\nBoolean(process.env.SSH_CONNECTION)" + "example": "Boolean(process.env.SSH_CONNECTION)" }, "snippet::is-interactive": { "id": "snippet::is-interactive", "type": "simple", "description": "You can check if the current environment is interactive using `process.stdout.isTTY` and checking that it is not running in CI.", - "example": "import process from 'node:process'\n\nBoolean(stream?.isTTY && !process.env.CI)" + "example": "Boolean(stream?.isTTY && !process.env.CI)" }, "snippet::is-jpg-buffer": { "id": "snippet::is-jpg-buffer", @@ -328,7 +328,7 @@ "id": "snippet::is-npm", "type": "simple", "description": "If the current environment is npm the `npm_config_user_agent` environment variable will be set and start with `\"npm\"`.", - "example": "import process from 'node:process'\n\nconst isNpm = process.env.npm_config_user_agent?.startsWith(\"npm\")" + "example": "const isNpm = process.env.npm_config_user_agent?.startsWith(\"npm\")" }, "snippet::is-null": { "id": "snippet::is-null", @@ -364,7 +364,7 @@ "id": "snippet::is-path-equal-cwd", "type": "simple", "description": "You can check if a path equals the current working directory using `path.relative`.", - "example": "import { relative } from 'node:path'\nimport process from 'node:process'\n\nconst isPathCwd = (p) => !relative(p, process.cwd())" + "example": "import { relative } from 'node:path'\n\nconst isPathCwd = (p) => !relative(p, process.cwd())" }, "snippet::is-png-buffer": { "id": "snippet::is-png-buffer", @@ -394,7 +394,7 @@ "id": "snippet::is-root-user", "type": "simple", "description": "You can use `process.getuid?.()` to check if a user is a root user.", - "example": "import process from 'node:process'\n\nconst isRootUser = process.getuid?.() === 0" + "example": "const isRootUser = process.getuid?.() === 0" }, "snippet::is-set": { "id": "snippet::is-set", @@ -436,7 +436,7 @@ "id": "snippet::is-travis", "type": "simple", "description": "You can check if the current environment is Travis CI by checking if the `TRAVIS` environment variable is set.", - "example": "import process from 'node:process'\n\nBoolean(process.env.TRAVIS)" + "example": "Boolean(process.env.TRAVIS)" }, "snippet::is-typed-array": { "id": "snippet::is-typed-array", @@ -478,7 +478,7 @@ "id": "snippet::is-windows", "type": "simple", "description": "You can check if the current environment is Windows by checking if `process.platform` is equal to \"win32\".", - "example": "import process from 'node:process'\n\nconst isWindows = () => process.platform === \"win32\";" + "example": "const isWindows = () => process.platform === \"win32\";" }, "snippet::is-word-character": { "id": "snippet::is-word-character", @@ -490,7 +490,7 @@ "id": "snippet::is-wsl", "type": "simple", "description": "You can check if the current environment is WSL by checking if the `WSL_DISTRO_NAME` environment variable is set.", - "example": "import process from 'node:process'\n\nBoolean(process.env.WSL_DISTRO_NAME)" + "example": "Boolean(process.env.WSL_DISTRO_NAME)" }, "snippet::json-file": { "id": "snippet::json-file", @@ -556,7 +556,7 @@ "id": "snippet::path-key", "type": "simple", "description": "You can use `Object.keys` with `Array.prototype.findLast` to find the case-insensitive `PATH` environment variable key.", - "example": "import process from 'node:process'\n\nconst pathKey = Object.keys(process.env).findLast((k) => k.toUpperCase() === 'PATH') ?? 'PATH';" + "example": "const pathKey = Object.keys(process.env).findLast((k) => k.toUpperCase() === 'PATH') ?? 'PATH';" }, "snippet::path-root": { "id": "snippet::path-root", @@ -622,7 +622,7 @@ "id": "snippet::typed-array-to-buffer", "type": "simple", "description": "You can use `Buffer.from` to convert a Typed Array to `Buffer` and `ArrayBuffer.isView` to avoid a copy.", - "example": "import { Buffer } from 'node:buffer'\n\nArrayBuffer.isView(arr)\n ? Buffer.from(arr.buffer, arr.byteOffset, arr.byteLength)\n : Buffer.from(arr)" + "example": "ArrayBuffer.isView(arr)\n ? Buffer.from(arr.buffer, arr.byteOffset, arr.byteLength)\n : Buffer.from(arr)" }, "snippet::typeof": { "id": "snippet::typeof",