foster/denoland-deno
1
0
Fork 0
mirror of https://github.com/denoland/deno.git synced 2024-11-26 16:09:27 -05:00
Code Issues Packages 1 Wiki Activity

Manual introduction improvements (#3157)

Browse source
This commit is contained in:
Andy Fleming 2019-10-21 08:45:52 -07:00 committed by Ry Dahl
parent 27cd2c97f1
commit 2b2868b8a7
1 changed files with 69 additions and 54 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

123
website/manual.md
View file

@ -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 href="https://github.com/denoland/deno/tree/master/std">a set
of reviewed (audited) standard modules</a> 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
<!-- prettier-ignore-start -->
<!-- see https://github.com/prettier/prettier/issues/3679 -->
<!-- prettier incorrectly moves the coming soon links to new lines -->
- 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)
<!-- prettier-ignore-end -->
### Non-goals
- No `package.json`.
- No npm.
- Not explicitly compatible with Node.
## Setup
### Binary Install