Skip to content

Commit

Permalink
BREAKING(types): soft-remove Deno.run() (#25403)
Browse files Browse the repository at this point in the history 
Towards #22079
  • Loading branch information
@iuioiua
iuioiua authored Sep 4, 2024
1 parent c32d692 commit 195b17a
Show file tree
Hide file tree
Showing 9 changed files with 58 additions and 368 deletions.
231 changes: 3 additions & 228 deletions cli/tsc/dts/lib.deno.ns.d.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3925,175 +3925,6 @@ declare namespace Deno {
options?: { recursive: boolean },
): FsWatcher;

/**
* Options which can be used with {@linkcode Deno.run}.
*
* @deprecated This will be removed in Deno 2.0. See the
* {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide}
* for migration instructions.
*
* @category Subprocess */
export interface RunOptions {
/** Arguments to pass.
*
* _Note_: the first element needs to be a path to the executable that is
* being run. */
cmd: readonly string[] | [string | URL, ...string[]];
/** The current working directory that should be used when running the
* sub-process. */
cwd?: string;
/** Any environment variables to be set when running the sub-process. */
env?: Record<string, string>;
/** By default subprocess inherits `stdout` of parent process. To change
* this this option can be set to a resource ID (_rid_) of an open file,
* `"inherit"`, `"piped"`, or `"null"`:
*
* - _number_: the resource ID of an open file/resource. This allows you to
* write to a file.
* - `"inherit"`: The default if unspecified. The subprocess inherits from the
* parent.
* - `"piped"`: A new pipe should be arranged to connect the parent and child
* sub-process.
* - `"null"`: This stream will be ignored. This is the equivalent of attaching
* the stream to `/dev/null`.
*/
stdout?: "inherit" | "piped" | "null" | number;
/** By default subprocess inherits `stderr` of parent process. To change
* this this option can be set to a resource ID (_rid_) of an open file,
* `"inherit"`, `"piped"`, or `"null"`:
*
* - _number_: the resource ID of an open file/resource. This allows you to
* write to a file.
* - `"inherit"`: The default if unspecified. The subprocess inherits from the
* parent.
* - `"piped"`: A new pipe should be arranged to connect the parent and child
* sub-process.
* - `"null"`: This stream will be ignored. This is the equivalent of attaching
* the stream to `/dev/null`.
*/
stderr?: "inherit" | "piped" | "null" | number;
/** By default subprocess inherits `stdin` of parent process. To change
* this this option can be set to a resource ID (_rid_) of an open file,
* `"inherit"`, `"piped"`, or `"null"`:
*
* - _number_: the resource ID of an open file/resource. This allows you to
* read from a file.
* - `"inherit"`: The default if unspecified. The subprocess inherits from the
* parent.
* - `"piped"`: A new pipe should be arranged to connect the parent and child
* sub-process.
* - `"null"`: This stream will be ignored. This is the equivalent of attaching
* the stream to `/dev/null`.
*/
stdin?: "inherit" | "piped" | "null" | number;
}

/**
* The status resolved from the `.status()` method of a
* {@linkcode Deno.Process} instance.
*
* If `success` is `true`, then `code` will be `0`, but if `success` is
* `false`, the sub-process exit code will be set in `code`.
*
* @deprecated This will be removed in Deno 2.0. See the
* {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide}
* for migration instructions.
*
* @category Subprocess */
export type ProcessStatus =
| {
success: true;
code: 0;
signal?: undefined;
}
| {
success: false;
code: number;
signal?: number;
};

/**
* Represents an instance of a sub process that is returned from
* {@linkcode Deno.run} which can be used to manage the sub-process.
*
* @deprecated This will be removed in Deno 2.0. See the
* {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide}
* for migration instructions.
*
* @category Subprocess */
export class Process<T extends RunOptions = RunOptions> {
/** The resource ID of the sub-process. */
readonly rid: number;
/** The operating system's process ID for the sub-process. */
readonly pid: number;
/** A reference to the sub-processes `stdin`, which allows interacting with
* the sub-process at a low level. */
readonly stdin: T["stdin"] extends "piped" ? Writer & Closer & {
writable: WritableStream<Uint8Array>;
}
: (Writer & Closer & { writable: WritableStream<Uint8Array> }) | null;
/** A reference to the sub-processes `stdout`, which allows interacting with
* the sub-process at a low level. */
readonly stdout: T["stdout"] extends "piped" ? Reader & Closer & {
readable: ReadableStream<Uint8Array>;
}
: (Reader & Closer & { readable: ReadableStream<Uint8Array> }) | null;
/** A reference to the sub-processes `stderr`, which allows interacting with
* the sub-process at a low level. */
readonly stderr: T["stderr"] extends "piped" ? Reader & Closer & {
readable: ReadableStream<Uint8Array>;
}
: (Reader & Closer & { readable: ReadableStream<Uint8Array> }) | null;
/** Wait for the process to exit and return its exit status.
*
* Calling this function multiple times will return the same status.
*
* The `stdin` reference to the process will be closed before waiting to
* avoid a deadlock.
*
* If `stdout` and/or `stderr` were set to `"piped"`, they must be closed
* manually before the process can exit.
*
* To run process to completion and collect output from both `stdout` and
* `stderr` use:
*
* ```ts
* const p = Deno.run({ cmd: [ "echo", "hello world" ], stderr: 'piped', stdout: 'piped' });
* const [status, stdout, stderr] = await Promise.all([
* p.status(),
* p.output(),
* p.stderrOutput()
* ]);
* p.close();
* ```
*/
status(): Promise<ProcessStatus>;
/** Buffer the stdout until EOF and return it as `Uint8Array`.
*
* You must set `stdout` to `"piped"` when creating the process.
*
* This calls `close()` on stdout after its done. */
output(): Promise<Uint8Array>;
/** Buffer the stderr until EOF and return it as `Uint8Array`.
*
* You must set `stderr` to `"piped"` when creating the process.
*
* This calls `close()` on stderr after its done. */
stderrOutput(): Promise<Uint8Array>;
/** Clean up resources associated with the sub-process instance. */
close(): void;
/** Send a signal to process.
* Default signal is `"SIGTERM"`.
*
* ```ts
* const p = Deno.run({ cmd: [ "sleep", "20" ]});
* p.kill("SIGTERM");
* p.close();
* ```
*/
kill(signo?: Signal): void;
}

/** Operating signals which can be listened for or sent to sub-processes. What
* signals and what their standard behaviors are OS dependent.
*
Expand Down Expand Up @@ -4175,61 +4006,6 @@ declare namespace Deno {
handler: () => void,
): void;

/**
* Spawns new subprocess. RunOptions must contain at a minimum the `opt.cmd`,
* an array of program arguments, the first of which is the binary.
*
* ```ts
* const p = Deno.run({
* cmd: ["curl", "https://example.com"],
* });
* const status = await p.status();
* ```
*
* Subprocess uses same working directory as parent process unless `opt.cwd`
* is specified.
*
* Environmental variables from parent process can be cleared using `opt.clearEnv`.
* Doesn't guarantee that only `opt.env` variables are present,
* as the OS may set environmental variables for processes.
*
* Environmental variables for subprocess can be specified using `opt.env`
* mapping.
*
* `opt.uid` sets the child process’s user ID. This translates to a setuid call
* in the child process. Failure in the setuid call will cause the spawn to fail.
*
* `opt.gid` is similar to `opt.uid`, but sets the group ID of the child process.
* This has the same semantics as the uid field.
*
* By default subprocess inherits stdio of parent process. To change
* this this, `opt.stdin`, `opt.stdout`, and `opt.stderr` can be set
* independently to a resource ID (_rid_) of an open file, `"inherit"`,
* `"piped"`, or `"null"`:
*
* - _number_: the resource ID of an open file/resource. This allows you to
* read or write to a file.
* - `"inherit"`: The default if unspecified. The subprocess inherits from the
* parent.
* - `"piped"`: A new pipe should be arranged to connect the parent and child
* sub-process.
* - `"null"`: This stream will be ignored. This is the equivalent of attaching
* the stream to `/dev/null`.
*
* Details of the spawned process are returned as an instance of
* {@linkcode Deno.Process}.
*
* Requires `allow-run` permission.
*
* @deprecated This will be soft-removed in Deno 2.0. See the
* {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide}
* for migration instructions.
*
* @tags allow-run
* @category Subprocess
*/
export function run<T extends RunOptions = RunOptions>(opt: T): Process<T>;

/** Create a child process.
*
* If any stdio options are not set to `"piped"`, accessing the corresponding
Expand Down Expand Up @@ -5308,11 +5084,10 @@ declare namespace Deno {
* Windows.
*
* ```ts
* const p = Deno.run({
* cmd: ["sleep", "10000"]
* });
* const command = new Deno.Command("sleep", { args: ["10000"] });
* const child = command.spawn();
*
* Deno.kill(p.pid, "SIGINT");
* Deno.kill(child.pid, "SIGINT");
* ```
*
* Requires `allow-run` permission.
Expand Down
74 changes: 0 additions & 74 deletions cli/tsc/dts/lib.deno.unstable.d.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -840,80 +840,6 @@ declare namespace Deno {
present(): void;
}

/** **UNSTABLE**: New API, yet to be vetted.
*
* These are unstable options which can be used with {@linkcode Deno.run}.
*
* @category Subprocess
* @experimental
*/
export interface UnstableRunOptions extends RunOptions {
/** If `true`, clears the environment variables before executing the
* sub-process.
*
* @default {false} */
clearEnv?: boolean;
/** For POSIX systems, sets the group ID for the sub process. */
gid?: number;
/** For POSIX systems, sets the user ID for the sub process. */
uid?: number;
}

/** **UNSTABLE**: New API, yet to be vetted.
*
* Spawns new subprocess. RunOptions must contain at a minimum the `opt.cmd`,
* an array of program arguments, the first of which is the binary.
*
* ```ts
* const p = Deno.run({
* cmd: ["curl", "https://example.com"],
* });
* const status = await p.status();
* ```
*
* Subprocess uses same working directory as parent process unless `opt.cwd`
* is specified.
*
* Environmental variables from parent process can be cleared using `opt.clearEnv`.
* Doesn't guarantee that only `opt.env` variables are present,
* as the OS may set environmental variables for processes.
*
* Environmental variables for subprocess can be specified using `opt.env`
* mapping.
*
* `opt.uid` sets the child process’s user ID. This translates to a setuid call
* in the child process. Failure in the setuid call will cause the spawn to fail.
*
* `opt.gid` is similar to `opt.uid`, but sets the group ID of the child process.
* This has the same semantics as the uid field.
*
* By default subprocess inherits stdio of parent process. To change
* this this, `opt.stdin`, `opt.stdout`, and `opt.stderr` can be set
* independently to a resource ID (_rid_) of an open file, `"inherit"`,
* `"piped"`, or `"null"`:
*
* - _number_: the resource ID of an open file/resource. This allows you to
* read or write to a file.
* - `"inherit"`: The default if unspecified. The subprocess inherits from the
* parent.
* - `"piped"`: A new pipe should be arranged to connect the parent and child
* sub-process.
* - `"null"`: This stream will be ignored. This is the equivalent of attaching
* the stream to `/dev/null`.
*
* Details of the spawned process are returned as an instance of
* {@linkcode Deno.Process}.
*
* Requires `allow-run` permission.
*
* @tags allow-run
* @category Subprocess
* @experimental
*/
export function run<T extends UnstableRunOptions = UnstableRunOptions>(
opt: T,
): Process<T>;

/** **UNSTABLE**: New API, yet to be vetted.
*
* A custom `HttpClient` for use with {@linkcode fetch} function. This is
Expand Down
7 changes: 2 additions & 5 deletions runtime/js/40_process.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -130,6 +130,8 @@ class Process {
}
}

// Note: This function was soft-removed in Deno 2. Its types have been removed,
// but its implementation has been kept to avoid breaking changes.
function run({
cmd,
cwd = undefined,
Expand All @@ -144,11 +146,6 @@ function run({
...new SafeArrayIterator(ArrayPrototypeSlice(cmd, 1)),
];
}
internals.warnOnDeprecatedApi(
"Deno.run()",
(new Error()).stack,
`Use "Deno.Command()" API instead.`,
);
const res = opRun({
cmd: ArrayPrototypeMap(cmd, String),
cwd,
Expand Down
Loading

0 comments on commit 195b17a

Please sign in to comment.