nano-spawn-compat 2.0.1

package/license

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (https://sindresorhus.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/package.json

@@ -0,0 +1,72 @@
+{
+	"name": "nano-spawn-compat",
+	"version": "2.0.1",
+	"description": "Tiny process execution for humans — a better child_process",
+	"license": "MIT",
+	"repository": "leonsilicon/nano-spawn-compat",
+	"funding": "https://github.com/sindresorhus/nano-spawn?sponsor=1",
+	"author": {
+		"name": "Sindre Sorhus",
+		"url": "https://sindresorhus.com"
+	},
+	"type": "module",
+	"exports": {
+		"types": "./source/index.d.ts",
+		"default": "./source/index.js"
+	},
+	"sideEffects": false,
+	"engines": {
+		"node": ">=20.17"
+	},
+	"scripts": {
+		"test": "xo && c8 ava && npm run type",
+		"type": "tsd -t ./source/index.d.ts -f ./source/index.test-d.ts"
+	},
+	"files": [
+		"source/**/*.js",
+		"source/**/*.d.ts"
+	],
+	"keywords": [
+		"spawn",
+		"exec",
+		"child",
+		"process",
+		"subprocess",
+		"execute",
+		"fork",
+		"execfile",
+		"file",
+		"shell",
+		"bin",
+		"binary",
+		"binaries",
+		"npm",
+		"path",
+		"local",
+		"zx",
+		"execa"
+	],
+	"devDependencies": {
+		"@types/node": "^22.5.4",
+		"ava": "^6.1.3",
+		"c8": "^10.1.2",
+		"get-node": "^15.0.1",
+		"log-process-errors": "^12.0.1",
+		"path-key": "^4.0.0",
+		"tempy": "^3.1.0",
+		"tsd": "^0.32.0",
+		"typescript": "^5.8.3",
+		"xo": "^0.60.0",
+		"yoctocolors": "^2.1.1"
+	},
+	"ava": {
+		"concurrency": 1,
+		"timeout": "240s",
+		"require": [
+			"./test/helpers/setup.js"
+		]
+	},
+	"dependencies": {
+		"strip-ansi": "^7.2.0"
+	}
+}

package/readme.md

@@ -0,0 +1,269 @@
+> This repo is a fork of [nano-spawn](https://github.com/sindresorhus/nano-spawn) by [@sindresorhus](https://github.com/sindresorhus) without depending on `node:readline` and `node:util` in order to support the [QuickJS-based LLRT runtime](https://github.com/awslabs/llrt).
+>
+> Why? Because this package is otherwise perfect for the LLRT runtime since it only relies on `child_process.spawn` which is currently the only [implemented export in `llrt_child_process`](https://github.com/awslabs/llrt/blob/36bd4a837d3fd85b5e3246906f23b1873c067503/modules/llrt_child_process/src/lib.rs#L580).
+
+<h1 align="center" title="nano-spawn">
+	<img src="media/logo.jpg" alt="nano-spawn logo">
+</h1>
+
+![Test coverage](https://img.shields.io/badge/coverage-100%25-green)
+<!-- [![Downloads](https://img.shields.io/npm/dm/nano-spawn.svg)](https://npmjs.com/nano-spawn) -->
+<!-- ![Dependents](https://img.shields.io/librariesio/dependents/npm/nano-spawn) -->
+
+> Tiny process execution for humans — a better [`child_process`](https://nodejs.org/api/child_process.html)
+
+## Features
+
+No dependencies. Small package size: ![npm package minzipped size](https://img.shields.io/bundlejs/size/nano-spawn) [![Install size](https://packagephobia.com/badge?p=nano-spawn)](https://packagephobia.com/result?p=nano-spawn)
+
+Despite the small size, this is packed with some essential features:
+- [Promise-based](#spawnfile-arguments-options-default-export) interface.
+- [Iterate](#subprocesssymbolasynciterator) over the output lines.
+- [Pipe](#subprocesspipefile-arguments-options) multiple subprocesses and retrieve [intermediate results](#resultpipedfrom).
+- Execute [locally installed binaries](#optionspreferlocal) without `npx`.
+- Improved [Windows support](#windows-support).
+- Proper handling of [subprocess failures](#subprocesserror) and better error messages.
+- Get [interleaved output](#resultoutput) from stdout and stderr similar to what is printed on the terminal.
+- Strip [unnecessary newlines](#resultstdout).
+- Pass strings as [`stdin` input](#optionsstdin-optionsstdout-optionsstderr) to the subprocess.
+- Preserve the current [Node.js version and flags](#spawnfile-arguments-options-default-export).
+- Simpler syntax to set [environment variables](#optionsenv) or [`stdin`/`stdout`/`stderr`](#optionsstdin-optionsstdout-optionsstderr).
+- Compute the command [duration](#resultdurationms).
+
+## Install
+
+```sh
+npm install nano-spawn
+```
+
+## Usage
+
+### Run commands
+
+```js
+import spawn from 'nano-spawn';
+
+const result = await spawn('echo', ['🦄']);
+
+console.log(result.output);
+//=> '🦄'
+```
+
+### Iterate over output lines
+
+```js
+for await (const line of spawn('ls', ['--oneline'])) {
+	console.log(line);
+}
+//=> index.d.ts
+//=> index.js
+//=> …
+```
+
+### Pipe commands
+
+```js
+const result = await spawn('npm', ['run', 'build'])
+	.pipe('sort')
+	.pipe('head', ['-n', '2']);
+```
+
+## API
+
+### spawn(file, arguments?, options?) <sup>default export</sup>
+
+`file`: `string`\
+`arguments`: `string[]`\
+`options`: [`Options`](#options)\
+_Returns_: [`Subprocess`](#subprocess)
+
+Executes a command using `file ...arguments`.
+
+This has the same syntax as [`child_process.spawn()`](https://nodejs.org/api/child_process.html#child_processspawncommand-args-options).
+
+If `file` is `'node'`, the current Node.js version and [flags](https://nodejs.org/api/cli.html#options) are inherited.
+
+#### Options
+
+##### options.stdio, options.shell, options.timeout, options.signal, options.cwd, options.killSignal, options.serialization, options.detached, options.uid, options.gid, options.windowsVerbatimArguments, options.windowsHide, options.argv0
+
+All [`child_process.spawn()` options](https://nodejs.org/api/child_process.html#child_processspawncommand-args-options) can be passed to [`spawn()`](#spawnfile-arguments-options-default-export).
+
+##### options.env
+
+_Type_: `object`\
+_Default_: `{}`
+
+Override specific [environment variables](https://en.wikipedia.org/wiki/Environment_variable). Other environment variables are inherited from the current process ([`process.env`](https://nodejs.org/api/process.html#processenv)).
+
+##### options.preferLocal
+
+_Type_: `boolean`\
+_Default_: `false`
+
+Allows executing binaries installed locally with `npm` (or `yarn`, etc.).
+
+##### options.stdin, options.stdout, options.stderr
+
+_Type_: `string | number | Stream | {string: string}`
+
+Subprocess's standard [input](https://en.wikipedia.org/wiki/Standard_streams#Standard_input_(stdin))/[output](https://en.wikipedia.org/wiki/Standard_streams#Standard_output_(stdout))/[error](https://en.wikipedia.org/wiki/Standard_streams#Standard_error_(stderr)).
+
+[All values supported](https://nodejs.org/api/child_process.html#optionsstdio) by `node:child_process` are available. The most common ones are:
+- `'pipe'` (default value): returns the output using [`result.stdout`](#resultstdout), [`result.stderr`](#resultstderr) and [`result.output`](#resultoutput).
+- `'inherit'`: uses the current process's [input](https://nodejs.org/api/process.html#processstdin)/[output](https://nodejs.org/api/process.html#processstdout). This is useful when running in a terminal.
+- `'ignore'`: discards the input/output.
+- [`Stream`](https://nodejs.org/api/stream.html#stream): redirects the input/output from/to a stream. For example, [`fs.createReadStream()`](https://nodejs.org/api/fs.html#fscreatereadstreampath-options)/[`fs.createWriteStream()`](https://nodejs.org/api/fs.html#fscreatewritestreampath-options) can be used, once the stream's [`open`](https://nodejs.org/api/fs.html#event-open) event has been emitted.
+- `{string: '...'}`: passes a string as input to `stdin`.
+
+#### Subprocess
+
+Subprocess started by [`spawn()`](#spawnfile-arguments-options-default-export).
+
+##### await subprocess
+
+_Returns_: [`Result`](#result)\
+_Throws_: [`SubprocessError`](#subprocesserror)
+
+A subprocess is a promise that is either resolved with a successful [`result` object](#result) or rejected with a [`subprocessError`](#error).
+
+##### subprocess.stdout
+
+_Returns_: `AsyncIterable<string>`\
+_Throws_: [`SubprocessError`](#subprocesserror)
+
+Iterates over each [`stdout`](#resultstdout) line, as soon as it is available.
+
+The iteration waits for the subprocess to end (even when using [`break`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/break) or [`return`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/return)). It throws if the subprocess [fails](#subprocesserror). This means you do not need to call [`await subprocess`](#await-subprocess).
+
+##### subprocess.stderr
+
+_Returns_: `AsyncIterable<string>`\
+_Throws_: [`SubprocessError`](#subprocesserror)
+
+Same as [`subprocess.stdout`](#subprocessstdout) but for [`stderr`](#resultstderr) instead.
+
+##### subprocess[Symbol.asyncIterator]\()
+
+_Returns_: `AsyncIterable<string>`\
+_Throws_: [`SubprocessError`](#subprocesserror)
+
+Same as [`subprocess.stdout`](#subprocessstdout) but for both [`stdout` and `stderr`](#resultoutput).
+
+##### subprocess.pipe(file, arguments?, options?)
+
+`file`: `string`\
+`arguments`: `string[]`\
+`options`: [`Options`](#options)\
+_Returns_: [`Subprocess`](#subprocess)
+
+Similar to the `|` symbol in shells. [Pipe](https://nodejs.org/api/stream.html#readablepipedestination-options) the subprocess's[`stdout`](https://en.wikipedia.org/wiki/Standard_streams#Standard_output_(stdout)) to a second subprocess's [`stdin`](https://en.wikipedia.org/wiki/Standard_streams#Standard_input_(stdin)).
+
+This resolves with that second subprocess's [result](#result). If either subprocess is rejected, this is rejected with that subprocess's [error](#subprocesserror) instead.
+
+This follows the same syntax as [`spawn(file, arguments?, options?)`](#spawnfile-arguments-options-default-export). It can be done multiple times in a row.
+
+##### await subprocess.nodeChildProcess
+
+_Type_: `ChildProcess`
+
+Underlying [Node.js child process](https://nodejs.org/api/child_process.html#class-childprocess).
+
+Among other things, this can be used to terminate the subprocess using [`.kill()`](https://nodejs.org/api/child_process.html#subprocesskillsignal) or exchange IPC message using [`.send()`](https://nodejs.org/api/child_process.html#subprocesssendmessage-sendhandle-options-callback).
+
+#### Result
+
+When the subprocess succeeds, its [promise](#await-subprocess) is resolved with an object with the following properties.
+
+##### result.stdout
+
+_Type_: `string`
+
+The output of the subprocess on [standard output](https://en.wikipedia.org/wiki/Standard_streams#Standard_output_(stdout)).
+
+If the output ends with a [newline](https://en.wikipedia.org/wiki/Newline), that newline is automatically stripped.
+
+This is an empty string if either:
+- The [`stdout`](#optionsstdin-optionsstdout-optionsstderr) option is set to another value than `'pipe'` (its default value).
+- The output is being iterated using [`subprocess.stdout`](#subprocessstdout) or [`subprocess[Symbol.asyncIterator]`](#subprocesssymbolasynciterator).
+
+##### result.stderr
+
+_Type_: `string`
+
+Like [`result.stdout`](#resultstdout) but for the [standard error](https://en.wikipedia.org/wiki/Standard_streams#Standard_error_(stderr)) instead.
+
+##### result.output
+
+_Type_: `string`
+
+Like [`result.stdout`](#resultstdout) but for both the [standard output](https://en.wikipedia.org/wiki/Standard_streams#Standard_output_(stdout)) and [standard error](https://en.wikipedia.org/wiki/Standard_streams#Standard_error_(stderr)), interleaved.
+
+##### result.command
+
+_Type_: `string`
+
+The file and arguments that were run.
+
+It is intended for logging or debugging. Since the escaping is fairly basic, it should not be executed directly.
+
+##### result.durationMs
+
+_Type_: `number`
+
+Duration of the subprocess, in milliseconds.
+
+##### result.pipedFrom
+
+_Type_: `Result | SubprocessError | undefined`
+
+If [`subprocess.pipe()`](#subprocesspipefile-arguments-options) was used, the [result](#result) or [error](#subprocesserror) of the other subprocess that was piped into this subprocess.
+
+#### SubprocessError
+
+_Type_: `Error`
+
+When the subprocess fails, its [promise](#await-subprocess) is rejected with this error.
+
+Subprocesses fail either when their [exit code](#subprocesserrorexitcode) is not `0` or when terminated by a [signal](#subprocesserrorsignalname). Other failure reasons include misspelling the command name or using the [`timeout`](https://nodejs.org/api/child_process.html#child_processspawncommand-args-options) option.
+
+Subprocess errors have the same shape as [successful results](#result), with the following additional properties.
+
+This error class is exported, so you can use `if (error instanceof SubprocessError) { ... }`.
+
+##### subprocessError.exitCode
+
+_Type_: `number | undefined`
+
+The numeric [exit code](https://en.wikipedia.org/wiki/Exit_status) of the subprocess that was run.
+
+This is `undefined` when the subprocess could not be started, or when it was terminated by a [signal](#subprocesserrorsignalname).
+
+##### subprocessError.signalName
+
+_Type_: `string | undefined`
+
+The name of the [signal](https://en.wikipedia.org/wiki/Signal_(IPC)) (like [`SIGTERM`](https://en.wikipedia.org/wiki/Signal_(IPC)#SIGTERM)) that terminated the subprocess, sent by either:
+- The current process.
+- Another process. This case is [not supported on Windows](https://nodejs.org/api/process.html#signal-events).
+
+If a signal terminated the subprocess, this property is defined and included in the [error message](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/message). Otherwise it is `undefined`.
+
+## Windows support
+
+This package fixes several cross-platform issues with [`node:child_process`](https://nodejs.org/api/child_process.html). It brings full Windows support for:
+- Node modules binaries (without requiring the [`shell`](https://nodejs.org/api/child_process.html#default-windows-shell) option). This includes running `npm ...` or `yarn ...`.
+- `.cmd`, `.bat`, and other shell files.
+- The [`PATHEXT`](https://wiki.tcl-lang.org/page/PATHEXT) environment variable.
+- Windows-specific [newlines](https://en.wikipedia.org/wiki/Newline#Representation).
+
+## Alternatives
+
+`nano-spawn`'s main goal is to be small, yet useful. Nonetheless, depending on your use case, there are other ways to run subprocesses in Node.js.
+
+## Maintainers
+
+- [Sindre Sorhus](https://github.com/sindresorhus)
+- [@ehmicky](https://github.com/ehmicky)
+- [Leon Si](https://github.com/leonsilicon)
+

package/source/context.js

@@ -0,0 +1,14 @@
+import process from 'node:process';
+import stripAnsi from 'strip-ansi';
+
+export const getContext = raw => ({
+	start: process.hrtime.bigint(),
+	command: raw.map(part => getCommandPart(stripAnsi(part))).join(' '),
+	state: {
+		stdout: '', stderr: '', output: '', isIterating: {}, nonIterable: [false, false],
+	},
+});
+
+const getCommandPart = part => /[^\w./-]/.test(part)
+	? `'${part.replaceAll('\'', '\'\\\'\'')}'`
+	: part;

package/source/index.d.ts

@@ -0,0 +1,250 @@
+import type {ChildProcess, SpawnOptions} from 'node:child_process';
+
+type StdioOption = Readonly<Exclude<SpawnOptions['stdio'], undefined>[number]>;
+type StdinOption = StdioOption | {readonly string?: string};
+
+/**
+Options passed to `nano-spawn`.
+
+All [`child_process.spawn()` options](https://nodejs.org/api/child_process.html#child_processspawncommand-args-options) can be passed.
+*/
+export type Options = Omit<SpawnOptions, 'env' | 'stdio'> & Readonly<Partial<{
+	/**
+	Subprocess's standard [input](https://en.wikipedia.org/wiki/Standard_streams#Standard_input_(stdin)).
+
+	[All values supported](https://nodejs.org/api/child_process.html#optionsstdio) by `node:child_process` are available. The most common ones are:
+	- `'pipe'` (default value): use `nodeChildProcess.stdin` stream.
+	- `'inherit'`: uses the current process's [input](https://nodejs.org/api/process.html#processstdin). This is useful when running in a terminal.
+	- `'ignore'`: discards the input/output.
+	- [`Stream`](https://nodejs.org/api/stream.html#stream): redirects the input from/to a stream. For example, [`fs.createReadStream()`](https://nodejs.org/api/fs.html#fscreatereadstreampath-options) can be used, once the stream's [`open`](https://nodejs.org/api/fs.html#event-open) event has been emitted.
+	- `{string: '...'}`: passes a string as input.
+
+	@default 'pipe'
+	*/
+	stdin: StdinOption;
+
+	/**
+	Subprocess's standard [output](https://en.wikipedia.org/wiki/Standard_streams#Standard_output_(stdout)).
+
+	[All values supported](https://nodejs.org/api/child_process.html#optionsstdio) by `node:child_process` are available. The most common ones are:
+	- `'pipe'` (default value): returns the output using `result.stdout` and `result.output`.
+	- `'inherit'`: uses the current process's [output](https://nodejs.org/api/process.html#processstdout). This is useful when running in a terminal.
+	- `'ignore'`: discards the input/output.
+	- [`Stream`](https://nodejs.org/api/stream.html#stream): redirects the output from/to a stream. For example, [`fs.createWriteStream()`](https://nodejs.org/api/fs.html#fscreatewritestreampath-options) can be used, once the stream's [`open`](https://nodejs.org/api/fs.html#event-open) event has been emitted.
+
+	@default 'pipe'
+	*/
+	stdout: StdioOption;
+
+	/**
+	Subprocess's standard [error](https://en.wikipedia.org/wiki/Standard_streams#Standard_error_(stderr)).
+
+	[All values supported](https://nodejs.org/api/child_process.html#optionsstdio) by `node:child_process` are available. The most common ones are:
+	- `'pipe'` (default value): returns the output using `result.stderr` and `result.output`.
+	- `'inherit'`: uses the current process's [output](https://nodejs.org/api/process.html#processstdout). This is useful when running in a terminal.
+	- `'ignore'`: discards the input/output.
+	- [`Stream`](https://nodejs.org/api/stream.html#stream): redirects the output from/to a stream. For example, [`fs.createWriteStream()`](https://nodejs.org/api/fs.html#fscreatewritestreampath-options) can be used, once the stream's [`open`](https://nodejs.org/api/fs.html#event-open) event has been emitted.
+
+	@default 'pipe'
+	*/
+	stderr: StdioOption;
+
+	/**
+	Subprocess's standard [input](https://en.wikipedia.org/wiki/Standard_streams#Standard_input_(stdin))/[output](https://en.wikipedia.org/wiki/Standard_streams#Standard_output_(stdout))/[error](https://en.wikipedia.org/wiki/Standard_streams#Standard_error_(stderr)).
+
+	[All values supported](https://nodejs.org/api/child_process.html#optionsstdio) by `node:child_process` are available. The most common ones are:
+	- `'pipe'` (default value): returns the output using `result.stdout`, `result.stderr` and `result.output`.
+	- `'inherit'`: uses the current process's [input](https://nodejs.org/api/process.html#processstdin)/[output](https://nodejs.org/api/process.html#processstdout). This is useful when running in a terminal.
+	- `'ignore'`: discards the input/output.
+	- [`Stream`](https://nodejs.org/api/stream.html#stream): redirects the input/output from/to a stream. For example, [`fs.createReadStream()`](https://nodejs.org/api/fs.html#fscreatereadstreampath-options)/[`fs.createWriteStream()`](https://nodejs.org/api/fs.html#fscreatewritestreampath-options) can be used, once the stream's [`open`](https://nodejs.org/api/fs.html#event-open) event has been emitted.
+	- `{string: '...'}`: passes a string as input to `stdin`.
+
+	@default ['pipe', 'pipe', 'pipe']
+	*/
+	stdio: SpawnOptions['stdio'] | readonly [StdinOption, ...readonly StdioOption[]];
+
+	/**
+	Allows executing binaries installed locally with `npm` (or `yarn`, etc.).
+
+	@default false
+	*/
+	preferLocal: boolean;
+
+	// Fixes issues with Remix and Next.js
+	// See https://github.com/sindresorhus/execa/pull/1141
+	/**
+	Override specific [environment variables](https://en.wikipedia.org/wiki/Environment_variable). Other environment variables are inherited from the current process ([`process.env`](https://nodejs.org/api/process.html#processenv)).
+
+	@default {}
+	*/
+	env: Readonly<Partial<Record<string, string>>>;
+}>>;
+
+/**
+When the subprocess succeeds, its promise is resolved with this object.
+*/
+export type Result = {
+	/**
+	The output of the subprocess on [standard output](https://en.wikipedia.org/wiki/Standard_streams#Standard_output_(stdout)).
+
+	If the output ends with a [newline](https://en.wikipedia.org/wiki/Newline), that newline is automatically stripped.
+
+	This is an empty string if either:
+	- The `stdout` option is set to another value than `'pipe'` (its default value).
+	- The output is being iterated using `subprocess.stdout` or `subprocess[Symbol.asyncIterator]`.
+	*/
+	stdout: string;
+
+	/**
+	The output of the subprocess on [standard error](https://en.wikipedia.org/wiki/Standard_streams#Standard_error_(stderr)).
+
+	If the output ends with a [newline](https://en.wikipedia.org/wiki/Newline), that newline is automatically stripped.
+
+	This is an empty string if either:
+	- The `stderr` option is set to another value than `'pipe'` (its default value).
+	- The output is being iterated using `subprocess.stderr` or `subprocess[Symbol.asyncIterator]`.
+	*/
+	stderr: string;
+
+	/**
+	Like `result.stdout` but for both the [standard output](https://en.wikipedia.org/wiki/Standard_streams#Standard_output_(stdout)) and [standard error](https://en.wikipedia.org/wiki/Standard_streams#Standard_error_(stderr)), interleaved.
+	*/
+	output: string;
+
+	/**
+	The file and arguments that were run.
+
+	It is intended for logging or debugging. Since the escaping is fairly basic, it should not be executed directly.
+	*/
+	command: string;
+
+	/**
+	Duration of the subprocess, in milliseconds.
+	*/
+	durationMs: number;
+
+	/**
+	If `subprocess.pipe()` was used, the result or error of the other subprocess that was piped into this subprocess.
+	*/
+	pipedFrom?: Result | SubprocessError;
+};
+
+/**
+When the subprocess fails, its promise is rejected with this error.
+
+Subprocesses fail either when their exit code is not `0` or when terminated by a signal. Other failure reasons include misspelling the command name or using the [`timeout`](https://nodejs.org/api/child_process.html#child_processspawncommand-args-options) option.
+*/
+export class SubprocessError extends Error implements Result {
+	stdout: Result['stdout'];
+	stderr: Result['stderr'];
+	output: Result['output'];
+	command: Result['command'];
+	durationMs: Result['durationMs'];
+	pipedFrom?: Exclude<Result['pipedFrom'], undefined>;
+
+	/**
+	The numeric [exit code](https://en.wikipedia.org/wiki/Exit_status) of the subprocess that was run.
+
+	This is `undefined` when the subprocess could not be started, or when it was terminated by a signal.
+	*/
+	exitCode?: number;
+
+	/**
+	The name of the [signal](https://en.wikipedia.org/wiki/Signal_(IPC)) (like [`SIGTERM`](https://en.wikipedia.org/wiki/Signal_(IPC)#SIGTERM)) that terminated the subprocess, sent by either:
+	- The current process.
+	- Another process. This case is [not supported on Windows](https://nodejs.org/api/process.html#signal-events).
+
+	If a signal terminated the subprocess, this property is defined and included in the [error message](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/message). Otherwise it is `undefined`.
+	*/
+	signalName?: string;
+}
+
+/**
+Subprocess started by `spawn()`.
+
+A subprocess is a promise that is either resolved with a successful `result` object or rejected with a `subprocessError`.
+
+It is also an iterable, iterating over each `stdout`/`stderr` line, as soon as it is available. The iteration waits for the subprocess to end (even when using [`break`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/break) or [`return`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/return)). It throws if the subprocess fails. This means you do not need to call `await subprocess`.
+*/
+export type Subprocess = Promise<Result> & AsyncIterable<string> & {
+	/**
+	Underlying [Node.js child process](https://nodejs.org/api/child_process.html#class-childprocess).
+
+	Among other things, this can be used to terminate the subprocess using [`.kill()`](https://nodejs.org/api/child_process.html#subprocesskillsignal) or exchange IPC message using [`.send()`](https://nodejs.org/api/child_process.html#subprocesssendmessage-sendhandle-options-callback).
+	*/
+	nodeChildProcess: Promise<ChildProcess>;
+
+	/**
+	Iterates over each `stdout` line, as soon as it is available.
+
+	The iteration waits for the subprocess to end (even when using [`break`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/break) or [`return`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/return)). It throws if the subprocess fails. This means you do not need to call `await subprocess`.
+	*/
+	stdout: AsyncIterable<string>;
+
+	/**
+	Iterates over each `stderr` line, as soon as it is available.
+
+	The iteration waits for the subprocess to end (even when using [`break`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/break) or [`return`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/return)). It throws if the subprocess fails. This means you do not need to call `await subprocess`.
+	*/
+	stderr: AsyncIterable<string>;
+
+	/**
+	Similar to the `|` symbol in shells. [Pipe](https://nodejs.org/api/stream.html#readablepipedestination-options) the subprocess's[`stdout`](https://en.wikipedia.org/wiki/Standard_streams#Standard_output_(stdout)) to a second subprocess's [`stdin`](https://en.wikipedia.org/wiki/Standard_streams#Standard_input_(stdin)).
+
+	This resolves with that second subprocess's result. If either subprocess is rejected, this is rejected with that subprocess's error instead.
+
+	This follows the same syntax as `spawn(file, arguments?, options?)`. It can be done multiple times in a row.
+
+	@param file - The program/script to execute
+	@param arguments - Arguments to pass to `file` on execution.
+	@param options
+	@returns `Subprocess`
+
+	@example
+
+	```
+	const result = await spawn('npm', ['run', 'build'])
+		.pipe('sort')
+		.pipe('head', ['-n', '2']);
+	```
+	*/
+	pipe(file: string, arguments?: readonly string[], options?: Options): Subprocess;
+	pipe(file: string, options?: Options): Subprocess;
+};
+
+/**
+Executes a command using `file ...arguments`.
+
+This has the same syntax as [`child_process.spawn()`](https://nodejs.org/api/child_process.html#child_processspawncommand-args-options).
+
+If `file` is `'node'`, the current Node.js version and [flags](https://nodejs.org/api/cli.html#options) are inherited.
+
+@param file - The program/script to execute
+@param arguments - Arguments to pass to `file` on execution.
+@param options
+@returns `Subprocess`
+
+@example <caption>Run commands</caption>
+
+```
+import spawn from 'nano-spawn';
+
+const result = await spawn('echo', ['🦄']);
+
+console.log(result.output);
+//=> '🦄'
+```
+
+@example <caption>Iterate over output lines</caption>
+
+```
+for await (const line of spawn('ls', ['--oneline'])) {
+	console.log(line);
+}
+//=> index.d.ts
+//=> index.js
+//=> …
+```
+*/
+export default function spawn(file: string, arguments?: readonly string[], options?: Options): Subprocess;
+export default function spawn(file: string, options?: Options): Subprocess;

package/source/index.js

@@ -0,0 +1,28 @@
+import {getContext} from './context.js';
+import {getOptions} from './options.js';
+import {spawnSubprocess} from './spawn.js';
+import {getResult} from './result.js';
+import {handlePipe} from './pipe.js';
+import {lineIterator, combineAsyncIterators} from './iterable.js';
+
+export {SubprocessError} from './result.js';
+
+export default function spawn(file, second, third, previous) {
+	const [commandArguments = [], options = {}] = Array.isArray(second) ? [second, third] : [[], second];
+	const context = getContext([file, ...commandArguments]);
+	const spawnOptions = getOptions(options);
+	const nodeChildProcess = spawnSubprocess(file, commandArguments, spawnOptions, context);
+	let subprocess = getResult(nodeChildProcess, spawnOptions, context);
+	Object.assign(subprocess, {nodeChildProcess});
+	subprocess = previous ? handlePipe([previous, subprocess]) : subprocess;
+
+	const stdout = lineIterator(subprocess, context, 'stdout', 0);
+	const stderr = lineIterator(subprocess, context, 'stderr', 1);
+	return Object.assign(subprocess, {
+		nodeChildProcess,
+		stdout,
+		stderr,
+		[Symbol.asyncIterator]: () => combineAsyncIterators(context, stdout, stderr),
+		pipe: (file, second, third) => spawn(file, second, third, subprocess),
+	});
+}

package/source/iterable.js

@@ -0,0 +1,88 @@
+export const lineIterator = async function * (subprocess, {state}, streamName, index) {
+	// Prevent buffering when iterating.
+	// This would defeat one of the main goals of iterating: low memory consumption.
+	if (state.isIterating[streamName] === false) {
+		throw new Error(`The subprocess must be iterated right away, for example:
+	for await (const line of spawn(...)) { ... }`);
+	}
+
+	state.isIterating[streamName] = true;
+
+	try {
+		const {[streamName]: stream} = await subprocess.nodeChildProcess;
+		if (!stream) {
+			state.nonIterable[index] = true;
+			const message = state.nonIterable.every(Boolean)
+				? 'either the option `stdout` or `stderr`'
+				: `the option \`${streamName}\``;
+			throw new TypeError(
+				`The subprocess cannot be iterated unless ${message} is 'pipe'.`,
+			);
+		}
+
+		handleErrors(subprocess);
+
+		// Reverted to before https://github.com/sindresorhus/nano-spawn/commit/51e8d8f481d1fc8210d19005efb1d70339683721 to avoid depending on "node:readline"
+		let buffer = '';
+		for await (const chunk of stream.iterator({destroyOnReturn: false})) {
+			const lines = `${buffer}${chunk}`.split(/\r?\n/);
+			buffer = lines.pop(); // Keep last line in buffer as it may not be complete
+			yield * lines;
+		}
+
+		if (buffer) {
+			yield buffer; // Yield any remaining data as the last line
+		}
+	} finally {
+		await subprocess;
+	}
+};
+
+// When the `subprocess` promise is rejected, we await it in the `finally`
+// block. However, this might not happen right away, so an `unhandledRejection`
+// error is emitted first, crashing the process. This prevents it.
+// This is safe since we are guaranteed to propagate the `subprocess` error
+// with the `finally` block.
+// See https://github.com/sindresorhus/nano-spawn/issues/104
+const handleErrors = async subprocess => {
+	try {
+		await subprocess;
+	} catch {}
+};
+
+// Merge two async iterators into one
+export const combineAsyncIterators = async function * ({state}, ...iterators) {
+	try {
+		let promises = [];
+		while (iterators.length > 0) {
+			promises = iterators.map((iterator, index) => promises[index] ?? getNext(iterator, index, state));
+			// eslint-disable-next-line no-await-in-loop
+			const [{value, done}, index] = await Promise.race(promises
+				.map((promise, index) => Promise.all([promise, index])));
+
+			const [iterator] = iterators.splice(index, 1);
+			promises.splice(index, 1);
+
+			if (!done) {
+				iterators.push(iterator);
+				yield value;
+			}
+		}
+	} finally {
+		await Promise.all(iterators.map(iterator => iterator.return()));
+	}
+};
+
+const getNext = async (iterator, index, {nonIterable}) => {
+	try {
+		return await iterator.next();
+	} catch (error) {
+		return shouldIgnoreError(nonIterable, index)
+			? iterator.return()
+			: iterator.throw(error);
+	}
+};
+
+const shouldIgnoreError = (nonIterable, index) => nonIterable.every(Boolean)
+	? index !== nonIterable.length - 1
+	: nonIterable[index];

package/source/options.js

@@ -0,0 +1,37 @@
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import process from 'node:process';
+
+export const getOptions = ({
+	stdin,
+	stdout,
+	stderr,
+	stdio = [stdin, stdout, stderr],
+	env: envOption,
+	preferLocal,
+	cwd: cwdOption = '.',
+	...options
+}) => {
+	const cwd = cwdOption instanceof URL ? fileURLToPath(cwdOption) : path.resolve(cwdOption);
+	const env = envOption ? {...process.env, ...envOption} : undefined;
+	const input = stdio[0]?.string;
+	return {
+		...options,
+		input,
+		stdio: input === undefined ? stdio : ['pipe', ...stdio.slice(1)],
+		env: preferLocal ? addLocalPath(env ?? process.env, cwd) : env,
+		cwd,
+	};
+};
+
+const addLocalPath = ({Path = '', PATH = Path, ...env}, cwd) => {
+	const pathParts = PATH.split(path.delimiter);
+	const localPaths = getLocalPaths([], path.resolve(cwd))
+		.map(localPath => path.join(localPath, 'node_modules/.bin'))
+		.filter(localPath => !pathParts.includes(localPath));
+	return {...env, PATH: [...localPaths, PATH].filter(Boolean).join(path.delimiter)};
+};
+
+const getLocalPaths = (localPaths, localPath) => localPaths.at(-1) === localPath
+	? localPaths
+	: getLocalPaths([...localPaths, localPath], path.resolve(localPath, '..'));

package/source/pipe.js

@@ -0,0 +1,43 @@
+import {pipeline} from 'node:stream/promises';
+
+export const handlePipe = async subprocesses => {
+	// Ensure both subprocesses have exited before resolving, and that we handle errors from both
+	const [[from, to]] = await Promise.all([Promise.allSettled(subprocesses), pipeStreams(subprocesses)]);
+
+	// If both subprocesses fail, throw destination error to use a predictable order and avoid race conditions
+	if (to.reason) {
+		to.reason.pipedFrom = from.reason ?? from.value;
+		throw to.reason;
+	}
+
+	if (from.reason) {
+		throw from.reason;
+	}
+
+	return {...to.value, pipedFrom: from.value};
+};
+
+const pipeStreams = async subprocesses => {
+	try {
+		const [{stdout}, {stdin}] = await Promise.all(subprocesses.map(({nodeChildProcess}) => nodeChildProcess));
+		if (stdin === null) {
+			throw new Error('The "stdin" option must be set on the first "spawn()" call in the pipeline.');
+		}
+
+		if (stdout === null) {
+			throw new Error('The "stdout" option must be set on the last "spawn()" call in the pipeline.');
+		}
+
+		// Do not `await` nor handle stream errors since this is already done by each subprocess
+		// eslint-disable-next-line promise/prefer-await-to-then
+		pipeline(stdout, stdin).catch(() => {});
+	} catch (error) {
+		await Promise.allSettled(subprocesses.map(({nodeChildProcess}) => closeStdin(nodeChildProcess)));
+		throw error;
+	}
+};
+
+const closeStdin = async nodeChildProcess => {
+	const {stdin} = await nodeChildProcess;
+	stdin.end();
+};

package/source/result.js

@@ -0,0 +1,74 @@
+import {once, on} from 'node:events';
+import process from 'node:process';
+
+export const getResult = async (nodeChildProcess, {input}, context) => {
+	const instance = await nodeChildProcess;
+	if (input !== undefined) {
+		instance.stdin.end(input);
+	}
+
+	const onClose = once(instance, 'close');
+
+	try {
+		await Promise.race([
+			onClose,
+			...instance.stdio.filter(Boolean).map(stream => onStreamError(stream)),
+		]);
+		checkFailure(context, getErrorOutput(instance));
+		return getOutputs(context);
+	} catch (error) {
+		await Promise.allSettled([onClose]);
+		throw getResultError(error, instance, context);
+	}
+};
+
+const onStreamError = async stream => {
+	for await (const [error] of on(stream, 'error')) {
+		// Ignore errors that are due to closing errors when the subprocesses exit normally, or due to piping
+		if (!['ERR_STREAM_PREMATURE_CLOSE', 'EPIPE'].includes(error?.code)) {
+			throw error;
+		}
+	}
+};
+
+const checkFailure = ({command}, {exitCode, signalName}) => {
+	if (signalName !== undefined) {
+		throw new SubprocessError(`Command was terminated with ${signalName}: ${command}`);
+	}
+
+	if (exitCode !== undefined) {
+		throw new SubprocessError(`Command failed with exit code ${exitCode}: ${command}`);
+	}
+};
+
+export const getResultError = (error, instance, context) => Object.assign(
+	getErrorInstance(error, context),
+	getErrorOutput(instance),
+	getOutputs(context),
+);
+
+const getErrorInstance = (error, {command}) => error instanceof SubprocessError
+	? error
+	: new SubprocessError(`Command failed: ${command}`, {cause: error});
+
+export class SubprocessError extends Error {
+	name = 'SubprocessError';
+}
+
+const getErrorOutput = ({exitCode, signalCode}) => ({
+	// `exitCode` can be a negative number (`errno`) when the `error` event is emitted on the `instance`
+	...(exitCode < 1 ? {} : {exitCode}),
+	...(signalCode === null ? {} : {signalName: signalCode}),
+});
+
+const getOutputs = ({state: {stdout, stderr, output}, command, start}) => ({
+	stdout: getOutput(stdout),
+	stderr: getOutput(stderr),
+	output: getOutput(output),
+	command,
+	durationMs: Number(process.hrtime.bigint() - start) / 1e6,
+});
+
+const getOutput = output => output.at(-1) === '\n'
+	? output.slice(0, output.at(-2) === '\r' ? -2 : -1)
+	: output;

package/source/spawn.js

@@ -0,0 +1,59 @@
+import {spawn} from 'node:child_process';
+import {once} from 'node:events';
+import process from 'node:process';
+import {applyForceShell} from './windows.js';
+import {getResultError} from './result.js';
+
+export const spawnSubprocess = async (file, commandArguments, options, context) => {
+	try {
+		// When running `node`, keep the current Node version and CLI flags.
+		// Not applied with file paths to `.../node` since those indicate a clear intent to use a specific Node version.
+		// This also provides a way to opting out, e.g. using `process.execPath` instead of `node` to discard current CLI flags.
+		// Does not work with shebangs, but those don't work cross-platform anyway.
+		if (['node', 'node.exe'].includes(file.toLowerCase())) {
+			file = process.execPath;
+			commandArguments = [...process.execArgv.filter(flag => !flag.startsWith('--inspect')), ...commandArguments];
+		}
+
+		[file, commandArguments, options] = await applyForceShell(file, commandArguments, options);
+		[file, commandArguments, options] = concatenateShell(file, commandArguments, options);
+		const instance = spawn(file, commandArguments, options);
+		bufferOutput(instance.stdout, context, 'stdout');
+		bufferOutput(instance.stderr, context, 'stderr');
+
+		// The `error` event is caught by `once(instance, 'spawn')` and `once(instance, 'close')`.
+		// But it creates an uncaught exception if it happens exactly one tick after 'spawn'.
+		// This prevents that.
+		instance.once('error', () => {});
+
+		await once(instance, 'spawn');
+		return instance;
+	} catch (error) {
+		throw getResultError(error, {}, context);
+	}
+};
+
+// When the `shell` option is set, any command argument is concatenated as a single string by Node.js:
+// https://github.com/nodejs/node/blob/e38ce27f3ca0a65f68a31cedd984cddb927d4002/lib/child_process.js#L614-L624
+// However, since Node 24, it also prints a deprecation warning.
+// To avoid this warning, we perform that same operation before calling `node:child_process`.
+// Shells only understand strings, which is why Node.js performs that concatenation.
+// However, we rely on users splitting command arguments as an array.
+// For example, this allows us to easily detect whether the binary file is `node` or `node.exe`.
+// So we do want users to pass array of arguments even with `shell: true`, but we also want to avoid any warning.
+const concatenateShell = (file, commandArguments, options) => options.shell && commandArguments.length > 0
+	? [[file, ...commandArguments].join(' '), [], options]
+	: [file, commandArguments, options];
+
+const bufferOutput = (stream, {state}, streamName) => {
+	if (stream) {
+		stream.setEncoding('utf8');
+		if (!state.isIterating[streamName]) {
+			state.isIterating[streamName] = false;
+			stream.on('data', chunk => {
+				state[streamName] += chunk;
+				state.output += chunk;
+			});
+		}
+	}
+};

package/source/windows.js

@@ -0,0 +1,71 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+
+// When setting `shell: true` under-the-hood, we must manually escape the file and arguments.
+// This ensures arguments are properly split, and prevents command injection.
+export const applyForceShell = async (file, commandArguments, options) => await shouldForceShell(file, options)
+	? [escapeFile(file), commandArguments.map(argument => escapeArgument(argument)), {...options, shell: true}]
+	: [file, commandArguments, options];
+
+// On Windows, running most executable files (except *.exe and *.com) requires using a shell.
+// This includes *.cmd and *.bat, which itself includes Node modules binaries.
+// We detect this situation and automatically:
+//  - Set the `shell: true` option
+//  - Escape shell-specific characters
+const shouldForceShell = async (file, {shell, cwd, env = process.env}) => process.platform === 'win32'
+	&& !shell
+	&& !(await isExe(file, cwd, env));
+
+// Detect whether the executable file is a *.exe or *.com file.
+// Windows allows omitting file extensions (present in the `PATHEXT` environment variable).
+// Therefore we must use the `PATH` environment variable and make `access` calls to check this.
+// Environment variables are case-insensitive on Windows, so we check both `PATH` and `Path`.
+const isExe = (file, cwd, {Path = '', PATH = Path}) =>
+	// If the *.exe or *.com file extension was not omitted.
+	// Windows common file systems are case-insensitive.
+	exeExtensions.some(extension => file.toLowerCase().endsWith(extension))
+	|| mIsExe(file, cwd, PATH);
+
+// Memoize the `mIsExe` and `fs.access`, for performance
+const EXE_MEMO = {};
+// eslint-disable-next-line no-return-assign
+const memoize = function_ => (...arguments_) =>
+	// Use returned assignment to keep code small
+	EXE_MEMO[arguments_.join('\0')] ??= function_(...arguments_);
+
+const access = memoize(fs.access);
+const mIsExe = memoize(async (file, cwd, PATH) => {
+	const parts = PATH
+		// `PATH` is ;-separated on Windows
+		.split(path.delimiter)
+		// `PATH` allows leading/trailing ; on Windows
+		.filter(Boolean)
+		// `PATH` parts can be double quoted on Windows
+		.map(part => part.replace(/^"(.*)"$/, '$1'));
+
+	// For performance, parallelize and stop iteration as soon as an *.exe or *.com file is found
+	try {
+		await Promise.any(
+			[cwd, ...parts].flatMap(part => exeExtensions
+				.map(extension => access(`${path.resolve(part, file)}${extension}`)),
+			),
+		);
+	} catch {
+		return false;
+	}
+
+	return true;
+});
+
+// Other file extensions require using a shell
+const exeExtensions = ['.exe', '.com'];
+
+// `cmd.exe` escaping for arguments.
+// Taken from https://github.com/moxystudio/node-cross-spawn
+const escapeArgument = argument => escapeFile(escapeFile(`"${argument
+	.replaceAll(/(\\*)"/g, '$1$1\\"')
+	.replace(/(\\*)$/, '$1$1')}"`));
+
+// `cmd.exe` escaping for file and arguments.
+const escapeFile = file => file.replaceAll(/([()\][%!^"`<>&|;, *?])/g, '^$1');