From 31b906db997ae97bc864b2997f5da25c329944c3 Mon Sep 17 00:00:00 2001 From: Asher Gomez Date: Mon, 3 Jun 2024 14:10:27 +1000 Subject: [PATCH] chore: ensure code examples use assertions in Doc Linter (#4911) --- _tools/check_docs.ts | 11 ++- async/deadline.ts | 3 +- async/delay.ts | 4 +- async/mod.ts | 2 +- async/mux_async_iterator.ts | 28 +++--- async/pool.ts | 5 +- async/retry.ts | 12 +-- async/tee.ts | 11 ++- bytes/concat.ts | 2 +- cli/parse_args.ts | 14 +-- cli/spinner.ts | 7 +- cli/unicode_width.ts | 14 +-- collections/sort_by.ts | 7 ++ crypto/mod.ts | 2 +- data_structures/binary_heap.ts | 86 +++++++++++++----- data_structures/binary_search_tree.ts | 101 ++++++++++++++++------ data_structures/comparators.ts | 16 ++-- data_structures/red_black_tree.ts | 35 +++++--- datetime/day_of_year.ts | 6 +- datetime/difference.ts | 38 ++++---- datetime/format.ts | 18 ++-- datetime/is_leap.ts | 25 +++--- datetime/mod.ts | 12 +-- datetime/parse.ts | 7 +- datetime/week_of_year.ts | 5 +- deno.json | 4 +- expect/expect.ts | 4 +- expect/fn.ts | 4 +- expect/mod.ts | 2 +- fmt/bytes.ts | 60 ++++++++----- fmt/colors.ts | 100 ++++++++++----------- fmt/duration.ts | 25 +++--- fmt/printf.ts | 18 ++-- html/entities.ts | 26 ++++-- html/mod.ts | 10 +-- http/cookie.ts | 25 ++++-- http/etag.ts | 2 +- http/negotiation.ts | 47 +++++----- http/server_sent_event_stream.ts | 2 +- http/status.ts | 21 +++-- http/unstable_signed_cookie.ts | 6 +- internal/build_message.ts | 2 +- internal/styles.ts | 20 ++--- jsonc/mod.ts | 14 +-- jsonc/parse.ts | 10 +-- path/mod.ts | 14 +-- path/posix/glob_to_regexp.ts | 5 +- path/posix/mod.ts | 10 +-- path/windows/glob_to_regexp.ts | 3 +- path/windows/mod.ts | 10 +-- semver/mod.ts | 16 +++- streams/buffer.ts | 10 +-- streams/byte_slice_stream.ts | 4 +- streams/delimiter_stream.ts | 4 +- streams/iterate_reader.ts | 8 +- streams/limited_bytes_transform_stream.ts | 4 +- streams/limited_transform_stream.ts | 4 +- streams/readable_stream_from_reader.ts | 2 +- streams/reader_from_iterable.ts | 2 +- streams/reader_from_stream_reader.ts | 2 +- streams/text_delimiter_stream.ts | 8 +- streams/text_line_stream.ts | 39 ++++++--- streams/writable_stream_from_writer.ts | 2 +- streams/writer_from_stream_writer.ts | 2 +- text/case.ts | 13 ++- text/closest_string.ts | 9 +- text/compare_similarity.ts | 13 ++- text/levenshtein_distance.ts | 4 +- text/mod.ts | 3 +- text/word_similarity_sort.ts | 15 ++-- toml/mod.ts | 42 ++++----- ulid/mod.ts | 30 ++++--- webgpu/describe_texture_format.ts | 10 ++- webgpu/row_padding.ts | 11 ++- 74 files changed, 716 insertions(+), 456 deletions(-) diff --git a/_tools/check_docs.ts b/_tools/check_docs.ts index 5c5d6e1be..a32444e52 100644 --- a/_tools/check_docs.ts +++ b/_tools/check_docs.ts @@ -61,6 +61,7 @@ const ENTRY_POINTS = [ ] as const; const TS_SNIPPET = /```ts[\s\S]*?```/g; +const ASSERTION_IMPORT = /import \{.*\} from "@std\/assert(?:\/.*)?";/gm; const NEWLINE = "\n"; const diagnostics: DocumentError[] = []; const snippetPromises: Promise[] = []; @@ -198,9 +199,17 @@ function assertSnippetsWork( } } for (let snippet of snippets) { - if (snippet.split(NEWLINE)[0]?.includes("no-eval")) continue; + const delim = snippet.split(NEWLINE)[0]; + if (delim?.includes("no-eval")) continue; // Trim the code block delimiters snippet = snippet.split(NEWLINE).slice(1, -1).join(NEWLINE); + if (!delim?.includes("no-assert")) { + assert( + snippet.match(ASSERTION_IMPORT) !== null, + "Snippet must contain assertion from '@std/assert'", + document, + ); + } snippetPromises.push(assertSnippetEvals(snippet, document)); } } diff --git a/async/deadline.ts b/async/deadline.ts index 53c780230..c755ee183 100644 --- a/async/deadline.ts +++ b/async/deadline.ts @@ -13,8 +13,9 @@ export interface DeadlineOptions { * Error thrown when {@linkcode deadline} times out. * * @example Usage - * ```ts + * ```ts no-assert * import { DeadlineError } from "@std/async/deadline"; + * * const error = new DeadlineError(); * ``` */ diff --git a/async/delay.ts b/async/delay.ts index a96eb9510..1feed535d 100644 --- a/async/delay.ts +++ b/async/delay.ts @@ -19,7 +19,7 @@ export interface DelayOptions { * @param options Additional options. * * @example Basic usage - * ```ts + * ```ts no-assert * import { delay } from "@std/async/delay"; * * // ... @@ -33,7 +33,7 @@ export interface DelayOptions { * Setting `persistent` to `false` will allow the process to continue to run as * long as the timer exists. * - * ```ts + * ```ts no-assert * import { delay } from "@std/async/delay"; * * // ... diff --git a/async/mod.ts b/async/mod.ts index 51c3e1e4f..0b66c91eb 100644 --- a/async/mod.ts +++ b/async/mod.ts @@ -5,7 +5,7 @@ * Provide help with asynchronous tasks like delays, debouncing, deferring, or * pooling. * - * ```ts + * ```ts no-assert * import { delay } from "@std/async/delay"; * * await delay(100); // waits for 100 milliseconds diff --git a/async/mux_async_iterator.ts b/async/mux_async_iterator.ts index 41014d4ef..67c14e272 100644 --- a/async/mux_async_iterator.ts +++ b/async/mux_async_iterator.ts @@ -15,6 +15,7 @@ interface TaggedYieldedValue { * @example Usage * ```ts * import { MuxAsyncIterator } from "@std/async/mux-async-iterator"; + * import { assertEquals } from "@std/assert/assert-equals"; * * async function* gen123(): AsyncIterableIterator { * yield 1; @@ -31,10 +32,10 @@ interface TaggedYieldedValue { * const mux = new MuxAsyncIterator(); * mux.add(gen123()); * mux.add(gen456()); - * for await (const value of mux) { - * // ... - * } - * // ... + * + * const result = await Array.fromAsync(mux); + * + * assertEquals(result, [1, 4, 2, 5, 3, 6]); * ``` * * @typeParam T The type of the provided async iterables and generated async iterable. @@ -54,6 +55,7 @@ export class MuxAsyncIterator implements AsyncIterable { * @example Usage * ```ts * import { MuxAsyncIterator } from "@std/async/mux-async-iterator"; + * import { assertEquals } from "@std/assert/assert-equals"; * * async function* gen123(): AsyncIterableIterator { * yield 1; @@ -63,6 +65,10 @@ export class MuxAsyncIterator implements AsyncIterable { * * const mux = new MuxAsyncIterator(); * mux.add(gen123()); + * + * const result = await Array.fromAsync(mux.iterate()); + * + * assertEquals(result, [1, 2, 3]); * ``` */ add(iterable: AsyncIterable) { @@ -93,6 +99,7 @@ export class MuxAsyncIterator implements AsyncIterable { * @example Usage * ```ts * import { MuxAsyncIterator } from "@std/async/mux-async-iterator"; + * import { assertEquals } from "@std/assert/assert-equals"; * * async function* gen123(): AsyncIterableIterator { * yield 1; @@ -103,9 +110,9 @@ export class MuxAsyncIterator implements AsyncIterable { * const mux = new MuxAsyncIterator(); * mux.add(gen123()); * - * for await (const value of mux) { - * // ... - * } + * const result = await Array.fromAsync(mux.iterate()); + * + * assertEquals(result, [1, 2, 3]); * ``` */ async *iterate(): AsyncIterableIterator { @@ -137,6 +144,7 @@ export class MuxAsyncIterator implements AsyncIterable { * @example Usage * ```ts * import { MuxAsyncIterator } from "@std/async/mux-async-iterator"; + * import { assertEquals } from "@std/assert/assert-equals"; * * async function* gen123(): AsyncIterableIterator { * yield 1; @@ -147,9 +155,9 @@ export class MuxAsyncIterator implements AsyncIterable { * const mux = new MuxAsyncIterator(); * mux.add(gen123()); * - * for await (const value of mux) { - * // ... - * } + * const result = await Array.fromAsync(mux); + * + * assertEquals(result, [1, 2, 3]); * ``` */ [Symbol.asyncIterator](): AsyncIterator { diff --git a/async/pool.ts b/async/pool.ts index 01e6531ef..64f1737e4 100644 --- a/async/pool.ts +++ b/async/pool.ts @@ -17,6 +17,7 @@ export const ERROR_WHILE_MAPPING_MESSAGE = "Threw while mapping."; * @example Usage * ```ts * import { pooledMap } from "@std/async/pool"; + * import { assertEquals } from "@std/assert/assert-equals"; * * const results = pooledMap( * 2, @@ -24,9 +25,7 @@ export const ERROR_WHILE_MAPPING_MESSAGE = "Threw while mapping."; * (i) => new Promise((r) => setTimeout(() => r(i), 1000)), * ); * - * for await (const value of results) { - * // ... - * } + * assertEquals(await Array.fromAsync(results), [1, 2, 3]); * ``` * * @typeParam T the input type. diff --git a/async/retry.ts b/async/retry.ts index a8ce017ac..2fdf627e1 100644 --- a/async/retry.ts +++ b/async/retry.ts @@ -9,10 +9,10 @@ import { exponentialBackoffWithJitter } from "./_util.ts"; * has been reached. * * @example Usage - * ```ts + * ```ts no-assert no-eval * import { RetryError } from "@std/async/retry"; * - * const error = new RetryError({ foo: "bar" }, 3); + * throw new RetryError({ foo: "bar" }, 3); * ``` */ export class RetryError extends Error { @@ -23,10 +23,10 @@ export class RetryError extends Error { * @param attempts the number of retry attempts made. * * @example Usage - * ```ts + * ```ts no-assert no-eval * import { RetryError } from "@std/async/retry"; * - * const error = new RetryError({ foo: "bar" }, 3); + * throw new RetryError({ foo: "bar" }, 3); * ``` */ constructor(cause: unknown, attempts: number) { @@ -95,7 +95,7 @@ const defaultRetryOptions: Required = { * When `jitter` is `0`, waits the full backoff time. * * @example Example configuration 1 - * ```ts + * ```ts no-assert * import { retry } from "@std/async/retry"; * const req = async () => { * // some function that throws sometimes @@ -112,7 +112,7 @@ const defaultRetryOptions: Required = { * ``` * * @example Example configuration 2 - * ```ts + * ```ts no-assert * import { retry } from "@std/async/retry"; * const req = async () => { * // some function that throws sometimes diff --git a/async/tee.ts b/async/tee.ts index 92d30ca4b..172f434b0 100644 --- a/async/tee.ts +++ b/async/tee.ts @@ -54,6 +54,7 @@ class Queue { * @example Usage * ```ts * import { tee } from "@std/async/tee"; + * import { assertEquals } from "@std/assert/assert-equals"; * * const gen = async function* gen() { * yield 1; @@ -63,13 +64,11 @@ class Queue { * * const [branch1, branch2] = tee(gen()); * - * for await (const n of branch1) { - * console.log(n); // => 1, 2, 3 - * } + * const result1 = await Array.fromAsync(branch1); + * assertEquals(result1, [1, 2, 3]); * - * for await (const n of branch2) { - * console.log(n); // => 1, 2, 3 - * } + * const result2 = await Array.fromAsync(branch2); + * assertEquals(result2, [1, 2, 3]); * ``` * * @typeParam T The type of the provided async iterable and the returned async iterables. diff --git a/bytes/concat.ts b/bytes/concat.ts index 7a0bda05e..6dd514f83 100644 --- a/bytes/concat.ts +++ b/bytes/concat.ts @@ -10,7 +10,7 @@ * @example Basic usage * ```ts * import { concat } from "@std/bytes/concat"; - * import { assertEquals } from "@std/assert/assert-equals" + * import { assertEquals } from "@std/assert/assert-equals"; * * const a = new Uint8Array([0, 1, 2]); * const b = new Uint8Array([3, 4, 5]); diff --git a/cli/parse_args.ts b/cli/parse_args.ts index fa7c5af91..d8b5599d0 100644 --- a/cli/parse_args.ts +++ b/cli/parse_args.ts @@ -451,14 +451,14 @@ const FLAG_REGEXP = * @example Usage * ```ts * import { parseArgs } from "@std/cli/parse-args"; - * const parsedArgs = parseArgs(Deno.args); - * ``` + * import { assertEquals } from "@std/assert/assert-equals"; * - * @example Usage - * ```ts - * import { parseArgs } from "@std/cli/parse-args"; - * const parsedArgs = parseArgs(["--foo", "--bar=baz", "./quux.txt"]); - * // parsedArgs: { foo: true, bar: "baz", _: ["./quux.txt"] } + * // For proper use, one should use `parseArgs(Deno.args)` + * assertEquals(parseArgs(["--foo", "--bar=baz", "./quux.txt"]), { + * foo: true, + * bar: "baz", + * _: ["./quux.txt"], + * }); * ``` */ export function parseArgs< diff --git a/cli/spinner.ts b/cli/spinner.ts index d52c3ee7d..c71caa674 100644 --- a/cli/spinner.ts +++ b/cli/spinner.ts @@ -121,7 +121,7 @@ export class Spinner { * Creates a new spinner. * * @example Usage - * ```ts + * ```ts no-assert * import { Spinner } from "@std/cli/spinner"; * * const spinner = new Spinner({ message: "Loading..." }); @@ -169,11 +169,12 @@ export class Spinner { * Get the current color of the spinner. * * @example Usage - * ```ts + * ```ts no-assert * import { Spinner } from "@std/cli/spinner"; * * const spinner = new Spinner({ message: "Loading", color: "blue" }); - * console.log(spinner.color); // "blue" + * + * spinner.color; // Blue ANSI escape sequence * ``` * @returns The color of the spinner or `undefined` if it's using the terminal default. */ diff --git a/cli/unicode_width.ts b/cli/unicode_width.ts index 4ce50f928..e7115b731 100644 --- a/cli/unicode_width.ts +++ b/cli/unicode_width.ts @@ -54,20 +54,22 @@ function charWidth(ch: string) { * @example Calculating the unicode width of a string * ```ts * import { unicodeWidth } from "@std/cli/unicode-width"; + * import { assertEquals } from "@std/assert/assert-equals"; * - * unicodeWidth("hello world"); // 11 - * unicodeWidth("天地玄黃宇宙洪荒"); // 16 - * unicodeWidth("ｆｕｌｌｗｉｄｔｈ"); // 18 + * assertEquals(unicodeWidth("hello world"), 11); + * assertEquals(unicodeWidth("天地玄黃宇宙洪荒"), 16); + * assertEquals(unicodeWidth("ｆｕｌｌｗｉｄｔｈ"), 18); * ``` * * @example Calculating the unicode width of a color-encoded string * ```ts * import { unicodeWidth } from "@std/cli/unicode-width"; * import { stripAnsiCode } from "@std/fmt/colors"; + * import { assertEquals } from "@std/assert/assert-equals"; * - * unicodeWidth(stripAnsiCode("\x1b[36mголубой\x1b[39m")); // 7 - * unicodeWidth(stripAnsiCode("\x1b[31m紅色\x1b[39m")); // 4 - * unicodeWidth(stripAnsiCode("\x1B]8;;https://deno.land\x07🦕\x1B]8;;\x07")); // 2 + * assertEquals(unicodeWidth(stripAnsiCode("\x1b[36mголубой\x1b[39m")), 7); + * assertEquals(unicodeWidth(stripAnsiCode("\x1b[31m紅色\x1b[39m")), 4); + * assertEquals(unicodeWidth(stripAnsiCode("\x1B]8;;https://deno.land\x07🦕\x1B]8;;\x07")), 2); * ``` * * Use diff --git a/collections/sort_by.ts b/collections/sort_by.ts index 8286d7521..d795342ee 100644 --- a/collections/sort_by.ts +++ b/collections/sort_by.ts @@ -77,6 +77,7 @@ export function sortBy( * @example Usage * ```ts * import { sortBy } from "@std/collections/sort-by"; + * import { assertEquals } from "@std/assert/assert-equals"; * * const people = [ * { name: "Anna" }, @@ -84,6 +85,12 @@ export function sortBy( * { name: "John" }, * ]; * const sortedByName = sortBy(people, (it) => it.name); + * + * assertEquals(sortedByName, [ + * { name: "Anna" }, + * { name: "John" }, + * { name: "Kim" }, + * ]); * ``` */ export function sortBy( diff --git a/crypto/mod.ts b/crypto/mod.ts index eccb9df01..37c4eff0b 100644 --- a/crypto/mod.ts +++ b/crypto/mod.ts @@ -7,7 +7,7 @@ * supporting additional encryption APIs, but also delegating to the built-in * APIs when possible. * - * ```ts + * ```ts no-assert * import { crypto } from "@std/crypto/crypto"; * * const message = "Hello, Deno!"; diff --git a/data_structures/binary_heap.ts b/data_structures/binary_heap.ts index c522ce317..602fcb41f 100644 --- a/data_structures/binary_heap.ts +++ b/data_structures/binary_heap.ts @@ -67,14 +67,16 @@ export class BinaryHeap implements Iterable { * Construct an empty binary heap. * * @example Creating an empty binary heap - * ```ts + * ```ts no-assert * import { BinaryHeap } from "@std/data-structures"; + * * const heap = new BinaryHeap(); * ``` * * @example Creating a binary heap with a custom comparison function - * ```ts + * ```ts no-assert * import { BinaryHeap, ascend } from "@std/data-structures"; + * * const heap = new BinaryHeap(ascend); * ``` * @@ -95,8 +97,11 @@ export class BinaryHeap implements Iterable { * @example Getting the underlying array * ```ts * import { BinaryHeap } from "@std/data-structures"; + * import { assertEquals } from "@std/assert/assert-equals"; + * * const heap = BinaryHeap.from([4, 1, 3, 5, 2]); - * heap.toArray(); // [ 5, 4, 3, 1, 2 ] + * + * assertEquals(heap.toArray(), [ 5, 4, 3, 1, 2 ]); * ``` * * @returns An array containing the values in the binary heap. @@ -115,27 +120,31 @@ export class BinaryHeap implements Iterable { * function is copied from the input heap. * * @example Creating a binary heap from an array like - * ```ts + * ```ts no-assert * import { BinaryHeap } from "@std/data-structures"; + * * const heap = BinaryHeap.from([4, 1, 3, 5, 2]); * ``` * * @example Creating a binary heap from an iterable object - * ```ts + * ```ts no-assert * import { BinaryHeap } from "@std/data-structures"; + * * const heap = BinaryHeap.from((function*() { yield* [4, 1, 3, 5, 2]; })()); * ``` * * @example Creating a binary heap from an existing binary heap - * ```ts + * ```ts no-assert * import { BinaryHeap } from "@std/data-structures"; + * * const heap = BinaryHeap.from([4, 1, 3, 5, 2]); * const copy = BinaryHeap.from(heap); * ``` * * @example Creating a binary heap from an array like with a custom comparison function - * ```ts + * ```ts no-assert * import { BinaryHeap, ascend } from "@std/data-structures"; + * * const heap = BinaryHeap.from([4, 1, 3, 5, 2], { compare: ascend }); * ``` * @@ -164,8 +173,9 @@ export class BinaryHeap implements Iterable { * sort the values in the heap after mapping the values. * * @example Creating a binary heap from an array like with a custom mapping function - * ```ts + * ```ts no-eval * import { BinaryHeap } from "@std/data-structures"; + * * const heap = BinaryHeap.from([4, 1, 3, 5, 2], { map: (value) => value * 2 }); * ``` * @@ -224,8 +234,11 @@ export class BinaryHeap implements Iterable { * @example Getting the length of the binary heap * ```ts * import { BinaryHeap } from "@std/data-structures"; + * import { assertEquals } from "@std/assert/assert-equals"; + * * const heap = BinaryHeap.from([4, 1, 3, 5, 2]); - * heap.length; // 5 + * + * assertEquals(heap.length, 5); * ``` * * @returns The count of values stored in the binary heap. @@ -243,15 +256,21 @@ export class BinaryHeap implements Iterable { * @example Getting the greatest value from the binary heap * ```ts * import { BinaryHeap } from "@std/data-structures"; + * import { assertEquals } from "@std/assert/assert-equals"; + * * const heap = BinaryHeap.from([4, 1, 3, 5, 2]); - * heap.peek(); // 5 + * + * assertEquals(heap.peek(), 5); * ``` * * @example Getting the greatest value from an empty binary heap * ```ts * import { BinaryHeap } from "@std/data-structures"; + * import { assertEquals } from "@std/assert/assert-equals"; + * * const heap = new BinaryHeap(); - * heap.peek(); // undefined + * + * assertEquals(heap.peek(), undefined); * ``` * * @returns The greatest value from the binary heap, or undefined if it is empty. @@ -267,9 +286,12 @@ export class BinaryHeap implements Iterable { * @example Removing the greatest value from the binary heap * ```ts * import { BinaryHeap } from "@std/data-structures"; + * import { assertEquals } from "@std/assert/assert-equals"; + * * const heap = BinaryHeap.from([4, 1, 3, 5, 2]); - * heap.pop(); // 5 - * [...heap]; // [ 4, 3, 2, 1 ] + * + * assertEquals(heap.pop(), 5); + * assertEquals([...heap], [4, 3, 2, 1]); * ``` * * The complexity of this operation is on average and worst case O(log n), @@ -278,8 +300,11 @@ export class BinaryHeap implements Iterable { * @example Removing the greatest value from an empty binary heap * ```ts * import { BinaryHeap } from "@std/data-structures"; + * import { assertEquals } from "@std/assert/assert-equals"; + * * const heap = new BinaryHeap(); - * heap.pop(); // undefined + * + * assertEquals(heap.pop(), undefined); * ``` * * @returns The greatest value from the binary heap, or undefined if the heap is empty. @@ -317,9 +342,12 @@ export class BinaryHeap implements Iterable { * @example Adding values to the binary heap * ```ts * import { BinaryHeap } from "@std/data-structures"; + * import { assertEquals } from "@std/assert/assert-equals"; + * * const heap = BinaryHeap.from([4, 1, 3, 2]); * heap.push(5); - * [...heap]; // [ 5, 4, 3, 1, 2 ] + * + * assertEquals([...heap], [5, 4, 3, 2, 1]); * ``` * * @param values The values to add to the binary heap. @@ -348,9 +376,12 @@ export class BinaryHeap implements Iterable { * @example Clearing the binary heap * ```ts * import { BinaryHeap } from "@std/data-structures"; + * import { assertEquals } from "@std/assert/assert-equals"; + * * const heap = BinaryHeap.from([4, 1, 3, 5, 2]); * heap.clear(); - * [...heap]; // [] + * + * assertEquals([...heap], []); * ``` */ clear() { @@ -363,10 +394,15 @@ export class BinaryHeap implements Iterable { * @example Checking if the binary heap is empty * ```ts * import { BinaryHeap } from "@std/data-structures"; + * import { assertEquals } from "@std/assert/assert-equals"; + * * const heap = new BinaryHeap(); - * heap.isEmpty(); // true + * + * assertEquals(heap.isEmpty(), true); + * * heap.push(42); - * heap.isEmpty(); // false + * + * assertEquals(heap.isEmpty(), false); * ``` * * @returns true if the binary heap is empty, otherwise false. @@ -385,9 +421,12 @@ export class BinaryHeap implements Iterable { * @example Draining the binary heap * ```ts * import { BinaryHeap } from "@std/data-structures"; + * import { assertEquals } from "@std/assert/assert-equals"; + * * const heap = BinaryHeap.from([4, 1, 3, 5, 2]); - * [...heap.drain()]; // [ 5, 4, 3, 2, 1 ] - * [...heap.drain()]; // [] + * + * assertEquals([...heap.drain()], [ 5, 4, 3, 2, 1 ]); + * assertEquals([...heap.drain()], []); * ``` * * @returns An iterator for retrieving and removing values from the binary heap. @@ -407,9 +446,12 @@ export class BinaryHeap implements Iterable { * @example Getting an iterator for the binary heap * ```ts * import { BinaryHeap } from "@std/data-structures"; + * import { assertEquals } from "@std/assert/assert-equals"; + * * const heap = BinaryHeap.from([4, 1, 3, 5, 2]); - * [...heap]; // [ 5, 4, 3, 2, 1 ] - * [...heap]; // [] + * + * assertEquals([...heap], [ 5, 4, 3, 2, 1 ]); + * assertEquals([...heap], []); * ``` * * @returns An iterator for retrieving and removing values from the binary heap. diff --git a/data_structures/binary_search_tree.ts b/data_structures/binary_search_tree.ts index 687e9dc00..211047463 100644 --- a/data_structures/binary_search_tree.ts +++ b/data_structures/binary_search_tree.ts @@ -99,13 +99,14 @@ export class BinarySearchTree implements Iterable { * Construct an empty binary search tree. * * @example Creating an empty binary search tree - * ```ts + * ```ts no-assert * import { BinarySearchTree } from "@std/data-structures"; + * * const tree = new BinarySearchTree(); * ``` * * @example Creating a binary search tree with a custom comparison function - * ```ts + * ```ts no-assert * import { BinarySearchTree, ascend } from "@std/data-structures"; * * const tree = new BinarySearchTree<{ price: number, name: string }>( @@ -167,14 +168,16 @@ export class BinarySearchTree implements Iterable { * function is copied from the input tree. * * @example Creating a binary search tree from an array like - * ```ts + * ```ts no-assert * import { BinarySearchTree } from "@std/data-structures"; + * * const tree = BinarySearchTree.from([42, 43, 41]); * ``` * * @example Creating a binary search tree from an iterable object - * ```ts + * ```ts no-assert * import { BinarySearchTree } from "@std/data-structures"; + * * const tree = BinarySearchTree.from((function*() { * yield 42; * yield 43; @@ -183,15 +186,17 @@ export class BinarySearchTree implements Iterable { * ``` * * @example Creating a binary search tree from an existing binary search tree - * ```ts + * ```ts no-assert * import { BinarySearchTree } from "@std/data-structures"; + * * const tree = BinarySearchTree.from([42, 43, 41]); * const copy = BinarySearchTree.from(tree); * ``` * * @example Creating a binary search tree from an array like with a custom comparison function - * ```ts + * ```ts no-assert * import { BinarySearchTree, descend } from "@std/data-structures"; + * * const tree = BinarySearchTree.from( * [42, 43, 41], * { compare: descend } @@ -225,8 +230,9 @@ export class BinarySearchTree implements Iterable { * the values. * * @example Creating a binary search tree from an array like with a custom mapping function - * ```ts + * ```ts no-assert * import { BinarySearchTree } from "@std/data-structures"; + * * const tree = BinarySearchTree.from( * [42, 43, 41], * { map: (value) => value.toString() } @@ -311,10 +317,13 @@ export class BinarySearchTree implements Iterable { * The complexity of this operation is O(1). * * @example Getting the size of the tree - * ```ts + * ```ts no-assert * import { BinarySearchTree } from "@std/data-structures"; + * import { assertEquals } from "@std/assert/assert-equals"; + * * const tree = BinarySearchTree.from([42, 43, 41]); - * tree.size; // 3 + * + * assertEquals(tree.size, 3); * ``` * * @returns The count of values stored in the binary search tree. @@ -427,9 +436,12 @@ export class BinarySearchTree implements Iterable { * @example Inserting values into the tree * ```ts * import { BinarySearchTree } from "@std/data-structures"; + * import { assertEquals } from "@std/assert/assert-equals"; + * * const tree = new BinarySearchTree(); - * tree.insert(42); // true - * tree.insert(42); // false + * + * assertEquals(tree.insert(42), true); + * assertEquals(tree.insert(42), false); * ``` * * @param value The value to insert into the binary search tree. @@ -448,9 +460,12 @@ export class BinarySearchTree implements Iterable { * @example Removing values from the tree * ```ts * import { BinarySearchTree } from "@std/data-structures"; + * import { assertEquals } from "@std/assert/assert-equals"; + * * const tree = BinarySearchTree.from([42]); - * tree.remove(42); // true - * tree.remove(42); // false + * + * assertEquals(tree.remove(42), true); + * assertEquals(tree.remove(42), false); * ``` * * @param value The value to remove from the binary search tree. @@ -471,9 +486,12 @@ export class BinarySearchTree implements Iterable { * @example Finding values in the tree * ```ts * import { BinarySearchTree } from "@std/data-structures"; + * import { assertEquals } from "@std/assert/assert-equals"; + * * const tree = BinarySearchTree.from([42]); - * tree.find(42); // 42 - * tree.find(43); // null + * + * assertEquals(tree.find(42), 42); + * assertEquals(tree.find(43), null); * ``` * * @param value The value to search for in the binary search tree. @@ -493,8 +511,11 @@ export class BinarySearchTree implements Iterable { * @example Finding the minimum value in the tree * ```ts * import { BinarySearchTree } from "@std/data-structures"; + * import { assertEquals } from "@std/assert/assert-equals"; + * * const tree = BinarySearchTree.from([42, 43, 41]); - * tree.min(); // 41 + * + * assertEquals(tree.min(), 41); * ``` * * @returns The minimum value in the binary search tree, or null if the tree is empty. @@ -513,8 +534,11 @@ export class BinarySearchTree implements Iterable { * @example Finding the maximum value in the tree * ```ts * import { BinarySearchTree } from "@std/data-structures"; + * import { assertEquals } from "@std/assert/assert-equals"; + * * const tree = BinarySearchTree.from([42, 43, 41]); - * tree.max(); // 43 + * + * assertEquals(tree.max(), 43); * ``` * * @returns The maximum value in the binary search tree, or null if the tree is empty. @@ -531,10 +555,13 @@ export class BinarySearchTree implements Iterable { * @example Clearing the tree * ```ts * import { BinarySearchTree } from "@std/data-structures"; + * import { assertEquals } from "@std/assert/assert-equals"; + * * const tree = BinarySearchTree.from([42, 43, 41]); * tree.clear(); - * tree.size; // 0 - * tree.find(42); // null + * + * assertEquals(tree.size, 0); + * assertEquals(tree.find(42), null); * ``` */ clear() { @@ -550,10 +577,15 @@ export class BinarySearchTree implements Iterable { * @example Checking if the tree is empty * ```ts * import { BinarySearchTree } from "@std/data-structures"; + * import { assertEquals } from "@std/assert/assert-equals"; + * * const tree = new BinarySearchTree(); - * tree.isEmpty(); // true + * + * assertEquals(tree.isEmpty(), true); + * * tree.insert(42); - * tree.isEmpty(); // false + * + * assertEquals(tree.isEmpty(), false); * ``` * * @returns `true` if the binary search tree is empty, `false` otherwise. @@ -569,8 +601,11 @@ export class BinarySearchTree implements Iterable { * @example Using the in-order LNR iterator * ```ts * import { BinarySearchTree } from "@std/data-structures"; + * import { assertEquals } from "@std/assert/assert-equals"; + * * const tree = BinarySearchTree.from([4, 1, 2, 5, 3]); - * [...tree.lnrValues()] // 1, 2, 3, 4, 5 + * + * assertEquals([...tree.lnrValues()], [1, 2, 3, 4, 5]); * ``` * * @returns An iterator that traverses the tree in-order (LNR). @@ -597,6 +632,8 @@ export class BinarySearchTree implements Iterable { * @example Using the reverse in-order RNL iterator * ```ts * import { BinarySearchTree } from "@std/data-structures"; + * import { assertEquals } from "@std/assert/assert-equals"; + * * const tree = BinarySearchTree.from([4, 1, 2, 5, 3]); * [...tree.rnlValues()] // 5, 4, 3, 2, 1 * ``` @@ -625,8 +662,11 @@ export class BinarySearchTree implements Iterable { * @example Using the pre-order NLR iterator * ```ts * import { BinarySearchTree } from "@std/data-structures"; + * import { assertEquals } from "@std/assert/assert-equals"; + * * const tree = BinarySearchTree.from([4, 1, 2, 5, 3]); - * [...tree.nlrValues()] // 4, 1, 2, 3, 5 + * + * assertEquals([...tree.nlrValues()], [4, 1, 2, 3, 5]); * ``` * * @returns An iterator that traverses the tree in pre-order (NLR). @@ -649,8 +689,11 @@ export class BinarySearchTree implements Iterable { * @example Using the post-order LRN iterator * ```ts * import { BinarySearchTree } from "@std/data-structures"; + * import { assertEquals } from "@std/assert/assert-equals"; + * * const tree = BinarySearchTree.from([4, 1, 2, 5, 3]); - * [...tree.lrnValues()] // 3, 2, 1, 5, 4 + * + * assertEquals([...tree.lrnValues()], [3, 2, 1, 5, 4]); * ``` * * @returns An iterator that traverses the tree in post-order (LRN). @@ -682,8 +725,11 @@ export class BinarySearchTree implements Iterable { * @example Using the level-order BFS iterator * ```ts * import { BinarySearchTree } from "@std/data-structures"; + * import { assertEquals } from "@std/assert/assert-equals"; + * * const tree = BinarySearchTree.from([4, 1, 2, 5, 3]); - * [...tree.lvlValues()] // 4, 1, 5, 2, 3 + * + * assertEquals([...tree.lvlValues()], [4, 1, 5, 2, 3]); * ``` * * @returns An iterator that traverses the tree in level-order (BFS). @@ -706,8 +752,11 @@ export class BinarySearchTree implements Iterable { * @example Using the in-order iterator * ```ts * import { BinarySearchTree } from "@std/data-structures"; + * import { assertEquals } from "@std/assert/assert-equals"; + * * const tree = BinarySearchTree.from([4, 1, 2, 5, 3]); - * [...tree] // 1, 2, 3, 4, 5 + * + * assertEquals([...tree], [1, 2, 3, 4, 5]); * ``` * * See {@link BinarySearchTree#lnrValues}. diff --git a/data_structures/comparators.ts b/data_structures/comparators.ts index b16dc522d..17ef65164 100644 --- a/data_structures/comparators.ts +++ b/data_structures/comparators.ts @@ -8,9 +8,11 @@ * @example Comparing numbers * ```ts * import { ascend } from "@std/data-structures"; - * ascend(1, 2); // -1 - * ascend(2, 1); // 1 - * ascend(1, 1); // 0 + * import { assertEquals } from "@std/assert/assert-equals"; + * + * assertEquals(ascend(1, 2), -1); + * assertEquals(ascend(2, 1), 1); + * assertEquals(ascend(1, 1), 0); * ``` * * @typeparam T The type of the values being compared. @@ -29,9 +31,11 @@ export function ascend(a: T, b: T): -1 | 0 | 1 { * @example Comparing numbers * ```ts * import { descend } from "@std/data-structures"; - * descend(1, 2); // 1 - * descend(2, 1); // -1 - * descend(1, 1); // 0 + * import { assertEquals } from "@std/assert/assert-equals"; + * + * assertEquals(descend(1, 2), 1); + * assertEquals(descend(2, 1), -1); + * assertEquals(descend(1, 1), 0); * ``` * * @typeparam T The type of the values being compared. diff --git a/data_structures/red_black_tree.ts b/data_structures/red_black_tree.ts index d39ec4d49..729899838 100644 --- a/data_structures/red_black_tree.ts +++ b/data_structures/red_black_tree.ts @@ -105,14 +105,16 @@ export class RedBlackTree extends BinarySearchTree { * Construct an empty red-black tree. * * @example Creating an empty red-black tree - * ```ts + * ```ts no-assert * import { RedBlackTree } from "@std/data-structures"; + * * const tree = new RedBlackTree(); * ``` * * @example Creating a red-black tree with a custom comparison function - * ```ts + * ```ts no-assert * import { RedBlackTree, ascend } from "@std/data-structures"; + * * const tree = new RedBlackTree<{ price: number, name: string }>( * (a, b) => ascend(a.price, b.price) || ascend(a.name, b.name) * ); @@ -139,14 +141,16 @@ export class RedBlackTree extends BinarySearchTree { * function is copied from the input tree. * * @example Creating a red-black tree from an array like - * ```ts + * ```ts no-assert * import { RedBlackTree } from "@std/data-structures"; + * * const tree = RedBlackTree.from([3, 10, 13, 4, 6, 7, 1, 14]); * ``` * * @example Creating a red-black tree from an iterable object - * ```ts + * ```ts no-assert * import { RedBlackTree } from "@std/data-structures"; + * * const tree = RedBlackTree.from((function*() { * yield 3; * yield 10; @@ -155,15 +159,17 @@ export class RedBlackTree extends BinarySearchTree { * ``` * * @example Creating a red-black tree from an existing red-black tree - * ```ts + * ```ts no-assert * import { RedBlackTree } from "@std/data-structures"; + * * const tree = RedBlackTree.from([3, 10, 13, 4, 6, 7, 1, 14]); * const copy = RedBlackTree.from(tree); * ``` * * @example Creating a red-black tree from an array like with a custom comparison function - * ```ts + * ```ts no-assert * import { RedBlackTree, descend } from "@std/data-structures"; + * * const tree = RedBlackTree.from([3, 10, 13, 4, 6, 7, 1, 14], { * compare: descend, * }); @@ -196,8 +202,9 @@ export class RedBlackTree extends BinarySearchTree { * the values. * * @example Creating a red-black tree from an array like with a custom mapping function - * ```ts + * ```ts no-assert * import { RedBlackTree } from "@std/data-structures"; + * * const tree = RedBlackTree.from([3, 10, 13, 4, 6, 7, 1, 14], { * map: (value) => value.toString(), * }); @@ -324,9 +331,12 @@ export class RedBlackTree extends BinarySearchTree { * @example Inserting a value into the tree * ```ts * import { RedBlackTree } from "@std/data-structures"; + * import { assertEquals } from "@std/assert/assert-equals"; + * * const tree = new RedBlackTree(); - * tree.insert(42); // true - * tree.insert(42); // false + * + * assertEquals(tree.insert(42), true); + * assertEquals(tree.insert(42), false); * ``` * * @param value The value to insert into the tree. @@ -378,9 +388,12 @@ export class RedBlackTree extends BinarySearchTree { * @example Removing values from the tree * ```ts * import { RedBlackTree } from "@std/data-structures"; + * import { assertEquals } from "@std/assert/assert-equals"; + * * const tree = RedBlackTree.from([42]); - * tree.remove(42); // true - * tree.remove(42); // false + * + * assertEquals(tree.remove(42), true); + * assertEquals(tree.remove(42), false); * ``` * * @param value The value to remove from the tree. diff --git a/datetime/day_of_year.ts b/datetime/day_of_year.ts index 81df7b46d..9e5e182bf 100644 --- a/datetime/day_of_year.ts +++ b/datetime/day_of_year.ts @@ -12,8 +12,9 @@ import { DAY } from "./constants.ts"; * @example Basic usage * ```ts * import { dayOfYear } from "@std/datetime/day-of-year"; + * import { assertEquals } from "@std/assert/assert-equals"; * - * dayOfYear(new Date("2019-03-11T03:24:00")); // 70 + * assertEquals(dayOfYear(new Date("2019-03-11T03:24:00")), 70); * ``` */ export function dayOfYear(date: Date): number { @@ -38,8 +39,9 @@ export function dayOfYear(date: Date): number { * @example Usage * ```ts * import { dayOfYearUtc } from "@std/datetime/day-of-year"; + * import { assertEquals } from "@std/assert/assert-equals"; * - * dayOfYearUtc(new Date("2019-03-11T03:24:00.000Z")) // 70 + * assertEquals(dayOfYearUtc(new Date("2019-03-11T03:24:00.000Z")), 70); * ``` */ export function dayOfYearUtc(date: Date): number { diff --git a/datetime/difference.ts b/datetime/difference.ts index ab87596c6..34aa6aa56 100644 --- a/datetime/difference.ts +++ b/datetime/difference.ts @@ -50,35 +50,43 @@ function calculateMonthsDifference(from: Date, to: Date): number { * @example Basic usage * ```ts * import { difference } from "@std/datetime/difference"; + * import { assertEquals } from "@std/assert/assert-equals"; * * const date0 = new Date("2018-05-14"); * const date1 = new Date("2020-05-13"); * - * difference(date0, date1); - * // { - * // milliseconds: 63072000000, - * // seconds: 63072000, - * // minutes: 1051200, - * // hours: 17520, - * // days: 730, - * // weeks: 104, - * // months: 23, - * // quarters: 7, - * // years: 1 - * // } + * assertEquals(difference(date0, date1), { + * milliseconds: 63072000000, + * seconds: 63072000, + * minutes: 1051200, + * hours: 17520, + * days: 730, + * weeks: 104, + * months: 23, + * quarters: 7, + * years: 1 + * }); * ``` * * @example Calculate difference in specific units + * + * The `units` option defines which units to calculate the difference in. + * * ```ts * import { difference } from "@std/datetime/difference"; + * import { assertEquals } from "@std/assert/assert-equals"; * * const date0 = new Date("2018-05-14"); * const date1 = new Date("2020-05-13"); * - * difference(date0, date1, { units: ["days", "months", "years"] }); - * // { days: 730, months: 23, years: 1 } + * const result = difference(date0, date1, { units: ["days", "months", "years"] }); + * + * assertEquals(result, { + * days: 730, + * months: 23, + * years: 1 + * }); * ``` - * The `units` option defines which units to calculate the difference in. */ export function difference( from: Date, diff --git a/datetime/format.ts b/datetime/format.ts index 69260b449..7df50c4d7 100644 --- a/datetime/format.ts +++ b/datetime/format.ts @@ -42,27 +42,31 @@ export interface FormatOptions { * @return The formatted date string. * * @example Basic usage - * ```ts + * ```ts no-eval * import { format } from "@std/datetime/format"; + * import { assertEquals } from "@std/assert/assert-equals"; * * const date = new Date(2019, 0, 20, 16, 34, 23, 123); * - * format(date, "dd-MM-yyyy"); // "20-01-2019" + * assertEquals(format(date, "dd-MM-yyyy"), "20-01-2019"); * - * format(date, "MM-dd-yyyy HH:mm:ss.SSS"); // "01-20-2019 16:34:23.123" + * assertEquals(format(date, "MM-dd-yyyy HH:mm:ss.SSS"), "01-20-2019 16:34:23.123"); * - * format(date, "'today:' yyyy-MM-dd"); // "today: 2019-01-20" + * assertEquals(format(date, "'today:' yyyy-MM-dd"), "today: 2019-01-20"); * ``` * * @example UTC formatting - * ```ts + * + * Enable UTC formatting by setting the `utc` option to `true`. + * + * ```ts no-eval * import { format } from "@std/datetime/format"; + * import { assertEquals } from "@std/assert/assert-equals"; * * const date = new Date(2019, 0, 20, 16, 34, 23, 123); * - * format(date, "yyyy-MM-dd HH:mm:ss", { utc: true }); // "2019-01-20 05:34:23" + * assertEquals(format(date, "yyyy-MM-dd HH:mm:ss", { utc: true }), "2019-01-20 05:34:23"); * ``` - * Enable UTC formatting by setting the `utc` option to `true`. */ export function format( date: Date, diff --git a/datetime/is_leap.ts b/datetime/is_leap.ts index f89522807..1eba587cc 100644 --- a/datetime/is_leap.ts +++ b/datetime/is_leap.ts @@ -22,25 +22,27 @@ function isYearNumberALeapYear(yearNumber: number): boolean { * @example Basic usage * ```ts * import { isLeap } from "@std/datetime/is-leap"; + * import { assertEquals } from "@std/assert/assert-equals"; * - * isLeap(new Date("1970-01-02")); // false + * assertEquals(isLeap(new Date("1970-01-02")), false); * - * isLeap(1970); // false + * assertEquals(isLeap(1970), false); * - * isLeap(new Date("1972-01-02")); // true + * assertEquals(isLeap(new Date("1972-01-02")), true); * - * isLeap(1972); // true + * assertEquals(isLeap(1972), true); * ``` * * @example Accounting for timezones - * ```ts + * ```ts no-assert * import { isLeap } from "@std/datetime/is-leap"; * + * // True if the local timezone is GMT+0; false if the local timezone is GMT-1 * isLeap(new Date("2000-01-01")); - * // true if the local timezone is GMT+0; false if the local timezone is GMT-1 * + * // True regardless of the local timezone * isLeap(2000); - * // true regardless of the local timezone + * * ``` */ export function isLeap(year: Date | number): boolean { @@ -61,14 +63,15 @@ export function isLeap(year: Date | number): boolean { * @example Basic usage * ```ts * import { isUtcLeap } from "@std/datetime/is-leap"; + * import { assertEquals } from "@std/assert/assert-equals"; * - * isUtcLeap(new Date("2000-01-01")); // true + * assertEquals(isUtcLeap(new Date("2000-01-01")), true); * - * isUtcLeap(new Date("December 31, 1999 23:59:59 GMT-01:00")); // true + * assertEquals(isUtcLeap(new Date("December 31, 1999 23:59:59 GMT-01:00")), true); * - * isUtcLeap(2000); // true + * assertEquals(isUtcLeap(2000), true); * - * isUtcLeap(1999); // false + * assertEquals(isUtcLeap(1999), false); * ``` */ export function isUtcLeap(year: Date | number): boolean { diff --git a/datetime/mod.ts b/datetime/mod.ts index 502d5015d..7590a0ef5 100644 --- a/datetime/mod.ts +++ b/datetime/mod.ts @@ -14,7 +14,7 @@ * {@linkcode dayOfYear} returns the number of the day in the year in the local * timezone. {@linkcode dayOfYearUtc} does the same but in UTC time. * - * ```ts + * ```ts no-assert * import { dayOfYear } from "@std/datetime/day-of-year"; * * dayOfYear(new Date("2019-03-11T03:24:00")); // 70 @@ -25,7 +25,7 @@ * {@linkcode difference} calculates the difference of the 2 given dates in * various units. * - * ```ts + * ```ts no-assert * import { difference } from "@std/datetime/difference"; * * const date0 = new Date("2018-05-14"); @@ -49,7 +49,7 @@ * * {@linkcode format} formats a date to a string with the specified format. * - * ```ts + * ```ts no-assert * import { format } from "@std/datetime/format"; * * const date = new Date(2019, 0, 20, 16, 34, 23, 123); @@ -66,7 +66,7 @@ * {@linkcode isLeap} returns whether the given year is a leap year. * {@linkcode isUtcLeap} does the same but in UTC time. * - * ```ts + * ```ts no-assert * import { isLeap } from "@std/datetime/is-leap"; * * isLeap(new Date("1970-01-02")); // false @@ -82,7 +82,7 @@ * * {@linkcode parse} parses a date string using the specified format string. * - * ```ts + * ```ts no-assert * import { parse } from "@std/datetime/parse"; * * parse("20-01-2019", "dd-MM-yyyy"); // 2019-01-19T13:00:00.000Z @@ -97,7 +97,7 @@ * {@linkcode weekOfYear} returns the number of the week in the year in the local * timezone. * - * ```ts + * ```ts no-assert * import { weekOfYear } from "@std/datetime/week-of-year"; * * weekOfYear(new Date("2020-12-28T03:24:00")); // 53 diff --git a/datetime/parse.ts b/datetime/parse.ts index cf6d3d392..db133180a 100644 --- a/datetime/parse.ts +++ b/datetime/parse.ts @@ -37,12 +37,11 @@ import { DateTimeFormatter } from "./_date_time_formatter.ts"; * @example Basic usage * ```ts * import { parse } from "@std/datetime/parse"; + * import { assertEquals } from "@std/assert/assert-equals"; * - * parse("20-01-2019", "dd-MM-yyyy"); // 2019-01-19T13:00:00.000Z + * assertEquals(parse("01-03-2019 16:30", "MM-dd-yyyy HH:mm"), new Date(2019, 0, 3, 16, 30)); * - * parse("01-20-2019 04:34 PM", "MM-dd-yyyy hh:mm a"); // 2019-01-20T05:34:00.000Z - * - * parse("01-20-2019 16:34:23.123", "MM-dd-yyyy HH:mm:ss.SSS"); // 2019-01-20T05:34:23.123Z + * assertEquals(parse("01-03-2019 16:33:23.123", "MM-dd-yyyy HH:mm:ss.SSS"), new Date(2019, 0, 3, 16, 33, 23, 123)); * ``` */ export function parse(dateString: string, formatString: string): Date { diff --git a/datetime/week_of_year.ts b/datetime/week_of_year.ts index 0891b3df9..5f44c9819 100644 --- a/datetime/week_of_year.ts +++ b/datetime/week_of_year.ts @@ -24,10 +24,11 @@ const Day = { * @example Basic usage * ```ts * import { weekOfYear } from "@std/datetime/week-of-year"; + * import { assertEquals } from "@std/assert/assert-equals"; * - * weekOfYear(new Date("2020-12-28T03:24:00")); // 53 + * assertEquals(weekOfYear(new Date("2020-12-28T03:24:00")), 53); * - * weekOfYear(new Date("2020-07-10T03:24:00")); // 28 + * assertEquals(weekOfYear(new Date("2020-07-10T03:24:00")), 28); * ``` */ export function weekOfYear(date: Date): number { diff --git a/deno.json b/deno.json index 2f0e019e9..331f007a6 100644 --- a/deno.json +++ b/deno.json @@ -23,7 +23,7 @@ "@std/data-structures": "jsr:@std/data-structures@^0.225.0", "@std/datetime": "jsr:@std/datetime@^0.224.0", "@std/dotenv": "jsr:@std/dotenv@^0.224.0", - "@std/encoding": "jsr:@std/encoding@^0.224.3", + "@std/encoding": "jsr:@std/encoding@1.0.0-rc.1", "@std/expect": "jsr:@std/expect@^0.224.3", "@std/fmt": "jsr:@std/fmt@^0.225.2", "@std/front-matter": "jsr:@std/front-matter@^0.224.1", @@ -48,7 +48,7 @@ "@std/toml": "jsr:@std/toml@^0.224.0", "@std/ulid": "jsr:@std/ulid@^0.224.1", "@std/url": "jsr:@std/url@^0.224.0", - "@std/uuid": "jsr:@std/uuid@^0.224.3", + "@std/uuid": "jsr:@std/uuid@1.0.0-rc.1", "@std/webgpu": "jsr:@std/webgpu@^0.224.2", "@std/yaml": "jsr:@std/yaml@^0.224.1" }, diff --git a/expect/expect.ts b/expect/expect.ts index 1e8a30ffc..774bf50ac 100644 --- a/expect/expect.ts +++ b/expect/expect.ts @@ -114,8 +114,8 @@ const matchers: Record = { * The `expect` function is used to test a value. You will use `expect` along with a * "matcher" function to assert something about a value. * - * @example basic usage - * ```ts + * @example Usage + * ```ts no-assert * import { expect } from "@std/expect"; * * function bestLaCroixFlavor(): string { diff --git a/expect/fn.ts b/expect/fn.ts index abc12fa47..f57a04ed2 100644 --- a/expect/fn.ts +++ b/expect/fn.ts @@ -29,8 +29,8 @@ import { MOCK_SYMBOL, type MockCall } from "./_mock_util.ts"; * @param stubs - functions to be used as stubs for different calls. * @returns A mock function that keeps track of calls and returns values based on the provided stubs. * - * @example basic usage - * ```ts + * @example Usage + * ```ts no-assert * import { fn, expect } from "@std/expect"; * * Deno.test("example", () => { diff --git a/expect/mod.ts b/expect/mod.ts index dd786625e..337619507 100644 --- a/expect/mod.ts +++ b/expect/mod.ts @@ -72,7 +72,7 @@ * This module is largely inspired by * {@link https://github.com/allain/expect | x/expect} module by Allain Lalonde. * - * ```ts + * ```ts no-assert * import { expect } from "@std/expect"; * * const x = 6 * 7; diff --git a/fmt/bytes.ts b/fmt/bytes.ts index 42b4a8d9a..d24ae4127 100644 --- a/fmt/bytes.ts +++ b/fmt/bytes.ts @@ -59,32 +59,46 @@ export interface FormatOptions { * * This module is browser compatible. * - * @example Usage - * ```ts - * import { format } from "@std/fmt/bytes"; - * - * format(1337); - * //=> '1.34 kB' - * - * format(100); - * //=> '100 B' - * - * // Display with units of bits - * format(1337, { bits: true }); - * //=> '1.34 kbit' - * - * // Display file size differences - * format(42, { signed: true }); - * //=> '+42 B' - * - * // Localized output using German locale - * format(1337, { locale: "de" }); - * //=> '1,34 kB' - * ``` - * * @param num The bytes value to format * @param options The options for formatting * @returns The formatted string + * + * @example Basic usage + * ```ts + * import { format } from "@std/fmt/bytes"; + * import { assertEquals } from "@std/assert/assert-equals"; + * + * assertEquals(format(1337), "1.34 kB"); + * assertEquals(format(100), "100 B"); + * ``` + * + * @example Include bits representation + * + * ```ts + * import { format } from "@std/fmt/bytes"; + * import { assertEquals } from "@std/assert/assert-equals"; + * + * assertEquals(format(1337, { bits: true }), "1.34 kbit"); + * ``` + * + * @example Include sign + * + * ```ts + * import { format } from "@std/fmt/bytes"; + * import { assertEquals } from "@std/assert/assert-equals"; + * + * assertEquals(format(42, { signed: true }), "+42 B"); + * assertEquals(format(-42, { signed: true }), "-42 B"); + * ``` + * + * @example Change locale + * + * ```ts + * import { format } from "@std/fmt/bytes"; + * import { assertEquals } from "@std/assert/assert-equals"; + * + * assertEquals(format(1337, { locale: "de" }), "1,34 kB"); + * ``` */ export function format( num: number, diff --git a/fmt/colors.ts b/fmt/colors.ts index ea2c6dc66..ccb7a7b36 100644 --- a/fmt/colors.ts +++ b/fmt/colors.ts @@ -11,7 +11,7 @@ * This module supports `NO_COLOR` environmental variable disabling any coloring * if `NO_COLOR` is set. * - * ```ts + * ```ts no-assert * import { * bgBlue, * bgRgb24, @@ -81,7 +81,7 @@ let enabled = !noColor; * doesn't work. * * @example Usage - * ```ts + * ```ts no-assert * import { setColorEnabled } from "@std/fmt/colors"; * * // Disable text color @@ -105,7 +105,7 @@ export function setColorEnabled(value: boolean) { * Get whether text color change is enabled or disabled. * * @example Usage - * ```ts + * ```ts no-assert * import { getColorEnabled } from "@std/fmt/colors"; * * console.log(getColorEnabled()); // true if enabled, false if disabled @@ -144,7 +144,7 @@ function run(str: string, code: Code): string { * Reset the text modified. * * @example Usage - * ```ts + * ```ts no-assert * import { reset } from "@std/fmt/colors"; * * console.log(reset("Hello, world!")); @@ -161,7 +161,7 @@ export function reset(str: string): string { * Make the text bold. * * @example Usage - * ```ts + * ```ts no-assert * import { bold } from "@std/fmt/colors"; * * console.log(bold("Hello, world!")); @@ -178,7 +178,7 @@ export function bold(str: string): string { * The text emits only a small amount of light. * * @example Usage - * ```ts + * ```ts no-assert * import { dim } from "@std/fmt/colors"; * * console.log(dim("Hello, world!")); @@ -198,7 +198,7 @@ export function dim(str: string): string { * Make the text italic. * * @example Usage - * ```ts + * ```ts no-assert * import { italic } from "@std/fmt/colors"; * * console.log(italic("Hello, world!")); @@ -215,7 +215,7 @@ export function italic(str: string): string { * Make the text underline. * * @example Usage - * ```ts + * ```ts no-assert * import { underline } from "@std/fmt/colors"; * * console.log(underline("Hello, world!")); @@ -232,7 +232,7 @@ export function underline(str: string): string { * Invert background color and text color. * * @example Usage - * ```ts + * ```ts no-assert * import { inverse } from "@std/fmt/colors"; * * console.log(inverse("Hello, world!")); @@ -249,7 +249,7 @@ export function inverse(str: string): string { * Make the text hidden. * * @example Usage - * ```ts + * ```ts no-assert * import { hidden } from "@std/fmt/colors"; * * console.log(hidden("Hello, world!")); @@ -266,7 +266,7 @@ export function hidden(str: string): string { * Put horizontal line through the center of the text. * * @example Usage - * ```ts + * ```ts no-assert * import { strikethrough } from "@std/fmt/colors"; * * console.log(strikethrough("Hello, world!")); @@ -283,7 +283,7 @@ export function strikethrough(str: string): string { * Set text color to black. * * @example Usage - * ```ts + * ```ts no-assert * import { black } from "@std/fmt/colors"; * * console.log(black("Hello, world!")); @@ -300,7 +300,7 @@ export function black(str: string): string { * Set text color to red. * * @example Usage - * ```ts + * ```ts no-assert * import { red } from "@std/fmt/colors"; * * console.log(red("Hello, world!")); @@ -317,7 +317,7 @@ export function red(str: string): string { * Set text color to green. * * @example Usage - * ```ts + * ```ts no-assert * import { green } from "@std/fmt/colors"; * * console.log(green("Hello, world!")); @@ -334,7 +334,7 @@ export function green(str: string): string { * Set text color to yellow. * * @example Usage - * ```ts + * ```ts no-assert * import { yellow } from "@std/fmt/colors"; * * console.log(yellow("Hello, world!")); @@ -351,7 +351,7 @@ export function yellow(str: string): string { * Set text color to blue. * * @example Usage - * ```ts + * ```ts no-assert * import { blue } from "@std/fmt/colors"; * * console.log(blue("Hello, world!")); @@ -368,7 +368,7 @@ export function blue(str: string): string { * Set text color to magenta. * * @example Usage - * ```ts + * ```ts no-assert * import { magenta } from "@std/fmt/colors"; * * console.log(magenta("Hello, world!")); @@ -385,7 +385,7 @@ export function magenta(str: string): string { * Set text color to cyan. * * @example Usage - * ```ts + * ```ts no-assert * import { cyan } from "@std/fmt/colors"; * * console.log(cyan("Hello, world!")); @@ -402,7 +402,7 @@ export function cyan(str: string): string { * Set text color to white. * * @example Usage - * ```ts + * ```ts no-assert * import { white } from "@std/fmt/colors"; * * console.log(white("Hello, world!")); @@ -419,7 +419,7 @@ export function white(str: string): string { * Set text color to gray. * * @example Usage - * ```ts + * ```ts no-assert * import { gray } from "@std/fmt/colors"; * * console.log(gray("Hello, world!")); @@ -436,7 +436,7 @@ export function gray(str: string): string { * Set text color to bright black. * * @example Usage - * ```ts + * ```ts no-assert * import { brightBlack } from "@std/fmt/colors"; * * console.log(brightBlack("Hello, world!")); @@ -453,7 +453,7 @@ export function brightBlack(str: string): string { * Set text color to bright red. * * @example Usage - * ```ts + * ```ts no-assert * import { brightRed } from "@std/fmt/colors"; * * console.log(brightRed("Hello, world!")); @@ -470,7 +470,7 @@ export function brightRed(str: string): string { * Set text color to bright green. * * @example Usage - * ```ts + * ```ts no-assert * import { brightGreen } from "@std/fmt/colors"; * * console.log(brightGreen("Hello, world!")); @@ -487,7 +487,7 @@ export function brightGreen(str: string): string { * Set text color to bright yellow. * * @example Usage - * ```ts + * ```ts no-assert * import { brightYellow } from "@std/fmt/colors"; * * console.log(brightYellow("Hello, world!")); @@ -504,7 +504,7 @@ export function brightYellow(str: string): string { * Set text color to bright blue. * * @example Usage - * ```ts + * ```ts no-assert * import { brightBlue } from "@std/fmt/colors"; * * console.log(brightBlue("Hello, world!")); @@ -521,7 +521,7 @@ export function brightBlue(str: string): string { * Set text color to bright magenta. * * @example Usage - * ```ts + * ```ts no-assert * import { brightMagenta } from "@std/fmt/colors"; * * console.log(brightMagenta("Hello, world!")); @@ -538,7 +538,7 @@ export function brightMagenta(str: string): string { * Set text color to bright cyan. * * @example Usage - * ```ts + * ```ts no-assert * import { brightCyan } from "@std/fmt/colors"; * * console.log(brightCyan("Hello, world!")); @@ -555,7 +555,7 @@ export function brightCyan(str: string): string { * Set text color to bright white. * * @example Usage - * ```ts + * ```ts no-assert * import { brightWhite } from "@std/fmt/colors"; * * console.log(brightWhite("Hello, world!")); @@ -572,7 +572,7 @@ export function brightWhite(str: string): string { * Set background color to black. * * @example Usage - * ```ts + * ```ts no-assert * import { bgBlack } from "@std/fmt/colors"; * * console.log(bgBlack("Hello, world!")); @@ -589,7 +589,7 @@ export function bgBlack(str: string): string { * Set background color to red. * * @example Usage - * ```ts + * ```ts no-assert * import { bgRed } from "@std/fmt/colors"; * * console.log(bgRed("Hello, world!")); @@ -606,7 +606,7 @@ export function bgRed(str: string): string { * Set background color to green. * * @example Usage - * ```ts + * ```ts no-assert * import { bgGreen } from "@std/fmt/colors"; * * console.log(bgGreen("Hello, world!")); @@ -623,7 +623,7 @@ export function bgGreen(str: string): string { * Set background color to yellow. * * @example Usage - * ```ts + * ```ts no-assert * import { bgYellow } from "@std/fmt/colors"; * * console.log(bgYellow("Hello, world!")); @@ -640,7 +640,7 @@ export function bgYellow(str: string): string { * Set background color to blue. * * @example Usage - * ```ts + * ```ts no-assert * import { bgBlue } from "@std/fmt/colors"; * * console.log(bgBlue("Hello, world!")); @@ -657,7 +657,7 @@ export function bgBlue(str: string): string { * Set background color to magenta. * * @example Usage - * ```ts + * ```ts no-assert * import { bgMagenta } from "@std/fmt/colors"; * * console.log(bgMagenta("Hello, world!")); @@ -674,7 +674,7 @@ export function bgMagenta(str: string): string { * Set background color to cyan. * * @example Usage - * ```ts + * ```ts no-assert * import { bgCyan } from "@std/fmt/colors"; * * console.log(bgCyan("Hello, world!")); @@ -691,7 +691,7 @@ export function bgCyan(str: string): string { * Set background color to white. * * @example Usage - * ```ts + * ```ts no-assert * import { bgWhite } from "@std/fmt/colors"; * * console.log(bgWhite("Hello, world!")); @@ -708,7 +708,7 @@ export function bgWhite(str: string): string { * Set background color to bright black. * * @example Usage - * ```ts + * ```ts no-assert * import { bgBrightBlack } from "@std/fmt/colors"; * * console.log(bgBrightBlack("Hello, world!")); @@ -725,7 +725,7 @@ export function bgBrightBlack(str: string): string { * Set background color to bright red. * * @example Usage - * ```ts + * ```ts no-assert * import { bgBrightRed } from "@std/fmt/colors"; * * console.log(bgBrightRed("Hello, world!")); @@ -742,7 +742,7 @@ export function bgBrightRed(str: string): string { * Set background color to bright green. * * @example Usage - * ```ts + * ```ts no-assert * import { bgBrightGreen } from "@std/fmt/colors"; * * console.log(bgBrightGreen("Hello, world!")); @@ -759,7 +759,7 @@ export function bgBrightGreen(str: string): string { * Set background color to bright yellow. * * @example Usage - * ```ts + * ```ts no-assert * import { bgBrightYellow } from "@std/fmt/colors"; * * console.log(bgBrightYellow("Hello, world!")); @@ -776,7 +776,7 @@ export function bgBrightYellow(str: string): string { * Set background color to bright blue. * * @example Usage - * ```ts + * ```ts no-assert * import { bgBrightBlue } from "@std/fmt/colors"; * * console.log(bgBrightBlue("Hello, world!")); @@ -793,7 +793,7 @@ export function bgBrightBlue(str: string): string { * Set background color to bright magenta. * * @example Usage - * ```ts + * ```ts no-assert * import { bgBrightMagenta } from "@std/fmt/colors"; * * console.log(bgBrightMagenta("Hello, world!")); @@ -810,7 +810,7 @@ export function bgBrightMagenta(str: string): string { * Set background color to bright cyan. * * @example Usage - * ```ts + * ```ts no-assert * import { bgBrightCyan } from "@std/fmt/colors"; * * console.log(bgBrightCyan("Hello, world!")); @@ -827,7 +827,7 @@ export function bgBrightCyan(str: string): string { * Set background color to bright white. * * @example Usage - * ```ts + * ```ts no-assert * import { bgBrightWhite } from "@std/fmt/colors"; * * console.log(bgBrightWhite("Hello, world!")); @@ -857,7 +857,7 @@ function clampAndTruncate(n: number, max = 255, min = 0): number { * https://en.wikipedia.org/wiki/ANSI_escape_code#8-bit * * @example Usage - * ```ts + * ```ts no-assert * import { rgb8 } from "@std/fmt/colors"; * * console.log(rgb8("Hello, world!", 42)); @@ -876,7 +876,7 @@ export function rgb8(str: string, color: number): string { * https://en.wikipedia.org/wiki/ANSI_escape_code#8-bit * * @example Usage - * ```ts + * ```ts no-assert * import { bgRgb8 } from "@std/fmt/colors"; * * console.log(bgRgb8("Hello, world!", 42)); @@ -896,7 +896,7 @@ export function bgRgb8(str: string, color: number): string { * an `Rgb`. * * @example To produce the color magenta: - * ```ts + * ```ts no-assert * import { rgb24 } from "@std/fmt/colors"; * * rgb24("foo", 0xff00ff); @@ -937,7 +937,7 @@ export function rgb24(str: string, color: number | Rgb): string { * an `Rgb`. * * @example To produce the color magenta: - * ```ts + * ```ts no-assert * import { bgRgb24 } from "@std/fmt/colors"; * * bgRgb24("foo", 0xff00ff); @@ -985,7 +985,7 @@ const ANSI_PATTERN = new RegExp( * Remove ANSI escape codes from the string. * * @example Usage - * ```ts + * ```ts no-assert * import { stripColor, red } from "@std/fmt/colors"; * * console.log(stripColor(red("Hello, world!"))); @@ -1004,7 +1004,7 @@ export function stripColor(string: string): string { * Remove ANSI escape codes from the string. * * @example Usage - * ```ts + * ```ts no-assert * import { stripAnsiCode, red } from "@std/fmt/colors"; * * console.log(stripAnsiCode(red("Hello, world!"))); diff --git a/fmt/duration.ts b/fmt/duration.ts index b37e0928b..64a582e3e 100644 --- a/fmt/duration.ts +++ b/fmt/duration.ts @@ -6,18 +6,15 @@ * * ```ts * import { format } from "@std/fmt/duration"; + * import { assertEquals } from "@std/assert/assert-equals"; * - * // "00:00:01:39:674:000:000" - * format(99674, { style: "digital" }); + * assertEquals(format(99674, { style: "digital" }), "00:00:01:39:674:000:000"); * - * // "0d 0h 1m 39s 674ms 0µs 0ns" - * format(99674); + * assertEquals(format(99674), "0d 0h 1m 39s 674ms 0µs 0ns"); * - * // "1m 39s 674ms" - * format(99674, { ignoreZero: true }); + * assertEquals(format(99674, { ignoreZero: true }), "1m 39s 674ms"); * - * // "1 minutes, 39 seconds, 674 milliseconds" - * format(99674, { style: "full", ignoreZero: true }); + * assertEquals(format(99674, { style: "full", ignoreZero: true }), "1 minutes, 39 seconds, 674 milliseconds"); * ``` * @module */ @@ -98,11 +95,15 @@ export interface PrettyDurationOptions { * @example Usage * ```ts * import { format } from "@std/fmt/duration"; + * import { assertEquals } from "@std/assert/assert-equals"; * - * format(99674, { style: "digital" }); // "00:00:01:39:674:000:000" - * format(99674); // "0d 0h 1m 39s 674ms 0µs 0ns" - * format(99674, { ignoreZero: true }); // "1m 39s 674ms" - * format(99674, { style: "full", ignoreZero: true }); // "1 minutes, 39 seconds, 674 milliseconds" + * assertEquals(format(99674, { style: "digital" }), "00:00:01:39:674:000:000"); + * + * assertEquals(format(99674), "0d 0h 1m 39s 674ms 0µs 0ns"); + * + * assertEquals(format(99674, { ignoreZero: true }), "1m 39s 674ms"); + * + * assertEquals(format(99674, { style: "full", ignoreZero: true }), "1 minutes, 39 seconds, 674 milliseconds"); * ``` * * @param ms The milliseconds value to format diff --git a/fmt/printf.ts b/fmt/printf.ts index ff2c4d9d2..2761f9df3 100644 --- a/fmt/printf.ts +++ b/fmt/printf.ts @@ -934,11 +934,14 @@ class Printf { * @example Usage * ```ts * import { sprintf } from "@std/fmt/printf"; - * import { assertEquals } from "@std/assert" + * import { assertEquals } from "@std/assert"; * * assertEquals(sprintf("%d", 9), "9"); + * * assertEquals(sprintf("%o", 9), "11"); + * * assertEquals(sprintf("%f", 4), "4.000000"); + * * assertEquals(sprintf("%.3f", 0.9999), "1.000"); * ``` * @@ -958,13 +961,16 @@ export function sprintf(format: string, ...args: unknown[]): string { * See the module documentation for the available format strings. * * @example Usage - * ```ts + * ```ts no-assert * import { printf } from "@std/fmt/printf"; * - * printf("%d", 9); // prints "9" - * printf("%o", 9); // prints "11" - * printf("%f", 4); // prints "4.000000" - * printf("%.3f", 0.9999); // prints "1.000" + * printf("%d", 9); // Prints "9" + * + * printf("%o", 9); // Prints "11" + * + * printf("%f", 4); // Prints "4.000000" + * + * printf("%.3f", 0.9999); // Prints "1.000" * ``` * * @param format The format string to use diff --git a/html/entities.ts b/html/entities.ts index 77d17c659..bc28b6e6f 100644 --- a/html/entities.ts +++ b/html/entities.ts @@ -28,12 +28,13 @@ const rawRe = new RegExp(`[${[...rawToEntity.keys()].join("")}]`, "g"); * @example Usage * ```ts * import { escape } from "@std/html/entities"; + * import { assertEquals } from "@std/assert/assert-equals"; * - * escape("<>'&AA"); // "<>'&AA" + * assertEquals(escape("<>'&AA"), "<>'&AA"); * * // Characters that don't need to be escaped will be left alone, * // even if named HTML entities exist for them. - * escape("þð"); // "þð" + * assertEquals(escape("þð"), "þð"); * ``` * * @param str The string to escape. @@ -60,18 +61,27 @@ const entityListRegexCache = new WeakMap(); /** * Unescapes HTML entities in text. * - * @example Usage + * Default options only handle `&<>'"` and numeric entities. + * + * @example Basic usage * ```ts * import { unescape } from "@std/html/entities"; + * import { assertEquals } from "@std/assert/assert-equals"; * - * // Default options (only handles &<>'" and numeric entities) - * unescape("<>'&AA"); // "<>'&AA" - * unescape("þð"); // "þð" + * assertEquals(unescape("<>'&AA"), "<>'&AA"); + * assertEquals(unescape("þð"), "þð"); + * ``` * - * // Using the full named entity list from the HTML spec (~47K un-minified) + * @example Using a custom entity list + * + * This uses the full named entity list from the HTML spec (~47K un-minified) + * + * ```ts + * import { unescape } from "@std/html/entities"; * import entityList from "@std/html/named-entity-list.json" with { type: "json" }; + * import { assertEquals } from "@std/assert/assert-equals"; * - * unescape("þð", { entityList }); // "þð" + * assertEquals(unescape("<>'&AA", { entityList }), "<>'&AA"); * ``` * * @param str The string to unescape. diff --git a/html/mod.ts b/html/mod.ts index f6974ff36..34f49375b 100644 --- a/html/mod.ts +++ b/html/mod.ts @@ -5,13 +5,11 @@ * Functions for HTML tasks such as escaping or unescaping HTML entities. * * ```ts - * import { escape } from "@std/html/entities"; + * import { unescape } from "@std/html/entities"; + * import { assertEquals } from "@std/assert/assert-equals"; * - * escape("<>'&AA"); // "<>'&AA" - * - * // Characters that don't need to be escaped will be left alone, - * // even if named HTML entities exist for them. - * escape("þð"); // "þð" + * assertEquals(unescape("<>'&AA"), "<>'&AA"); + * assertEquals(unescape("þð"), "þð"); * ``` * * @module diff --git a/http/cookie.ts b/http/cookie.ts index 8c9cdded4..ad2007433 100644 --- a/http/cookie.ts +++ b/http/cookie.ts @@ -197,12 +197,13 @@ function validateDomain(domain: string) { * @example Usage * ```ts * import { getCookies } from "@std/http/cookie"; + * import { assertEquals } from "@std/assert/assert-equals"; * * const headers = new Headers(); * headers.set("Cookie", "full=of; tasty=chocolate"); * * const cookies = getCookies(headers); - * console.log(cookies); // { full: "of", tasty: "chocolate" } + * assertEquals(cookies, { full: "of", tasty: "chocolate" }); * ``` * * @param headers The headers instance to get cookies from @@ -229,17 +230,16 @@ export function getCookies(headers: Headers): Record { * * @example Usage * ```ts - * import { - * Cookie, - * setCookie, - * } from "@std/http/cookie"; + * import { Cookie, setCookie } from "@std/http/cookie"; + * import { assertEquals } from "@std/assert/assert-equals"; * * const headers = new Headers(); * const cookie: Cookie = { name: "Space", value: "Cat" }; * setCookie(headers, cookie); * * const cookieHeader = headers.get("set-cookie"); - * console.log(cookieHeader); // Space=Cat + * + * assertEquals(cookieHeader, "Space=Cat"); * ``` * * @param headers The headers instance to set the cookie to @@ -263,12 +263,14 @@ export function setCookie(headers: Headers, cookie: Cookie) { * @example Usage * ```ts * import { deleteCookie } from "@std/http/cookie"; + * import { assertEquals } from "@std/assert/assert-equals"; * * const headers = new Headers(); * deleteCookie(headers, "deno"); * * const cookieHeader = headers.get("set-cookie"); - * console.log(cookieHeader); // deno=; Expires=Thus, 01 Jan 1970 00:00:00 GMT + * + * assertEquals(cookieHeader, "deno=; Expires=Thu, 01 Jan 1970 00:00:00 GMT"); * ``` * * @param headers The headers instance to delete the cookie from @@ -379,6 +381,7 @@ function parseSetCookie(value: string): Cookie | null { * @example Usage * ```ts * import { getSetCookies } from "@std/http/cookie"; + * import { assertEquals } from "@std/assert/assert-equals"; * * const headers = new Headers([ * ["Set-Cookie", "lulu=meow; Secure; Max-Age=3600"], @@ -386,7 +389,13 @@ function parseSetCookie(value: string): Cookie | null { * ]); * * const cookies = getSetCookies(headers); - * console.log(cookies); // [{ name: "lulu", value: "meow", secure: true, maxAge: 3600 }, { name: "booya", value: "kahsa", httpOnly: true, path: "/ }] + * + * assertEquals(cookies[0], { + * name: "lulu", + * value: "meow", + * secure: true, + * maxAge: 3600 + * }); * ``` * * @param headers The headers instance to get set-cookies from diff --git a/http/etag.ts b/http/etag.ts index b34ca8fb5..9f2a6ef3f 100644 --- a/http/etag.ts +++ b/http/etag.ts @@ -98,7 +98,7 @@ async function calcFileInfo( * @example Usage * ```ts * import { calculate } from "@std/http/etag"; - * import { assert } from "@std/assert/assert" + * import { assert } from "@std/assert/assert"; * * const body = "hello deno!"; * diff --git a/http/negotiation.ts b/http/negotiation.ts index c1633522f..29585603f 100644 --- a/http/negotiation.ts +++ b/http/negotiation.ts @@ -27,22 +27,22 @@ export type Request = { * @example Usage * ```ts * import { accepts } from "@std/http/negotiation"; + * import { assertEquals } from "@std/assert/assert-equals"; * - * const req = new Request("https://example.com/", { + * const request = new Request("https://example.com/", { * headers: { - * "accept": + * accept: * "text/html, application/xhtml+xml, application/xml;q=0.9, image/webp, *\/*;q=0.8", * }, * }); * - * console.log(accepts(req)); - * // [ - * // "text/html", - * // "application/xhtml+xml", - * // "image/webp", - * // "application/xml", - * // "*\/*", - * // ] + * assertEquals(accepts(request), [ + * "text/html", + * "application/xhtml+xml", + * "image/webp", + * "application/xml", + * "*\/*", + * ]); * ``` * * @param request The request to get the acceptable media types for. @@ -56,15 +56,16 @@ export function accepts(request: Request): string[]; * @example Usage * ```ts * import { accepts } from "@std/http/negotiation"; + * import { assertEquals } from "@std/assert/assert-equals"; * - * const req = new Request("https://example.com/", { + * const request = new Request("https://example.com/", { * headers: { - * "accept": + * accept: * "text/html, application/xhtml+xml, application/xml;q=0.9, image/webp, *\/*;q=0.8", * }, * }); * - * accepts(req, "text/html", "image/webp"); // "text/html"; + * assertEquals(accepts(request, "text/html", "image/webp"), "text/html"); * ``` * * @param request The request to get the acceptable media types for. @@ -95,12 +96,13 @@ export function accepts( * @example Usage * ```ts * import { acceptsEncodings } from "@std/http/negotiation"; + * import { assertEquals } from "@std/assert/assert-equals"; * - * const req = new Request("https://example.com/", { + * const request = new Request("https://example.com/", { * headers: { "accept-encoding": "deflate, gzip;q=1.0, *;q=0.5" }, * }); * - * acceptsEncodings(req); // ["deflate", "gzip", "*"] + * assertEquals(acceptsEncodings(request), ["deflate", "gzip", "*"]); * ``` * * @param request The request to get the acceptable content encodings for. @@ -119,12 +121,13 @@ export function acceptsEncodings(request: Request): string[]; * @example Usage * ```ts * import { acceptsEncodings } from "@std/http/negotiation"; + * import { assertEquals } from "@std/assert/assert-equals"; * - * const req = new Request("https://example.com/", { + * const request = new Request("https://example.com/", { * headers: { "accept-encoding": "deflate, gzip;q=1.0, *;q=0.5" }, * }); * - * acceptsEncodings(req, "gzip", "identity"); // "gzip" + * assertEquals(acceptsEncodings(request, "gzip", "identity"), "gzip"); * ``` * * @param request The request to get the acceptable content encodings for. @@ -157,14 +160,15 @@ export function acceptsEncodings( * @example Usage * ```ts * import { acceptsLanguages } from "@std/http/negotiation"; + * import { assertEquals } from "@std/assert/assert-equals"; * - * const req = new Request("https://example.com/", { + * const request = new Request("https://example.com/", { * headers: { * "accept-language": "fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5", * }, * }); * - * acceptsLanguages(req); // ["fr-CH", "fr", "en", "de", "*"] + * assertEquals(acceptsLanguages(request), ["fr-CH", "fr", "en", "de", "*"]); * ``` * * @param request The request to get the acceptable languages for. @@ -178,14 +182,15 @@ export function acceptsLanguages(request: Request): string[]; * @example Usage * ```ts * import { acceptsLanguages } from "@std/http/negotiation"; + * import { assertEquals } from "@std/assert/assert-equals"; * - * const req = new Request("https://example.com/", { + * const request = new Request("https://example.com/", { * headers: { * "accept-language": "fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5", * }, * }); * - * acceptsLanguages(req, "en-gb", "en-us", "en"); // "en" + * assertEquals(acceptsLanguages(request, "en-gb", "en-us", "en"), "en"); * ``` * * @param request The request to get the acceptable language for. diff --git a/http/server_sent_event_stream.ts b/http/server_sent_event_stream.ts index bbc940693..0a43efcf2 100644 --- a/http/server_sent_event_stream.ts +++ b/http/server_sent_event_stream.ts @@ -62,7 +62,7 @@ function stringify(message: ServerSentEventMessage): Uint8Array { * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events} * * @example Usage - * ```ts + * ```ts no-assert * import { * type ServerSentEventMessage, * ServerSentEventStream, diff --git a/http/status.ts b/http/status.ts index b38c9ca65..64708d986 100644 --- a/http/status.ts +++ b/http/status.ts @@ -319,8 +319,9 @@ export type ErrorStatus = ClientErrorStatus | ServerErrorStatus; * @example Usage * ```ts * import { isStatus } from "@std/http/status"; + * import { assert } from "@std/assert/assert"; * - * console.log(isStatus(404)); // Returns true + * assert(isStatus(404)); * ``` * * @param status The status to assert against. @@ -336,8 +337,9 @@ export function isStatus(status: number): status is StatusCode { * @example Usage * ```ts * import { isInformationalStatus } from "@std/http/status"; + * import { assert } from "@std/assert/assert"; * - * console.log(isInformationalStatus(404)); // Returns false + * assert(isInformationalStatus(100)); * ``` * * @param status The status to assert against. @@ -355,8 +357,9 @@ export function isInformationalStatus( * @example Usage * ```ts * import { isSuccessfulStatus } from "@std/http/status"; + * import { assert } from "@std/assert/assert"; * - * console.log(isSuccessfulStatus(404)); // Returns false + * assert(isSuccessfulStatus(200)); * ``` * * @param status The status to assert against. @@ -374,8 +377,9 @@ export function isSuccessfulStatus( * @example Usage * ```ts * import { isRedirectStatus } from "@std/http/status"; + * import { assert } from "@std/assert/assert"; * - * console.log(isRedirectStatus(302)); // Returns true + * assert(isRedirectStatus(302)); * ``` * * @param status The status to assert against. @@ -391,8 +395,9 @@ export function isRedirectStatus(status: number): status is RedirectStatus { * @example Usage * ```ts * import { isClientErrorStatus } from "@std/http/status"; + * import { assert } from "@std/assert/assert"; * - * console.log(isClientErrorStatus(404)); // Returns true + * assert(isClientErrorStatus(404)); * ``` * * @param status The status to assert against. @@ -410,8 +415,9 @@ export function isClientErrorStatus( * @example Usage * ```ts * import { isServerErrorStatus } from "@std/http/status"; + * import { assert } from "@std/assert/assert"; * - * console.log(isServerErrorStatus(502)); // Returns true + * assert(isServerErrorStatus(502)); * ``` * * @param status The status to assert against. @@ -429,8 +435,9 @@ export function isServerErrorStatus( * @example Usage * ```ts * import { isErrorStatus } from "@std/http/status"; + * import { assert } from "@std/assert/assert"; * - * console.log(isErrorStatus(502)); // Returns true + * assert(isErrorStatus(502)); * ``` * * @param status The status to assert against. diff --git a/http/unstable_signed_cookie.ts b/http/unstable_signed_cookie.ts index 6d0674485..de75abfe8 100644 --- a/http/unstable_signed_cookie.ts +++ b/http/unstable_signed_cookie.ts @@ -16,7 +16,7 @@ function splitByLast(value: string, separator: string): [string, string] { * key. * * @example Usage - * ```ts + * ```ts no-eval no-assert * import { signCookie } from "@std/http/unstable-signed-cookie"; * import { setCookie } from "@std/http/cookie"; * @@ -54,7 +54,7 @@ export async function signCookie( * Returns a promise of a boolean indicating whether the signed cookie is valid. * * @example Usage - * ```ts + * ```ts no-eval no-assert * import { verifyCookie } from "@std/http/unstable-signed-cookie"; * import { getCookies } from "@std/http/cookie"; * @@ -95,7 +95,7 @@ export async function verifyCookie( * Important: always verify the cookie using {@linkcode verifyCookie} first. * * @example Usage - * ```ts + * ```ts no-eval no-assert * import { verifyCookie, parseSignedCookie } from "@std/http/unstable-signed-cookie"; * import { getCookies } from "@std/http/cookie"; * diff --git a/internal/build_message.ts b/internal/build_message.ts index d7bf29bce..72f95817a 100644 --- a/internal/build_message.ts +++ b/internal/build_message.ts @@ -88,7 +88,7 @@ export interface BuildMessageOptions { * @returns An array of strings representing the built message. * * @example Usage - * ```ts + * ```ts no-assert * import { diffStr, buildMessage } from "@std/internal"; * * const diffResult = diffStr("Hello, world!", "Hello, world"); diff --git a/internal/styles.ts b/internal/styles.ts index 73e294126..74aec57e0 100644 --- a/internal/styles.ts +++ b/internal/styles.ts @@ -43,7 +43,7 @@ function run(str: string, code: Code): string { * @returns Bold text for printing * * @example Usage - * ```ts + * ```ts no-assert * import { bold } from "@std/internal/styles"; * * console.log(bold("Hello, world!")); // Prints "Hello, world!" in bold @@ -63,7 +63,7 @@ export function bold(str: string): string { * @returns Red text for printing * * @example Usage - * ```ts + * ```ts no-assert * import { red } from "@std/internal/styles"; * * console.log(red("Hello, world!")); // Prints "Hello, world!" in red @@ -83,7 +83,7 @@ export function red(str: string): string { * @returns Green text for print * * @example Usage - * ```ts + * ```ts no-assert * import { green } from "@std/internal/styles"; * * console.log(green("Hello, world!")); // Prints "Hello, world!" in green @@ -103,7 +103,7 @@ export function green(str: string): string { * @returns Yellow text for print * * @example Usage - * ```ts + * ```ts no-assert * import { yellow } from "@std/internal/styles"; * * console.log(yellow("Hello, world!")); // Prints "Hello, world!" in yellow @@ -121,7 +121,7 @@ export function yellow(str: string): string { * @returns White text for print * * @example Usage - * ```ts + * ```ts no-assert * import { white } from "@std/internal/styles"; * * console.log(white("Hello, world!")); // Prints "Hello, world!" in white @@ -139,7 +139,7 @@ export function white(str: string): string { * @returns Gray text for print * * @example Usage - * ```ts + * ```ts no-assert * import { gray } from "@std/internal/styles"; * * console.log(gray("Hello, world!")); // Prints "Hello, world!" in gray @@ -157,7 +157,7 @@ export function gray(str: string): string { * @returns Bright-black text for print * * @example Usage - * ```ts + * ```ts no-assert * import { brightBlack } from "@std/internal/styles"; * * console.log(brightBlack("Hello, world!")); // Prints "Hello, world!" in bright-black @@ -175,7 +175,7 @@ export function brightBlack(str: string): string { * @returns Red background text for print * * @example Usage - * ```ts + * ```ts no-assert * import { bgRed } from "@std/internal/styles"; * * console.log(bgRed("Hello, world!")); // Prints "Hello, world!" with red background @@ -193,7 +193,7 @@ export function bgRed(str: string): string { * @returns Green background text for print * * @example Usage - * ```ts + * ```ts no-assert * import { bgGreen } from "@std/internal/styles"; * * console.log(bgGreen("Hello, world!")); // Prints "Hello, world!" with green background @@ -220,7 +220,7 @@ const ANSI_PATTERN = new RegExp( * @returns Text without ANSI escape codes * * @example Usage - * ```ts + * ```ts no-assert * import { red, stripAnsiCode } from "@std/internal/styles"; * * console.log(stripAnsiCode(red("Hello, world!"))); // Prints "Hello, world!" diff --git a/jsonc/mod.ts b/jsonc/mod.ts index 7b42dd119..725f8e2bd 100644 --- a/jsonc/mod.ts +++ b/jsonc/mod.ts @@ -10,12 +10,16 @@ * * ```ts * import { parse } from "@std/jsonc"; + * import { assertEquals } from "@std/assert/assert-equals"; * - * parse('{"foo": "bar", } // comment'); // { foo: "bar" } - * parse('{"foo": "bar", } /* comment *\/'); // { foo: "bar" } - * parse('{"foo": "bar" } // comment', { - * allowTrailingComma: false, - * }); // { foo: "bar" } + * assertEquals(parse('{"foo": "bar", } // comment'), { foo: "bar" }); + * + * assertEquals(parse('{"foo": "bar", } /* comment *\/'), { foo: "bar" }); + * + * assertEquals( + * parse('{"foo": "bar" } // comment', { allowTrailingComma: false }), + * { foo: "bar" } + * ); * ``` * * @module diff --git a/jsonc/parse.ts b/jsonc/parse.ts index 3202b0bfb..6d8fd9e2a 100644 --- a/jsonc/parse.ts +++ b/jsonc/parse.ts @@ -32,12 +32,12 @@ export interface ParseOptions { * @example Usage * ```ts * import { parse } from "@std/jsonc"; + * import { assertEquals } from "@std/assert"; * - * parse('{"foo": "bar", } // comment'); // { foo: "bar" } - * parse('{"foo": "bar", } /* comment *\/'); // { foo: "bar" } - * parse('{"foo": "bar" } // comment', { - * allowTrailingComma: false, - * }); // { foo: "bar" } + * assertEquals(parse('{"foo": "bar"}'), { foo: "bar" }); + * assertEquals(parse('{"foo": "bar", }'), { foo: "bar" }); + * assertEquals(parse('{"foo": "bar", } /* comment *\/'), { foo: "bar" }); + * assertEquals(parse('{"foo": "bar" } // comment', { allowTrailingComma: false }), { foo: "bar" }); * ``` * * @param text A valid JSONC string. diff --git a/path/mod.ts b/path/mod.ts index e89640635..eebb20084 100644 --- a/path/mod.ts +++ b/path/mod.ts @@ -13,20 +13,22 @@ * To use functions for a specific path style regardless of the current OS * import the modules from the platform sub directory instead. * - * Example, for `posix`: + * Example, for POSIX: * * ```ts * import { fromFileUrl } from "@std/path/posix/from-file-url"; - * const p = fromFileUrl("file:///home/foo"); - * console.log(p); // "/home/foo" + * import { assertEquals } from "@std/assert/assert-equals"; + * + * assertEquals(fromFileUrl("file:///home/foo"), "/home/foo"); * ``` * - * or, for `windows`: + * Or, for Windows: * * ```ts * import { fromFileUrl } from "@std/path/windows/from-file-url"; - * const p = fromFileUrl("file:///home/foo"); - * console.log(p); // "\\home\\foo" + * import { assertEquals } from "@std/assert/assert-equals"; + * + * assertEquals(fromFileUrl("file:///home/foo"), "\\home\\foo"); * ``` * * This module is browser compatible. diff --git a/path/posix/glob_to_regexp.ts b/path/posix/glob_to_regexp.ts index e8c124bb8..086cc9af6 100644 --- a/path/posix/glob_to_regexp.ts +++ b/path/posix/glob_to_regexp.ts @@ -76,9 +76,10 @@ const constants: GlobConstants = { * * @example Usage * ```ts - * import { globToRegExp } from "@std/path/glob-to-regexp"; + * import { globToRegExp } from "@std/path/posix/glob-to-regexp"; + * import { assertEquals } from "@std/assert/assert-equals"; * - * globToRegExp("*.js"); // /^[^/]*\.js\/*$/; + * assertEquals(globToRegExp("*.js"), /^[^/]*\.js\/*$/); * ``` * * @param glob Glob string to convert. diff --git a/path/posix/mod.ts b/path/posix/mod.ts index 3c5a27adb..e66589d37 100644 --- a/path/posix/mod.ts +++ b/path/posix/mod.ts @@ -9,12 +9,12 @@ * Codes in the examples uses POSIX path but it automatically use Windows path * on Windows. Use methods under `posix` or `win32` object instead to handle non * platform specific path like: + * * ```ts - * import { posix, win32 } from "@std/path"; - * const p1 = posix.fromFileUrl("file:///home/foo"); - * const p2 = win32.fromFileUrl("file:///home/foo"); - * console.log(p1); // "/home/foo" - * console.log(p2); // "\\home\\foo" + * import { fromFileUrl } from "@std/path/posix"; + * import { assertEquals } from "@std/assert/assert-equals"; + * + * assertEquals(fromFileUrl("file:///home/foo"), "/home/foo"); * ``` * * This module is browser compatible. diff --git a/path/windows/glob_to_regexp.ts b/path/windows/glob_to_regexp.ts index 55f00679e..86476bf51 100644 --- a/path/windows/glob_to_regexp.ts +++ b/path/windows/glob_to_regexp.ts @@ -75,8 +75,9 @@ const constants: GlobConstants = { * @example Usage * ```ts * import { globToRegExp } from "@std/path/windows/glob-to-regexp"; + * import { assertEquals } from "@std/assert/assert-equals"; * - * globToRegExp("*.js"); // /^[^\\]*\.js\/*$/; + * assertEquals(globToRegExp("*.js"), /^[^\\/]*\.js(?:\\|\/)*$/); * ``` * * @param glob Glob string to convert. diff --git a/path/windows/mod.ts b/path/windows/mod.ts index 3c5a27adb..ff6df0060 100644 --- a/path/windows/mod.ts +++ b/path/windows/mod.ts @@ -9,12 +9,12 @@ * Codes in the examples uses POSIX path but it automatically use Windows path * on Windows. Use methods under `posix` or `win32` object instead to handle non * platform specific path like: + * * ```ts - * import { posix, win32 } from "@std/path"; - * const p1 = posix.fromFileUrl("file:///home/foo"); - * const p2 = win32.fromFileUrl("file:///home/foo"); - * console.log(p1); // "/home/foo" - * console.log(p2); // "\\home\\foo" + * import { fromFileUrl } from "@std/path/windows"; + * import { assertEquals } from "@std/assert/assert-equals"; + * + * assertEquals(fromFileUrl("file:///home/foo"), "\\home\\foo"); * ``` * * This module is browser compatible. diff --git a/semver/mod.ts b/semver/mod.ts index bf78afe16..778e2af66 100644 --- a/semver/mod.ts +++ b/semver/mod.ts @@ -15,16 +15,26 @@ * lessThan, * format * } from "@std/semver"; + * import { assertEquals } from "@std/assert/assert-equals"; * * const semver = parse("1.2.3"); + * assertEquals(semver, { + * major: 1, + * minor: 2, + * patch: 3, + * prerelease: [], + * build: [] + * }); + * + * assertEquals(format(semver), "1.2.3"); + * * const range = parseRange("1.x || >=2.5.0 || 5.0.0 - 7.2.3"); * * const s0 = parse("1.2.3"); * const s1 = parse("9.8.7"); - * greaterThan(s0, s1); // false - * lessThan(s0, s1); // true * - * format(semver) // "1.2.3" + * assertEquals(greaterThan(s0, s1), false); + * assertEquals(lessThan(s0, s1), true); * ``` * * ## Versions diff --git a/streams/buffer.ts b/streams/buffer.ts index 75d410ec9..803b292af 100644 --- a/streams/buffer.ts +++ b/streams/buffer.ts @@ -93,7 +93,7 @@ export class Buffer { * @returns A `ReadableStream` of the buffer. * * @example Read the content out of the buffer to stdout - * ```ts + * ```ts no-assert * import { Buffer } from "@std/streams/buffer"; * * const buf = new Buffer(); @@ -117,7 +117,7 @@ export class Buffer { * @returns A `WritableStream` of the buffer. * * @example Write the data from stdin to the buffer - * ```ts + * ```ts no-assert * import { Buffer } from "@std/streams/buffer"; * * const buf = new Buffer(); @@ -134,14 +134,14 @@ export class Buffer { * @param ab An optional buffer to use as the initial buffer. * * @example No initial buffer provided - * ```ts + * ```ts no-assert * import { Buffer } from "@std/streams/buffer"; * * const buf = new Buffer(); * ``` * * @example With a pre-allocated buffer - * ```ts + * ```ts no-assert * import { Buffer } from "@std/streams/buffer"; * * const arrayBuffer = new ArrayBuffer(8); @@ -149,7 +149,7 @@ export class Buffer { * ``` * * @example From Uint8Array - * ```ts + * ```ts no-assert * import { Buffer } from "@std/streams/buffer"; * * const array = new Uint8Array([0, 1, 2]); diff --git a/streams/byte_slice_stream.ts b/streams/byte_slice_stream.ts index c3af61bee..c1a4e16f9 100644 --- a/streams/byte_slice_stream.ts +++ b/streams/byte_slice_stream.ts @@ -47,14 +47,14 @@ export class ByteSliceStream extends TransformStream { * @param end The zero-indexed byte index to stop reading at. Inclusive. * * @example No parameters - * ```ts + * ```ts no-assert * import { ByteSliceStream } from "@std/streams/byte-slice-stream"; * * const byteSliceStream = new ByteSliceStream(); * ``` * * @example start = 4, end = 11 - * ```ts + * ```ts no-assert * import { ByteSliceStream } from "@std/streams/byte-slice-stream"; * * const byteSliceStream = new ByteSliceStream(4, 11); diff --git a/streams/delimiter_stream.ts b/streams/delimiter_stream.ts index 1f3c5afa6..0cd60c97b 100644 --- a/streams/delimiter_stream.ts +++ b/streams/delimiter_stream.ts @@ -76,14 +76,14 @@ export class DelimiterStream extends TransformStream { * @param options Options for the delimiter stream. * * @example comma as a delimiter - * ```ts + * ```ts no-assert * import { DelimiterStream } from "@std/streams/delimiter-stream"; * * const delimiterStream = new DelimiterStream(new TextEncoder().encode(",")); * ``` * * @example semicolon as a delimiter, and disposition set to `"suffix"` - * ```ts + * ```ts no-assert * import { DelimiterStream } from "@std/streams/delimiter-stream"; * * const delimiterStream = new DelimiterStream(new TextEncoder().encode(";"), { diff --git a/streams/iterate_reader.ts b/streams/iterate_reader.ts index cd51bd617..3ef3c38e3 100644 --- a/streams/iterate_reader.ts +++ b/streams/iterate_reader.ts @@ -17,7 +17,7 @@ export type { Reader, ReaderSync }; * @returns An async iterator that yields Uint8Array. * * @example Convert a `Deno.FsFile` into an async iterator and iterate over it - * ```ts + * ```ts no-assert no-eval * import { iterateReader } from "@std/streams/iterate-reader"; * * using f = await Deno.open("./README.md"); @@ -27,7 +27,7 @@ export type { Reader, ReaderSync }; * ``` * * @example Specify a buffer size of 1MiB - * ```ts + * ```ts no-assert no-eval * import { iterateReader } from "@std/streams/iterate-reader"; * * using f = await Deno.open("./README.md"); @@ -59,7 +59,7 @@ export function iterateReader( * @returns An iterator that yields Uint8Array. * * @example Convert a `Deno.FsFile` into an iterator and iterate over it - * ```ts + * ```ts no-eval no-assert * import { iterateReaderSync } from "@std/streams/iterate-reader"; * * using f = Deno.openSync("./README.md"); @@ -69,7 +69,7 @@ export function iterateReader( * ``` * * @example Specify a buffer size of 1MiB - * ```ts + * ```ts no-eval no-assert * import { iterateReaderSync } from "@std/streams/iterate-reader"; * * using f = await Deno.open("./README.md"); diff --git a/streams/limited_bytes_transform_stream.ts b/streams/limited_bytes_transform_stream.ts index a8f6823ec..e88f4672c 100644 --- a/streams/limited_bytes_transform_stream.ts +++ b/streams/limited_bytes_transform_stream.ts @@ -99,14 +99,14 @@ export class LimitedBytesTransformStream * @param options Options for the stream. * * @example size = 42 - * ```ts + * ```ts no-assert * import { LimitedBytesTransformStream } from "@std/streams/limited-bytes-transform-stream"; * * const limitedBytesTransformStream = new LimitedBytesTransformStream(42); * ``` * * @example size = 42, error = true - * ```ts + * ```ts no-assert * import { LimitedBytesTransformStream } from "@std/streams/limited-bytes-transform-stream"; * * const limitedBytesTransformStream = new LimitedBytesTransformStream(42, { error: true }); diff --git a/streams/limited_transform_stream.ts b/streams/limited_transform_stream.ts index 3a337c94a..2a49fac81 100644 --- a/streams/limited_transform_stream.ts +++ b/streams/limited_transform_stream.ts @@ -81,14 +81,14 @@ export class LimitedTransformStream extends TransformStream { * @param options Options for the stream. * * @example size = 42 - * ```ts + * ```ts no-assert * import { LimitedTransformStream } from "@std/streams/limited-transform-stream"; * * const limitedTransformStream = new LimitedTransformStream(42); * ``` * * @example size = 42, error = true - * ```ts + * ```ts no-assert * import { LimitedTransformStream } from "@std/streams/limited-transform-stream"; * * const limitedTransformStream = new LimitedTransformStream(42, { error: true }); diff --git a/streams/readable_stream_from_reader.ts b/streams/readable_stream_from_reader.ts index 581fe6723..88670f0e3 100644 --- a/streams/readable_stream_from_reader.ts +++ b/streams/readable_stream_from_reader.ts @@ -39,7 +39,7 @@ export interface ReadableStreamFromReaderOptions { * @returns A `ReadableStream` of `Uint8Array`s. * * @example Convert a `Deno.FsFile` into a readable stream: - * ```ts + * ```ts no-eval no-assert * import { readableStreamFromReader } from "@std/streams/readable-stream-from-reader"; * * using file = await Deno.open("./README.md", { read: true }); diff --git a/streams/reader_from_iterable.ts b/streams/reader_from_iterable.ts index ae498b5bd..16be4f070 100644 --- a/streams/reader_from_iterable.ts +++ b/streams/reader_from_iterable.ts @@ -12,7 +12,7 @@ import type { Reader } from "@std/io/types"; * @returns A `Reader` that reads from the iterable. * * @example Write `Deno.build` information to the blackhole 3 times every second - * ```ts + * ```ts no-eval no-assert * import { readerFromIterable } from "@std/streams/reader-from-iterable"; * import { copy } from "@std/io/copy"; * import { delay } from "@std/async/delay"; diff --git a/streams/reader_from_stream_reader.ts b/streams/reader_from_stream_reader.ts index 960a83110..fb646e27f 100644 --- a/streams/reader_from_stream_reader.ts +++ b/streams/reader_from_stream_reader.ts @@ -11,7 +11,7 @@ import type { Reader } from "@std/io/types"; * @returns A `Reader` that reads from the `streamReader`. * * @example Copy the response body of a fetch request to the blackhole - * ```ts + * ```ts no-eval no-assert * import { copy } from "@std/io/copy"; * import { readerFromStreamReader } from "@std/streams/reader-from-stream-reader"; * import { devNull } from "node:os"; diff --git a/streams/text_delimiter_stream.ts b/streams/text_delimiter_stream.ts index b36a7a2d7..a78cd31fb 100644 --- a/streams/text_delimiter_stream.ts +++ b/streams/text_delimiter_stream.ts @@ -68,15 +68,15 @@ export class TextDelimiterStream extends TransformStream { * @param delimiter A delimiter to split the stream by. * @param options Options for the stream. * - * @example comma as a delimiter - * ```ts + * @example Comma as a delimiter + * ```ts no-assert * import { TextDelimiterStream } from "@std/streams/text-delimiter-stream"; * * const delimiterStream = new TextDelimiterStream(","); * ``` * - * @example semicolon as a delimiter, and disposition set to `"suffix"` - * ```ts + * @example Semicolon as a delimiter, and disposition set to `"suffix"` + * ```ts no-assert * import { TextDelimiterStream } from "@std/streams/text-delimiter-stream"; * * const delimiterStream = new TextDelimiterStream(",", { diff --git a/streams/text_line_stream.ts b/streams/text_line_stream.ts index f68328d99..7832a3883 100644 --- a/streams/text_line_stream.ts +++ b/streams/text_line_stream.ts @@ -48,22 +48,20 @@ export interface TextLineStreamOptions { * ); * ``` * - * @example allowCR: true + * @example Allow splitting by `\r` + * * ```ts * import { TextLineStream } from "@std/streams/text-line-stream"; * import { assertEquals } from "@std/assert/assert-equals"; * * const stream = ReadableStream.from([ - * "CR\rLF", - * "\nCRLF\r\ndone", - * ]); + * "CR\rLF", + * "\nCRLF\r\ndone", + * ]).pipeThrough(new TextLineStream({ allowCR: true })); * - * const lineStream = stream.pipeThrough(new TextLineStream({ allowCR: true })); + * const lines = await Array.fromAsync(stream); * - * assertEquals( - * await Array.fromAsync(lineStream), - * ["CR", "LF", "CRLF", "done"], - * ); + * assertEquals(lines, ["CR", "LF", "CRLF", "done"]); * ``` */ export class TextLineStream extends TransformStream { @@ -77,15 +75,32 @@ export class TextLineStream extends TransformStream { * @example No parameters * ```ts * import { TextLineStream } from "@std/streams/text-line-stream"; + * import { assertEquals } from "@std/assert/assert-equals"; * - * const textLineStream = new TextLineStream(); + * const stream = ReadableStream.from([ + * "Hello,\n", + * "world!\n", + * ]).pipeThrough(new TextLineStream()); + * + * const lines = await Array.fromAsync(stream); + * + * assertEquals(lines, ["Hello,", "world!"]); * ``` * - * @example allowCR = true + * @example Allow splitting by `\r` + * * ```ts * import { TextLineStream } from "@std/streams/text-line-stream"; + * import { assertEquals } from "@std/assert/assert-equals"; * - * const textLineStream = new TextLineStream({ allowCR: true }); + * const stream = ReadableStream.from([ + * "CR\rLF", + * "\nCRLF\r\ndone", + * ]).pipeThrough(new TextLineStream({ allowCR: true })); + * + * const lines = await Array.fromAsync(stream); + * + * assertEquals(lines, ["CR", "LF", "CRLF", "done"]); * ``` */ constructor(options: TextLineStreamOptions = { allowCR: false }) { diff --git a/streams/writable_stream_from_writer.ts b/streams/writable_stream_from_writer.ts index 52df58ea3..5f3bb6246 100644 --- a/streams/writable_stream_from_writer.ts +++ b/streams/writable_stream_from_writer.ts @@ -27,7 +27,7 @@ export interface WritableStreamFromWriterOptions { * @returns A `WritableStream` of `Uint8Array`s. * * @example Convert `Deno.stdout` into a writable stream - * ```ts + * ```ts no-eval no-assert * // Note that you can directly get the writer from `Deno.stdout` by * // `Deno.stdout.writable`. This example is just for demonstration purposes; * // definitely not a recommended way. diff --git a/streams/writer_from_stream_writer.ts b/streams/writer_from_stream_writer.ts index 7e9c875dc..a12b7f5b9 100644 --- a/streams/writer_from_stream_writer.ts +++ b/streams/writer_from_stream_writer.ts @@ -12,7 +12,7 @@ export type { Writer }; * @returns A `Writer` that writes to the `WritableStreamDefaultWriter`. * * @example Read from a file and write to stdout using a writable stream - * ```ts + * ```ts no-eval no-assert * import { copy } from "@std/io/copy"; * import { writerFromStreamWriter } from "@std/streams/writer-from-stream-writer"; * diff --git a/text/case.ts b/text/case.ts index f017e15a4..139b6a007 100644 --- a/text/case.ts +++ b/text/case.ts @@ -9,8 +9,9 @@ import { capitalizeWord, splitToWords } from "./_util.ts"; * @example Usage * ```ts * import { toCamelCase } from "@std/text/case"; + * import { assertEquals } from "@std/assert/assert-equals"; * - * toCamelCase("deno is awesome"); // "denoIsAwesome" + * assertEquals(toCamelCase("deno is awesome"),"denoIsAwesome"); * ``` * * @param input The string that is going to be converted into camelCase @@ -28,8 +29,9 @@ export function toCamelCase(input: string): string { * @example Usage * ```ts * import { toKebabCase } from "@std/text/case"; + * import { assertEquals } from "@std/assert/assert-equals"; * - * toKebabCase("deno is awesome"); // "deno-is-awesome" + * assertEquals(toKebabCase("deno is awesome"), "deno-is-awesome"); * ``` * * @param input The string that is going to be converted into kebab-case @@ -46,8 +48,9 @@ export function toKebabCase(input: string): string { * @example Usage * ```ts * import { toPascalCase } from "@std/text/case"; + * import { assertEquals } from "@std/assert/assert-equals"; * - * toPascalCase("deno is awesome"); // "DenoIsAwesome" + * assertEquals(toPascalCase("deno is awesome"), "DenoIsAwesome"); * ``` * * @param input The string that is going to be converted into PascalCase @@ -64,7 +67,9 @@ export function toPascalCase(input: string): string { * @example Usage * ```ts * import { toSnakeCase } from "@std/text/case"; - * toSnakeCase("deno is awesome"); // "deno_is_awesome" + * import { assertEquals } from "@std/assert/assert-equals"; + * + * assertEquals(toSnakeCase("deno is awesome"), "deno_is_awesome"); * ``` * * @param input The string that is going to be converted into snake_case diff --git a/text/closest_string.ts b/text/closest_string.ts index 08a964ffd..0c35a3dde 100644 --- a/text/closest_string.ts +++ b/text/closest_string.ts @@ -7,16 +7,17 @@ import { assert } from "@std/assert/assert"; const getWordDistance = levenshteinDistance; /** - * get most-similar word + * The the most similar string from an array of strings. * * @example Usage * ```ts * import { closestString } from "@std/text/closest-string"; + * import { assertEquals } from "@std/assert/assert-equals"; * - * const possibleWords: string[] = ["length", "size", "blah", "help"]; + * const possibleWords = ["length", "size", "blah", "help"]; + * const suggestion = closestString("hep", possibleWords); * - * // case-insensitive by default - * const word = closestString("hep", possibleWords); + * assertEquals(suggestion, "help"); * ``` * * @param givenWord The string to measure distance against diff --git a/text/compare_similarity.ts b/text/compare_similarity.ts index 920d062f9..fa2296ded 100644 --- a/text/compare_similarity.ts +++ b/text/compare_similarity.ts @@ -6,7 +6,7 @@ import { levenshteinDistance } from "./levenshtein_distance.ts"; const getWordDistance = levenshteinDistance; /** - * Sort based on word similarity + * Sort based on word similarity. * * @param givenWord The string to measure distance against. * @param options An options bag containing a `caseSensitive` flag indicating @@ -16,12 +16,17 @@ const getWordDistance = levenshteinDistance; * similar, or `0` if they are equally similar. * * @example Usage + * + * Most-similar words will be at the start of the array. + * * ```ts * import { compareSimilarity } from "@std/text/compare-similarity"; - * const words = ["hi", "hello", "help"]; + * import { assertEquals } from "@std/assert/assert-equals"; * - * // words most-similar to "hep" will be at the front - * words.sort(compareSimilarity("hep")); + * const words = ["hi", "hello", "help"]; + * const sortedWords = words.sort(compareSimilarity("hep")); + * + * assertEquals(sortedWords, ["help", "hi", "hello"]); * ``` * @note * the ordering of words may change with version-updates diff --git a/text/levenshtein_distance.ts b/text/levenshtein_distance.ts index 00cab78f9..5bca6c916 100644 --- a/text/levenshtein_distance.ts +++ b/text/levenshtein_distance.ts @@ -7,7 +7,9 @@ * @example Usage * ```ts * import { levenshteinDistance } from "@std/text/levenshtein-distance"; - * levenshteinDistance("aa", "bb"); // 2 + * import { assertEquals } from "@std/assert/assert-equals"; + * + * assertEquals(levenshteinDistance("aa", "bb"), 2); * ``` * @param str1 - The first string. * @param str2 - The second string. diff --git a/text/mod.ts b/text/mod.ts index b8bfe4cb3..0473aef55 100644 --- a/text/mod.ts +++ b/text/mod.ts @@ -8,8 +8,9 @@ * * ```ts * import { toCamelCase } from "@std/text/case"; + * import { assertEquals } from "@std/assert/assert-equals"; * - * console.log(toCamelCase("snake_case")); // "snakeCase" + * assertEquals(toCamelCase("snake_case"), "snakeCase"); * ``` * * Or for comparing strings: diff --git a/text/word_similarity_sort.ts b/text/word_similarity_sort.ts index 82e8df008..a1b2033b2 100644 --- a/text/word_similarity_sort.ts +++ b/text/word_similarity_sort.ts @@ -3,26 +3,27 @@ import { compareSimilarity } from "./compare_similarity.ts"; /** - * Sorts a string-array by similarity to a given string + * Sorts a string-array by similarity to a given string. + * + * @example Basic usage + * + * This function is case-insensitive by default. * - * @example Usage * ```ts * import { wordSimilaritySort } from "@std/text/word-similarity-sort"; + * import { assertEquals } from "@std/assert/assert-equals"; * * const possibleWords = ["length", "size", "blah", "help"]; - * - * // case-insensitive by default * const suggestions = wordSimilaritySort("hep", possibleWords).join(", "); * - * // force case sensitive - * wordSimilaritySort("hep", possibleWords, { caseSensitive: true }); + * assertEquals(suggestions, "help, size, blah, length"); * ``` * * @param givenWord - The string to measure distance against * @param possibleWords - The string-array that will be sorted * @param options An options bag containing a `caseSensitive` flag indicating * whether the distance should include case. Default is false. - * @returns {string[]} A sorted copy of possibleWords + * @returns A sorted copy of possibleWords */ export function wordSimilaritySort( givenWord: string, diff --git a/toml/mod.ts b/toml/mod.ts index 3aa7aafb5..a38ce5a5e 100644 --- a/toml/mod.ts +++ b/toml/mod.ts @@ -91,10 +91,9 @@ * This module is browser compatible. * * ```ts - * import { - * parse, - * stringify, - * } from "@std/toml"; + * import { parse, stringify } from "@std/toml"; + * import { assertEquals } from "@std/assert/assert-equals"; + * * const obj = { * bin: [ * { name: "deno", path: "cli/main.rs" }, @@ -102,33 +101,24 @@ * ], * nib: [{ name: "node", path: "not_found" }], * }; + * * const tomlString = stringify(obj); - * console.log(tomlString); + * assertEquals(tomlString, ` + * [[bin]] + * name = "deno" + * path = "cli/main.rs" * - * // => - * // [[bin]] - * // name = "deno" - * // path = "cli/main.rs" + * [[bin]] + * name = "deno_core" + * path = "src/foo.rs" * - * // [[bin]] - * // name = "deno_core" - * // path = "src/foo.rs" - * - * // [[nib]] - * // name = "node" - * // path = "not_found" + * [[nib]] + * name = "node" + * path = "not_found" + * `); * * const tomlObject = parse(tomlString); - * console.log(tomlObject); - * - * // => - * // { - * // bin: [ - * // { name: "deno", path: "cli/main.rs" }, - * // { name: "deno_core", path: "src/foo.rs" } - * // ], - * // nib: [ { name: "node", path: "not_found" } ] - * // } + * assertEquals(tomlObject, obj); * ``` * * @module diff --git a/ulid/mod.ts b/ulid/mod.ts index a24e6a208..6c93dafc2 100644 --- a/ulid/mod.ts +++ b/ulid/mod.ts @@ -10,7 +10,7 @@ * To generate a ULID use the {@linkcode ulid} function. This will generate a * ULID based on the current time. * - * ```ts + * ```ts no-assert * import { ulid } from "@std/ulid"; * * ulid(); // 01HYFKMDF3HVJ4J3JZW8KXPVTY @@ -21,7 +21,7 @@ * will be strictly increasing, even for the same current time, use the * {@linkcode monotonicUlid} function. * - * ```ts + * ```ts no-assert * import { monotonicUlid } from "@std/ulid"; * * monotonicUlid(); // 01HYFKHG5F8RHM2PM3D7NSTDAS @@ -33,9 +33,12 @@ * * ```ts * import { decodeTime, ulid } from "@std/ulid"; + * import { assertEquals } from "@std/assert/assert-equals"; * - * const x = ulid(150000); - * decodeTime(x); // 150000 + * const timestamp = 150_000; + * const ulidString = ulid(timestamp); + * + * assertEquals(decodeTime(ulidString), timestamp); * ``` * * @module @@ -58,10 +61,13 @@ import { * * @example Decode the time from a ULID * ```ts - * import { ulid, decodeTime } from "@std/ulid"; + * import { decodeTime, ulid } from "@std/ulid"; + * import { assertEquals } from "@std/assert/assert-equals"; * - * const x = ulid(150000); - * decodeTime(x); // 150000 + * const timestamp = 150_000; + * const ulidString = ulid(timestamp); + * + * assertEquals(decodeTime(ulidString), timestamp); * ``` * * @param ulid The ULID to extract the timestamp from. @@ -102,15 +108,16 @@ const defaultMonotonicUlid = monotonicFactory(); * previous ULIDs for that same seed time. * * @example Generate a monotonic ULID - * ```ts + * ```ts no-assert * import { monotonicUlid } from "@std/ulid"; + * * monotonicUlid(); // 01HYFKHG5F8RHM2PM3D7NSTDAS * monotonicUlid(); // 01HYFKHG5F8RHM2PM3D7NSTDAT * monotonicUlid(); // 01HYFKHHX8H4BRY8BYHAV1BZ2T * ``` * * @example Generate a monotonic ULID with a seed time - * ```ts + * ```ts no-assert * import { monotonicUlid } from "@std/ulid"; * * // Strict ordering for the same timestamp, by incrementing the least-significant random bit by 1 @@ -144,15 +151,16 @@ export function monotonicUlid(seedTime: number = Date.now()): string { * same. For that, use the {@linkcode monotonicUlid} function. * * @example Generate a ULID - * ```ts + * ```ts no-assert * import { ulid } from "@std/ulid"; + * * ulid(); // 01HYFKMDF3HVJ4J3JZW8KXPVTY * ulid(); // 01HYFKMDF3D2P7G502B9Z2VKV0 * ulid(); // 01HYFKMDZQ7JD17CRKDXQSZ3Z4 * ``` * * @example Generate a ULID with a seed time - * ```ts + * ```ts no-assert * import { ulid } from "@std/ulid"; * * ulid(150000); // 0000004JFG3EKDRE04TVVDJW7K diff --git a/webgpu/describe_texture_format.ts b/webgpu/describe_texture_format.ts index 7e323d24c..9629514ea 100644 --- a/webgpu/describe_texture_format.ts +++ b/webgpu/describe_texture_format.ts @@ -33,8 +33,16 @@ const allFlags = GPUTextureUsage.COPY_SRC | GPUTextureUsage.COPY_DST | * @example Basic usage * ```ts * import { describeTextureFormat } from "@std/webgpu/describe-texture-format"; + * import { assertEquals } from "@std/assert/assert-equals"; * - * describeTextureFormat("rgba8unorm-srgb"); + * assertEquals(describeTextureFormat("rgba8unorm"), { + * requiredFeature: undefined, + * sampleType: "float", + * allowedUsages: 31, + * blockDimensions: [1, 1], + * blockSize: 4, + * components: 4, + * }); * ``` * * @param format The format to get the information about. diff --git a/webgpu/row_padding.ts b/webgpu/row_padding.ts index 8b75e955d..06257ba10 100644 --- a/webgpu/row_padding.ts +++ b/webgpu/row_padding.ts @@ -16,15 +16,17 @@ export const COPY_BYTES_PER_ROW_ALIGNMENT = 256; export const BYTES_PER_PIXEL = 4; /** - * Calculates the number of bytes including necessary padding when passing a {@linkcode GPUImageCopyBuffer}. + * Calculates the number of bytes including necessary padding when passing a + * {@linkcode GPUImageCopyBuffer}. * * Ref: https://en.wikipedia.org/wiki/Data_structure_alignment#Computing_padding * * @example Usage * ```ts * import { getRowPadding } from "@std/webgpu/row-padding"; + * import { assertEquals } from "@std/assert/assert-equals"; * - * getRowPadding(2); // { unpadded: 8, padded: 256 } + * assertEquals(getRowPadding(1), { unpadded: 4, padded: 256 }); * ``` * * @param width The width to get the padding for @@ -55,9 +57,12 @@ export function getRowPadding(width: number): Padding { * @example Usage * ```ts * import { resliceBufferWithPadding } from "@std/webgpu/row-padding"; + * import { assertEquals } from "@std/assert/assert-equals"; * * const input = new Uint8Array([0, 255, 0, 255, 120, 120, 120]); - * resliceBufferWithPadding(input, 1, 1); // Uint8Array(4) [ 0, 255, 0, 255 ] + * const result = resliceBufferWithPadding(input, 1, 1); + * + * assertEquals(result, new Uint8Array([0, 255, 0, 255])); * ``` * * @param buffer The buffer to reslice.