From 2b2868b8a77bb545238ce19e039e2018578fb5ad Mon Sep 17 00:00:00 2001 From: Andy Fleming Date: Mon, 21 Oct 2019 08:45:52 -0700 Subject: [PATCH] Manual introduction improvements (#3157) --- website/manual.md | 123 ++++++++++++++++++++++++++-------------------- 1 file changed, 69 insertions(+), 54 deletions(-) diff --git a/website/manual.md b/website/manual.md index bb75114c4c..e1dc76aaa6 100644 --- a/website/manual.md +++ b/website/manual.md @@ -2,15 +2,37 @@ [toc] -## Disclaimer +## Project Status / Disclaimer -A word of caution: Deno is very much under development. We encourage brave early -adopters, but expect bugs large and small. The API is subject to change without -notice. [Bug reports](https://github.com/denoland/deno/issues) do help! +**A word of caution: Deno is very much under development.** + +We encourage brave early adopters, but expect bugs large and small. The API is +subject to change without notice. +[Bug reports](https://github.com/denoland/deno/issues) do help! + +We are +[actively working towards 1.0](https://github.com/denoland/deno/issues/2473), +but there is no date guarantee. ## Introduction -A secure JavaScript/TypeScript runtime built with V8, Rust, and Tokio +Deno is a JavaScript/TypeScript runtime with secure defaults and a great +developer experience. + +It's built on V8, Rust, and Tokio. + +### Feature Highlights + +- Secure by default. No file, network, or environment access (unless explicitly + 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 + formatter (`deno fmt`). +- Has + [a set of reviewed (audited) standard modules](https://github.com/denoland/deno/tree/master/std) + that are guaranteed to work with Deno. +- Scripts can be bundled into a single javascript file. ### Philosophy @@ -23,69 +45,62 @@ program, it is runnable with nothing more than Deno explicitly takes on the role of both runtime and package manager. It uses a standard browser-compatible protocol for loading modules: URLs. -Deno provides security guarantees about how programs can access your system with -the default being the most restrictive secure sandbox. - -Deno provides a set -of reviewed (audited) standard modules that are guaranteed to work with -Deno. +Among other things, Deno is a great replacement for utility scripts that may +have been historically written with bash or python. ### Goals -- Support TypeScript out of the box. - -- Uses "ES Modules" and does not support `require()`. Like the browser, allows - imports from URLs: - - ```ts - import * as log from "https://deno.land/std/log/mod.ts"; - ``` - -- Remote code is fetched and cached on first execution, and never updated until - the code is run with the `--reload` flag. (So, this will still work on an - airplane. See `~/.deno/src` for details on the cache.) - -- File system and network access can be controlled in order to run sandboxed - code. Access between V8 (unprivileged) and Rust (privileged) is only done via - serialized messages. This makes it easy to audit. For example, to enable write - access use the flag `--allow-write` or for network access `--allow-net`. - -- Only ship a single executable. - -- Always dies on uncaught errors. - +- Only ship a single executable (`deno`). +- Provide Secure Defaults + - Unless specifically allowed, scripts can't access files, the environment, or + the network. - Browser compatible: The subset of Deno programs which are written completely in JavaScript and do not use the global `Deno` namespace (or feature test for it), ought to also be able to be run in a modern web browser without change. +- Provide built-in tooling like unit testing, code formatting, and linting to + improve developer experience. +- Does not leak V8 concepts into user land. +- Be able to serve HTTP efficiently -- [Aims to support top-level `await`.](https://github.com/denoland/deno/issues/471) +### Comparison to Node.js -- Be able to serve HTTP efficiently. - ([Currently it is relatively slow.](https://deno.land/benchmarks.html#req-per-sec)) +- Deno does not use `npm` + - It uses modules referenced as URLs or file paths +- Deno does not use `package.json` in its module resolution algorithm. +- All async actions in Deno return a promise. Thus Deno provides different APIs + than Node. +- Deno requires explicit permissions for file, network, and environment access. +- Deno always dies on uncaught errors. +- Uses "ES Modules" and does not support `require()`. Third party modules are + imported via URLs: + +```javascript +import * as log from "https://deno.land/std/log/mod.ts"; +``` + +### Other key behaviors + +- Remote code is fetched and cached on first execution, and never updated until + the code is run with the `--reload` flag. (So, this will still work on an + airplane.) +- Modules/files loaded from remote URLs are intended to be immutable and + cacheable. + +## Built-in Deno Utilities / Commands - + -- Provide useful tooling out of the box: - - dependency inspector (`deno info`) - - code formatter (`deno fmt`), - - bundling (`deno bundle`) - - runtime type info (`deno types`) - - test runner (`deno test`) - - command-line debugger (`--debug`) - [not yet](https://github.com/denoland/deno/issues/1120) - - linter (`deno lint`) [not yet](https://github.com/denoland/deno/issues/1880) +- dependency inspector (`deno info`) +- code formatter (`deno fmt`) +- bundling (`deno bundle`) +- runtime type info (`deno types`) +- test runner (`deno test`) +- command-line debugger (`--debug`) [coming soon](https://github.com/denoland/deno/issues/1120) +- linter (`deno lint`) [coming soon](https://github.com/denoland/deno/issues/1880) -### Non-goals - -- No `package.json`. - -- No npm. - -- Not explicitly compatible with Node. - ## Setup ### Binary Install