diff --git a/deno.json b/deno.json index 7b262949812c..fca56b671097 100644 --- a/deno.json +++ b/deno.json @@ -14,7 +14,7 @@ }, "tasks": { "test": "RUST_BACKTRACE=1 deno test --unstable-http --unstable-webgpu --doc --allow-all --parallel --coverage --trace-leaks", - "test:browser": "git grep --name-only \"This module is browser compatible.\" | grep -v deno.json | grep -v .github/workflows | grep -v _tools | xargs deno check --config browser-compat.tsconfig.json", + "test:browser": "git grep --name-only \"This module is browser compatible.\" | grep -v deno.json | grep -v .github/workflows | grep -v _tools | grep -v encoding/README.md | xargs deno check --config browser-compat.tsconfig.json", "fmt:licence-headers": "deno run --allow-read --allow-write ./_tools/check_licence.ts", "lint:deprecations": "deno run --allow-read --allow-net --allow-env=HOME ./_tools/check_deprecation.ts", "lint:doc-imports": "deno run --allow-env --allow-read ./_tools/check_doc_imports.ts", diff --git a/encoding/README.md b/encoding/README.md new file mode 100644 index 000000000000..2dfea1e9b18b --- /dev/null +++ b/encoding/README.md @@ -0,0 +1,9 @@ +Utilities for encoding and decoding common formats like hex, base64, and varint. + +This module is browser compatible. + +```ts +import { encodeBase64 } from "https://deno.land/std@$STD_VERSION/encoding/base64.ts"; + +encodeBase64("foobar"); // "Zm9vYmFy" +``` diff --git a/encoding/ascii85.ts b/encoding/ascii85.ts index 10ec4542ac9e..b85a3b606483 100644 --- a/encoding/ascii85.ts +++ b/encoding/ascii85.ts @@ -55,7 +55,7 @@ const Z85 = * ```ts * import { encodeAscii85 } from "https://deno.land/std@$STD_VERSION/encoding/ascii85.ts"; * - * encodeAscii85("Hello world!"); // => "87cURD]j7BEbo80" + * encodeAscii85("Hello world!"); // "87cURD]j7BEbo80" * ``` */ export function encodeAscii85( @@ -124,13 +124,18 @@ export function encodeAscii85( } /** - * Decodes a given ascii85-encoded string. + * Decodes a ascii85-encoded string. + * + * @param ascii85 The ascii85-encoded string to decode. + * @param options Options for decoding. + * @returns The decoded data. * * @example * ```ts * import { decodeAscii85 } from "https://deno.land/std@$STD_VERSION/encoding/ascii85.ts"; * - * decodeAscii85("87cURD]j7BEbo80"); // => Uint8Array [ 72, 101, 108, 108, 111, 32, 119, 111, 114, 108, 100, 33 ] + * decodeAscii85("87cURD]j7BEbo80"); + * // Uint8Array(12) [ 72, 101, 108, 108, 111, 32, 119, 111, 114, 108, 100, 33 ] * ``` */ export function decodeAscii85( @@ -162,7 +167,7 @@ export function decodeAscii85( ); break; } - //remove all invalid characters + // remove all invalid characters ascii85 = ascii85.replaceAll(/[^!-u]/g, ""); const len = ascii85.length; const output = new Uint8Array(len + 4 - (len % 4)); diff --git a/encoding/base32.ts b/encoding/base32.ts index 893cab2ab582..f64c6fb71cef 100644 --- a/encoding/base32.ts +++ b/encoding/base32.ts @@ -11,6 +11,14 @@ * * This module is browser compatible. * + * ```ts + * import { encodeBase32, decodeBase32 } from "https://deno.land/std@$STD_VERSION/encoding/base32.ts"; + * + * const encoded = encodeBase32("foobar"); // "MZXW6YTBOI======" + * + * decodeBase32(encoded); // Uint8Array(6) [ 102, 111, 111, 98, 97, 114 ] + * ``` + * * @module */ @@ -53,11 +61,15 @@ function _byteLength(validLen: number, placeHoldersLen: number): number { * * @see {@link https://datatracker.ietf.org/doc/html/rfc4648#section-6} * + * @param b32 The base32-encoded string to decode. + * @returns The decoded data. + * * @example * ```ts * import { decodeBase32 } from "https://deno.land/std@$STD_VERSION/encoding/base32.ts"; * - * decodeBase32("NRQMA==="); // Uint8Array(3) [ 108, 96, 192 ] + * decodeBase32("NRQMA==="); + * // Uint8Array(3) [ 108, 96, 192 ] * ``` */ export function decodeBase32(b32: string): Uint8Array { @@ -151,10 +163,13 @@ function encodeChunk(uint8: Uint8Array, start: number, end: number): string { } /** - * Converts data to a base32-encoded string. + * Converts data into a base32-encoded string. * * @see {@link https://datatracker.ietf.org/doc/html/rfc4648#section-6} * + * @param data The data to encode. + * @returns The base32-encoded string. + * * @example * ```ts * import { encodeBase32 } from "https://deno.land/std@$STD_VERSION/encoding/base32.ts"; diff --git a/encoding/base58.ts b/encoding/base58.ts index 6d2f532fec18..fd992ff372e2 100644 --- a/encoding/base58.ts +++ b/encoding/base58.ts @@ -8,6 +8,15 @@ * * This module is browser compatible. * + * ```ts + * import { encodeBase58, decodeBase58 } from "https://deno.land/std@$STD_VERSION/encoding/base58.ts"; + * + * const encoded = encodeBase58("Hello World!"); // "2NEpo7TZRRrLZSi2U" + * + * decodeBase58(encoded); + * // Uint8Array(12) [ 72, 101, 108, 108, 111, 32, 87, 111, 114, 108, 100, 33 ] + * ``` + * * @module */ @@ -27,10 +36,13 @@ const base58alphabet = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz".split(""); /** - * Converts data to a base58-encoded string. + * Converts data into a base58-encoded string. * * @see {@link https://datatracker.ietf.org/doc/html/draft-msporny-base58-03#section-3} * + * @param data The data to encode. + * @returns The base58-encoded string. + * * @example * ```ts * import { encodeBase58 } from "https://deno.land/std@$STD_VERSION/encoding/base58.ts"; @@ -93,11 +105,15 @@ export function encodeBase58(data: ArrayBuffer | Uint8Array | string): string { * * @see {@link https://datatracker.ietf.org/doc/html/draft-msporny-base58-03#section-4} * + * @param b58 The base58-encoded string to decode. + * @returns The decoded data. + * * @example * ```ts * import { decodeBase58 } from "https://deno.land/std@$STD_VERSION/encoding/base58.ts"; * - * decodeBase58("2NEpo7TZRRrLZSi2U"); // Uint8Array(12) [ 72, 101, 108, 108, 111, 32, 87, 111, 114, 108, 100, 33 ] + * decodeBase58("2NEpo7TZRRrLZSi2U"); + * // Uint8Array(12) [ 72, 101, 108, 108, 111, 32, 87, 111, 114, 108, 100, 33 ] * ``` */ export function decodeBase58(b58: string): Uint8Array { diff --git a/encoding/base64.ts b/encoding/base64.ts index ae621d09508f..f0651c6c162d 100644 --- a/encoding/base64.ts +++ b/encoding/base64.ts @@ -8,6 +8,17 @@ * * This module is browser compatible. * + * ```ts + * import { + * encodeBase64, + * decodeBase64, + * } from "https://deno.land/std@$STD_VERSION/encoding/base64.ts"; + * + * const encoded = encodeBase64("foobar"); // "Zm9vYmFy" + * + * decodeBase64(encoded); // Uint8Array(6) [ 102, 111, 111, 98, 97, 114 ] + * ``` + * * @module */ @@ -85,6 +96,9 @@ const base64abc = [ * * @see {@link https://datatracker.ietf.org/doc/html/rfc4648#section-4} * + * @param data The data to encode. + * @returns The base64-encoded string. + * * @example * ```ts * import { encodeBase64 } from "https://deno.land/std@$STD_VERSION/encoding/base64.ts"; @@ -134,11 +148,14 @@ export function encodeBase64(data: ArrayBuffer | Uint8Array | string): string { * * @see {@link https://datatracker.ietf.org/doc/html/rfc4648#section-4} * + * @param b64 The base64-encoded string to decode. + * @returns The decoded data. + * * @example * ```ts - * import { encodeBase64 } from "https://deno.land/std@$STD_VERSION/encoding/base64.ts"; + * import { decodeBase64 } from "https://deno.land/std@$STD_VERSION/encoding/base64.ts"; * - * encodeBase64("foobar"); // "Zm9vYmFy" + * decodeBase64("Zm9vYmFy"); // Uint8Array(6) [ 102, 111, 111, 98, 97, 114 ] * ``` */ export function decodeBase64(b64: string): Uint8Array { diff --git a/encoding/base64url.ts b/encoding/base64url.ts index 831718474f8d..4043895d5289 100644 --- a/encoding/base64url.ts +++ b/encoding/base64url.ts @@ -49,11 +49,14 @@ function convertBase64ToBase64url(b64: string) { * * @see {@link https://datatracker.ietf.org/doc/html/rfc4648#section-5} * + * @param data The data to encode. + * @returns The base64url-encoded string. + * * @example * ```ts * import { encodeBase64Url } from "https://deno.land/std@$STD_VERSION/encoding/base64url.ts"; * - * encodeBase64Url(new TextEncoder().encode("foobar")); // "Zm9vYmFy" + * encodeBase64Url("foobar"); // "Zm9vYmFy" * ``` */ export function encodeBase64Url( @@ -67,6 +70,9 @@ export function encodeBase64Url( * * @see {@link https://datatracker.ietf.org/doc/html/rfc4648#section-5} * + * @param b64url The base64url-encoded string to decode. + * @returns The decoded data. + * * @example * ```ts * import { decodeBase64Url } from "https://deno.land/std@$STD_VERSION/encoding/base64url.ts"; diff --git a/encoding/hex.ts b/encoding/hex.ts index 60cd2f9cafed..1bb1c1d57b86 100644 --- a/encoding/hex.ts +++ b/encoding/hex.ts @@ -10,20 +10,15 @@ * * This module is browser compatible. * - * @example * ```ts * import { * decodeHex, * encodeHex, * } from "https://deno.land/std@$STD_VERSION/encoding/hex.ts"; * - * const binary = new TextEncoder().encode("abc"); - * const encoded = encodeHex(binary); - * console.log(encoded); - * // => "616263" + * const encoded = encodeHex("abc"); // "616263" * - * console.log(decodeHex(encoded)); - * // => Uint8Array(3) [ 97, 98, 99 ] + * decodeHex(encoded); // Uint8Array(3) [ 97, 98, 99 ] * ``` * * @module diff --git a/encoding/varint.ts b/encoding/varint.ts index 20146d512f0b..e9e25d822e8a 100644 --- a/encoding/varint.ts +++ b/encoding/varint.ts @@ -4,6 +4,16 @@ /** * Functions for encoding typed integers in array buffers. * + * ```ts + * import { encode, decode } from "https://deno.land/std@$STD_VERSION/encoding/varint.ts"; + * + * const buf = new Uint8Array(10); + * const [encoded, bytesWritten] = encode(42n, buf); + * // [ Uint8Array(1) [ 42 ], 1 ]; + * + * decode(encoded); // [ 42n, 1 ]; + * ``` + * * @module */ @@ -37,6 +47,19 @@ const U64_VIEW = new BigUint64Array(AB); * * To know how many bytes the VarInt took to encode, simply negate `offset` * from the returned new `offset`. + * + * @param buf The buffer to decode from. + * @param offset The offset to start decoding from. + * @returns A tuple of the decoded varint 64-bit number, and the new offset. + * + * @example + * ```ts + * import { decode } from "https://deno.land/std@$STD_VERSION/encoding/varint.ts"; + * + * const buf = new Uint8Array([0x8E, 0x02]); + * decode(buf); + * // [ 300n, 2 ]; + * ``` */ export function decode(buf: Uint8Array, offset = 0): [bigint, number] { // Clear the last result from the Two's complement view @@ -110,6 +133,19 @@ export function decode(buf: Uint8Array, offset = 0): [bigint, number] { * * To know how many bytes the VarInt took to encode, simply negate `offset` * from the returned new `offset`. + * + * @param buf The buffer to decode from. + * @param offset The offset to start decoding from. + * @returns A tuple of the decoded varint 32-bit number, and the new offset. + * + * @example + * ```ts + * import { decode32 } from "https://deno.land/std@$STD_VERSION/encoding/varint.ts"; + * + * const buf = new Uint8Array([0x8E, 0x02]); + * decode32(buf); + * // [ 300, 2 ]; + * ``` */ export function decode32(buf: Uint8Array, offset = 0): [number, number] { let shift = 0; @@ -138,6 +174,19 @@ export function decode32(buf: Uint8Array, offset = 0): [number, number] { * If passed `buf` then that will be written into, starting at `offset`. The * resulting returned `Uint8Array` will be a slice of `buf`. The resulting * returned number is effectively `offset + bytesWritten`. + * + * @param num The number to encode. + * @param buf The buffer to write into. + * @param offset The offset to start writing at. + * @returns A tuple of the encoded VarInt `Uint8Array` and the new offset. + * + * @example + * ```ts + * import { encode } from "https://deno.land/std@$STD_VERSION/encoding/varint.ts"; + * + * const buf = new Uint8Array(10); + * encode(42n, buf); // [ Uint8Array(1) [ 42 ], 1 ]; + * ``` */ export function encode( num: bigint | number,