From 803a87d17b39dddce7efeb45e0a316a0aed13709 Mon Sep 17 00:00:00 2001 From: Kevin Whinnery Date: Fri, 15 Sep 2023 14:25:42 -0500 Subject: [PATCH 1/3] cleanup and audit --- runtime/manual/basics/modules/index.md | 6 +- runtime/manual/node/compatibility.mdx | 21 +++++-- runtime/manual/node/migrate.md | 61 +++++++++------------ runtime/manual/node/node_specifiers.md | 2 +- runtime/manual/node/package_json.md | 12 ++-- runtime/manual/runtime/http_server_apis.md | 3 +- runtime/manual/runtime/permission_apis.md | 4 +- runtime/manual/runtime/web_platform_apis.md | 20 ++++--- 8 files changed, 62 insertions(+), 67 deletions(-) diff --git a/runtime/manual/basics/modules/index.md b/runtime/manual/basics/modules/index.md index ec1438a0c..011586642 100644 --- a/runtime/manual/basics/modules/index.md +++ b/runtime/manual/basics/modules/index.md @@ -1,8 +1,4 @@ ---- -sidebar_position: 1 ---- - -# ECMAScript Modules in Deno +# Modules ## Concepts diff --git a/runtime/manual/node/compatibility.mdx b/runtime/manual/node/compatibility.mdx index 30f6a4c52..34d55d15e 100644 --- a/runtime/manual/node/compatibility.mdx +++ b/runtime/manual/node/compatibility.mdx @@ -7,11 +7,21 @@ which modules you need by ## Built-in module support -✅ = Full support   ℹ️ = Partial support   ❌ = Stubs only +
+
✅ = Full support
+
ℹ️ = Partial support
+
❌ = Stubs only
+
- node:assert, node:assert/strict + node:assert
✅
@@ -201,7 +211,7 @@ which modules you need by
- node:fs, node:fs/promises + node:fs
ℹ️
@@ -450,8 +460,7 @@ which modules you need by
- node:stream, node:stream/consumers,  - node:stream/promises, node:stream/web + node:stream
✅
@@ -512,7 +521,7 @@ which modules you need by
- node:timers, node:timers/promises + node:timers
✅
diff --git a/runtime/manual/node/migrate.md b/runtime/manual/node/migrate.md index 18d9dc191..3d26427f3 100644 --- a/runtime/manual/node/migrate.md +++ b/runtime/manual/node/migrate.md @@ -5,19 +5,14 @@ differences to take into account between the Node and Deno runtimes. This guide will attempt to call out several of those differences, and describe how you can begin to migrate your Node.js project to work on Deno. -> Node.js compatibility is an ongoing project in Deno - you may encounter some -> modules or packages on npm that do not work as you expect. If you do run into -> a problem with Node.js compatibility, please let us know by -> [opening an issue on GitHub](https://github.com/denoland/deno/issues). +:::info About Node.js Compatibility -**On this page:** +Node.js compatibility is an ongoing project in Deno - you may encounter some +modules or packages on npm that do not work as you expect. If you do run into a +problem with Node.js compatibility, please let us know by +[opening an issue on GitHub](https://github.com/denoland/deno/issues). -- [Module imports and exports](#module-imports-and-exports) -- [Node.js built-ins](#nodejs-built-ins) -- [Runtime permission system](#runtime-permissions-in-deno) -- [npm scripts](#running-npm-scripts-in-deno) -- [Using and managing npm dependencies](#using-and-managing-npm-dependencies) -- [Node.js global objects](#nodejs-global-objects) +::: ## Module imports and exports @@ -31,16 +26,12 @@ be changed as well. Consider the following two files in a Node.js program, located in the same directory: -**`index.js`** - -```js +```js title="index.js" const addNumbers = require("./add_numbers"); console.log(addNumbers(2, 2)); ``` -**`add_numbers.js`** - -```js +```js title="add_numbers.js" module.exports = function addNumbers(num1, num2) { return num1 + num2; }; @@ -56,7 +47,7 @@ module. Replace `require` statements with an `import`, like so: -``` +```js import addNumbers from "./add_numbers.js"; ``` @@ -70,7 +61,7 @@ of files named `index.js`. In the `add_numbers.js` file that exports the function, we would use a default export from ES6 modules rather than the `module.exports` provided by CommonJS. -```js +```js title="add_numbers.js" export default function addNumbers(num1, num2) { return num1 + num2; } @@ -86,9 +77,7 @@ In Node.js 20 and earlier, built-in modules in the Node.js standard library could be imported with "bare specifiers". Consider the Node program below with a `.mjs` extension: -**`index.mjs`** - -``` +```js title="index.mjs" import * as os from "os"; console.log(os.cpus()); ``` @@ -96,9 +85,13 @@ console.log(os.cpus()); The [`os` module](https://nodejs.org/api/os.html#oscpus) is built in to the Node.js runtime, and can be imported using a bare specifier as above. -> **NOTE:** The `.mjs` file extension is supported but not required in Deno. -> Because Node doesn't support ESM by default, it requires you to name any files -> that use ESM with a `.mjs` file extension. +:::info .mjs extensions not required in Deno + +The `.mjs` file extension is supported but not required in Deno. Because Node +doesn't support ESM by default, it requires you to name any files that use ESM +with a `.mjs` file extension. + +::: Deno provides a compatibility layer that allows the use of Node.js built-in APIs within Deno programs. However, in order to use them, you will need to add the @@ -133,7 +126,7 @@ will likely prompt you for access to the permissions it needs to execute your code. Consider the following simple [express](https://expressjs.com/) server: ```js -import express from "npm:express"; +import express from "npm:express@4"; const app = express(); @@ -152,7 +145,7 @@ show you what runtime permission flags need to be passed in to grant the access you need. Running the code above with the necessary permissions provided would look like this: -```plain +```shell deno run --allow-net --allow-read --allow-env server.js ``` @@ -180,7 +173,7 @@ run your programs with all runtime permissions enabled. This would be the default behavior of Node, which lacks a permission system. To run a program with all permissions enabled, you can do so with: -```plain +```shell deno run -A server.js ``` @@ -197,19 +190,15 @@ One of the ways [Deno supports existing `package.json` files](./package_json.md) is by executing any scripts configured there with `deno task`. Consider the following Node.js project with a package.json and a script configured within it. -**`bin/my_task.mjs`** - -```js +```js title="bin/my_task.mjs" console.log("running my task..."); ``` -**`package.json`** - -```json +```json title="package.json" { "name": "test", "scripts": { - "start": "node index.mjs" + "start": "node bin/my_task.mjs" } } ``` @@ -232,7 +221,7 @@ When importing npm packages, you would use the `npm:` specifier, much like you would the `node:` specifier for any built-in Node modules. ```js -import express from "npm:express"; +import express from "npm:express@4"; const app = express(); diff --git a/runtime/manual/node/node_specifiers.md b/runtime/manual/node/node_specifiers.md index e1b4fabb2..67d0bd971 100644 --- a/runtime/manual/node/node_specifiers.md +++ b/runtime/manual/node/node_specifiers.md @@ -6,7 +6,7 @@ Deno supports using Node.js built-in modules such as [process](https://nodejs.org/api/process.html#process), and many more via `node:` specifiers. -```ts, ignore +```ts import { readFileSync } from "node:fs"; console.log(readFileSync("deno.json", { encoding: "utf8" })); diff --git a/runtime/manual/node/package_json.md b/runtime/manual/node/package_json.md index fd2efca8a..77be3bc4e 100644 --- a/runtime/manual/node/package_json.md +++ b/runtime/manual/node/package_json.md @@ -5,9 +5,7 @@ current or ancestor directories. This is similar to how Node.js resolves dependencies. We recommend using import maps with `deno.json` which is explained [here](../basics/import_maps.md). -**package.json** - -```json +```json title="package.json" { "name": "@deno/my-example-project", "description": "An example app created with Deno", @@ -21,9 +19,7 @@ dependencies. We recommend using import maps with `deno.json` which is explained } ``` -**main.ts** - -```ts, ignore +```ts title="main.ts" import chalk from "chalk"; console.log(chalk.green("Hello from Deno!")); @@ -31,14 +27,14 @@ console.log(chalk.green("Hello from Deno!")); Then we can run this script: -```shell, ignore +```shell > deno run --allow-env --allow-sys main.ts Hello from Deno! ``` Or also execute package.json scripts via `deno task`: -```shell, ignore +```shell > deno task dev Hello from Deno! ``` diff --git a/runtime/manual/runtime/http_server_apis.md b/runtime/manual/runtime/http_server_apis.md index 675d4e12f..b6781c314 100644 --- a/runtime/manual/runtime/http_server_apis.md +++ b/runtime/manual/runtime/http_server_apis.md @@ -1,13 +1,12 @@ # HTTP Server APIs -Deno currently has three HTTP Server APIs: +Deno currently has two HTTP Server APIs: - [`Deno.serve`](https://deno.land/api?s=Deno.serve): native, _higher-level_, supports HTTP/1.1 and HTTP2, this is the preferred API to write HTTP servers in Deno. - [`Deno.serveHttp`](https://deno.land/api?s=Deno.serveHttp): native, _low-level_, supports HTTP/1.1 and HTTP2. - - [A "Hello World" server](#a-hello-world-server) - [Inspecting the incoming request](#inspecting-the-incoming-request) - [Responding with a response](#responding-with-a-response) diff --git a/runtime/manual/runtime/permission_apis.md b/runtime/manual/runtime/permission_apis.md index 64bb66cc5..48a7bd006 100644 --- a/runtime/manual/runtime/permission_apis.md +++ b/runtime/manual/runtime/permission_apis.md @@ -36,8 +36,8 @@ const desc5 = { name: "hrtime" } as const; ``` > ⚠️ See -> [`PermissionDescriptor`](https://www.deno.land/api?s=Deno.PermissionDescriptor) -> in API reference for more details. +> [`PermissionDescriptor`](https://deno.land/api?s=Deno.PermissionDescriptor) in +> API reference for more details. > ⚠️ In 1.30 and onwards, synchronous API counterparts (ex. > `Deno.permissions.querySync`) exist for all the APIs described below. diff --git a/runtime/manual/runtime/web_platform_apis.md b/runtime/manual/runtime/web_platform_apis.md index 070b2a196..4906bc07c 100644 --- a/runtime/manual/runtime/web_platform_apis.md +++ b/runtime/manual/runtime/web_platform_apis.md @@ -1,12 +1,13 @@ # Using Web Platform APIs -Deno aims to use web platform APIs (like `fetch`) instead of inventing a new -proprietary API where it makes sense. These APIs generally follow the -specifications and should match the implementation in Chrome and Firefox. In -some cases it makes sense to deviate from the spec slightly, because of the -different security model Deno has. +One way Deno simplifies web and cloud development is by using Web Platform APIs +(like `fetch`) over proprietary APIs. This means if you've ever built for the +browser, you're likely already familiar with Deno, and if you're learning Deno, +you're also investing in your knowledge of the web. -Here is a list of web platform APIs Deno implements: +## Supported APIs + +Here's a partial list of supported web platform APIs in Deno: - [Blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob) - [BroadcastChannel](https://developer.mozilla.org/en-US/docs/Web/API/BroadcastChannel) @@ -33,7 +34,12 @@ Here is a list of web platform APIs Deno implements: - [Web Workers API](https://developer.mozilla.org/en-US/docs/Web/API/Worker) - [`WebSocket`](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket) -You can find the Deno reference for these APIs [here](https://deno.land/api). +You can find the Deno reference for these APIs [here](https://deno.land/api). To +check if a Web Platform API is available in Deno, click on +[the interface on MDN](https://developer.mozilla.org/en-US/docs/Web/API#interfaces) +and refer to +[its Browser Compatibility table](https://developer.mozilla.org/en-US/docs/Web/API/AbortController#browser_compatibility) +(link as an example). ## `fetch` API From d61eb7db64d12d8fa8a30dae0bed8694be2622ad Mon Sep 17 00:00:00 2001 From: Kevin Whinnery Date: Fri, 15 Sep 2023 14:27:04 -0500 Subject: [PATCH 2/3] revert title --- runtime/manual/basics/modules/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/runtime/manual/basics/modules/index.md b/runtime/manual/basics/modules/index.md index 011586642..0b2c2dde0 100644 --- a/runtime/manual/basics/modules/index.md +++ b/runtime/manual/basics/modules/index.md @@ -1,4 +1,4 @@ -# Modules +# ECMAScript Modules in Deno ## Concepts From 493000a1181ea0da5b2c1f6b4f080f8dc08791a2 Mon Sep 17 00:00:00 2001 From: Kevin Whinnery Date: Fri, 15 Sep 2023 14:40:39 -0500 Subject: [PATCH 3/3] add license --- LICENSE | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) create mode 100644 LICENSE diff --git a/LICENSE b/LICENSE new file mode 100644 index 000000000..37beb2277 --- /dev/null +++ b/LICENSE @@ -0,0 +1,20 @@ +MIT License + +Copyright 2023 the Deno Authors + +Permission is hereby granted, free of charge, to any person obtaining a copy of +this software and associated documentation files (the “Software”), to deal in +the Software without restriction, including without limitation the rights to +use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of +the Software, and to permit persons to whom the Software is furnished to do so, +subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS +FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR +COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER +IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN +CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.