denoland / deno-docs Goto Github PK

View Code? Open in Web Editor NEW

49.0 49.0 88.0 17.65 MB

Deno documentation, examples and API Reference. Powered by Lume.

Home Page: https://docs.deno.com

License: MIT License

JavaScript 1.46% TypeScript 93.76% CSS 4.78%

deno-docs's People

Contributors

Stargazers

Watchers

Forkers

johnspurlock kt3k nberlette dsherret denobot mohsinalipro bipo38 rgbkrk indranilkhedkar bukhalo felipecrs phibkro motoya-k lupinum-dev yabuki taisan11 gjzwiers arnoldderoij michrome jlandowner beefsack luob1215 tniessen scarf005 adamzerner ngdangtu-vn nicolo-ribaudo pawelgrzybek ryuapp myty ooker777 muddlebee lczerniawski mearman mavdotjs chengr4 iuioiua bcomnes tjamesmac jiawei397 noracodes danieltprice cre3per yairrand bombillazo bavoco danielkim1 gabrielbrattgard johnspurlock-skymethod eryue0220 nathanwhit lino-levan sobanieca yusato saravieira magurotuna you-saku ldanilov losfair nreilingh ahai-code olets mmastrac htunnicliff numbertheory jozef-javorsky-dodo dandv healingdrawing ashishkujoy donjo fwqaaq catme0w cosmoswafer hwittenborn raiindev sntran maheshbansod-wingify ericmutta timreichen gmarty zebreus mattvr mugi0096 nus3 irbull byvide sbmsr josanshuo

deno-docs's Issues

Improve contributing guidelines

I suggest the maintainers add a CONTRIBUTING.md file:
https://mozillascience.github.io/working-open-workshop/contributing/

As someone who just had the need to clone Deno & poke around, I can say that beyond just regular rust setup, there are a lot of not fully clear things, e.g:

What does a comfortable DX looks like for debugging *.js files from ext/?
Known issues with compilation? (for example, it seemed like cargo was over-zealously rebuilding some packages for me

And just in general, it's a very friendly way to let someone who can contribute code or debug something know how to get the rubber to hit the road with minimal headaches.

If those instructions do exist somewhere, you could link them from CONTRIBUTING.md or vice versa, because if they DO exist, they weren't very easily discoverable (I sure did try)

Style Guide `Exported functions` section needs updated

Deno.serve API isn't consistent with the current Exported functions section of the style guide. We need to update the style guide to cover Deno.serve design

jsdom manual example - Not Implemented: isContext

Using the manual example for:
https://github.com/denoland/manual/blob/v1.26.1/jsx_dom/jsdom.md
I get:

error: Uncaught Error: Not implemented: isContext
throw new Error(message);
^
at notImplemented (https://deno.land/[email protected]/node/_utils.ts:23:9)
at Object.isContext (https://deno.land/[email protected]/node/vm.ts:62:3)
at new Sme (https://esm.sh/v96/[email protected]/deno/jsdom.js:800:8449)
at iY.createWindow (https://esm.sh/v96/[email protected]/deno/jsdom.js:800:6192)
at new py (https://esm.sh/v96/[email protected]/deno/jsdom.js:800:23482)
at file:///Users/tracey/av/jsdom.js:4:34

I tried a few versions back in jsdom -- just in case it was that. But get same style failure up to versions 1y old, too, eg:

deno eval 'import { JSDOM } from  "https://esm.sh/[email protected]"; new JSDOM("<!DOCTYPE html><html><body></body></html>")'

I'm using latest v1.26.1 of deno. Any help appreciated! I'd love to convert my work codebase jest-based (a fair amount using jsdom) from node to deno. (I tried
import { DOMParser } from 'https://deno.land/x/deno_dom/deno-dom-wasm.ts'; too. And that is working decently for some of the testing -- but we could use a more complete DOM fake for some tests (eg: form submitting, etc.)

Full example here:

> cat deno.jsonc;
{
  "compilerOptions": {
    "lib": [
      "deno.ns",
      "dom",
      "dom.iterable",
      "dom.asynciterable"
    ]
  }
}


> cat jsdom.js   
import { JSDOM } from  "https://esm.sh/jsdom";
import { assert } from "https://deno.land/[email protected]/testing/asserts.ts";

const { window: { document } } = new JSDOM(
  `<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Hello from Deno</title>
  </head>
  <body>
    <h1>Hello from Deno</h1>
    <form>
      <input name="user">
      <button>
        Submit
      </button>
    </form>
  </body>
</html>`,
  {
    url: "https://example.com/",
    referrer: "https://example.org/",
    contentType: "text/html",
    storageQuota: 10000000,
  },
);

const h1 = document.querySelector("h1");
assert(h1);

console.log(h1.textContent);


> deno run -A jsdom.js
error: Uncaught Error: Not implemented: isContext
  throw new Error(message);
        ^
    at notImplemented (https://deno.land/[email protected]/node/_utils.ts:23:9)
    at Object.isContext (https://deno.land/[email protected]/node/vm.ts:62:3)
    at new Sme (https://esm.sh/v96/[email protected]/deno/jsdom.js:800:8449)
    at iY.createWindow (https://esm.sh/v96/[email protected]/deno/jsdom.js:800:6192)
    at new py (https://esm.sh/v96/[email protected]/deno/jsdom.js:800:23482)
    at file:///Users/tracey/av/jsdom.js:4:34

Add "What has changed?" page

It would be great if manual had "What has changed?" page. It's not easy right now for users to see what new additions where made to manual since the last release.

It's unreasonable to expect users to go to Github repository and see commit log to figure this out. This could be somehow generated using git log and then mapped to actual manual pages with additions.

CC @lucacasonato

Document special env variables

Special env variables are documented in deno --help output, but some of these are not mentioned in the manual at all. I think we need a page for listing these env vars in the manual to make these variables searchable in the homepage.

ENVIRONMENT VARIABLES:
    DENO_AUTH_TOKENS     A semi-colon separated list of bearer tokens and
                         hostnames to use when fetching remote modules from
                         private repositories
                         (e.g. "[email protected];[email protected]")
    DENO_TLS_CA_STORE    Comma-separated list of order dependent certificate
                         stores. Possible values: "system", "mozilla".
                         Defaults to "mozilla".
    DENO_CERT            Load certificate authority from PEM encoded file
    DENO_DIR             Set the cache directory
    DENO_INSTALL_ROOT    Set deno install's output directory
                         (defaults to $HOME/.deno/bin)
    DENO_NO_PROMPT       Set to disable permission prompts on access
                         (alternative to passing --no-prompt on invocation)
    DENO_NO_UPDATE_CHECK Set to disable checking if a newer Deno version is
                         available
    DENO_WEBGPU_TRACE    Directory to use for wgpu traces
    DENO_JOBS            Number of parallel workers used for the --parallel
                         flag with the test subcommand. Defaults to number
                         of available CPUs.
    HTTP_PROXY           Proxy address for HTTP requests
                         (module downloads, fetch)
    HTTPS_PROXY          Proxy address for HTTPS requests
                         (module downloads, fetch)
    NPM_CONFIG_REGISTRY  URL to use for the npm registry.
    NO_COLOR             Set to disable color
    NO_PROXY             Comma-separated list of hosts which do not use a proxy
                         (module downloads, fetch)

Redirect /manual* and /deploy/docs* to docs.deno.land

When docs.deno.land is in a shippable state, add redirects for both the manual and deploy docs in the main dotcom repo. API reference won't be initially redirected until the generation step is working.

Ensure all TODO doc placeholders are swapped out

Search the runtime and deploy folder for markdown files containing todo - there may be some hanging around to clean up.

[Basics/React]: Is note on Aleph using Preact correct?

Note: Fresh and Aleph.js provide a framework for developing React-like websites, but use an alternative foundational technology, Preact to provide a better, more performant experience.

https://deno.com/[email protected]/basics/react

I don't believe this is correct, given that the very first issue in Aleph's tracker is requesting Preact support?

The new version path of twind has no sheets

https://deno.land/[email protected]/advanced/jsx_dom/twind

import { setup, tw } from "https://esm.sh/[email protected]"
import { virtualSheet, getStyleTag } from "https://esm.sh/[email protected]/sheets"

These two items, the import above is correct, but the url below is invalid

Add section on using Rust in Deno

We should add wasmbuild to the manual https://deno.com/blog/wasmbuild

I think this would go under the "Using WebAssembly" section.

Create new social / OG image for Deno Docs

Need a new dedicated social image that is docs-specific (ideally). Should replace current static/social.png.

Subprocess example: Child process not closed during test

https://deno.land/[email protected]/examples/subprocess

Deno.test("example", async () => {
  const cmd = ["echo", "hello"];

  // create subprocess
  const p = Deno.run({ cmd });

  // await its completion
  await p.status();
})

A child process (rid xxx) was started during the test, but not closed during the test. 
Close the child process by calling `proc.kill()` or `proc.close()`.

Depricate all refrences to skypack.dev

The skypack-cdn seems to be abandoned. No issue updates have been made recently and the search API on the website is broken. We should:

Preemptively replace links from skypack.dev to esm.sh to ensure if skypack.dev goes completely down new users won't be confused
Note on the node-faq page that the project seems to be abandoned and should not be used.

Add "deno test" section to tools

Code from section "Reading a file" warns "deprecation"

The example uses import { copy } from "https://deno.land/[email protected]/streams/conversion.ts";, reporting the following warning:

@deprecated
(will be removed after 0.169.0) Import from std/streams/copy.ts instead.

It would be nice to upgrade it to use something like import { copy } from "https://deno.land/[email protected]/streams/copy.ts";.

List not supported features of standalone Deno apps

I think it would be helpful to list here what features are not supported in standalone (aka deno compile) apps. As far I know, there isn't any official doc mentioning the differences.

I only know of Web Workers, but there might be others too.

Thoughts ? 😄

Add manual installation guide

There're many edge cases where install.sh doesn't work well with users environment (e.g. missing unzip, broken curl, the shell is not bash or zsh ), but also we don't want to make install.sh more complex to support those edge cases.

To address those edge cases, I suggest we should have manual installation guide, which instructs the users to install Deno completely manually (like with the sections 1. Download, 2. Move, 3. Configure $PATH and each section describes some alternatives.)

esm.sh vs npm specifiers

call out benefits to use npm specifiers over esh.sm:

the major advantage of npm specifiers is that you don't have to rely on 3rd party service to transpile them and Deno's static analysis is more precise than esm.sh due to being run locally. that allows you to load Node-API files and data files from packages. which isn't really possible with esm.sh.

Redesign home page away from cartoon graphics to a more austere look

Don't lean on Deno hand-drawn graphic background in the docs home page. Come up with a new look that is a bit more minimalistic.

Create SubChapter of Embedding Deno

Related to denoland/manual#15

It is important to have an easy-to-use explanation of all of deno's crates and what features they provide.

It makes it easier to build custom operators and pick and choose features to create the perfect Embedded Runtime.

Redundant limitation sections on the jsx page.

There's two limitations mentioned at the bottom of
https://github.com/denoland/manual/blob/v1.32.1/advanced/jsx_dom/jsx.md

Both of the issues that have been linked are closed, so I think these limitations can be removed?
I'm not sure though, I'm only just now getting started with jsx so I have very limited knowledge on the topic.

Add `deno cache` to tools

It's missing: https://deno.land/[email protected]/tools

Configure Algolia search

Connect Algolia search to the doc site using the Docusaurus plugin.

Error in the debugging section?

https://deno.land/[email protected]/getting_started/debugging_your_code#chrome-devtools

You might notice that DevTools pauses execution on the first line of
_constants.ts instead of file_server.ts. This is expected behavior caused by
the way ES modules are evaluated in JavaScript (_constants.ts is left-most,
bottom-most dependency of file_server.ts so it is evaluated first).

In my system, the DevTools pauses execution on os.ts instead of _constants.ts:

I'm using Deno 1.26.0 and Chrome 106.

Deno KV: need to set path if compiled with `deno compile`

need to set path if compiled, eg:

const kv = await Deno.openKv('/tmp/kv.db');

otherwise the compiled binary will open KV in memory (aka nothing is persisted beyond process)

"Manage dependencies" should be a separate chapter

https://deno.land/[email protected]/examples/manage_dependencies

Currently this chapter is very short and not in-depth, whilst the subject at hand is huge.

We should have a separate chapter for how to manage dependencies, including:

examples of existing community tools
anti-patterns
how it's different than Node dep management
how it's similar to Node dep management

Create catch-all handler for 404s in static site

Redirects from deno.land may not be sent to the correct location - in the Oak server sitting on top of the Docusaurus site, introduce a middleware handler that will be the fallback if a static file isn't found. 301 redirect if possible, otherwise 404.

Add chapter to "Testing" section about writing front-end test and DOM integration

This question comes up fairly often on Discord, and here's latest question on GitHub: denoland/deno#14565

Even though we have a chapter about using DOM in Deno, we should update "Testing" chapter to provide some "common recipes" for testing frontend code. We might even want to consider providing some simpler integration in deno_std/testing

Generate standard library API reference

Include generated API reference for the standard library in the docs.deno.land site.

Finish Deno Runtime quick start

The quick start section for the Deno runtime is not yet complete, needs additional content.

Add documentation for WebCrypto API

Summary of what APIs and algorithms Deno currently supports.

Invalid signal: SIGINT process.kill("SIGINT")

https://deno.land/[email protected]/examples/subprocess

I follow the code at the bottom of the document page to execute an invalid type error

import { mergeReadableStreams } from "https://deno.land/[email protected]/streams/merge_readable_streams.ts";

// create the file to attach the process to
const file = await Deno.open("./hello.txt", {
  read: true,
  write: true,
  create: true,
});

// start the process
const process = Deno.run({
  cmd: ["yes"],
  stdout: "piped",
  stderr: "piped",
});

// example of combining stdout and stderr while sending to a file
const joined = mergeReadableStreams(
  process.stdout.readable,
  process.stderr.readable,
);

// returns a promise that resolves when the process is killed/closed
joined.pipeTo(file.writable).then(() => console.log("pipe join done"));

// manually stop process "yes" will never end on its own
setTimeout(() => {
  process.kill("SIGINT"); //Change to SIGTERM, no error
}, 100);

error: Uncaught TypeError: Invalid signal: SIGINT
process.kill("SIGINT"); //SIGTERM
^
at opKill (deno:runtime/js/40_process.js:21:9)
at Process.kill (deno:runtime/js/40_process.js:99:7)
at file:///E:/test/deno/deno01/index.ts:648:11
at Object.action (deno:ext/web/02_timers.js:147:13)
at handleTimerMacrotask (deno:ext/web/02_timers.js:64:12)

How to Deploy Deno to Digital Ocean missing step

I think your otherwise very useful Digital Ocean tutorial page is missing a step:

$ doctl registry login

The push command didn’t work until I had done this.

Document common scenario of packages incorrectly declaring they have a default export instead of `export =`

denoland/deno#17058 (comment)

Update release process docs for using this repo rather than the manual

Ensure CLI team is equipped to update this site for any updates that previously required updates to the manual.

Set up CI and Deno Deploy project

Create the necessary CI integrations and Deno Deploy setup to run the doc site. Site should be hosted on the main Deno Deploy account.

Generate API Reference for Deno runtime as a build task

The API reference today is dynamically generated per request on the server. The current implementation of the doc site links back to deno.land where this work is being done today.

However, this content is not truly dynamic, and could benefit from static generation. This would also allow us to use the sitemap generation features of Docusaurus.

Using the same API endpoints that exist for the Deno runtime today, we should generate MDX files for the Runtime and include them in the runtime docs folder.

Update left navigation for both /runtime and /deploy

Left nav is not finalized or organized for both runtime and deploy docs. This needs to be finished before docs are in a shippable state.

Deno KV: add selecting range with `{ start: ["withdrawal", 1], end: ["withdrawal", 2] }`

Intent here is to add examples for the start and end options for the list operation.

Set up DNS for docs.deno.land / docs.deno.com

Create necessary DNS configuration to serve docs.deno.land / docs.deno.com from this app.

[Deploy docs] - Finish/Fix DynamoDB example

What problem are you trying to solve?

The Connect to DynamoDB docs page has snippets of useful information but is ultimately a let down as there are large gaps that need filled in on your own. It would be far more useful to have a complete working example. Specific issues:

Gather credentials from DynamoDB

My experience in getting credentials was different to this. This may be my inexperience of using AWS, but should be checked for currency.

Write code that connects to DynamoDB

By referencing new ApiFactory().makeNew(DynamoDB) I am assuming that you are referencing https://deno.land/x/aws_api but there is no mention of this anywhere on the page nor any imports anywhere to guide you. Also, there is a strong caveat to using this library, namely:

Do not use this module in mission critical stuff. It's supposed to be for automation scripts, quick & dirty pieces of infrastructure, and prototype microservices and so on. If you just want the real, full-fat AWS SDK, a port of it has been uploaded at /x/aws_sdk.

Either use this library and highlight the caveat or show the example using the official AWS SDK.

Also, this line const data = await client.send(command); is thrown in without any suggestion where command comes from, how to construct it, what it looks like, etc.

Describe the solution you'd like

The docs for this are too light, much is left to the reader to work out and do a disservice to anyone attempting to follow them. Either this example should be properly and more thoroughly completed or this page removed.

Describe alternatives you've considered

As per above, complete this example or remove this page.

Documentation, Adoption, Migration Strategy

No response

Details about the event loop

Deno's manual doesn't seem to have a detail section for the event loop. (I'm new to deno, so I might miss the section.)
How is the event loop implemented in Deno with Tokio different from Node.js?
For example, nextTickQueue doesn't exist in Deno.

https://nodejs.org/en/docs/guides/event-loop-timers-and-nexttick/

Revise Deno Deploy quick start doc

Deno Deploy quick start doc looks like it has not been touched in some time - let's sneak in a revision before going live.

Add banner to doc.deno.land to ask if they meant "docs.deno.land"

doc.deno.land doesn't receive much traffic, but once we ship a docs.deno.land people may end up browsing there by accident. Once docs.deno.land is live, add a banner here with a link.

Missing documentation for `deno check` tool

I think it would be helpful to document deno check usage. I knew the command existed but it's usage is not that clear (including --help output).

I expected deno check to typecheck the whole project but it needs the file. Calling it like this deno check **/**.ts is also not what I was looking for. After some trial and error I figured out that it type-checks all of the imported files recursively so I basically needed to call deno check src/mod.ts.

Would be nice to clarify this in docs.

Negative Not-a-Number?

https://github.com/denoland/manual/blob/c6c176f5a133efc10214e4108a78d6fafa488902/runtime/kv/key_space.md?plain=1#L59-L60

-NaN isn't a thing, right?

Doubts on "Integrity Checking and Lock Files" Article

Greetings!

The article "Integrity Checking and Lock Files" doesn't explain what happen if the checking fails. How the another developer fix the problem? The dependency on cloud has not the code that the project needs. Must the first developer share the dependency manually? How do that?

Thanks. Deno is great!

Add isize to list of supported FFI types

It looks like isize is missing from this table:

https://github.com/denoland/manual/blob/a7ea15e32090a703976f7777d0f2faacff63637f/runtime/ffi_api.md#supported-types

It appears here:

https://github.com/denoland/deno/blob/23647a0d8a409d9a242a7ff5ecfae89fdda8a1bb/ext/ffi/lib.rs#L200

Only isize seems to be missing.

Update manual and deploy docs content for 1.36

Bring in new content from latest feature release from the Manual.

Deno mongoose does not mention that it does not provide types

https://github.com/denoland/manual/blob/main/node/how_to_with_npm/mongoose.md

There are not types in mongoose library.
So it feels a bit weird using deno with under-the-hood ts support but absence of types for such a big library.

Is there any ways to make deno use npm:mongoose and still provide types?