Unstable methods should not appear in runtime or d.ts (#4957)

Co-authored-by: Kitson Kelly <me@kitsonkelly.com>

cli/js/compiler.ts

@@ -51,7 +51,8 @@ interface CompilerRequestCompile {
   // options: ts.CompilerOptions;
   configPath?: string;
   config?: string;
-  bundle?: boolean;
+  unstable: boolean;
+  bundle: boolean;
   outFile?: string;
 }
 
@@ -60,6 +61,7 @@ interface CompilerRequestRuntimeCompile {
   target: CompilerHostTarget;
   rootName: string;
   sources?: Record<string, string>;
+  unstable?: boolean;
   bundle?: boolean;
   options?: string;
 }
@@ -90,7 +92,15 @@ type RuntimeBundleResult = [undefined | DiagnosticItem[], string];
 async function compile(
   request: CompilerRequestCompile
 ): Promise<CompileResult> {
-  const { bundle, config, configPath, outFile, rootNames, target } = request;
+  const {
+    bundle,
+    config,
+    configPath,
+    outFile,
+    rootNames,
+    target,
+    unstable,
+  } = request;
   util.log(">>> compile start", {
     rootNames,
     type: CompilerRequestType[request.type],
@@ -116,6 +126,7 @@ async function compile(
     bundle,
     target,
     writeFile,
+    unstable,
   }));
   let diagnostics: readonly ts.Diagnostic[] | undefined;
 
@@ -185,7 +196,7 @@ async function compile(
 async function runtimeCompile(
   request: CompilerRequestRuntimeCompile
 ): Promise<RuntimeCompileResult | RuntimeBundleResult> {
-  const { rootName, sources, options, bundle, target } = request;
+  const { bundle, options, rootName, sources, target, unstable } = request;
 
   util.log(">>> runtime compile start", {
     rootName,
@@ -259,6 +270,14 @@ async function runtimeCompile(
   if (convertedOptions) {
     compilerOptions.push(convertedOptions);
   }
+  if (unstable) {
+    compilerOptions.push({
+      lib: [
+        "deno.unstable",
+        ...((convertedOptions && convertedOptions.lib) || ["deno.window"]),
+      ],
+    });
+  }
   if (bundle) {
     compilerOptions.push(defaultBundlerOptions);
   }

cli/js/compiler/bootstrap.ts

@@ -20,6 +20,7 @@ ts.libMap.set("deno.ns", "lib.deno.ns.d.ts");
 ts.libMap.set("deno.window", "lib.deno.window.d.ts");
 ts.libMap.set("deno.worker", "lib.deno.worker.d.ts");
 ts.libMap.set("deno.shared_globals", "lib.deno.shared_globals.d.ts");
+ts.libMap.set("deno.unstable", "lib.deno.unstable.d.ts");
 
 // this pre-populates the cache at snapshot time of our library files, so they
 // are available in the future when needed.
@@ -30,6 +31,7 @@ host.getSourceFile(
   `${ASSETS}/lib.deno.shared_globals.d.ts`,
   ts.ScriptTarget.ESNext
 );
+host.getSourceFile(`${ASSETS}/lib.deno.unstable.d.ts`, ts.ScriptTarget.ESNext);
 
 export const TS_SNAPSHOT_PROGRAM = ts.createProgram({
   rootNames: [`${ASSETS}/bootstrap.ts`],

cli/js/compiler/host.ts

@@ -14,9 +14,8 @@ export enum CompilerHostTarget {
 
 export interface CompilerHostOptions {
   bundle?: boolean;
-
   target: CompilerHostTarget;
-
+  unstable?: boolean;
   writeFile: WriteFileCallback;
 }
 
@@ -146,13 +145,26 @@ export class Host implements ts.CompilerHost {
 
   /* Deno specific APIs */
 
-  constructor({ bundle = false, target, writeFile }: CompilerHostOptions) {
+  constructor({
+    bundle = false,
+    target,
+    unstable,
+    writeFile,
+  }: CompilerHostOptions) {
     this.#target = target;
     this.#writeFile = writeFile;
     if (bundle) {
       // options we need to change when we are generating a bundle
       Object.assign(this.#options, defaultBundlerOptions);
     }
+    if (unstable) {
+      this.#options.lib = [
+        target === CompilerHostTarget.Worker
+          ? "lib.deno.worker.d.ts"
+          : "lib.deno.window.d.ts",
+        "lib.deno.unstable.d.ts",
+      ];
+    }
   }
 
   configure(path: string, configurationText: string): ConfigureResponse {

cli/js/deno.ts

@@ -11,7 +11,6 @@ export {
 export { build } from "./build.ts";
 export { chmodSync, chmod } from "./ops/fs/chmod.ts";
 export { chownSync, chown } from "./ops/fs/chown.ts";
-export { transpileOnly, compile, bundle } from "./compiler/api.ts";
 export { customInspect, inspect } from "./web/console.ts";
 export { copyFileSync, copyFile } from "./ops/fs/copy_file.ts";
 export {
@@ -20,8 +19,7 @@ export {
   DiagnosticItem,
   DiagnosticMessageChain,
 } from "./diagnostics.ts";
-export { chdir, cwd } from "./ops/fs/dir.ts";
-export { applySourceMap, formatDiagnostics } from "./ops/errors.ts";
+export { chdir } from "./ops/fs/dir.ts";
 export { errors } from "./errors.ts";
 export {
   File,
@@ -51,7 +49,6 @@ export {
   Closer,
   Seeker,
 } from "./io.ts";
-export { linkSync, link } from "./ops/fs/link.ts";
 export {
   makeTempDirSync,
   makeTempDir,
@@ -61,34 +58,8 @@ export {
 } from "./ops/fs/make_temp.ts";
 export { metrics, Metrics } from "./ops/runtime.ts";
 export { mkdirSync, mkdir, MkdirOptions } from "./ops/fs/mkdir.ts";
-export {
-  connect,
-  listen,
-  listenDatagram,
-  DatagramConn,
-  Listener,
-  Conn,
-  ShutdownMode,
-  shutdown,
-} from "./net.ts";
-export {
-  dir,
-  env,
-  exit,
-  execPath,
-  hostname,
-  loadavg,
-  osRelease,
-} from "./ops/os.ts";
-export {
-  permissions,
-  PermissionName,
-  PermissionState,
-  PermissionStatus,
-  Permissions,
-} from "./permissions.ts";
-export { openPlugin } from "./ops/plugins.ts";
-export { kill } from "./ops/process.ts";
+export { connect, listen, Listener, Conn } from "./net.ts";
+export { dir, env, exit, execPath, hostname } from "./ops/os.ts";
 export { run, RunOptions, Process, ProcessStatus } from "./process.ts";
 export { DirEntry, readDirSync, readDir } from "./ops/fs/read_dir.ts";
 export { readFileSync, readFile } from "./read_file.ts";
@@ -98,14 +69,10 @@ export { realPathSync, realPath } from "./ops/fs/real_path.ts";
 export { removeSync, remove, RemoveOptions } from "./ops/fs/remove.ts";
 export { renameSync, rename } from "./ops/fs/rename.ts";
 export { resources, close } from "./ops/resources.ts";
-export { signal, signals, Signal, SignalStream } from "./signals.ts";
 export { FileInfo, statSync, lstatSync, stat, lstat } from "./ops/fs/stat.ts";
-export { symlinkSync, symlink } from "./ops/fs/symlink.ts";
-export { connectTls, listenTls, startTls } from "./tls.ts";
+export { connectTls, listenTls } from "./tls.ts";
 export { truncateSync, truncate } from "./ops/fs/truncate.ts";
-export { isatty, setRaw } from "./ops/tty.ts";
-export { umask } from "./ops/fs/umask.ts";
-export { utimeSync, utime } from "./ops/fs/utime.ts";
+export { isatty } from "./ops/tty.ts";
 export { version } from "./version.ts";
 export { writeFileSync, writeFile, WriteFileOptions } from "./write_file.ts";
 export { writeTextFileSync, writeTextFile } from "./write_text_file.ts";

cli/js/deno_unstable.ts

@@ -0,0 +1,26 @@
+// Copyright 2018-2020 the Deno authors. All rights reserved. MIT license.
+
+// This module exports unstable Deno APIs.
+
+export { umask } from "./ops/fs/umask.ts";
+export { linkSync, link } from "./ops/fs/link.ts";
+export { symlinkSync, symlink } from "./ops/fs/symlink.ts";
+export { dir, loadavg, osRelease } from "./ops/os.ts";
+export { openPlugin } from "./ops/plugins.ts";
+export { transpileOnly, compile, bundle } from "./compiler/api.ts";
+export { applySourceMap, formatDiagnostics } from "./ops/errors.ts";
+export { signal, signals, Signal, SignalStream } from "./signals.ts";
+export { setRaw } from "./ops/tty.ts";
+export { utimeSync, utime } from "./ops/fs/utime.ts";
+export { ShutdownMode, shutdown } from "./net.ts";
+export { listen, listenDatagram, connect } from "./net_unstable.ts";
+export { cwd } from "./ops/fs/dir.ts";
+export { startTls } from "./tls.ts";
+export { kill } from "./ops/process.ts";
+export {
+  permissions,
+  PermissionName,
+  PermissionState,
+  PermissionStatus,
+  Permissions,
+} from "./permissions.ts";

cli/js/globals_unstable.ts

@@ -0,0 +1,5 @@
+// Copyright 2018-2020 the Deno authors. All rights reserved. MIT license.
+
+export const unstableMethods = {};
+
+export const unstableProperties = {};

cli/js/net.ts

@@ -48,6 +48,7 @@ export class ConnImpl implements Conn {
     close(this.rid);
   }
 
+  // TODO(lucacasonato): make this unavailable in stable
   closeWrite(): void {
     netOps.shutdown(this.rid, netOps.ShutdownMode.Write);
   }
@@ -141,59 +142,22 @@ export interface Conn extends Reader, Writer, Closer {
 export interface ListenOptions {
   port: number;
   hostname?: string;
-  transport?: "tcp" | "udp";
-}
-
-export interface UnixListenOptions {
-  transport: "unix" | "unixpacket";
-  path: string;
+  transport?: "tcp";
 }
 
 export function listen(
   options: ListenOptions & { transport?: "tcp" }
 ): Listener;
-export function listen(
-  options: UnixListenOptions & { transport: "unix" }
-): Listener;
-export function listen(options: ListenOptions | UnixListenOptions): Listener {
-  let res;
-
-  if (options.transport === "unix") {
-    res = netOps.listen(options);
-  } else {
-    res = netOps.listen({
-      transport: "tcp",
-      hostname: "127.0.0.1",
-      ...(options as ListenOptions),
-    });
-  }
+export function listen(options: ListenOptions): Listener {
+  const res = netOps.listen({
+    transport: "tcp",
+    hostname: "127.0.0.1",
+    ...(options as ListenOptions),
+  });
 
   return new ListenerImpl(res.rid, res.localAddr);
 }
 
-export function listenDatagram(
-  options: ListenOptions & { transport: "udp" }
-): DatagramConn;
-export function listenDatagram(
-  options: UnixListenOptions & { transport: "unixpacket" }
-): DatagramConn;
-export function listenDatagram(
-  options: ListenOptions | UnixListenOptions
-): DatagramConn {
-  let res;
-  if (options.transport === "unixpacket") {
-    res = netOps.listen(options);
-  } else {
-    res = netOps.listen({
-      transport: "udp",
-      hostname: "127.0.0.1",
-      ...(options as ListenOptions),
-    });
-  }
-
-  return new DatagramImpl(res.rid, res.localAddr);
-}
-
 export interface ConnectOptions {
   port: number;
   hostname?: string;

cli/js/net_unstable.ts

@@ -0,0 +1,79 @@
+import * as netOps from "./ops/net.ts";
+import {
+  Listener,
+  DatagramConn,
+  ListenerImpl,
+  DatagramImpl,
+  ConnectOptions,
+  Conn,
+  ConnImpl,
+  listen as stableListen,
+  connect as stableConnect,
+} from "./net.ts";
+
+export interface ListenOptions {
+  port: number;
+  hostname?: string;
+  transport?: "tcp" | "udp";
+}
+
+export interface UnixListenOptions {
+  transport: "unix" | "unixpacket";
+  path: string;
+}
+
+export function listen(
+  options: ListenOptions & { transport?: "tcp" }
+): Listener;
+export function listen(
+  options: UnixListenOptions & { transport: "unix" }
+): Listener;
+export function listen(options: ListenOptions | UnixListenOptions): Listener {
+  if (options.transport === "unix") {
+    const res = netOps.listen(options);
+    return new ListenerImpl(res.rid, res.localAddr);
+  } else {
+    return stableListen(options as ListenOptions & { transport?: "tcp" });
+  }
+}
+
+export function listenDatagram(
+  options: ListenOptions & { transport: "udp" }
+): DatagramConn;
+export function listenDatagram(
+  options: UnixListenOptions & { transport: "unixpacket" }
+): DatagramConn;
+export function listenDatagram(
+  options: ListenOptions | UnixListenOptions
+): DatagramConn {
+  let res;
+  if (options.transport === "unixpacket") {
+    res = netOps.listen(options);
+  } else {
+    res = netOps.listen({
+      transport: "udp",
+      hostname: "127.0.0.1",
+      ...(options as ListenOptions),
+    });
+  }
+
+  return new DatagramImpl(res.rid, res.localAddr);
+}
+
+export interface UnixConnectOptions {
+  transport: "unix";
+  path: string;
+}
+
+export async function connect(options: UnixConnectOptions): Promise<Conn>;
+export async function connect(options: ConnectOptions): Promise<Conn>;
+export async function connect(
+  options: ConnectOptions | UnixConnectOptions
+): Promise<Conn> {
+  if (options.transport === "unix") {
+    const res = await netOps.connect(options);
+    return new ConnImpl(res.rid, res.remoteAddr!, res.localAddr!);
+  } else {
+    return stableConnect(options as ConnectOptions);
+  }
+}

cli/js/ops/runtime.ts

@@ -3,20 +3,19 @@
 import { sendSync } from "./dispatch_json.ts";
 
 export interface Start {
-  cwd: string;
-  pid: number;
   args: string[];
-  location: string; // Absolute URL.
-  repl: boolean;
+  cwd: string;
   debugFlag: boolean;
-  depsFlag: boolean;
-  typesFlag: boolean;
-  versionFlag: boolean;
   denoVersion: string;
-  v8Version: string;
-  tsVersion: string;
+  location: string; // Absolute URL.
   noColor: boolean;
+  pid: number;
+  repl: boolean;
   target: string;
+  tsVersion: string;
+  unstableFlag: boolean;
+  v8Version: string;
+  versionFlag: boolean;
 }
 
 export function opStart(): Start {

cli/js/runtime_main.ts

@@ -7,7 +7,8 @@
 //  - `bootstrapMainRuntime` - must be called once, when Isolate is created.
 //   It sets up runtime by providing globals for `WindowScope` and adds `Deno` global.
 
-import * as Deno from "./deno.ts";
+import * as denoNs from "./deno.ts";
+import * as denoUnstableNs from "./deno_unstable.ts";
 import * as csprng from "./ops/get_random_values.ts";
 import { exit } from "./ops/os.ts";
 import {
@@ -19,6 +20,7 @@ import {
   eventTargetProperties,
   setEventTargetData,
 } from "./globals.ts";
+import { unstableMethods, unstableProperties } from "./globals_unstable.ts";
 import { internalObject, internalSymbol } from "./internals.ts";
 import { setSignals } from "./signals.ts";
 import { replLoop } from "./repl.ts";
@@ -31,7 +33,7 @@ import { log, immutableDefine } from "./util.ts";
 // Add internal object to Deno object.
 // This is not exposed as part of the Deno types.
 // @ts-ignore
-Deno[internalSymbol] = internalObject;
+denoNs[internalSymbol] = internalObject;
 
 let windowIsClosing = false;
 
@@ -96,29 +98,44 @@ export function bootstrapMainRuntime(): void {
     }
   });
 
-  const s = runtime.start();
+  const {
+    args,
+    cwd,
+    location,
+    noColor,
+    pid,
+    repl,
+    unstableFlag,
+  } = runtime.start();
 
-  const location = new LocationImpl(s.location);
-  immutableDefine(globalThis, "location", location);
+  const location_ = new LocationImpl(location);
+  immutableDefine(globalThis, "location", location_);
   Object.freeze(globalThis.location);
 
-  Object.defineProperties(Deno, {
-    pid: readOnly(s.pid),
-    noColor: readOnly(s.noColor),
-    args: readOnly(Object.freeze(s.args)),
+  Object.defineProperties(denoNs, {
+    pid: readOnly(pid),
+    noColor: readOnly(noColor),
+    args: readOnly(Object.freeze(args)),
   });
+
+  if (unstableFlag) {
+    Object.defineProperties(globalThis, unstableMethods);
+    Object.defineProperties(globalThis, unstableProperties);
+    Object.assign(denoNs, denoUnstableNs);
+  }
+
   // Setup `Deno` global - we're actually overriding already
   // existing global `Deno` with `Deno` namespace from "./deno.ts".
-  immutableDefine(globalThis, "Deno", Deno);
+  immutableDefine(globalThis, "Deno", denoNs);
   Object.freeze(globalThis.Deno);
   Object.freeze(globalThis.Deno.core);
   Object.freeze(globalThis.Deno.core.sharedQueue);
   setSignals();
 
-  log("cwd", s.cwd);
-  log("args", Deno.args);
+  log("cwd", cwd);
+  log("args", args);
 
-  if (s.repl) {
+  if (repl) {
     replLoop();
   }
 }

cli/js/runtime_worker.ts

@@ -17,7 +17,9 @@ import {
   eventTargetProperties,
   setEventTargetData,
 } from "./globals.ts";
-import * as Deno from "./deno.ts";
+import { unstableMethods, unstableProperties } from "./globals_unstable.ts";
+import * as denoNs from "./deno.ts";
+import * as denoUnstableNs from "./deno_unstable.ts";
 import * as webWorkerOps from "./ops/web_worker.ts";
 import { LocationImpl } from "./web/location.ts";
 import { log, assert, immutableDefine } from "./util.ts";
@@ -32,7 +34,7 @@ import { setSignals } from "./signals.ts";
 // Add internal object to Deno object.
 // This is not exposed as part of the Deno types.
 // @ts-ignore
-Deno[internalSymbol] = internalObject;
+denoNs[internalSymbol] = internalObject;
 
 const encoder = new TextEncoder();
 
@@ -136,21 +138,31 @@ export function bootstrapWorkerRuntime(
   Object.defineProperties(globalThis, eventTargetProperties);
   Object.defineProperties(globalThis, { name: readOnly(name) });
   setEventTargetData(globalThis);
-  const s = runtime.start(internalName ?? name);
+  const { location, unstableFlag, pid, noColor, args } = runtime.start(
+    internalName ?? name
+  );
 
-  const location = new LocationImpl(s.location);
-  immutableDefine(globalThis, "location", location);
+  const location_ = new LocationImpl(location);
+  immutableDefine(globalThis, "location", location_);
   Object.freeze(globalThis.location);
 
+  if (unstableFlag) {
+    Object.defineProperties(globalThis, unstableMethods);
+    Object.defineProperties(globalThis, unstableProperties);
+  }
+
   if (useDenoNamespace) {
-    Object.defineProperties(Deno, {
-      pid: readOnly(s.pid),
-      noColor: readOnly(s.noColor),
-      args: readOnly(Object.freeze(s.args)),
+    if (unstableFlag) {
+      Object.assign(denoNs, denoUnstableNs);
+    }
+    Object.defineProperties(denoNs, {
+      pid: readOnly(pid),
+      noColor: readOnly(noColor),
+      args: readOnly(Object.freeze(args)),
     });
     // Setup `Deno` global - we're actually overriding already
     // existing global `Deno` with `Deno` namespace from "./deno.ts".
-    immutableDefine(globalThis, "Deno", Deno);
+    immutableDefine(globalThis, "Deno", denoNs);
     Object.freeze(globalThis.Deno);
     Object.freeze(globalThis.Deno.core);
     Object.freeze(globalThis.Deno.core.sharedQueue);