Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

BREAKING(types): soft-remove Deno.run() #25403

Merged
merged 3 commits into from
Sep 4, 2024
Merged

BREAKING(types): soft-remove Deno.run() #25403

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
bbd61cb
BREAKING: soft-remove `Deno.run()`
iuioiua Sep 3, 2024
31019dd
add note
iuioiua Sep 3, 2024
102ba13
fixes
iuioiua Sep 3, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
231 changes: 3 additions & 228 deletions cli/tsc/dts/lib.deno.ns.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4103,175 +4103,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 @@ -4353,61 +4184,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 @@ -5616,11 +5392,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");
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

#25405

* ```
*
* Requires `allow-run` permission.
Expand Down
74 changes: 0 additions & 74 deletions cli/tsc/dts/lib.deno.unstable.d.ts
View file
Open in desktop
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Missed in #25371

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
Open in desktop
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.`,
);
iuioiua marked this conversation as resolved.
Show resolved Hide resolved
const res = opRun({
cmd: ArrayPrototypeMap(cmd, String),
cwd,
Expand Down
1 change: 0 additions & 1 deletion tests/testdata/run/warn_on_deprecated_api/main.out
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,4 @@
Download http://localhost:4545/run/warn_on_deprecated_api/mod.ts
warning: Use of deprecated "Deno.run()" API. This API will be removed in Deno 2. Run again with DENO_VERBOSE_WARNINGS=1 to get more details.
hello world
hello world
hello world
Expand Down
5 changes: 0 additions & 5 deletions tests/testdata/run/warn_on_deprecated_api/main.verbose.out
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,4 @@
Download http://localhost:4545/run/warn_on_deprecated_api/mod.ts
warning: Use of deprecated "Deno.run()" API. This API will be removed in Deno 2.

See the Deno 1 to 2 Migration Guide for more information at https://docs.deno.com/runtime/manual/advanced/migrate_deprecations

Expand All @@ -9,7 +8,6 @@ Stack trace:
hint: Use "Deno.Command()" API instead.

hello world
warning: Use of deprecated "Deno.run()" API. This API will be removed in Deno 2.

See the Deno 1 to 2 Migration Guide for more information at https://docs.deno.com/runtime/manual/advanced/migrate_deprecations

Expand All @@ -20,7 +18,6 @@ Stack trace:
hint: Use "Deno.Command()" API instead.

hello world
warning: Use of deprecated "Deno.run()" API. This API will be removed in Deno 2.

See the Deno 1 to 2 Migration Guide for more information at https://docs.deno.com/runtime/manual/advanced/migrate_deprecations

Expand All @@ -31,7 +28,6 @@ Stack trace:
hint: Use "Deno.Command()" API instead.

hello world
warning: Use of deprecated "Deno.run()" API. This API will be removed in Deno 2.

See the Deno 1 to 2 Migration Guide for more information at https://docs.deno.com/runtime/manual/advanced/migrate_deprecations

Expand All @@ -51,7 +47,6 @@ hello world
hello world
hello world
hello world
warning: Use of deprecated "Deno.run()" API. This API will be removed in Deno 2.

See the Deno 1 to 2 Migration Guide for more information at https://docs.deno.com/runtime/manual/advanced/migrate_deprecations

Expand Down
Loading