├── docs
    ├── rustdoc
    ├── typedoc
    ├── welcome.ts
    ├── favicon.ico
    ├── images
    │   ├── deno_logo.png
    │   ├── deno_logo_2.gif
    │   ├── schematic_v0.2.png
    │   └── deno_logo_3.svg
    ├── toc.js
    ├── sticky_toc.js
    ├── manual.html
    ├── style_guide.html
    ├── style.css
    ├── showdown_toc.js
    ├── app_test.js
    ├── benchmarks.html
    ├── style_guide.zh.md
    ├── index.html
    ├── app.js
    ├── style_guide.md
    ├── manual.zh.md
    └── manual.md
├── .mds-list
├── .gitignore
├── sync-en.sh
├── readme.md
├── style_guide.zh.md
├── style_guide.md
├── manual.zh.md
└── manual.md


/docs/rustdoc:
--------------------------------------------------------------------------------
1 | ../target/doc/


--------------------------------------------------------------------------------
/docs/typedoc:
--------------------------------------------------------------------------------
1 | ../target/typedoc/


--------------------------------------------------------------------------------
/.mds-list:
--------------------------------------------------------------------------------
1 | source/manual.md
2 | source/style_guide.md
3 | 


--------------------------------------------------------------------------------
/docs/welcome.ts:
--------------------------------------------------------------------------------
1 | console.log("Welcome to Deno 🦕");
2 | 


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | node_modules/
2 | .DS_Store
3 | fork
4 | source
5 | hub-create.sh


--------------------------------------------------------------------------------
/docs/favicon.ico:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/chinanf-boy/deno-website-zh/master/docs/favicon.ico


--------------------------------------------------------------------------------
/docs/images/deno_logo.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/chinanf-boy/deno-website-zh/master/docs/images/deno_logo.png


--------------------------------------------------------------------------------
/docs/images/deno_logo_2.gif:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/chinanf-boy/deno-website-zh/master/docs/images/deno_logo_2.gif


--------------------------------------------------------------------------------
/docs/images/schematic_v0.2.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/chinanf-boy/deno-website-zh/master/docs/images/schematic_v0.2.png


--------------------------------------------------------------------------------
/docs/toc.js:
--------------------------------------------------------------------------------
 1 | (function() {
 2 |   let H = `<div><ol>`;
 3 | 
 4 |   function liEl(str, id) {
 5 |     return `<li><a href="#${id}">${str}</a></li>`;
 6 |   }
 7 | 
 8 |   function run() {
 9 |     setTimeout(() => {
10 |       if (window.anchors && window.anchors.elements.length) {
11 |         let lis = window.anchors.elements.map(el => {
12 |           return liEl(el.innerText, el.id);
13 |         });
14 |         let result = `${H}${lis.join('\n')}</ol></div>`;
15 |         document.getElementsByClassName("toc")[0].innerHTML = result;
16 |       } else {
17 |         console.log('query anchors again');
18 |         run();
19 |       }
20 |     }, 100);
21 |   }
22 | 
23 |   run();
24 | })();
25 | 


--------------------------------------------------------------------------------
/sync-en.sh:
--------------------------------------------------------------------------------
 1 | cat './.mds-list' | while read line || [[ -n ${line} ]]
 2 | do
 3 |     testseq="zh.md"
 4 |     if [[ $line =~ $testseq || "$line" == "" ]]; then
 5 |         echo "skip $line"
 6 |     else
 7 |         lowline=`echo "$line" | awk '{print tolower($0)}'`
 8 |         # lowwer string
 9 |         zh=${line//source\//}
10 |         dir=$(dirname $zh)
11 |         
12 |         source_readme="./source/readme.md"
13 |         if [[ $lowline == $source_readme ]];then
14 |         # source/[readme|REAMDE].md => en.md
15 |         filename="en.md"
16 |         else 
17 |         # source/other.md => ./other.md
18 |         filename=$(basename $zh)
19 |         fi
20 |         echo "$line >> $dir/$filename"
21 |         mkdir -p $dir && cp $line "$_/$filename"
22 |     fi
23 | done


--------------------------------------------------------------------------------
/docs/sticky_toc.js:
--------------------------------------------------------------------------------
 1 | (function() {
 2 |   const isTopOut = function(elem) {
 3 |     const bounding = elem.getBoundingClientRect();
 4 |     return bounding.top <= 20 && bounding.left >= 0;
 5 |   };
 6 | 
 7 |   function changePosition(el, add) {
 8 |     if (add) {
 9 |       el.style.position = 'fixed'; // actually use fixed
10 |       el.style.top = '0em';
11 |       el.style.bottom = '1em';
12 |       // el.style.right = '0em';
13 |       el.style.maxHeight = 'max-content';
14 |       
15 |     } else {
16 |       el.style.position = 'absolute';
17 |       // el.style.right = '1em';
18 |       el.style.top = '';
19 |       el.style.bottom = '';
20 |     }
21 |   }
22 |   let manualEl;
23 |   let tocEl;
24 | 
25 |   window.addEventListener('scroll', event => {
26 |     !manualEl && (manualEl = document.getElementById('manual'));
27 |     !tocEl && (tocEl = document.getElementsByClassName('toc')[0]);
28 | 
29 |     if (window.innerWidth >= 1200) {
30 |       if (isTopOut(manualEl) && tocEl.style.position != 'fixed') {
31 |         changePosition(tocEl, true);
32 |       } else if (!isTopOut(manualEl) && tocEl.style.position == 'fixed') {
33 |         changePosition(tocEl, false);
34 |       }
35 |     }
36 |   });
37 | })();
38 | 


--------------------------------------------------------------------------------
/docs/manual.html:
--------------------------------------------------------------------------------
 1 | <!-- Copyright 2018-2019 the Deno authors. All rights reserved. MIT license. -->
 2 | <!DOCTYPE html>
 3 | <html>
 4 |   <head>
 5 |     <title>Deno Manual</title>
 6 |     <link rel="shortcut icon" href="favicon.ico" />
 7 |     <link
 8 |       href="https://cdn.bootcss.com/highlight.js/9.15.6/styles/default.min.css"
 9 |       rel="stylesheet"
10 |     />
11 |     <link
12 |       rel="stylesheet"
13 |       href="https://cdn.bootcss.com/highlight.js/9.15.6/styles/github-gist.min.css"
14 |     />
15 |     <script src="https://cdn.bootcss.com/highlight.js/9.15.6/highlight.min.js"></script>
16 |     <script src="https://cdn.bootcss.com/highlight.js/9.15.6/languages/typescript.min.js"></script>
17 |     <link rel="stylesheet" href="style.css" />
18 |     <meta content="width=device-width, initial-scale=1.0" name="viewport" />
19 |     <script src="https://cdn.bootcss.com/marked/0.6.2/marked.min.js"></script>
20 |     <script src="https://cdn.bootcss.com/anchor-js/4.2.0/anchor.min.js"></script>
21 |   </head>
22 |   <body>
23 |     <main>
24 |       <a href="/"><img id="logo" src="images/deno_logo_3.svg" width="200"/></a>
25 |       <div class="toc"></div>
26 |       <div id="manual"></div>
27 | 
28 |       <script>
29 |         const url = 'manual.zh.md';
30 | 
31 |         async function main() {
32 |           const response = await fetch(url);
33 |           const content = await response.text();
34 | 
35 |           const manual = document.getElementById('manual');
36 |           manual.innerHTML = marked(content);
37 | 
38 |           // Disable automatic language detection
39 |           hljs.configure({
40 |             languages: []
41 |           });
42 | 
43 |           hljs.initHighlighting();
44 | 
45 |           anchors.options = {
46 |             visible: 'hover',
47 |             placement: 'left',
48 |             icon: '¶'
49 |           };
50 |           anchors.add();
51 |         }
52 | 
53 |         main();
54 |       </script>
55 |     </main>
56 |     <script src="toc.js"></script>
57 |     <script src="sticky_toc.js"></script>
58 |   </body>
59 | </html>
60 | 


--------------------------------------------------------------------------------
/docs/style_guide.html:
--------------------------------------------------------------------------------
 1 | <!-- Copyright 2018-2019 the Deno authors. All rights reserved. MIT license. -->
 2 | <!DOCTYPE html>
 3 | <html>
 4 |   <head>
 5 |     <title>Deno Style Guide</title>
 6 |     <link rel="shortcut icon" href="favicon.ico" />
 7 |     <link
 8 |       href="https://cdn.bootcss.com/highlight.js/9.15.6/styles/default.min.css"
 9 |       rel="stylesheet"
10 |     />
11 |     <link
12 |       rel="stylesheet"
13 |       href="https://cdn.bootcss.com/highlight.js/9.15.6/styles/github-gist.min.css"
14 |     />
15 |     <script src="https://cdn.bootcss.com/highlight.js/9.15.6/highlight.min.js"></script>
16 |     <script src="https://cdn.bootcss.com/highlight.js/9.15.6/languages/typescript.min.js"></script>
17 |     <link rel="stylesheet" href="style.css" />
18 |     <meta content="width=device-width, initial-scale=1.0" name="viewport" />
19 |     <script src="https://cdn.bootcss.com/marked/0.6.2/marked.min.js"></script>
20 |     <script src="https://cdn.bootcss.com/anchor-js/4.2.0/anchor.min.js"></script>
21 |   </head>
22 |   <body>
23 |     <main>
24 |       <a href="/"><img id="logo" src="images/deno_logo_3.svg" width="200"/></a>
25 |       <div class="toc"></div>
26 |       <div id="manual"></div>
27 | 
28 |       <script>
29 |         const url = 'style_guide.zh.md';
30 | 
31 |         async function main() {
32 |           const response = await fetch(url);
33 |           const content = await response.text();
34 | 
35 |           const manual = document.getElementById('manual');
36 |           manual.innerHTML = marked(content);
37 | 
38 |           // Disable automatic language detection
39 |           hljs.configure({
40 |             languages: []
41 |           });
42 | 
43 |           hljs.initHighlighting();
44 | 
45 |           anchors.options = {
46 |             visible: 'hover',
47 |             placement: 'left',
48 |             icon: '¶'
49 |           };
50 |           anchors.add();
51 |         }
52 | 
53 |         main();
54 |       </script>
55 |     </main>
56 |     <script src="toc.js"></script>
57 |     <script src="sticky_toc.js"></script>
58 |   </body>
59 | </html>
60 | 


--------------------------------------------------------------------------------
/docs/style.css:
--------------------------------------------------------------------------------
  1 | body {
  2 |   color: #444;
  3 |   background: #f0f0f0;
  4 |   padding: 0;
  5 | 
  6 |   line-height: 1.5;
  7 |   font-family: sans-serif;
  8 | 
  9 |   margin: 5ex 10ex;
 10 |   max-width: 80ex;
 11 | }
 12 | 
 13 | #manual img {
 14 |   width: 100%;
 15 |   max-width: 800px;
 16 | }
 17 | 
 18 | h1,
 19 | h2,
 20 | h3,
 21 | h4 {
 22 |   font-weight: normal;
 23 |   margin-bottom: 0;
 24 | }
 25 | 
 26 | h1,
 27 | h2,
 28 | h3,
 29 | h4,
 30 | p,
 31 | table {
 32 |   margin-left: 8px;
 33 |   margin-right: 8px;
 34 | }
 35 | 
 36 | table {
 37 |   border-collapse: collapse;
 38 |   margin-top: 8px;
 39 | }
 40 | td,
 41 | th {
 42 |   font-weight: normal;
 43 |   text-align: center;
 44 |   border: 1px dotted #bbb;
 45 |   padding: 4px;
 46 | }
 47 | 
 48 | svg {
 49 |   margin: 0px;
 50 |   width: 100%;
 51 |   height: 300px;
 52 | }
 53 | 
 54 | a {
 55 |   color: #106ad5;
 56 | }
 57 | 
 58 | pre a {
 59 |   color: #001631;
 60 | }
 61 | 
 62 | h2 a,
 63 | h3 a {
 64 |   display: none;
 65 |   color: #3bace5;
 66 |   text-decoration: none;
 67 | }
 68 | 
 69 | h2:hover a,
 70 | h3:hover a {
 71 |   display: inline;
 72 | }
 73 | 
 74 | pre {
 75 |   /* background: rgba(36, 126, 233, 0.03); */
 76 |   color: #161616;
 77 |   background: rgba(36, 126, 233, 0.1);
 78 |   padding: 15px;
 79 |   word-wrap: normal;
 80 |   overflow-x: auto;
 81 | }
 82 | 
 83 | header {
 84 |   display: flex;
 85 |   align-items: center;
 86 |   margin: 16px 4px;
 87 | }
 88 | 
 89 | header > * {
 90 |   margin: 8px;
 91 | }
 92 | 
 93 | header h1 {
 94 |   margin: 8px 0;
 95 | }
 96 | 
 97 | @media only screen and (max-device-width: 480px) {
 98 |   body {
 99 |     margin: 0;
100 |   }
101 | }
102 | 
103 | code {
104 |   background: rgba(36, 126, 233, 0.1);
105 |   padding: 2px 5px;
106 |   color: #333;
107 | }
108 | 
109 | .hljs {
110 |   background: transparent;
111 | }
112 | 
113 | .toc {
114 |   position: relative;
115 | }
116 | 
117 | @media only screen and (min-width: 1250px) {
118 |   .toc {
119 |     background-color: #fbf6ec;
120 |     max-width: 40%;
121 |     position: absolute;
122 |     border: #968674 dashed 3px;
123 |     right: 1em;
124 |     width: var(--sidebar-width);
125 |     overflow-y: auto;
126 |     padding: 0 10px;
127 |     font-size: 0.875em;
128 |     box-sizing: border-box;
129 |     -webkit-overflow-scrolling: touch;
130 |     overscroll-behavior-y: contain;
131 |     background-color: var(--sidebar-bg);
132 |     color: var(--sidebar-fg);
133 |   }
134 | 
135 |   .toc li {
136 |     padding: 1px 3px;
137 |   }
138 | 
139 |   .toc::-webkit-scrollbar { 
140 |     display: none; 
141 |   } 
142 | }
143 | 
144 | 


--------------------------------------------------------------------------------
/docs/showdown_toc.js:
--------------------------------------------------------------------------------
  1 | // Extension loading compatible with AMD and CommonJs
  2 | (function(extension) {
  3 |   "use strict";
  4 | 
  5 |   if (typeof showdown === "object") {
  6 |     // global (browser or nodejs global)
  7 |     showdown.extension("toc", extension());
  8 |   } else if (typeof define === "function" && define.amd) {
  9 |     // AMD
 10 |     define("toc", extension());
 11 |   } else if (typeof exports === "object") {
 12 |     // Node, CommonJS-like
 13 |     module.exports = extension();
 14 |   } else {
 15 |     // showdown was not found so we throw
 16 |     throw Error("Could not find showdown library");
 17 |   }
 18 | })(function() {
 19 |   function getHeaderEntries(sourceHtml) {
 20 |     if (typeof window === "undefined") {
 21 |       return getHeaderEntriesInNodeJs(sourceHtml);
 22 |     } else {
 23 |       return getHeaderEntriesInBrowser(sourceHtml);
 24 |     }
 25 |   }
 26 | 
 27 |   function getHeaderEntriesInNodeJs(sourceHtml) {
 28 |     var cheerio = require("cheerio");
 29 |     var $ = cheerio.load(sourceHtml);
 30 |     var headers = $("h1, h2, h3, h4, h5, h6");
 31 | 
 32 |     var headerList = [];
 33 |     for (var i = 0; i < headers.length; i++) {
 34 |       var el = headers[i];
 35 |       headerList.push(new TocEntry(el.name, $(el).text(), $(el).attr("id")));
 36 |     }
 37 | 
 38 |     return headerList;
 39 |   }
 40 | 
 41 |   function getHeaderEntriesInBrowser(sourceHtml) {
 42 |     // Generate dummy element
 43 |     var source = document.createElement("div");
 44 |     source.innerHTML = sourceHtml;
 45 | 
 46 |     // Find headers
 47 |     var headers = source.querySelectorAll("h1, h2, h3, h4, h5, h6");
 48 |     var headerList = [];
 49 |     for (var i = 0; i < headers.length; i++) {
 50 |       var el = headers[i];
 51 |       headerList.push(new TocEntry(el.tagName, el.textContent, el.id));
 52 |     }
 53 | 
 54 |     return headerList;
 55 |   }
 56 | 
 57 |   function TocEntry(tagName, text, anchor) {
 58 |     this.tagName = tagName;
 59 |     this.text = text;
 60 |     this.anchor = anchor;
 61 |     this.children = [];
 62 |   }
 63 | 
 64 |   TocEntry.prototype.childrenToString = function() {
 65 |     if (this.children.length === 0) {
 66 |       return "";
 67 |     }
 68 |     var result = "<ul>\n";
 69 |     for (var i = 0; i < this.children.length; i++) {
 70 |       result += this.children[i].toString();
 71 |     }
 72 |     result += "</ul>\n";
 73 |     return result;
 74 |   };
 75 | 
 76 |   TocEntry.prototype.toString = function() {
 77 |     var result = "<li>";
 78 |     if (this.text) {
 79 |       result += '<a href="#' + this.anchor + '">' + this.text + "</a>";
 80 |     }
 81 |     result += this.childrenToString();
 82 |     result += "</li>\n";
 83 |     return result;
 84 |   };
 85 | 
 86 |   function sortHeader(tocEntries, level) {
 87 |     level = level || 1;
 88 |     var tagName = "H" + level,
 89 |       result = [],
 90 |       currentTocEntry;
 91 | 
 92 |     function push(tocEntry) {
 93 |       if (tocEntry !== undefined) {
 94 |         if (tocEntry.children.length > 0) {
 95 |           tocEntry.children = sortHeader(tocEntry.children, level + 1);
 96 |         }
 97 |         result.push(tocEntry);
 98 |       }
 99 |     }
100 | 
101 |     for (var i = 0; i < tocEntries.length; i++) {
102 |       var tocEntry = tocEntries[i];
103 |       if (tocEntry.tagName.toUpperCase() !== tagName) {
104 |         if (currentTocEntry === undefined) {
105 |           currentTocEntry = new TocEntry();
106 |         }
107 |         currentTocEntry.children.push(tocEntry);
108 |       } else {
109 |         push(currentTocEntry);
110 |         currentTocEntry = tocEntry;
111 |       }
112 |     }
113 | 
114 |     push(currentTocEntry);
115 |     return result;
116 |   }
117 | 
118 |   return {
119 |     type: "output",
120 |     filter: function(sourceHtml) {
121 |       var headerList = getHeaderEntries(sourceHtml);
122 | 
123 |       // No header found
124 |       if (headerList.length === 0) {
125 |         return sourceHtml;
126 |       }
127 | 
128 |       // Sort header
129 |       headerList = sortHeader(headerList);
130 | 
131 |       // Skip the title.
132 |       if (headerList.length == 1) {
133 |         headerList = headerList[0].children;
134 |       }
135 | 
136 |       // Build result and replace all [toc]
137 |       var result =
138 |         '<div class="toc">\n<ul>\n' + headerList.join("") + "</ul>\n</div>\n";
139 |       return sourceHtml.replace(/\[toc\]/gi, result);
140 |     }
141 |   };
142 | });
143 | 


--------------------------------------------------------------------------------
/docs/app_test.js:
--------------------------------------------------------------------------------
  1 | // Copyright 2018-2019 the Deno authors. All rights reserved. MIT license.
  2 | 
  3 | import { test, testPerm, assert, assertEquals } from "../js/test_util.ts";
  4 | import {
  5 |   createBinarySizeColumns,
  6 |   createExecTimeColumns,
  7 |   createThreadCountColumns,
  8 |   createSyscallCountColumns,
  9 |   createSha1List
 10 | } from "./app.js";
 11 | 
 12 | const regularData = [
 13 |   {
 14 |     created_at: "2018-01-01T01:00:00Z",
 15 |     sha1: "abcdef",
 16 |     binary_size: {
 17 |       deno: 100000000,
 18 |       "main.js": 90000000,
 19 |       "main.js.map": 80000000,
 20 |       "snapshot_deno.bin": 70000000
 21 |     },
 22 |     throughput: {
 23 |       "100M_tcp": 3.6,
 24 |       "100M_cat": 3.0,
 25 |       "10M_tcp": 1.6,
 26 |       "10M_cat": 1.0
 27 |     },
 28 |     req_per_sec: {
 29 |       node: 16000,
 30 |       deno: 1000
 31 |     },
 32 |     benchmark: {
 33 |       hello: {
 34 |         mean: 0.05
 35 |       },
 36 |       relative_import: {
 37 |         mean: 0.06
 38 |       },
 39 |       cold_hello: {
 40 |         mean: 0.05
 41 |       },
 42 |       cold_relative_import: {
 43 |         mean: 0.06
 44 |       }
 45 |     },
 46 |     thread_count: {
 47 |       set_timeout: 4,
 48 |       fetch_deps: 6
 49 |     },
 50 |     syscall_count: {
 51 |       hello: 600,
 52 |       fetch_deps: 700
 53 |     }
 54 |   },
 55 |   {
 56 |     created_at: "2018-01-02T01:00:00Z",
 57 |     sha1: "012345",
 58 |     binary_size: {
 59 |       deno: 100000001,
 60 |       "main.js": 90000001,
 61 |       "main.js.map": 80000001,
 62 |       "snapshot_deno.bin": 70000001
 63 |     },
 64 |     throughput: {
 65 |       "100M_tcp": 3.6,
 66 |       "100M_cat": 3.0,
 67 |       "10M_tcp": 1.6,
 68 |       "10M_cat": 1.0
 69 |     },
 70 |     req_per_sec: {
 71 |       node: 1600,
 72 |       deno: 3.0
 73 |     },
 74 |     benchmark: {
 75 |       hello: {
 76 |         mean: 0.055
 77 |       },
 78 |       relative_import: {
 79 |         mean: 0.065
 80 |       },
 81 |       cold_hello: {
 82 |         mean: 0.055
 83 |       },
 84 |       cold_relative_import: {
 85 |         mean: 0.065
 86 |       }
 87 |     },
 88 |     thread_count: {
 89 |       set_timeout: 5,
 90 |       fetch_deps: 7
 91 |     },
 92 |     syscall_count: {
 93 |       hello: 700,
 94 |       fetch_deps: 800
 95 |     }
 96 |   }
 97 | ];
 98 | 
 99 | const irregularData = [
100 |   {
101 |     created_at: "2018-01-01T01:00:00Z",
102 |     sha1: "123",
103 |     benchmark: {},
104 |     throughput: {},
105 |     binary_size: {},
106 |     thread_count: {},
107 |     syscall_count: {}
108 |   },
109 |   {
110 |     created_at: "2018-02-01T01:00:00Z",
111 |     sha1: "456",
112 |     benchmark: {
113 |       hello: {},
114 |       relative_import: {},
115 |       cold_hello: {},
116 |       cold_relative_import: {}
117 |     },
118 |     throughput: {
119 |       "100M_tcp": 3.0
120 |     },
121 |     binary_size: {
122 |       deno: 1
123 |     },
124 |     thread_count: {
125 |       set_timeout: 5,
126 |       fetch_deps: 7
127 |     },
128 |     syscall_count: {
129 |       hello: 700,
130 |       fetch_deps: 800
131 |     }
132 |   }
133 | ];
134 | 
135 | test(function createExecTimeColumnsRegularData() {
136 |   const columns = createExecTimeColumns(regularData);
137 |   assertEquals(columns, [
138 |     ["hello", 0.05, 0.055],
139 |     ["relative_import", 0.06, 0.065],
140 |     ["cold_hello", 0.05, 0.055],
141 |     ["cold_relative_import", 0.06, 0.065]
142 |   ]);
143 | });
144 | 
145 | test(function createExecTimeColumnsIrregularData() {
146 |   const columns = createExecTimeColumns(irregularData);
147 |   assertEquals(columns, [
148 |     ["hello", null, null],
149 |     ["relative_import", null, null],
150 |     ["cold_hello", null, null],
151 |     ["cold_relative_import", null, null]
152 |   ]);
153 | });
154 | 
155 | test(function createBinarySizeColumnsRegularData() {
156 |   const columns = createBinarySizeColumns(regularData);
157 |   assertEquals(columns, [
158 |     ["deno", 100000000, 100000001],
159 |     ["main.js", 90000000, 90000001],
160 |     ["main.js.map", 80000000, 80000001],
161 |     ["snapshot_deno.bin", 70000000, 70000001]
162 |   ]);
163 | });
164 | 
165 | test(function createBinarySizeColumnsIrregularData() {
166 |   const columns = createBinarySizeColumns(irregularData);
167 |   assertEquals(columns, [["deno", null, 1]]);
168 | });
169 | 
170 | test(function createThreadCountColumnsRegularData() {
171 |   const columns = createThreadCountColumns(regularData);
172 |   assertEquals(columns, [["set_timeout", 4, 5], ["fetch_deps", 6, 7]]);
173 | });
174 | 
175 | test(function createThreadCountColumnsIrregularData() {
176 |   const columns = createThreadCountColumns(irregularData);
177 |   assertEquals(columns, [["set_timeout", null, 5], ["fetch_deps", null, 7]]);
178 | });
179 | 
180 | test(function createSyscallCountColumnsRegularData() {
181 |   const columns = createSyscallCountColumns(regularData);
182 |   assertEquals(columns, [["hello", 600, 700], ["fetch_deps", 700, 800]]);
183 | });
184 | 
185 | test(function createSyscallCountColumnsIrregularData() {
186 |   const columns = createSyscallCountColumns(irregularData);
187 |   assertEquals(columns, [["hello", null, 700], ["fetch_deps", null, 800]]);
188 | });
189 | 
190 | test(function createSha1ListRegularData() {
191 |   const sha1List = createSha1List(regularData);
192 |   assertEquals(sha1List, ["abcdef", "012345"]);
193 | });
194 | 


--------------------------------------------------------------------------------
/docs/benchmarks.html:
--------------------------------------------------------------------------------
  1 | <!-- Copyright 2018-2019 the Deno authors. All rights reserved. MIT license. -->
  2 | <!DOCTYPE html>
  3 | <html>
  4 |   <head>
  5 |     <title>Deno Benchmarks</title>
  6 |     <link rel="shortcut icon" href="favicon.ico">
  7 |     <link rel="stylesheet" href="https://unpkg.com/c3@0.6.7/c3.min.css" />
  8 |     <link rel="stylesheet" href="style.css" />
  9 |     <meta content="width=device-width, initial-scale=1.0" name="viewport" />
 10 |   </head>
 11 |   <body>
 12 |     <main>
 13 |       <a href="/"><img src="images/deno_logo_3.svg" width=200></a>
 14 |       <h1>Deno Continuous Benchmarks</h1>
 15 | 
 16 |       <p>
 17 |         These plots are updated on every commit to
 18 |         <a href="https://github.com/denoland/deno">master branch</a>.
 19 |       </p>
 20 | 
 21 |       <p><a href="#recent">recent data</a></p>
 22 |       <p><a href="#all">all data</a> (takes a moment to load)</p>
 23 | 
 24 |       <h3 id="exec-time">Execution time <a href="#exec-time">#</a></h3>
 25 |       <p>
 26 |         This shows how much time total it takes to run a few simple deno
 27 |         programs:
 28 |         <a
 29 |           href="https://github.com/denoland/deno/blob/master/tests/002_hello.ts"
 30 |         >
 31 |           tests/002_hello.ts
 32 |         </a>,
 33 |         <a
 34 |           href="https://github.com/denoland/deno/blob/master/tests/003_relative_import.ts"
 35 |           >tests/003_relative_import.ts</a
 36 |         >,
 37 |         <a
 38 |           href="https://github.com/denoland/deno/blob/master/tests/worker_round_robin_bench.ts"
 39 |           >tests/worker_round_robin_bench.ts</a
 40 |         >, and
 41 |         <a
 42 |           href="https://github.com/denoland/deno/blob/master/tests/worker_startup_bench.ts"
 43 |           >tests/worker_startup_bench.ts</a
 44 |         >. For deno to execute typescript, it must first compile it to JS. A
 45 |         warm startup is when deno has a cached JS output already, so it should
 46 |         be fast because it bypasses the TS compiler. A cold startup is when deno
 47 |         must compile from scratch.
 48 |       </p>
 49 |       <div id="exec-time-chart"></div>
 50 | 
 51 |       <h3 id="throughput">Throughput <a href="#throughput">#</a></h3>
 52 | 
 53 |       <p>
 54 |         Time it takes to pipe a certain amount of data through Deno.
 55 | 
 56 |         <a
 57 |           href="https://github.com/denoland/deno/blob/master/tests/echo_server.ts"
 58 |         >
 59 |           echo_server.ts
 60 |         </a>
 61 |         and
 62 |         <a href="https://github.com/denoland/deno/blob/master/tests/cat.ts">
 63 |           cat.ts </a
 64 |         >. Smaller is better.
 65 |       </p>
 66 | 
 67 |       <div id="throughput-chart"></div>
 68 | 
 69 |       <h3 id="req-per-sec">Req/Sec <a href="#req-per-sec">#</a></h3>
 70 | 
 71 |       <p>
 72 |         Tests HTTP server performance. 10 keep-alive connections do as many
 73 |         hello-world requests as possible. Bigger is better.
 74 |       </p>
 75 | 
 76 |       <ul>
 77 |         <!-- TODO rename "deno" to "deno_tcp". -->
 78 |         <li>
 79 |           <a
 80 |             href="https://github.com/denoland/deno/blob/master/tests/http_bench.ts"
 81 |           >
 82 |             deno
 83 |           </a>
 84 |           is a fake http server that doesn't parse HTTP. It is comparable to
 85 |           <a
 86 |             href="https://github.com/denoland/deno/blob/master/tools/node_tcp.js"
 87 |           >
 88 |             node_tcp
 89 |           </a>
 90 |           .
 91 |         </li>
 92 | 
 93 |         <li>
 94 |           <a
 95 |             href="https://github.com/denoland/deno_std/blob/master/http/http_bench.ts"
 96 |           >
 97 |             deno_net_http
 98 |           </a>
 99 |           is a web server written in TypeScript. It is comparable to
100 |           <a
101 |             href="https://github.com/denoland/deno/blob/master/tools/node_http.js"
102 |           >
103 |             node_http
104 |           </a>
105 |           .
106 |         </li>
107 | 
108 |         <li>
109 |           <a
110 |             href="https://github.com/denoland/deno/blob/master/tools/hyper_hello.rs"
111 |           >
112 |             hyper
113 |           </a>
114 |           is a Rust HTTP server and represents an upper bound.
115 |         </li>
116 |       </ul>
117 | 
118 |       <div id="req-per-sec-chart"></div>
119 | 
120 |       <h3 id="max-latency">Max Latency <a href="#max-latency">#</a></h3>
121 | 
122 |       <p>
123 |         Max latency during the same test used above for requests/second. Smaller is better.
124 |       </p>
125 | 
126 |       <div id="max-latency-chart"></div>
127 | 
128 |       <h3 id="size">Executable size <a href="#size">#</a></h3>
129 |       <p>deno ships only a single binary. We track its size here.</p>
130 |       <div id="binary-size-chart"></div>
131 | 
132 |       <h3 id="threads">Thread count <a href="#threads">#</a></h3>
133 |       <p>How many threads various programs use.</p>
134 |       <div id="thread-count-chart"></div>
135 | 
136 |       <h3 id="syscalls">Syscall count <a href="#syscalls">#</a></h3>
137 |       <p>
138 |         How many total syscalls are performed when executing a given script.
139 |       </p>
140 |       <div id="syscall-count-chart"></div>
141 |     </main>
142 |     <script src="https://unpkg.com/d3@5.7.0/dist/d3.min.js"></script>
143 |     <script src="https://unpkg.com/c3@0.6.7/c3.min.js"></script>
144 | 
145 |     <script type="module">
146 |       import { drawCharts } from "./app.js";
147 |       window.chartWidth = 800;
148 | 
149 |       let u = window.location.hash.match("all") ? "./data.json" : "recent.json";
150 | 
151 |       drawCharts(u);
152 |     </script>
153 |   </body>
154 | </html>
155 | 


--------------------------------------------------------------------------------
/readme.md:
--------------------------------------------------------------------------------
  1 | # denoland/deno [![explain]][source] [![translate-svg]][translate-list]
  2 | 
  3 | <!-- [![size-img]][size] -->
  4 | 
  5 | [explain]: http://llever.com/explain.svg
  6 | [source]: https://github.com/chinanf-boy/Source-Explain
  7 | [translate-svg]: http://llever.com/translate.svg
  8 | [translate-list]: https://github.com/chinanf-boy/chinese-translate-list
  9 | [size-img]: https://packagephobia.now.sh/badge?p=Name
 10 | [size]: https://packagephobia.now.sh/result?p=Name
 11 | 
 12 | 「 JavaScript 和 TypeScript 安全运行时，使用 V8, Rust, 和 Tokio 构建。」
 13 | 
 14 | [中文](./readme.md) | [english](https://github.com/denoland/deno)
 15 | 
 16 | ---
 17 | 
 18 | ## 校对 ✅
 19 | 
 20 | <!-- doc-templite START generated -->
 21 | <!-- repo = 'denoland/deno' -->
 22 | <!-- commit = '3324afbd404a4237f0339e50a345a5f20c4ea7dd' -->
 23 | <!-- time = '2019-04-07' -->
 24 | 
 25 | | 翻译的原文 | 与日期        | 最新更新 | 更多                       |
 26 | | ---------- | ------------- | -------- | -------------------------- |
 27 | | [commit]   | ⏰ 2019-04-07 | ![last]  | [中文翻译][translate-list] |
 28 | 
 29 | [last]: https://img.shields.io/github/last-commit/denoland/deno.svg
 30 | [commit]: https://github.com/denoland/deno/tree/3324afbd404a4237f0339e50a345a5f20c4ea7dd
 31 | 
 32 | <!-- doc-templite END generated -->
 33 | 
 34 | 原文：denoland/deno/website
 35 | 
 36 | - [x] readme
 37 | - [x] [手册](./manual.zh.md)
 38 | - [x] [风格指南](./style_guide.zh.md)
 39 | 
 40 | ### 贡献
 41 | 
 42 | 欢迎 👏 勘误/校对/更新贡献 😊 [具体贡献请看](https://github.com/chinanf-boy/chinese-translate-list#贡献)
 43 | 
 44 | ## 生活
 45 | 
 46 | [help me live , live need money 💰](https://github.com/chinanf-boy/live-need-money)
 47 | 
 48 | ---
 49 | 
 50 | <img id="logo" src="docs/images/deno_logo_3.svg" width="500" />
 51 | 
 52 | 
 53 | # Deno
 54 | 
 55 | JavaScript 和 TypeScript 安全运行时，使用 V8, Rust, 和 Tokio 构建。
 56 | 
 57 | <table>
 58 |         <tr>
 59 |           <th></th>
 60 |           <th>Linux &amp; Mac</th>
 61 |           <th>Windows</th>
 62 |         </tr>
 63 |         <tr>
 64 |           <th><a href="https://github.com/denoland/deno">deno</a></th>
 65 |           <td>
 66 |             <a class="badge" href="https://travis-ci.com/denoland/deno">
 67 |               <img
 68 |                 src="https://travis-ci.com/denoland/deno.svg?branch=master"
 69 |               />
 70 |             </a>
 71 |           </td>
 72 |           <td>
 73 |             <a class="badge" href="https://ci.appveyor.com/project/deno/deno">
 74 |               <img
 75 |                 src="https://ci.appveyor.com/api/projects/status/yel7wtcqwoy0to8x/branch/master?svg=true"
 76 |               />
 77 |             </a>
 78 |           </td>
 79 |         </tr>
 80 |         <tr>
 81 |           <th><a href="https://github.com/denoland/deno_std">deno_std</a></th>
 82 |           <td colspan="2">
 83 |             <a
 84 |               class="badge"
 85 |               href="https://dev.azure.com/denoland/deno_std/_build?definitionId=2"
 86 |             >
 87 |               <img
 88 |                 src="https://dev.azure.com/denoland/deno_std/_apis/build/status/denoland.deno_std?branchName=master"
 89 |               />
 90 |             </a>
 91 |           </td>
 92 |         </tr>
 93 |         <tr>
 94 |           <th>
 95 |             <a href="https://github.com/denoland/deno_install">deno_install</a>
 96 |           </th>
 97 |           <td>
 98 |             <a class="badge" href="https://travis-ci.com/denoland/deno_install">
 99 |               <img
100 |                 src="https://travis-ci.com/denoland/deno_install.svg?branch=master"
101 |               />
102 |             </a>
103 |           </td>
104 |           <td>
105 |             <a
106 |               class="badge"
107 |               href="https://ci.appveyor.com/project/deno/deno-install"
108 |             >
109 |               <img
110 |                 src="https://ci.appveyor.com/api/projects/status/gtekeaf7r60xa896?branch=master&svg=true"
111 |               />
112 |             </a>
113 |           </td>
114 |         </tr>
115 |         <tr>
116 |           <th><a href="https://github.com/denoland/registry">registry</a></th>
117 |           <td colspan=2>
118 |             <a class="badge" href="https://travis-ci.com/denoland/registry">
119 |               <img
120 |                 src="https://travis-ci.com/denoland/registry.svg?branch=master"
121 |               />
122 |             </a>
123 |           </td>
124 |         </tr>
125 |       </table>
126 | 
127 | ## 安装
128 | 
129 | 使用 Shell:
130 | 
131 | ```bash
132 | curl -fsSL https://github.com/denoland/deno_install/blob/master/install.sh | sh
133 | ```
134 | 
135 | Or 使用 PowerShell:
136 | 
137 | ```
138 | iwr https://github.com/denoland/deno_install/blob/master/install.ps1 | iex
139 | ```
140 | 
141 | 查看 [deno_install](https://github.com/denoland/deno_install) ，了解更多
142 | 
143 | ## 例子
144 | 
145 | 尝试运行一个简单程序:
146 | 
147 | ```bash
148 | deno https://deno.land/welcome.ts
149 | ```
150 | 
151 | 或更为复杂点的:
152 | 
153 | ```typescript
154 | import {serve} from 'https://deno.land/std@v0.3.2/http/server.ts';
155 | 
156 | async function main() {
157 |   const body = new TextEncoder().encode('Hello World\n');
158 |   for await (const req of serve(':8000')) {
159 |     req.respond({body});
160 |   }
161 | }
162 | 
163 | main();
164 | ```
165 | 
166 | ## 深挖...
167 | 
168 | **[手册](http://llever.com/deno-website-zh/manual.html)**
169 | 
170 | [API 参考](https://deno.land/typedoc/)
171 | 
172 | [风格指南](http://llever.com/deno-website-zh/style_guide.html)
173 | 
174 | [模块 存储库](https://deno.land/x/)
175 | 
176 | [Twitter](https://twitter.com/deno_land)
177 | 
178 | [发布记录](https://github.com/denoland/deno/blob/master/Releases.md)
179 | 
180 | [社区聊天室](https://gitter.im/denolife/Lobby)
181 | 
182 | [基准](https://deno.land/benchmarks.html)
183 | 
184 | [awesome Deno](https://github.com/denolib/awesome-deno)
185 | 


--------------------------------------------------------------------------------
/docs/style_guide.zh.md:
--------------------------------------------------------------------------------
  1 | # Deno 风格指南
  2 | 
  3 | ## 使用 TypeScript
  4 | 
  5 | ## 使用术语"模块(module)"，而不是"库(library)"或"包(package)"
  6 | 
  7 | 为了明确性和一致性，请避免使用术语"库"和"包"。而是使用"module"来指明单个 JS 或 TS 文件，当然还包括 TS / JS 代码的目录。
  8 | 
  9 | ## 不要使用文件名`"index.ts"或"index.js"`
 10 | 
 11 | Deno 不会对"index.js"或"index.ts"特殊处理。这些文件名的使用，会对当不用它们时，却可以被排除在模块描述之外，感到困惑。
 12 | 
 13 | 如果代码目录需要默认入口点，请使用文件名`mod.ts`。文件名`mod.ts`遵循 Rust 的惯例，比`index.ts`简短，并且没有任何先入为主，关于其应该如何运作的观念。
 14 | 
 15 | ## 在"deno-std"中，不依赖外部代码
 16 | 
 17 | `deno_std`旨在成为所有 Deno 程序可以依赖的地基功能。我们希望向用户保证此代码，不包含可能未经审核的第三方代码。
 18 | 
 19 | ## 在"deno-std"中，最小化依赖关系；不要进行循环导入。
 20 | 
 21 | 虽然`deno_std`是一个独立的代码库，我们仍然必须小心保持，内部依赖关系的简单和易于管理。特别要注意，不要产生(死)循环导入。
 22 | 
 23 | ## 为了保持一致性，文件名请使用下划线，而不是短划线。
 24 | 
 25 | 示例：不是`file-server.ts`，使用`file_server.ts`。
 26 | 
 27 | ## 使用 prettier 格式化代码。
 28 | 
 29 | 更具体地说，代码行应在 80 列内，使用 2 空格缩进，并使用驼峰式。使用`//format.ts`调用 prettier。
 30 | 
 31 | ## 导出的函数：最多 2 个参数，将其余的参数放入 options 对象。
 32 | 
 33 | 设计函数接口时，请遵守以下规则。
 34 | 
 35 | 1.  作为公有 API 一部分的函数需要 0-2 个必需参数，如果需要的话，加上一个选项(options)对象（总共最多 3 个）。
 36 | 
 37 | 2.  可选参数，通常应该放进 options 对象。
 38 | 
 39 |     如果只有一个参数，且我们将来不太可能添加更多可选参数，那么不在选项对象中的可选参数，是能够接受的。
 40 | 
 41 | 3.  'options'参数是唯一的常规'Object'类型。
 42 | 
 43 |     其他参数可以是对象(/容器类型)，但它们必须与"普通"对象(`Object`)运行时，区分开来，方法是：
 44 | 
 45 |     - 一个有区别的原型（例如`Array`，`Map`，`Date`，`class MyThing`）
 46 |     - 一个众所周知的符号属性（例如，一个可迭代的`Symbol.iterator`）。
 47 | 
 48 |     这允许 API 以向后兼容的方式扩展，即使选项对象的位置，发生变化也能行。
 49 | 
 50 | ```ts
 51 | // 不好的方式: 可选参数，不是options 对象的一部分。 (#2)
 52 | export function resolve(
 53 |   hostname: string,
 54 |   family?: 'ipv4' | 'ipv6',
 55 |   timeout?: number
 56 | ): IPAddress[] {}
 57 | 
 58 | // 好的方式.
 59 | export interface ResolveOptions {
 60 |   family?: 'ipv4' | 'ipv6';
 61 |   timeout?: number;
 62 | }
 63 | export function resolve(
 64 |   hostname: string,
 65 |   options: ResolveOptions = {}
 66 | ): IPAddress[] {}
 67 | ```
 68 | 
 69 | ```ts
 70 | export interface Environment {
 71 |   [key: string]: string;
 72 | }
 73 | 
 74 | // 不好的方式: `env` 可能是常规对象，因此无法区分是否为一个选项对象. (#3)
 75 | export function runShellWithEnv(cmdline: string, env: Environment): string {}
 76 | 
 77 | // 好的方式.
 78 | export interface RunShellOptions {
 79 |   env: Environment;
 80 | }
 81 | export function runShellWithEnv(
 82 |   cmdline: string,
 83 |   options: RunShellOptions
 84 | ): string {}
 85 | ```
 86 | 
 87 | ```ts
 88 | // 不好的方式: 超过 3 参数 (#1), 过多可选参数 (#2).
 89 | export function renameSync(
 90 |   oldname: string,
 91 |   newname: string,
 92 |   replaceExisting?: boolean,
 93 |   followLinks?: boolean
 94 | ) {}
 95 | 
 96 | // 好的方式.
 97 | interface RenameOptions {
 98 |   replaceExisting?: boolean;
 99 |   followLinks?: boolean;
100 | }
101 | export function renameSync(
102 |   oldname: string,
103 |   newname: string,
104 |   options: RenameOptions = {}
105 | ) {}
106 | ```
107 | 
108 | ```ts
109 | // 不好的方式: 过多参数. (#1)
110 | export function pwrite(
111 |   fd: number,
112 |   buffer: TypedArray,
113 |   offset: number,
114 |   length: number,
115 |   position: number
116 | ) {}
117 | 
118 | // 更好.
119 | export interface PWrite {
120 |   fd: number;
121 |   buffer: TypedArray;
122 |   offset: number;
123 |   length: number;
124 |   position: number;
125 | }
126 | export function pwrite(options: PWrite) {}
127 | ```
128 | 
129 | ## TODO 注释(待续讨论)
130 | 
131 | TODO 注释应该在括号中，包含问题或作者的 github 用户名。例：
132 | 
133 | ```ts
134 | // TODO(ry) Add tests.
135 | // TODO(#123) Support Windows.
136 | ```
137 | 
138 | ## 版权标题
139 | 
140 | `deno_std`大多数文件，应具有以下版权标题：
141 | 
142 | ```ts
143 | // Copyright 2018-2019 the Deno authors. All rights reserved. MIT license.
144 | ```
145 | 
146 | 如果代码来自其他地方，请确保该文件，具有适当的版权标题。我们`deno_std`只允许使用 MIT，BSD 和 Apache 许可代码。
147 | 
148 | ## 顶级函数，不应使用箭头语法
149 | 
150 | 顶级函数应该使用`function`关键词。箭头语法，应仅限闭包使用。
151 | 
152 | 坏
153 | 
154 | ```ts
155 | export const foo(): string => {
156 |   return "bar";
157 | }
158 | ```
159 | 
160 | 好
161 | 
162 | ```ts
163 | export function foo(): string {
164 |   return 'bar';
165 | }
166 | ```
167 | 
168 | ## 不鼓励，使用元编程。包括代理的用法。
169 | 
170 | 即使它意味着更多的代码，也要代码具备明确性。
171 | 
172 | 在某些情况下，使用这些技术，可能是有意义的，但在绝大多数情况下，没有。
173 | 
174 | ## 如果文件名，以下划线开头，请不要链接到它："\_foo.ts"`
175 | 
176 | 有时可能存在内部模块的需要，但其 API 不是稳定或可供链接的情况。在这种情况下，用下划线作为前缀。按照惯例，只有本文件目录中的(文件)，才能导入它。
177 | 
178 | ## 使用 jsdoc 文档化，导出 API 的情况
179 | 
180 | 我们力求完整的文档。理想情况下，每个导出的符号，都应该有文档行。
181 | 
182 | 如果可能，请编写 JS 文档。例：
183 | 
184 | ```ts
185 | /** foo 做了某 bar. */
186 | export function foo() {
187 |   // ...
188 | }
189 | ```
190 | 
191 | 重要的是文档，易于给人阅读，但还需要提供额外的样式信息，以确保生成的文档是，更丰富的文本。因此，JSDoc 通常遵循 markdown 标记，来丰富文本。
192 | 
193 | 虽然 markdown 支持 HTML 标签，但在 JSDoc 区块中，禁止使用。
194 | 
195 | 代码格式字符串，应使用反引号（\`)标记而不是引号。例如：
196 | 
197 | ```ts
198 | /** Import something from the `deno` module. */
199 | ```
200 | 
201 | 不要文档化函数参数，除非它们的意图不明显（尽管它们，具有不明显意图，但 API 无论如何都应该考虑清楚）。因此`@param`通常，不应该使用。如果`@param`真使用了，那它不应该包括`type`，因为 TypeScript 已经是强类型的。
202 | 
203 | ```ts
204 | /**
205 |  * 带有不明显意图参数的函数
206 |  * @param foo 描述不明显意图的参数
207 |  */
208 | ```
209 | 
210 | 应尽可能减小垂直间距。因此，单行注释应写为：
211 | 
212 | ```ts
213 | /** JSDoc 单行标准写法 */
214 | ```
215 | 
216 | 而不是
217 | 
218 | ```ts
219 | /**
220 |  * JSDoc 差的示例
221 |  */
222 | ```
223 | 
224 | 代码示例(区块)，不应使用三个反引号（\`\`\`）表示。它们应该只用缩进：具体需要在区块之前空一行，并为示例的每一行，添加 6 个额外的空格。这比注释的第一列，多 4 个。例如：
225 | 
226 | ```ts
227 | /** A straight forward comment and an example:
228 |  *
229 |  *       import { foo } from "deno";
230 |  *       foo("bar");
231 |  */
232 | ```
233 | 
234 | 代码示例，不应包含其他注释。它已经在外注释中。如果它需要进一步的注释，那就不是一个很好的例子。
235 | 
236 | ## 每个模块都应该有测试
237 | 
238 | 每个模块应该有个测试文件`modulename_test.ts`，作为它的兄弟姐妹。例如模块`foo.ts`应该带着它的兄弟姐妹`foo_test.ts`。
239 | 
240 | ## 单元测试应该是明确的
241 | 
242 | 为了更好地理解测试，应在整个测试命令中，正确命名函数，比如：
243 | 
244 | ```
245 | test myTestFunction ... ok
246 | ```
247 | 
248 | 测试示例：
249 | 
250 | ```ts
251 | import {assertEquals} from 'https://deno.land/std@v0.3.1/testing/asserts.ts';
252 | import {test} from 'https://deno.land/std@v0.3.1/testing/mod.ts';
253 | import {foo} from './mod.ts';
254 | 
255 | test(function myTestFunction() {
256 |   assertEquals(foo(), {bar: 'bar'});
257 | });
258 | ```
259 | 


--------------------------------------------------------------------------------
/docs/index.html:
--------------------------------------------------------------------------------
  1 | <!-- Copyright 2018-2019 the Deno authors. All rights reserved. MIT license. -->
  2 | <!DOCTYPE html>
  3 | <html>
  4 |   <head>
  5 |     <title>Deno</title>
  6 |     <link rel="shortcut icon" href="favicon.ico" />
  7 |     <link
  8 |       href="https://cdn.bootcss.com/highlight.js/9.15.6/styles/default.min.css"
  9 |       rel="stylesheet"
 10 |     />
 11 |     <link
 12 |       rel="stylesheet"
 13 |       href="https://cdn.bootcss.com/highlight.js/9.15.6/styles/github-gist.min.css"
 14 |     />
 15 |     <script src="https://cdn.bootcss.com/highlight.js/9.15.6/highlight.min.js"></script>
 16 |     <script src="https://cdn.bootcss.com/highlight.js/9.15.6/languages/typescript.min.js"></script>
 17 |     <link rel="stylesheet" href="style.css" />
 18 |     <meta content="width=device-width, initial-scale=1.0" name="viewport" />
 19 |   </head>
 20 |   <body>
 21 |     <main>
 22 |       <header>
 23 |         <img id="logo" src="images/deno_logo_3.svg" width="200" />
 24 |         <div>
 25 |           <h1>Deno</h1>
 26 |           JavaScript 和 TypeScript 安全运行时，使用 V8, Rust, 和 Tokio 构建。
 27 |         </div>
 28 |       </header>
 29 | 
 30 |       <table>
 31 |         <tr>
 32 |           <th></th>
 33 |           <th>Linux &amp; Mac</th>
 34 |           <th>Windows</th>
 35 |         </tr>
 36 |         <tr>
 37 |           <th><a href="https://github.com/denoland/deno">deno</a></th>
 38 |           <td>
 39 |             <a class="badge" href="https://travis-ci.com/denoland/deno">
 40 |               <img
 41 |                 src="https://travis-ci.com/denoland/deno.svg?branch=master"
 42 |               />
 43 |             </a>
 44 |           </td>
 45 |           <td>
 46 |             <a class="badge" href="https://ci.appveyor.com/project/deno/deno">
 47 |               <img
 48 |                 src="https://ci.appveyor.com/api/projects/status/yel7wtcqwoy0to8x/branch/master?svg=true"
 49 |               />
 50 |             </a>
 51 |           </td>
 52 |         </tr>
 53 |         <tr>
 54 |           <th><a href="https://github.com/denoland/deno_std">deno_std</a></th>
 55 |           <td colspan="2">
 56 |             <a
 57 |               class="badge"
 58 |               href="https://dev.azure.com/denoland/deno_std/_build?definitionId=2"
 59 |             >
 60 |               <img
 61 |                 src="https://dev.azure.com/denoland/deno_std/_apis/build/status/denoland.deno_std?branchName=master"
 62 |               />
 63 |             </a>
 64 |           </td>
 65 |         </tr>
 66 |         <tr>
 67 |           <th>
 68 |             <a href="https://github.com/denoland/deno_install">deno_install</a>
 69 |           </th>
 70 |           <td>
 71 |             <a class="badge" href="https://travis-ci.com/denoland/deno_install">
 72 |               <img
 73 |                 src="https://travis-ci.com/denoland/deno_install.svg?branch=master"
 74 |               />
 75 |             </a>
 76 |           </td>
 77 |           <td>
 78 |             <a
 79 |               class="badge"
 80 |               href="https://ci.appveyor.com/project/deno/deno-install"
 81 |             >
 82 |               <img
 83 |                 src="https://ci.appveyor.com/api/projects/status/gtekeaf7r60xa896?branch=master&svg=true"
 84 |               />
 85 |             </a>
 86 |           </td>
 87 |         </tr>
 88 |         <tr>
 89 |           <th><a href="https://github.com/denoland/registry">registry</a></th>
 90 |           <td colspan="2">
 91 |             <a class="badge" href="https://travis-ci.com/denoland/registry">
 92 |               <img
 93 |                 src="https://travis-ci.com/denoland/registry.svg?branch=master"
 94 |               />
 95 |             </a>
 96 |           </td>
 97 |         </tr>
 98 |       </table>
 99 | 
100 |       <h2 id="install">安装 <a href="#install">#</a></h2>
101 | 
102 |       <p>使用 Shell:</p>
103 |       <pre>curl -fsSL <a
104 | href="https://github.com/denoland/deno_install/blob/master/install.sh">https://deno.land/x/install/install.sh</a> | sh</pre>
105 |       <p>Or 使用 PowerShell:</p>
106 |       <pre>iwr <a
107 | href="https://github.com/denoland/deno_install/blob/master/install.ps1">https://deno.land/x/install/install.ps1</a> | iex</pre>
108 |       <p>
109 |         查看
110 |         <a href="https://github.com/denoland/deno_install">deno_install</a>
111 |         ，了解更多。
112 |       </p>
113 | 
114 |       <h2 id="example">例子 <a href="#example">#</a></h2>
115 | 
116 |       <p>尝试运行一个简单程序:</p>
117 |       <pre>deno https://deno.land/welcome.ts</pre>
118 | 
119 |       <p>或更为复杂点的:</p>
120 | 
121 |       <pre><code class="typescript language-typescript">import {serve} from 'https://deno.land/std@v0.3.2/http/server.ts';
122 | 
123 | async function main() {
124 |   const body = new TextEncoder().encode('Hello World\n');
125 |   for await (const req of serve(':8000')) {
126 |     req.respond({body});
127 |   }
128 | }
129 | 
130 | main();</code></pre>
131 | 
132 |       <h2 id="dig-in">深挖... <a href="#dig-in">#</a></h2>
133 | 
134 |       <p>
135 |         <b><a href="manual.html">手册</a></b>
136 |       </p>
137 | 
138 |       <p><a href="https://deno.land/typedoc/">API 参考</a></p>
139 | 
140 |       <p><a href="style_guide.html">风格指南</a></p>
141 | 
142 |       <p><a href="https://deno.land/x/">模块 存储库</a></p>
143 | 
144 |       <p><a href="https://twitter.com/deno_land">Twitter</a></p>
145 | 
146 |       <p>
147 |         <a href="https://github.com/denoland/deno/blob/master/Releases.md"
148 |           >发布记录</a
149 |         >
150 |       </p>
151 | 
152 |       <p><a href="https://gitter.im/denolife/Lobby">社区聊天室</a></p>
153 | 
154 |       <p>
155 |         <a href="http://llever.com/deno-website-zh/benchmarks.html">基准</a>
156 |       </p>
157 | 
158 |       <p>
159 |         <a href="https://github.com/denolib/awesome-deno">awesome Deno</a>
160 |       </p>
161 | 
162 |       <script>
163 |         // Disable automatic language detection
164 |         hljs.configure({
165 |           languages: []
166 |         });
167 | 
168 |         hljs.initHighlighting();
169 |       </script>
170 |     </main>
171 |   </body>
172 | </html>
173 | 


--------------------------------------------------------------------------------
/docs/images/deno_logo_3.svg:
--------------------------------------------------------------------------------
 1 | <?xml version="1.0" standalone="no"?>
 2 | <!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 20010904//EN"
 3 |  "http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd">
 4 | <svg version="1.0" xmlns="http://www.w3.org/2000/svg"
 5 |  width="1024.000000pt" height="1024.000000pt" viewBox="0 0 1024.000000 1024.000000"
 6 |  preserveAspectRatio="xMidYMid meet">
 7 | <metadata>
 8 | Created by potrace 1.15, written by Peter Selinger 2001-2017
 9 | </metadata>
10 | <g transform="translate(0.000000,1024.000000) scale(0.100000,-0.100000)"
11 | fill="#000000" stroke="none">
12 | <path d="M4720 9174 c-19 -2 -80 -9 -135 -14 -782 -82 -1552 -413 -2180 -939
13 | -116 -96 -380 -360 -476 -476 -520 -621 -824 -1318 -936 -2143 -25 -183 -25
14 | -801 0 -984 112 -825 416 -1522 936 -2143 96 -116 360 -380 476 -476 621 -520
15 | 1318 -824 2143 -936 183 -25 801 -25 984 0 825 112 1522 416 2143 936 116 96
16 | 380 360 476 476 520 621 824 1318 936 2143 25 183 25 801 0 984 -112 825 -416
17 | 1522 -936 2143 -96 116 -360 380 -476 476 -619 518 -1323 826 -2137 935 -88
18 | 12 -216 17 -453 19 -181 2 -346 1 -365 -1z m50 -432 c0 -117 8 -371 19 -612 6
19 | -118 13 -287 16 -375 11 -312 44 -1131 49 -1204 l5 -73 -45 5 c-25 2 -48 8
20 | -52 11 -3 4 -10 73 -14 154 -18 356 -77 1737 -83 1939 l-6 222 28 4 c15 2 40
21 | 5 56 6 l27 1 0 -78z m957 24 c1 -1 4 -303 7 -671 4 -369 9 -700 12 -736 3 -37
22 | 2 -69 -3 -71 -4 -3 -29 -3 -54 0 l-46 4 -7 291 c-4 161 -9 339 -11 397 -8 177
23 | -15 778 -9 793 4 11 15 12 57 5 29 -6 53 -11 54 -12z m-2313 -335 c6 -9 53
24 | -560 111 -1281 19 -245 38 -469 41 -497 5 -51 4 -53 -28 -73 -18 -11 -36 -20
25 | -40 -20 -3 0 -9 26 -12 58 -14 130 -68 758 -106 1212 -22 267 -42 506 -45 532
26 | -5 44 -4 48 22 62 32 17 50 20 57 7z m2753 -201 c28 -10 31 -15 37 -72 10
27 | -100 7 -578 -4 -578 -29 0 -89 34 -94 53 -3 12 -6 154 -6 315 0 325 -4 306 67
28 | 282z m-1847 -47 c0 -27 7 -176 15 -333 8 -157 17 -356 21 -442 7 -174 9 -168
29 | -58 -172 -33 -1 -33 -1 -35 49 -2 28 -7 115 -13 195 -5 80 -17 253 -25 385 -8
30 | 132 -18 263 -21 291 -6 50 -5 52 22 62 16 6 44 11 62 11 32 1 32 1 32 -46z
31 | m2774 -137 l34 -14 7 -134 c3 -73 5 -231 3 -350 l-3 -218 -42 21 -42 20 -3
32 | 332 c-2 183 -1 338 1 345 4 15 4 15 45 -2z m-1826 -131 c6 -6 20 -491 21 -737
33 | l1 -148 -47 7 c-27 3 -49 6 -50 7 -3 2 -33 743 -33 815 l0 74 51 -6 c29 -4 54
34 | -9 57 -12z m2303 -71 c12 -14 14 -233 17 -1441 3 -1387 3 -1423 -15 -1423 -11
35 | 0 -26 6 -35 13 -15 11 -17 132 -22 1317 -4 718 -9 1370 -12 1449 l-6 144 29
36 | -21 c17 -12 36 -29 44 -38z m-897 -205 c5 -4 10 -61 11 -126 5 -221 6 -1576 1
37 | -1580 -2 -2 -20 3 -40 11 l-36 15 0 851 0 850 28 -6 c15 -4 31 -10 36 -15z
38 | m-2760 -56 c3 -27 8 -88 11 -138 3 -49 10 -161 16 -248 12 -176 10 -187 -47
39 | -187 -30 0 -34 3 -38 33 -10 59 -45 551 -40 559 5 7 57 25 81 27 6 1 14 -20
40 | 17 -46z m-1654 -255 c11 -106 33 -328 49 -493 17 -165 31 -305 31 -311 0 -12
41 | -77 -50 -85 -42 -5 5 -105 890 -105 930 0 24 77 125 87 114 3 -2 13 -91 23
42 | -198z m3921 -105 l29 -17 1 -216 c1 -118 3 -250 3 -293 2 -90 -9 -105 -63 -86
43 | l-31 11 0 86 c0 48 -3 187 -7 310 l-6 222 23 0 c12 0 35 -8 51 -17z m-3482
44 | -388 c18 -192 47 -516 66 -720 l34 -370 -39 -39 -38 -39 -7 79 c-4 44 -24 248
45 | -45 454 -21 206 -51 505 -66 664 l-28 288 39 36 c35 33 39 34 46 16 4 -10 21
46 | -176 38 -369z m-749 -121 c22 -197 80 -721 130 -1164 50 -443 97 -870 106
47 | -950 8 -80 22 -201 30 -270 14 -117 14 -125 -2 -137 -24 -18 -34 -16 -34 5 0
48 | 9 -9 85 -20 167 -18 137 -48 369 -115 890 -14 105 -41 314 -60 465 -20 151
49 | -49 376 -65 500 -16 124 -43 336 -60 473 -18 136 -29 257 -26 270 7 27 66 121
50 | 72 115 2 -3 22 -166 44 -364z m-306 -431 c15 -120 43 -339 62 -488 19 -148 43
51 | -333 54 -410 l19 -140 -21 -18 c-12 -10 -24 -14 -28 -10 -4 4 -12 44 -18 88
52 | -6 44 -43 301 -83 570 l-71 490 23 68 c12 37 25 67 28 67 4 0 19 -98 35 -217z
53 | m5490 131 c14 -14 16 -76 16 -535 l0 -519 -28 0 c-61 0 -60 -15 -64 553 l-3
54 | 517 32 0 c17 0 39 -7 47 -16z m-2189 -179 c226 -34 423 -97 618 -197 126 -65
55 | 186 -110 326 -244 208 -199 336 -373 456 -619 175 -358 243 -675 329 -1525 39
56 | -381 90 -1072 101 -1355 3 -82 10 -217 16 -300 11 -176 24 -152 -131 -227
57 | -215 -104 -422 -176 -695 -243 -334 -82 -550 -108 -880 -109 l-240 -1 2 115
58 | c0 63 6 210 12 325 30 557 24 1260 -15 1650 -22 224 -65 496 -89 556 -5 13 18
59 | 24 117 58 181 63 338 142 362 181 43 74 -34 180 -132 180 -17 0 -68 -18 -115
60 | -39 -224 -103 -673 -224 -932 -251 -179 -19 -457 -8 -650 27 -105 19 -293 90
61 | -450 171 -181 94 -292 219 -325 367 -18 80 -13 240 10 330 25 99 95 243 159
62 | 327 285 375 873 700 1476 814 192 36 464 40 670 9z m3085 -31 c36 -15 40 -19
63 | 40 -53 2 -273 -4 -897 -9 -923 -1 -9 -53 -10 -75 -2 -14 5 -16 59 -16 500 0
64 | 316 4 494 10 494 5 0 28 -7 50 -16z m437 -549 l36 -15 -7 -828 c-8 -1055 -9
65 | -1086 -47 -1177 -62 -149 -59 -179 -53 475 2 327 7 658 9 735 2 77 4 294 5
66 | 483 0 228 3 342 10 342 6 0 27 -7 47 -15z m-6014 -249 c6 -81 4 -89 -25 -153
67 | l-32 -68 -12 100 c-19 160 -19 167 19 191 17 12 35 20 38 18 3 -2 9 -42 12
68 | -88z m-618 -603 c9 -82 79 -626 115 -893 54 -413 58 -472 34 -447 -3 3 -26
69 | 142 -50 309 -156 1078 -155 1071 -142 1079 27 18 36 8 43 -48z m720 -458 c6
70 | -25 35 -296 35 -329 0 -28 -36 -54 -52 -38 -5 5 -18 90 -28 188 -11 99 -22
71 | 202 -25 229 l-6 50 35 -40 c20 -22 38 -49 41 -60z m807 -377 c11 -10 18 -50
72 | 27 -158 15 -195 17 -180 -24 -180 -42 0 -41 -3 -55 173 -14 179 -14 177 13
73 | 177 13 0 30 -6 39 -12z m792 -15 c2 -10 7 -70 11 -133 3 -63 12 -205 20 -315
74 | 28 -404 29 -455 12 -455 -19 0 -21 15 -43 300 -8 118 -23 304 -33 413 -9 109
75 | -15 200 -12 202 11 12 40 3 45 -12z m-1880 -192 c6 -9 44 -329 91 -766 14
76 | -132 28 -259 31 -283 l5 -43 -25 16 c-19 13 -26 26 -26 49 0 63 -43 478 -76
77 | 732 -19 144 -34 271 -34 283 0 21 24 29 34 12z m5771 -418 l-7 -418 -25 -37
78 | c-57 -84 -54 -100 -51 368 l2 429 37 38 c20 20 40 37 44 37 3 0 3 -188 0 -417z
79 | m-925 -663 c5 -581 4 -626 -12 -644 -10 -11 -19 -18 -22 -15 -7 8 -17 1275 -9
80 | 1282 4 4 14 6 23 5 13 -3 16 -74 20 -628z m-3266 398 c7 -62 32 -359 42 -499
81 | 6 -94 6 -97 -16 -104 -12 -4 -26 -3 -30 2 -7 7 -29 229 -56 571 l-7 82 31 0
82 | c29 0 31 -2 36 -52z m-786 -350 c7 -7 12 -32 12 -57 0 -26 12 -161 25 -301 38
83 | -383 41 -435 24 -425 -26 15 -49 38 -44 44 2 4 -2 54 -10 111 -7 58 -16 152
84 | -20 210 -4 58 -13 164 -21 235 -19 175 -18 195 4 195 10 0 23 -5 30 -12z m473
85 | -673 c3 -22 9 -104 13 -182 7 -150 4 -161 -37 -130 -12 9 -20 47 -32 161 -21
86 | 206 -22 198 17 194 29 -3 33 -7 39 -43z"/>
87 | <path d="M3184 5756 c-104 -45 -112 -186 -14 -236 71 -36 143 -19 180 43 70
88 | 114 -44 246 -166 193z"/>
89 | <path d="M3862 5660 c-96 -59 -96 -201 0 -260 95 -57 218 18 218 132 0 110
90 | -126 184 -218 128z"/>
91 | </g>
92 | </svg>
93 | 


--------------------------------------------------------------------------------
/docs/app.js:
--------------------------------------------------------------------------------
  1 | // Copyright 2018-2019 the Deno authors. All rights reserved. MIT license.
  2 | 
  3 | // How much to multiply time values in order to process log graphs properly.
  4 | const TimeScaleFactor = 10000;
  5 | 
  6 | export async function getJson(path) {
  7 |   return (await fetch(path)).json();
  8 | }
  9 | 
 10 | function getBenchmarkVarieties(data, benchmarkName) {
 11 |   // Look at last sha hash.
 12 |   const last = data[data.length - 1];
 13 |   return Object.keys(last[benchmarkName]);
 14 | }
 15 | 
 16 | export function createColumns(data, benchmarkName) {
 17 |   const varieties = getBenchmarkVarieties(data, benchmarkName);
 18 |   return varieties.map(variety => [
 19 |     variety,
 20 |     ...data.map(d => {
 21 |       if (d[benchmarkName] != null) {
 22 |         if (d[benchmarkName][variety] != null) {
 23 |           const v = d[benchmarkName][variety];
 24 |           if (benchmarkName == "benchmark") {
 25 |             const meanValue = v ? v.mean : 0;
 26 |             return meanValue || null;
 27 |           } else {
 28 |             return v;
 29 |           }
 30 |         }
 31 |       }
 32 |       return null;
 33 |     })
 34 |   ]);
 35 | }
 36 | 
 37 | export function createExecTimeColumns(data) {
 38 |   return createColumns(data, "benchmark");
 39 | }
 40 | 
 41 | export function createThroughputColumns(data) {
 42 |   return createColumns(data, "throughput");
 43 | }
 44 | 
 45 | export function createReqPerSecColumns(data) {
 46 |   return createColumns(data, "req_per_sec");
 47 | }
 48 | 
 49 | export function createMaxLatencyColumns(data) {
 50 |   return createColumns(data, "max_latency");
 51 | }
 52 | 
 53 | export function createBinarySizeColumns(data) {
 54 |   const propName = "binary_size";
 55 |   const binarySizeNames = Object.keys(data[data.length - 1][propName]);
 56 |   return binarySizeNames.map(name => [
 57 |     name,
 58 |     ...data.map(d => {
 59 |       const binarySizeData = d["binary_size"];
 60 |       switch (typeof binarySizeData) {
 61 |         case "number": // legacy implementation
 62 |           return name === "deno" ? binarySizeData : 0;
 63 |         default:
 64 |           if (!binarySizeData) {
 65 |             return null;
 66 |           }
 67 |           return binarySizeData[name] || null;
 68 |       }
 69 |     })
 70 |   ]);
 71 | }
 72 | 
 73 | export function createThreadCountColumns(data) {
 74 |   const propName = "thread_count";
 75 |   const threadCountNames = Object.keys(data[data.length - 1][propName]);
 76 |   return threadCountNames.map(name => [
 77 |     name,
 78 |     ...data.map(d => {
 79 |       const threadCountData = d[propName];
 80 |       if (!threadCountData) {
 81 |         return null;
 82 |       }
 83 |       return threadCountData[name] || null;
 84 |     })
 85 |   ]);
 86 | }
 87 | 
 88 | export function createSyscallCountColumns(data) {
 89 |   const propName = "syscall_count";
 90 |   const syscallCountNames = Object.keys(data[data.length - 1][propName]);
 91 |   return syscallCountNames.map(name => [
 92 |     name,
 93 |     ...data.map(d => {
 94 |       const syscallCountData = d[propName];
 95 |       if (!syscallCountData) {
 96 |         return null;
 97 |       }
 98 |       return syscallCountData[name] || null;
 99 |     })
100 |   ]);
101 | }
102 | 
103 | export function createSha1List(data) {
104 |   return data.map(d => d.sha1);
105 | }
106 | 
107 | export function formatMB(bytes) {
108 |   return (bytes / (1024 * 1024)).toFixed(2);
109 | }
110 | 
111 | export function formatReqSec(reqPerSec) {
112 |   return reqPerSec / 1000;
113 | }
114 | 
115 | /**
116 |  * @param {string} id The id of dom element
117 |  * @param {string[]} categories categories for x-axis values
118 |  * @param {any[][]} columns The columns data
119 |  * @param {function} onclick action on clicking nodes of chart
120 |  * @param {string} yLabel label of y axis
121 |  * @param {function} yTickFormat formatter of y axis ticks
122 |  */
123 | function generate(
124 |   id,
125 |   categories,
126 |   columns,
127 |   onclick,
128 |   yLabel = "",
129 |   yTickFormat = null
130 | ) {
131 |   const yAxis = {
132 |     padding: { bottom: 0 },
133 |     min: 0,
134 |     label: yLabel
135 |   };
136 |   if (yTickFormat) {
137 |     yAxis.tick = {
138 |       format: yTickFormat
139 |     };
140 |     if (yTickFormat == logScale) {
141 |       delete yAxis.min;
142 |       for (let col of columns) {
143 |         for (let i = 1; i < col.length; i++) {
144 |           if (col[i] == null) {
145 |             continue;
146 |           }
147 |           col[i] = Math.log10(col[i] * TimeScaleFactor);
148 |         }
149 |       }
150 |     }
151 |   }
152 | 
153 |   // @ts-ignore
154 |   c3.generate({
155 |     bindto: id,
156 |     data: {
157 |       columns,
158 |       onclick
159 |     },
160 |     axis: {
161 |       x: {
162 |         type: "category",
163 |         show: false,
164 |         categories
165 |       },
166 |       y: yAxis
167 |     }
168 |   });
169 | }
170 | 
171 | function logScale(t) {
172 |   return (Math.pow(10, t) / TimeScaleFactor).toFixed(4);
173 | }
174 | 
175 | function formatSecsAsMins(t) {
176 |   // TODO use d3.round()
177 |   const a = t % 60;
178 |   const min = Math.floor(t / 60);
179 |   return a < 30 ? min : min + 1;
180 | }
181 | 
182 | /**
183 |  * @param dataUrl The url of benchramk data json.
184 |  */
185 | export function drawCharts(dataUrl) {
186 |   // TODO Using window["location"]["hostname"] instead of
187 |   // window.location.hostname because when deno runs app_test.js it gets a type
188 |   // error here, not knowing about window.location.  Ideally Deno would skip
189 |   // type check entirely on JS files.
190 |   if (window["location"]["hostname"] != "deno.github.io") {
191 |     dataUrl = "https://denoland.github.io/deno/" + dataUrl;
192 |   }
193 |   drawChartsFromBenchmarkData(dataUrl);
194 | }
195 | 
196 | /**
197 |  * Draws the charts from the benchmark data stored in gh-pages branch.
198 |  */
199 | export async function drawChartsFromBenchmarkData(dataUrl) {
200 |   const data = await getJson(dataUrl);
201 | 
202 |   const execTimeColumns = createExecTimeColumns(data);
203 |   const throughputColumns = createThroughputColumns(data);
204 |   const reqPerSecColumns = createReqPerSecColumns(data);
205 |   const maxLatencyColumns = createMaxLatencyColumns(data);
206 |   const binarySizeColumns = createBinarySizeColumns(data);
207 |   const threadCountColumns = createThreadCountColumns(data);
208 |   const syscallCountColumns = createSyscallCountColumns(data);
209 |   const sha1List = createSha1List(data);
210 |   const sha1ShortList = sha1List.map(sha1 => sha1.substring(0, 6));
211 | 
212 |   const viewCommitOnClick = _sha1List => d => {
213 |     // @ts-ignore
214 |     window.open(
215 |       `https://github.com/denoland/deno/commit/${_sha1List[d["index"]]}`
216 |     );
217 |   };
218 | 
219 |   function gen(id, columns, yLabel = "", yTickFormat = null) {
220 |     generate(
221 |       id,
222 |       sha1ShortList,
223 |       columns,
224 |       viewCommitOnClick(sha1List),
225 |       yLabel,
226 |       yTickFormat
227 |     );
228 |   }
229 | 
230 |   gen("#exec-time-chart", execTimeColumns, "seconds", logScale);
231 |   gen("#throughput-chart", throughputColumns, "seconds", logScale);
232 |   gen("#req-per-sec-chart", reqPerSecColumns, "1000 req/sec", formatReqSec);
233 |   gen("#max-latency-chart", maxLatencyColumns, "milliseconds", logScale);
234 |   gen("#binary-size-chart", binarySizeColumns, "megabytes", formatMB);
235 |   gen("#thread-count-chart", threadCountColumns, "threads");
236 |   gen("#syscall-count-chart", syscallCountColumns, "syscalls");
237 | }
238 | 


--------------------------------------------------------------------------------
/style_guide.zh.md:
--------------------------------------------------------------------------------
  1 | # Deno 风格指南
  2 | 
  3 | <!-- START doctoc generated TOC please keep comment here to allow auto update -->
  4 | <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
  5 | 
  6 | 
  7 | - [使用 TypeScript](#%E4%BD%BF%E7%94%A8-typescript)
  8 | - [使用术语"模块(module)"，而不是"库(library)"或"包(package)"](#%E4%BD%BF%E7%94%A8%E6%9C%AF%E8%AF%AD%E6%A8%A1%E5%9D%97module%E8%80%8C%E4%B8%8D%E6%98%AF%E5%BA%93library%E6%88%96%E5%8C%85package)
  9 | - [不要使用文件名`"index.ts"或"index.js"`](#%E4%B8%8D%E8%A6%81%E4%BD%BF%E7%94%A8%E6%96%87%E4%BB%B6%E5%90%8Dindexts%E6%88%96indexjs)
 10 | - [在"deno-std"中，不依赖外部代码](#%E5%9C%A8deno-std%E4%B8%AD%E4%B8%8D%E4%BE%9D%E8%B5%96%E5%A4%96%E9%83%A8%E4%BB%A3%E7%A0%81)
 11 | - [在"deno-std"中，最小化依赖关系；不要进行循环导入。](#%E5%9C%A8deno-std%E4%B8%AD%E6%9C%80%E5%B0%8F%E5%8C%96%E4%BE%9D%E8%B5%96%E5%85%B3%E7%B3%BB%E4%B8%8D%E8%A6%81%E8%BF%9B%E8%A1%8C%E5%BE%AA%E7%8E%AF%E5%AF%BC%E5%85%A5)
 12 | - [为了保持一致性，文件名请使用下划线，而不是短划线。](#%E4%B8%BA%E4%BA%86%E4%BF%9D%E6%8C%81%E4%B8%80%E8%87%B4%E6%80%A7%E6%96%87%E4%BB%B6%E5%90%8D%E8%AF%B7%E4%BD%BF%E7%94%A8%E4%B8%8B%E5%88%92%E7%BA%BF%E8%80%8C%E4%B8%8D%E6%98%AF%E7%9F%AD%E5%88%92%E7%BA%BF)
 13 | - [使用 prettier 格式化代码。](#%E4%BD%BF%E7%94%A8-prettier-%E6%A0%BC%E5%BC%8F%E5%8C%96%E4%BB%A3%E7%A0%81)
 14 | - [导出的函数：最多 2 个参数，将其余的参数放入 options 对象。](#%E5%AF%BC%E5%87%BA%E7%9A%84%E5%87%BD%E6%95%B0%E6%9C%80%E5%A4%9A-2-%E4%B8%AA%E5%8F%82%E6%95%B0%E5%B0%86%E5%85%B6%E4%BD%99%E7%9A%84%E5%8F%82%E6%95%B0%E6%94%BE%E5%85%A5-options-%E5%AF%B9%E8%B1%A1)
 15 | - [TODO 注释(待续讨论)](#todo-%E6%B3%A8%E9%87%8A%E5%BE%85%E7%BB%AD%E8%AE%A8%E8%AE%BA)
 16 | - [版权标题](#%E7%89%88%E6%9D%83%E6%A0%87%E9%A2%98)
 17 | - [顶级函数，不应使用箭头语法](#%E9%A1%B6%E7%BA%A7%E5%87%BD%E6%95%B0%E4%B8%8D%E5%BA%94%E4%BD%BF%E7%94%A8%E7%AE%AD%E5%A4%B4%E8%AF%AD%E6%B3%95)
 18 | - [不鼓励，使用元编程。包括代理的用法。](#%E4%B8%8D%E9%BC%93%E5%8A%B1%E4%BD%BF%E7%94%A8%E5%85%83%E7%BC%96%E7%A8%8B%E5%8C%85%E6%8B%AC%E4%BB%A3%E7%90%86%E7%9A%84%E7%94%A8%E6%B3%95)
 19 | - [如果文件名，以下划线开头，请不要链接到它："_foo.ts"`](#%E5%A6%82%E6%9E%9C%E6%96%87%E4%BB%B6%E5%90%8D%E4%BB%A5%E4%B8%8B%E5%88%92%E7%BA%BF%E5%BC%80%E5%A4%B4%E8%AF%B7%E4%B8%8D%E8%A6%81%E9%93%BE%E6%8E%A5%E5%88%B0%E5%AE%83_foots)
 20 | - [使用 jsdoc 文档化，导出 API 的情况](#%E4%BD%BF%E7%94%A8-jsdoc-%E6%96%87%E6%A1%A3%E5%8C%96%E5%AF%BC%E5%87%BA-api-%E7%9A%84%E6%83%85%E5%86%B5)
 21 | - [每个模块都应该有测试](#%E6%AF%8F%E4%B8%AA%E6%A8%A1%E5%9D%97%E9%83%BD%E5%BA%94%E8%AF%A5%E6%9C%89%E6%B5%8B%E8%AF%95)
 22 | - [单元测试应该是明确的](#%E5%8D%95%E5%85%83%E6%B5%8B%E8%AF%95%E5%BA%94%E8%AF%A5%E6%98%AF%E6%98%8E%E7%A1%AE%E7%9A%84)
 23 | 
 24 | <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 25 | 
 26 | ## 使用 TypeScript
 27 | 
 28 | ## 使用术语"模块(module)"，而不是"库(library)"或"包(package)"
 29 | 
 30 | 为了明确性和一致性，请避免使用术语"库"和"包"。而是使用"module"来指明单个 JS 或 TS 文件，当然还包括 TS / JS 代码的目录。
 31 | 
 32 | ## 不要使用文件名`"index.ts"或"index.js"`
 33 | 
 34 | Deno 不会对"index.js"或"index.ts"特殊处理。这些文件名的使用，会对当不用它们时，却可以被排除在模块描述之外，感到困惑。
 35 | 
 36 | 如果代码目录需要默认入口点，请使用文件名`mod.ts`。文件名`mod.ts`遵循 Rust 的惯例，比`index.ts`简短，并且没有任何先入为主，关于其应该如何运作的观念。
 37 | 
 38 | ## 在"deno-std"中，不依赖外部代码
 39 | 
 40 | `deno_std`旨在成为所有 Deno 程序可以依赖的地基功能。我们希望向用户保证此代码，不包含可能未经审核的第三方代码。
 41 | 
 42 | ## 在"deno-std"中，最小化依赖关系；不要进行循环导入。
 43 | 
 44 | 虽然`deno_std`是一个独立的代码库，我们仍然必须小心保持，内部依赖关系的简单和易于管理。特别要注意，不要产生(死)循环导入。
 45 | 
 46 | ## 为了保持一致性，文件名请使用下划线，而不是短划线。
 47 | 
 48 | 示例：不是`file-server.ts`，使用`file_server.ts`。
 49 | 
 50 | ## 使用 prettier 格式化代码。
 51 | 
 52 | 更具体地说，代码行应在 80 列内，使用 2 空格缩进，并使用驼峰式。使用`//format.ts`调用 prettier。
 53 | 
 54 | ## 导出的函数：最多 2 个参数，将其余的参数放入 options 对象。
 55 | 
 56 | 设计函数接口时，请遵守以下规则。
 57 | 
 58 | 1.  作为公有 API 一部分的函数需要 0-2 个必需参数，如果需要的话，加上一个选项(options)对象（总共最多 3 个）。
 59 | 
 60 | 2.  可选参数，通常应该放进 options 对象。
 61 | 
 62 |     如果只有一个参数，且我们将来不太可能添加更多可选参数，那么不在选项对象中的可选参数，是能够接受的。
 63 | 
 64 | 3.  'options'参数是唯一的常规'Object'类型。
 65 | 
 66 |     其他参数可以是对象(/容器类型)，但它们必须与"普通"对象(`Object`)运行时，区分开来，方法是：
 67 | 
 68 |     - 一个有区别的原型（例如`Array`，`Map`，`Date`，`class MyThing`）
 69 |     - 一个众所周知的符号属性（例如，一个可迭代的`Symbol.iterator`）。
 70 | 
 71 |     这允许 API 以向后兼容的方式扩展，即使选项对象的位置，发生变化也能行。
 72 | 
 73 | ```ts
 74 | // 不好的方式: 可选参数，不是options 对象的一部分。 (#2)
 75 | export function resolve(
 76 |   hostname: string,
 77 |   family?: 'ipv4' | 'ipv6',
 78 |   timeout?: number
 79 | ): IPAddress[] {}
 80 | 
 81 | // 好的方式.
 82 | export interface ResolveOptions {
 83 |   family?: 'ipv4' | 'ipv6';
 84 |   timeout?: number;
 85 | }
 86 | export function resolve(
 87 |   hostname: string,
 88 |   options: ResolveOptions = {}
 89 | ): IPAddress[] {}
 90 | ```
 91 | 
 92 | ```ts
 93 | export interface Environment {
 94 |   [key: string]: string;
 95 | }
 96 | 
 97 | // 不好的方式: `env` 可能是常规对象，因此无法区分是否为一个选项对象. (#3)
 98 | export function runShellWithEnv(cmdline: string, env: Environment): string {}
 99 | 
100 | // 好的方式.
101 | export interface RunShellOptions {
102 |   env: Environment;
103 | }
104 | export function runShellWithEnv(
105 |   cmdline: string,
106 |   options: RunShellOptions
107 | ): string {}
108 | ```
109 | 
110 | ```ts
111 | // 不好的方式: 超过 3 参数 (#1), 过多可选参数 (#2).
112 | export function renameSync(
113 |   oldname: string,
114 |   newname: string,
115 |   replaceExisting?: boolean,
116 |   followLinks?: boolean
117 | ) {}
118 | 
119 | // 好的方式.
120 | interface RenameOptions {
121 |   replaceExisting?: boolean;
122 |   followLinks?: boolean;
123 | }
124 | export function renameSync(
125 |   oldname: string,
126 |   newname: string,
127 |   options: RenameOptions = {}
128 | ) {}
129 | ```
130 | 
131 | ```ts
132 | // 不好的方式: 过多参数. (#1)
133 | export function pwrite(
134 |   fd: number,
135 |   buffer: TypedArray,
136 |   offset: number,
137 |   length: number,
138 |   position: number
139 | ) {}
140 | 
141 | // 更好.
142 | export interface PWrite {
143 |   fd: number;
144 |   buffer: TypedArray;
145 |   offset: number;
146 |   length: number;
147 |   position: number;
148 | }
149 | export function pwrite(options: PWrite) {}
150 | ```
151 | 
152 | ## TODO 注释(待续讨论)
153 | 
154 | TODO 注释应该在括号中，包含问题或作者的 github 用户名。例：
155 | 
156 | ```ts
157 | // TODO(ry) Add tests.
158 | // TODO(#123) Support Windows.
159 | ```
160 | 
161 | ## 版权标题
162 | 
163 | `deno_std`大多数文件，应具有以下版权标题：
164 | 
165 | ```ts
166 | // Copyright 2018-2019 the Deno authors. All rights reserved. MIT license.
167 | ```
168 | 
169 | 如果代码来自其他地方，请确保该文件，具有适当的版权标题。我们`deno_std`只允许使用 MIT，BSD 和 Apache 许可代码。
170 | 
171 | ## 顶级函数，不应使用箭头语法
172 | 
173 | 顶级函数应该使用`function`关键词。箭头语法，应仅限闭包使用。
174 | 
175 | 坏
176 | 
177 | ```ts
178 | export const foo(): string => {
179 |   return "bar";
180 | }
181 | ```
182 | 
183 | 好
184 | 
185 | ```ts
186 | export function foo(): string {
187 |   return 'bar';
188 | }
189 | ```
190 | 
191 | ## 不鼓励，使用元编程。包括代理的用法。
192 | 
193 | 即使它意味着更多的代码，也要代码具备明确性。
194 | 
195 | 在某些情况下，使用这些技术，可能是有意义的，但在绝大多数情况下，没有。
196 | 
197 | ## 如果文件名，以下划线开头，请不要链接到它："_foo.ts"`
198 | 
199 | 有时可能存在内部模块的需要，但其 API 不是稳定或可供链接的情况。在这种情况下，用下划线作为前缀。按照惯例，只有本文件目录中的(文件)，才能导入它。
200 | 
201 | ## 使用 jsdoc 文档化，导出 API 的情况
202 | 
203 | 我们力求完整的文档。理想情况下，每个导出的符号，都应该有文档行。
204 | 
205 | 如果可能，请编写 JS 文档。例：
206 | 
207 | ```ts
208 | /** foo 做了某 bar. */
209 | export function foo() {
210 |   // ...
211 | }
212 | ```
213 | 
214 | 重要的是文档，易于给人阅读，但还需要提供额外的样式信息，以确保生成的文档是，更丰富的文本。因此，JSDoc 通常遵循 markdown 标记，来丰富文本。
215 | 
216 | 虽然 markdown 支持 HTML 标签，但在 JSDoc 区块中，禁止使用。
217 | 
218 | 代码格式字符串，应使用反引号（\`)标记而不是引号。例如：
219 | 
220 | ```ts
221 | /** Import something from the `deno` module. */
222 | ```
223 | 
224 | 不要文档化函数参数，除非它们的意图不明显（尽管它们，具有不明显意图，但 API 无论如何都应该考虑清楚）。因此`@param`通常，不应该使用。如果`@param`真使用了，那它不应该包括`type`，因为 TypeScript 已经是强类型的。
225 | 
226 | ```ts
227 | /**
228 |  * 带有不明显意图参数的函数
229 |  * @param foo 描述不明显意图的参数
230 |  */
231 | ```
232 | 
233 | 应尽可能减小垂直间距。因此，单行注释应写为：
234 | 
235 | ```ts
236 | /** JSDoc 单行标准写法 */
237 | ```
238 | 
239 | 而不是
240 | 
241 | ```ts
242 | /**
243 |  * JSDoc 差的示例
244 |  */
245 | ```
246 | 
247 | 代码示例(区块)，不应使用三个反引号（\`\`\`）表示。它们应该只用缩进：具体需要在区块之前空一行，并为示例的每一行，添加 6 个额外的空格。这比注释的第一列，多 4 个。例如：
248 | 
249 | ```ts
250 | /** A straight forward comment and an example:
251 |  *
252 |  *       import { foo } from "deno";
253 |  *       foo("bar");
254 |  */
255 | ```
256 | 
257 | 代码示例，不应包含其他注释。它已经在外注释中。如果它需要进一步的注释，那就不是一个很好的例子。
258 | 
259 | ## 每个模块都应该有测试
260 | 
261 | 每个模块应该有个测试文件`modulename_test.ts`，作为它的兄弟姐妹。例如模块`foo.ts`应该带着它的兄弟姐妹`foo_test.ts`。
262 | 
263 | ## 单元测试应该是明确的
264 | 
265 | 为了更好地理解测试，应在整个测试命令中，正确命名函数，比如：
266 | 
267 | ```
268 | test myTestFunction ... ok
269 | ```
270 | 
271 | 测试示例：
272 | 
273 | ```ts
274 | import {assertEquals} from 'https://deno.land/std@v0.3.1/testing/asserts.ts';
275 | import {test} from 'https://deno.land/std@v0.3.1/testing/mod.ts';
276 | import {foo} from './mod.ts';
277 | 
278 | test(function myTestFunction() {
279 |   assertEquals(foo(), {bar: 'bar'});
280 | });
281 | ```
282 | 


--------------------------------------------------------------------------------
/style_guide.md:
--------------------------------------------------------------------------------
  1 | # Deno Style Guide
  2 | 
  3 | [toc]
  4 | 
  5 | ## Use TypeScript
  6 | 
  7 | ## Use the term "module" instead of "library" or "package"
  8 | 
  9 | For clarity and consistency avoid the terms "library" and "package". Instead use
 10 | "module" to refer to a single JS or TS file and also to refer to a directory of
 11 | TS/JS code.
 12 | 
 13 | ## Do not use the filename `index.ts` nor `index.js`
 14 | 
 15 | Deno does not treat "index.js" or "index.ts" in a special way. By using these
 16 | filenames, it suggests that they can be left out of the module specifier when
 17 | they cannot. This is confusing.
 18 | 
 19 | If a directory of code needs a default entry point, use the filename `mod.ts`.
 20 | The filename `mod.ts` follows Rust’s convention, is shorter than `index.ts`, and
 21 | doesn’t come with any preconceived notions about how it might work.
 22 | 
 23 | ## Within `deno_std`, do not depend on external code
 24 | 
 25 | `deno_std` is intended to be baseline functionality that all Deno programs can
 26 | rely on. We want to guarantee to users that this code does not include
 27 | potentially unreviewed third party code.
 28 | 
 29 | ## Within `deno_std`, minimize dependencies; do not make circular imports.
 30 | 
 31 | Although `deno_std` is a standalone codebase, we must still be careful to keep
 32 | the internal dependencies simple and manageable. In particular, be careful to
 33 | not to introduce circular imports.
 34 | 
 35 | ## For consistency, use underscores, not dashes in filenames.
 36 | 
 37 | Example: Instead of `file-server.ts` use `file_server.ts`.
 38 | 
 39 | ## Format code according using prettier.
 40 | 
 41 | More specifically, code should be wrapped at 80 columns and use 2-space
 42 | indentation and use camel-case. Use `//format.ts` to invoke prettier.
 43 | 
 44 | ## Exported functions: max 2 args, put the rest into an options object.
 45 | 
 46 | When designing function interfaces, stick to the following rules.
 47 | 
 48 | 1. A function that is part of the public API takes 0-2 required arguments, plus
 49 |    (if necessary) an options object (so max 3 total).
 50 | 
 51 | 2. Optional parameters should generally go into the options object.
 52 | 
 53 |    An optional parameter that's not in an options object might be acceptable if
 54 |    there is only one, and it seems inconceivable that we would add more optional
 55 |    parameters in the future.
 56 | 
 57 | 3. The 'options' argument is the only argument that is a regular 'Object'.
 58 | 
 59 |    Other arguments can be objects, but they must be distinguishable from a
 60 |    'plain' Object runtime, by having either:
 61 | 
 62 |    - a distinguishing prototype (e.g. `Array`, `Map`, `Date`, `class MyThing`)
 63 |    - a well-known symbol property (e.g. an iterable with `Symbol.iterator`).
 64 | 
 65 |    This allows the API to evolve in a backwards compatible way, even when the
 66 |    position of the options object changes.
 67 | 
 68 | ```ts
 69 | // BAD: optional parameters not part of options object. (#2)
 70 | export function resolve(
 71 |   hostname: string,
 72 |   family?: "ipv4" | "ipv6",
 73 |   timeout?: number
 74 | ): IPAddress[] {}
 75 | 
 76 | // GOOD.
 77 | export interface ResolveOptions {
 78 |   family?: "ipv4" | "ipv6";
 79 |   timeout?: number;
 80 | }
 81 | export function resolve(
 82 |   hostname: string,
 83 |   options: ResolveOptions = {}
 84 | ): IPAddress[] {}
 85 | ```
 86 | 
 87 | ```ts
 88 | export interface Environment {
 89 |   [key: string]: string;
 90 | }
 91 | 
 92 | // BAD: `env` could be a regular Object and is therefore indistinguishable
 93 | // from an options object. (#3)
 94 | export function runShellWithEnv(cmdline: string, env: Environment): string {}
 95 | 
 96 | // GOOD.
 97 | export interface RunShellOptions {
 98 |   env: Environment;
 99 | }
100 | export function runShellWithEnv(
101 |   cmdline: string,
102 |   options: RunShellOptions
103 | ): string {}
104 | ```
105 | 
106 | ```ts
107 | // BAD: more than 3 arguments (#1), multiple optional parameters (#2).
108 | export function renameSync(
109 |   oldname: string,
110 |   newname: string,
111 |   replaceExisting?: boolean,
112 |   followLinks?: boolean
113 | ) {}
114 | 
115 | // GOOD.
116 | interface RenameOptions {
117 |   replaceExisting?: boolean;
118 |   followLinks?: boolean;
119 | }
120 | export function renameSync(
121 |   oldname: string,
122 |   newname: string,
123 |   options: RenameOptions = {}
124 | ) {}
125 | ```
126 | 
127 | ```ts
128 | // BAD: too many arguments. (#1)
129 | export function pwrite(
130 |   fd: number,
131 |   buffer: TypedArray,
132 |   offset: number,
133 |   length: number,
134 |   position: number
135 | ) {}
136 | 
137 | // BETTER.
138 | export interface PWrite {
139 |   fd: number;
140 |   buffer: TypedArray;
141 |   offset: number;
142 |   length: number;
143 |   position: number;
144 | }
145 | export function pwrite(options: PWrite) {}
146 | ```
147 | 
148 | ## TODO Comments
149 | 
150 | TODO comments should include an issue or the author's github username in
151 | parentheses. Example:
152 | 
153 | ```ts
154 | // TODO(ry) Add tests.
155 | // TODO(#123) Support Windows.
156 | ```
157 | 
158 | ## Copyright headers
159 | 
160 | Most files in `deno_std` should have the following copyright header:
161 | 
162 | ```ts
163 | // Copyright 2018-2019 the Deno authors. All rights reserved. MIT license.
164 | ```
165 | 
166 | If the code originates elsewhere, ensure that the file has the proper copyright
167 | headers. We only allow MIT, BSD, and Apache licensed code in `deno_std`.
168 | 
169 | ## Top level functions should not use arrow syntax
170 | 
171 | Top level functions should use the `function` keyword. Arrow syntax should be
172 | limited to closures.
173 | 
174 | Bad
175 | 
176 | ```ts
177 | export const foo(): string => {
178 |   return "bar";
179 | }
180 | ```
181 | 
182 | Good
183 | 
184 | ```ts
185 | export function foo(): string {
186 |   return "bar";
187 | }
188 | ```
189 | 
190 | ## Meta-programming is discouraged. Including the use of Proxy.
191 | 
192 | Be explicit even when it means more code.
193 | 
194 | There are some situations where it may make sense to use such techniques, but in
195 | the vast majority of cases it does not.
196 | 
197 | ## If a filename starts with underscore, do not link to it: `_foo.ts`
198 | 
199 | Sometimes there maybe situations where an internal module is necessary but its
200 | API is not meant to be stable or linked to. In this case prefix it with an
201 | underscore. By convention, only files in its own directory should import it.
202 | 
203 | ## Use JSDoc to document exported machinery
204 | 
205 | We strive for complete documentation. Every exported symbol ideally should have
206 | a documentation line.
207 | 
208 | If possible, use a single line for the JS Doc. Example:
209 | 
210 | ```ts
211 | /** foo does bar. */
212 | export function foo() {
213 |   // ...
214 | }
215 | ```
216 | 
217 | It is important that documentation is easily human readable, but there is also a
218 | need to provide additional styling information to ensure generated documentation
219 | is more rich text. Therefore JSDoc should generally follow markdown markup to
220 | enrich the text.
221 | 
222 | While markdown supports HTML tags, it is forbidden in JSDoc blocks.
223 | 
224 | Code string literals should be braced with the back-tick (\`) instead of quotes.
225 | For example:
226 | 
227 | ```ts
228 | /** Import something from the `deno` module. */
229 | ```
230 | 
231 | Do not document function arguments unless they are non-obvious of their intent
232 | (though if they are non-obvious intent, the API should be considered anyways).
233 | Therefore `@param` should generally not be used. If `@param` is used, it should
234 | not include the `type` as TypeScript is already strongly typed.
235 | 
236 | ```ts
237 | /**
238 |  * Function with non obvious param
239 |  * @param foo Description of non obvious parameter
240 |  */
241 | ```
242 | 
243 | Vertical spacing should be minimized whenever possible. Therefore single line
244 | comments should be written as:
245 | 
246 | ```ts
247 | /** This is a good single line JSDoc */
248 | ```
249 | 
250 | And not
251 | 
252 | ```ts
253 | /**
254 |  * This is a bad single line JSDoc
255 |  */
256 | ```
257 | 
258 | Code examples should not utilise the triple-back tick (\`\`\`) notation or tags.
259 | They should just be marked by indentation, which requires a break before the
260 | block and 6 additional spaces for each line of the example. This is 4 more than
261 | the first column of the comment. For example:
262 | 
263 | ```ts
264 | /** A straight forward comment and an example:
265 |  *
266 |  *       import { foo } from "deno";
267 |  *       foo("bar");
268 |  */
269 | ```
270 | 
271 | Code examples should not contain additional comments. It is already inside a
272 | comment. If it needs further comments is not a good example.
273 | 
274 | ## Each module should come with tests
275 | 
276 | Each module should come with its test as a sibling with the name
277 | `modulename_test.ts`. For example the module `foo.ts` should come with its
278 | sibling `foo_test.ts`.
279 | 
280 | ## Unit Tests should be explicit
281 | 
282 | For a better understanding of the tests, function should be correctly named as
283 | its prompted throughout the test command. Like:
284 | 
285 | ```
286 | test myTestFunction ... ok
287 | ```
288 | 
289 | Example of test:
290 | 
291 | ```ts
292 | import { assertEquals } from "https://deno.land/std@v0.3.1/testing/asserts.ts";
293 | import { test } from "https://deno.land/std@v0.3.1/testing/mod.ts";
294 | import { foo } from "./mod.ts";
295 | 
296 | test(function myTestFunction() {
297 |   assertEquals(foo(), { bar: "bar" });
298 | });
299 | ```
300 | 


--------------------------------------------------------------------------------
/docs/style_guide.md:
--------------------------------------------------------------------------------
  1 | # Deno Style Guide
  2 | 
  3 | [toc]
  4 | 
  5 | ## Use TypeScript
  6 | 
  7 | ## Use the term "module" instead of "library" or "package"
  8 | 
  9 | For clarity and consistency avoid the terms "library" and "package". Instead use
 10 | "module" to refer to a single JS or TS file and also to refer to a directory of
 11 | TS/JS code.
 12 | 
 13 | ## Do not use the filename `index.ts` nor `index.js`
 14 | 
 15 | Deno does not treat "index.js" or "index.ts" in a special way. By using these
 16 | filenames, it suggests that they can be left out of the module specifier when
 17 | they cannot. This is confusing.
 18 | 
 19 | If a directory of code needs a default entry point, use the filename `mod.ts`.
 20 | The filename `mod.ts` follows Rust’s convention, is shorter than `index.ts`, and
 21 | doesn’t come with any preconceived notions about how it might work.
 22 | 
 23 | ## Within `deno_std`, do not depend on external code
 24 | 
 25 | `deno_std` is intended to be baseline functionality that all Deno programs can
 26 | rely on. We want to guarantee to users that this code does not include
 27 | potentially unreviewed third party code.
 28 | 
 29 | ## Within `deno_std`, minimize dependencies; do not make circular imports.
 30 | 
 31 | Although `deno_std` is a standalone codebase, we must still be careful to keep
 32 | the internal dependencies simple and manageable. In particular, be careful to
 33 | not to introduce circular imports.
 34 | 
 35 | ## For consistency, use underscores, not dashes in filenames.
 36 | 
 37 | Example: Instead of `file-server.ts` use `file_server.ts`.
 38 | 
 39 | ## Format code according using prettier.
 40 | 
 41 | More specifically, code should be wrapped at 80 columns and use 2-space
 42 | indentation and use camel-case. Use `//format.ts` to invoke prettier.
 43 | 
 44 | ## Exported functions: max 2 args, put the rest into an options object.
 45 | 
 46 | When designing function interfaces, stick to the following rules.
 47 | 
 48 | 1. A function that is part of the public API takes 0-2 required arguments, plus
 49 |    (if necessary) an options object (so max 3 total).
 50 | 
 51 | 2. Optional parameters should generally go into the options object.
 52 | 
 53 |    An optional parameter that's not in an options object might be acceptable if
 54 |    there is only one, and it seems inconceivable that we would add more optional
 55 |    parameters in the future.
 56 | 
 57 | 3. The 'options' argument is the only argument that is a regular 'Object'.
 58 | 
 59 |    Other arguments can be objects, but they must be distinguishable from a
 60 |    'plain' Object runtime, by having either:
 61 | 
 62 |    - a distinguishing prototype (e.g. `Array`, `Map`, `Date`, `class MyThing`)
 63 |    - a well-known symbol property (e.g. an iterable with `Symbol.iterator`).
 64 | 
 65 |    This allows the API to evolve in a backwards compatible way, even when the
 66 |    position of the options object changes.
 67 | 
 68 | ```ts
 69 | // BAD: optional parameters not part of options object. (#2)
 70 | export function resolve(
 71 |   hostname: string,
 72 |   family?: "ipv4" | "ipv6",
 73 |   timeout?: number
 74 | ): IPAddress[] {}
 75 | 
 76 | // GOOD.
 77 | export interface ResolveOptions {
 78 |   family?: "ipv4" | "ipv6";
 79 |   timeout?: number;
 80 | }
 81 | export function resolve(
 82 |   hostname: string,
 83 |   options: ResolveOptions = {}
 84 | ): IPAddress[] {}
 85 | ```
 86 | 
 87 | ```ts
 88 | export interface Environment {
 89 |   [key: string]: string;
 90 | }
 91 | 
 92 | // BAD: `env` could be a regular Object and is therefore indistinguishable
 93 | // from an options object. (#3)
 94 | export function runShellWithEnv(cmdline: string, env: Environment): string {}
 95 | 
 96 | // GOOD.
 97 | export interface RunShellOptions {
 98 |   env: Environment;
 99 | }
100 | export function runShellWithEnv(
101 |   cmdline: string,
102 |   options: RunShellOptions
103 | ): string {}
104 | ```
105 | 
106 | ```ts
107 | // BAD: more than 3 arguments (#1), multiple optional parameters (#2).
108 | export function renameSync(
109 |   oldname: string,
110 |   newname: string,
111 |   replaceExisting?: boolean,
112 |   followLinks?: boolean
113 | ) {}
114 | 
115 | // GOOD.
116 | interface RenameOptions {
117 |   replaceExisting?: boolean;
118 |   followLinks?: boolean;
119 | }
120 | export function renameSync(
121 |   oldname: string,
122 |   newname: string,
123 |   options: RenameOptions = {}
124 | ) {}
125 | ```
126 | 
127 | ```ts
128 | // BAD: too many arguments. (#1)
129 | export function pwrite(
130 |   fd: number,
131 |   buffer: TypedArray,
132 |   offset: number,
133 |   length: number,
134 |   position: number
135 | ) {}
136 | 
137 | // BETTER.
138 | export interface PWrite {
139 |   fd: number;
140 |   buffer: TypedArray;
141 |   offset: number;
142 |   length: number;
143 |   position: number;
144 | }
145 | export function pwrite(options: PWrite) {}
146 | ```
147 | 
148 | ## TODO Comments
149 | 
150 | TODO comments should include an issue or the author's github username in
151 | parentheses. Example:
152 | 
153 | ```ts
154 | // TODO(ry) Add tests.
155 | // TODO(#123) Support Windows.
156 | ```
157 | 
158 | ## Copyright headers
159 | 
160 | Most files in `deno_std` should have the following copyright header:
161 | 
162 | ```ts
163 | // Copyright 2018-2019 the Deno authors. All rights reserved. MIT license.
164 | ```
165 | 
166 | If the code originates elsewhere, ensure that the file has the proper copyright
167 | headers. We only allow MIT, BSD, and Apache licensed code in `deno_std`.
168 | 
169 | ## Top level functions should not use arrow syntax
170 | 
171 | Top level functions should use the `function` keyword. Arrow syntax should be
172 | limited to closures.
173 | 
174 | Bad
175 | 
176 | ```ts
177 | export const foo(): string => {
178 |   return "bar";
179 | }
180 | ```
181 | 
182 | Good
183 | 
184 | ```ts
185 | export function foo(): string {
186 |   return "bar";
187 | }
188 | ```
189 | 
190 | ## Meta-programming is discouraged. Including the use of Proxy.
191 | 
192 | Be explicit even when it means more code.
193 | 
194 | There are some situations where it may make sense to use such techniques, but in
195 | the vast majority of cases it does not.
196 | 
197 | ## If a filename starts with underscore, do not link to it: `_foo.ts`
198 | 
199 | Sometimes there maybe situations where an internal module is necessary but its
200 | API is not meant to be stable or linked to. In this case prefix it with an
201 | underscore. By convention, only files in its own directory should import it.
202 | 
203 | ## Use JSDoc to document exported machinery
204 | 
205 | We strive for complete documentation. Every exported symbol ideally should have
206 | a documentation line.
207 | 
208 | If possible, use a single line for the JS Doc. Example:
209 | 
210 | ```ts
211 | /** foo does bar. */
212 | export function foo() {
213 |   // ...
214 | }
215 | ```
216 | 
217 | It is important that documentation is easily human readable, but there is also a
218 | need to provide additional styling information to ensure generated documentation
219 | is more rich text. Therefore JSDoc should generally follow markdown markup to
220 | enrich the text.
221 | 
222 | While markdown supports HTML tags, it is forbidden in JSDoc blocks.
223 | 
224 | Code string literals should be braced with the back-tick (\`) instead of quotes.
225 | For example:
226 | 
227 | ```ts
228 | /** Import something from the `deno` module. */
229 | ```
230 | 
231 | Do not document function arguments unless they are non-obvious of their intent
232 | (though if they are non-obvious intent, the API should be considered anyways).
233 | Therefore `@param` should generally not be used. If `@param` is used, it should
234 | not include the `type` as TypeScript is already strongly typed.
235 | 
236 | ```ts
237 | /**
238 |  * Function with non obvious param
239 |  * @param foo Description of non obvious parameter
240 |  */
241 | ```
242 | 
243 | Vertical spacing should be minimized whenever possible. Therefore single line
244 | comments should be written as:
245 | 
246 | ```ts
247 | /** This is a good single line JSDoc */
248 | ```
249 | 
250 | And not
251 | 
252 | ```ts
253 | /**
254 |  * This is a bad single line JSDoc
255 |  */
256 | ```
257 | 
258 | Code examples should not utilise the triple-back tick (\`\`\`) notation or tags.
259 | They should just be marked by indentation, which requires a break before the
260 | block and 6 additional spaces for each line of the example. This is 4 more than
261 | the first column of the comment. For example:
262 | 
263 | ```ts
264 | /** A straight forward comment and an example:
265 |  *
266 |  *       import { foo } from "deno";
267 |  *       foo("bar");
268 |  */
269 | ```
270 | 
271 | Code examples should not contain additional comments. It is already inside a
272 | comment. If it needs further comments is not a good example.
273 | 
274 | ## Each module should come with tests
275 | 
276 | Each module should come with its test as a sibling with the name
277 | `modulename_test.ts`. For example the module `foo.ts` should come with its
278 | sibling `foo_test.ts`.
279 | 
280 | ## Unit Tests should be explicit
281 | 
282 | For a better understanding of the tests, function should be correctly named as
283 | its prompted throughout the test command. Like:
284 | 
285 | ```
286 | test myTestFunction ... ok
287 | ```
288 | 
289 | Example of test:
290 | 
291 | ```ts
292 | import { assertEquals } from "https://deno.land/std@v0.3.1/testing/asserts.ts";
293 | import { test } from "https://deno.land/std@v0.3.1/testing/mod.ts";
294 | import { foo } from "./mod.ts";
295 | 
296 | test(function myTestFunction() {
297 |   assertEquals(foo(), { bar: "bar" });
298 | });
299 | ```
300 | 


--------------------------------------------------------------------------------
/docs/manual.zh.md:
--------------------------------------------------------------------------------
  1 | # Deno 手册
  2 | 
  3 | ## 免责声明
  4 | 
  5 | 警告语：Deno 正在开发中。我们鼓励勇敢的早期采用者，但期望反馈大或小的 Bug。API 如有变更，恕不另行通知。[错误报告](https://github.com/denoland/deno/issues)会有用！
  6 | 
  7 | ## 介绍
  8 | 
  9 | 使用 V8、Rust 和 Tokio 构建的安全 javascript/typescript 运行时
 10 | 
 11 | ### 哲学
 12 | 
 13 | Deno 的目标是为现代程序员提供一个高效、安全的脚本环境。
 14 | 
 15 | 它始终以单个可执行文件形态，作为分发文件，并且该可执行文件，足够运行任何 deno 程序。给定一个 deno 程序的 URL，您应该能够用不超过 50MB 的 Deno 可执行文件，来执行它。
 16 | 
 17 | Deno 明确承担运行时，和包管理器的角色。它用标准的浏览器兼容协议，来加载模块：URLs。
 18 | 
 19 | Deno 为提供了程序访问系统的安全保证，默认情况下，它是最严格的安全沙盒。
 20 | 
 21 | Deno 提供<a href="https://github.com/denoland/deno_std">一套经过评审（审核）的标准模块</a>这保证了与 Deno 的合作。
 22 | 
 23 | ### 目标
 24 | 
 25 | - 支持现成的 typescript。
 26 | 
 27 | - 与浏览器一样，允许（模块）以 URL 形式导入：
 28 | 
 29 |   ```ts
 30 |   import * as log from 'https://deno.land/std/log/mod.ts';
 31 |   ```
 32 | 
 33 | - 远程代码在第一次执行时，被获取和缓存，并且在使用`--reload`标志，才会更新(同一 URL 路径的代码)。（所以，还能在飞机上使用。见`~/.deno/src`，有关缓存的详细信息。）
 34 | 
 35 | - 使用"ES 模块"，不支持`require()`.
 36 | 
 37 | - 为了沙盒代码的运行，会对文件系统和网络访问(权限)有所控制。V8（没权限）和 Rust（权限）之间的访问，只能通过在[flatbuffer](https://github.com/denoland/deno/blob/master/cli/msg.fbs)定义的序列化消息，完成沟通。这使得审计变得容易。例如，要启用 write(写) 访问，请使用标志`--allow-write`，或用于网络访问`--allow-net`。
 38 | 
 39 | - 只运输一个可执行文件。
 40 | 
 41 | - 总是死(崩溃)于，未发现的错误。
 42 | 
 43 | - 浏览器兼容：Deno 程序的子集，完全用 JavaScript 编写，它（或它的功能测试）并没有使用全局`Deno`名称空间，想来应该能够在现代 Web 浏览器上运行，而不需要更改。
 44 | 
 45 | - [目标：支持顶级`await`.](https://github.com/denoland/deno/issues/471)
 46 | 
 47 | - 能够高效地服务 HTTP。（[目前，速度比较慢。](https://deno.land/benchmarks.html#req-per-sec)）
 48 | 
 49 | - 提供现成的有用工具：
 50 |   - 命令行调试器[还没有](https://github.com/denoland/deno/issues/1120)
 51 |   - linter[还没有](https://github.com/denoland/deno/issues/1880)
 52 |   - 依赖关系检查器（`deno info`）
 53 |   - 代码格式化程序（`deno fmt`）
 54 | 
 55 | ### 反目标
 56 | 
 57 | - 没有`package.json`.
 58 | 
 59 | - 没有 npm。
 60 | 
 61 | - 与 Node 不显式兼容。
 62 | 
 63 | ## 安装程序
 64 | 
 65 | ### 二进制安装
 66 | 
 67 | Deno 在 OSX、Linux 和 Windows 上工作。deno 是单个二进制可执行文件。它没有外部依赖关系。
 68 | 
 69 | [deno_install](https://github.com/denoland/deno_install)提供方便的脚本，来下载和安装二进制文件。
 70 | 
 71 | 使用 Shell：
 72 | 
 73 | ```shellsession
 74 | $ curl -fsSL https://deno.land/x/install/install.sh | sh
 75 | ```
 76 | 
 77 | 使用 PowerShell:
 78 | 
 79 | ```shellsession
 80 | > iwr https://deno.land/x/install/install.ps1 | iex
 81 | ```
 82 | 
 83 | 使用[Scoop](https://scoop.sh/)（Windows）：
 84 | 
 85 | ```
 86 | scoop install deno
 87 | ```
 88 | 
 89 | 也可以通过[github.com/denoland/deno/releases](https://github.com/denoland/deno/releases)下载 tarball 或 zip 文件，手动安装 deno。这些包只包含一个可执行文件。您必须在 Mac 和 Linux 上，设置可执行的环境变量(PATH)。
 90 | 
 91 | 一旦它安装和已在`$PATH`，开始试试吧：
 92 | 
 93 | ```shellsession
 94 | $ deno https://deno.land/welcome.ts
 95 | ```
 96 | 
 97 | ### 从源代码生成
 98 | 
 99 | ```bash
100 | # 获取 源和开发依赖.
101 | git clone --recurse-submodules https://github.com/denoland/deno.git
102 | cd deno
103 | ./tools/setup.py
104 | 
105 | # 你可能需要确保 sccache 是在运行的。
106 | # (TODO 需要与否，其实并不明确.)
107 | # prebuilt/mac/sccache --start-server
108 | 
109 | # 构建.
110 | ./tools/build.py
111 | 
112 | # 运行.
113 | ./target/debug/deno tests/002_hello.ts
114 | 
115 | # 测试.
116 | ./tools/test.py
117 | 
118 | # 格式化代码.
119 | ./tools/format.py
120 | ```
121 | 
122 | #### 先决条件
123 | 
124 | 为了确保构建的可重复性，deno 在 git 子模块中有其大部分依赖项。但是，您需要单独安装：
125 | 
126 | 1.  [Rust](https://www.rust-lang.org/en-US/install.html)> 1.31.1
127 | 2.  [Node](https://nodejs.org/)
128 | 3.  Python 2。[不是 3](https://github.com/denoland/deno/issues/464#issuecomment-411795578).
129 | 
130 | Mac 用户的额外步骤：安装[XCode](https://developer.apple.com/xcode/) :(
131 | 
132 | Windows 用户的额外步骤：
133 | 
134 | 1.  添加`python.exe`到`PATH`（例如 `set PATH=%PATH%;C:\Python27\python.exe`）
135 | 2.  得到[VS Community 2017](https://www.visualstudio.com/downloads/)，随着"Desktop development with C++"工具包，并确保选择以下列出所有的 C++工具。
136 |     - Windows 10 SDK >= 10.0.17134
137 |     - X86 和 X64 的 Visual C++ ATL
138 |     - X86 和 X64 的 Visual C++ MFC
139 |     - C++ profiling 工具
140 | 3.  启用"Windows 调试工具"。转到"控制面板"→"程序"→"程序和功能"→ 选择"Windows 软件开发工具包-Windows 10"→"更改"→"更改"→ 检查"Windows 调试工具"→"更改"->"完成"
141 | 
142 | > ("Control Panel" → "Programs" → "Programs and Features" → Select "Windows Software >Development Kit - Windows 10" →
143 | > "Change" → "Change" → Check "Debugging Tools >For Windows" → "Change" -> "Finish")。
144 | 
145 | 4.  确保使用的是 Git 2.19.2.Windows.1 或更高版本。
146 | 
147 | #### 其他有用的命令
148 | 
149 | ```bash
150 | # 手动呼叫 ninja。
151 | ./third_party/depot_tools/ninja -C target/debug
152 | 
153 | # 构建发布二进制文件。
154 | ./tools/build.py --release deno
155 | 
156 | # 列出可执行目标。
157 | ./third_party/depot_tools/gn ls target/debug //:* --as=output --type=executable
158 | 
159 | # 列表构建配置。
160 | ./third_party/depot_tools/gn args target/debug/ --list
161 | 
162 | # 编辑构建配置。
163 | ./third_party/depot_tools/gn args target/debug/
164 | 
165 | # 描述一个目标。
166 | ./third_party/depot_tools/gn desc target/debug/ :deno
167 | ./third_party/depot_tools/gn help
168 | 
169 | # 更新third_party模块
170 | git submodule update
171 | ```
172 | 
173 | 环境变量：`DENO_BUILD_MODE`，`DENO_BUILD_PATH`，`DENO_BUILD_ARGS`，`DENO_DIR`。
174 | 
175 | ## API 参考
176 | 
177 | ### deno --types
178 | 
179 | 要获得 Deno 运行时，准确的 API 参考，请在命令行中，运行以下命令：
180 | 
181 | ```shellsession
182 | $ deno --types
183 | ```
184 | 
185 | [这就是输出的样子。](https://gist.github.com/ry/46da4724168cdefa763e13207d27ede5)
186 | 
187 | ### 参考网站
188 | 
189 | [TypeScript Deno api](https://deno.land/typedoc/index.html)。
190 | 
191 | 如果要在 Rust 程序中，嵌入 deno，请参见[Rust Deno API](https://deno.land/rustdoc/deno/index.html)。
192 | 
193 | ## 实例
194 | 
195 | ### Unix "cat"程序的实现
196 | 
197 | 在这个程序中，每个命令行参数，都被假定为文件名，文件被打开，并打印到 stdout。
198 | 
199 | ```ts
200 | (async () => {
201 |   for (let i = 1; i < Deno.args.length; i++) {
202 |     let filename = Deno.args[i];
203 |     let file = await Deno.open(filename);
204 |     await Deno.copy(Deno.stdout, file);
205 |     file.close();
206 |   }
207 | })();
208 | ```
209 | 
210 | 这个`copy()`函数，实际上只做了，必要的内核->用户空间->内核副本。也就是说，从文件读取来的数据的相同内存，被写入 stdout。这说明了 deno 中，关于 I/O 流的通用设计目标。
211 | 
212 | 尝试程序：
213 | 
214 | ```shellsession
215 | $ deno --allow-read https://deno.land/std/examples/cat.ts /etc/passwd
216 | ```
217 | 
218 | ### TCP 回音服务器
219 | 
220 | 这是一个简单服务器的例子，它接受端口 8080 上的连接，并将它发送的任何内容，返回给客户端。
221 | 
222 | ```ts
223 | const {listen, copy} = Deno;
224 | 
225 | (async () => {
226 |   const addr = '0.0.0.0:8080';
227 |   const listener = listen('tcp', addr);
228 |   console.log('listening on', addr);
229 |   while (true) {
230 |     const conn = await listener.accept();
231 |     copy(conn, conn);
232 |   }
233 | })();
234 | ```
235 | 
236 | 启动此程序时，将提示用户，要有在网络上侦听的权限：
237 | 
238 | ```shellsession
239 | $ deno https://deno.land/std/examples/echo_server.ts
240 | ⚠️  Deno requests network access to "listen". Grant? [yN] y
241 | listening on 0.0.0.0:8080
242 | ```
243 | 
244 | 出于安全原因，Deno 不允许程序，在没有明确许可的情况下访问网络。要避免控制台提示，请使用命令行标志：
245 | 
246 | ```shellsession
247 | $ deno https://deno.land/std/examples/echo_server.ts --allow-net
248 | ```
249 | 
250 | 要测试它，请尝试使用 curl 向它发送 HTTP 请求。请求会被直接写回客户端。
251 | 
252 | ```shellsession
253 | $ curl http://localhost:8080/
254 | GET / HTTP/1.1
255 | Host: localhost:8080
256 | User-Agent: curl/7.54.0
257 | Accept: */*
258 | ```
259 | 
260 | 值得注意的是，类似`cat.ts`那个例子，这里的`copy()`函数，也不会进行不必要的内存复制。它从内核接收一个数据包，并发送回来，没有进一步的复杂性。
261 | 
262 | ### 检查和撤消权限
263 | 
264 | 有时程序可能希望撤消以前授予的权限。当程序在后期需要这些权限时，则向用户显示一个新的提示。
265 | 
266 | ```ts
267 | const {permissions, revokePermission, open, remove} = Deno;
268 | 
269 | (async () => {
270 |   // 查看一个权限
271 |   if (!permissions().write) {
272 |     throw new Error('need write permission');
273 |   }
274 | 
275 |   const log = await open('request.log', 'a+');
276 | 
277 |   // 撤消一些权限
278 |   revokePermission('read');
279 |   revokePermission('write');
280 | 
281 |   // 使用 log file
282 |   await log.write(encoder.encode('hello\n'));
283 | 
284 |   // 然后提示需要 write 权限或者失败。
285 |   await remove('request.log');
286 | })();
287 | ```
288 | 
289 | ### 文件服务器
290 | 
291 | 这一个在 HTTP 中，提供服务的本地目录。
292 | 
293 | ```bash
294 | alias file_server="deno  --allow-net --allow-read \
295 |   https://deno.land/std/http/file_server.ts"
296 | ```
297 | 
298 | 运行它：
299 | 
300 | ```shellsession
301 | $ file_server .
302 | Downloading https://deno.land/std/http/file_server.ts...
303 | [...]
304 | HTTP server listening on http://0.0.0.0:4500/
305 | ```
306 | 
307 | 如果您想升级到，最新发布的版本：
308 | 
309 | ```shellsession
310 | $ file_server --reload
311 | ```
312 | 
313 | ### 运行子过程
314 | 
315 | [API 参考](https://deno.land/typedoc/index.html#run)
316 | 
317 | 例子：
318 | 
319 | ```ts
320 | async function main() {
321 |   // 创建子进程
322 |   const p = Deno.run({
323 |     args: ['echo', 'hello']
324 |   });
325 | 
326 |   // await(等待) 完成
327 |   await p.status();
328 | }
329 | 
330 | main();
331 | ```
332 | 
333 | 运行它：
334 | 
335 | ```shellsession
336 | $ deno --allow-run ./subprocess_simple.ts
337 | hello
338 | ```
339 | 
340 | 默认情况下，`Deno.run()`的子进程，会继承父进程的`stdin`，`stdout`和`stdout`。如果要与已启动的子进程通信，可以使用`"piped"`选项。
341 | 
342 | ```ts
343 | async function main() {
344 |   const decoder = new TextDecoder();
345 | 
346 |   const fileNames = Deno.args.slice(1);
347 | 
348 |   const p = Deno.run({
349 |     args: [
350 |       'deno',
351 |       '--allow-read',
352 |       'https://deno.land/std/examples/cat.ts',
353 |       ...fileNames
354 |     ],
355 |     stdout: 'piped',
356 |     stderr: 'piped'
357 |   });
358 | 
359 |   const {code} = await p.status();
360 | 
361 |   if (code === 0) {
362 |     const rawOutput = await p.output();
363 |     Deno.stdout.write(rawOutput);
364 |   } else {
365 |     const rawError = await p.stderrOutput();
366 |     Deno.stdout.write(rawError);
367 |   }
368 | 
369 |   Deno.exit(code);
370 | }
371 | 
372 | main();
373 | ```
374 | 
375 | 运行时：
376 | 
377 | ```shellsession
378 | $ deno ./subprocess.ts --allow-run <somefile>
379 | [file content]
380 | 
381 | $ deno ./subprocess.ts --allow-run non_existent_file.md
382 | 
383 | Uncaught NotFound: No such file or directory (os error 2)
384 |     at DenoError (deno/js/errors.ts:19:5)
385 |     at maybeError (deno/js/errors.ts:38:12)
386 |     at handleAsyncMsgFromRust (deno/js/dispatch.ts:27:17)
387 | ```
388 | 
389 | ### 链接到第三方代码
390 | 
391 | 在上面的例子中，我们看到了 deno 可以用 URL 执行脚本。和浏览器 javascript 一样，deno 可以直接用 URL 导入库。此示例使用 URL 导入，测试运行程序库：
392 | 
393 | ```ts
394 | import {test, runIfMain} from 'https://deno.land/std/testing/mod.ts';
395 | import {assertEquals} from 'https://deno.land/std/testing/asserts.ts';
396 | 
397 | test(function t1() {
398 |   assertEquals('hello', 'hello');
399 | });
400 | 
401 | test(function t2() {
402 |   assertEquals('world', 'world');
403 | });
404 | 
405 | runIfMain(import.meta);
406 | ```
407 | 
408 | 尝试运行此：
409 | 
410 | ```shellsession
411 | $ deno test.ts
412 | running 2 tests
413 | test t1 ... ok
414 | test t2 ... ok
415 | 
416 | test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out
417 | ```
418 | 
419 | 注意，我们不必提供`--allow-net`此程序的标志，但它访问了网络。事实上，Deno 运行时具有，下载导入(文件)，并将其缓存到磁盘的特殊访问权。
420 | 
421 | deno 将远程导入，缓存到`$DENO_DIR`环境变量。如果`$DENO_DIR`未指定。下次运行程序时，将不会进行下载。如果程序没有更改，也不会重新编译。默认目录为：
422 | 
423 | - 在 Linux/Redox：`$XDG_CACHE_HOME/deno`或`$HOME/.cache/deno`
424 | - 在 Windows 上：`%LOCALAPPDATA%/deno`（`%LOCALAPPDATA%` = `FOLDERID_LocalAppData`）
425 | - 在 MaOS:`$HOME/Library/Caches/deno`
426 | - 如果某件事失败了，它会回到`$HOME/.deno`
427 | 
428 | **但是如果`https://deno.land/`失联了？**依赖外部服务器便于开发，但在生产环境中，却很脆弱。生产软件应始终捆绑其依赖项。具体在 deno 的操作是，通过让`$DENO_DIR`，搭上你的源代码管理系统，把运行时的`$DENO_DIR`环境变量，指定为该路径。
429 | 
430 | **如何导入到特定版本？**只需在 URL 中,指定版本。例如，此 URL 完全指定，正在运行的代码：`https://unpkg.com/liltest@0.0.5/dist/liltest.js`。 结合上述在生产环境，设置`$DENO_DIR`，来存储代码的方式，你可以完全指定，要运行的确切代码，还可以在没有网络访问的情况下，执行代码。
431 | 
432 | **在任何地方导入 URL 似乎都不方便。如果其中一个 URL ，链接到了一个稍微不同的库版本呢？在大型项目中，维护 URL 是否容易出错？**解决方案是在中心`deps.ts`文件，导入和重新导出外部库（与 Node 的`package.json`文件目的相同）。例如，假设您在一个大型项目中，使用了上述测试库。要做的，不是在任何地方导入`"https://deno.land/std/testing/mod.ts"`，而是可以创建一个`deps.ts`，用来导出第三方代码：
433 | 
434 | ```ts
435 | export {test, assertEquals} from 'https://deno.land/std/testing/mod.ts';
436 | ```
437 | 
438 | 在整个项目中，都可以从`deps.ts`导入，这样就可以避免对同一个 URL 进行多次引用：
439 | 
440 | ```ts
441 | import {test, assertEquals} from './deps.ts';
442 | ```
443 | 
444 | 这种设计避免了，由于包管理软件、集中的代码库和多余的文件格式，而产生的过多复杂性。
445 | 
446 | ### 测试当前文件，是否为主程序
447 | 
448 | 通过检查`import.meta.main`，测测当前脚本，是否已作为程序的主输入执行。
449 | 
450 | ```ts
451 | if (import.meta.main) {
452 |   console.log('main');
453 | }
454 | ```
455 | 
456 | ## 命令行界面
457 | 
458 | ### 标志
459 | 
460 | ```shellsession
461 | $ deno -h
462 | deno
463 | 
464 | USAGE:
465 |     deno_dev [FLAGS] [OPTIONS] [SUBCOMMAND]
466 | 
467 | FLAGS:
468 |     -A, --allow-all        允许所有权限
469 |         --allow-env        允许环境访问
470 |         --allow-net        允许网络访问
471 |         --allow-read       允许文件系统读访问权限
472 |         --allow-run        允许运行子进程
473 |         --allow-write      允许文件系统写访问权限
474 |     -h, --help             打印帮助信息
475 |     -D, --log-debug        记录调试输出
476 |         --no-prompt        不要使用提示
477 |         --prefetch         预取依赖项
478 |     -r, --reload           重新加载源代码缓存（重新编译 TypeScript）
479 |         --types            打印运行时的 TypeScript 声明
480 |         --v8-options       打印 V8 命令行选项
481 |     -v, --version          打印版本
482 | 
483 | OPTIONS:
484 |         --v8-flags=<v8-flags>    设置V8命令行选项
485 | 
486 | SUBCOMMANDS(子命令):
487 |     <script>    要运行的脚本
488 |     fmt         格式化文件
489 |     info        显示源文件相关信息
490 | 
491 | ENVIRONMENT VARIABLES(环境变量):
492 |     DENO_DIR        设置 deno 的地基目录
493 |     NO_COLOR        设置为，禁用颜色
494 | ```
495 | 
496 | ### 环境变量
497 | 
498 | 有几个环境变量，控制着 deno 的行为：
499 | 
500 | `DENO_DIR`默认为`$HOME/.deno`，但也可以设置为任何路径。它控制着生成和缓存的源代码的写入和读取位置。
501 | 
502 | 如果`NO_COLOR`设置了，将关闭颜色输出。见[https://no-color.org/](https://no-color.org/)。 不用`--allow-env`标志，用户代码通过使用`Deno.noColor`(布尔类型)，就可以测测`NO_COLOR`是否设置了。
503 | 
504 | ### V8 标志
505 | 
506 | V8 有许多内部命令行标志，您可以使用`--v8-options`。 [看起来像这样。](https://gist.github.com/ry/1c5b080dcbdc6367e5612392049c9ee7)
507 | 
508 | 特别有用的：
509 | 
510 | ```
511 | --async-stack-trace
512 | ```
513 | 
514 | ## 内部详细信息
515 | 
516 | ### deno 和 linux 的类比
517 | 
518 | |                               **Linux** | **Deno**                          |
519 | | --------------------------------------: | :-------------------------------- |
520 | |                         Processes(进程) | Web Workers                       |
521 | |                      Syscalls(系统调用) | Ops                               |
522 | |       File descriptors(文件描述符) (fd) | [Resource(资源) ids (rid)](#资源) |
523 | |                     Scheduler(调度程序) | Tokio                             |
524 | | Userland(用户层): libc++ / glib / boost | deno_std                          |
525 | |                         /proc/\$\$/stat | [Deno.metrics()](#metrics)        |
526 | |                               man pages | deno --types                      |
527 | 
528 | #### 资源
529 | 
530 | 资源(Resource)（也称为 `rid`），是 deno 版本的文件描述符。它们是整数值，是对打开的文件、套接字和其他概念的引用(/指向)。对于测试来说挺好的，因为能够查询到，系统现在有多少开放资源。
531 | 
532 | ```ts
533 | const {resources, close} = Deno;
534 | console.log(resources());
535 | // output like: { 0: "stdin", 1: "stdout", 2: "stderr", 3: "repl" }
536 | 
537 | // close resource by rid
538 | close(3);
539 | ```
540 | 
541 | #### metrics
542 | 
543 | metrics(指标) 是 deno 的内部计数器，针对各种静态。
544 | 
545 | ```shellsession
546 | > console.table(Deno.metrics())
547 | ┌──────────────────┬────────┐
548 | │     (index)      │ Values │
549 | ├──────────────────┼────────┤
550 | │  opsDispatched   │   9    │
551 | │   opsCompleted   │   9    │
552 | │ bytesSentControl │  504   │
553 | │  bytesSentData   │   0    │
554 | │  bytesReceived   │  856   │
555 | └──────────────────┴────────┘
556 | ```
557 | 
558 | ### 示意图
559 | 
560 | <img src="images/schematic_v0.2.png">
561 | 
562 | ### 分析
563 | 
564 | 要开始分析，
565 | 
566 | ```sh
567 | # 确保我们只是构建发布(release)版本。
568 | # 构建 deno 和 V8 的 d8。
569 | ./tools/build.py --release d8 deno
570 | # 我们想要程序使用 --prof，进行基准测试
571 | ./target/release/deno tests/http_bench.ts --allow-net --prof &
572 | # 练练吧
573 | third_party/wrk/linux/wrk http://localhost:4500/
574 | kill `pgrep deno`
575 | ```
576 | 
577 | V8 将在当前目录中，写入如下文件：`isolate-0x7fad98242400-v8.log`。 要检查此文件：
578 | 
579 | ```sh
580 | D8_PATH=target/release/ ./third_party/v8/tools/linux-tick-processor
581 | isolate-0x7fad98242400-v8.log > prof.log
582 | # 在 macOS 上，请改用 ./third_party/v8/tools/mac-tick-processor
583 | ```
584 | 
585 | `prof.log`将包含，有关不同调用的 tick 分布的信息。
586 | 
587 | 要使用 Web UI ，查看日志，请生成日志的 JSON 文件：
588 | 
589 | ```sh
590 | D8_PATH=target/release/ ./third_party/v8/tools/linux-tick-processor
591 | isolate-0x7fad98242400-v8.log --preprocess > prof.json
592 | ```
593 | 
594 | 正常在浏览器中，打开`third_party/v8/tools/profview/index.html`，选择`prof.json`，以图形方式查看分布。
595 | 
596 | 了解`d8`和分析的更多信息，查看以下链接：
597 | 
598 | - <https://v8.dev/docs/d8>
599 | - [https://v8.dev/docs/profile/](https://v8.dev/docs/profile)
600 | 
601 | ### 用 LLDB 调试
602 | 
603 | 我们可以使用 LLDB 来调试 deno。
604 | 
605 | ```shellsession
606 | $ lldb -- target/debug/deno tests/worker.js
607 | > run
608 | > bt
609 | > up
610 | > up
611 | > l
612 | ```
613 | 
614 | 要调试 Rust 代码，我们可以使用`rust-lldb`。 它应该跟着`rustc`一起安装的，是一个围绕 LLDB 的包装器。
615 | 
616 | ```shellsession
617 | $ rust-lldb -- ./target/debug/deno tests/http_bench.ts --allow-net
618 | # On macOS, you might get warnings like
619 | # `ImportError: cannot import name _remove_dead_weakref`
620 | # In that case, use system python by setting PATH, e.g.
621 | # PATH=/System/Library/Frameworks/Python.framework/Versions/2.7/bin:$PATH
622 | (lldb) command script import "/Users/kevinqian/.rustup/toolchains/1.30.0-x86_64-apple-darwin/lib/rustlib/etc/lldb_rust_formatters.py"
623 | (lldb) type summary add --no-value --python-function lldb_rust_formatters.print_val -x ".*" --category Rust
624 | (lldb) type category enable Rust
625 | (lldb) target create "../deno/target/debug/deno"
626 | Current executable set to '../deno/target/debug/deno' (x86_64).
627 | (lldb) settings set -- target.run-args  "tests/http_bench.ts" "--allow-net"
628 | (lldb) b op_start
629 | (lldb) r
630 | ```
631 | 
632 | ### Deno 核心
633 | 
634 | DENO 的 core(核心) 绑定层。它作为一个[独立箱子](https://crates.io/crates/deno)发布。 核心内部是 V8 本身，一个名为"libdeno"的绑定 API。有关更多详细信息，请参阅该箱子的文档。
635 | 
636 | ### Flatbuffers
637 | 
638 | 我们使用 flatbuffers 定义 typescript 和 rust 之间的，公共结构和枚举。这些常见的数据结构，定义在[msg.fbs](https://github.com/denoland/deno/blob/master/cli/msg.fbs)
639 | 
640 | ### 更新预构建的二进制文件
641 | 
642 | ```shellsession
643 | $ ./third_party/depot_tools/upload_to_google_storage.py -b denoland  \
644 |   -e ~/.config/gcloud/legacy_credentials/ry@tinyclouds.org/.boto `which sccache`
645 | $ mv `which sccache`.sha1 prebuilt/linux64/
646 | $ gsutil acl ch -u AllUsers:R gs://denoland/608be47bf01004aa11d4ed06955414e93934516e
647 | ```
648 | 
649 | ### 连续基准
650 | 
651 | [在这里](https://deno.land/benchmarks.html)，看看我们的基准
652 | 
653 | 基准图表假设`//website/data.json`有`BenchmarkData[]`类型，这里的`BenchmarkData`定义如下：
654 | 
655 | ```ts
656 | interface ExecTimeData {
657 |   mean: number;
658 |   stddev: number;
659 |   user: number;
660 |   system: number;
661 |   min: number;
662 |   max: number;
663 | }
664 | 
665 | interface BenchmarkData {
666 |   created_at: string;
667 |   sha1: string;
668 |   benchmark: {
669 |     [key: string]: ExecTimeData;
670 |   };
671 |   binarySizeData: {
672 |     [key: string]: number;
673 |   };
674 |   threadCountData: {
675 |     [key: string]: number;
676 |   };
677 |   syscallCountData: {
678 |     [key: string]: number;
679 |   };
680 | }
681 | ```
682 | 
683 | ### Logos
684 | 
685 | 这些 deno 徽标，像 deno 软件一样，是在 MIT 许可证（公共域和免费使用）下发布的。
686 | 
687 | - [由 @ry 亲手画的](https://github.com/denoland/deno/blob/master/website/images/deno_logo.png)
688 | 
689 | - [由 @hashrock 制作的动画](https://github.com/denolib/animated-deno-logo/)
690 | 
691 | - [由 @kevinkassimo 提供的高分辨率 SVG](https://github.com/denolib/high-res-deno-logo)
692 | 
693 | ## 贡献
694 | 
695 | [风格指南](style_guide.html)
696 | 
697 | [在这里](https://github.com/denoland/deno/milestones)，跟踪未来版本的进展。
698 | 
699 | 请不要把[基准](https://deno.land/benchmarks.html)，搞得一团糟。
700 | 
701 | 在[社区聊天室](https://gitter.im/denolife/Lobby)，寻求帮助。
702 | 
703 | 如果您要处理某个问题，在你开始着手解决这个问题*之前*，请在问题评论中提及。
704 | 
705 | ### 提交 PR
706 | 
707 | 提交前，请确保完成以下操作：
708 | 
709 | 1.  有一个相关的问题，它在 PR 文本中,被引用。
710 | 2.  有一些测试可以覆盖这些更改。
711 | 3.  确保`./tools/test.py`成功。
712 | 4.  使用`tools/format.py`格式化代码。
713 | 5.  确保`./tools/lint.py`成功。
714 | 
715 | ### `third_party`的改变
716 | 
717 | [`deno_third_party`](https://github.com/denoland/deno_third_party)包含 deno 所依赖的大部分外部代码，这样我们就可以准确地知道，在任何给定时间执行的是什么。它是由人工和个人脚本，混合而成的，经过仔细维护。您可能需要 @ry 或 @pissisaureus 的帮助来进行更改。
718 | 
719 | ### 添加 Ops（即绑定）
720 | 
721 | 我们非常担心在添加新的 API 时出错。在 Deno 中添加一个 Op 时，需要研究其他平台上的对应接口。请列出如何在 go、node、rust 和 python 中完成此功能。
722 | 
723 | 例如，请参见被提议的`Deno.rename()`，并最终在[PR #671](https://github.com/denoland/deno/pull/671)加入。
724 | 
725 | ### 文档化 API
726 | 
727 | 记录公有 API 是很重要的，我们希望在代码中这样做。这有助于确保代码和文档紧密耦合在一起。
728 | 
729 | #### 利用 JSDoc
730 | 
731 | 所有公有的 API 和类型，都需要`deno`模块，还有 global/`window`命名空间的 JSDoc 文档。这些文档会被 typescript 编译器解析，并使用，因此，很容易提供给下游。JSDoc 代码块(注释定义)正好，位于它们应用的语句之前，并用`/**`前缀和`*/`结尾表示。 例如：
732 | 
733 | ```ts
734 | /** 一个简单 的 JSDoc z */
735 | export const FOO = 'foo'; // 应用的语句
736 | ```
737 | 


--------------------------------------------------------------------------------
/manual.zh.md:
--------------------------------------------------------------------------------
  1 | # Deno 手册
  2 | 
  3 | <!-- START doctoc generated TOC please keep comment here to allow auto update -->
  4 | <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
  5 | 
  6 | 
  7 | - [免责声明](#%E5%85%8D%E8%B4%A3%E5%A3%B0%E6%98%8E)
  8 | - [介绍](#%E4%BB%8B%E7%BB%8D)
  9 |   - [哲学](#%E5%93%B2%E5%AD%A6)
 10 |   - [目标](#%E7%9B%AE%E6%A0%87)
 11 |   - [反目标](#%E5%8F%8D%E7%9B%AE%E6%A0%87)
 12 | - [安装程序](#%E5%AE%89%E8%A3%85%E7%A8%8B%E5%BA%8F)
 13 |   - [二进制安装](#%E4%BA%8C%E8%BF%9B%E5%88%B6%E5%AE%89%E8%A3%85)
 14 |   - [从源代码生成](#%E4%BB%8E%E6%BA%90%E4%BB%A3%E7%A0%81%E7%94%9F%E6%88%90)
 15 |     - [先决条件](#%E5%85%88%E5%86%B3%E6%9D%A1%E4%BB%B6)
 16 |     - [其他有用的命令](#%E5%85%B6%E4%BB%96%E6%9C%89%E7%94%A8%E7%9A%84%E5%91%BD%E4%BB%A4)
 17 | - [API 参考](#api-%E5%8F%82%E8%80%83)
 18 |   - [deno --types](#deno---types)
 19 |   - [参考网站](#%E5%8F%82%E8%80%83%E7%BD%91%E7%AB%99)
 20 | - [实例](#%E5%AE%9E%E4%BE%8B)
 21 |   - [Unix "cat"程序的实现](#unix-cat%E7%A8%8B%E5%BA%8F%E7%9A%84%E5%AE%9E%E7%8E%B0)
 22 |   - [TCP 回音服务器](#tcp-%E5%9B%9E%E9%9F%B3%E6%9C%8D%E5%8A%A1%E5%99%A8)
 23 |   - [检查和撤消权限](#%E6%A3%80%E6%9F%A5%E5%92%8C%E6%92%A4%E6%B6%88%E6%9D%83%E9%99%90)
 24 |   - [文件服务器](#%E6%96%87%E4%BB%B6%E6%9C%8D%E5%8A%A1%E5%99%A8)
 25 |   - [运行子过程](#%E8%BF%90%E8%A1%8C%E5%AD%90%E8%BF%87%E7%A8%8B)
 26 |   - [链接到第三方代码](#%E9%93%BE%E6%8E%A5%E5%88%B0%E7%AC%AC%E4%B8%89%E6%96%B9%E4%BB%A3%E7%A0%81)
 27 |   - [测试当前文件，是否为主程序](#%E6%B5%8B%E8%AF%95%E5%BD%93%E5%89%8D%E6%96%87%E4%BB%B6%E6%98%AF%E5%90%A6%E4%B8%BA%E4%B8%BB%E7%A8%8B%E5%BA%8F)
 28 | - [命令行界面](#%E5%91%BD%E4%BB%A4%E8%A1%8C%E7%95%8C%E9%9D%A2)
 29 |   - [标志](#%E6%A0%87%E5%BF%97)
 30 |   - [环境变量](#%E7%8E%AF%E5%A2%83%E5%8F%98%E9%87%8F)
 31 |   - [V8 标志](#v8-%E6%A0%87%E5%BF%97)
 32 | - [内部详细信息](#%E5%86%85%E9%83%A8%E8%AF%A6%E7%BB%86%E4%BF%A1%E6%81%AF)
 33 |   - [deno 和 linux 的类比](#deno-%E5%92%8C-linux-%E7%9A%84%E7%B1%BB%E6%AF%94)
 34 |     - [资源](#%E8%B5%84%E6%BA%90)
 35 |     - [metrics](#metrics)
 36 |   - [示意图](#%E7%A4%BA%E6%84%8F%E5%9B%BE)
 37 |   - [分析](#%E5%88%86%E6%9E%90)
 38 |   - [用 LLDB 调试](#%E7%94%A8-lldb-%E8%B0%83%E8%AF%95)
 39 |   - [Deno 核心](#deno-%E6%A0%B8%E5%BF%83)
 40 |   - [Flatbuffers](#flatbuffers)
 41 |   - [更新预构建的二进制文件](#%E6%9B%B4%E6%96%B0%E9%A2%84%E6%9E%84%E5%BB%BA%E7%9A%84%E4%BA%8C%E8%BF%9B%E5%88%B6%E6%96%87%E4%BB%B6)
 42 |   - [连续基准](#%E8%BF%9E%E7%BB%AD%E5%9F%BA%E5%87%86)
 43 |   - [Logos](#logos)
 44 | - [贡献](#%E8%B4%A1%E7%8C%AE)
 45 |   - [提交 PR](#%E6%8F%90%E4%BA%A4-pr)
 46 |   - [`third_party`的改变](#third_party%E7%9A%84%E6%94%B9%E5%8F%98)
 47 |   - [添加 Ops（即绑定）](#%E6%B7%BB%E5%8A%A0-ops%E5%8D%B3%E7%BB%91%E5%AE%9A)
 48 |   - [文档化 API](#%E6%96%87%E6%A1%A3%E5%8C%96-api)
 49 |     - [利用 JSDoc](#%E5%88%A9%E7%94%A8-jsdoc)
 50 | 
 51 | <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 52 | 
 53 | ## 免责声明
 54 | 
 55 | 警告语：Deno 正在开发中。我们鼓励勇敢的早期采用者，但期望反馈大或小的 Bug。API 如有变更，恕不另行通知。[错误报告](https://github.com/denoland/deno/issues)会有用！
 56 | 
 57 | ## 介绍
 58 | 
 59 | 使用 V8、Rust 和 Tokio 构建的安全 javascript/typescript 运行时
 60 | 
 61 | ### 哲学
 62 | 
 63 | Deno 的目标是为现代程序员提供一个高效、安全的脚本环境。
 64 | 
 65 | 它始终以单个可执行文件形态，作为分发文件，并且该可执行文件，足够运行任何 deno 程序。给定一个 deno 程序的 URL，您应该能够用不超过 50MB 的 Deno 可执行文件，来执行它。
 66 | 
 67 | Deno 明确承担运行时，和包管理器的角色。它用标准的浏览器兼容协议，来加载模块：URLs。
 68 | 
 69 | Deno 为提供了程序访问系统的安全保证，默认情况下，它是最严格的安全沙盒。
 70 | 
 71 | Deno 提供<a href="https://github.com/denoland/deno_std">一套经过评审（审核）的标准模块</a>这保证了与 Deno 的合作。
 72 | 
 73 | ### 目标
 74 | 
 75 | - 支持现成的 typescript。
 76 | 
 77 | - 与浏览器一样，允许（模块）以 URL 形式导入：
 78 | 
 79 |   ```ts
 80 |   import * as log from 'https://deno.land/std/log/mod.ts';
 81 |   ```
 82 | 
 83 | - 远程代码在第一次执行时，被获取和缓存，并且在使用`--reload`标志，才会更新(同一 URL 路径的代码)。（所以，还能在飞机上使用。见`~/.deno/src`，有关缓存的详细信息。）
 84 | 
 85 | - 使用"ES 模块"，不支持`require()`.
 86 | 
 87 | - 为了沙盒代码的运行，会对文件系统和网络访问(权限)有所控制。V8（没权限）和 Rust（权限）之间的访问，只能通过在[flatbuffer](https://github.com/denoland/deno/blob/master/cli/msg.fbs)定义的序列化消息，完成沟通。这使得审计变得容易。例如，要启用 write(写) 访问，请使用标志`--allow-write`，或用于网络访问`--allow-net`。
 88 | 
 89 | - 只运输一个可执行文件。
 90 | 
 91 | - 总是死(崩溃)于，未发现的错误。
 92 | 
 93 | - 浏览器兼容：Deno 程序的子集，完全用 JavaScript 编写，它（或它的功能测试）并没有使用全局`Deno`名称空间，想来应该能够在现代 Web 浏览器上运行，而不需要更改。
 94 | 
 95 | - [目标：支持顶级`await`.](https://github.com/denoland/deno/issues/471)
 96 | 
 97 | - 能够高效地服务 HTTP。（[目前，速度比较慢。](https://deno.land/benchmarks.html#req-per-sec)）
 98 | 
 99 | - 提供现成的有用工具：
100 |   - 命令行调试器[还没有](https://github.com/denoland/deno/issues/1120)
101 |   - linter[还没有](https://github.com/denoland/deno/issues/1880)
102 |   - 依赖关系检查器（`deno info`）
103 |   - 代码格式化程序（`deno fmt`）
104 | 
105 | ### 反目标
106 | 
107 | - 没有`package.json`.
108 | 
109 | - 没有 npm。
110 | 
111 | - 与 Node 不显式兼容。
112 | 
113 | ## 安装程序
114 | 
115 | ### 二进制安装
116 | 
117 | Deno 在 OSX、Linux 和 Windows 上工作。deno 是单个二进制可执行文件。它没有外部依赖关系。
118 | 
119 | [deno_install](https://github.com/denoland/deno_install)提供方便的脚本，来下载和安装二进制文件。
120 | 
121 | 使用 Shell：
122 | 
123 | ```shellsession
124 | $ curl -fsSL https://deno.land/x/install/install.sh | sh
125 | ```
126 | 
127 | 使用 PowerShell:
128 | 
129 | ```shellsession
130 | > iwr https://deno.land/x/install/install.ps1 | iex
131 | ```
132 | 
133 | 使用[Scoop](https://scoop.sh/)（Windows）：
134 | 
135 | ```
136 | scoop install deno
137 | ```
138 | 
139 | 也可以通过[github.com/denoland/deno/releases](https://github.com/denoland/deno/releases)下载 tarball 或 zip 文件，手动安装 deno。这些包只包含一个可执行文件。您必须在 Mac 和 Linux 上，设置可执行的环境变量(PATH)。
140 | 
141 | 一旦它安装和已在`$PATH`，开始试试吧：
142 | 
143 | ```shellsession
144 | $ deno https://deno.land/welcome.ts
145 | ```
146 | 
147 | ### 从源代码生成
148 | 
149 | ```bash
150 | # 获取 源和开发依赖.
151 | git clone --recurse-submodules https://github.com/denoland/deno.git
152 | cd deno
153 | ./tools/setup.py
154 | 
155 | # 你可能需要确保 sccache 是在运行的。
156 | # (TODO 需要与否，其实并不明确.)
157 | # prebuilt/mac/sccache --start-server
158 | 
159 | # 构建.
160 | ./tools/build.py
161 | 
162 | # 运行.
163 | ./target/debug/deno tests/002_hello.ts
164 | 
165 | # 测试.
166 | ./tools/test.py
167 | 
168 | # 格式化代码.
169 | ./tools/format.py
170 | ```
171 | 
172 | #### 先决条件
173 | 
174 | 为了确保构建的可重复性，deno 在 git 子模块中有其大部分依赖项。但是，您需要单独安装：
175 | 
176 | 1.  [Rust](https://www.rust-lang.org/en-US/install.html)> 1.31.1
177 | 2.  [Node](https://nodejs.org/)
178 | 3.  Python 2。[不是 3](https://github.com/denoland/deno/issues/464#issuecomment-411795578).
179 | 
180 | Mac 用户的额外步骤：安装[XCode](https://developer.apple.com/xcode/) :(
181 | 
182 | Windows 用户的额外步骤：
183 | 
184 | 1.  添加`python.exe`到`PATH`（例如 `set PATH=%PATH%;C:\Python27\python.exe`）
185 | 2.  得到[VS Community 2017](https://www.visualstudio.com/downloads/)，随着"Desktop development with C++"工具包，并确保选择以下列出所有的 C++工具。
186 |     - Windows 10 SDK >= 10.0.17134
187 |     - X86 和 X64 的 Visual C++ ATL
188 |     - X86 和 X64 的 Visual C++ MFC
189 |     - C++ profiling 工具
190 | 3.  启用"Windows 调试工具"。转到"控制面板"→"程序"→"程序和功能"→ 选择"Windows 软件开发工具包-Windows 10"→"更改"→"更改"→ 检查"Windows 调试工具"→"更改"->"完成"
191 | 
192 | > ("Control Panel" → "Programs" → "Programs and Features" → Select "Windows Software >Development Kit - Windows 10" →
193 | > "Change" → "Change" → Check "Debugging Tools >For Windows" → "Change" -> "Finish")。
194 | 
195 | 4.  确保使用的是 Git 2.19.2.Windows.1 或更高版本。
196 | 
197 | #### 其他有用的命令
198 | 
199 | ```bash
200 | # 手动呼叫 ninja。
201 | ./third_party/depot_tools/ninja -C target/debug
202 | 
203 | # 构建发布二进制文件。
204 | ./tools/build.py --release deno
205 | 
206 | # 列出可执行目标。
207 | ./third_party/depot_tools/gn ls target/debug //:* --as=output --type=executable
208 | 
209 | # 列表构建配置。
210 | ./third_party/depot_tools/gn args target/debug/ --list
211 | 
212 | # 编辑构建配置。
213 | ./third_party/depot_tools/gn args target/debug/
214 | 
215 | # 描述一个目标。
216 | ./third_party/depot_tools/gn desc target/debug/ :deno
217 | ./third_party/depot_tools/gn help
218 | 
219 | # 更新third_party模块
220 | git submodule update
221 | ```
222 | 
223 | 环境变量：`DENO_BUILD_MODE`，`DENO_BUILD_PATH`，`DENO_BUILD_ARGS`，`DENO_DIR`。
224 | 
225 | ## API 参考
226 | 
227 | ### deno --types
228 | 
229 | 要获得 Deno 运行时，准确的 API 参考，请在命令行中，运行以下命令：
230 | 
231 | ```shellsession
232 | $ deno --types
233 | ```
234 | 
235 | [这就是输出的样子。](https://gist.github.com/ry/46da4724168cdefa763e13207d27ede5)
236 | 
237 | ### 参考网站
238 | 
239 | [TypeScript Deno api](https://deno.land/typedoc/index.html)。
240 | 
241 | 如果要在 Rust 程序中，嵌入 deno，请参见[Rust Deno API](https://deno.land/rustdoc/deno/index.html)。
242 | 
243 | ## 实例
244 | 
245 | ### Unix "cat"程序的实现
246 | 
247 | 在这个程序中，每个命令行参数，都被假定为文件名，文件被打开，并打印到 stdout。
248 | 
249 | ```ts
250 | (async () => {
251 |   for (let i = 1; i < Deno.args.length; i++) {
252 |     let filename = Deno.args[i];
253 |     let file = await Deno.open(filename);
254 |     await Deno.copy(Deno.stdout, file);
255 |     file.close();
256 |   }
257 | })();
258 | ```
259 | 
260 | 这个`copy()`函数，实际上只做了，必要的内核->用户空间->内核副本。也就是说，从文件读取来的数据的相同内存，被写入 stdout。这说明了 deno 中，关于 I/O 流的通用设计目标。
261 | 
262 | 尝试程序：
263 | 
264 | ```shellsession
265 | $ deno --allow-read https://deno.land/std/examples/cat.ts /etc/passwd
266 | ```
267 | 
268 | ### TCP 回音服务器
269 | 
270 | 这是一个简单服务器的例子，它接受端口 8080 上的连接，并将它发送的任何内容，返回给客户端。
271 | 
272 | ```ts
273 | const {listen, copy} = Deno;
274 | 
275 | (async () => {
276 |   const addr = '0.0.0.0:8080';
277 |   const listener = listen('tcp', addr);
278 |   console.log('listening on', addr);
279 |   while (true) {
280 |     const conn = await listener.accept();
281 |     copy(conn, conn);
282 |   }
283 | })();
284 | ```
285 | 
286 | 启动此程序时，将提示用户，要有在网络上侦听的权限：
287 | 
288 | ```shellsession
289 | $ deno https://deno.land/std/examples/echo_server.ts
290 | ⚠️  Deno requests network access to "listen". Grant? [yN] y
291 | listening on 0.0.0.0:8080
292 | ```
293 | 
294 | 出于安全原因，Deno 不允许程序，在没有明确许可的情况下访问网络。要避免控制台提示，请使用命令行标志：
295 | 
296 | ```shellsession
297 | $ deno https://deno.land/std/examples/echo_server.ts --allow-net
298 | ```
299 | 
300 | 要测试它，请尝试使用 curl 向它发送 HTTP 请求。请求会被直接写回客户端。
301 | 
302 | ```shellsession
303 | $ curl http://localhost:8080/
304 | GET / HTTP/1.1
305 | Host: localhost:8080
306 | User-Agent: curl/7.54.0
307 | Accept: */*
308 | ```
309 | 
310 | 值得注意的是，类似`cat.ts`那个例子，这里的`copy()`函数，也不会进行不必要的内存复制。它从内核接收一个数据包，并发送回来，没有进一步的复杂性。
311 | 
312 | ### 检查和撤消权限
313 | 
314 | 有时程序可能希望撤消以前授予的权限。当程序在后期需要这些权限时，则向用户显示一个新的提示。
315 | 
316 | ```ts
317 | const {permissions, revokePermission, open, remove} = Deno;
318 | 
319 | (async () => {
320 |   // 查看一个权限
321 |   if (!permissions().write) {
322 |     throw new Error('need write permission');
323 |   }
324 | 
325 |   const log = await open('request.log', 'a+');
326 | 
327 |   // 撤消一些权限
328 |   revokePermission('read');
329 |   revokePermission('write');
330 | 
331 |   // 使用 log file
332 |   await log.write(encoder.encode('hello\n'));
333 | 
334 |   // 然后提示需要 write 权限或者失败。
335 |   await remove('request.log');
336 | })();
337 | ```
338 | 
339 | ### 文件服务器
340 | 
341 | 这一个在 HTTP 中，提供服务的本地目录。
342 | 
343 | ```bash
344 | alias file_server="deno  --allow-net --allow-read \
345 |   https://deno.land/std/http/file_server.ts"
346 | ```
347 | 
348 | 运行它：
349 | 
350 | ```shellsession
351 | $ file_server .
352 | Downloading https://deno.land/std/http/file_server.ts...
353 | [...]
354 | HTTP server listening on http://0.0.0.0:4500/
355 | ```
356 | 
357 | 如果您想升级到，最新发布的版本：
358 | 
359 | ```shellsession
360 | $ file_server --reload
361 | ```
362 | 
363 | ### 运行子过程
364 | 
365 | [API 参考](https://deno.land/typedoc/index.html#run)
366 | 
367 | 例子：
368 | 
369 | ```ts
370 | async function main() {
371 |   // 创建子进程
372 |   const p = Deno.run({
373 |     args: ['echo', 'hello']
374 |   });
375 | 
376 |   // await(等待) 完成
377 |   await p.status();
378 | }
379 | 
380 | main();
381 | ```
382 | 
383 | 运行它：
384 | 
385 | ```shellsession
386 | $ deno --allow-run ./subprocess_simple.ts
387 | hello
388 | ```
389 | 
390 | 默认情况下，`Deno.run()`的子进程，会继承父进程的`stdin`，`stdout`和`stdout`。如果要与已启动的子进程通信，可以使用`"piped"`选项。
391 | 
392 | ```ts
393 | async function main() {
394 |   const decoder = new TextDecoder();
395 | 
396 |   const fileNames = Deno.args.slice(1);
397 | 
398 |   const p = Deno.run({
399 |     args: [
400 |       'deno',
401 |       '--allow-read',
402 |       'https://deno.land/std/examples/cat.ts',
403 |       ...fileNames
404 |     ],
405 |     stdout: 'piped',
406 |     stderr: 'piped'
407 |   });
408 | 
409 |   const {code} = await p.status();
410 | 
411 |   if (code === 0) {
412 |     const rawOutput = await p.output();
413 |     Deno.stdout.write(rawOutput);
414 |   } else {
415 |     const rawError = await p.stderrOutput();
416 |     Deno.stdout.write(rawError);
417 |   }
418 | 
419 |   Deno.exit(code);
420 | }
421 | 
422 | main();
423 | ```
424 | 
425 | 运行时：
426 | 
427 | ```shellsession
428 | $ deno ./subprocess.ts --allow-run <somefile>
429 | [file content]
430 | 
431 | $ deno ./subprocess.ts --allow-run non_existent_file.md
432 | 
433 | Uncaught NotFound: No such file or directory (os error 2)
434 |     at DenoError (deno/js/errors.ts:19:5)
435 |     at maybeError (deno/js/errors.ts:38:12)
436 |     at handleAsyncMsgFromRust (deno/js/dispatch.ts:27:17)
437 | ```
438 | 
439 | ### 链接到第三方代码
440 | 
441 | 在上面的例子中，我们看到了 deno 可以用 URL 执行脚本。和浏览器 javascript 一样，deno 可以直接用 URL 导入库。此示例使用 URL 导入，测试运行程序库：
442 | 
443 | ```ts
444 | import {test, runIfMain} from 'https://deno.land/std/testing/mod.ts';
445 | import {assertEquals} from 'https://deno.land/std/testing/asserts.ts';
446 | 
447 | test(function t1() {
448 |   assertEquals('hello', 'hello');
449 | });
450 | 
451 | test(function t2() {
452 |   assertEquals('world', 'world');
453 | });
454 | 
455 | runIfMain(import.meta);
456 | ```
457 | 
458 | 尝试运行此：
459 | 
460 | ```shellsession
461 | $ deno test.ts
462 | running 2 tests
463 | test t1 ... ok
464 | test t2 ... ok
465 | 
466 | test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out
467 | ```
468 | 
469 | 注意，我们不必提供`--allow-net`此程序的标志，但它访问了网络。事实上，Deno 运行时具有，下载导入(文件)，并将其缓存到磁盘的特殊访问权。
470 | 
471 | deno 将远程导入，缓存到`$DENO_DIR`环境变量。如果`$DENO_DIR`未指定。下次运行程序时，将不会进行下载。如果程序没有更改，也不会重新编译。默认目录为：
472 | 
473 | - 在 Linux/Redox：`$XDG_CACHE_HOME/deno`或`$HOME/.cache/deno`
474 | - 在 Windows 上：`%LOCALAPPDATA%/deno`（`%LOCALAPPDATA%` = `FOLDERID_LocalAppData`）
475 | - 在 MaOS:`$HOME/Library/Caches/deno`
476 | - 如果某件事失败了，它会回到`$HOME/.deno`
477 | 
478 | **但是如果`https://deno.land/`失联了？**依赖外部服务器便于开发，但在生产环境中，却很脆弱。生产软件应始终捆绑其依赖项。具体在 deno 的操作是，通过让`$DENO_DIR`，搭上你的源代码管理系统，把运行时的`$DENO_DIR`环境变量，指定为该路径。
479 | 
480 | **如何导入到特定版本？**只需在 URL 中,指定版本。例如，此 URL 完全指定，正在运行的代码：`https://unpkg.com/liltest@0.0.5/dist/liltest.js`。 结合上述在生产环境，设置`$DENO_DIR`，来存储代码的方式，你可以完全指定，要运行的确切代码，还可以在没有网络访问的情况下，执行代码。
481 | 
482 | **在任何地方导入 URL 似乎都不方便。如果其中一个 URL ，链接到了一个稍微不同的库版本呢？在大型项目中，维护 URL 是否容易出错？**解决方案是在中心`deps.ts`文件，导入和重新导出外部库（与 Node 的`package.json`文件目的相同）。例如，假设您在一个大型项目中，使用了上述测试库。要做的，不是在任何地方导入`"https://deno.land/std/testing/mod.ts"`，而是可以创建一个`deps.ts`，用来导出第三方代码：
483 | 
484 | ```ts
485 | export {test, assertEquals} from 'https://deno.land/std/testing/mod.ts';
486 | ```
487 | 
488 | 在整个项目中，都可以从`deps.ts`导入，这样就可以避免对同一个 URL 进行多次引用：
489 | 
490 | ```ts
491 | import {test, assertEquals} from './deps.ts';
492 | ```
493 | 
494 | 这种设计避免了，由于包管理软件、集中的代码库和多余的文件格式，而产生的过多复杂性。
495 | 
496 | ### 测试当前文件，是否为主程序
497 | 
498 | 通过检查`import.meta.main`，测测当前脚本，是否已作为程序的主输入执行。
499 | 
500 | ```ts
501 | if (import.meta.main) {
502 |   console.log('main');
503 | }
504 | ```
505 | 
506 | ## 命令行界面
507 | 
508 | ### 标志
509 | 
510 | ```shellsession
511 | $ deno -h
512 | deno
513 | 
514 | USAGE:
515 |     deno_dev [FLAGS] [OPTIONS] [SUBCOMMAND]
516 | 
517 | FLAGS:
518 |     -A, --allow-all        允许所有权限
519 |         --allow-env        允许环境访问
520 |         --allow-net        允许网络访问
521 |         --allow-read       允许文件系统读访问权限
522 |         --allow-run        允许运行子进程
523 |         --allow-write      允许文件系统写访问权限
524 |     -h, --help             打印帮助信息
525 |     -D, --log-debug        记录调试输出
526 |         --no-prompt        不要使用提示
527 |         --prefetch         预取依赖项
528 |     -r, --reload           重新加载源代码缓存（重新编译 TypeScript）
529 |         --types            打印运行时的 TypeScript 声明
530 |         --v8-options       打印 V8 命令行选项
531 |     -v, --version          打印版本
532 | 
533 | OPTIONS:
534 |         --v8-flags=<v8-flags>    设置V8命令行选项
535 | 
536 | SUBCOMMANDS(子命令):
537 |     <script>    要运行的脚本
538 |     fmt         格式化文件
539 |     info        显示源文件相关信息
540 | 
541 | ENVIRONMENT VARIABLES(环境变量):
542 |     DENO_DIR        设置 deno 的地基目录
543 |     NO_COLOR        设置为，禁用颜色
544 | ```
545 | 
546 | ### 环境变量
547 | 
548 | 有几个环境变量，控制着 deno 的行为：
549 | 
550 | `DENO_DIR`默认为`$HOME/.deno`，但也可以设置为任何路径。它控制着生成和缓存的源代码的写入和读取位置。
551 | 
552 | 如果`NO_COLOR`设置了，将关闭颜色输出。见[https://no-color.org/](https://no-color.org/)。 不用`--allow-env`标志，用户代码通过使用`Deno.noColor`(布尔类型)，就可以测测`NO_COLOR`是否设置了。
553 | 
554 | ### V8 标志
555 | 
556 | V8 有许多内部命令行标志，您可以使用`--v8-options`。 [看起来像这样。](https://gist.github.com/ry/1c5b080dcbdc6367e5612392049c9ee7)
557 | 
558 | 特别有用的：
559 | 
560 | ```
561 | --async-stack-trace
562 | ```
563 | 
564 | ## 内部详细信息
565 | 
566 | ### deno 和 linux 的类比
567 | 
568 | |                               **Linux** | **Deno**                          |
569 | | --------------------------------------: | :-------------------------------- |
570 | |                         Processes(进程) | Web Workers                       |
571 | |                      Syscalls(系统调用) | Ops                               |
572 | |       File descriptors(文件描述符) (fd) | [Resource(资源) ids (rid)](#资源) |
573 | |                     Scheduler(调度程序) | Tokio                             |
574 | | Userland(用户层): libc++ / glib / boost | deno_std                          |
575 | |                         /proc/\$\$/stat | [Deno.metrics()](#metrics)        |
576 | |                               man pages | deno --types                      |
577 | 
578 | #### 资源
579 | 
580 | 资源(Resource)（也称为 `rid`），是 deno 版本的文件描述符。它们是整数值，是对打开的文件、套接字和其他概念的引用(/指向)。对于测试来说挺好的，因为能够查询到，系统现在有多少开放资源。
581 | 
582 | ```ts
583 | const {resources, close} = Deno;
584 | console.log(resources());
585 | // output like: { 0: "stdin", 1: "stdout", 2: "stderr", 3: "repl" }
586 | 
587 | // close resource by rid
588 | close(3);
589 | ```
590 | 
591 | #### metrics
592 | 
593 | metrics(指标) 是 deno 的内部计数器，针对各种静态。
594 | 
595 | ```shellsession
596 | > console.table(Deno.metrics())
597 | ┌──────────────────┬────────┐
598 | │     (index)      │ Values │
599 | ├──────────────────┼────────┤
600 | │  opsDispatched   │   9    │
601 | │   opsCompleted   │   9    │
602 | │ bytesSentControl │  504   │
603 | │  bytesSentData   │   0    │
604 | │  bytesReceived   │  856   │
605 | └──────────────────┴────────┘
606 | ```
607 | 
608 | ### 示意图
609 | 
610 | <img src="docs/images/schematic_v0.2.png">
611 | 
612 | ### 分析
613 | 
614 | 要开始分析，
615 | 
616 | ```sh
617 | # 确保我们只是构建发布(release)版本。
618 | # 构建 deno 和 V8 的 d8。
619 | ./tools/build.py --release d8 deno
620 | # 我们想要程序使用 --prof，进行基准测试
621 | ./target/release/deno tests/http_bench.ts --allow-net --prof &
622 | # 练练吧
623 | third_party/wrk/linux/wrk http://localhost:4500/
624 | kill `pgrep deno`
625 | ```
626 | 
627 | V8 将在当前目录中，写入如下文件：`isolate-0x7fad98242400-v8.log`。 要检查此文件：
628 | 
629 | ```sh
630 | D8_PATH=target/release/ ./third_party/v8/tools/linux-tick-processor
631 | isolate-0x7fad98242400-v8.log > prof.log
632 | # 在 macOS 上，请改用 ./third_party/v8/tools/mac-tick-processor
633 | ```
634 | 
635 | `prof.log`将包含，有关不同调用的 tick 分布的信息。
636 | 
637 | 要使用 Web UI ，查看日志，请生成日志的 JSON 文件：
638 | 
639 | ```sh
640 | D8_PATH=target/release/ ./third_party/v8/tools/linux-tick-processor
641 | isolate-0x7fad98242400-v8.log --preprocess > prof.json
642 | ```
643 | 
644 | 正常在浏览器中，打开`third_party/v8/tools/profview/index.html`，选择`prof.json`，以图形方式查看分布。
645 | 
646 | 了解`d8`和分析的更多信息，查看以下链接：
647 | 
648 | - <https://v8.dev/docs/d8>
649 | - [https://v8.dev/docs/profile/](https://v8.dev/docs/profile)
650 | 
651 | ### 用 LLDB 调试
652 | 
653 | 我们可以使用 LLDB 来调试 deno。
654 | 
655 | ```shellsession
656 | $ lldb -- target/debug/deno tests/worker.js
657 | > run
658 | > bt
659 | > up
660 | > up
661 | > l
662 | ```
663 | 
664 | 要调试 Rust 代码，我们可以使用`rust-lldb`。 它应该跟着`rustc`一起安装的，是一个围绕 LLDB 的包装器。
665 | 
666 | ```shellsession
667 | $ rust-lldb -- ./target/debug/deno tests/http_bench.ts --allow-net
668 | # On macOS, you might get warnings like
669 | # `ImportError: cannot import name _remove_dead_weakref`
670 | # In that case, use system python by setting PATH, e.g.
671 | # PATH=/System/Library/Frameworks/Python.framework/Versions/2.7/bin:$PATH
672 | (lldb) command script import "/Users/kevinqian/.rustup/toolchains/1.30.0-x86_64-apple-darwin/lib/rustlib/etc/lldb_rust_formatters.py"
673 | (lldb) type summary add --no-value --python-function lldb_rust_formatters.print_val -x ".*" --category Rust
674 | (lldb) type category enable Rust
675 | (lldb) target create "../deno/target/debug/deno"
676 | Current executable set to '../deno/target/debug/deno' (x86_64).
677 | (lldb) settings set -- target.run-args  "tests/http_bench.ts" "--allow-net"
678 | (lldb) b op_start
679 | (lldb) r
680 | ```
681 | 
682 | ### Deno 核心
683 | 
684 | DENO 的 core(核心) 绑定层。它作为一个[独立箱子](https://crates.io/crates/deno)发布。 核心内部是 V8 本身，一个名为"libdeno"的绑定 API。有关更多详细信息，请参阅该箱子的文档。
685 | 
686 | ### Flatbuffers
687 | 
688 | 我们使用 flatbuffers 定义 typescript 和 rust 之间的，公共结构和枚举。这些常见的数据结构，定义在[msg.fbs](https://github.com/denoland/deno/blob/master/cli/msg.fbs)
689 | 
690 | ### 更新预构建的二进制文件
691 | 
692 | ```shellsession
693 | $ ./third_party/depot_tools/upload_to_google_storage.py -b denoland  \
694 |   -e ~/.config/gcloud/legacy_credentials/ry@tinyclouds.org/.boto `which sccache`
695 | $ mv `which sccache`.sha1 prebuilt/linux64/
696 | $ gsutil acl ch -u AllUsers:R gs://denoland/608be47bf01004aa11d4ed06955414e93934516e
697 | ```
698 | 
699 | ### 连续基准
700 | 
701 | [在这里](https://deno.land/benchmarks.html)，看看我们的基准
702 | 
703 | 基准图表假设`//website/data.json`有`BenchmarkData[]`类型，这里的`BenchmarkData`定义如下：
704 | 
705 | ```ts
706 | interface ExecTimeData {
707 |   mean: number;
708 |   stddev: number;
709 |   user: number;
710 |   system: number;
711 |   min: number;
712 |   max: number;
713 | }
714 | 
715 | interface BenchmarkData {
716 |   created_at: string;
717 |   sha1: string;
718 |   benchmark: {
719 |     [key: string]: ExecTimeData;
720 |   };
721 |   binarySizeData: {
722 |     [key: string]: number;
723 |   };
724 |   threadCountData: {
725 |     [key: string]: number;
726 |   };
727 |   syscallCountData: {
728 |     [key: string]: number;
729 |   };
730 | }
731 | ```
732 | 
733 | ### Logos
734 | 
735 | 这些 deno 徽标，像 deno 软件一样，是在 MIT 许可证（公共域和免费使用）下发布的。
736 | 
737 | - [由 @ry 亲手画的](https://github.com/denoland/deno/blob/master/website/images/deno_logo.png)
738 | 
739 | - [由 @hashrock 制作的动画](https://github.com/denolib/animated-deno-logo/)
740 | 
741 | - [由 @kevinkassimo 提供的高分辨率 SVG](https://github.com/denolib/high-res-deno-logo)
742 | 
743 | ## 贡献
744 | 
745 | [风格指南](style_guide.html)
746 | 
747 | [在这里](https://github.com/denoland/deno/milestones)，跟踪未来版本的进展。
748 | 
749 | 请不要把[基准](https://deno.land/benchmarks.html)，搞得一团糟。
750 | 
751 | 在[社区聊天室](https://gitter.im/denolife/Lobby)，寻求帮助。
752 | 
753 | 如果您要处理某个问题，在你开始着手解决这个问题*之前*，请在问题评论中提及。
754 | 
755 | ### 提交 PR
756 | 
757 | 提交前，请确保完成以下操作：
758 | 
759 | 1.  有一个相关的问题，它在 PR 文本中,被引用。
760 | 2.  有一些测试可以覆盖这些更改。
761 | 3.  确保`./tools/test.py`成功。
762 | 4.  使用`tools/format.py`格式化代码。
763 | 5.  确保`./tools/lint.py`成功。
764 | 
765 | ### `third_party`的改变
766 | 
767 | [`deno_third_party`](https://github.com/denoland/deno_third_party)包含 deno 所依赖的大部分外部代码，这样我们就可以准确地知道，在任何给定时间执行的是什么。它是由人工和个人脚本，混合而成的，经过仔细维护。您可能需要 @ry 或 @pissisaureus 的帮助来进行更改。
768 | 
769 | ### 添加 Ops（即绑定）
770 | 
771 | 我们非常担心在添加新的 API 时出错。在 Deno 中添加一个 Op 时，需要研究其他平台上的对应接口。请列出如何在 go、node、rust 和 python 中完成此功能。
772 | 
773 | 例如，请参见被提议的`Deno.rename()`，并最终在[PR #671](https://github.com/denoland/deno/pull/671)加入。
774 | 
775 | ### 文档化 API
776 | 
777 | 记录公有 API 是很重要的，我们希望在代码中这样做。这有助于确保代码和文档紧密耦合在一起。
778 | 
779 | #### 利用 JSDoc
780 | 
781 | 所有公有的 API 和类型，都需要`deno`模块，还有 global/`window`命名空间的 JSDoc 文档。这些文档会被 typescript 编译器解析，并使用，因此，很容易提供给下游。JSDoc 代码块(注释定义)正好，位于它们应用的语句之前，并用`/**`前缀和`*/`结尾表示。 例如：
782 | 
783 | ```ts
784 | /** 一个简单 的 JSDoc z */
785 | export const FOO = 'foo'; // 应用的语句
786 | ```
787 | 


--------------------------------------------------------------------------------
/manual.md:
--------------------------------------------------------------------------------
  1 | # Deno Manual
  2 | 
  3 | [toc]
  4 | 
  5 | ## Disclaimer
  6 | 
  7 | A word of caution: Deno is very much under development. We encourage brave early
  8 | adopters, but expect bugs large and small. The API is subject to change without
  9 | notice. [Bug reports](https://github.com/denoland/deno/issues) do help!
 10 | 
 11 | ## Introduction
 12 | 
 13 | A secure JavaScript/TypeScript runtime built with V8, Rust, and Tokio
 14 | 
 15 | ### Philosophy
 16 | 
 17 | Deno aims to be a productive and secure scripting environment for the modern
 18 | programmer.
 19 | 
 20 | It will always be distributed as a single executable - and that executable will
 21 | be sufficient software to run any deno program. Given a URL to a deno program,
 22 | you should be able to execute it with nothing more than the 50 megabyte deno
 23 | executable.
 24 | 
 25 | Deno explicitly takes on the role of both runtime and package manager. It uses a
 26 | standard browser-compatible protocol for loading modules: URLs.
 27 | 
 28 | Deno provides security guarantees about how programs can access your system with
 29 | the default being the most restrictive secure sandbox.
 30 | 
 31 | Deno provides <a href="https://github.com/denoland/deno_std">a set of reviewed
 32 | (audited) standard modules</a> that are guaranteed to work with Deno.
 33 | 
 34 | ### Goals
 35 | 
 36 | - Support TypeScript out of the box.
 37 | 
 38 | - Like the browser, allows imports from URLs:
 39 | 
 40 |   ```ts
 41 |   import * as log from "https://deno.land/std/log/mod.ts";
 42 |   ```
 43 | 
 44 | - Remote code is fetched and cached on first execution, and never updated until
 45 |   the code is run with the `--reload` flag. (So, this will still work on an
 46 |   airplane. See `~/.deno/src` for details on the cache.)
 47 | 
 48 | - Uses "ES Modules" and does not support `require()`.
 49 | 
 50 | - File system and network access can be controlled in order to run sandboxed
 51 |   code. Access between V8 (unprivileged) and Rust (privileged) is only done via
 52 |   serialized messages defined in this
 53 |   [flatbuffer](https://github.com/denoland/deno/blob/master/cli/msg.fbs). This
 54 |   makes it easy to audit. For example, to enable write access use the flag
 55 |   `--allow-write` or for network access `--allow-net`.
 56 | 
 57 | - Only ship a single executable.
 58 | 
 59 | - Always dies on uncaught errors.
 60 | 
 61 | - Browser compatible: The subset of Deno programs which are written completely
 62 |   in JavaScript and do not use the global `Deno` namespace (or feature test for
 63 |   it), ought to also be able to be run in a modern web browser without change.
 64 | 
 65 | - [Aims to support top-level `await`.](https://github.com/denoland/deno/issues/471)
 66 | 
 67 | - Be able to serve HTTP efficiently.
 68 |   ([Currently it is relatively slow.](https://deno.land/benchmarks.html#req-per-sec))
 69 | 
 70 | - Provide useful tooling out of the box:
 71 |   - command-line debugger
 72 |     [not yet](https://github.com/denoland/deno/issues/1120)
 73 |   - linter [not yet](https://github.com/denoland/deno/issues/1880)
 74 |   - dependency inspector (`deno info`)
 75 |   - code formatter (`deno fmt`),
 76 | 
 77 | ### Non-goals
 78 | 
 79 | - No `package.json`.
 80 | 
 81 | - No npm.
 82 | 
 83 | - Not explicitly compatible with Node.
 84 | 
 85 | ## Setup
 86 | 
 87 | ### Binary Install
 88 | 
 89 | Deno works on OSX, Linux, and Windows. Deno is a single binary executable. It
 90 | has no external dependencies.
 91 | 
 92 | [deno_install](https://github.com/denoland/deno_install) provides convenience
 93 | scripts to download and install the binary.
 94 | 
 95 | Using Shell:
 96 | 
 97 | ```shellsession
 98 | $ curl -fsSL https://deno.land/x/install/install.sh | sh
 99 | ```
100 | 
101 | Using PowerShell:
102 | 
103 | ```shellsession
104 | > iwr https://deno.land/x/install/install.ps1 | iex
105 | ```
106 | 
107 | Using [Scoop](https://scoop.sh/) (windows):
108 | 
109 | ```
110 | scoop install deno
111 | ```
112 | 
113 | Deno can also be installed manually, by downloading a tarball or zip file at
114 | [github.com/denoland/deno/releases](https://github.com/denoland/deno/releases).
115 | These packages contain just a single executable file. You will have to set the
116 | executable bit on Mac and Linux.
117 | 
118 | Once it's installed and in your `$PATH`, try it:
119 | 
120 | ```shellsession
121 | $ deno https://deno.land/welcome.ts
122 | ```
123 | 
124 | ### Build from source
125 | 
126 | ```bash
127 | # Fetch deps.
128 | git clone --recurse-submodules https://github.com/denoland/deno.git
129 | cd deno
130 | ./tools/setup.py
131 | 
132 | # You may need to ensure that sccache is running.
133 | # (TODO it's unclear if this is necessary or not.)
134 | # prebuilt/mac/sccache --start-server
135 | 
136 | # Build.
137 | ./tools/build.py
138 | 
139 | # Run.
140 | ./target/debug/deno tests/002_hello.ts
141 | 
142 | # Test.
143 | ./tools/test.py
144 | 
145 | # Format code.
146 | ./tools/format.py
147 | ```
148 | 
149 | #### Prerequisites
150 | 
151 | To ensure reproducible builds, deno has most of its dependencies in a git
152 | submodule. However, you need to install separately:
153 | 
154 | 1. [Rust](https://www.rust-lang.org/en-US/install.html) >= 1.31.1
155 | 2. [Node](https://nodejs.org/)
156 | 3. Python 2.
157 |    [Not 3](https://github.com/denoland/deno/issues/464#issuecomment-411795578).
158 | 
159 | Extra steps for Mac users: install [XCode](https://developer.apple.com/xcode/)
160 | :(
161 | 
162 | Extra steps for Windows users:
163 | 
164 | 1. Add `python.exe` to `PATH` (e.g. `set PATH=%PATH%;C:\Python27\python.exe`)
165 | 2. Get [VS Community 2017](https://www.visualstudio.com/downloads/) with
166 |    "Desktop development with C++" toolkit and make sure to select the following
167 |    required tools listed below along with all C++ tools.
168 |    - Windows 10 SDK >= 10.0.17134
169 |    - Visual C++ ATL for x86 and x64
170 |    - Visual C++ MFC for x86 and x64
171 |    - C++ profiling tools
172 | 3. Enable "Debugging Tools for Windows". Go to "Control Panel" → "Programs" →
173 |    "Programs and Features" → Select "Windows Software Development Kit - Windows
174 |    10" → "Change" → "Change" → Check "Debugging Tools For Windows" → "Change" ->
175 |    "Finish".
176 | 4. Make sure you are using git version 2.19.2.windows.1 or newer.
177 | 
178 | #### Other useful commands
179 | 
180 | ```bash
181 | # Call ninja manually.
182 | ./third_party/depot_tools/ninja -C target/debug
183 | 
184 | # Build a release binary.
185 | ./tools/build.py --release deno
186 | 
187 | # List executable targets.
188 | ./third_party/depot_tools/gn ls target/debug //:* --as=output --type=executable
189 | 
190 | # List build configuration.
191 | ./third_party/depot_tools/gn args target/debug/ --list
192 | 
193 | # Edit build configuration.
194 | ./third_party/depot_tools/gn args target/debug/
195 | 
196 | # Describe a target.
197 | ./third_party/depot_tools/gn desc target/debug/ :deno
198 | ./third_party/depot_tools/gn help
199 | 
200 | # Update third_party modules
201 | git submodule update
202 | ```
203 | 
204 | Environment variables: `DENO_BUILD_MODE`, `DENO_BUILD_PATH`, `DENO_BUILD_ARGS`,
205 | `DENO_DIR`.
206 | 
207 | ## API reference
208 | 
209 | ### deno --types
210 | 
211 | To get an exact reference of deno's runtime API, run the following in the
212 | command line:
213 | 
214 | ```shellsession
215 | $ deno --types
216 | ```
217 | 
218 | [This is what the output looks like.](https://gist.github.com/ry/46da4724168cdefa763e13207d27ede5)
219 | 
220 | ### Reference websites
221 | 
222 | [TypeScript Deno API](https://deno.land/typedoc/index.html).
223 | 
224 | If you are embedding deno in a Rust program, see
225 | [Rust Deno API](https://deno.land/rustdoc/deno/index.html).
226 | 
227 | ## Examples
228 | 
229 | ### An implementation of the unix "cat" program
230 | 
231 | In this program each command-line argument is assumed to be a filename, the file
232 | is opened, and printed to stdout.
233 | 
234 | ```ts
235 | (async () => {
236 |   for (let i = 1; i < Deno.args.length; i++) {
237 |     let filename = Deno.args[i];
238 |     let file = await Deno.open(filename);
239 |     await Deno.copy(Deno.stdout, file);
240 |     file.close();
241 |   }
242 | })();
243 | ```
244 | 
245 | The `copy()` function here actually makes no more than the necessary kernel ->
246 | userspace -> kernel copies. That is, the same memory from which data is read
247 | from the file, is written to stdout. This illustrates a general design goal for
248 | I/O streams in Deno.
249 | 
250 | Try the program:
251 | 
252 | ```shellsession
253 | $ deno --allow-read https://deno.land/std/examples/cat.ts /etc/passwd
254 | ```
255 | 
256 | ### TCP echo server
257 | 
258 | This is an example of a simple server which accepts connections on port 8080,
259 | and returns to the client anything it sends.
260 | 
261 | ```ts
262 | const { listen, copy } = Deno;
263 | 
264 | (async () => {
265 |   const addr = "0.0.0.0:8080";
266 |   const listener = listen("tcp", addr);
267 |   console.log("listening on", addr);
268 |   while (true) {
269 |     const conn = await listener.accept();
270 |     copy(conn, conn);
271 |   }
272 | })();
273 | ```
274 | 
275 | When this program is started, the user is prompted for permission to listen on
276 | the network:
277 | 
278 | ```shellsession
279 | $ deno https://deno.land/std/examples/echo_server.ts
280 | ⚠️  Deno requests network access to "listen". Grant? [yN] y
281 | listening on 0.0.0.0:8080
282 | ```
283 | 
284 | For security reasons, deno does not allow programs to access the network without
285 | explicit permission. To avoid the console prompt, use a command-line flag:
286 | 
287 | ```shellsession
288 | $ deno https://deno.land/std/examples/echo_server.ts --allow-net
289 | ```
290 | 
291 | To test it, try sending a HTTP request to it by using curl. The request gets
292 | written directly back to the client.
293 | 
294 | ```shellsession
295 | $ curl http://localhost:8080/
296 | GET / HTTP/1.1
297 | Host: localhost:8080
298 | User-Agent: curl/7.54.0
299 | Accept: */*
300 | ```
301 | 
302 | It's worth noting that like the `cat.ts` example, the `copy()` function here
303 | also does not make unnecessary memory copies. It receives a packet from the
304 | kernel and sends back, without further complexity.
305 | 
306 | ### Inspecting and revoking permissions
307 | 
308 | Sometimes a program may want to revoke previously granted permissions. When a
309 | program, at a later stage, needs those permissions, a new prompt will be
310 | presented to the user.
311 | 
312 | ```ts
313 | const { permissions, revokePermission, open, remove } = Deno;
314 | 
315 | (async () => {
316 |   // lookup a permission
317 |   if (!permissions().write) {
318 |     throw new Error("need write permission");
319 |   }
320 | 
321 |   const log = await open("request.log", "a+");
322 | 
323 |   // revoke some permissions
324 |   revokePermission("read");
325 |   revokePermission("write");
326 | 
327 |   // use the log file
328 |   await log.write(encoder.encode("hello\n"));
329 | 
330 |   // this will prompt for the write permission or fail.
331 |   await remove("request.log");
332 | })();
333 | ```
334 | 
335 | ### File server
336 | 
337 | This one serves a local directory in HTTP.
338 | 
339 | ```bash
340 | alias file_server="deno  --allow-net --allow-read \
341 |   https://deno.land/std/http/file_server.ts"
342 | ```
343 | 
344 | Run it:
345 | 
346 | ```shellsession
347 | $ file_server .
348 | Downloading https://deno.land/std/http/file_server.ts...
349 | [...]
350 | HTTP server listening on http://0.0.0.0:4500/
351 | ```
352 | 
353 | And if you ever want to upgrade to the latest published version:
354 | 
355 | ```shellsession
356 | $ file_server --reload
357 | ```
358 | 
359 | ### Run subprocess
360 | 
361 | [API Reference](https://deno.land/typedoc/index.html#run)
362 | 
363 | Example:
364 | 
365 | ```ts
366 | async function main() {
367 |   // create subprocess
368 |   const p = Deno.run({
369 |     args: ["echo", "hello"]
370 |   });
371 | 
372 |   // await its completion
373 |   await p.status();
374 | }
375 | 
376 | main();
377 | ```
378 | 
379 | Run it:
380 | 
381 | ```shellsession
382 | $ deno --allow-run ./subprocess_simple.ts
383 | hello
384 | ```
385 | 
386 | By default when you use `Deno.run()` subprocess inherits `stdin`, `stdout` and
387 | `stdout` of parent process. If you want to communicate with started subprocess
388 | you can use `"piped"` option.
389 | 
390 | ```ts
391 | async function main() {
392 |   const decoder = new TextDecoder();
393 | 
394 |   const fileNames = Deno.args.slice(1);
395 | 
396 |   const p = Deno.run({
397 |     args: [
398 |       "deno",
399 |       "--allow-read",
400 |       "https://deno.land/std/examples/cat.ts",
401 |       ...fileNames
402 |     ],
403 |     stdout: "piped",
404 |     stderr: "piped"
405 |   });
406 | 
407 |   const { code } = await p.status();
408 | 
409 |   if (code === 0) {
410 |     const rawOutput = await p.output();
411 |     Deno.stdout.write(rawOutput);
412 |   } else {
413 |     const rawError = await p.stderrOutput();
414 |     Deno.stdout.write(rawError);
415 |   }
416 | 
417 |   Deno.exit(code);
418 | }
419 | 
420 | main();
421 | ```
422 | 
423 | When you run it:
424 | 
425 | ```shellsession
426 | $ deno ./subprocess.ts --allow-run <somefile>
427 | [file content]
428 | 
429 | $ deno ./subprocess.ts --allow-run non_existent_file.md
430 | 
431 | Uncaught NotFound: No such file or directory (os error 2)
432 |     at DenoError (deno/js/errors.ts:19:5)
433 |     at maybeError (deno/js/errors.ts:38:12)
434 |     at handleAsyncMsgFromRust (deno/js/dispatch.ts:27:17)
435 | ```
436 | 
437 | ### Linking to third party code
438 | 
439 | In the above examples, we saw that Deno could execute scripts from URLs. Like
440 | browser JavaScript, Deno can import libraries directly from URLs. This example
441 | uses a URL to import a test runner library:
442 | 
443 | ```ts
444 | import { test, runIfMain } from "https://deno.land/std/testing/mod.ts";
445 | import { assertEquals } from "https://deno.land/std/testing/asserts.ts";
446 | 
447 | test(function t1() {
448 |   assertEquals("hello", "hello");
449 | });
450 | 
451 | test(function t2() {
452 |   assertEquals("world", "world");
453 | });
454 | 
455 | runIfMain(import.meta);
456 | ```
457 | 
458 | Try running this:
459 | 
460 | ```shellsession
461 | $ deno test.ts
462 | running 2 tests
463 | test t1 ... ok
464 | test t2 ... ok
465 | 
466 | test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out
467 | 
468 | ```
469 | 
470 | Note that we did not have to provide the `--allow-net` flag for this program,
471 | and yet it accessed the network. The runtime has special access to download
472 | imports and cache them to disk.
473 | 
474 | Deno caches remote imports in a special directory specified by the `$DENO_DIR`
475 | environmental variable. It defaults to the system's cache directory if
476 | `$DENO_DIR` is not specified. The next time you run the program, no downloads
477 | will be made. If the program hasn't changed, it won't be recompiled either. The
478 | default directory is:
479 | 
480 | - On Linux/Redox: `$XDG_CACHE_HOME/deno` or `$HOME/.cache/deno`
481 | - On Windows: `%LOCALAPPDATA%/deno` (`%LOCALAPPDATA%` = `FOLDERID_LocalAppData`)
482 | - On macOS: `$HOME/Library/Caches/deno`
483 | - If something fails, it falls back to `$HOME/.deno`
484 | 
485 | **But what if `https://deno.land/` goes down?** Relying on external servers is
486 | convenient for development but brittle in production. Production software should
487 | always bundle its dependencies. In Deno this is done by checking the `$DENO_DIR`
488 | into your source control system, and specifying that path as the `$DENO_DIR`
489 | environmental variable at runtime.
490 | 
491 | **How do you import to a specific version?** Simply specify the version in the
492 | URL. For example, this URL fully specifies the code being run:
493 | `https://unpkg.com/liltest@0.0.5/dist/liltest.js`. Combined with the
494 | aforementioned technique of setting `$DENO_DIR` in production to stored code,
495 | one can fully specify the exact code being run, and execute the code without
496 | network access.
497 | 
498 | **It seems unwieldy to import URLs everywhere. What if one of the URLs links to
499 | a subtly different version of a library? Isn't it error prone to maintain URLs
500 | everywhere in a large project?** The solution is to import and re-export your
501 | external libraries in a central `deps.ts` file (which serves the same purpose as
502 | Node's `package.json` file). For example, let's say you were using the above
503 | testing library across a large project. Rather than importing
504 | `"https://deno.land/std/testing/mod.ts"` everywhere, you could create a
505 | `deps.ts` file the exports the third-party code:
506 | 
507 | ```ts
508 | export { test, assertEquals } from "https://deno.land/std/testing/mod.ts";
509 | ```
510 | 
511 | And throughout project one can import from the `deps.ts` and avoid having many
512 | references to the same URL:
513 | 
514 | ```ts
515 | import { test, assertEquals } from "./deps.ts";
516 | ```
517 | 
518 | This design circumvents a plethora of complexity spawned by package management
519 | software, centralized code repositories, and superfluous file formats.
520 | 
521 | ### Testing if current file is the main program
522 | 
523 | To test if the current script has been executed as the main input to the program
524 | check `import.meta.main`.
525 | 
526 | ```ts
527 | if (import.meta.main) {
528 |   console.log("main");
529 | }
530 | ```
531 | 
532 | ## Command line interface
533 | 
534 | ### Flags
535 | 
536 | ```shellsession
537 | $ deno -h
538 | deno
539 | 
540 | USAGE:
541 |     deno_dev [FLAGS] [OPTIONS] [SUBCOMMAND]
542 | 
543 | FLAGS:
544 |     -A, --allow-all      Allow all permissions
545 |         --allow-env      Allow environment access
546 |         --allow-net      Allow network access
547 |         --allow-read     Allow file system read access
548 |         --allow-run      Allow running subprocesses
549 |         --allow-write    Allow file system write access
550 |     -h, --help           Prints help information
551 |     -D, --log-debug      Log debug output
552 |         --no-prompt      Do not use prompts
553 |         --prefetch       Prefetch the dependencies
554 |     -r, --reload         Reload source code cache (recompile TypeScript)
555 |         --types          Print runtime TypeScript declarations
556 |         --v8-options     Print V8 command line options
557 |     -v, --version        Print the version
558 | 
559 | OPTIONS:
560 |         --v8-flags=<v8-flags>    Set V8 command line options
561 | 
562 | SUBCOMMANDS:
563 |     <script>    Script to run
564 |     fmt         Format files
565 |     info        Show source file related info
566 | 
567 | ENVIRONMENT VARIABLES:
568 |     DENO_DIR        Set deno's base directory
569 |     NO_COLOR        Set to disable color
570 | ```
571 | 
572 | ### Environmental variables
573 | 
574 | There are several env vars that control how Deno behaves:
575 | 
576 | `DENO_DIR` defaults to `$HOME/.deno` but can be set to any path to control where
577 | generated and cached source code is written and read to.
578 | 
579 | `NO_COLOR` will turn off color output if set. See https://no-color.org/. User
580 | code can test if `NO_COLOR` was set without having `--allow-env` by using the
581 | boolean constant `Deno.noColor`.
582 | 
583 | ### V8 flags
584 | 
585 | V8 has many many internal command-line flags, that you can see with
586 | `--v8-options`.
587 | [It looks like this.](https://gist.github.com/ry/1c5b080dcbdc6367e5612392049c9ee7)
588 | 
589 | Particularly useful ones:
590 | 
591 | ```
592 | --async-stack-trace
593 | ```
594 | 
595 | ## Internal details
596 | 
597 | ### Deno and Linux analogy
598 | 
599 | |                       **Linux** | **Deno**                         |
600 | | ------------------------------: | :------------------------------- |
601 | |                       Processes | Web Workers                      |
602 | |                        Syscalls | Ops                              |
603 | |           File descriptors (fd) | [Resource ids (rid)](#resources) |
604 | |                       Scheduler | Tokio                            |
605 | | Userland: libc++ / glib / boost | deno_std                         |
606 | |                 /proc/\$\$/stat | [Deno.metrics()](#metrics)       |
607 | |                       man pages | deno --types                     |
608 | 
609 | #### Resources
610 | 
611 | Resources (AKA `rid`) are Deno's version of file descriptors. They are integer
612 | values used to refer to open files, sockets, and other concepts. For testing it
613 | would be good to be able to query the system for how many open resources there
614 | are.
615 | 
616 | ```ts
617 | const { resources, close } = Deno;
618 | console.log(resources());
619 | // output like: { 0: "stdin", 1: "stdout", 2: "stderr", 3: "repl" }
620 | 
621 | // close resource by rid
622 | close(3);
623 | ```
624 | 
625 | #### Metrics
626 | 
627 | Metrics is deno's internal counters for various statics.
628 | 
629 | ```shellsession
630 | > console.table(Deno.metrics())
631 | ┌──────────────────┬────────┐
632 | │     (index)      │ Values │
633 | ├──────────────────┼────────┤
634 | │  opsDispatched   │   9    │
635 | │   opsCompleted   │   9    │
636 | │ bytesSentControl │  504   │
637 | │  bytesSentData   │   0    │
638 | │  bytesReceived   │  856   │
639 | └──────────────────┴────────┘
640 | ```
641 | 
642 | ### Schematic diagram
643 | 
644 | <img src="images/schematic_v0.2.png">
645 | 
646 | ### Profiling
647 | 
648 | To start profiling,
649 | 
650 | ```sh
651 | # Make sure we're only building release.
652 | # Build deno and V8's d8.
653 | ./tools/build.py --release d8 deno
654 | # Start the program we want to benchmark with --prof
655 | ./target/release/deno tests/http_bench.ts --allow-net --prof &
656 | # Exercise it.
657 | third_party/wrk/linux/wrk http://localhost:4500/
658 | kill `pgrep deno`
659 | ```
660 | 
661 | V8 will write a file in the current directory that looks like this:
662 | `isolate-0x7fad98242400-v8.log`. To examine this file:
663 | 
664 | ```sh
665 | D8_PATH=target/release/ ./third_party/v8/tools/linux-tick-processor
666 | isolate-0x7fad98242400-v8.log > prof.log
667 | # on macOS, use ./third_party/v8/tools/mac-tick-processor instead
668 | ```
669 | 
670 | `prof.log` will contain information about tick distribution of different calls.
671 | 
672 | To view the log with Web UI, generate JSON file of the log:
673 | 
674 | ```sh
675 | D8_PATH=target/release/ ./third_party/v8/tools/linux-tick-processor
676 | isolate-0x7fad98242400-v8.log --preprocess > prof.json
677 | ```
678 | 
679 | Open `third_party/v8/tools/profview/index.html` in your brower, and select
680 | `prof.json` to view the distribution graphically.
681 | 
682 | To learn more about `d8` and profiling, check out the following links:
683 | 
684 | - [https://v8.dev/docs/d8](https://v8.dev/docs/d8)
685 | - [https://v8.dev/docs/profile](https://v8.dev/docs/profile)
686 | 
687 | ### Debugging with LLDB
688 | 
689 | We can use LLDB to debug deno.
690 | 
691 | ```shellsession
692 | $ lldb -- target/debug/deno tests/worker.js
693 | > run
694 | > bt
695 | > up
696 | > up
697 | > l
698 | ```
699 | 
700 | To debug Rust code, we can use `rust-lldb`. It should come with `rustc` and is a
701 | wrapper around LLDB.
702 | 
703 | ```shellsession
704 | $ rust-lldb -- ./target/debug/deno tests/http_bench.ts --allow-net
705 | # On macOS, you might get warnings like
706 | # `ImportError: cannot import name _remove_dead_weakref`
707 | # In that case, use system python by setting PATH, e.g.
708 | # PATH=/System/Library/Frameworks/Python.framework/Versions/2.7/bin:$PATH
709 | (lldb) command script import "/Users/kevinqian/.rustup/toolchains/1.30.0-x86_64-apple-darwin/lib/rustlib/etc/lldb_rust_formatters.py"
710 | (lldb) type summary add --no-value --python-function lldb_rust_formatters.print_val -x ".*" --category Rust
711 | (lldb) type category enable Rust
712 | (lldb) target create "../deno/target/debug/deno"
713 | Current executable set to '../deno/target/debug/deno' (x86_64).
714 | (lldb) settings set -- target.run-args  "tests/http_bench.ts" "--allow-net"
715 | (lldb) b op_start
716 | (lldb) r
717 | ```
718 | 
719 | ### Deno Core
720 | 
721 | The core binding layer for Deno. It is released as a
722 | [standalone crate](https://crates.io/crates/deno). Inside of core is V8 itself,
723 | with a binding API called "libdeno". See the crate documentation for more
724 | details.
725 | 
726 | ### Flatbuffers
727 | 
728 | We use Flatbuffers to define common structs and enums between TypeScript and
729 | Rust. These common data structures are defined in
730 | [msg.fbs](https://github.com/denoland/deno/blob/master/cli/msg.fbs)
731 | 
732 | ### Updating prebuilt binaries
733 | 
734 | ```shellsession
735 | $ ./third_party/depot_tools/upload_to_google_storage.py -b denoland  \
736 |   -e ~/.config/gcloud/legacy_credentials/ry@tinyclouds.org/.boto `which sccache`
737 | $ mv `which sccache`.sha1 prebuilt/linux64/
738 | $ gsutil acl ch -u AllUsers:R gs://denoland/608be47bf01004aa11d4ed06955414e93934516e
739 | ```
740 | 
741 | ### Continuous Benchmarks
742 | 
743 | See our benchmarks [over here](https://deno.land/benchmarks.html)
744 | 
745 | The benchmark chart supposes `//website/data.json` has the type
746 | `BenchmarkData[]` where `BenchmarkData` is defined like the below:
747 | 
748 | ```ts
749 | interface ExecTimeData {
750 |   mean: number;
751 |   stddev: number;
752 |   user: number;
753 |   system: number;
754 |   min: number;
755 |   max: number;
756 | }
757 | 
758 | interface BenchmarkData {
759 |   created_at: string;
760 |   sha1: string;
761 |   benchmark: {
762 |     [key: string]: ExecTimeData;
763 |   };
764 |   binarySizeData: {
765 |     [key: string]: number;
766 |   };
767 |   threadCountData: {
768 |     [key: string]: number;
769 |   };
770 |   syscallCountData: {
771 |     [key: string]: number;
772 |   };
773 | }
774 | ```
775 | 
776 | ### Logos
777 | 
778 | These Deno logos, like the Deno software, are distributed under the MIT license
779 | (public domain and free for use)
780 | 
781 | - [A hand drawn one by @ry](https://github.com/denoland/deno/blob/master/website/images/deno_logo.png)
782 | 
783 | - [An animated one by @hashrock](https://github.com/denolib/animated-deno-logo/)
784 | 
785 | - [A high resolution SVG one by @kevinkassimo](https://github.com/denolib/high-res-deno-logo)
786 | 
787 | ## Contributing
788 | 
789 | [Style Guide](style_guide.html)
790 | 
791 | Progress towards future releases is tracked
792 | [here](https://github.com/denoland/deno/milestones).
793 | 
794 | Please don't make [the benchmarks](https://deno.land/benchmarks.html) worse.
795 | 
796 | Ask for help in the [community chat room](https://gitter.im/denolife/Lobby).
797 | 
798 | If you are going to work on an issue, mention so in the issue comments _before_
799 | you start working on the issue.
800 | 
801 | ### Submitting a pull request
802 | 
803 | Before submitting, please make sure the following is done:
804 | 
805 | 1. That there is a related issue and it is referenced in the PR text.
806 | 2. There are tests that cover the changes.
807 | 3. Ensure `./tools/test.py` passes.
808 | 4. Format your code with `tools/format.py`
809 | 5. Make sure `./tools/lint.py` passes.
810 | 
811 | ### Changes to `third_party`
812 | 
813 | [`deno_third_party`](https://github.com/denoland/deno_third_party) contains most
814 | of the external code that Deno depends on, so that we know exactly what we are
815 | executing at any given time. It is carefully maintained with a mixture of manual
816 | labor and private scripts. It's likely you will need help from @ry or
817 | @piscisaureus to make changes.
818 | 
819 | ### Adding Ops (aka bindings)
820 | 
821 | We are very concerned about making mistakes when adding new APIs. When adding an
822 | Op to Deno, the counterpart interfaces on other platforms should be researched.
823 | Please list how this functionality is done in Go, Node, Rust, and Python.
824 | 
825 | As an example, see how `Deno.rename()` was proposed and added in
826 | [PR #671](https://github.com/denoland/deno/pull/671).
827 | 
828 | ### Documenting APIs
829 | 
830 | It is important to document public APIs and we want to do that inline with the
831 | code. This helps ensure that code and documentation are tightly coupled
832 | together.
833 | 
834 | #### Utilize JSDoc
835 | 
836 | All publicly exposed APIs and types, both via the `deno` module as well as the
837 | global/`window` namespace should have JSDoc documentation. This documentation is
838 | parsed and available to the TypeScript compiler, and therefore easy to provide
839 | further downstream. JSDoc blocks come just prior to the statement they apply to
840 | and are denoted by a leading `/**` before terminating with a `*/`. For example:
841 | 
842 | ```ts
843 | /** A simple JSDoc comment */
844 | export const FOO = "foo";
845 | ```
846 | 


--------------------------------------------------------------------------------
/docs/manual.md:
--------------------------------------------------------------------------------
  1 | # Deno Manual
  2 | 
  3 | [toc]
  4 | 
  5 | ## Disclaimer
  6 | 
  7 | A word of caution: Deno is very much under development. We encourage brave early
  8 | adopters, but expect bugs large and small. The API is subject to change without
  9 | notice. [Bug reports](https://github.com/denoland/deno/issues) do help!
 10 | 
 11 | ## Introduction
 12 | 
 13 | A secure JavaScript/TypeScript runtime built with V8, Rust, and Tokio
 14 | 
 15 | ### Philosophy
 16 | 
 17 | Deno aims to be a productive and secure scripting environment for the modern
 18 | programmer.
 19 | 
 20 | It will always be distributed as a single executable - and that executable will
 21 | be sufficient software to run any deno program. Given a URL to a deno program,
 22 | you should be able to execute it with nothing more than the 50 megabyte deno
 23 | executable.
 24 | 
 25 | Deno explicitly takes on the role of both runtime and package manager. It uses a
 26 | standard browser-compatible protocol for loading modules: URLs.
 27 | 
 28 | Deno provides security guarantees about how programs can access your system with
 29 | the default being the most restrictive secure sandbox.
 30 | 
 31 | Deno provides <a href="https://github.com/denoland/deno_std">a set of reviewed
 32 | (audited) standard modules</a> that are guaranteed to work with Deno.
 33 | 
 34 | ### Goals
 35 | 
 36 | - Support TypeScript out of the box.
 37 | 
 38 | - Like the browser, allows imports from URLs:
 39 | 
 40 |   ```ts
 41 |   import * as log from "https://deno.land/std/log/mod.ts";
 42 |   ```
 43 | 
 44 | - Remote code is fetched and cached on first execution, and never updated until
 45 |   the code is run with the `--reload` flag. (So, this will still work on an
 46 |   airplane. See `~/.deno/src` for details on the cache.)
 47 | 
 48 | - Uses "ES Modules" and does not support `require()`.
 49 | 
 50 | - File system and network access can be controlled in order to run sandboxed
 51 |   code. Access between V8 (unprivileged) and Rust (privileged) is only done via
 52 |   serialized messages defined in this
 53 |   [flatbuffer](https://github.com/denoland/deno/blob/master/cli/msg.fbs). This
 54 |   makes it easy to audit. For example, to enable write access use the flag
 55 |   `--allow-write` or for network access `--allow-net`.
 56 | 
 57 | - Only ship a single executable.
 58 | 
 59 | - Always dies on uncaught errors.
 60 | 
 61 | - Browser compatible: The subset of Deno programs which are written completely
 62 |   in JavaScript and do not use the global `Deno` namespace (or feature test for
 63 |   it), ought to also be able to be run in a modern web browser without change.
 64 | 
 65 | - [Aims to support top-level `await`.](https://github.com/denoland/deno/issues/471)
 66 | 
 67 | - Be able to serve HTTP efficiently.
 68 |   ([Currently it is relatively slow.](https://deno.land/benchmarks.html#req-per-sec))
 69 | 
 70 | - Provide useful tooling out of the box:
 71 |   - command-line debugger
 72 |     [not yet](https://github.com/denoland/deno/issues/1120)
 73 |   - linter [not yet](https://github.com/denoland/deno/issues/1880)
 74 |   - dependency inspector (`deno info`)
 75 |   - code formatter (`deno fmt`),
 76 | 
 77 | ### Non-goals
 78 | 
 79 | - No `package.json`.
 80 | 
 81 | - No npm.
 82 | 
 83 | - Not explicitly compatible with Node.
 84 | 
 85 | ## Setup
 86 | 
 87 | ### Binary Install
 88 | 
 89 | Deno works on OSX, Linux, and Windows. Deno is a single binary executable. It
 90 | has no external dependencies.
 91 | 
 92 | [deno_install](https://github.com/denoland/deno_install) provides convenience
 93 | scripts to download and install the binary.
 94 | 
 95 | Using Shell:
 96 | 
 97 | ```shellsession
 98 | $ curl -fsSL https://deno.land/x/install/install.sh | sh
 99 | ```
100 | 
101 | Using PowerShell:
102 | 
103 | ```shellsession
104 | > iwr https://deno.land/x/install/install.ps1 | iex
105 | ```
106 | 
107 | Using [Scoop](https://scoop.sh/) (windows):
108 | 
109 | ```
110 | scoop install deno
111 | ```
112 | 
113 | Deno can also be installed manually, by downloading a tarball or zip file at
114 | [github.com/denoland/deno/releases](https://github.com/denoland/deno/releases).
115 | These packages contain just a single executable file. You will have to set the
116 | executable bit on Mac and Linux.
117 | 
118 | Once it's installed and in your `$PATH`, try it:
119 | 
120 | ```shellsession
121 | $ deno https://deno.land/welcome.ts
122 | ```
123 | 
124 | ### Build from source
125 | 
126 | ```bash
127 | # Fetch deps.
128 | git clone --recurse-submodules https://github.com/denoland/deno.git
129 | cd deno
130 | ./tools/setup.py
131 | 
132 | # You may need to ensure that sccache is running.
133 | # (TODO it's unclear if this is necessary or not.)
134 | # prebuilt/mac/sccache --start-server
135 | 
136 | # Build.
137 | ./tools/build.py
138 | 
139 | # Run.
140 | ./target/debug/deno tests/002_hello.ts
141 | 
142 | # Test.
143 | ./tools/test.py
144 | 
145 | # Format code.
146 | ./tools/format.py
147 | ```
148 | 
149 | #### Prerequisites
150 | 
151 | To ensure reproducible builds, deno has most of its dependencies in a git
152 | submodule. However, you need to install separately:
153 | 
154 | 1. [Rust](https://www.rust-lang.org/en-US/install.html) >= 1.31.1
155 | 2. [Node](https://nodejs.org/)
156 | 3. Python 2.
157 |    [Not 3](https://github.com/denoland/deno/issues/464#issuecomment-411795578).
158 | 
159 | Extra steps for Mac users: install [XCode](https://developer.apple.com/xcode/)
160 | :(
161 | 
162 | Extra steps for Windows users:
163 | 
164 | 1. Add `python.exe` to `PATH` (e.g. `set PATH=%PATH%;C:\Python27\python.exe`)
165 | 2. Get [VS Community 2017](https://www.visualstudio.com/downloads/) with
166 |    "Desktop development with C++" toolkit and make sure to select the following
167 |    required tools listed below along with all C++ tools.
168 |    - Windows 10 SDK >= 10.0.17134
169 |    - Visual C++ ATL for x86 and x64
170 |    - Visual C++ MFC for x86 and x64
171 |    - C++ profiling tools
172 | 3. Enable "Debugging Tools for Windows". Go to "Control Panel" → "Programs" →
173 |    "Programs and Features" → Select "Windows Software Development Kit - Windows
174 |    10" → "Change" → "Change" → Check "Debugging Tools For Windows" → "Change" ->
175 |    "Finish".
176 | 4. Make sure you are using git version 2.19.2.windows.1 or newer.
177 | 
178 | #### Other useful commands
179 | 
180 | ```bash
181 | # Call ninja manually.
182 | ./third_party/depot_tools/ninja -C target/debug
183 | 
184 | # Build a release binary.
185 | ./tools/build.py --release deno
186 | 
187 | # List executable targets.
188 | ./third_party/depot_tools/gn ls target/debug //:* --as=output --type=executable
189 | 
190 | # List build configuration.
191 | ./third_party/depot_tools/gn args target/debug/ --list
192 | 
193 | # Edit build configuration.
194 | ./third_party/depot_tools/gn args target/debug/
195 | 
196 | # Describe a target.
197 | ./third_party/depot_tools/gn desc target/debug/ :deno
198 | ./third_party/depot_tools/gn help
199 | 
200 | # Update third_party modules
201 | git submodule update
202 | ```
203 | 
204 | Environment variables: `DENO_BUILD_MODE`, `DENO_BUILD_PATH`, `DENO_BUILD_ARGS`,
205 | `DENO_DIR`.
206 | 
207 | ## API reference
208 | 
209 | ### deno --types
210 | 
211 | To get an exact reference of deno's runtime API, run the following in the
212 | command line:
213 | 
214 | ```shellsession
215 | $ deno --types
216 | ```
217 | 
218 | [This is what the output looks like.](https://gist.github.com/ry/46da4724168cdefa763e13207d27ede5)
219 | 
220 | ### Reference websites
221 | 
222 | [TypeScript Deno API](https://deno.land/typedoc/index.html).
223 | 
224 | If you are embedding deno in a Rust program, see
225 | [Rust Deno API](https://deno.land/rustdoc/deno/index.html).
226 | 
227 | ## Examples
228 | 
229 | ### An implementation of the unix "cat" program
230 | 
231 | In this program each command-line argument is assumed to be a filename, the file
232 | is opened, and printed to stdout.
233 | 
234 | ```ts
235 | (async () => {
236 |   for (let i = 1; i < Deno.args.length; i++) {
237 |     let filename = Deno.args[i];
238 |     let file = await Deno.open(filename);
239 |     await Deno.copy(Deno.stdout, file);
240 |     file.close();
241 |   }
242 | })();
243 | ```
244 | 
245 | The `copy()` function here actually makes no more than the necessary kernel ->
246 | userspace -> kernel copies. That is, the same memory from which data is read
247 | from the file, is written to stdout. This illustrates a general design goal for
248 | I/O streams in Deno.
249 | 
250 | Try the program:
251 | 
252 | ```shellsession
253 | $ deno --allow-read https://deno.land/std/examples/cat.ts /etc/passwd
254 | ```
255 | 
256 | ### TCP echo server
257 | 
258 | This is an example of a simple server which accepts connections on port 8080,
259 | and returns to the client anything it sends.
260 | 
261 | ```ts
262 | const { listen, copy } = Deno;
263 | 
264 | (async () => {
265 |   const addr = "0.0.0.0:8080";
266 |   const listener = listen("tcp", addr);
267 |   console.log("listening on", addr);
268 |   while (true) {
269 |     const conn = await listener.accept();
270 |     copy(conn, conn);
271 |   }
272 | })();
273 | ```
274 | 
275 | When this program is started, the user is prompted for permission to listen on
276 | the network:
277 | 
278 | ```shellsession
279 | $ deno https://deno.land/std/examples/echo_server.ts
280 | ⚠️  Deno requests network access to "listen". Grant? [yN] y
281 | listening on 0.0.0.0:8080
282 | ```
283 | 
284 | For security reasons, deno does not allow programs to access the network without
285 | explicit permission. To avoid the console prompt, use a command-line flag:
286 | 
287 | ```shellsession
288 | $ deno https://deno.land/std/examples/echo_server.ts --allow-net
289 | ```
290 | 
291 | To test it, try sending a HTTP request to it by using curl. The request gets
292 | written directly back to the client.
293 | 
294 | ```shellsession
295 | $ curl http://localhost:8080/
296 | GET / HTTP/1.1
297 | Host: localhost:8080
298 | User-Agent: curl/7.54.0
299 | Accept: */*
300 | ```
301 | 
302 | It's worth noting that like the `cat.ts` example, the `copy()` function here
303 | also does not make unnecessary memory copies. It receives a packet from the
304 | kernel and sends back, without further complexity.
305 | 
306 | ### Inspecting and revoking permissions
307 | 
308 | Sometimes a program may want to revoke previously granted permissions. When a
309 | program, at a later stage, needs those permissions, a new prompt will be
310 | presented to the user.
311 | 
312 | ```ts
313 | const { permissions, revokePermission, open, remove } = Deno;
314 | 
315 | (async () => {
316 |   // lookup a permission
317 |   if (!permissions().write) {
318 |     throw new Error("need write permission");
319 |   }
320 | 
321 |   const log = await open("request.log", "a+");
322 | 
323 |   // revoke some permissions
324 |   revokePermission("read");
325 |   revokePermission("write");
326 | 
327 |   // use the log file
328 |   await log.write(encoder.encode("hello\n"));
329 | 
330 |   // this will prompt for the write permission or fail.
331 |   await remove("request.log");
332 | })();
333 | ```
334 | 
335 | ### File server
336 | 
337 | This one serves a local directory in HTTP.
338 | 
339 | ```bash
340 | alias file_server="deno  --allow-net --allow-read \
341 |   https://deno.land/std/http/file_server.ts"
342 | ```
343 | 
344 | Run it:
345 | 
346 | ```shellsession
347 | $ file_server .
348 | Downloading https://deno.land/std/http/file_server.ts...
349 | [...]
350 | HTTP server listening on http://0.0.0.0:4500/
351 | ```
352 | 
353 | And if you ever want to upgrade to the latest published version:
354 | 
355 | ```shellsession
356 | $ file_server --reload
357 | ```
358 | 
359 | ### Run subprocess
360 | 
361 | [API Reference](https://deno.land/typedoc/index.html#run)
362 | 
363 | Example:
364 | 
365 | ```ts
366 | async function main() {
367 |   // create subprocess
368 |   const p = Deno.run({
369 |     args: ["echo", "hello"]
370 |   });
371 | 
372 |   // await its completion
373 |   await p.status();
374 | }
375 | 
376 | main();
377 | ```
378 | 
379 | Run it:
380 | 
381 | ```shellsession
382 | $ deno --allow-run ./subprocess_simple.ts
383 | hello
384 | ```
385 | 
386 | By default when you use `Deno.run()` subprocess inherits `stdin`, `stdout` and
387 | `stdout` of parent process. If you want to communicate with started subprocess
388 | you can use `"piped"` option.
389 | 
390 | ```ts
391 | async function main() {
392 |   const decoder = new TextDecoder();
393 | 
394 |   const fileNames = Deno.args.slice(1);
395 | 
396 |   const p = Deno.run({
397 |     args: [
398 |       "deno",
399 |       "--allow-read",
400 |       "https://deno.land/std/examples/cat.ts",
401 |       ...fileNames
402 |     ],
403 |     stdout: "piped",
404 |     stderr: "piped"
405 |   });
406 | 
407 |   const { code } = await p.status();
408 | 
409 |   if (code === 0) {
410 |     const rawOutput = await p.output();
411 |     Deno.stdout.write(rawOutput);
412 |   } else {
413 |     const rawError = await p.stderrOutput();
414 |     Deno.stdout.write(rawError);
415 |   }
416 | 
417 |   Deno.exit(code);
418 | }
419 | 
420 | main();
421 | ```
422 | 
423 | When you run it:
424 | 
425 | ```shellsession
426 | $ deno ./subprocess.ts --allow-run <somefile>
427 | [file content]
428 | 
429 | $ deno ./subprocess.ts --allow-run non_existent_file.md
430 | 
431 | Uncaught NotFound: No such file or directory (os error 2)
432 |     at DenoError (deno/js/errors.ts:19:5)
433 |     at maybeError (deno/js/errors.ts:38:12)
434 |     at handleAsyncMsgFromRust (deno/js/dispatch.ts:27:17)
435 | ```
436 | 
437 | ### Linking to third party code
438 | 
439 | In the above examples, we saw that Deno could execute scripts from URLs. Like
440 | browser JavaScript, Deno can import libraries directly from URLs. This example
441 | uses a URL to import a test runner library:
442 | 
443 | ```ts
444 | import { test, runIfMain } from "https://deno.land/std/testing/mod.ts";
445 | import { assertEquals } from "https://deno.land/std/testing/asserts.ts";
446 | 
447 | test(function t1() {
448 |   assertEquals("hello", "hello");
449 | });
450 | 
451 | test(function t2() {
452 |   assertEquals("world", "world");
453 | });
454 | 
455 | runIfMain(import.meta);
456 | ```
457 | 
458 | Try running this:
459 | 
460 | ```shellsession
461 | $ deno test.ts
462 | running 2 tests
463 | test t1 ... ok
464 | test t2 ... ok
465 | 
466 | test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out
467 | 
468 | ```
469 | 
470 | Note that we did not have to provide the `--allow-net` flag for this program,
471 | and yet it accessed the network. The runtime has special access to download
472 | imports and cache them to disk.
473 | 
474 | Deno caches remote imports in a special directory specified by the `$DENO_DIR`
475 | environmental variable. It defaults to the system's cache directory if
476 | `$DENO_DIR` is not specified. The next time you run the program, no downloads
477 | will be made. If the program hasn't changed, it won't be recompiled either. The
478 | default directory is:
479 | 
480 | - On Linux/Redox: `$XDG_CACHE_HOME/deno` or `$HOME/.cache/deno`
481 | - On Windows: `%LOCALAPPDATA%/deno` (`%LOCALAPPDATA%` = `FOLDERID_LocalAppData`)
482 | - On macOS: `$HOME/Library/Caches/deno`
483 | - If something fails, it falls back to `$HOME/.deno`
484 | 
485 | **But what if `https://deno.land/` goes down?** Relying on external servers is
486 | convenient for development but brittle in production. Production software should
487 | always bundle its dependencies. In Deno this is done by checking the `$DENO_DIR`
488 | into your source control system, and specifying that path as the `$DENO_DIR`
489 | environmental variable at runtime.
490 | 
491 | **How do you import to a specific version?** Simply specify the version in the
492 | URL. For example, this URL fully specifies the code being run:
493 | `https://unpkg.com/liltest@0.0.5/dist/liltest.js`. Combined with the
494 | aforementioned technique of setting `$DENO_DIR` in production to stored code,
495 | one can fully specify the exact code being run, and execute the code without
496 | network access.
497 | 
498 | **It seems unwieldy to import URLs everywhere. What if one of the URLs links to
499 | a subtly different version of a library? Isn't it error prone to maintain URLs
500 | everywhere in a large project?** The solution is to import and re-export your
501 | external libraries in a central `deps.ts` file (which serves the same purpose as
502 | Node's `package.json` file). For example, let's say you were using the above
503 | testing library across a large project. Rather than importing
504 | `"https://deno.land/std/testing/mod.ts"` everywhere, you could create a
505 | `deps.ts` file the exports the third-party code:
506 | 
507 | ```ts
508 | export { test, assertEquals } from "https://deno.land/std/testing/mod.ts";
509 | ```
510 | 
511 | And throughout project one can import from the `deps.ts` and avoid having many
512 | references to the same URL:
513 | 
514 | ```ts
515 | import { test, assertEquals } from "./deps.ts";
516 | ```
517 | 
518 | This design circumvents a plethora of complexity spawned by package management
519 | software, centralized code repositories, and superfluous file formats.
520 | 
521 | ### Testing if current file is the main program
522 | 
523 | To test if the current script has been executed as the main input to the program
524 | check `import.meta.main`.
525 | 
526 | ```ts
527 | if (import.meta.main) {
528 |   console.log("main");
529 | }
530 | ```
531 | 
532 | ## Command line interface
533 | 
534 | ### Flags
535 | 
536 | ```shellsession
537 | $ deno -h
538 | deno
539 | 
540 | USAGE:
541 |     deno_dev [FLAGS] [OPTIONS] [SUBCOMMAND]
542 | 
543 | FLAGS:
544 |     -A, --allow-all      Allow all permissions
545 |         --allow-env      Allow environment access
546 |         --allow-net      Allow network access
547 |         --allow-read     Allow file system read access
548 |         --allow-run      Allow running subprocesses
549 |         --allow-write    Allow file system write access
550 |     -h, --help           Prints help information
551 |     -D, --log-debug      Log debug output
552 |         --no-prompt      Do not use prompts
553 |         --prefetch       Prefetch the dependencies
554 |     -r, --reload         Reload source code cache (recompile TypeScript)
555 |         --types          Print runtime TypeScript declarations
556 |         --v8-options     Print V8 command line options
557 |     -v, --version        Print the version
558 | 
559 | OPTIONS:
560 |         --v8-flags=<v8-flags>    Set V8 command line options
561 | 
562 | SUBCOMMANDS:
563 |     <script>    Script to run
564 |     fmt         Format files
565 |     info        Show source file related info
566 | 
567 | ENVIRONMENT VARIABLES:
568 |     DENO_DIR        Set deno's base directory
569 |     NO_COLOR        Set to disable color
570 | ```
571 | 
572 | ### Environmental variables
573 | 
574 | There are several env vars that control how Deno behaves:
575 | 
576 | `DENO_DIR` defaults to `$HOME/.deno` but can be set to any path to control where
577 | generated and cached source code is written and read to.
578 | 
579 | `NO_COLOR` will turn off color output if set. See https://no-color.org/. User
580 | code can test if `NO_COLOR` was set without having `--allow-env` by using the
581 | boolean constant `Deno.noColor`.
582 | 
583 | ### V8 flags
584 | 
585 | V8 has many many internal command-line flags, that you can see with
586 | `--v8-options`.
587 | [It looks like this.](https://gist.github.com/ry/1c5b080dcbdc6367e5612392049c9ee7)
588 | 
589 | Particularly useful ones:
590 | 
591 | ```
592 | --async-stack-trace
593 | ```
594 | 
595 | ## Internal details
596 | 
597 | ### Deno and Linux analogy
598 | 
599 | |                       **Linux** | **Deno**                         |
600 | | ------------------------------: | :------------------------------- |
601 | |                       Processes | Web Workers                      |
602 | |                        Syscalls | Ops                              |
603 | |           File descriptors (fd) | [Resource ids (rid)](#resources) |
604 | |                       Scheduler | Tokio                            |
605 | | Userland: libc++ / glib / boost | deno_std                         |
606 | |                 /proc/\$\$/stat | [Deno.metrics()](#metrics)       |
607 | |                       man pages | deno --types                     |
608 | 
609 | #### Resources
610 | 
611 | Resources (AKA `rid`) are Deno's version of file descriptors. They are integer
612 | values used to refer to open files, sockets, and other concepts. For testing it
613 | would be good to be able to query the system for how many open resources there
614 | are.
615 | 
616 | ```ts
617 | const { resources, close } = Deno;
618 | console.log(resources());
619 | // output like: { 0: "stdin", 1: "stdout", 2: "stderr", 3: "repl" }
620 | 
621 | // close resource by rid
622 | close(3);
623 | ```
624 | 
625 | #### Metrics
626 | 
627 | Metrics is deno's internal counters for various statics.
628 | 
629 | ```shellsession
630 | > console.table(Deno.metrics())
631 | ┌──────────────────┬────────┐
632 | │     (index)      │ Values │
633 | ├──────────────────┼────────┤
634 | │  opsDispatched   │   9    │
635 | │   opsCompleted   │   9    │
636 | │ bytesSentControl │  504   │
637 | │  bytesSentData   │   0    │
638 | │  bytesReceived   │  856   │
639 | └──────────────────┴────────┘
640 | ```
641 | 
642 | ### Schematic diagram
643 | 
644 | <img src="images/schematic_v0.2.png">
645 | 
646 | ### Profiling
647 | 
648 | To start profiling,
649 | 
650 | ```sh
651 | # Make sure we're only building release.
652 | # Build deno and V8's d8.
653 | ./tools/build.py --release d8 deno
654 | # Start the program we want to benchmark with --prof
655 | ./target/release/deno tests/http_bench.ts --allow-net --prof &
656 | # Exercise it.
657 | third_party/wrk/linux/wrk http://localhost:4500/
658 | kill `pgrep deno`
659 | ```
660 | 
661 | V8 will write a file in the current directory that looks like this:
662 | `isolate-0x7fad98242400-v8.log`. To examine this file:
663 | 
664 | ```sh
665 | D8_PATH=target/release/ ./third_party/v8/tools/linux-tick-processor
666 | isolate-0x7fad98242400-v8.log > prof.log
667 | # on macOS, use ./third_party/v8/tools/mac-tick-processor instead
668 | ```
669 | 
670 | `prof.log` will contain information about tick distribution of different calls.
671 | 
672 | To view the log with Web UI, generate JSON file of the log:
673 | 
674 | ```sh
675 | D8_PATH=target/release/ ./third_party/v8/tools/linux-tick-processor
676 | isolate-0x7fad98242400-v8.log --preprocess > prof.json
677 | ```
678 | 
679 | Open `third_party/v8/tools/profview/index.html` in your brower, and select
680 | `prof.json` to view the distribution graphically.
681 | 
682 | To learn more about `d8` and profiling, check out the following links:
683 | 
684 | - [https://v8.dev/docs/d8](https://v8.dev/docs/d8)
685 | - [https://v8.dev/docs/profile](https://v8.dev/docs/profile)
686 | 
687 | ### Debugging with LLDB
688 | 
689 | We can use LLDB to debug deno.
690 | 
691 | ```shellsession
692 | $ lldb -- target/debug/deno tests/worker.js
693 | > run
694 | > bt
695 | > up
696 | > up
697 | > l
698 | ```
699 | 
700 | To debug Rust code, we can use `rust-lldb`. It should come with `rustc` and is a
701 | wrapper around LLDB.
702 | 
703 | ```shellsession
704 | $ rust-lldb -- ./target/debug/deno tests/http_bench.ts --allow-net
705 | # On macOS, you might get warnings like
706 | # `ImportError: cannot import name _remove_dead_weakref`
707 | # In that case, use system python by setting PATH, e.g.
708 | # PATH=/System/Library/Frameworks/Python.framework/Versions/2.7/bin:$PATH
709 | (lldb) command script import "/Users/kevinqian/.rustup/toolchains/1.30.0-x86_64-apple-darwin/lib/rustlib/etc/lldb_rust_formatters.py"
710 | (lldb) type summary add --no-value --python-function lldb_rust_formatters.print_val -x ".*" --category Rust
711 | (lldb) type category enable Rust
712 | (lldb) target create "../deno/target/debug/deno"
713 | Current executable set to '../deno/target/debug/deno' (x86_64).
714 | (lldb) settings set -- target.run-args  "tests/http_bench.ts" "--allow-net"
715 | (lldb) b op_start
716 | (lldb) r
717 | ```
718 | 
719 | ### Deno Core
720 | 
721 | The core binding layer for Deno. It is released as a
722 | [standalone crate](https://crates.io/crates/deno). Inside of core is V8 itself,
723 | with a binding API called "libdeno". See the crate documentation for more
724 | details.
725 | 
726 | ### Flatbuffers
727 | 
728 | We use Flatbuffers to define common structs and enums between TypeScript and
729 | Rust. These common data structures are defined in
730 | [msg.fbs](https://github.com/denoland/deno/blob/master/cli/msg.fbs)
731 | 
732 | ### Updating prebuilt binaries
733 | 
734 | ```shellsession
735 | $ ./third_party/depot_tools/upload_to_google_storage.py -b denoland  \
736 |   -e ~/.config/gcloud/legacy_credentials/ry@tinyclouds.org/.boto `which sccache`
737 | $ mv `which sccache`.sha1 prebuilt/linux64/
738 | $ gsutil acl ch -u AllUsers:R gs://denoland/608be47bf01004aa11d4ed06955414e93934516e
739 | ```
740 | 
741 | ### Continuous Benchmarks
742 | 
743 | See our benchmarks [over here](https://deno.land/benchmarks.html)
744 | 
745 | The benchmark chart supposes `//website/data.json` has the type
746 | `BenchmarkData[]` where `BenchmarkData` is defined like the below:
747 | 
748 | ```ts
749 | interface ExecTimeData {
750 |   mean: number;
751 |   stddev: number;
752 |   user: number;
753 |   system: number;
754 |   min: number;
755 |   max: number;
756 | }
757 | 
758 | interface BenchmarkData {
759 |   created_at: string;
760 |   sha1: string;
761 |   benchmark: {
762 |     [key: string]: ExecTimeData;
763 |   };
764 |   binarySizeData: {
765 |     [key: string]: number;
766 |   };
767 |   threadCountData: {
768 |     [key: string]: number;
769 |   };
770 |   syscallCountData: {
771 |     [key: string]: number;
772 |   };
773 | }
774 | ```
775 | 
776 | ### Logos
777 | 
778 | These Deno logos, like the Deno software, are distributed under the MIT license
779 | (public domain and free for use)
780 | 
781 | - [A hand drawn one by @ry](https://github.com/denoland/deno/blob/master/website/images/deno_logo.png)
782 | 
783 | - [An animated one by @hashrock](https://github.com/denolib/animated-deno-logo/)
784 | 
785 | - [A high resolution SVG one by @kevinkassimo](https://github.com/denolib/high-res-deno-logo)
786 | 
787 | ## Contributing
788 | 
789 | [Style Guide](style_guide.html)
790 | 
791 | Progress towards future releases is tracked
792 | [here](https://github.com/denoland/deno/milestones).
793 | 
794 | Please don't make [the benchmarks](https://deno.land/benchmarks.html) worse.
795 | 
796 | Ask for help in the [community chat room](https://gitter.im/denolife/Lobby).
797 | 
798 | If you are going to work on an issue, mention so in the issue comments _before_
799 | you start working on the issue.
800 | 
801 | ### Submitting a pull request
802 | 
803 | Before submitting, please make sure the following is done:
804 | 
805 | 1. That there is a related issue and it is referenced in the PR text.
806 | 2. There are tests that cover the changes.
807 | 3. Ensure `./tools/test.py` passes.
808 | 4. Format your code with `tools/format.py`
809 | 5. Make sure `./tools/lint.py` passes.
810 | 
811 | ### Changes to `third_party`
812 | 
813 | [`deno_third_party`](https://github.com/denoland/deno_third_party) contains most
814 | of the external code that Deno depends on, so that we know exactly what we are
815 | executing at any given time. It is carefully maintained with a mixture of manual
816 | labor and private scripts. It's likely you will need help from @ry or
817 | @piscisaureus to make changes.
818 | 
819 | ### Adding Ops (aka bindings)
820 | 
821 | We are very concerned about making mistakes when adding new APIs. When adding an
822 | Op to Deno, the counterpart interfaces on other platforms should be researched.
823 | Please list how this functionality is done in Go, Node, Rust, and Python.
824 | 
825 | As an example, see how `Deno.rename()` was proposed and added in
826 | [PR #671](https://github.com/denoland/deno/pull/671).
827 | 
828 | ### Documenting APIs
829 | 
830 | It is important to document public APIs and we want to do that inline with the
831 | code. This helps ensure that code and documentation are tightly coupled
832 | together.
833 | 
834 | #### Utilize JSDoc
835 | 
836 | All publicly exposed APIs and types, both via the `deno` module as well as the
837 | global/`window` namespace should have JSDoc documentation. This documentation is
838 | parsed and available to the TypeScript compiler, and therefore easy to provide
839 | further downstream. JSDoc blocks come just prior to the statement they apply to
840 | and are denoted by a leading `/**` before terminating with a `*/`. For example:
841 | 
842 | ```ts
843 | /** A simple JSDoc comment */
844 | export const FOO = "foo";
845 | ```
846 | 


--------------------------------------------------------------------------------