BREAKING(std): reorganization (denoland#5087)

* Prepend underscores to private modules
* Remove collectUint8Arrays() It would be a misuse of Deno.iter()'s result.
* Move std/_util/async.ts to std/async
* Move std/util/sha*.ts to std/hash

cli/test_runner.rs

@@ -153,9 +153,9 @@ mod tests {
  let root_url = Url::from_file_path(root).unwrap().to_string();
  println!("root_url {}", root_url);
  let expected: Vec<Url> = vec![
+ format!("{}/_io_test.ts", root_url),
  format!("{}/cookie_test.ts", root_url),
  format!("{}/file_server_test.ts", root_url),
- format!("{}/io_test.ts", root_url),
  format!("{}/racing_server_test.ts", root_url),
  format!("{}/server_test.ts", root_url),
  ]

docs/linking_to_external_code/reloading_modules.md

@@ -14,9 +14,9 @@ To reload all standard modules
 
 `--reload=https://deno.land/std`
 
-To reload specific modules (in this example - colors and file system utils) use
-a comma to separate URLs
+To reload specific modules (in this example - colors and file system copy) use a
+comma to separate URLs
 
-`--reload=https://deno.land/std/fs/utils.ts,https://deno.land/std/fmt/colors.ts`
+`--reload=https://deno.land/std/fs/copy.ts,https://deno.land/std/fmt/colors.ts`
 
 <!-- Should this be part of examples? --

std/README.md

@@ -10,28 +10,27 @@ Contributions are welcome!
 
 These modules are tagged in accordance with Deno releases. So, for example, the
 v0.3.0 tag is guaranteed to work with deno v0.3.0. You can link to v0.3.0 using
-the URL `https://deno.land/[email protected]/`
+the URL `https://deno.land/[email protected]/`. Not specifying a tag will link to the
+master branch.
 
-It's strongly recommended that you link to tagged releases rather than the
-master branch. The project is still young and we expect disruptive renames in
-the future.
+It is strongly recommended that you link to tagged releases to avoid unintended
+updates.
+
+Don't link to / import any module whose path:
+
+- Has a name or parent with an underscore prefix: `_foo.ts`, `_util/bar.ts`.
+- Is that of a test module or test data: `test.ts`, `foo_test.ts`,
+ `testdata/bar.txt`.
+
+No stability is guaranteed for these files.
 
 ## Documentation
 
-Here are the dedicated documentations of modules:
-
-- [colors](fmt/colors.ts)
-- [datetime](datetime/README.md)
-- [encoding](encoding/README.md)
-- [examples](examples/README.md)
-- [flags](flags/README.md)
-- [fs](fs/README.md)
-- [http](http/README.md)
-- [log](log/README.md)
-- [node](node/README.md)
-- [testing](testing/README.md)
-- [uuid](uuid/README.md)
-- [ws](ws/README.md)
+To browse documentation for modules:
+
+- Go to https://deno.land/std/.
+- Navigate to any module of interest.
+- Click the "DOCUMENTATION" link.
 
 ## Contributing
 

std/async/deferred.ts

@@ -0,0 +1,26 @@
+// Copyright 2018-2020 the Deno authors. All rights reserved. MIT license.
+// TODO(ry) It'd be better to make Deferred a class that inherits from
+// Promise, rather than an interface. This is possible in ES2016, however
+// typescript produces broken code when targeting ES5 code.
+// See https://github.com/Microsoft/TypeScript/issues/15202
+// At the time of writing, the github issue is closed but the problem remains.
+export interface Deferred<T> extends Promise<T> {
+ resolve: (value?: T | PromiseLike<T>) => void;
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ reject: (reason?: any) => void;
+}
+
+/** Creates a Promise with the `reject` and `resolve` functions
+ * placed as methods on the promise object itself. It allows you to do:
+ *
+ * const p = deferred<number>();
+ * // ...
+ * p.resolve(42);
+ */
+export function deferred<T>(): Deferred<T> {
+ let methods;
+ const promise = new Promise<T>((resolve, reject): void => {
+ methods = { resolve, reject };
+ });
+ return Object.assign(promise, methods) as Deferred<T>;
+}

std/async/deferred_test.ts

@@ -0,0 +1,8 @@
+// Copyright 2018-2020 the Deno authors. All rights reserved. MIT license.
+import { deferred } from "./deferred.ts";
+
+Deno.test("[async] deferred", function (): Promise<void> {
+ const d = deferred<number>();
+ d.resolve(12);
+ return Promise.resolve();
+});

std/async/delay.ts

@@ -0,0 +1,9 @@
+// Copyright 2018-2020 the Deno authors. All rights reserved. MIT license.
+/* Resolves after the given number of milliseconds. */
+export function delay(ms: number): Promise<void> {
+ return new Promise((res): number =>
+ setTimeout((): void => {
+ res();
+ }, ms)
+ );
+}

std/async/mod.ts

@@ -0,0 +1,4 @@
+// Copyright 2018-2020 the Deno authors. All rights reserved. MIT license.
+export * from "./deferred.ts";
+export * from "./delay.ts";
+export * from "./mux_async_iterator.ts";

std/async/mux_async_iterator.ts

@@ -0,0 +1,58 @@
+// Copyright 2018-2020 the Deno authors. All rights reserved. MIT license.
+import { Deferred, deferred } from "./deferred.ts";
+
+interface TaggedYieldedValue<T> {
+ iterator: AsyncIterableIterator<T>;
+ value: T;
+}
+
+/** The MuxAsyncIterator class multiplexes multiple async iterators into a
+ * single stream. It currently makes a few assumptions:
+ * - The iterators do not throw.
+ * - The final result (the value returned and not yielded from the iterator)
+ * does not matter; if there is any, it is discarded.
+ */
+export class MuxAsyncIterator<T> implements AsyncIterable<T> {
+ private iteratorCount = 0;
+ private yields: Array<TaggedYieldedValue<T>> = [];
+ private signal: Deferred<void> = deferred();
+
+ add(iterator: AsyncIterableIterator<T>): void {
+ ++this.iteratorCount;
+ this.callIteratorNext(iterator);
+ }
+
+ private async callIteratorNext(
+ iterator: AsyncIterableIterator<T>
+ ): Promise<void> {
+ const { value, done } = await iterator.next();
+ if (done) {
+ --this.iteratorCount;
+ } else {
+ this.yields.push({ iterator, value });
+ }
+ this.signal.resolve();
+ }
+
+ async *iterate(): AsyncIterableIterator<T> {
+ while (this.iteratorCount > 0) {
+ // Sleep until any of the wrapped iterators yields.
+ await this.signal;
+
+ // Note that while we're looping over `yields`, new items may be added.
+ for (let i = 0; i < this.yields.length; i++) {
+ const { iterator, value } = this.yields[i];
+ yield value;
+ this.callIteratorNext(iterator);
+ }
+
+ // Clear the `yields` list and reset the `signal` promise.
+ this.yields.length = 0;
+ this.signal = deferred();
+ }
+ }
+
+ [Symbol.asyncIterator](): AsyncIterableIterator<T> {
+ return this.iterate();
+ }
+}

std/async/mux_async_iterator_test.ts

@@ -0,0 +1,28 @@
+// Copyright 2018-2020 the Deno authors. All rights reserved. MIT license.
+import { assertEquals } from "../testing/asserts.ts";
+import { MuxAsyncIterator } from "./mux_async_iterator.ts";
+
+// eslint-disable-next-line require-await
+async function* gen123(): AsyncIterableIterator<number> {
+ yield 1;
+ yield 2;
+ yield 3;
+}
+
+// eslint-disable-next-line require-await
+async function* gen456(): AsyncIterableIterator<number> {
+ yield 4;
+ yield 5;
+ yield 6;
+}
+
+Deno.test("[async] MuxAsyncIterator", async function (): Promise<void> {
+ const mux = new MuxAsyncIterator<number>();
+ mux.add(gen123());
+ mux.add(gen456());
+ const results = new Set();
+ for await (const value of mux) {
+ results.add(value);
+ }
+ assertEquals(results.size, 6);
+});

std/encoding/README.md

@@ -243,9 +243,7 @@ Serializes `object` as a YAML document.
 
 ### More example
 
-See [`./yaml/example`](./yaml/example) folder and [js-yaml] repository.
-
-[js-yaml]: https://github.com/nodeca/js-yaml
+See https://github.com/nodeca/js-yaml.
 
 ## base32
 

std/encoding/toml.ts

@@ -1,5 +1,5 @@
 // Copyright 2018-2020 the Deno authors. All rights reserved. MIT license.
-import { deepAssign } from "../util/deep_assign.ts";
+import { deepAssign } from "../_util/deep_assign.ts";
 import { assert } from "../testing/asserts.ts";
 
 class KeyValuePair {

std/encoding/yaml.ts

@@ -3,9 +3,9 @@
 // Copyright 2011-2015 by Vitaly Puzrin. All rights reserved. MIT license.
 // Copyright 2018-2020 the Deno authors. All rights reserved. MIT license.
 
-export { ParseOptions, parse, parseAll } from "./yaml/parse.ts";
+export { ParseOptions, parse, parseAll } from "./_yaml/parse.ts";
 export {
  DumpOptions as StringifyOptions,
  stringify,
-} from "./yaml/stringify.ts";
-export * from "./yaml/schema/mod.ts";
+} from "./_yaml/stringify.ts";
+export { Schema, SchemaDefinition, TypeMap } from "./_yaml/schema/mod.ts";

std/encoding/yaml_test.ts

@@ -1,4 +1,4 @@
 // Copyright 2018-2020 the Deno authors. All rights reserved. MIT license.
 
-import "./yaml/parse_test.ts";
-import "./yaml/stringify_test.ts";
+import "./_yaml/parse_test.ts";
+import "./_yaml/stringify_test.ts";

std/examples/chat/server_test.ts

@@ -3,7 +3,7 @@ import { assert, assertEquals } from "../../testing/asserts.ts";
 import { TextProtoReader } from "../../textproto/mod.ts";
 import { BufReader } from "../../io/bufio.ts";
 import { connectWebSocket, WebSocket } from "../../ws/mod.ts";
-import { delay } from "../../util/async.ts";
+import { delay } from "../../async/delay.ts";
 
 const { test } = Deno;
 

std/flags/example.ts → std/examples/flags.ts

@@ -1,5 +1,7 @@
 // Copyright 2018-2020 the Deno authors. All rights reserved. MIT license.
 const { args } = Deno;
-import { parse } from "./mod.ts";
+import { parse } from "../flags/mod.ts";
 
-console.dir(parse(args));
+if (import.meta.main) {
+ console.dir(parse(args));
+}

std/flags/README.md

@@ -12,12 +12,12 @@ console.dir(parse(args));
 ```
 
 ```
-$ deno run example.ts -a beep -b boop
+$ deno run https://deno.land/std/examples/flags.ts -a beep -b boop
 { _: [], a: 'beep', b: 'boop' }
 ```
 
 ```
-$ deno run example.ts -x 3 -y 4 -n5 -abc --beep=boop foo bar baz
+$ deno run https://deno.land/std/examples/flags.ts -x 3 -y 4 -n5 -abc --beep=boop foo bar baz
 { _: [ 'foo', 'bar', 'baz' ],
  x: 3,
  y: 4,
@@ -56,16 +56,13 @@ options can be:
  the `--` and `parsedArgs['--']` with everything after the `--`. Here's an
  example:
  ```ts
+ // $ deno run example.ts -- a arg1
  const { args } = Deno;
  import { parse } from "https://deno.land/std/flags/mod.ts";
- // options['--'] is now set to false
  console.dir(parse(args, { "--": false }));
- // $ deno run example.ts -- a arg1
- // output: { _: [ "example.ts", "a", "arg1" ] }
- // options['--'] is now set to true
+ // output: { _: [ "a", "arg1" ] }
  console.dir(parse(args, { "--": true }));
- // $ deno run example.ts -- a arg1
- // output: { _: [ "example.ts" ], --: [ "a", "arg1" ] }
+ // output: { _: [], --: [ "a", "arg1" ] }
  ```
 - `options.unknown` - a function which is invoked with a command line parameter
  not defined in the `options` configuration object. If the function returns

std/flags/mod.ts

@@ -14,16 +14,13 @@ export interface ArgParsingOptions {
  /** When `true`, populate the result `_` with everything before the `--` and
  * the result `['--']` with everything after the `--`. Here's an example:
  *
+ * // $ deno run example.ts -- a arg1
  * const { args } = Deno;
  * import { parse } from "https://deno.land/std/flags/mod.ts";
- * // options['--'] is now set to false
  * console.dir(parse(args, { "--": false }));
- * // $ deno run example.ts -- a arg1
- * // output: { _: [ "example.ts", "a", "arg1" ] }
- * // options['--'] is now set to true
+ * // output: { _: [ "a", "arg1" ] }
  * console.dir(parse(args, { "--": true }));
- * // $ deno run example.ts -- a arg1
- * // output: { _: [ "example.ts" ], --: [ "a", "arg1" ] }
+ * // output: { _: [], --: [ "a", "arg1" ] }
  *
  * Defaults to `false`.
  */

std/fs/utils_test.ts → std/fs/_util_test.ts

@@ -2,7 +2,7 @@
 
 import { assertEquals } from "../testing/asserts.ts";
 import * as path from "../path/mod.ts";
-import { isSubdir, getFileInfoType, PathType } from "./utils.ts";
+import { isSubdir, getFileInfoType, PathType } from "./_util.ts";
 import { ensureFileSync } from "./ensure_file.ts";
 import { ensureDirSync } from "./ensure_dir.ts";
 

std/fs/copy.ts

@@ -1,7 +1,7 @@
 // Copyright 2018-2020 the Deno authors. All rights reserved. MIT license.
 import * as path from "../path/mod.ts";
 import { ensureDir, ensureDirSync } from "./ensure_dir.ts";
-import { isSubdir, getFileInfoType } from "./utils.ts";
+import { isSubdir, getFileInfoType } from "./_util.ts";
 import { assert } from "../testing/asserts.ts";
 
 export interface CopyOptions {

std/fs/ensure_dir.ts

@@ -1,5 +1,5 @@
 // Copyright 2018-2020 the Deno authors. All rights reserved. MIT license.
-import { getFileInfoType } from "./utils.ts";
+import { getFileInfoType } from "./_util.ts";
 const { lstat, lstatSync, mkdir, mkdirSync } = Deno;
 
 /**

std/fs/ensure_file.ts

@@ -1,7 +1,7 @@
 // Copyright 2018-2020 the Deno authors. All rights reserved. MIT license.
 import * as path from "../path/mod.ts";
 import { ensureDir, ensureDirSync } from "./ensure_dir.ts";
-import { getFileInfoType } from "./utils.ts";
+import { getFileInfoType } from "./_util.ts";
 const { lstat, lstatSync, writeFile, writeFileSync } = Deno;
 
 /**

std/fs/ensure_link.ts

@@ -2,7 +2,7 @@
 import * as path from "../path/mod.ts";
 import { ensureDir, ensureDirSync } from "./ensure_dir.ts";
 import { exists, existsSync } from "./exists.ts";
-import { getFileInfoType } from "./utils.ts";
+import { getFileInfoType } from "./_util.ts";
 
 /**
  * Ensures that the hard link exists.

std/fs/ensure_symlink.ts

@@ -2,7 +2,7 @@
 import * as path from "../path/mod.ts";
 import { ensureDir, ensureDirSync } from "./ensure_dir.ts";
 import { exists, existsSync } from "./exists.ts";
-import { getFileInfoType } from "./utils.ts";
+import { getFileInfoType } from "./_util.ts";
 
 /**
  * Ensures that the link exists.

std/fs/expand_glob.ts

@@ -4,7 +4,6 @@ import {
  globToRegExp,
  isAbsolute,
  isGlob,
- isWindows,
  joinGlobs,
  normalize,
 } from "../path/mod.ts";
@@ -19,6 +18,8 @@ import { assert } from "../testing/asserts.ts";
 const { cwd } = Deno;
 type FileInfo = Deno.FileInfo;
 
+const isWindows = Deno.build.os == "windows";
+
 export interface ExpandGlobOptions extends GlobOptions {
  root?: string;
  exclude?: string[];

std/fs/move.ts

@@ -1,6 +1,6 @@
 // Copyright 2018-2020 the Deno authors. All rights reserved. MIT license.
 import { exists, existsSync } from "./exists.ts";
-import { isSubdir } from "./utils.ts";
+import { isSubdir } from "./_util.ts";
 
 interface MoveOptions {
  overwrite?: boolean;