Skip to main content

Subprocess

Spawn and manage child processes, execute commands, and collect output. Useful for executing external programs from Deno.

Eg Deno.Command

Classes

c
Deno.ChildProcess

The interface for handling a child process returned from Deno.Command.spawn.

c
Deno.Command

Create a child process.

Functions

f
Deno.kill

Send a signal to process under given pid. The value and meaning of the signal to the process is operating system and process dependant. Signal provides the most common signals. Default signal is "SIGTERM".

    f
    Deno.spawn

    Spawns a new subprocess, returning a Deno.ChildProcess handle.

      f
      Deno.spawnAndWait

      Spawns a subprocess, waits for it to finish, and returns the output.

        f
        Deno.spawnAndWaitSync

        Synchronously spawns a subprocess, waits for it to finish, and returns the output.

          Interfaces

          I
          Deno.CommandOutput

          The interface returned from calling Deno.Command.output or Deno.Command.outputSync which represents the result of spawning the child process.

          I
          Deno.CommandStatus
          No documentation available
          I
          Deno.SubprocessReadableStream

          The interface for stdout and stderr streams for child process returned from Deno.Command.spawn.

          class Deno.ChildProcess

          implements AsyncDisposable

          The interface for handling a child process returned from Deno.Command.spawn.

          Properties #

          #pid: number
          readonly
          #status: Promise<CommandStatus>
          readonly

          Get the status of the child.

          #stdin: WritableStream<Uint8Array<ArrayBufferLike>>
          readonly

          Methods #

          #[Symbol.asyncDispose](): Promise<void>
          #kill(signo?: Signal | number): void

          Kills the process with given Deno.Signal or numeric signal.

          Defaults to SIGTERM if no signal is provided.

          #output(): Promise<CommandOutput>

          Waits for the child to exit completely, returning all its output and status.

          #ref(): void

          Ensure that the status of the child process prevents the Deno process from exiting.

          #unref(): void

          Ensure that the status of the child process does not block the Deno process from exiting.

          class Deno.Command

          allow-run

          Create a child process.

          If any stdio options are not set to "piped", accessing the corresponding field on the Command or its CommandOutput will throw a TypeError.

          If stdin is set to "piped", the stdin WritableStream needs to be closed manually.

          Command acts as a builder. Each call to Command.spawn or Command.output will spawn a new subprocess.

          Examples #

          #
          const command = new Deno.Command(Deno.execPath(), {
  args: [
    "eval",
    "console.log('Hello World')",
  ],
  stdin: "piped",
  stdout: "piped",
});
const child = command.spawn();

// open a file and pipe the subprocess output to it.
child.stdout.pipeTo(
  Deno.openSync("output", { write: true, create: true }).writable,
);

// manually close stdin
child.stdin.close();
const status = await child.status;
          #
          const command = new Deno.Command(Deno.execPath(), {
  args: [
    "eval",
    "console.log('hello'); console.error('world')",
  ],
});
const { code, stdout, stderr } = await command.output();
console.assert(code === 0);
console.assert("hello\n" === new TextDecoder().decode(stdout));
console.assert("world\n" === new TextDecoder().decode(stderr));
          #
          const command = new Deno.Command(Deno.execPath(), {
  args: [
    "eval",
    "console.log('hello'); console.error('world')",
  ],
});
const { code, stdout, stderr } = command.outputSync();
console.assert(code === 0);
console.assert("hello\n" === new TextDecoder().decode(stdout));
console.assert("world\n" === new TextDecoder().decode(stderr));

          Constructors #

          #Command(
          command: string | URL,
          options?: CommandOptions,
          )
          new

          Methods #

          #output(): Promise<CommandOutput>

          Executes the Deno.Command, waiting for it to finish and collecting all of its output.

          Will throw an error if stdin: "piped" is set.

          If options stdout or stderr are not set to "piped", accessing the corresponding field on Deno.CommandOutput will throw a TypeError.

          #outputSync(): CommandOutput

          Synchronously executes the Deno.Command, waiting for it to finish and collecting all of its output.

          Will throw an error if stdin: "piped" is set.

          If options stdout or stderr are not set to "piped", accessing the corresponding field on Deno.CommandOutput will throw a TypeError.

          #spawn(): ChildProcess

          Spawns a streamable subprocess, allowing to use the other methods.

          function Deno.kill

          allow-run
          #kill(
          pid: number,
          signo?: Signal | number,
          ): void

          Send a signal to process under given pid. The value and meaning of the signal to the process is operating system and process dependant. Signal provides the most common signals. Default signal is "SIGTERM".

          The term kill is adopted from the UNIX-like command line command kill which also signals processes.

          If pid is negative, the signal will be sent to the process group identified by pid. An error will be thrown if a negative pid is used on Windows.

          const command = new Deno.Command("sleep", { args: ["10000"] });
const child = command.spawn();

Deno.kill(child.pid, "SIGINT");

          As a special case, a signal of 0 can be used to test for the existence of a process.

          Requires allow-run permission.

          Parameters #

          #pid: number
          #signo: Signal | number
          optional

          Return Type #

          void

          function Deno.spawn

          unstable
          allow-run

          Overload 1

          #spawn(
          command: string | URL,
          options?: CommandOptions,
          ): ChildProcess

          Spawns a new subprocess, returning a Deno.ChildProcess handle.

          Examples #

          #
          const child = Deno.spawn(Deno.execPath(), {
  args: ["eval", "console.log('hello')"],
  stdout: "piped",
});
const output = await child.stdout.text();
console.log(output); // "hello\n"
const status = await child.status;

          Parameters #

          #command: string | URL
          #options: CommandOptions
          optional

          Return Type #

          ChildProcess

          Overload 2

          #spawn(
          command: string | URL,
          args: string[],
          options?: Omit<CommandOptions, "args">,
          ): ChildProcess

          Spawns a new subprocess with the given arguments, returning a Deno.ChildProcess handle.

          Examples #

          #
          const child = Deno.spawn(Deno.execPath(), ["eval", "console.log('hello')"], {
  stdout: "piped",
});
const output = await child.stdout.text();
console.log(output); // "hello\n"
const status = await child.status;

          Parameters #

          #command: string | URL
          #args: string[]
          #options: Omit<CommandOptions, "args">
          optional

          Return Type #

          ChildProcess

          function Deno.spawnAndWait

          unstable
          allow-run

          Overload 1

          #spawnAndWait(
          command: string | URL,
          options?: CommandOptions,
          ): Promise<CommandOutput>

          Spawns a subprocess, waits for it to finish, and returns the output.

          Examples #

          #
          const { code, stdout, stderr } = await Deno.spawnAndWait(Deno.execPath(), {
  args: ["eval", "console.log('hello')"],
});
console.log(new TextDecoder().decode(stdout)); // "hello\n"

          Parameters #

          #command: string | URL
          #options: CommandOptions
          optional

          Return Type #

          Promise<CommandOutput>

          Overload 2

          #spawnAndWait(
          command: string | URL,
          args: string[],
          options?: Omit<CommandOptions, "args">,
          ): Promise<CommandOutput>

          Spawns a subprocess with the given arguments, waits for it to finish, and returns the output.

          Examples #

          #
          const { code, stdout } = await Deno.spawnAndWait(
  Deno.execPath(),
  ["eval", "console.log('hello')"],
);
console.log(new TextDecoder().decode(stdout)); // "hello\n"

          Parameters #

          #command: string | URL
          #args: string[]
          #options: Omit<CommandOptions, "args">
          optional

          Return Type #

          Promise<CommandOutput>

          function Deno.spawnAndWaitSync

          unstable
          allow-run

          Overload 1

          #spawnAndWaitSync(
          command: string | URL,
          options?: CommandOptions,
          ): CommandOutput

          Synchronously spawns a subprocess, waits for it to finish, and returns the output.

          Examples #

          #
          const { code, stdout } = Deno.spawnAndWaitSync(Deno.execPath(), {
  args: ["eval", "console.log('hello')"],
});
console.log(new TextDecoder().decode(stdout)); // "hello\n"

          Parameters #

          #command: string | URL
          #options: CommandOptions
          optional

          Return Type #

          CommandOutput

          Overload 2

          #spawnAndWaitSync(
          command: string | URL,
          args: string[],
          options?: Omit<CommandOptions, "args">,
          ): CommandOutput

          Synchronously spawns a subprocess with the given arguments, waits for it to finish, and returns the output.

          Examples #

          #
          const { code, stdout } = Deno.spawnAndWaitSync(
  Deno.execPath(),
  ["eval", "console.log('hello')"],
);
console.log(new TextDecoder().decode(stdout)); // "hello\n"

          Parameters #

          #command: string | URL
          #args: string[]
          #options: Omit<CommandOptions, "args">
          optional

          Return Type #

          CommandOutput

          interface Deno.CommandOptions

          Options which can be set when calling Deno.Command.

          Properties #

          #args: string[]
          optional

          Arguments to pass to the process.

          #cwd: string | URL
          optional

          The working directory of the process.

          If not specified, the cwd of the parent process is used.

          #clearEnv: boolean = false
          optional

          Clear environmental variables from parent process.

          Doesn't guarantee that only env variables are present, as the OS may set environmental variables for processes.

          #env: Record<string, string>
          optional

          Environmental variables to pass to the subprocess.

          #uid: number
          optional

          Sets the child process’s user ID. This translates to a setuid call in the child process. Failure in the set uid call will cause the spawn to fail.

          #gid: number
          optional

          Similar to uid, but sets the group ID of the child process.

          #signal: AbortSignal
          optional

          An AbortSignal that allows closing the process using the corresponding AbortController by sending the process a SIGTERM signal.

          Not supported in Deno.Command.outputSync.

          #stdin:
          "piped"
          | "inherit"
          | "null"
          optional

          How stdin of the spawned process should be handled.

          Defaults to "inherit" for output & outputSync, and "inherit" for spawn.

          #stdout:
          "piped"
          | "inherit"
          | "null"
          optional

          How stdout of the spawned process should be handled.

          Defaults to "piped" for output & outputSync, and "inherit" for spawn.

          #stderr:
          "piped"
          | "inherit"
          | "null"
          optional

          How stderr of the spawned process should be handled.

          Defaults to "piped" for output & outputSync, and "inherit" for spawn.

          #windowsRawArguments: boolean = false
          optional

          Skips quoting and escaping of the arguments on windows. This option is ignored on non-windows platforms.

          #detached: boolean = false
          optional

          Whether to detach the spawned process from the current process. This allows the spawned process to continue running after the current process exits.

          Note: In order to allow the current process to exit, you need to ensure you call unref() on the child process.

          In addition, the stdio streams – if inherited or piped – may keep the current process from exiting until the streams are closed.

          interface Deno.CommandOutput

          The interface returned from calling Deno.Command.output or Deno.Command.outputSync which represents the result of spawning the child process.

          Properties #

          #stdout: Uint8Array<ArrayBuffer>
          readonly

          The buffered output from the child process' stdout.

          #stderr: Uint8Array<ArrayBuffer>
          readonly

          The buffered output from the child process' stderr.

          interface Deno.CommandStatus

          Properties #

          #success: boolean

          If the child process exits with a 0 status code, success will be set to true, otherwise false.

          #code: number

          The exit code of the child process.

          #signal: Signal | null

          The signal associated with the child process.

          interface Deno.SubprocessReadableStream

          extends ReadableStream<Uint8Array<ArrayBuffer>>

          The interface for stdout and stderr streams for child process returned from Deno.Command.spawn.

          Methods #

          #arrayBuffer(): Promise<ArrayBuffer>

          Reads the stream to completion. It returns a promise that resolves with an ArrayBuffer.

          #bytes(): Promise<Uint8Array<ArrayBuffer>>

          Reads the stream to completion. It returns a promise that resolves with a Uint8Array.

          #json(): Promise<any>

          Reads the stream to completion. It returns a promise that resolves with the result of parsing the body text as JSON.

          #text(): Promise<string>

          Reads the stream to completion. It returns a promise that resolves with a USVString (text).

          Did you find what you needed?

          Privacy policy