From 16025e52ba7e637e8e0b0dbe800676afbb33068e Mon Sep 17 00:00:00 2001 From: Asher Gomez Date: Fri, 10 May 2024 15:57:17 +1000 Subject: [PATCH 1/5] feat(internal): `internal@1.0.0` --- internal/deno.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/internal/deno.json b/internal/deno.json index e43fda6b17fd..848616078ff6 100644 --- a/internal/deno.json +++ b/internal/deno.json @@ -1,6 +1,6 @@ { "name": "@std/internal", - "version": "0.225.0", + "version": "1.0.0", "exports": { ".": "./mod.ts", "./build-message": "./build_message.ts", From 29974cb6100525fcd7baed6379bb7ea666ea9119 Mon Sep 17 00:00:00 2001 From: Asher Gomez Date: Wed, 15 May 2024 15:53:23 +1000 Subject: [PATCH 2/5] work --- _tools/check_docs.ts | 1 + deno.json | 2 +- internal/_types.ts | 9 --- internal/build_message.ts | 35 ++++++++- internal/deno.json | 3 +- internal/diff.ts | 18 ++++- internal/diff_str.ts | 28 ++++++- internal/format.ts | 15 +++- internal/mod.ts | 1 + internal/styles.ts | 155 +++++++++++++++++++++++++++++++------- internal/types.ts | 18 +++++ 11 files changed, 239 insertions(+), 46 deletions(-) delete mode 100644 internal/_types.ts create mode 100644 internal/types.ts diff --git a/_tools/check_docs.ts b/_tools/check_docs.ts index 88da0aa5ac75..46edd27d1888 100644 --- a/_tools/check_docs.ts +++ b/_tools/check_docs.ts @@ -21,6 +21,7 @@ const ENTRY_POINTS = [ "../bytes/mod.ts", "../datetime/mod.ts", "../collections/mod.ts", + "../internal/mod.ts", ] as const; const MD_SNIPPET = /(?<=```ts\n)(\n|.)*(?=\n```)/g; diff --git a/deno.json b/deno.json index 830d320b7d86..3d5263817d55 100644 --- a/deno.json +++ b/deno.json @@ -19,7 +19,7 @@ "lint:circular": "deno run --allow-env --allow-read --allow-net=deno.land,jsr.io ./_tools/check_circular_package_dependencies.ts", "lint:mod-exports": "deno run --allow-env --allow-read ./_tools/check_mod_exports.ts", "lint:tools-types": "deno check _tools/*.ts", - "lint:docs": "deno run -A _tools/check_docs.ts && deno doc --lint collections/mod.ts bytes/mod.ts datetime/mod.ts url/mod.ts", + "lint:docs": "deno run -A _tools/check_docs.ts && deno doc --lint collections/mod.ts bytes/mod.ts datetime/mod.ts internal/mod.ts url/mod.ts", "lint": "deno lint && deno task fmt:licence-headers --check && deno task lint:circular && deno task lint:deprecations && deno task lint:tools-types && deno task lint:mod-exports && deno task lint:docs", "typos": "typos -c ./.github/workflows/typos.toml", "build:crypto": "deno task --cwd crypto/_wasm wasmbuild", diff --git a/internal/_types.ts b/internal/_types.ts deleted file mode 100644 index 000a2adafc16..000000000000 --- a/internal/_types.ts +++ /dev/null @@ -1,9 +0,0 @@ -// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license. - -export type DiffType = "removed" | "common" | "added"; - -export interface DiffResult { - type: DiffType; - value: T; - details?: DiffResult[]; -} diff --git a/internal/build_message.ts b/internal/build_message.ts index 11db42c838e5..8f9854f2a53d 100644 --- a/internal/build_message.ts +++ b/internal/build_message.ts @@ -2,7 +2,7 @@ // This module is browser compatible. import { bgGreen, bgRed, bold, gray, green, red, white } from "./styles.ts"; -import type { DiffResult, DiffType } from "./_types.ts"; +import type { DiffResult, DiffType } from "./types.ts"; /** * Colors the output of assertion diffs. @@ -49,19 +49,48 @@ function createSign(diffType: DiffType): string { } } +/** Options for {@linkcode buildMessage}. */ +export interface BuildMessageOptions { + /** + * Whether to output the diff as a single string. + * + * @default {false} + */ + stringDiff?: boolean; +} + /** * Builds a message based on the provided diff result. * * @param diffResult The diff result array. * @param options Optional parameters for customizing the message. - * @param options.stringDiff Whether to output the diff as a single string. * * @returns An array of strings representing the built message. + * + * @example Usage + * ```ts + * import { diffstr, buildMessage } from "@std/internal"; + * + * const diffResult = diffstr("Hello, world!", "Hello, world"); + * + * console.log(buildMessage(diffResult)); + * // [ + * // "", + * // "", + * // " [Diff] Actual / Expected", + * // "", + * // "", + * // "- Hello, world!", + * // "+ Hello, world", + * // "", + * // ] + * ``` */ export function buildMessage( diffResult: ReadonlyArray>, - { stringDiff = false } = {}, + options: BuildMessageOptions = {}, ): string[] { + const { stringDiff = false } = options; const messages = [ "", "", diff --git a/internal/deno.json b/internal/deno.json index 5acb0b80c041..919f41200d80 100644 --- a/internal/deno.json +++ b/internal/deno.json @@ -7,6 +7,7 @@ "./diff-str": "./diff_str.ts", "./diff": "./diff.ts", "./format": "./format.ts", - "./styles": "./styles.ts" + "./styles": "./styles.ts", + "./types": "./types.ts" } } diff --git a/internal/diff.ts b/internal/diff.ts index 137d74c235fe..2dc66177e61d 100644 --- a/internal/diff.ts +++ b/internal/diff.ts @@ -1,7 +1,7 @@ // Copyright 2018-2024 the Deno authors. All rights reserved. MIT license. // This module is browser compatible. -import type { DiffResult, DiffType } from "./_types.ts"; +import type { DiffResult, DiffType } from "./types.ts"; interface FarthestPoint { y: number; @@ -128,6 +128,22 @@ function createFp( * @param B Expected value * * @returns An array of differences between the actual and expected values. + * + * @example Usage + * ```ts + * import { diff } from "@std/internal/diff"; + * import { assertEquals } from "@std/assert/assert-equals"; + * + * const a = [1, 2, 3]; + * const b = [1, 2, 4]; + * + * assertEquals(diff(a, b), [ + * { type: "common", value: 1 }, + * { type: "common", value: 2 }, + * { type: "removed", value: 3 }, + * { type: "added", value: 4 }, + * ]); + * ``` */ export function diff(A: T[], B: T[]): DiffResult[] { const prefixCommon = createCommon(A, B); diff --git a/internal/diff_str.ts b/internal/diff_str.ts index 747e6c14e01b..4120cbd9094a 100644 --- a/internal/diff_str.ts +++ b/internal/diff_str.ts @@ -1,5 +1,5 @@ // Copyright 2018-2024 the Deno authors. All rights reserved. MIT license. -import type { DiffResult } from "./_types.ts"; +import type { DiffResult } from "./types.ts"; import { diff } from "./diff.ts"; /** @@ -106,6 +106,32 @@ function createDetails( * @param B Expected string * * @returns Array of diff results. + * + * @example Usage + * ```ts + * import { diffstr } from "@std/internal/diff-str"; + * import { assertEquals } from "@std/assert/assert-equals"; + * + * assertEquals(diffstr("Hello!", "Hello"), [ + * { + * type: "removed", + * value: "Hello!\n", + * details: [ + * { type: "common", value: "Hello" }, + * { type: "removed", value: "!" }, + * { type: "common", value: "\n" } + * ] + * }, + * { + * type: "added", + * value: "Hello\n", + * details: [ + * { type: "common", value: "Hello" }, + * { type: "common", value: "\n" } + * ] + * } + * ]); + * ``` */ export function diffstr(A: string, B: string): DiffResult[] { // Compute multi-line diff diff --git a/internal/format.ts b/internal/format.ts index 5415657e2177..fd01e6837b00 100644 --- a/internal/format.ts +++ b/internal/format.ts @@ -3,8 +3,21 @@ /** * Converts the input into a string. Objects, Sets and Maps are sorted so as to - * make tests less flaky + * make tests less flaky. + * * @param v Value to be formatted + * + * @returns The formatted string + * + * @example Usage + * ```ts + * import { format } from "@std/internal/format"; + * import { assertEquals } from "@std/assert/assert-equals"; + * + * assertEquals(format({ a: 1, b: 2 }), "{\n a: 1,\n b: 2,\n}"); + * assertEquals(format(new Set([1, 2])), "Set(2) {\n 1,\n 2,\n}"); + * assertEquals(format(new Map([[1, 2]])), "Map(1) {\n 1 => 2,\n}"); + * ``` */ export function format(v: unknown): string { // deno-lint-ignore no-explicit-any diff --git a/internal/mod.ts b/internal/mod.ts index 1bddb34c4f5a..b372119485e8 100644 --- a/internal/mod.ts +++ b/internal/mod.ts @@ -12,3 +12,4 @@ export * from "./diff.ts"; export * from "./diff_str.ts"; export * from "./format.ts"; export * from "./styles.ts"; +export * from "./types.ts"; diff --git a/internal/styles.ts b/internal/styles.ts index 4e664649bec5..73199beee40a 100644 --- a/internal/styles.ts +++ b/internal/styles.ts @@ -66,11 +66,6 @@ interface Code { const enabled = !noColor; -/** - * Builds color code - * @param open - * @param close - */ function code(open: number[], close: number): Code { return { open: `\x1b[${open.join(";")}m`, @@ -79,11 +74,6 @@ function code(open: number[], close: number): Code { }; } -/** - * Applies color and background based on color code and its associated text - * @param str text to apply color settings to - * @param code color code to apply - */ function run(str: string, code: Code): string { return enabled ? `${code.open}${str.replace(code.regexp, code.open)}${code.close}` @@ -91,72 +81,170 @@ function run(str: string, code: Code): string { } /** - * Make the text bold. - * @param str text to make bold + * Sets the style of text to be printed to bold. + * + * Disable by setting the `NO_COLOR` environmental variable. + * + * @param str Text to make bold + * + * @returns Bold text for printing + * + * @example Usage + * ```ts + * import { bold } from "@std/internal/styles"; + * + * console.log(bold("Hello, world!")); // Prints "Hello, world!" in bold + * ``` */ export function bold(str: string): string { return run(str, code([1], 22)); } /** - * Set text color to red. - * @param str text to make red + * Sets the color of text to be printed to red. + * + * Disable by setting the `NO_COLOR` environmental variable. + * + * @param str Text to make red + * + * @returns Red text for printing + * + * @example Usage + * ```ts + * import { red } from "@std/internal/styles"; + * + * console.log(red("Hello, world!")); // Prints "Hello, world!" in red + * ``` */ export function red(str: string): string { return run(str, code([31], 39)); } /** - * Set text color to green. - * @param str text to make green + * Sets the color of text to be printed to green. + * + * Disable by setting the `NO_COLOR` environmental variable. + * + * @param str Text to make green + * + * @returns Green text for print + * + * @example Usage + * ```ts + * import { green } from "@std/internal/styles"; + * + * console.log(green("Hello, world!")); // Prints "Hello, world!" in green + * ``` */ export function green(str: string): string { return run(str, code([32], 39)); } /** - * Set text color to yellow. - * @param str text to make yellow + * Sets the color of text to be printed to yellow. + * + * Disable by setting the `NO_COLOR` environmental variable. + * + * @param str Text to make yellow + * + * @returns Yellow text for print + * + * @example Usage + * ```ts + * import { yellow } from "@std/internal/styles"; + * + * console.log(yellow("Hello, world!")); // Prints "Hello, world!" in yellow + * ``` */ export function yellow(str: string): string { return run(str, code([33], 39)); } /** - * Set text color to white. - * @param str text to make white + * Sets the color of text to be printed to white. + * + * @param str Text to make white + * + * @returns White text for print + * + * @example Usage + * ```ts + * import { white } from "@std/internal/styles"; + * + * console.log(white("Hello, world!")); // Prints "Hello, world!" in white + * ``` */ export function white(str: string): string { return run(str, code([37], 39)); } /** - * Set text color to gray. - * @param str text to make gray + * Sets the color of text to be printed to gray. + * + * @param str Text to make gray + * + * @returns Gray text for print + * + * @example Usage + * ```ts + * import { gray } from "@std/internal/styles"; + * + * console.log(gray("Hello, world!")); // Prints "Hello, world!" in gray + * ``` */ export function gray(str: string): string { return brightBlack(str); } /** - * Set text color to bright black. - * @param str text to make bright-black + * Sets the color of text to be printed to italic. + * + * @param str Text to make bright-black + * + * @returns Bright-black text for print + * + * @example Usage + * ```ts + * import { italic } from "@std/internal/styles"; + * + * console.log(italic("Hello, world!")); // Prints "Hello, world!" in italic + * ``` */ function brightBlack(str: string): string { return run(str, code([90], 39)); } /** - * Set background color to red. - * @param str text to make its background red + * Sets the background color of text to be printed to red. + * + * @param str Text to make its background red + * + * @returns Red background text for print + * + * @example Usage + * ```ts + * import { bgRed } from "@std/internal/styles"; + * + * console.log(bgRed("Hello, world!")); // Prints "Hello, world!" with red background + * ``` */ export function bgRed(str: string): string { return run(str, code([41], 49)); } /** - * Set background color to green. - * @param str text to make its background green + * Sets the background color of text to be printed to green. + * + * @param str Text to make its background green + * + * @returns Green background text for print + * + * @example Usage + * ```ts + * import { bgGreen } from "@std/internal/styles"; + * + * console.log(bgGreen("Hello, world!")); // Prints "Hello, world!" with green background + * ``` */ export function bgGreen(str: string): string { return run(str, code([42], 49)); @@ -174,7 +262,16 @@ const ANSI_PATTERN = new RegExp( /** * Remove ANSI escape codes from the string. * - * @param string to remove ANSI escape codes from + * @param string Text to remove ANSI escape codes from + * + * @returns Text without ANSI escape codes + * + * @example Usage + * ```ts + * import { red, stripAnsiCode } from "@std/internal/styles"; + * + * console.log(stripAnsiCode(red("Hello, world!"))); // Prints "Hello, world!" + * ``` */ export function stripAnsiCode(string: string): string { return string.replace(ANSI_PATTERN, ""); diff --git a/internal/types.ts b/internal/types.ts new file mode 100644 index 000000000000..9a073a709c27 --- /dev/null +++ b/internal/types.ts @@ -0,0 +1,18 @@ +// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license. + +/** Ways that lines in a diff can be different. */ +export type DiffType = "removed" | "common" | "added"; + +/** + * Represents the result of a diff operation. + * + * @template T The type of the value in the diff result. + */ +export interface DiffResult { + /** The type of the diff. */ + type: DiffType; + /** The value of the diff. */ + value: T; + /** The details of the diff. */ + details?: DiffResult[]; +} From f2097a5db49e2ba67235a5aaf499862aba6b6c2d Mon Sep 17 00:00:00 2001 From: Asher Gomez Date: Wed, 15 May 2024 15:53:47 +1000 Subject: [PATCH 3/5] revert --- internal/deno.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/internal/deno.json b/internal/deno.json index 919f41200d80..3d2d2a48db9c 100644 --- a/internal/deno.json +++ b/internal/deno.json @@ -1,6 +1,6 @@ { "name": "@std/internal", - "version": "1.0.0", + "version": "0.225.0", "exports": { ".": "./mod.ts", "./build-message": "./build_message.ts", From 9eda106eeddb9b79cdaf216faf09f191af570fb1 Mon Sep 17 00:00:00 2001 From: Asher Gomez Date: Wed, 15 May 2024 16:04:55 +1000 Subject: [PATCH 4/5] fix --- internal/styles.ts | 53 +++------------------------------------------- 1 file changed, 3 insertions(+), 50 deletions(-) diff --git a/internal/styles.ts b/internal/styles.ts index 73199beee40a..953bc93985dd 100644 --- a/internal/styles.ts +++ b/internal/styles.ts @@ -5,53 +5,6 @@ // This code is vendored from `fmt/colors.ts`. -/** - * String formatters and utilities for dealing with ANSI color codes. - * - * This module is browser compatible. - * - * This module supports `NO_COLOR` environmental variable disabling any coloring - * if `NO_COLOR` is set. - * - * @example - * ```ts - * import { - * bgBlue, - * bgRgb24, - * bgRgb8, - * bold, - * italic, - * red, - * rgb24, - * rgb8, - * } from "@std/fmt/colors"; - * - * console.log(bgBlue(italic(red(bold("Hello, World!"))))); - * - * // also supports 8bit colors - * - * console.log(rgb8("Hello, World!", 42)); - * - * console.log(bgRgb8("Hello, World!", 42)); - * - * // and 24bit rgb - * - * console.log(rgb24("Hello, World!", { - * r: 41, - * g: 42, - * b: 43, - * })); - * - * console.log(bgRgb24("Hello, World!", { - * r: 41, - * g: 42, - * b: 43, - * })); - * ``` - * - * @module - */ - // deno-lint-ignore no-explicit-any const { Deno } = globalThis as any; const noColor = typeof Deno?.noColor === "boolean" @@ -197,7 +150,7 @@ export function gray(str: string): string { } /** - * Sets the color of text to be printed to italic. + * Sets the color of text to be printed to bright-black. * * @param str Text to make bright-black * @@ -205,9 +158,9 @@ export function gray(str: string): string { * * @example Usage * ```ts - * import { italic } from "@std/internal/styles"; + * import { brightBlack } from "@std/internal/styles"; * - * console.log(italic("Hello, world!")); // Prints "Hello, world!" in italic + * console.log(brightBlack("Hello, world!")); // Prints "Hello, world!" in bright-black * ``` */ function brightBlack(str: string): string { From 8c82bed8234cc6c746eac9a2e04d6511242b8dfd Mon Sep 17 00:00:00 2001 From: Asher Gomez Date: Wed, 15 May 2024 16:08:30 +1000 Subject: [PATCH 5/5] fix --- internal/styles.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/internal/styles.ts b/internal/styles.ts index 953bc93985dd..73e294126a58 100644 --- a/internal/styles.ts +++ b/internal/styles.ts @@ -163,7 +163,7 @@ export function gray(str: string): string { * console.log(brightBlack("Hello, world!")); // Prints "Hello, world!" in bright-black * ``` */ -function brightBlack(str: string): string { +export function brightBlack(str: string): string { return run(str, code([90], 39)); }