docs: Improve examples (#6958)

docs/examples.md

@@ -2,3 +2,20 @@
 
 In this chapter you can find some example programs that you can use to learn
 more about the runtime.
+
+## Basic
+
+- [Hello World](./examples/hello_world)
+- [Import and Export Modules](./examples/import_export)
+- [How to Manage Dependencies](./examples/manage_dependencies)
+
+## Advanced
+
+- [Unix Cat](./examples/unix_cat)
+- [File Server](./examples/file_server)
+- [TCP Echo](./examples/tcp_echo)
+- [Subprocess](./examples/subprocess)
+- [Permissions](./examples/permissions)
+- [OS Signals](./examples/os_signals)
+- [File System Events](./examples/file_system_events)
+- [Testing If Main](./examples/testing_if_main)

docs/examples/hello_world.md

@@ -0,0 +1,66 @@
+# Hello World
+
+Deno is a secure runtime for both JavaScript and TypeScript. As the hello world
+examples below highlight the same functionality can be created in JavaScript or
+TypeScript, and Deno will execute both.
+
+## JavaScript
+
+In this JavaScript example the message `Hello [name]` is printed to the console
+and the code ensures the name provided is capitalized.
+
+**Command:** `deno run hello-world.js`
+
+```js
+function capitalize(word) {
+  return word.charAt(0).toUpperCase() + word.slice(1);
+}
+
+function hello(name) {
+  return "Hello " + capitalize(name);
+}
+
+console.log(hello("john"));
+console.log(hello("Sarah"));
+console.log(hello("kai"));
+
+/**
+ * Output:
+ *
+ * Hello John
+ * Hello Sarah
+ * Hello Kai
+**/
+```
+
+## TypeScript
+
+This TypeScript example is exactly the same as the JavaScript example above, the
+code just has the additional type information which TypeScript supports.
+
+The `deno run` command is exactly the same, it just references a `*.ts` file
+rather than a `*.js` file.
+
+**Command:** `deno run hello-world.ts`
+
+```ts
+function capitalize(word: string): string {
+  return word.charAt(0).toUpperCase() + word.slice(1);
+}
+
+function hello(name: string): string {
+  return "Hello " + capitalize(name);
+}
+
+console.log(hello("john"));
+console.log(hello("Sarah"));
+console.log(hello("kai"));
+
+/**
+ * Output:
+ *
+ * Hello John
+ * Hello Sarah
+ * Hello Kai
+**/
+```

docs/examples/import_export.md

@@ -0,0 +1,102 @@
+# Import and Export Modules
+
+Deno by default standardizes the way modules are imported in both JavaScript and
+TypeScript. It follows the ECMAScript 6 `import/export` standard with one
+caveat, the file type must be included at the end of import statement.
+
+```js
+import {
+  add,
+  multiply,
+} from "./arithmetic.ts";
+```
+
+Dependencies are also imported directly, there is no package management
+overhead. Local modules are imported in exactly the same way as remote modules.
+As the examples show below, the same functionality can be produced in the same
+way with local or remote modules.
+
+## Local Import
+
+In this example the `add` and `multiply` functions are imported from a local
+`arithmetic.ts` module.
+
+**Command:** `deno run local.ts`
+
+```ts
+import { add, multiply } from "./arithmetic.ts";
+
+function totalCost(outbound: number, inbound: number, tax: number): number {
+  return multiply(add(outbound, inbound), tax);
+}
+
+console.log(totalCost(19, 31, 1.2));
+console.log(totalCost(45, 27, 1.15));
+
+/**
+ * Output
+ *
+ * 60
+ * 82.8
+ */
+```
+
+## Export
+
+In the example above the `add` and `multiply` functions are imported from a
+locally stored arithmetic module. To make this possible the functions stored in
+the arithmetic module must be exported.
+
+To do this just add the keyword `export` to the beginning of the function
+signature as is shown below.
+
+```ts
+export function add(a: number, b: number): number {
+  return a + b;
+}
+
+export function multiply(a: number, b: number): number {
+  return a * b;
+}
+```
+
+All functions, classes, constants and variables which need to be accessible
+inside external modules must be exported. Either by prepending them with the
+`export` keyword or including them in an export statement at the bottom of the
+file.
+
+To find out more on ECMAScript Export functionality please read the
+[MDN Documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/export).
+
+## Remote Import
+
+In the local import example above an `add` and `multiply` method are imported
+from a locally stored arithmetic module. The same functionality can be created
+by importing `add` and `multiply` methods from a remote module too.
+
+In this case the Ramda module is referenced, including the version number. Also
+note a JavaScript module is imported directly into a TypeSript module, Deno has
+no problem handling this.
+
+**Command:** `deno run ./remote.ts`
+
+```ts
+import {
+  add,
+  multiply,
+} from "https://x.nest.land/ramda@0.27.0/source/index.js";
+
+function totalCost(outbound: number, inbound: number, tax: number): number {
+  return multiply(add(outbound, inbound), tax);
+}
+
+console.log(totalCost(19, 31, 1.2));
+console.log(totalCost(45, 27, 1.15));
+
+/**
+ * Output
+ *
+ * 60
+ * 82.8
+ */
+```

docs/examples/manage_dependencies.md

@@ -0,0 +1,56 @@
+# Managing Dependencies
+
+In Deno there is no concept of a package manager as external modules are
+imported directly into local modules. This raises the question of how to manage
+remote dependencies without a package manager. In big projects with many
+dependencies it will become cumbersome and time consuming to update modules if
+they are all imported individually into individual modules.
+
+The standard practice for solving this problem in Deno is to create a `deps.ts`
+file. All required remote dependencies are referenced in this file and the
+required methods and classes are re-exported. The dependent local modules then
+reference the `deps.ts` rather than the remote dependencies.
+
+This enables easy updates to modules across a large codebase and solves the
+'package manager problem', if it ever existed. Dev dependencies can also be
+managed in a separate `dev_deps.ts` file.
+
+**deps.ts example**
+
+```ts
+/**
+ * deps.ts re-exports the required methods from the remote Ramda module.
+ **/
+export {
+  add,
+  multiply,
+} from "https://x.nest.land/ramda@0.27.0/source/index.js";
+```
+
+In this example the same functionality is created as is the case in the
+[local and remote import examples](./import_export.md). But in this case instead
+of the Ramda module being referenced directly it is referenced by proxy using a
+local `deps.ts` module.
+
+**Command:** `deno run dependencies.ts`
+
+```ts
+import {
+  add,
+  multiply,
+} from "./deps.ts";
+
+function totalCost(outbound: number, inbound: number, tax: number): number {
+  return multiply(add(outbound, inbound), tax);
+}
+
+console.log(totalCost(19, 31, 1.2));
+console.log(totalCost(45, 27, 1.15));
+
+/**
+ * Output
+ *
+ * 60
+ * 82.8
+ */
+```

docs/toc.json

@@ -68,6 +68,9 @@
   "examples": {
     "name": "Examples",
     "children": {
+      "hello_world": "Hello World",
+      "import_export": "Import and Export Modules",
+      "manage_dependencies": "Manage Dependencies",
       "unix_cat": "Unix cat program",
       "file_server": "File server",
       "tcp_echo": "TCP echo server",