Merge branch 'main' into expect-1

denoland · Jul 21, 2024 · 9820a60 · 9820a60
2 parents 4060a86 + c3ccd67
commit 9820a60
Show file tree

Hide file tree

Showing 77 changed files with 555 additions and 702 deletions.
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
@@ -133,3 +133,23 @@ delimiter. E.g.
  * ```
  */
 ````
+
+### Notices for unstable APIs
+
+Each unstable API must have the
+[`@experimental`](https://tsdoc.org/pages/tags/experimental/) TSDoc tag and a
+[warning alert](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts)
+after the starting description.
+
+```ts
+/**
+ * <description>
+ *
+ * > [!WARNING]
+ * > **UNSTABLE**: New API, yet to be vetted.
+ *
+ * @experimental
+ *
+ * ...
+ */
+```
diff --git a/.github/FAQ.md b/.github/FAQ.md
@@ -18,7 +18,7 @@ The Standard Library aims to compliment the
 By virtue of the APIs it supports, the Standard Library primarily aims to work
 with:
 
-1. [Deno](https://deno.com/)
+1. [Deno](https://deno.com/) (latest stable version and canary)
 1. [Deno Deploy](https://deno.com/deploy)
 1. Web browsers (i.e. [Google Chrome](https://www.google.com.au/chrome/),
    [Mozilla Firefox](https://www.mozilla.org/firefox/),
@@ -31,6 +31,18 @@ support the same APIs that the Standard Library targets. These runtimes include:
 1. [Cloudflare Workers](https://workers.cloudflare.com/)
 1. [Bun](https://bun.sh/)
 
+## Why is the Standard Library versioned differently to the Deno runtime?
+
+Deno is not the only runtime that the Standard Library is designed to work with
+(see above section). Hence, there's no reason to have Deno and the Standard
+Library to be versioned the same. Also, having both projects versioned
+independently allows them to progress asynchronously.
+
+## Which versions of Deno is the Standard Library guaranteed to work with?
+
+The Standard Library is designed to work with the latest stable and canary
+versions of Deno. This is checked-for with all PRs in CI.
+
 ## How is the Standard Library distributed?
 
 The Standard Library is distributed as a library of packages on

diff --git a/.github/workflows/title.yml b/.github/workflows/title.yml
@@ -35,43 +35,43 @@ jobs:
             revert
           # This should be kept up-to-date with the current packages list
           scopes: |
-            archive
-            assert
-            async
-            bytes
-            cache
-            cli
-            collections
-            crypto
-            csv
-            data-structures
-            datetime
-            dotenv
-            encoding
-            expect
-            fmt
-            front-matter
-            fs
-            html
-            http
-            ini
+            archive(/unstable)?
+            assert(/unstable)?
+            async(/unstable)?
+            bytes(/unstable)?
+            cache(/unstable)?
+            cli(/unstable)?
+            collections(/unstable)?
+            crypto(/unstable)?
+            csv(/unstable)?
+            data-structures(/unstable)?
+            datetime(/unstable)?
+            dotenv(/unstable)?
+            encoding(/unstable)?
+            expect(/unstable)?
+            fmt(/unstable)?
+            front-matter(/unstable)?
+            fs(/unstable)?
+            html(/unstable)?
+            http(/unstable)?
+            ini(/unstable)?
             internal
-            io
-            json
-            jsonc
-            log
-            media-types
-            msgpack
-            net
-            path
-            regexp
-            semver
-            streams
-            testing
-            text
-            toml
-            ulid
-            url
-            uuid
-            webgpu
-            yaml
+            io(/unstable)?
+            json(/unstable)?
+            jsonc(/unstable)?
+            log(/unstable)?
+            media-types(/unstable)?
+            msgpack(/unstable)?
+            net(/unstable)?
+            path(/unstable)?
+            regexp(/unstable)?
+            semver(/unstable)?
+            streams(/unstable)?
+            testing(/unstable)?
+            text(/unstable)?
+            toml(/unstable)?
+            ulid(/unstable)?
+            url(/unstable)?
+            uuid(/unstable)?
+            webgpu(/unstable)?
+            yaml(/unstable)?
diff --git a/README.md b/README.md
@@ -1,8 +1,8 @@
 # Deno Standard Library
 
 [![JSR @std](https://jsr.io/badges/@std)](https://jsr.io/@std)
-[![codecov](https://codecov.io/gh/denoland/deno_std/branch/main/graph/badge.svg?token=w6s3ODtULz)](https://codecov.io/gh/denoland/deno_std)
-[![ci](https://github.com/denoland/deno_std/actions/workflows/ci.yml/badge.svg)](https://github.com/denoland/deno_std/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/denoland/std/branch/main/graph/badge.svg?token=w6s3ODtULz)](https://codecov.io/gh/denoland/std)
+[![ci](https://github.com/denoland/std/actions/workflows/ci.yml/badge.svg)](https://github.com/denoland/std/actions/workflows/ci.yml)
 
 High-quality APIs for [Deno](https://deno.com/) and the web. Use fearlessly.
 
@@ -68,7 +68,7 @@ documentation:
 ## Stabilization
 
 The Standard Library is now in the process of stabilizing its packages. See
-[#4600](https://github.com/denoland/deno_std/issues/4600) for details.
+[#4600](https://github.com/denoland/std/issues/4600) for details.
 
 ## Architecture
 
@@ -97,14 +97,14 @@ package versions <1.0.0 follow
   <img
     width="135"
     height="20"
-    src="https://raw.githubusercontent.com/denoland/deno_std/main/badge.svg"
+    src="https://raw.githubusercontent.com/denoland/std/main/badge.svg"
     alt="Built with the Deno Standard Library"
   />
 </a>
 ```
 
 ```md
-[![Built with the Deno Standard Library](https://raw.githubusercontent.com/denoland/deno_std/main/badge.svg)](https://jsr.io/@std)
+[![Built with the Deno Standard Library](https://raw.githubusercontent.com/denoland/std/main/badge.svg)](https://jsr.io/@std)
 ```
 
 ## Frequently Asked Questions

diff --git a/Releases.md b/Releases.md
@@ -1,3 +1,102 @@
+### 2024.07.19
+
+#### @std/async 1.0.0 (major)
+
+- chore(async): release `async@1.0.0` (#5211)
+
+#### @std/cli 1.0.0 (major)
+
+- docs(cli): fix options arguments display (#5486)
+- docs(cli): improve unstable API notices (#5482)
+- docs(cli): documentation tweaks (#5458)
+- chore(cli): release `cli@1.0.0` (#5212)
+
+#### @std/collections 1.0.5 (patch)
+
+- refactor(collections): use `Set.prototype.intersection()` method in
+  `intersect()` (#5417)
+
+#### @std/csv 1.0.0-rc.4 (prerelease)
+
+- BREAKING(csv): remove `ParseError` (#5405)
+
+#### @std/dotenv 0.225.0 (minor)
+
+- BREAKING(dotenv): remove `defaultPath` option from `load[Sync]()` (#5451)
+- BREAKING(dotenv): remove `examplePath` option from `load[Sync]()` (#5450)
+
+#### @std/expect 1.0.0-rc.3 (prerelease)
+
+- fix(expect): improve `expect` type to make it work better with `expect.extend`
+  (#5309)
+
+#### @std/fs 1.0.0-rc.6 (prerelease)
+
+- docs(fs): fix options argument display (#5491)
+- docs(fs): fix options argument display (#5487)
+
+#### @std/http 1.0.0-rc.5 (prerelease)
+
+- docs(http): fix options argument display (#5488)
+- docs(http): fix options argument display (#5489)
+- docs(http): improve unstable API notices (#5483)
+
+#### @std/json 1.0.0-rc.3 (prerelease)
+
+- docs(json): fix options argument display (#5490)
+
+#### @std/jsonc 1.0.0-rc.3 (prerelease)
+
+- docs(jsonc): remove docs for removed `options` parameter (#5438)
+
+#### @std/media-types 1.0.2 (patch)
+
+- fix(media-types): return `video/mp4` for `.mp4` extension (#5475)
+
+#### @std/net 1.0.0-rc.2 (prerelease)
+
+- docs(net): tweak `getNetworkAddress()` return doc (#5473)
+
+#### @std/path 1.0.1 (patch)
+
+- fix(path): support use in dnt (#5478)
+
+#### @std/semver 1.0.0-rc.3 (prerelease)
+
+- BREAKING(semver): replace `prerelease` and `buildmetadata` arguments with
+  options object (#5471)
+
+#### @std/streams 1.0.0-rc.4 (prerelease)
+
+- docs(streams): address documentation issues (#5480)
+- chore(streams): release `streams@1.0.0` (#5213)
+
+#### @std/text 1.0.0 (major)
+
+- BREAKING(text): align to single-export file pattern (#5428)
+- feat(text): add ability for user to control word comparison function (#5448)
+- docs(text): state complexity of `levenshteinDistance()` (#5472)
+- chore(text): release `text@1.0.0` (#5209)
+
+#### @std/ulid 1.0.0 (major)
+
+- fix(ulid): fix decode-time export path (#5432)
+- chore(ulid): release `ulid@1.0.0` (#5206)
+
+#### @std/yaml 1.0.0-rc.4 (prerelease)
+
+- BREAKING(yaml): replace `YamlError` with `TypeError` in `stringify()` (#5452)
+- BREAKING(yaml): replace `YamlError` with `SyntaxError` in `parse()` (#5446)
+- docs(yaml): list `extended` schema (#5444)
+- refactor(yaml): change `object` type from `any` to `unknown` in `writeNode`
+  (#5404)
+- refactor(yaml): remove `instanceOf` field of `Type` (#5462)
+- refactor(yaml): add `KindType` generic type argument to `Type` (#5461)
+- refactor(yaml): improve `Type.predicate` behavior (#5460)
+- refactor(yaml): remove `Type.loadKind` property (#5459)
+- refactor(yaml): remove dead code in `Schema` constructor (#5445)
+- refactor(yaml): make `Type.kind` required (#5442)
+
 ### 2024.07.12
 
 #### @std/async 1.0.0-rc.4 (prerelease)

diff --git a/_tools/check_docs.ts b/_tools/check_docs.ts
@@ -409,7 +409,6 @@ function assertConstructorDocs(
       assertHasParamTag(constructor, param.left.name);
     }
   }
-  assertHasExampleTag(constructor);
 }
 
 /**

diff --git a/async/deno.json b/async/deno.json
@@ -1,6 +1,6 @@
 {
   "name": "@std/async",
-  "version": "1.0.0-rc.4",
+  "version": "1.0.0",
   "exports": {
     ".": "./mod.ts",
     "./abortable": "./abortable.ts",

diff --git a/cli/deno.json b/cli/deno.json
@@ -1,6 +1,6 @@
 {
   "name": "@std/cli",
-  "version": "1.0.0-rc.5",
+  "version": "1.0.0",
   "exports": {
     ".": "./mod.ts",
     "./parse-args": "./parse_args.ts",

diff --git a/cli/parse_args.ts b/cli/parse_args.ts
@@ -237,7 +237,7 @@ type Dedot<TKey extends string, TValue> = TKey extends
 
 type ValueOf<TValue> = TValue[keyof TValue];
 
-/** The value returned from `parseArgs`. */
+/** The value returned from {@linkcode parseArgs}. */
 export type Args<
   // deno-lint-ignore no-explicit-any
   TArgs extends Record<string, unknown> = Record<string, any>,
@@ -260,7 +260,7 @@ type DoubleDash = {
   "--"?: Array<string>;
 };
 
-/** The options for the `parseArgs` call. */
+/** Options for {@linkcode parseArgs}. */
 export interface ParseOptions<
   TBooleans extends BooleanType = BooleanType,
   TStrings extends StringType = StringType,
@@ -435,12 +435,12 @@ const FLAG_REGEXP =
  * considered a key-value pair. Any arguments which could not be parsed are
  * available in the `_` property of the returned object.
  *
- * By default, the flags module tries to determine the type of all arguments
- * automatically and the return type of the `parseArgs` method will have an index
+ * By default, this module tries to determine the type of all arguments
+ * automatically and the return type of this function will have an index
  * signature with `any` as value (`{ [x: string]: any }`).
  *
  * If the `string`, `boolean` or `collect` option is set, the return value of
- * the `parseArgs` method will be fully typed and the index signature of the return
+ * this function will be fully typed and the index signature of the return
  * type will change to `{ [x: string]: unknown }`.
  *
  * Any arguments after `'--'` will not be parsed and will end up in `parsedArgs._`.
@@ -449,6 +449,7 @@ const FLAG_REGEXP =
  * or `options.boolean` is set for that argument name.
  *
  * @param args An array of command line arguments.
+ * @param options Options for the parse function.
  *
  * @typeParam TArgs Type of result.
  * @typeParam TDoubleDash Used by `TArgs` for the result.
@@ -496,7 +497,17 @@ export function parseArgs<
   TAliasNames extends string = string,
 >(
   args: string[],
-  {
+  options?: ParseOptions<
+    TBooleans,
+    TStrings,
+    TCollectable,
+    TNegatable,
+    TDefaults,
+    TAliases,
+    TDoubleDash
+  >,
+): Args<TArgs, TDoubleDash> {
+  const {
     "--": doubleDash = false,
     alias = {} as NonNullable<TAliases>,
     boolean = false,
@@ -506,16 +517,7 @@ export function parseArgs<
     collect = [],
     negatable = [],
     unknown: unknownFn = (i: string): unknown => i,
-  }: ParseOptions<
-    TBooleans,
-    TStrings,
-    TCollectable,
-    TNegatable,
-    TDefaults,
-    TAliases,
-    TDoubleDash
-  > = {},
-): Args<TArgs, TDoubleDash> {
+  } = options ?? {};
   const aliasMap: Map<string, Set<string>> = new Map();
   const booleanSet = new Set<string>();
   const stringSet = new Set<string>();

diff --git a/cli/prompt_secret.ts b/cli/prompt_secret.ts
@@ -29,6 +29,7 @@ export type PromptSecretOptions = {
  * Use an empty `mask` if you don't want to show any character.
  *
  * @param message The prompt message to show to the user.
+ * @param options The options for the prompt.
  * @returns The string that was entered or `null` if stdin is not a TTY.
  *
  * @example Usage
@@ -43,8 +44,10 @@ export type PromptSecretOptions = {
  */
 export function promptSecret(
   message = "Secret",
-  { mask = "*", clear }: PromptSecretOptions = {},
+  options?: PromptSecretOptions,
 ): string | null {
+  const { mask = "*", clear } = options ?? {};
+
   if (!input.isTerminal()) {
     return null;
   }
-Original file line number
+Diff line change
@@ Expand Up / @@ -409,7 +409,6 @@ function assertConstructorDocs( @@
           assertHasParamTag(constructor, param.left.name);
         }
       }
-      assertHasExampleTag(constructor);
     }
     /**
@@ Expand Down @@