diff --git a/std/manual.md b/std/manual.md index 1e8fefcb10..b4122fd083 100644 --- a/std/manual.md +++ b/std/manual.md @@ -27,7 +27,7 @@ It's built on V8, Rust, and Tokio. enabled). - Supports TypeScript out of the box. - Ships a single executable (`deno`). -- Has built in utilities like a dependency inspector (`deno info`) and a code +- Has built-in utilities like a dependency inspector (`deno info`) and a code formatter (`deno fmt`). - Has [a set of reviewed (audited) standard modules](https://github.com/denoland/deno/tree/master/std) @@ -592,7 +592,7 @@ for that module is located, you can specify the type definition at import. This takes the form of a compiler hint. Compiler hints inform Deno the location of `.d.ts` files and the JavaScript code that is imported that they relate to. The hint is `@deno-types` and when specified the value will be used in the compiler -instead of the JavaScript module. For example if you had `foo.js`, but you know +instead of the JavaScript module. For example, if you had `foo.js`, but you know that along side of it was `foo.d.ts` which was the types for the file, the code would look like this: @@ -614,11 +614,11 @@ the program. #### Triple-slash reference directive in JavaScript files If you are hosting modules which you want to be consumed by Deno, and you want -to inform Deno the location of the type definitions, you can utilise a +to inform Deno about the location of the type definitions, you can utilise a triple-slash directive in the actual code. For example, if you have a JavaScript -module, where you want to provide Deno with the location of the type definitions -for that JavaScript file, which happens to be along side that file. You -JavaScript module named `foo.js` might look like this: +module and you would like to provide Deno with the location of the type +definitions which happen to be alongside that file, your JavaScript module named +`foo.js` might look like this: ```js /// @@ -667,10 +667,10 @@ that Deno supports. By default, the compiler runtime APIs which type check TypeScript also use these libraries (`Deno.compile()` and `Deno.bundle()`). But if you want to compile or bundle TypeScript for some other runtime, you may -want to override the default libraries. In order to do this, the runtime APIs -support the `lib` property in the compiler options. For example, if you had -TypeScript code that is destined for the browser, you would want to use the -TypeScript `"dom"` library: +want to override the default libraries. To do this, the runtime APIs support the +`lib` property in the compiler options. For example, if you had TypeScript code +that is destined for the browser, you would want to use the TypeScript `"dom"` +library: ```ts const [errors, emitted] = await Deno.compile( @@ -730,9 +730,9 @@ errors logged as part of the compilation. #### Using the triple slash reference -You do not have to specify the `lib` in just the compiler options. Deno supports +You do not have to specify the `lib` in the compiler options. Deno also supports [the triple-slash reference to a lib](https://www.typescriptlang.org/docs/handbook/triple-slash-directives.html#-reference-lib-). -and could be embedded in the contents of the file. For example of you have a +which can be embedded in the contents of the file. For example, if you have a `main.ts` like: ```ts @@ -741,7 +741,7 @@ and could be embedded in the contents of the file. For example of you have a document.getElementById("foo"); ``` -It would compiler without errors like this: +It would compile without errors like this: ```ts const [errors, emitted] = await Deno.compile("./main.ts", undefined, { @@ -841,8 +841,8 @@ The bundle can just be run as any other module in Deno would: deno colors.bundle.js ``` -The output is a self contained ES Module, which any exports from the main module -supplied on the command line will be available. For example if the main module +The output is a self contained ES Module, where any exports from the main module +supplied on the command line will be available. For example, if the main module looked something like this: ```ts @@ -877,8 +877,8 @@ Or you could import it into another ES module to consume: Deno provides ability to easily install and distribute executable code via `deno install` command. -`deno install [FLAGS...] [EXE_NAME] [URL] [SCRIPT_ARGS...]` will install script -available at `URL` with name `EXE_NAME`. +`deno install [FLAGS...] [EXE_NAME] [URL] [SCRIPT_ARGS...]` will install the +script available at `URL` under the name `EXE_NAME`. This command is a thin wrapper that creates executable shell scripts which invoke `deno` with specified permissions and CLI flags. @@ -937,8 +937,8 @@ if (import.meta.main) { } ``` -When you create executable script make sure to let users know by adding example -installation command to your repository: +When you create an executable script make sure to let users know by adding an +example installation command to your repository: ```shell # Install using deno install @@ -966,14 +966,14 @@ To update or create a lock use `--lock=lock.json --lock-write`. Deno supports [import maps](https://github.com/WICG/import-maps). -One can use import map with `--importmap=` CLI flag. +You can use import map with the `--importmap=` CLI flag. Current limitations: - single import map - no fallback URLs - Deno does not support `std:` namespace -- Does supports only `file:`, `http:` and `https:` schemes +- supports only `file:`, `http:` and `https:` schemes Example: @@ -1031,7 +1031,7 @@ console.log(fib(20)); ## Compiler API -Deno supports runtime access to the built in TypeScript compiler. There are +Deno supports runtime access to the built-in TypeScript compiler. There are three methods in the `Deno` namespace that provide this access. ### `Deno.compile()` @@ -1039,7 +1039,7 @@ three methods in the `Deno` namespace that provide this access. This works similar to `deno fetch` in that it can fetch code, compile it, but not run it. It takes up to three arguments, the `rootName`, optionally `sources`, and optionally `options`. The `rootName` is the root module which -will be used to generate the resulting program. This is like module name you +will be used to generate the resulting program. This is like the module name you would pass on the command line in `deno --reload run example.ts`. The `sources` is a hash where the key is the fully qualified module name, and the value is the text source of the module. If `sources` is passed, Deno will resolve all the @@ -1048,11 +1048,11 @@ If `sources` are not provided, Deno will resolve modules as if the root module had been passed on the command line. Deno will also cache any of these resources. The `options` argument is a set of options of type `Deno.CompilerOptions`, which is a subset of the TypeScript compiler options -which can be supported by Deno. +containing the ones supported by Deno. -The method resolves with a tuple where the first argument is any diagnostics -(syntax or type errors) related to the code, and a map of the code, where the -key would be the output filename and the value would be the content. +The method resolves with a tuple. The first argument contains any diagnostics +(syntax or type errors) related to the code. The second argument is a map where +the keys are the output filenames and the values are the content. An example of providing sources: @@ -1078,7 +1078,7 @@ const [diagnostics, emitMap] = await Deno.compile( ); ``` -We should get back in the `emitMap` a simple `console.log()` statement. +In this case `emitMap` will contain a simple `console.log()` statement. ### `Deno.bundle()` @@ -1097,7 +1097,7 @@ outside of Deno. If `sources` are not provided, Deno will resolve modules as if the root module had been passed on the command line. Deno will also cache any of these resources. The `options` argument is a set of options of type `Deno.CompilerOptions`, which is a subset of the TypeScript compiler options -which can be supported by Deno. +containing the ones supported by Deno. An example of providing sources: @@ -1123,7 +1123,7 @@ const [diagnostics, emit] = await Deno.bundle( ); ``` -We should get back in `emit` a self contained JavaScript ES module with all of +In this case `emit` will be a self contained JavaScript ES module with all of its dependencies resolved and exporting the same exports as the source module. ### `Deno.transpileOnly()` @@ -1131,15 +1131,14 @@ its dependencies resolved and exporting the same exports as the source module. This is based off of the TypeScript function `transpileModule()`. All this does is "erase" any types from the modules and emit JavaScript. There is no type checking and no resolution of dependencies. It accepts up to two arguments, the -first is a hash where the key is the module name and the value is the contents. +first is a hash where the key is the module name and the value is the content. The only purpose of the module name is when putting information into a source -map, of what the source file name was. The second is optionally `options` which -is of type `Deno.CompilerOptions`. This is a subset of options which can be -supported by Deno. It resolves with a map where the key is the source module -name supplied, and the value is an object with a property of `source` which is -the output contents of the module, and optionally `map` which would be the -source map. By default, source maps are output, but can be turned off via the -`options` argument. +map, of what the source file name was. The second argument contains optional +`options` of the type `Deno.CompilerOptions`. The function resolves with a map +where the key is the source module name supplied, and the value is an object +with a property of `source` and optionally `map`. The first is the output +contents of the module. The `map` property is the source map. Source maps are +provided by default, but can be turned off via the `options` argument. An example: @@ -1157,20 +1156,19 @@ enumerable, and the map to be defined. ## TypeScript Compiler Options -In Deno ecosystem, all strict flags are enabled in order to comply with -TypeScript ideal of being `strict` by default. However, in order to provide a +In the Deno ecosystem, all strict flags are enabled in order to comply with +TypeScript's ideal of being `strict` by default. However, in order to provide a way to support customization a configuration file such as `tsconfig.json` might be provided to Deno on program execution. -You do need to explicitly tell Deno where to look for this configuration, in -order to do so you can use the `-c` argument when executing your application. +You need to explicitly tell Deno where to look for this configuration by setting +the `-c` argument when executing your application. ```bash deno -c tsconfig.json mod.ts ``` -Currently allowed settings, as well as their default values in Deno go as -follows: +Following are the currently allowed settings and their default values in Deno: ```json { @@ -1210,8 +1208,8 @@ follows: } ``` -For documentation on allowed values and use cases please visit -https://www.typescriptlang.org/docs/handbook/compiler-options.html +For documentation on allowed values and use cases please visit the +[typescript docs](https://www.typescriptlang.org/docs/handbook/compiler-options.html). **Note**: Any options not listed above are either not supported by Deno or are listed as deprecated/experimental in the TypeScript documentation. @@ -1219,11 +1217,10 @@ listed as deprecated/experimental in the TypeScript documentation. ## Program lifecycle Deno supports browser compatible lifecycle events: `load` and `unload`. You can -use these event to provide setup and cleanup code in your program. +use these events to provide setup and cleanup code in your program. -`load` event listener supports asynchronous functions and will await these -functions. `unload` event listener supports only synchronous code. Both events -are not cancellable. +Listener for `load` events can be asynchronous and will be awaited. Listener for +`unload` events need to be synchronous. Both events cannot be cancelled. Example: @@ -1318,7 +1315,7 @@ console.log(resources()); #### Metrics -Metrics is Deno's internal counters for various statics. +Metrics is Deno's internal counter for various statistics. ```shell > console.table(Deno.metrics())