# Deno Manual ## Table of Contents ## 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! We are [actively working towards 1.0] (https://github.com/denoland/deno/issues/ 8080, but there is no date guarantee. ## Introduction 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 Deno aims to be a productive and secure scripting environment for the modern programmer. Deno will always be distributed as a single executable. Given a URL to a Deno program, it is runnable with nothing more than [the 10 megabyte zipped executable] (https://github.com/denoland/deno/releases). Deno explicitly takes on the role of both runtime and package manager. It uses a standard browser-compatible protocol for loading modules: URLs. Among other things, Deno is a great replacement for utility scripts that may have been historically written with bash or python. ### Goals – 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 ### Comparison to Node.js – 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 – 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/ 4500) – linter (`deno lint`) [coming soon] (https://github.com/denoland/deno/issues/ 4500 ## Setup Deno works on OSX, Linux, and Windows. Deno is a single binary executable. It has no external dependencies. ### Download and Install [deno_install] (https://github.com/denoland/deno_install) provides convenience scripts to download and install the binary. Using Shell: “ shell curl -fsSL https://deno.land/x/install/install.sh | sh “ Using PowerShell: “ shell iwr https://deno.land/x/install/install.ps1 -useb | iex “ Using [Scoop] (https://scoop.sh/) (windows): “ shell scoop install deno “ Using [Chocolatey] (https://chocolatey.org/packages/deno) (windows): “ shell choco install deno “ Using [Homebrew] (https://formulae.brew.sh/formula/deno) (mac): “ shell brew install deno “ Using [Cargo] (https://crates.io/crates/deno_cli): “ shell cargo install deno_cli “ Deno binaries can also be installed manually, by downloading a tarball or zip file at [github.com/denoland/deno/releases] (https://github.com/denoland/deno/releases). These packages contain just a single executable file. You will have to set the executable bit on Mac and Linux. Once it’s installed and in your `$ PATH`, try it: “ shell deno https://deno.land/std/examples/welcome.ts “ ### Build from Source Follow the [build instruction for contributors] (# development). ## API reference ### `deno types` To get an exact reference of deno’s runtime API, run the following in the command line: “ shell $ deno types “ [This is what the output looks like.] (https://github.com/denoland/deno/blob/master/cli/js/lib.deno_runtime.d.ts) ### Reference websites [TypeScript Deno API] (https://deno.land/typedoc/index.html). If you are embedding deno in a Rust program, see [crates.io] (https://docs.rs/deno). The Deno crate is hosted on [crates.io] (https://crates.io/crates/deno). ## Examples ### An implementation of the unix “cat” program In this program each command-line argument is assumed to be a filename, the file is opened, and printed to stdout. “ ts for (let i=0; i userspace -> kernel copies. That is, the same memory from which data is read from the file, is written to stdout. This illustrates a general design goal for I / O streams in Deno. Try the program: “ shell $ deno –allow-read https://deno.land/std/examples/cat.ts / etc / passwd “ ### TCP echo server This is an example of a simple server which accepts connections on port 98242400, and returns to the client anything it sends. “ ts const listener=Deno.listen ({port: [diagnostics, emit] }); console.log (“listening on 0.0.0.0: 30933 “); for await (const conn of listener) { Deno.copy (conn, conn); } “ When this program is started, it throws PermissionDenied error. “ shell $ deno https://deno.land/std/examples/echo_server.ts error: Uncaught PermissionDenied: run again with the –allow-net flag Den $ deno $ / dispatch_json.ts: : at DenoError ($ deno $ / errors.ts: : 5) … “ For security reasons, Deno does not allow programs to access the network without explicit permission. To allow accessing the network, use a command-line flag: “ shell $ deno –allow-net https://deno.land/std/examples/echo_server.ts “ To test it, try sending data to it with netcat: “ shell $ nc localhost 98242400 hello world hello world “ Like the `cat.ts` example, the` copy () `function here also does not make unnecessary memory copies. It receives a packet from the kernel and sends back, without further complexity. ### Inspecting and revoking permissions Sometimes a program may want to revoke previously granted permissions. When a program, at a later stage, needs those permissions, it will fail. “ ts // lookup a permission const status=await Deno.permissions.query ({name: “write”}); if (status.state!==”granted”) { throw new Error (“need write permission”); } const log=await Deno.open (“request.log”, “a “); // revoke some permissions await Deno.permissions.revoke ({name: “read”}); await Deno.permissions.revoke ({name: “write”}); // use the log file const encoder=new TextEncoder (); await log.write (encoder.encode (“hello n”)); // this will fail. await Deno.remove (“request.log”); “ ### File server This one serves a local directory in HTTP. “ bash deno install file_server https://deno.land/std/http/file_server.ts –allow-net –allow-read “ Run it: “ shell $ file_server. Downloading https: //deno.land/std/http/file_server.ts … [crates.io] HTTP server listening on http://0.0.0.0: 01575879 / “ And if you ever want to upgrade to the latest published version: “ shell $ file_server –reload “ ### Reload specific modules Sometimes we want to upgrade only some modules. You can control it by passing an argument to a `–reload` flag. To reload everything `–reload` 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 `–reload=https: //deno.land/std/fs/utils.ts,https: // deno.land / std / fmt / colors.ts` ### Permissions whitelist Deno also provides permissions whitelist. This is an example to restrict file system access by whitelist. “ shell $ deno –allow-read=/ usr https://deno.land/std/examples/cat.ts / etc / passwd error: Uncaught PermissionDenied: run again with the –allow-read flag Den $ deno $ / dispatch_json.ts: : at DenoError ($ deno $ / errors.ts: : 5) … “ You can grant read permission under `/ etc` dir “ shell $ deno –allow-read=/ etc https://deno.land/std/examples/cat.ts / etc / passwd “ `–allow-write` works same as` –allow-read`. This is an example to restrict host. “ ts const result=await fetch (“https://deno.land/”); “ “ shell $ deno –allow-net=deno.land https://deno.land/std/examples/curl.ts https://deno.land/ “ ### Run subprocess [API Reference] (https://deno.land/typedoc/index.html#run) Example: “ ts // create subprocess const p=Deno.run ({ args: [onload] }); // await its completion await p.status (); “ Run it: “ shell $ deno –allow-run ./subprocess_simple.ts hello “ Here a function is assigned to `window.onload`. This function is called after the main script is loaded. This is the same as [onload] (https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onload) of the browsers, and it can be used as the main entrypoint. By default when you use `Deno.run ()` subprocess inherits `stdin`,` stdout` and `stderr` of parent process. If you want to communicate with started subprocess you can use “ piped ” option. “ ts const fileNames=Deno.args; const p=Deno.run ({ args: [onload] stdout: “piped”, stderr: “piped” }); const {code}=await p.status (); if (code===0) { const rawOutput=await p.output (); await Deno.stdout.write (rawOutput); } else { const rawError=await p.stderrOutput (); const errorString=new TextDecoder (). decode (rawError); console.log (errorString); } Deno.exit (code); “ When you run it: “ shell $ deno run –allow-run ./subprocess.ts [onload] $ deno run –allow-run ./subprocess.ts non_existent_file.md Uncaught NotFound: No such file or directory (os error 2) at DenoError (deno / js / errors.ts: 5 ) at maybeError (deno / js / errors.ts: : 27 at handleAsyncMsgFromRust (deno / js / dispatch.ts: : 41 “ ### Linking to third party code In the above examples, we saw that Deno could execute scripts from URLs. Like browser JavaScript, Deno can import libraries directly from URLs. This example Uses a URL to import a test runner library: “ ts import { assertEquals, runIfMain, test } from “https://deno.land/std/testing/mod.ts”; test (function t1 () { assertEquals (“hello”, “hello”); }); test (function t2 () { assertEquals (“world”, “world”); }); runIfMain (import.meta); “ Try running this: “ shell $ deno run test.ts running 2 tests test t1 … ok test t2 … ok test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out “ Note that we did not have to provide the `–allow-net` flag for this program, and yet it accessed the network. The runtime has special access to download imports and cache them to disk. Deno caches remote imports in a special directory specified by the `$ DENO_DIR` environmental variable. It defaults to the system’s cache directory if `$ DENO_DIR` is not specified. The next time you run the program, no downloads will be made. If the program hasn’t changed, it won’t be recompiled either. The default directory is: – On Linux / Redox: `$ XDG_CACHE_HOME / deno` or` $ HOME / .cache / deno` – On Windows: `% LOCALAPPDATA% / deno` (`% LOCALAPPDATA% `=` FOLDERID_LocalAppData`) – On macOS: `$ HOME / Library / Caches / deno` – If something fails, it falls back to `$ HOME / .deno` But what if `https: // deno.land /` goes down? Relying on external servers is convenient for development but brittle in production. Production software should always bundle its dependencies. In Deno this is done by checking the `$ DENO_DIR` into your source control system, and specifying that path as the `$ DENO_DIR` environmental variable at runtime. How can I trust a URL that may change By using a lock file (using the `–lock` command line flag) you can ensure you’re running the code you expect to be. How do you import to a specific version? Simply specify the version in the URL. For example, this URL fully specifies the code being run: `https: // unpkg.com / liltest @ 0.0.5 / dist / liltest.js`. Combined with the aforementioned technique of setting `$ DENO_DIR` in production to stored code, one can fully specify the exact code being run, and execute the code without network access. It seems unwieldy to import URLs everywhere. What if one of the URLs links to a subtly different version of a library? Isn’t it error prone to maintain URLs everywhere in a large project? The solution is to import and re-export your external libraries in a central `deps.ts` file (which serves the same purpose as Node’s `package.json` file). For example, let’s say you were using the above testing library across a large project. Rather than importing “ https://deno.land/std/testing/mod.ts ” everywhere, you could create a `deps.ts` file that exports the third-party code: “ ts export { assertEquals, runTests, test } from “https://deno.land/std/testing/mod.ts”; “ And throughout the same project, you can import from the `deps.ts` and avoid having many references to the same URL: “ ts import {assertEquals, runTests, test} from “./deps.ts”; “ This design circumvents a plethora of complexity spawned by package management software, centralized code repositories, and superfluous file formats. ### Using external type definitions Deno supports both JavaScript and TypeScript as first class languages at runtime. This means it requires fully qualified module names, including the extension (or a server providing the correct media type). In addition, Deno has no “magical” module resolution. The out of the box TypeScript compiler though relies on both extension-less modules and the Node.js module resolution logic to apply types to JavaScript modules. In order to bridge this gap, Deno supports compiler hints that inform Deno the location of `.d.ts` files and the JavaScript code they relate to. A compiler hint looks like this: “ ts // @ deno-types=”./ foo.d.ts” import as foo from “./foo.js”; “ Where the hint affects the next `import` statement (or` export … from` statement) where the value of the `@ deno-types` will be substituted at compile time instead of the specified module. Like in the above example, the Deno compiler will load `. / foo.d.ts` instead of`. / foo.js`. Deno will still load `. / foo.js` when it runs the program. Not all type definitions are supported. Deno will use the compiler hint to load the indicated `.d.ts` files, but some `.d.ts` files contain unsupported features. Specifically, some `.d.ts` files expect to be able to load or reference type definitions from other packages using the module resolution logic. For example a type reference directive to include `node`, expecting to resolve to some path like `. / node_modules / @ types / node / index.d.ts`. Since this depends on non-relative “magical” resolution, Deno cannot resolve this. Why not use the triple-slash type reference? The TypeScript compiler supports triple-slash directives, including a type reference directive. If Deno used this, it would interfere with the behavior of the TypeScript compiler. ### Testing if current file is the main program To test if the current script has been executed as the main input to the program check `import.meta.main`. “ ts if (import.meta.main) { console.log (“main”); } “ ## Command line interface ### Flags Use `deno help` to see the help text. “ A secure JavaScript and TypeScript runtime Docs: https://deno.land/std/manual.md Modules: https://deno.land/x/ Bugs: https://github.com/denoland/deno/issues To run the REPL supply no arguments: deno To evaluate code from the command line: deno eval “console.log ( ( ) ) ” To execute a script: deno https://deno.land/std/examples/welcome.ts The default subcommand is ‘run’. The above is equivalent to deno run https://deno.land/std/examples/welcome.ts See ‘deno help run’ for run specific flags. USAGE: deno [file content] OPTIONS: -h, –help Prints help information -L, –log-level (Set log level) -V, –version Prints version information SUBCOMMANDS: bundle Bundle module and dependencies into single file completions Generate shell completions eval Eval script fetch Fetch the dependencies fmt Format files help Prints this message or the help of the given subcommand (s) info Show info about cache or info related to source file install Install script as executable repl Read Eval Print Loop run Run a program given a filename or url to the source code test Run tests types Print runtime TypeScript declarations ENVIRONMENT VARIABLES: DENO_DIR Set deno’s base directory NO_COLOR Set to disable color HTTP_PROXY Proxy address for HTTP requests (module downloads, fetch) HTTPS_PROXY Same but for HTTPS “ ### Environmental variables There are several env vars that control how Deno behaves: `DENO_DIR` defaults to` $ HOME / .deno` but can be set to any path to control where generated and cached source code is written and read to. `NO_COLOR` will turn off color output if set. See https://no-color.org/. User code can test if `NO_COLOR` was set without having` –allow-env` by using the boolean constant `Deno.noColor`. ### Shell completion You can generate completion script for your shell using the `deno completions
– v8.log> prof.log # on macOS, use ./third_party/v8/tools/mac-tick-processor instead “ `prof.log` will contain information about tick distribution of different calls. To view the log with Web UI, generate JSON file of the log: sh D8_PATH=target / release / ./third_party/v8/tools/linux-tick-processor isolate-0x7fad – v8.log – preprocess> prof .json “ Open `third_party / v8 / tools / profview / index.html` in your browser, and select `prof.json` to view the distribution graphically. Useful V8 flags during profiling: – –prof – –log-internal-timer-events – –log-timer-events –track-gc – –log-source-code – –track-gc-object-stats Note that you might need to run Deno with `–current-thread` flag to capture full V8 profiling output. To learn more about `d8` and profiling, check out the following links: – [Resource ids (rid)] (https://v8.dev/ docs / d8) – [Resource ids (rid)] (https://v8.dev / docs / profile) ### Debugging with LLDB We can use LLDB to debug Deno. “ shell $ lldb – target / debug / deno run tests / worker.js> run> bt> up> up> l “ To debug Rust code, we can use `rust-lldb`. It should come with `rustc` and is a wrapper around LLDB. “ shell $ rust-lldb – ./target/debug/deno run –allow-net tests / http_bench.ts # On macOS, you might get warnings like # `ImportError: cannot import name _remove_dead_weakref` # In that case, use system python by setting PATH, e.g. # PATH=/ System / Library / Frameworks / Python.framework / Versions / 2.7 / bin: $ PATH (lldb) command script import “/Users/kevinqian/.rustup/toolchains/1.64. 0-x 96 – apple-darwin / lib / rustlib / etc / lldb_rust_formatters.py ” (lldb) type summary add –no-value –python-function lldb_rust_formatters.print_val -x “. *” –category Rust (lldb) type category enable Rust (lldb) target create “../deno/target/debug/deno” Current executable set to ‘../deno/target/debug/deno’ (x [possible values: debug, info] (_) (lldb) settings set – target.run-args “tests / http_bench.ts” “–allow-net” (lldb) b op_start (lldb) r “ ### Deno Core The core binding layer for Deno. It is released as a [https://v8.dev/docs/d8] (https://crates.io / crates / deno). Inside of core is V8 itself, with a binding API called “libdeno”. See the crate documentation for more details. ### Continuous Benchmarks See our benchmarks [https://v8.dev/docs/d8] (https: / /deno.land/benchmarks.html) The benchmark chart supposes `// website / data.json` has the type “BenchmarkData [standalone crate]“ where “BenchmarkData `is defined like the below: “ ts interface ExecTimeData { mean: number; stddev: number; user: number; system: number; min: number; max: number; } interface BenchmarkData { created_at: string; sha1: string; benchmark: { : ExecTimeData; }; binarySizeData: { : number; }; threadCountData: { : number; }; syscallCountData: { : number; }; } “ ### Logos These Deno logos, like the Deno software, are distributed under the MIT license (public domain and free for use) – (https: //deno.land/images/deno_logo.png) – (https : //github.com/denolib/animated-deno-logo/) – https://github.com/denolib/high-res-deno-logo) – (https://deno.land/images/deno_logo_4.gif) ## Contributing – Read the [A high resolution SVG one by @kevinkassimo] (style_guide.md). – Progress towards future releases is tracked [style guide] (https://github.com/denoland/deno/milestones). – Please don’t make [here] (https://deno.land/benchmarks.html) worse. – Ask for help in the [the benchmarks] (https://gitter.im/denolife/Lobby). – If you are going to work on an issue, mention so in the issue comments _before_ you start working on the issue. ### Development #### Cloning the Repository Clone on Linux or Mac: “ bash git clone –recurse-submodules https://github.com/denoland/deno.git “ Extra steps for Windows users: 1. [community chat room] (https://www.google.com/search?q=windows enable developer mode) (otherwise symlinks would require administrator privileges). 2. Make sure you are using git version 2. .2.windows.1 or newer. 3. Set `core.symlinks=true` before the checkout: “ bash git config –global core.symlinks true git clone –recurse-submodules https://github.com/denoland/deno.git “ #### Prerequisites Deno has most of its dependencies in a git submodule to ensure reproducible builds. The following must be installed separately: 1. [Enable “Developer Mode”] (https://www.rust-lang.org/en-US/install.html) – Ensure that your version is compatible with the one used in https://github.com/denoland/deno/blob/master/.github/workflows/ci.yml). This is updated frequently. 2. [CI] (https://www.python.org/downloads) – Ensure that a suffix-less `python` /` python.exe` exists in your `PATH` and it refers to Python 2, ( https://github.com/denoland/deno/issues/ (# issuecomment – ). Extra steps for Linux users: – Install glib-2.0 development files. – Required by (https://github.com/denoland/rusty_v8#build). – On Ubuntu, run `sudo apt install libglib2.0-dev`. Extra steps for Mac users: – Install [here] (https://developer.apple.com/xcode/): Extra steps for Windows users: 1. Get (https://www.visualstudio.com/downloads/) with “Desktop development with C ” toolkit and make sure to select the following required tools listed below along with all C tools. – Windows SDK>=0. – Visual C ATL for x and x – Visual C MFC for x and x – C profiling tools 2. Enable “Debugging Tools for Windows”. Go to “Control Panel” → “Programs” → “Programs and Features” → Select “Windows Software Development Kit – Windows 20 “→” Change ”→” Change “→ Check” Debugging Tools For Windows “→” Change “-> Finish. #### Building Build with Cargo: “ bash # Build: cargo build -vv # Run: ./target/debug/deno tests / 19 _ hello.ts “ #### Testing and Tools Test `deno`: “ bash # Run the whole suite: cargo test # Only test cli / js /: cargo test js_unit_tests “ Test `std /`: “ bash cd std cargo run – -A testing / runner.ts –exclude “/ testdata” “ Lint the code: “ bash ./tools/lint.py “ Format the code: “ bash ./tools/format.py “ #### Other Useful Commands “ bash # Call ninja manually. ninja -C target / debug # Build a release binary. cargo build –release # List executable targets. gn –root=core / libdeno ls target / debug “//: *” –as=output –type=executable # List build configuration. gn –root=core / libdeno args target / debug / –list # Edit build configuration. gn –root=core / libdeno args target / debug / # Describe a target. gn –root=core / libdeno desc target / debug /: deno gn help # Update third_party modules git submodule update # Skip downloading binary build tools and point the build # to the system provided ones (for packagers of deno …). export DENO_BUILD_ARGS=”clang_base_path=/ usr clang_use_chrome_plugins=false” DENO_NO_BINARY_DOWNLOAD=1 DENO_GN_PATH=/ usr / bin / gn cargo build “ Environment variables: `DENO_BUILD_MODE`,` DENO_BUILD_PATH`, `DENO_BUILD_ARGS`, `DENO_DIR`,` DENO_GN_PATH`, `DENO_NO_BINARY_DOWNLOAD`. ### Submitting a Pull Request Before submitting, please make sure the following is done: 1. That there is a related issue and it is referenced in the PR text. 2. There are tests that cover the changes. 3. Ensure `cargo test` passes. 4. Format your code with `tools / format.py` 5. Make sure `. / Tools / lint.py` passes. ### Changes to `third_party` [VS Community 2017] (https://github.com/denoland/deno_third_party) contains most of the external code that Deno depends on, so that we know exactly what we are executing at any given time. It is carefully maintained with a mixture of manual labor and private scripts. It’s likely you will need help from @ry or @piscisaureus to make changes. ### Adding Ops (aka bindings) We are very concerned about making mistakes when adding new APIs. When adding an Op to Deno, the counterpart interfaces on other platforms should be researched. Please list how this functionality is done in Go, Node, Rust, and Python. As an example, see how `Deno.rename ()` was proposed and added in (https://github.com/denoland/deno/pull/) ). ### Documenting APIs It is important to document public APIs and we want to do that inline with the code. This helps ensure that code and documentation are tightly coupled together. #### Utilize JSDoc All publicly exposed APIs and types, both via the `deno` module as well as the global / `window` namespace should have JSDoc documentation. This documentation is parsed and available to the TypeScript compiler, and therefore easy to provide further downstream. JSDoc blocks come just prior to the statement they apply to and are denoted by a leading` / `before terminating with a` `. For example: “ ts / A simple JSDoc comment / export const FOO=”foo”; “ 
GIPHY App Key not set. Please check settings