2023-10-28 07:50:54 +00:00
|
|
|
# Deno Standard Library
|
2018-11-07 19:28:47 +00:00
|
|
|
|
2021-03-17 08:30:10 +00:00
|
|
|
[](https://codecov.io/gh/denoland/deno_std)
|
2023-10-28 07:50:54 +00:00
|
|
|
[](https://github.com/denoland/deno_std/actions/workflows/ci.yml)
|
2021-03-17 08:30:10 +00:00
|
|
|
|
2023-10-28 07:50:54 +00:00
|
|
|
High-quality APIs for [Deno](https://deno.com/) and the web. Use fearlessly.
|
2019-01-03 16:40:09 +00:00
|
|
|
|
2024-03-08 15:24:01 +00:00
|
|
|
> **NOTE:** The standard library is also available on JSR - check out the
|
|
|
|
|
> [`@std` scope on JSR here](https://jsr.io/@std).
|
|
|
|
|
|
2023-10-28 07:50:54 +00:00
|
|
|
## Get Started
|
2019-01-03 16:40:09 +00:00
|
|
|
|
2023-10-28 07:50:54 +00:00
|
|
|
```ts
|
|
|
|
|
import { copy } from "https://deno.land/std@$STD_VERSION/fs/copy.ts";
|
2021-02-03 20:47:28 +00:00
|
|
|
|
2023-10-28 07:50:54 +00:00
|
|
|
await copy("./foo", "./bar");
|
|
|
|
|
```
|
2021-02-03 20:47:28 +00:00
|
|
|
|
2023-10-28 07:50:54 +00:00
|
|
|
See [here](#recommended-usage) for recommended usage patterns.
|
2021-02-03 20:47:28 +00:00
|
|
|
|
2023-10-28 07:50:54 +00:00
|
|
|
## Documentation
|
2019-01-03 16:40:09 +00:00
|
|
|
|
2023-10-28 07:50:54 +00:00
|
|
|
Check out the documentation [here](https://deno.land/std?doc).
|
2019-01-03 16:40:09 +00:00
|
|
|
|
2023-10-28 07:50:54 +00:00
|
|
|
## Recommended Usage
|
2020-05-09 12:34:47 +00:00
|
|
|
|
2023-10-28 07:50:54 +00:00
|
|
|
1. Include the version of the library in the import specifier.
|
2020-05-09 12:34:47 +00:00
|
|
|
|
2023-10-28 07:50:54 +00:00
|
|
|
Good:
|
|
|
|
|
```ts
|
2023-11-15 14:39:37 +00:00
|
|
|
import { copy } from "https://deno.land/std@$STD_VERSION/fs/copy.ts";
|
2023-10-28 07:50:54 +00:00
|
|
|
```
|
2020-05-09 12:34:47 +00:00
|
|
|
|
2023-10-28 07:50:54 +00:00
|
|
|
1. Only import modules that you require.
|
2020-07-11 04:52:18 +00:00
|
|
|
|
2023-10-28 07:50:54 +00:00
|
|
|
Bad (when using only one function):
|
|
|
|
|
```ts
|
|
|
|
|
import * as fs from "https://deno.land/std@$STD_VERSION/fs/mod.ts";
|
|
|
|
|
```
|
2018-12-24 15:28:01 +00:00
|
|
|
|
2023-10-28 07:50:54 +00:00
|
|
|
Good (when using only one function):
|
|
|
|
|
```ts
|
|
|
|
|
import { copy } from "https://deno.land/std@$STD_VERSION/fs/copy.ts";
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Good (when using multiple functions):
|
|
|
|
|
```ts
|
|
|
|
|
import * as fs from "https://deno.land/std@$STD_VERSION/fs/mod.ts";
|
|
|
|
|
```
|
|
|
|
|
|
2024-02-25 20:16:11 +00:00
|
|
|
1. Do not import symbols with a name _prefixed_ by an underscore (they're not
|
|
|
|
|
intended for public use).
|
2023-10-28 07:50:54 +00:00
|
|
|
|
|
|
|
|
Bad:
|
2024-02-26 08:46:10 +00:00
|
|
|
```ts, ignore
|
2023-10-28 07:50:54 +00:00
|
|
|
import { _format } from "https://deno.land/std@$STD_VERSION/path/_common/format.ts";
|
|
|
|
|
```
|
2019-04-13 19:30:56 +00:00
|
|
|
|
2024-02-25 20:16:11 +00:00
|
|
|
1. Do not import modules with a directory or filename _prefixed_ by an
|
|
|
|
|
underscore (they're not intended for public use).
|
2020-05-09 12:34:47 +00:00
|
|
|
|
2023-10-28 07:50:54 +00:00
|
|
|
Bad:
|
2024-02-26 08:46:10 +00:00
|
|
|
```ts, ignore
|
2024-02-25 20:16:11 +00:00
|
|
|
import { createLPS } from "https://deno.land/std@$STD_VERSION/streams/_common.ts";
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Good:
|
|
|
|
|
```ts
|
|
|
|
|
import { TextLineStream } from "https://deno.land/std@$STD_VERSION/streams/text_line_stream.ts";
|
2023-10-28 07:50:54 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
|
|
1. Do not import test modules or test data.
|
|
|
|
|
|
|
|
|
|
Bad:
|
|
|
|
|
```ts
|
|
|
|
|
import { test } from "https://deno.land/std@$STD_VERSION/front_matter/test.ts";
|
|
|
|
|
```
|
2019-04-13 19:30:56 +00:00
|
|
|
|
2024-04-22 06:47:41 +00:00
|
|
|
## Packages
|
2023-10-31 06:17:28 +00:00
|
|
|
|
2024-04-22 05:16:28 +00:00
|
|
|
For a package to reach v1 (aka stable) status, it must meet the following
|
|
|
|
|
requirements:
|
|
|
|
|
|
|
|
|
|
1. Approved by four members of the internal team. There must be consensus that
|
|
|
|
|
the API design is satisfactory and unlikely to change in the future.
|
|
|
|
|
1. 100% documented, passing `deno doc --lint` checks and adhering to the
|
|
|
|
|
[documentation guidelines](https://github.com/denoland/deno_std/blob/main/.github/CONTRIBUTING.md#documentation).
|
|
|
|
|
1. Maximum possible test coverage
|
|
|
|
|
1. No open issues or pull requests that might lead to breaking changes. For
|
|
|
|
|
example, issues that suggest new non-breaking features are fine to exist at
|
|
|
|
|
stabilization.
|
|
|
|
|
|
2024-04-22 06:47:41 +00:00
|
|
|
| Package | Status | Latest version |
|
|
|
|
|
| ------------------------------------------------------ | ---------- | ----------------------------------------------------------------------------------------- |
|
|
|
|
|
| [archive](https://jsr.io/@std/archive) | Unstable | [](https://jsr.io/@std/archive) |
|
|
|
|
|
| [assert](https://jsr.io/@std/assert) | Settled | [](https://jsr.io/@std/assert) |
|
|
|
|
|
| [async](https://jsr.io/@std/async) | Settled | [](https://jsr.io/@std/async) |
|
|
|
|
|
| [bytes](https://jsr.io/@std/bytes) | Settled | [](https://jsr.io/@std/bytes) |
|
|
|
|
|
| [cli](https://jsr.io/@std/cli) | Unstable | [](https://jsr.io/@std/cli) |
|
|
|
|
|
| [collections](https://jsr.io/@std/collections) | Settled | [](https://jsr.io/@std/collections) |
|
|
|
|
|
| [console](https://jsr.io/@std/console) | Unstable | [](https://jsr.io/@std/console) |
|
|
|
|
|
| [crypto](https://jsr.io/@std/crypto) | Settled | [](https://jsr.io/@std/crypto) |
|
|
|
|
|
| [csv](https://jsr.io/@std/csv) | Settled | [](https://jsr.io/@std/csv) |
|
|
|
|
|
| [data_structures](https://jsr.io/@std/data_structures) | Unstable | [](https://jsr.io/@std/data-structures) |
|
|
|
|
|
| [datetime](https://jsr.io/@std/datetime) | Unstable | [](https://jsr.io/@std/datetime) |
|
|
|
|
|
| [dotenv](https://jsr.io/@std/dotenv) | Unstable | [](https://jsr.io/@std/dotenv) |
|
|
|
|
|
| [encoding](https://jsr.io/@std/encoding) | Settled | [](https://jsr.io/@std/encoding) |
|
|
|
|
|
| [expect](https://jsr.io/@std/expect) | Unstable | [](https://jsr.io/@std/expect) |
|
|
|
|
|
| [flags](https://jsr.io/@std/flags) | Deprecated | [](https://jsr.io/@std/flags) |
|
|
|
|
|
| [fmt](https://jsr.io/@std/fmt) | Settled | [](https://jsr.io/@std/fmt) |
|
|
|
|
|
| [front_matter](https://jsr.io/@std/front-matter) | Settled | [](https://jsr.io/@std/front-matter) |
|
|
|
|
|
| [fs](https://jsr.io/@std/fs) | Settled | [](https://jsr.io/@std/fs) |
|
|
|
|
|
| [html](https://jsr.io/@std/html) | Unstable | [](https://jsr.io/@std/html) |
|
|
|
|
|
| [http](https://jsr.io/@std/http) | Unstable | [](https://jsr.io/@std/http) |
|
|
|
|
|
| [ini](https://jsr.io/@std/ini) | Unstable | [](https://jsr.io/@std/ini) |
|
|
|
|
|
| [io](https://jsr.io/@std/io) | Unstable | [](https://jsr.io/@std/io) |
|
|
|
|
|
| [json](https://jsr.io/@std/json) | Settled | [](https://jsr.io/@std/json) |
|
|
|
|
|
| [jsonc](https://jsr.io/@std/jsonc) | Settled | [](https://jsr.io/@std/jsonc) |
|
|
|
|
|
| [log](https://jsr.io/@std/log) | Unstable | [](https://jsr.io/@std/log) |
|
|
|
|
|
| [media_types](https://jsr.io/@std/media-types) | Settled | [](https://jsr.io/@std/media-types) |
|
|
|
|
|
| [msgpack](https://jsr.io/@std/msgpack) | Unstable | [](https://jsr.io/@std/msgpack) |
|
|
|
|
|
| [net](https://jsr.io/@std/net) | Unstable | [](https://jsr.io/@std/net) |
|
|
|
|
|
| [path](https://jsr.io/@std/path) | Settled | [](https://jsr.io/@std/path) |
|
|
|
|
|
| [permissions](https://jsr.io/@std/permissions) | Deprecated | [](https://jsr.io/@std/permissions) |
|
|
|
|
|
| [regexp](https://jsr.io/@std/regexp) | Unstable | [](https://jsr.io/@std/regexp) |
|
|
|
|
|
| [semver](https://jsr.io/@std/semver) | Unstable | [](https://jsr.io/@std/semver) |
|
|
|
|
|
| [streams](https://jsr.io/@std/streams) | Settled | [](https://jsr.io/@std/streams) |
|
|
|
|
|
| [testing](https://jsr.io/@std/testing) | Settled | [](https://jsr.io/@std/testing) |
|
|
|
|
|
| [text](https://jsr.io/@std/text) | Unstable | [](https://jsr.io/@std/text) |
|
|
|
|
|
| [toml](https://jsr.io/@std/toml) | Settled | [](https://jsr.io/@std/toml) |
|
|
|
|
|
| [ulid](https://jsr.io/@std/ulid) | Unstable | [](https://jsr.io/@std/ulid) |
|
|
|
|
|
| [url](https://jsr.io/@std/url) | Unstable | [](https://jsr.io/@std/url) |
|
|
|
|
|
| [uuid](https://jsr.io/@std/uuid) | Settled | [](https://jsr.io/@std/uuid) |
|
|
|
|
|
| [webgpu](https://jsr.io/@std/webgpu) | Unstable | [](https://jsr.io/@std/webgpu) |
|
|
|
|
|
| [yaml](https://jsr.io/@std/yaml) | Settled | [](https://jsr.io/@std/yaml) |
|
|
|
|
|
|
|
|
|
|
> Note: Settled status means a package is unlikely to have breaking changes, but
|
|
|
|
|
> has not yet achieved v1 status.
|
2023-10-31 06:17:28 +00:00
|
|
|
|
2024-04-10 01:27:39 +00:00
|
|
|
## Architecture
|
|
|
|
|
|
|
|
|
|
Check out the architecture guide [here](./.github/ARCHITECTURE.md).
|
|
|
|
|
|
2024-01-16 03:18:57 +00:00
|
|
|
## Design
|
|
|
|
|
|
2024-04-16 10:06:02 +00:00
|
|
|
### Minimal Exports
|
2024-01-16 03:18:57 +00:00
|
|
|
|
|
|
|
|
Files are structured to minimize the number of dependencies they incur and the
|
|
|
|
|
amount of effort required to manage them, both for the maintainer and the user.
|
|
|
|
|
In most cases, only a single function or class, alongside its related types, are
|
|
|
|
|
exported. In other cases, functions that incur negligible dependency overhead
|
|
|
|
|
will be grouped together in the same file.
|
|
|
|
|
|
2023-11-15 14:39:37 +00:00
|
|
|
## Deprecation Policy
|
|
|
|
|
|
|
|
|
|
We deprecate the APIs in the Standard Library when they get covered by new
|
|
|
|
|
JavaScript language APIs or new Web Standard APIs. These APIs are usually
|
|
|
|
|
removed after 3 minor versions.
|
|
|
|
|
|
|
|
|
|
If you still need to use such APIs after the removal for some reason (for
|
|
|
|
|
example, the usage in Fresh island), please use the URL pinned to the version
|
|
|
|
|
where they are still available.
|
|
|
|
|
|
|
|
|
|
For example, if you want to keep using `readableStreamFromIterable`, which was
|
|
|
|
|
deprecated and removed in favor of `ReadableStream.from` in `v0.195.0`, please
|
|
|
|
|
use the import URL pinned to `v0.194.0`:
|
|
|
|
|
|
|
|
|
|
```ts
|
|
|
|
|
import { readableStreamFromIterable } from "https://deno.land/std@0.194.0/streams/readable_stream_from_iterable.ts";
|
|
|
|
|
```
|
|
|
|
|
|
2019-02-12 23:23:49 +00:00
|
|
|
## Contributing
|
2019-01-04 04:13:21 +00:00
|
|
|
|
2023-11-11 11:11:19 +00:00
|
|
|
Check out the contributing guidelines [here](.github/CONTRIBUTING.md).
|
2023-10-28 07:50:54 +00:00
|
|
|
|
|
|
|
|
## Releases
|
|
|
|
|
|
|
|
|
|
The Standard Library is versioned independently of the Deno CLI. This will
|
|
|
|
|
change once the Standard Library is stabilized. See
|
2024-01-10 19:01:57 +00:00
|
|
|
[here](https://deno.com/versions.json) for the compatibility of different
|
2023-12-14 06:41:16 +00:00
|
|
|
versions of the Deno Standard Library and the Deno CLI.
|
2023-11-11 11:11:19 +00:00
|
|
|
|
|
|
|
|
A new minor version of the Standard Library is published at the same time as
|
|
|
|
|
every new version of the Deno CLI (including patch versions).
|
2023-11-24 02:54:28 +00:00
|
|
|
|
|
|
|
|
## Badge
|
|
|
|
|
|
|
|
|
|
[](https://deno.land/std)
|
|
|
|
|
|
|
|
|
|
```html
|
|
|
|
|
<a href="https://deno.land/std">
|
|
|
|
|
<img
|
|
|
|
|
width="135"
|
|
|
|
|
height="20"
|
|
|
|
|
src="https://raw.githubusercontent.com/denoland/deno_std/main/badge.svg"
|
|
|
|
|
alt="Built with the Deno Standard Library"
|
|
|
|
|
/>
|
|
|
|
|
</a>
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
```md
|
|
|
|
|
[](https://deno.land/std)
|
|
|
|
|
```
|
