From 1d8f3cc896ac417ceed4a28e4a001a758ab49185 Mon Sep 17 00:00:00 2001 From: Ry Dahl Date: Thu, 24 Oct 2019 16:14:05 -0400 Subject: Remove old website (#3194) Move manual.md and style_guide.md into //std so they can be accessed from https://deno.land/std/manual.md Code for new website is https://github.com/denoland/deno_website2 Co-authored-by: Christian Moritz --- website/app.ts | 480 -------------- website/app_test.ts | 199 ------ website/benchmarks.html | 273 -------- website/favicon.ico | Bin 15086 -> 0 bytes website/images/deno_logo.png | Bin 22719 -> 0 bytes website/images/deno_logo_3.svg | 92 --- website/images/deno_logo_4.gif | Bin 24896 -> 0 bytes website/images/schematic_v0.2.png | Bin 58275 -> 0 bytes website/index.html | 151 ----- website/manual.html | 54 -- website/manual.md | 1280 ------------------------------------- website/rustdoc | 1 - website/showdown_toc.js | 143 ----- website/style.css | 209 ------ website/style_guide.html | 55 -- website/style_guide.md | 304 --------- website/typedoc | 1 - website/welcome.ts | 1 - 18 files changed, 3243 deletions(-) delete mode 100644 website/app.ts delete mode 100644 website/app_test.ts delete mode 100644 website/benchmarks.html delete mode 100644 website/favicon.ico delete mode 100644 website/images/deno_logo.png delete mode 100644 website/images/deno_logo_3.svg delete mode 100644 website/images/deno_logo_4.gif delete mode 100644 website/images/schematic_v0.2.png delete mode 100644 website/index.html delete mode 100644 website/manual.html delete mode 100644 website/manual.md delete mode 120000 website/rustdoc delete mode 100644 website/showdown_toc.js delete mode 100644 website/style.css delete mode 100644 website/style_guide.html delete mode 100644 website/style_guide.md delete mode 120000 website/typedoc delete mode 100644 website/welcome.ts (limited to 'website') diff --git a/website/app.ts b/website/app.ts deleted file mode 100644 index 809be51bb..000000000 --- a/website/app.ts +++ /dev/null @@ -1,480 +0,0 @@ -// Copyright 2018-2019 the Deno authors. All rights reserved. MIT license. - -// How much to multiply time values in order to process log graphs properly. -const TimeScaleFactor = 10000; - -export interface BenchmarkExecTimeResult { - min?: number; - max?: number; - mean?: number; - stddev?: number; - system?: number; - user?: number; -} - -export interface BenchmarkExecTimeResultSet { - [variant: string]: BenchmarkExecTimeResult; -} - -export interface BenchmarkVariantsResultSet { - [variant: string]: number; -} - -export interface BenchmarkRun { - created_at: string; - sha1: string; - benchmark: BenchmarkExecTimeResultSet; - binary_size?: BenchmarkVariantsResultSet | number; - max_memory?: BenchmarkVariantsResultSet | number; - bundle_size?: BenchmarkVariantsResultSet; - max_latency?: BenchmarkVariantsResultSet; - req_per_sec?: BenchmarkVariantsResultSet; - req_per_sec_proxy?: BenchmarkVariantsResultSet; - syscall_count?: BenchmarkVariantsResultSet; - thread_count?: BenchmarkVariantsResultSet; - throughput?: BenchmarkVariantsResultSet; -} - -export type BenchmarkName = Exclude; - -type Column = [string, ...Array]; - -interface C3DataNode { - id: string; - index: number; - name: string; - value: number; - x: number; -} - -type C3OnClickCallback = (C3DataNode, unknown) => void; -type C3OnRenderedCallback = () => void; -type C3TickFormatter = (number) => number | string; - -export async function getJson(path: string): Promise { - return (await fetch(path)).json(); -} - -function getBenchmarkVarieties( - data: BenchmarkRun[], - benchmarkName: BenchmarkName -): string[] { - // Look at last sha hash. - const last = data[data.length - 1]; - return Object.keys(last[benchmarkName]); -} - -export function createColumns( - data: BenchmarkRun[], - benchmarkName: BenchmarkName -): Column[] { - const varieties = getBenchmarkVarieties(data, benchmarkName); - return varieties.map(variety => [ - variety, - ...data.map(d => { - if (d[benchmarkName] != null) { - if (d[benchmarkName][variety] != null) { - const v = d[benchmarkName][variety]; - if (benchmarkName == "benchmark") { - const meanValue = v ? v.mean : 0; - return meanValue || null; - } else { - return v; - } - } - } - return null; - }) - ]); -} - -export function createNormalizedColumns( - data: BenchmarkRun[], - benchmarkName: BenchmarkName, - baselineBenchmark: BenchmarkName, - baselineVariety: string -): Column[] { - const varieties = getBenchmarkVarieties(data, benchmarkName); - return varieties.map(variety => [ - variety, - ...data.map(d => { - if (d[baselineBenchmark] != null) { - if (d[baselineBenchmark][baselineVariety] != null) { - const baseline = d[baselineBenchmark][baselineVariety]; - if (d[benchmarkName] != null) { - if (d[benchmarkName][variety] != null && baseline != 0) { - const v = d[benchmarkName][variety]; - if (benchmarkName == "benchmark") { - const meanValue = v ? v.mean : 0; - return meanValue || null; - } else { - return v / baseline; - } - } - } - } - } - return null; - }) - ]); -} - -export function createExecTimeColumns(data: BenchmarkRun[]): Column[] { - return createColumns(data, "benchmark"); -} - -export function createThroughputColumns(data: BenchmarkRun[]): Column[] { - return createColumns(data, "throughput"); -} - -export function createProxyColumns(data: BenchmarkRun[]): Column[] { - return createColumns(data, "req_per_sec_proxy"); -} - -export function createNormalizedProxyColumns(data: BenchmarkRun[]): Column[] { - return createNormalizedColumns( - data, - "req_per_sec_proxy", - "req_per_sec", - "hyper" - ); -} - -export function createReqPerSecColumns(data: BenchmarkRun[]): Column[] { - return createColumns(data, "req_per_sec"); -} - -export function createNormalizedReqPerSecColumns( - data: BenchmarkRun[] -): Column[] { - return createNormalizedColumns(data, "req_per_sec", "req_per_sec", "hyper"); -} - -export function createMaxLatencyColumns(data: BenchmarkRun[]): Column[] { - return createColumns(data, "max_latency"); -} - -export function createMaxMemoryColumns(data: BenchmarkRun[]): Column[] { - return createColumns(data, "max_memory"); -} - -export function createBinarySizeColumns(data: BenchmarkRun[]): Column[] { - const propName = "binary_size"; - const binarySizeNames = Object.keys(data[data.length - 1][propName]); - return binarySizeNames.map(name => [ - name, - ...data.map(d => { - const binarySizeData = d["binary_size"]; - switch (typeof binarySizeData) { - case "number": // legacy implementation - return name === "deno" ? binarySizeData : 0; - default: - if (!binarySizeData) { - return null; - } - return binarySizeData[name] || null; - } - }) - ]); -} - -export function createThreadCountColumns(data: BenchmarkRun[]): Column[] { - const propName = "thread_count"; - const threadCountNames = Object.keys(data[data.length - 1][propName]); - return threadCountNames.map(name => [ - name, - ...data.map(d => { - const threadCountData = d[propName]; - if (!threadCountData) { - return null; - } - return threadCountData[name] || null; - }) - ]); -} - -export function createSyscallCountColumns(data: BenchmarkRun[]): Column[] { - const propName = "syscall_count"; - const syscallCountNames = Object.keys(data[data.length - 1][propName]); - return syscallCountNames.map(name => [ - name, - ...data.map(d => { - const syscallCountData = d[propName]; - if (!syscallCountData) { - return null; - } - return syscallCountData[name] || null; - }) - ]); -} - -export function createBundleSizeColumns(data: BenchmarkRun[]): Column[] { - return createColumns(data, "bundle_size"); -} - -export function createSha1List(data: BenchmarkRun[]): string[] { - return data.map(d => d.sha1); -} - -export function formatKB(bytes: number): string { - return (bytes / 1024).toFixed(2); -} - -export function formatMB(bytes: number): string { - return (bytes / (1024 * 1024)).toFixed(2); -} - -export function formatReqSec(reqPerSec: number): string { - return (reqPerSec / 1000).toFixed(3); -} - -export function formatPercentage(decimal: number): string { - return (decimal * 100).toFixed(2); -} - -/** - * @param {string} id The id of dom element - * @param {string[]} categories categories for x-axis values - * @param {any[][]} columns The columns data - * @param {function} onclick action on clicking nodes of chart - * @param {string} yLabel label of y axis - * @param {function} yTickFormat formatter of y axis ticks - * @param {boolean} zoomEnabled enables the zoom feature - */ -function generate( - id: string, - categories: string[], - columns: Column[], - onclick: C3OnClickCallback, - yLabel = "", - yTickFormat?: C3TickFormatter, - zoomEnabled = true, - onrendered?: C3OnRenderedCallback -): void { - const yAxis = { - padding: { bottom: 0 }, - min: 0, - label: yLabel, - tick: null - }; - if (yTickFormat) { - yAxis.tick = { - format: yTickFormat - }; - if (yTickFormat == logScale) { - delete yAxis.min; - for (const col of columns) { - for (let i = 1; i < col.length; i++) { - if (col[i] == null || col[i] === 0) { - continue; - } - col[i] = Math.log10((col[i] as number) * TimeScaleFactor); - } - } - } - } - - // @ts-ignore - c3.generate({ - bindto: id, - onrendered, - data: { - columns, - onclick - }, - axis: { - x: { - type: "category", - show: false, - categories - }, - y: yAxis - }, - zoom: { - enabled: zoomEnabled - } - }); -} - -function logScale(t: number): string { - return (Math.pow(10, t) / TimeScaleFactor).toFixed(4); -} - -/** - * @param dataUrl The url of benchmark data json. - */ -export function drawCharts(dataUrl: string): Promise { - // TODO Using window["location"]["hostname"] instead of - // window.location.hostname because when deno runs app_test.js it gets a type - // error here, not knowing about window.location. Ideally Deno would skip - // type check entirely on JS files. - if (window["location"]["hostname"] != "deno.github.io") { - dataUrl = "https://denoland.github.io/deno/" + dataUrl; - } - return drawChartsFromBenchmarkData(dataUrl); -} - -const proxyFields: BenchmarkName[] = ["req_per_sec"]; -function extractProxyFields(data: BenchmarkRun[]): void { - for (const row of data) { - for (const field of proxyFields) { - const d = row[field]; - if (!d) continue; - const name = field + "_proxy"; - const newField = {}; - row[name] = newField; - for (const k of Object.getOwnPropertyNames(d)) { - if (k.includes("_proxy")) { - const v = d[k]; - delete d[k]; - newField[k] = v; - } - } - } - } -} -/** - * Draws the charts from the benchmark data stored in gh-pages branch. - */ -export async function drawChartsFromBenchmarkData( - dataUrl: string -): Promise { - const data = (await getJson(dataUrl)) as BenchmarkRun[]; - - // hack to extract proxy fields from req/s fields - extractProxyFields(data); - - const execTimeColumns = createExecTimeColumns(data); - const throughputColumns = createThroughputColumns(data); - const reqPerSecColumns = createReqPerSecColumns(data); - const normalizedReqPerSecColumns = createNormalizedReqPerSecColumns(data); - const proxyColumns = createProxyColumns(data); - const normalizedProxyColumns = createNormalizedProxyColumns(data); - const maxLatencyColumns = createMaxLatencyColumns(data); - const maxMemoryColumns = createMaxMemoryColumns(data); - const binarySizeColumns = createBinarySizeColumns(data); - const threadCountColumns = createThreadCountColumns(data); - const syscallCountColumns = createSyscallCountColumns(data); - const bundleSizeColumns = createBundleSizeColumns(data); - const sha1List = createSha1List(data); - const sha1ShortList = sha1List.map(sha1 => sha1.substring(0, 6)); - - function viewCommitOnClick(d: C3DataNode, _: unknown): void { - // @ts-ignore - window.open(`https://github.com/denoland/deno/commit/${sha1List[d.index]}`); - } - - function gen( - id: string, - columns: Column[], - yLabel = "", - yTickFormat?: C3TickFormatter, - onrendered?: C3OnRenderedCallback - ): void { - generate( - id, - sha1ShortList, - columns, - viewCommitOnClick, - yLabel, - yTickFormat, - true, - onrendered - ); - } - - gen("#exec-time-chart", execTimeColumns, "seconds", logScale); - gen("#throughput-chart", throughputColumns, "seconds", logScale); - gen("#req-per-sec-chart", reqPerSecColumns, "1000 req/sec", formatReqSec); - gen( - "#normalized-req-per-sec-chart", - normalizedReqPerSecColumns, - "% of hyper througput", - formatPercentage, - hideOnRender("normalized-req-per-sec-chart") - ); - gen("#proxy-req-per-sec-chart", proxyColumns, "req/sec"); - gen( - "#normalized-proxy-req-per-sec-chart", - normalizedProxyColumns, - "% of hyper througput", - formatPercentage, - hideOnRender("normalized-proxy-req-per-sec-chart") - ); - gen("#max-latency-chart", maxLatencyColumns, "milliseconds", logScale); - gen("#max-memory-chart", maxMemoryColumns, "megabytes", formatMB); - gen("#binary-size-chart", binarySizeColumns, "megabytes", formatMB); - gen("#thread-count-chart", threadCountColumns, "threads"); - gen("#syscall-count-chart", syscallCountColumns, "syscalls"); - gen("#bundle-size-chart", bundleSizeColumns, "kilobytes", formatKB); -} - -function hideOnRender(elementID: string): C3OnRenderedCallback { - return (): void => { - const chart = window["document"].getElementById(elementID); - if (!chart.getAttribute("data-inital-hide-done")) { - chart.setAttribute("data-inital-hide-done", "true"); - chart.classList.add("hidden"); - } - }; -} - -function registerNormalizedSwitcher( - checkboxID: string, - chartID: string, - normalizedChartID: string -): void { - const checkbox = window["document"].getElementById(checkboxID); - const regularChart = window["document"].getElementById(chartID); - const normalizedChart = window["document"].getElementById(normalizedChartID); - - checkbox.addEventListener("change", _ => { - // If checked is true the normalized variant should be shown - // @ts-ignore - if (checkbox.checked) { - regularChart.classList.add("hidden"); - normalizedChart.classList.remove("hidden"); - } else { - normalizedChart.classList.add("hidden"); - regularChart.classList.remove("hidden"); - } - }); -} - -export function main(): void { - window["chartWidth"] = 800; - const overlay = window["document"].getElementById("spinner-overlay"); - - function showSpinner(): void { - overlay.style.display = "block"; - } - - function hideSpinner(): void { - overlay.style.display = "none"; - } - - function updateCharts(): void { - const u = window.location.hash.match("all") ? "./data.json" : "recent.json"; - - showSpinner(); - - drawCharts(u) - .then(hideSpinner) - .catch(hideSpinner); - } - updateCharts(); - - registerNormalizedSwitcher( - "req-per-sec-chart-show-normalized", - "req-per-sec-chart", - "normalized-req-per-sec-chart" - ); - - registerNormalizedSwitcher( - "proxy-req-per-sec-chart-show-normalized", - "proxy-req-per-sec-chart", - "normalized-proxy-req-per-sec-chart" - ); - - window["onhashchange"] = updateCharts; -} diff --git a/website/app_test.ts b/website/app_test.ts deleted file mode 100644 index ebc8699f6..000000000 --- a/website/app_test.ts +++ /dev/null @@ -1,199 +0,0 @@ -// Copyright 2018-2019 the Deno authors. All rights reserved. MIT license. - -import { test, assertEquals } from "../cli/js/test_util.ts"; -import { runIfMain } from "../std/testing/mod.ts"; -import { - BenchmarkRun, - createBinarySizeColumns, - createExecTimeColumns, - createThreadCountColumns, - createSyscallCountColumns, - createSha1List -} from "./app.ts"; - -/* eslint-disable @typescript-eslint/camelcase */ -const regularData: BenchmarkRun[] = [ - { - created_at: "2018-01-01T01:00:00Z", - sha1: "abcdef", - binary_size: { - deno: 100000000, - "main.js": 90000000, - "main.js.map": 80000000, - "snapshot_deno.bin": 70000000 - }, - throughput: { - "100M_tcp": 3.6, - "100M_cat": 3.0, - "10M_tcp": 1.6, - "10M_cat": 1.0 - }, - req_per_sec: { - node: 16000, - deno: 1000 - }, - benchmark: { - hello: { - mean: 0.05 - }, - relative_import: { - mean: 0.06 - }, - cold_hello: { - mean: 0.05 - }, - cold_relative_import: { - mean: 0.06 - } - }, - thread_count: { - set_timeout: 4, - fetch_deps: 6 - }, - syscall_count: { - hello: 600, - fetch_deps: 700 - } - }, - { - created_at: "2018-01-02T01:00:00Z", - sha1: "012345", - binary_size: { - deno: 100000001, - "main.js": 90000001, - "main.js.map": 80000001, - "snapshot_deno.bin": 70000001 - }, - throughput: { - "100M_tcp": 3.6, - "100M_cat": 3.0, - "10M_tcp": 1.6, - "10M_cat": 1.0 - }, - req_per_sec: { - node: 1600, - deno: 3.0 - }, - benchmark: { - hello: { - mean: 0.055 - }, - relative_import: { - mean: 0.065 - }, - cold_hello: { - mean: 0.055 - }, - cold_relative_import: { - mean: 0.065 - } - }, - thread_count: { - set_timeout: 5, - fetch_deps: 7 - }, - syscall_count: { - hello: 700, - fetch_deps: 800 - } - } -]; - -const irregularData: BenchmarkRun[] = [ - { - created_at: "2018-01-01T01:00:00Z", - sha1: "123", - benchmark: {}, - throughput: {}, - binary_size: {}, - thread_count: {}, - syscall_count: {} - }, - { - created_at: "2018-02-01T01:00:00Z", - sha1: "456", - benchmark: { - hello: {}, - relative_import: {}, - cold_hello: {}, - cold_relative_import: {} - }, - throughput: { - "100M_tcp": 3.0 - }, - binary_size: { - deno: 1 - }, - thread_count: { - set_timeout: 5, - fetch_deps: 7 - }, - syscall_count: { - hello: 700, - fetch_deps: 800 - } - } -]; -/* eslint-enable @typescript-eslint/camelcase */ - -test(function createExecTimeColumnsRegularData() { - const columns = createExecTimeColumns(regularData); - assertEquals(columns, [ - ["hello", 0.05, 0.055], - ["relative_import", 0.06, 0.065], - ["cold_hello", 0.05, 0.055], - ["cold_relative_import", 0.06, 0.065] - ]); -}); - -test(function createExecTimeColumnsIrregularData() { - const columns = createExecTimeColumns(irregularData); - assertEquals(columns, [ - ["hello", null, null], - ["relative_import", null, null], - ["cold_hello", null, null], - ["cold_relative_import", null, null] - ]); -}); - -test(function createBinarySizeColumnsRegularData() { - const columns = createBinarySizeColumns(regularData); - assertEquals(columns, [ - ["deno", 100000000, 100000001], - ["main.js", 90000000, 90000001], - ["main.js.map", 80000000, 80000001], - ["snapshot_deno.bin", 70000000, 70000001] - ]); -}); - -test(function createBinarySizeColumnsIrregularData() { - const columns = createBinarySizeColumns(irregularData); - assertEquals(columns, [["deno", null, 1]]); -}); - -test(function createThreadCountColumnsRegularData() { - const columns = createThreadCountColumns(regularData); - assertEquals(columns, [["set_timeout", 4, 5], ["fetch_deps", 6, 7]]); -}); - -test(function createThreadCountColumnsIrregularData() { - const columns = createThreadCountColumns(irregularData); - assertEquals(columns, [["set_timeout", null, 5], ["fetch_deps", null, 7]]); -}); - -test(function createSyscallCountColumnsRegularData() { - const columns = createSyscallCountColumns(regularData); - assertEquals(columns, [["hello", 600, 700], ["fetch_deps", 700, 800]]); -}); - -test(function createSyscallCountColumnsIrregularData() { - const columns = createSyscallCountColumns(irregularData); - assertEquals(columns, [["hello", null, 700], ["fetch_deps", null, 800]]); -}); - -test(function createSha1ListRegularData() { - const sha1List = createSha1List(regularData); - assertEquals(sha1List, ["abcdef", "012345"]); -}); - -runIfMain(import.meta); diff --git a/website/benchmarks.html b/website/benchmarks.html deleted file mode 100644 index 80a47f03c..000000000 --- a/website/benchmarks.html +++ /dev/null @@ -1,273 +0,0 @@ - - - - - Deno Benchmarks - - - - - - -
-
- ` -
-
- -

Deno Continuous Benchmarks

- -

- These plots are updated on every commit to - master branch. -

- -

- Make sure your adblocker is disabled as some can block the chart - rendering. -

- -

recent data

-

all data (takes a moment to load)

- -

Req/Sec #

- -

- Tests HTTP server performance. 10 keep-alive connections do as many - hello-world requests as possible. Bigger is better. -

- - - -
- -
- - - - -

- Proxy Req/Sec # -

- -

- Tests proxy performance. 10 keep-alive connections do as many - hello-world requests as possible. Bigger is better. -

- -
    -
  • - deno_proxy_tcp - is a fake tcp proxy server that doesn't parse HTTP. It is comparable - to - node_proxy_tcp - . -
  • - -
  • - deno_proxy - is an HTTP proxy server written in TypeScript. It is comparable to - node_proxy - . -
  • - -
  • - - hyper - - is a Rust HTTP server used as the origin for the proxy tests -
  • -
- -
- -
- - - - -

Max Latency #

- -

- Max latency during the same test used above for requests/second. Smaller - is better. -

- -
- -

Execution time #

-

- This shows how much time total it takes to run a few simple deno - programs: - - tests/002_hello.ts , - tests/003_relative_import.ts, - cli/tests/text_decoder_perf.js, - tests/workers_round_robin_bench.ts, and - tests/workers_startup_bench.ts. For deno to execute typescript, it must first compile it to JS. A - warm startup is when deno has a cached JS output already, so it should - be fast because it bypasses the TS compiler. A cold startup is when deno - must compile from scratch. -

-
- -

Throughput #

- -

- Time it takes to pipe a certain amount of data through Deno. - - - echo_server.ts - - and - - cat.ts . Smaller is better. -

- -
- -

Max Memory Usage #

- -

- Max memory usage during execution. Smaller is better. -

- -
- -

Executable size #

-

deno ships only a single binary. We track its size here.

-
- -

Thread count #

-

How many threads various programs use.

-
- -

Syscall count #

-

- How many total syscalls are performed when executing a given script. -

-
- -

Bundle size #

-

- Size of different bundled scripts. -

- - - -
-
- - - - - - - - - diff --git a/website/favicon.ico b/website/favicon.ico deleted file mode 100644 index 816402bca..000000000 Binary files a/website/favicon.ico and /dev/null differ diff --git a/website/images/deno_logo.png b/website/images/deno_logo.png deleted file mode 100644 index 24f62512e..000000000 Binary files a/website/images/deno_logo.png and /dev/null differ diff --git a/website/images/deno_logo_3.svg b/website/images/deno_logo_3.svg deleted file mode 100644 index 21e51d193..000000000 --- a/website/images/deno_logo_3.svg +++ /dev/null @@ -1,92 +0,0 @@ - - - - -Created by potrace 1.15, written by Peter Selinger 2001-2017 - - - - - - - diff --git a/website/images/deno_logo_4.gif b/website/images/deno_logo_4.gif deleted file mode 100644 index 5514ffb49..000000000 Binary files a/website/images/deno_logo_4.gif and /dev/null differ diff --git a/website/images/schematic_v0.2.png b/website/images/schematic_v0.2.png deleted file mode 100644 index abf7b1f2e..000000000 Binary files a/website/images/schematic_v0.2.png and /dev/null differ diff --git a/website/index.html b/website/index.html deleted file mode 100644 index 38c0092c7..000000000 --- a/website/index.html +++ /dev/null @@ -1,151 +0,0 @@ - - - - - Deno - - - - - - - - - - -
-
- -
-

Deno

- A secure runtime for JavaScript and TypeScript built with V8, Rust, and Tokio -
-
- - - - - - - - - - - - - - - - - - - - -
Linux & MacWindows
deno - - - -
- deno_install - - - - - - - - -
registry - - - -
- -

Install #

- -

Using Shell:

-
curl -fsSL https://deno.land/x/install/install.sh | sh
-

Or using PowerShell:

-
iwr https://deno.land/x/install/install.ps1 -useb | iex
-

Using Homebrew (mac):

-
brew install deno
-

Using Scoop (windows): -

scoop install deno
-

Using Cargo: -

cargo install deno_cli
-

See deno_install for more installation options.

- -

Example #

- -

Try running a simple program:

-
deno https://deno.land/welcome.ts
- -

Or a more complex one:

- -
import { serve } from "https://deno.land/std@v0.19.0/http/server.ts";
-const body = new TextEncoder().encode("Hello World\n");
-const s = serve(":8000");
-window.onload = async () => {
-  console.log("http://localhost:8000/");
-  for await (const req of s) {
-    req.respond({ body });
-  }
-};
- -

Dig in... #

- -

- Manual -

- -

API Reference

- -

- Standard Modules -

- -

Style Guide

- -

Module repository

- -

Twitter Account

- -

- Release notes -

- -

Community chat room

- -

Benchmarks

- -

- A curated list of awesome Deno things -

- - - -
- - diff --git a/website/manual.html b/website/manual.html deleted file mode 100644 index bc5624bfa..000000000 --- a/website/manual.html +++ /dev/null @@ -1,54 +0,0 @@ - - - - - Deno Manual - - - - - - - - - - -
- -
- - - - -
- - diff --git a/website/manual.md b/website/manual.md deleted file mode 100644 index 045aaab34..000000000 --- a/website/manual.md +++ /dev/null @@ -1,1280 +0,0 @@ -# Deno Manual - -[toc] - -## Project Status / Disclaimer - -**A word of caution: Deno is very much under development.** - -We encourage brave early adopters, but expect bugs large and small. The API is -subject to change without notice. -[Bug reports](https://github.com/denoland/deno/issues) do help! - -We are -[actively working towards 1.0](https://github.com/denoland/deno/issues/2473), -but there is no date guarantee. - -## Introduction - -Deno is a JavaScript/TypeScript runtime with secure defaults and a great -developer experience. - -It's built on V8, Rust, and Tokio. - -### Feature Highlights - -- Secure by default. No file, network, or environment access (unless explicitly - enabled). -- Supports TypeScript out of the box. -- Ships a single executable (`deno`). -- Has built in utilities like a dependency inspector (`deno info`) and a code - formatter (`deno fmt`). -- Has - [a set of reviewed (audited) standard modules](https://github.com/denoland/deno/tree/master/std) - that are guaranteed to work with Deno. -- Scripts can be bundled into a single javascript file. - -### Philosophy - -Deno aims to be a productive and secure scripting environment for the modern -programmer. - -Deno will always be distributed as a single executable. Given a URL to a Deno -program, it is runnable with nothing more than -[the 10 megabyte zipped executable](https://github.com/denoland/deno/releases). -Deno explicitly takes on the role of both runtime and package manager. It uses a -standard browser-compatible protocol for loading modules: URLs. - -Among other things, Deno is a great replacement for utility scripts that may -have been historically written with bash or python. - -### Goals - -- Only ship a single executable (`deno`). -- Provide Secure Defaults - - Unless specifically allowed, scripts can't access files, the environment, or - the network. -- Browser compatible: The subset of Deno programs which are written completely - in JavaScript and do not use the global `Deno` namespace (or feature test for - it), ought to also be able to be run in a modern web browser without change. -- Provide built-in tooling like unit testing, code formatting, and linting to - improve developer experience. -- Does not leak V8 concepts into user land. -- Be able to serve HTTP efficiently - -### Comparison to Node.js - -- Deno does not use `npm` - - It uses modules referenced as URLs or file paths -- Deno does not use `package.json` in its module resolution algorithm. -- All async actions in Deno return a promise. Thus Deno provides different APIs - than Node. -- Deno requires explicit permissions for file, network, and environment access. -- Deno always dies on uncaught errors. -- Uses "ES Modules" and does not support `require()`. Third party modules are - imported via URLs: - -```javascript -import * as log from "https://deno.land/std/log/mod.ts"; -``` - -### Other key behaviors - -- Remote code is fetched and cached on first execution, and never updated until - the code is run with the `--reload` flag. (So, this will still work on an - airplane.) -- Modules/files loaded from remote URLs are intended to be immutable and - cacheable. - -## Built-in Deno Utilities / Commands - - - - -- dependency inspector (`deno info`) -- code formatter (`deno fmt`) -- bundling (`deno bundle`) -- runtime type info (`deno types`) -- test runner (`deno test`) -- command-line debugger (`--debug`) [coming soon](https://github.com/denoland/deno/issues/1120) -- linter (`deno lint`) [coming soon](https://github.com/denoland/deno/issues/1880) - - - -## Setup - -### Binary Install - -Deno works on OSX, Linux, and Windows. Deno is a single binary executable. It -has no external dependencies. - -[deno_install](https://github.com/denoland/deno_install) provides convenience -scripts to download and install the binary. - -Using Shell: - -```shell -curl -fsSL https://deno.land/x/install/install.sh | sh -``` - -Using PowerShell: - -```shell -iwr https://deno.land/x/install/install.ps1 -useb | iex -``` - -Using [Scoop](https://scoop.sh/) (windows): - -```shell -scoop install deno -``` - -Using [Homebrew](https://brew.sh/) (mac): - -```shell -brew install deno -``` - -To install from source: - -```shell -cargo install deno_cli -``` - -Deno binaries can also be installed manually, by downloading a tarball or zip -file at -[github.com/denoland/deno/releases](https://github.com/denoland/deno/releases). -These packages contain just a single executable file. You will have to set the -executable bit on Mac and Linux. - -Once it's installed and in your `$PATH`, try it: - -```shell -deno https://deno.land/welcome.ts -``` - -### Build from source - -Clone on Linux or Mac: - -```bash -git clone --recurse-submodules https://github.com/denoland/deno.git -``` - -On Windows, a couple extra steps are required to clone because we use symlinks -in the repository. First -[enable "Developer Mode"](https://www.google.com/search?q=windows+enable+developer+mode) -(otherwise symlinks would require administrator privileges). Then you must set -`core.symlinks=true` before the checkout is started. - -```bash -git config --global core.symlinks=true -git clone --recurse-submodules https://github.com/denoland/deno.git -``` - -Now we can start the build: - -```bash -# Build. -cargo build -vv - -# Run. -./target/debug/deno tests/002_hello.ts - -# Test. -cargo test - -# Format code. -./tools/format.py -``` - -#### Prerequisites - -To ensure reproducible builds, Deno has most of its dependencies in a git -submodule. However, you need to install separately: - -1. [Rust](https://www.rust-lang.org/en-US/install.html) >= 1.36.0 -2. Python 2. - [Not 3](https://github.com/denoland/deno/issues/464#issuecomment-411795578). - -Extra steps for Mac users: install [XCode](https://developer.apple.com/xcode/) -:( - -Extra steps for Windows users: - - - - -1. Add `python.exe` to `PATH` (e.g. `set PATH=%PATH%;C:\Python27\python.exe`) -2. Get [VS Community 2017](https://www.visualstudio.com/downloads/) with - "Desktop development with C++" toolkit and make sure to select the following - required tools listed below along with all C++ tools. - - Windows 10 SDK >= 10.0.17134 - - Visual C++ ATL for x86 and x64 - - Visual C++ MFC for x86 and x64 - - C++ profiling tools -3. Enable "Debugging Tools for Windows". Go to "Control Panel" → "Programs" → - "Programs and Features" → Select "Windows Software Development Kit - Windows - 10" → "Change" → "Change" → Check "Debugging Tools For Windows" → "Change" -> - "Finish". -4. Make sure you are using git version 2.19.2.windows.1 or newer. - - - -#### Other useful commands - -```bash -# Call ninja manually. -ninja -C target/debug - -# Build a release binary. -cargo build --release - -# List executable targets. -gn --root=core/libdeno ls target/debug "//:*" --as=output --type=executable - -# List build configuration. -gn --root=core/libdeno args target/debug/ --list - -# Edit build configuration. -gn --root=core/libdeno args target/debug/ - -# Describe a target. -gn --root=core/libdeno desc target/debug/ :deno -gn help - -# Update third_party modules -git submodule update - -# Skip downloading binary build tools and point the build -# to the system provided ones (for packagers of deno ...). -export DENO_BUILD_ARGS="clang_base_path=/usr clang_use_chrome_plugins=false" -DENO_NO_BINARY_DOWNLOAD=1 DENO_GN_PATH=/usr/bin/gn cargo build -``` - -Environment variables: `DENO_BUILD_MODE`, `DENO_BUILD_PATH`, `DENO_BUILD_ARGS`, -`DENO_DIR`, `DENO_GN_PATH`, `DENO_NO_BINARY_DOWNLOAD`. - -## API reference - -### deno types - -To get an exact reference of deno's runtime API, run the following in the -command line: - -```shell -$ deno types -``` - -[This is what the output looks like.](https://gist.github.com/ry/46da4724168cdefa763e13207d27ede5) - -### Reference websites - -[TypeScript Deno API](https://deno.land/typedoc/index.html). - -If you are embedding deno in a Rust program, see -[Rust Deno API](https://docs.rs/deno). - -The Deno crate is hosted on [crates.io](https://crates.io/crates/deno). - -## Examples - -### An implementation of the unix "cat" program - -In this program each command-line argument is assumed to be a filename, the file -is opened, and printed to stdout. - -```ts -for (let i = 1; i < Deno.args.length; i++) { - let filename = Deno.args[i]; - let file = await Deno.open(filename); - await Deno.copy(Deno.stdout, file); - file.close(); -} -``` - -The `copy()` function here actually makes no more than the necessary kernel -> -userspace -> kernel copies. That is, the same memory from which data is read -from the file, is written to stdout. This illustrates a general design goal for -I/O streams in Deno. - -Try the program: - -```shell -$ deno --allow-read https://deno.land/std/examples/cat.ts /etc/passwd -``` - -### TCP echo server - -This is an example of a simple server which accepts connections on port 8080, -and returns to the client anything it sends. - -```ts -const listener = Deno.listen({ port: 8080 }); -console.log("listening on 0.0.0.0:8080"); -while (true) { - const conn = await listener.accept(); - Deno.copy(conn, conn); -} -``` - -When this program is started, it throws PermissionDenied error. - -```shell -$ deno https://deno.land/std/examples/echo_server.ts -error: Uncaught PermissionDenied: run again with the --allow-net flag -► $deno$/dispatch_json.ts:40:11 - at DenoError ($deno$/errors.ts:20:5) - ... -``` - -For security reasons, Deno does not allow programs to access the network without -explicit permission. To allow accessing the network, use a command-line flag: - -```shell -$ deno --allow-net https://deno.land/std/examples/echo_server.ts -``` - -To test it, try sending data to it with netcat: - -```shell -$ nc localhost 8080 -hello world -hello world -``` - -Like the `cat.ts` example, the `copy()` function here also does not make -unnecessary memory copies. It receives a packet from the kernel and sends back, -without further complexity. - -### Inspecting and revoking permissions - -Sometimes a program may want to revoke previously granted permissions. When a -program, at a later stage, needs those permissions, it will fail. - -```ts -const { permissions, revokePermission, open, remove } = Deno; - -// lookup a permission -if (!permissions().write) { - throw new Error("need write permission"); -} - -const log = await open("request.log", "a+"); - -// revoke some permissions -revokePermission("read"); -revokePermission("write"); - -// use the log file -const encoder = new TextEncoder(); -await log.write(encoder.encode("hello\n")); - -// this will fail. -await remove("request.log"); -``` - -### File server - -This one serves a local directory in HTTP. - -```bash -deno install file_server https://deno.land/std/http/file_server.ts --allow-net --allow-read -``` - -Run it: - -```shell -$ file_server . -Downloading https://deno.land/std/http/file_server.ts... -[...] -HTTP server listening on http://0.0.0.0:4500/ -``` - -And if you ever want to upgrade to the latest published version: - -```shell -$ file_server --reload -``` - -### Reload specific modules - -Sometimes we want to upgrade only some modules. You can control it by passing an -argument to a `--reload` flag. - -To reload everything - -`--reload` - -To reload all standard modules - -`--reload=https://deno.land/std` - -To reload specific modules (in this example - colors and file system utils) use -a comma to separate URLs - -`--reload=https://deno.land/std/fs/utils.ts,https://deno.land/std/fmt/colors.ts` - -### Permissions whitelist - -Deno also provides permissions whitelist. - -This is an example to restrict File system access by whitelist. - -```shell -$ deno --allow-read=/usr https://deno.land/std/examples/cat.ts /etc/passwd -error: Uncaught PermissionDenied: run again with the --allow-read flag -► $deno$/dispatch_json.ts:40:11 - at DenoError ($deno$/errors.ts:20:5) - ... -``` - -You can grant read permission under `/etc` dir - -```shell -$ deno --allow-read=/etc https://deno.land/std/examples/cat.ts /etc/passwd -``` - -`--allow-write` works same as `--allow-read`. - -This is an example to restrict host. - -```ts -const result = await fetch("https://deno.land/"); -``` - -```shell -$ deno --allow-net=deno.land https://deno.land/std/examples/curl.ts https://deno.land/ -``` - -### Run subprocess - -[API Reference](https://deno.land/typedoc/index.html#run) - -Example: - -```ts -// create subprocess -const p = Deno.run({ - args: ["echo", "hello"] -}); - -// await its completion -await p.status(); -``` - -Run it: - -```shell -$ deno --allow-run ./subprocess_simple.ts -hello -``` - -Here a function is assigned to `window.onload`. This function is called after -the main script is loaded. This is the same as -[onload](https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onload) -of the browsers, and it can be used as the main entrypoint. - -By default when you use `Deno.run()` subprocess inherits `stdin`, `stdout` and -`stderr` of parent process. If you want to communicate with started subprocess -you can use `"piped"` option. - -```ts -const fileNames = Deno.args.slice(1); - -const p = Deno.run({ - args: [ - "deno", - "run", - "--allow-read", - "https://deno.land/std/examples/cat.ts", - ...fileNames - ], - stdout: "piped", - stderr: "piped" -}); - -const { code } = await p.status(); - -if (code === 0) { - const rawOutput = await p.output(); - await Deno.stdout.write(rawOutput); -} else { - const rawError = await p.stderrOutput(); - const errorString = new TextDecoder().decode(rawError); - console.log(errorString); -} - -Deno.exit(code); -``` - -When you run it: - -```shell -$ deno run --allow-run ./subprocess.ts -[file content] - -$ deno run --allow-run ./subprocess.ts non_existent_file.md - -Uncaught NotFound: No such file or directory (os error 2) - at DenoError (deno/js/errors.ts:22:5) - at maybeError (deno/js/errors.ts:41:12) - at handleAsyncMsgFromRust (deno/js/dispatch.ts:27:17) -``` - -### Linking to third party code - -In the above examples, we saw that Deno could execute scripts from URLs. Like -browser JavaScript, Deno can import libraries directly from URLs. This example -uses a URL to import a test runner library: - -```ts -import { test, runIfMain } from "https://deno.land/std/testing/mod.ts"; -import { assertEquals } from "https://deno.land/std/testing/asserts.ts"; - -test(function t1() { - assertEquals("hello", "hello"); -}); - -test(function t2() { - assertEquals("world", "world"); -}); - -runIfMain(import.meta); -``` - -Try running this: - -```shell -$ deno run test.ts -running 2 tests -test t1 ... ok -test t2 ... ok - -test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out - -``` - -Note that we did not have to provide the `--allow-net` flag for this program, -and yet it accessed the network. The runtime has special access to download -imports and cache them to disk. - -Deno caches remote imports in a special directory specified by the `$DENO_DIR` -environmental variable. It defaults to the system's cache directory if -`$DENO_DIR` is not specified. The next time you run the program, no downloads -will be made. If the program hasn't changed, it won't be recompiled either. The -default directory is: - -- On Linux/Redox: `$XDG_CACHE_HOME/deno` or `$HOME/.cache/deno` -- On Windows: `%LOCALAPPDATA%/deno` (`%LOCALAPPDATA%` = `FOLDERID_LocalAppData`) -- On macOS: `$HOME/Library/Caches/deno` -- If something fails, it falls back to `$HOME/.deno` - -**But what if `https://deno.land/` goes down?** Relying on external servers is -convenient for development but brittle in production. Production software should -always bundle its dependencies. In Deno this is done by checking the `$DENO_DIR` -into your source control system, and specifying that path as the `$DENO_DIR` -environmental variable at runtime. - -**How do you import to a specific version?** Simply specify the version in the -URL. For example, this URL fully specifies the code being run: -`https://unpkg.com/liltest@0.0.5/dist/liltest.js`. Combined with the -aforementioned technique of setting `$DENO_DIR` in production to stored code, -one can fully specify the exact code being run, and execute the code without -network access. - -**It seems unwieldy to import URLs everywhere. What if one of the URLs links to -a subtly different version of a library? Isn't it error prone to maintain URLs -everywhere in a large project?** The solution is to import and re-export your -external libraries in a central `deps.ts` file (which serves the same purpose as -Node's `package.json` file). For example, let's say you were using the above -testing library across a large project. Rather than importing -`"https://deno.land/std/testing/mod.ts"` everywhere, you could create a -`deps.ts` file that exports the third-party code: - -```ts -export { test, assertEquals } from "https://deno.land/std/testing/mod.ts"; -``` - -And throughout the same project, you can import from the `deps.ts` and avoid -having many references to the same URL: - -```ts -import { test, assertEquals } from "./deps.ts"; -``` - -This design circumvents a plethora of complexity spawned by package management -software, centralized code repositories, and superfluous file formats. - -### Using external type definitions - -Deno supports both JavaScript and TypeScript as first class languages at -runtime. This means it requires fully qualified module names, including the -extension (or a server providing the correct media type). In addition, Deno has -no "magical" module resolution. - -The out of the box TypeScript compiler though relies on both extension-less -modules and the Node.js module resolution logic to apply types to JavaScript -modules. - -In order to bridge this gap, Deno supports compiler hints that inform Deno the -location of `.d.ts` files and the JavaScript code they relate to. A compiler -hint looks like this: - -```ts -// @deno-types="./foo.d.ts" -import * as foo from "./foo.js"; -``` - -Where the hint affects the next `import` statement (or `export ... from` -statement) where the value of the `@deno-types` will be substituted at compile -time instead of the specified module. Like in the above example, the Deno -compiler will load `./foo.d.ts` instead of `./foo.js`. Deno will still load -`./foo.js` when it runs the program. - -**Not all type definitions are supported.** - -Deno will use the compiler hint to load the indicated `.d.ts` files, but some -`.d.ts` files contain unsupported features. Specifically, some `.d.ts` files -expect to be able to load or reference type definitions from other packages -using the module resolution logic. For example a type reference directive to -include `node`, expecting to resolve to some path like -`./node_modules/@types/node/index.d.ts`. Since this depends on non-relative -"magical" resolution, Deno cannot resolve this. - -**Why not use the triple-slash type reference?** - -The TypeScript compiler supports triple-slash directives, including a type -reference directive. If Deno used this, it would interfere with the behavior of -the TypeScript compiler. - -### Testing if current file is the main program - -To test if the current script has been executed as the main input to the program -check `import.meta.main`. - -```ts -if (import.meta.main) { - console.log("main"); -} -``` - -## Command line interface - -### Flags - -Use `deno help` to see the help text. - -``` -deno -A secure runtime for JavaScript and TypeScript built with V8, Rust, and Tokio. - -Docs: https://deno.land/manual.html -Modules: https://deno.land/x/ -Bugs: https://github.com/denoland/deno/issues - -To run the REPL: - - deno - -To execute a sandboxed script: - - deno https://deno.land/welcome.ts - -To evaluate code from the command line: - - deno eval "console.log(30933 + 404)" - -To get help on the another subcommands (run in this case): - - deno help run - -USAGE: - deno [OPTIONS] [SUBCOMMAND] - -OPTIONS: - -A, --allow-all Allow all permissions - --allow-env Allow environment access - --allow-hrtime Allow high resolution time measurement - --allow-net= Allow network access - --allow-read= Allow file system read access - --allow-run Allow running subprocesses - --allow-write= Allow file system write access - -c, --config Load compiler configuration file - --current-thread Use tokio::runtime::current_thread - -h, --help Prints help information - --importmap Load import map file - -L, --log-level Set log level [possible values: debug, info] - --no-fetch Do not download remote modules - -r, --reload= Reload source code cache (recompile TypeScript) - --seed Seed Math.random() - --v8-flags= Set V8 command line options - --v8-options Print V8 command line options - -v, --version Print the version - -SUBCOMMANDS: - [SCRIPT] Script to run - bundle Bundle module and dependencies into single file - completions Generate shell completions - eval Eval script - fetch Fetch the dependencies - fmt Format files - help Prints this message or the help of the given subcommand(s) - info Show info about cache or info related to source file - install Install script as executable - run Run a program given a filename or url to the source code - test Run tests - types Print runtime TypeScript declarations - version Print the version - xeval Eval a script on text segments from stdin - -ENVIRONMENT VARIABLES: - DENO_DIR Set deno's base directory - NO_COLOR Set to disable color - HTTP_PROXY Set proxy address for HTTP requests (module downloads, fetch) - HTTPS_PROXY Set proxy address for HTTPS requests (module downloads, fetch) -``` - -### Environmental variables - -There are several env vars that control how Deno behaves: - -`DENO_DIR` defaults to `$HOME/.deno` but can be set to any path to control where -generated and cached source code is written and read to. - -`NO_COLOR` will turn off color output if set. See https://no-color.org/. User -code can test if `NO_COLOR` was set without having `--allow-env` by using the -boolean constant `Deno.noColor`. - -### Shell completion - -You can generate completion script for your shell using the -`deno completions ` command. The command outputs to stdout so you should -redirect it to an appropriate file. - -The supported shells are: - -- zsh -- bash -- fish -- powershell -- elvish - -Example: - -```shell -deno completions bash > /usr/local/etc/bash_completion.d/deno.bash -source /usr/local/etc/bash_completion.d/deno.bash -``` - -### V8 flags - -V8 has many many internal command-line flags, that you can see with -`--v8-options`. -[It looks like this.](https://gist.github.com/ry/1c5b080dcbdc6367e5612392049c9ee7) - -Particularly useful ones: - -``` ---async-stack-trace -``` - -### Bundling - -`deno bundle [URL]` will output a single JavaScript file, using -[AMD](https://en.wikipedia.org/wiki/Asynchronous_module_definition), which -includes all dependencies of the specified input. - -``` -> deno bundle https://deno.land/std/examples/colors.ts -Bundling "colors.bundle.js" -Emitting bundle to "colors.bundle.js" -9.2 kB emitted. -``` - -To run then bundle in Deno use - -``` -deno https://deno.land/std/bundle/run.ts colors.bundle.js -``` - -Bundles can also be loaded in the web browser with the assistance of -[RequireJS](https://requirejs.org/). Suppose we have a bundle called -`website.bundle.js`, then the following HTML should be able to load it: - -```html - - - -``` - -Here we assume there's an exported function `main()` from `website.ts`. - -```js -// website.ts -export main() { - console.log("hello from the web browser"); -} -``` - -### Installing executable scripts - -Deno provides ability to easily install and distribute executable code via -`deno install` command. - -`deno install [EXE_NAME] [URL] [FLAGS...]` will install script available at -`URL` with name `EXE_NAME`. - -This command is a thin wrapper that creates executable shell scripts which -invoke `deno` with specified permissions and CLI flags. - -Example: - -```shell -$ deno install file_server https://deno.land/std/http/file_server.ts --allow-net --allow-read -[1/1] Compiling https://deno.land/std/http/file_server.ts - -✅ Successfully installed file_server. -/Users/deno/.deno/bin/file_server -``` - -By default scripts are installed at `$HOME/.deno/bin` and that directory must be -added to the path manually. - -```shell -$ echo 'export PATH="$HOME/.deno/bin:$PATH"' >> ~/.bashrc -``` - -Installation directory can be changed using `-d/--dir` flag: - -```shell -$ deno install --dir /usr/local/bin prettier https://deno.land/std/prettier/main.ts --allow-write --allow-read -``` - -When installing a script you can specify permissions that will be used to run -the script. They are placed after the script URL and can be mixed with any -additional CLI flags you want to pass to the script. - -Example: - -```shell -$ deno install format_check https://deno.land/std/prettier/main.ts --allow-write --allow-read --check --print-width 88 --tab-width 2 -``` - -Above command creates an executable called `format_check` that runs `prettier` -with write and read permissions. When you run `format_check` deno will run -prettier in `check` mode and configured to use `88` column width with `2` column -tabs. - -It is a good practice to use `import.meta.main` idiom for an entry point for -executable file. See -[Testing if current file is the main program](#testingifcurrentfileisthemainprogram) -section. - -Example: - -```ts -// https://example.com/awesome/cli.ts -async function myAwesomeCli(): Promise { - -- snip -- -} - -if (import.meta.main) { - myAwesomeCli(); -} -``` - -When you create executable script make sure to let users know by adding example -installation command to your repository: - -```shell -# Install using deno install - -$ deno install awesome_cli https://example.com/awesome/cli.ts -``` - -## Proxies - -Deno supports proxies for module downloads and `fetch` API. - -Proxy configuration is read from environmental variables: `HTTP_PROXY` and -`HTTPS_PROXY`. - -In case of Windows if environmental variables are not found Deno falls back to -reading proxies from registry. - -## Import maps - -Deno supports [import maps](https://github.com/WICG/import-maps). - -One can use import map with `--importmap=` CLI flag. - -Current limitations: - -- single import map -- no fallback URLs -- Deno does not support `std:` namespace -- Does supports only `file:`, `http:` and `https:` schemes - -Example: - -```js -// import_map.json - -{ - "imports": { - "http/": "https://deno.land/std/http/" - } -} -``` - -```ts -// hello_server.ts - -import { serve } from "http/server.ts"; - -window.onload = async function() { - const body = new TextEncoder().encode("Hello World\n"); - for await (const req of serve(":8000")) { - req.respond({ body }); - } -}; -``` - -```shell -$ deno run --importmap=import_map.json hello_server.ts -``` - -## Program lifecycle - -Deno supports browser compatible lifecycle events: `load` and `unload`. You can -use these event to provide setup and cleanup code in your program. - -`load` event listener supports asynchronous functions and will await these -functions. `unload` event listener supports only synchronous code. Both events -are not cancellable. - -Example: - -```typescript -// main.ts -import "./imported.ts"; - -const handler = (e: Event): void => { - console.log(`got ${e.type} event in event handler (main)`); -}; - -window.addEventListener("load", handler); - -window.addEventListener("unload", handler); - -window.onload = (e: Event): void => { - console.log(`got ${e.type} event in onload function (main)`); -}; - -window.onunload = (e: Event): void => { - console.log(`got ${e.type} event in onunload function (main)`); -}; - -// imported.ts -const handler = (e: Event): void => { - console.log(`got ${e.type} event in event handler (imported)`); -}; - -window.addEventListener("load", handler); -window.addEventListener("unload", handler); - -window.onload = (e: Event): void => { - console.log(`got ${e.type} event in onload function (imported)`); -}; - -window.onunload = (e: Event): void => { - console.log(`got ${e.type} event in onunload function (imported)`); -}; - -console.log("log from imported script"); -``` - -Note that you can use both `window.addEventListener` and -`window.onload`/`window.onunload` to define handlers for events. There is a -major difference between them, let's run example: - -```shell -$ deno main.ts -log from imported script -log from main script -got load event in onload function (main) -got load event in event handler (imported) -got load event in event handler (main) -got unload event in onunload function (main) -got unload event in event handler (imported) -got unload event in event handler (main) -``` - -All listeners added using `window.addEventListener` were run, but -`window.onload` and `window.onunload` defined in `main.ts` overridden handlers -defined in `imported.ts`. - -## Internal details - -### Deno and Linux analogy - -| **Linux** | **Deno** | -| ------------------------------: | :------------------------------- | -| Processes | Web Workers | -| Syscalls | Ops | -| File descriptors (fd) | [Resource ids (rid)](#resources) | -| Scheduler | Tokio | -| Userland: libc++ / glib / boost | https://deno.land/std/ | -| /proc/\$\$/stat | [Deno.metrics()](#metrics) | -| man pages | deno types | - -#### Resources - -Resources (AKA `rid`) are Deno's version of file descriptors. They are integer -values used to refer to open files, sockets, and other concepts. For testing it -would be good to be able to query the system for how many open resources there -are. - -```ts -const { resources, close } = Deno; -console.log(resources()); -// output like: { 0: "stdin", 1: "stdout", 2: "stderr", 3: "repl" } - -// close resource by rid -close(3); -``` - -#### Metrics - -Metrics is Deno's internal counters for various statics. - -```shell -> console.table(Deno.metrics()) -┌──────────────────┬────────┐ -│ (index) │ Values │ -├──────────────────┼────────┤ -│ opsDispatched │ 9 │ -│ opsCompleted │ 9 │ -│ bytesSentControl │ 504 │ -│ bytesSentData │ 0 │ -│ bytesReceived │ 856 │ -└──────────────────┴────────┘ -``` - -### Schematic diagram - - - -### Profiling - -To start profiling, - -```sh -# Make sure we're only building release. -# Build deno and V8's d8. -ninja -C target/release d8 - -# Start the program we want to benchmark with --prof -./target/release/deno tests/http_bench.ts --allow-net --v8-flags=--prof & - -# Exercise it. -third_party/wrk/linux/wrk http://localhost:4500/ -kill `pgrep deno` -``` - -V8 will write a file in the current directory that looks like this: -`isolate-0x7fad98242400-v8.log`. To examine this file: - -```sh -D8_PATH=target/release/ ./third_party/v8/tools/linux-tick-processor -isolate-0x7fad98242400-v8.log > prof.log -# on macOS, use ./third_party/v8/tools/mac-tick-processor instead -``` - -`prof.log` will contain information about tick distribution of different calls. - -To view the log with Web UI, generate JSON file of the log: - -```sh -D8_PATH=target/release/ ./third_party/v8/tools/linux-tick-processor -isolate-0x7fad98242400-v8.log --preprocess > prof.json -``` - -Open `third_party/v8/tools/profview/index.html` in your browser, and select -`prof.json` to view the distribution graphically. - -Useful V8 flags during profiling: - -- --prof -- --log-internal-timer-events -- --log-timer-events -- --track-gc -- --log-source-code -- --track-gc-object-stats - -Note that you might need to run Deno with `--current-thread` flag to capture -full V8 profiling output. - -To learn more about `d8` and profiling, check out the following links: - -- [https://v8.dev/docs/d8](https://v8.dev/docs/d8) -- [https://v8.dev/docs/profile](https://v8.dev/docs/profile) - -### Debugging with LLDB - -We can use LLDB to debug Deno. - -```shell -$ lldb -- target/debug/deno run tests/worker.js -> run -> bt -> up -> up -> l -``` - -To debug Rust code, we can use `rust-lldb`. It should come with `rustc` and is a -wrapper around LLDB. - -```shell -$ rust-lldb -- ./target/debug/deno run --allow-net tests/http_bench.ts -# On macOS, you might get warnings like -# `ImportError: cannot import name _remove_dead_weakref` -# In that case, use system python by setting PATH, e.g. -# PATH=/System/Library/Frameworks/Python.framework/Versions/2.7/bin:$PATH -(lldb) command script import "/Users/kevinqian/.rustup/toolchains/1.36.0-x86_64-apple-darwin/lib/rustlib/etc/lldb_rust_formatters.py" -(lldb) type summary add --no-value --python-function lldb_rust_formatters.print_val -x ".*" --category Rust -(lldb) type category enable Rust -(lldb) target create "../deno/target/debug/deno" -Current executable set to '../deno/target/debug/deno' (x86_64). -(lldb) settings set -- target.run-args "tests/http_bench.ts" "--allow-net" -(lldb) b op_start -(lldb) r -``` - -### Deno Core - -The core binding layer for Deno. It is released as a -[standalone crate](https://crates.io/crates/deno). Inside of core is V8 itself, -with a binding API called "libdeno". See the crate documentation for more -details. - -### Updating prebuilt binaries - -```shell -$ ./third_party/depot_tools/upload_to_google_storage.py -b denoland \ - -e ~/.config/gcloud/legacy_credentials/ry@tinyclouds.org/.boto `which sccache` -$ mv `which sccache`.sha1 prebuilt/linux64/ -$ gsutil acl ch -u AllUsers:R gs://denoland/608be47bf01004aa11d4ed06955414e93934516e -``` - -### Continuous Benchmarks - -See our benchmarks [over here](https://deno.land/benchmarks.html) - -The benchmark chart supposes `//website/data.json` has the type -`BenchmarkData[]` where `BenchmarkData` is defined like the below: - -```ts -interface ExecTimeData { - mean: number; - stddev: number; - user: number; - system: number; - min: number; - max: number; -} - -interface BenchmarkData { - created_at: string; - sha1: string; - benchmark: { - [key: string]: ExecTimeData; - }; - binarySizeData: { - [key: string]: number; - }; - threadCountData: { - [key: string]: number; - }; - syscallCountData: { - [key: string]: number; - }; -} -``` - -### Logos - -These Deno logos, like the Deno software, are distributed under the MIT license -(public domain and free for use) - -- [A hand drawn one by @ry](https://github.com/denoland/deno/blob/master/website/images/deno_logo.png) - -- [An animated one by @hashrock](https://github.com/denolib/animated-deno-logo/) - -- [A high resolution SVG one by @kevinkassimo](https://github.com/denolib/high-res-deno-logo) - -- [A pixelated animation one by @tanakaworld](https://github.com/denoland/deno/blob/master/website/images/deno_logo_4.gif) - -## Contributing - -[Style Guide](style_guide.html) - -Progress towards future releases is tracked -[here](https://github.com/denoland/deno/milestones). - -Please don't make [the benchmarks](https://deno.land/benchmarks.html) worse. - -Ask for help in the [community chat room](https://gitter.im/denolife/Lobby). - -If you are going to work on an issue, mention so in the issue comments _before_ -you start working on the issue. - -### Submitting a pull request - -Before submitting, please make sure the following is done: - -1. That there is a related issue and it is referenced in the PR text. -2. There are tests that cover the changes. -3. Ensure `cargo test` passes. -4. Format your code with `tools/format.py` -5. Make sure `./tools/lint.py` passes. - -### Changes to `third_party` - -[`deno_third_party`](https://github.com/denoland/deno_third_party) contains most -of the external code that Deno depends on, so that we know exactly what we are -executing at any given time. It is carefully maintained with a mixture of manual -labor and private scripts. It's likely you will need help from @ry or -@piscisaureus to make changes. - -### Adding Ops (aka bindings) - -We are very concerned about making mistakes when adding new APIs. When adding an -Op to Deno, the counterpart interfaces on other platforms should be researched. -Please list how this functionality is done in Go, Node, Rust, and Python. - -As an example, see how `Deno.rename()` was proposed and added in -[PR #671](https://github.com/denoland/deno/pull/671). - -### Documenting APIs - -It is important to document public APIs and we want to do that inline with the -code. This helps ensure that code and documentation are tightly coupled -together. - -#### Utilize JSDoc - -All publicly exposed APIs and types, both via the `deno` module as well as the -global/`window` namespace should have JSDoc documentation. This documentation is -parsed and available to the TypeScript compiler, and therefore easy to provide -further downstream. JSDoc blocks come just prior to the statement they apply to -and are denoted by a leading `/**` before terminating with a `*/`. For example: - -```ts -/** A simple JSDoc comment */ -export const FOO = "foo"; -``` diff --git a/website/rustdoc b/website/rustdoc deleted file mode 120000 index 91ebb25e2..000000000 --- a/website/rustdoc +++ /dev/null @@ -1 +0,0 @@ -../target/doc/ \ No newline at end of file diff --git a/website/showdown_toc.js b/website/showdown_toc.js deleted file mode 100644 index 886036443..000000000 --- a/website/showdown_toc.js +++ /dev/null @@ -1,143 +0,0 @@ -// Extension loading compatible with AMD and CommonJs -(function(extension) { - "use strict"; - - if (typeof showdown === "object") { - // global (browser or nodejs global) - showdown.extension("toc", extension()); - } else if (typeof define === "function" && define.amd) { - // AMD - define("toc", extension()); - } else if (typeof exports === "object") { - // Node, CommonJS-like - module.exports = extension(); - } else { - // showdown was not found so we throw - throw Error("Could not find showdown library"); - } -})(function() { - function getHeaderEntries(sourceHtml) { - if (typeof window === "undefined") { - return getHeaderEntriesInNodeJs(sourceHtml); - } else { - return getHeaderEntriesInBrowser(sourceHtml); - } - } - - function getHeaderEntriesInNodeJs(sourceHtml) { - // eslint-disable-next-line @typescript-eslint/no-var-requires - const cheerio = require("cheerio"); - const $ = cheerio.load(sourceHtml); - const headers = $("h1, h2, h3, h4, h5, h6"); - - const headerList = []; - for (let i = 0; i < headers.length; i++) { - const el = headers[i]; - headerList.push(new TocEntry(el.name, $(el).text(), $(el).attr("id"))); - } - - return headerList; - } - - function getHeaderEntriesInBrowser(sourceHtml) { - // Generate dummy element - const source = document.createElement("div"); - source.innerHTML = sourceHtml; - - // Find headers - const headers = source.querySelectorAll("h1, h2, h3, h4, h5, h6"); - const headerList = []; - for (let i = 0; i < headers.length; i++) { - const el = headers[i]; - headerList.push(new TocEntry(el.tagName, el.textContent, el.id)); - } - - return headerList; - } - - function TocEntry(tagName, text, anchor) { - this.tagName = tagName; - this.text = text; - this.anchor = anchor; - this.children = []; - } - - TocEntry.prototype.childrenToString = function() { - if (this.children.length === 0) { - return ""; - } - let result = "
    \n"; - for (let i = 0; i < this.children.length; i++) { - result += this.children[i].toString(); - } - result += "
\n"; - return result; - }; - - TocEntry.prototype.toString = function() { - let result = "
  • "; - if (this.text) { - result += '' + this.text + ""; - } - result += this.childrenToString(); - result += "
  • \n"; - return result; - }; - - function sortHeader(tocEntries, level) { - level = level || 1; - const tagName = "H" + level; - const result = []; - - function push(tocEntry) { - if (tocEntry !== undefined) { - if (tocEntry.children.length > 0) { - tocEntry.children = sortHeader(tocEntry.children, level + 1); - } - result.push(tocEntry); - } - } - - let currentTocEntry; - for (let i = 0; i < tocEntries.length; i++) { - const tocEntry = tocEntries[i]; - if (tocEntry.tagName.toUpperCase() !== tagName) { - if (currentTocEntry === undefined) { - currentTocEntry = new TocEntry(); - } - currentTocEntry.children.push(tocEntry); - } else { - push(currentTocEntry); - currentTocEntry = tocEntry; - } - } - - push(currentTocEntry); - return result; - } - - return { - type: "output", - filter: function(sourceHtml) { - let headerList = getHeaderEntries(sourceHtml); - - // No header found - if (headerList.length === 0) { - return sourceHtml; - } - - // Sort header - headerList = sortHeader(headerList); - - // Skip the title. - if (headerList.length == 1) { - headerList = headerList[0].children; - } - - // Build result and replace all [toc] - const result = - '
    \n
      \n' + headerList.join("") + "
    \n
    \n"; - return sourceHtml.replace(/\[toc\]/gi, result); - } - }; -}); diff --git a/website/style.css b/website/style.css deleted file mode 100644 index 2610202de..000000000 --- a/website/style.css +++ /dev/null @@ -1,209 +0,0 @@ -:root { - --text-color: #444; - --background-color: #f0f0f0; - --link-color: #106ad5; - --table-border: #bbb; - --pre-color: #161616; - --pre-link-color: #001631; - --pre-background: rgba(36, 126, 233, 0.1); - --code-color: #333; -} - -@media (prefers-color-scheme: dark) { - :root { - --background-color: #444; - --text-color: #f0f0f0; - --link-color: #4498ff; - --pre-color: #e8e8e8; - --pre-link-color: #cee4ff; - --code-color: #ccc; - } - - #logo { - filter: invert(); - } - - .c3-tooltip th { - background: #6f6f6f; - } - - .c3-tooltip td { - background: var(--background-color); - } - - .c3-axis g, - .c3-axis text, - .c3-legend-item text { - fill: var(--text-color); - } - - .c3-axis line, - .c3-axis path.domain { - stroke: var(--text-color); - } -} - -body { - color: var(--text-color); - background: var(--background-color); - padding: 0; - - line-height: 1.5; - font-family: -apple-system,BlinkMacSystemFont,avenir next,avenir,helvetica neue,helvetica,ubuntu,roboto,noto,segoe ui,arial,sans-serif; - - margin: 5ex 10ex; - max-width: 80ex; -} - -#manual img { - width: 100%; - max-width: 800px; -} - -h1, -h2, -h3, -h4 { - font-weight: 500; - margin-top: 2em; - margin-bottom: 0; -} - -h1:first-child, -h2:first-child, -h3:first-child, -h4:first-child { - margin-top: 0; -} - -h1, -h2, -h3, -h4, -p, -table { - margin-left: 8px; - margin-right: 8px; -} - -table { - border-collapse: collapse; - margin-top: 8px; -} - -td, -th { - font-weight: normal; - text-align: center; - border: 1px solid var(--table-border); - padding: 4px; -} - -@media only screen and (min-width: 768px) { - td, - th { - padding: 8px 16px; - } -} - -svg { - margin: 0px; - width: 100%; - height: 300px; -} - -a { - color: var(--link-color); -} - -pre a { - color: var(--pre-link-color); -} - -h2 a, -h3 a { - display: none; - color: #3bace5; - text-decoration: none; -} - -h2:hover a, -h3:hover a { - display: inline; -} - -pre { - /* background: rgba(36, 126, 233, 0.03); */ - color: var(--pre-color); - background: var(--pre-background); - padding: 15px; - white-space: pre-wrap; - word-break: break-all; - overflow-x: auto; -} - -header { - display: flex; - align-items: center; - margin: 16px 4px; -} - -header > * { - margin: 8px; -} - -header h1 { - margin: 8px 0; -} - -@media only screen and (max-width: 480px) { - body { - margin: 0; - } -} - -code { - background: rgba(36, 126, 233, 0.1); - padding: 2px 5px; - color: var(--code-color); -} - -.hljs { - background: transparent; -} - -#spinner-overlay { - display: none; - position: fixed; - top: 0px; - bottom: 0px; - left: 0px; - right: 0px; - background: rgba(0, 0, 0, 0.3); -} - -@keyframes spinner { - to { - transform: rotate(360deg); - } -} - -.spinner:before { - content: ""; - box-sizing: border-box; - position: absolute; - top: 50%; - left: 50%; - width: 60px; - height: 60px; - margin-top: -30px; - margin-left: -30px; - border-radius: 50%; - border: 2px solid #ccc; - border-top-color: #000; - animation: spinner 0.6s linear infinite; -} - -.hidden { - display: none; -} diff --git a/website/style_guide.html b/website/style_guide.html deleted file mode 100644 index 667a2eac7..000000000 --- a/website/style_guide.html +++ /dev/null @@ -1,55 +0,0 @@ - - - - - Deno Style Guide - - - - - - - - - - -
    - - -
    - - - - -
    - - diff --git a/website/style_guide.md b/website/style_guide.md deleted file mode 100644 index e701ac0b3..000000000 --- a/website/style_guide.md +++ /dev/null @@ -1,304 +0,0 @@ -# Deno Style Guide - -[toc] - -## Use TypeScript - -## Use the term "module" instead of "library" or "package" - -For clarity and consistency avoid the terms "library" and "package". Instead use -"module" to refer to a single JS or TS file and also to refer to a directory of -TS/JS code. - -## Do not use the filename `index.ts` nor `index.js` - -Deno does not treat "index.js" or "index.ts" in a special way. By using these -filenames, it suggests that they can be left out of the module specifier when -they cannot. This is confusing. - -If a directory of code needs a default entry point, use the filename `mod.ts`. -The filename `mod.ts` follows Rust’s convention, is shorter than `index.ts`, and -doesn’t come with any preconceived notions about how it might work. - -## Within `deno_std`, do not depend on external code - -`deno_std` is intended to be baseline functionality that all Deno programs can -rely on. We want to guarantee to users that this code does not include -potentially unreviewed third party code. - -## Within `deno_std`, minimize dependencies; do not make circular imports. - -Although `deno_std` is a standalone codebase, we must still be careful to keep -the internal dependencies simple and manageable. In particular, be careful to -not to introduce circular imports. - -## For consistency, use underscores, not dashes in filenames. - -Example: Instead of `file-server.ts` use `file_server.ts`. - -## Format code using prettier. - -More specifically, code should be wrapped at 80 columns and use 2-space -indentation and use camel-case. Use `//format.ts` to invoke prettier. - -## Exported functions: max 2 args, put the rest into an options object. - -When designing function interfaces, stick to the following rules. - -1. A function that is part of the public API takes 0-2 required arguments, plus - (if necessary) an options object (so max 3 total). - -2. Optional parameters should generally go into the options object. - - An optional parameter that's not in an options object might be acceptable if - there is only one, and it seems inconceivable that we would add more optional - parameters in the future. - - - - -3. The 'options' argument is the only argument that is a regular 'Object'. - - Other arguments can be objects, but they must be distinguishable from a - 'plain' Object runtime, by having either: - - - a distinguishing prototype (e.g. `Array`, `Map`, `Date`, `class MyThing`) - - a well-known symbol property (e.g. an iterable with `Symbol.iterator`). - - This allows the API to evolve in a backwards compatible way, even when the - position of the options object changes. - - - -```ts -// BAD: optional parameters not part of options object. (#2) -export function resolve( - hostname: string, - family?: "ipv4" | "ipv6", - timeout?: number -): IPAddress[] {} - -// GOOD. -export interface ResolveOptions { - family?: "ipv4" | "ipv6"; - timeout?: number; -} -export function resolve( - hostname: string, - options: ResolveOptions = {} -): IPAddress[] {} -``` - -```ts -export interface Environment { - [key: string]: string; -} - -// BAD: `env` could be a regular Object and is therefore indistinguishable -// from an options object. (#3) -export function runShellWithEnv(cmdline: string, env: Environment): string {} - -// GOOD. -export interface RunShellOptions { - env: Environment; -} -export function runShellWithEnv( - cmdline: string, - options: RunShellOptions -): string {} -``` - -```ts -// BAD: more than 3 arguments (#1), multiple optional parameters (#2). -export function renameSync( - oldname: string, - newname: string, - replaceExisting?: boolean, - followLinks?: boolean -) {} - -// GOOD. -interface RenameOptions { - replaceExisting?: boolean; - followLinks?: boolean; -} -export function renameSync( - oldname: string, - newname: string, - options: RenameOptions = {} -) {} -``` - -```ts -// BAD: too many arguments. (#1) -export function pwrite( - fd: number, - buffer: TypedArray, - offset: number, - length: number, - position: number -) {} - -// BETTER. -export interface PWrite { - fd: number; - buffer: TypedArray; - offset: number; - length: number; - position: number; -} -export function pwrite(options: PWrite) {} -``` - -## TODO Comments - -TODO comments should include an issue or the author's github username in -parentheses. Example: - -```ts -// TODO(ry) Add tests. -// TODO(#123) Support Windows. -``` - -## Copyright headers - -Most files in `deno_std` should have the following copyright header: - -```ts -// Copyright 2018-2019 the Deno authors. All rights reserved. MIT license. -``` - -If the code originates elsewhere, ensure that the file has the proper copyright -headers. We only allow MIT, BSD, and Apache licensed code in `deno_std`. - -## Top level functions should not use arrow syntax - -Top level functions should use the `function` keyword. Arrow syntax should be -limited to closures. - -Bad - -```ts -export const foo = (): string => { - return "bar"; -}; -``` - -Good - -```ts -export function foo(): string { - return "bar"; -} -``` - -## Meta-programming is discouraged. Including the use of Proxy. - -Be explicit even when it means more code. - -There are some situations where it may make sense to use such techniques, but in -the vast majority of cases it does not. - -## If a filename starts with underscore, do not link to it: `_foo.ts` - -Sometimes there maybe situations where an internal module is necessary but its -API is not meant to be stable or linked to. In this case prefix it with an -underscore. By convention, only files in its own directory should import it. - -## Use JSDoc to document exported machinery - -We strive for complete documentation. Every exported symbol ideally should have -a documentation line. - -If possible, use a single line for the JS Doc. Example: - -```ts -/** foo does bar. */ -export function foo() { - // ... -} -``` - -It is important that documentation is easily human readable, but there is also a -need to provide additional styling information to ensure generated documentation -is more rich text. Therefore JSDoc should generally follow markdown markup to -enrich the text. - -While markdown supports HTML tags, it is forbidden in JSDoc blocks. - -Code string literals should be braced with the back-tick (\`) instead of quotes. -For example: - -```ts -/** Import something from the `deno` module. */ -``` - -Do not document function arguments unless they are non-obvious of their intent -(though if they are non-obvious intent, the API should be considered anyways). -Therefore `@param` should generally not be used. If `@param` is used, it should -not include the `type` as TypeScript is already strongly typed. - -```ts -/** - * Function with non obvious param - * @param foo Description of non obvious parameter - */ -``` - -Vertical spacing should be minimized whenever possible. Therefore single line -comments should be written as: - -```ts -/** This is a good single line JSDoc */ -``` - -And not - -```ts -/** - * This is a bad single line JSDoc - */ -``` - -Code examples should not utilise the triple-back tick (\`\`\`) notation or tags. -They should just be marked by indentation, which requires a break before the -block and 6 additional spaces for each line of the example. This is 4 more than -the first column of the comment. For example: - -```ts -/** A straight forward comment and an example: - * - * import { foo } from "deno"; - * foo("bar"); - */ -``` - -Code examples should not contain additional comments. It is already inside a -comment. If it needs further comments it is not a good example. - -## Each module should come with tests - -Each module should come with its test as a sibling with the name -`modulename_test.ts`. For example the module `foo.ts` should come with its -sibling `foo_test.ts`. - -## Unit Tests should be explicit - -For a better understanding of the tests, function should be correctly named as -its prompted throughout the test command. Like: - -``` -test myTestFunction ... ok -``` - -Example of test: - -```ts -import { assertEquals } from "https://deno.land/std@v0.11/testing/asserts.ts"; -import { test } from "https://deno.land/std@v0.11/testing/mod.ts"; -import { foo } from "./mod.ts"; - -test(function myTestFunction() { - assertEquals(foo(), { bar: "bar" }); -}); -``` diff --git a/website/typedoc b/website/typedoc deleted file mode 120000 index eba22d9ca..000000000 --- a/website/typedoc +++ /dev/null @@ -1 +0,0 @@ -../target/typedoc/ \ No newline at end of file diff --git a/website/welcome.ts b/website/welcome.ts deleted file mode 100644 index 69f1069f8..000000000 --- a/website/welcome.ts +++ /dev/null @@ -1 +0,0 @@ -console.log("Welcome to Deno 🦕"); -- cgit v1.2.3