diff --git a/docs/examples.md b/docs/examples.md index 13c15a2c70..5a323b3451 100644 --- a/docs/examples.md +++ b/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) diff --git a/docs/examples/hello_world.md b/docs/examples/hello_world.md new file mode 100644 index 0000000000..90a833f71d --- /dev/null +++ b/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 +**/ +``` diff --git a/docs/examples/import_export.md b/docs/examples/import_export.md new file mode 100644 index 0000000000..22d02eea70 --- /dev/null +++ b/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 + */ +``` diff --git a/docs/examples/manage_dependencies.md b/docs/examples/manage_dependencies.md new file mode 100644 index 0000000000..142d66bac3 --- /dev/null +++ b/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 + */ +``` diff --git a/docs/toc.json b/docs/toc.json index e902720d02..0e5cd01536 100644 --- a/docs/toc.json +++ b/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",