From 6adf67631763304b1513844880c68b5f69f4db88 Mon Sep 17 00:00:00 2001 From: Asher Gomez Date: Wed, 13 Dec 2023 11:00:17 +1100 Subject: [PATCH 1/2] docs(encoding): complete documentation --- encoding/ascii85.ts | 69 ++++++++++++++++++++----------------------- encoding/base32.ts | 59 ++++++++++++++++++------------------ encoding/base58.ts | 45 +++++++++++++++++----------- encoding/base64.ts | 58 ++++++++++++++++++------------------ encoding/base64url.ts | 57 +++++++++++++++++------------------ encoding/hex.ts | 35 +++++++++++++++++----- 6 files changed, 174 insertions(+), 149 deletions(-) diff --git a/encoding/ascii85.ts b/encoding/ascii85.ts index d4b68a3fd700..279c3abb7df2 100644 --- a/encoding/ascii85.ts +++ b/encoding/ascii85.ts @@ -4,8 +4,7 @@ import { validateBinaryLike } from "./_util.ts"; /** - * {@linkcode encode} and {@linkcode decode} for - * [Ascii85/base85](https://en.wikipedia.org/wiki/Ascii85) encoding. + * Utilities for working with [ascii85]{@link https://en.wikipedia.org/wiki/Ascii85} encoding. * * This module is browser compatible. * @@ -23,36 +22,25 @@ import { validateBinaryLike } from "./_util.ts"; * encoded data for btoa. Checksums for btoa are not supported. Delimiters are not * supported by other encodings.) * - * @example - * ```ts - * import { - * decodeAscii85, - * encodeAscii85, - * } from "https://deno.land/std@$STD_VERSION/encoding/ascii85.ts"; - * - * const a85Repr = "LpTqp"; - * - * const binaryData = decodeAscii85(a85Repr); - * console.log(binaryData); - * // => Uint8Array [ 136, 180, 79, 24 ] - * - * console.log(encodeAscii85(binaryData)); - * // => LpTqp - * ``` - * * @module */ +/** Supported ascii85 standards. */ export type Ascii85Standard = "Adobe" | "btoa" | "RFC 1924" | "Z85"; -/** encoding/decoding options */ +/** Options for {@linkcode encodeAscii85} and {@linkcode decodeAscii85}. */ export interface Ascii85Options { - /** characterset and delimiter (if supported and used). + /** + * Character set and delimiter (if supported and used). * * @default {"Adobe"} */ standard?: Ascii85Standard; - /** whether to use a delimiter (if supported) - "<~" and "~>" by default */ + /** + * Whether to use a delimiter (if supported). + * + * @default {false} + */ delimiter?: boolean; } const rfc1924 = @@ -61,22 +49,25 @@ const Z85 = "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ.-:+=^!/*?&<>()[]{}@%$#"; /** - * @deprecated (will be removed in 0.210.0) Use {@linkcode encodeAscii85} instead. - * * Encodes a given Uint8Array into ascii85, supports multiple standards * @param uint8 input to encode * @param [options] encoding options * @param [options.standard=Adobe] encoding standard (Adobe, btoa, RFC 1924 or Z85) * @param [options.delimiter] whether to use a delimiter, if supported by encoding standard + * + * @deprecated (will be removed in 0.210.0) Use {@linkcode encodeAscii85} instead. */ -export const encode = encodeAscii85; +export const encode: typeof encodeAscii85 = encodeAscii85; /** - * Encodes a given Uint8Array into ascii85, supports multiple standards - * @param uint8 input to encode - * @param [options] encoding options - * @param [options.standard=Adobe] encoding standard (Adobe, btoa, RFC 1924 or Z85) - * @param [options.delimiter] whether to use a delimiter, if supported by encoding standard + * Converts data into an ascii58-encoded string. + * + * @example + * ```ts + * import { encodeAscii85 } from "https://deno.land/std@$STD_VERSION/encoding/ascii85.ts"; + * + * encodeAscii85("Hello world!"); // => "87cURD]j7BEbo80" + * ``` */ export function encodeAscii85( data: ArrayBuffer | Uint8Array | string, @@ -144,20 +135,24 @@ export function encodeAscii85( } /** - * @deprecated (will be removed in 0.210.0) Use {@linkcode decodeAscii85} instead. - * * Decodes a given ascii85 encoded string. * @param ascii85 input to decode * @param [options] decoding options * @param [options.standard=Adobe] encoding standard used in the input string (Adobe, btoa, RFC 1924 or Z85) + * + * @deprecated (will be removed in 0.210.0) Use {@linkcode decodeAscii85} instead. */ -export const decode = decodeAscii85; +export const decode: typeof decodeAscii85 = decodeAscii85; /** - * Decodes a given ascii85 encoded string. - * @param ascii85 input to decode - * @param [options] decoding options - * @param [options.standard=Adobe] encoding standard used in the input string (Adobe, btoa, RFC 1924 or Z85) + * Decodes a given ascii85-encoded string. + * + * @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 ] + * ``` */ export function decodeAscii85( ascii85: string, diff --git a/encoding/base32.ts b/encoding/base32.ts index 2afbed9c1aa1..955fbceb7107 100644 --- a/encoding/base32.ts +++ b/encoding/base32.ts @@ -5,30 +5,14 @@ import { validateBinaryLike } from "./_util.ts"; /** - * {@linkcode encode} and {@linkcode decode} for - * [base32](https://en.wikipedia.org/wiki/Base32) encoding. + * Utilities for + * [base32]{@link https://datatracker.ietf.org/doc/html/rfc4648#section-6} + * encoding and decoding. * - * Modified from https://github.com/beatgammit/base64-js + * Modified from {@link https://github.com/beatgammit/base64-js}. * * This module is browser compatible. * - * @example - * ```ts - * import { - * decodeBase32, - * encodeBase32, - * } from "https://deno.land/std@$STD_VERSION/encoding/base32.ts"; - * - * const b32Repr = "RC2E6GA="; - * - * const binaryData = decodeBase32(b32Repr); - * console.log(binaryData); - * // => Uint8Array [ 136, 180, 79, 24 ] - * - * console.log(encodeBase32(binaryData)); - * // => RC2E6GA= - * ``` - * * @module */ @@ -80,16 +64,24 @@ function _byteLength(validLen: number, placeHoldersLen: number): number { } /** - * @deprecated (will be removed in 0.210.0) Use {@linkcode decodeBase32} instead. - * * Decodes a given RFC4648 base32 encoded string. * @param b32 + * + * @deprecated (will be removed in 0.210.0) Use {@linkcode decodeBase32} instead. */ -export const decode = decodeBase32; +export const decode: typeof decodeBase32 = decodeBase32; /** - * Decodes a given RFC4648 base32 encoded string. - * @param b32 + * Decodes a base32-encoded string. + * + * @see {@link https://datatracker.ietf.org/doc/html/rfc4648#section-6} + * + * @example + * ```ts + * import { decodeBase32 } from "https://deno.land/std@$STD_VERSION/encoding/base32.ts"; + * + * decodeBase32("NRQMA==="); // Uint8Array(3) [ 108, 96, 192 ] + * ``` */ export function decodeBase32(b32: string): Uint8Array { let tmp: number; @@ -182,15 +174,24 @@ function encodeChunk(uint8: Uint8Array, start: number, end: number): string { } /** - * @deprecated (will be removed in 0.210.0) Use {@linkcode encodeBase32} instead. - * * Encodes a given Uint8Array into RFC4648 base32 representation * @param uint8 + * + * @deprecated (will be removed in 0.210.0) Use {@linkcode encodeBase32} instead. */ -export const encode = encodeBase32; +export const encode: typeof encodeBase32 = encodeBase32; /** - * Encodes a given Uint8Array into RFC4648 base32 representation + * Converts data to a base32-encoded string. + * + * @see {@link https://datatracker.ietf.org/doc/html/rfc4648#section-6} + * + * @example + * ```ts + * import { encodeBase32 } from "https://deno.land/std@$STD_VERSION/encoding/base32.ts"; + * + * encodeBase32("6c60c0"); // "NRQMA===" + * ``` */ export function encodeBase32(data: ArrayBuffer | Uint8Array | string): string { const uint8 = validateBinaryLike(data); diff --git a/encoding/base58.ts b/encoding/base58.ts index 56ed24e36d0d..5fd03f99f8f0 100644 --- a/encoding/base58.ts +++ b/encoding/base58.ts @@ -4,8 +4,9 @@ import { validateBinaryLike } from "./_util.ts"; /** - * {@linkcode encodeBase58} and {@linkcode decodeBase58} for - * [base58](https://en.wikipedia.org/wiki/Binary-to-text_encoding#Base58) encoding. + * Utilities for + * [base58]{@link https://datatracker.ietf.org/doc/html/draft-msporny-base58-03} + * encoding and decoding. * * This module is browser compatible. * @@ -26,32 +27,32 @@ const base58alphabet = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz".split(""); /** - * @deprecated (will be removed in 0.210.0) Use {@linkcode encodeBase58} instead. - * * Encodes a given Uint8Array, ArrayBuffer or string into draft-mspotny-base58-03 RFC base58 representation: * https://tools.ietf.org/id/draft-msporny-base58-01.html#rfc.section.1 * - * @param data - * - * @returns Encoded value + * @deprecated (will be removed in 0.210.0) Use {@linkcode encodeBase58} instead. */ -export const encode = encodeBase58; +export const encode: typeof encodeBase58 = encodeBase58; /** - * @deprecated (will be removed in 0.210.0) Use {@linkcode decodeBase58} instead. - * * Decodes a given b58 string according to draft-mspotny-base58-03 RFC base58 representation: * https://tools.ietf.org/id/draft-msporny-base58-01.html#rfc.section.1 * - * @param b58 - * - * @returns Decoded value + * @deprecated (will be removed in 0.210.0) Use {@linkcode decodeBase58} instead. */ -export const decode = decodeBase58; +export const decode: typeof decodeBase58 = decodeBase58; /** - * Encodes a given Uint8Array, ArrayBuffer or string into draft-mspotny-base58-03 RFC base58 representation: - * https://tools.ietf.org/id/draft-msporny-base58-01.html#rfc.section.1 + * Converts data to a base58-encoded string. + * + * @see {@link https://datatracker.ietf.org/doc/html/draft-msporny-base58-03#section-3} + * + * @example + * ```ts + * import { encodeBase58 } from "https://deno.land/std@$STD_VERSION/encoding/base58.ts"; + * + * encodeBase58("Hello World!"); // "2NEpo7TZRRrLZSi2U" + * ``` */ export function encodeBase58(data: ArrayBuffer | Uint8Array | string): string { const uint8tData = validateBinaryLike(data); @@ -102,8 +103,16 @@ export function encodeBase58(data: ArrayBuffer | Uint8Array | string): string { } /** - * Decodes a given b58 string according to draft-mspotny-base58-03 RFC base58 representation: - * https://tools.ietf.org/id/draft-msporny-base58-01.html#rfc.section.1 + * Decodes a base58-encoded string. + * + * @see {@link https://datatracker.ietf.org/doc/html/draft-msporny-base58-03#section-4} + * + * @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 ] + * ``` */ export function decodeBase58(b58: string): Uint8Array { const splitInput = b58.trim().split(""); diff --git a/encoding/base64.ts b/encoding/base64.ts index 6ffc38ca91e1..2c37a8f8b6e5 100644 --- a/encoding/base64.ts +++ b/encoding/base64.ts @@ -4,28 +4,12 @@ import { validateBinaryLike } from "./_util.ts"; /** - * {@linkcode encodeBase64} and {@linkcode decodeBase64} for - * [base64](https://en.wikipedia.org/wiki/Base64) encoding. + * Utilities for + * [base64]{@link https://datatracker.ietf.org/doc/html/rfc4648#section-4} + * encoding and decoding. * * This module is browser compatible. * - * @example - * ```ts - * import { - * decodeBase64, - * encodeBase64, - * } from "https://deno.land/std@$STD_VERSION/encoding/base64.ts"; - * - * const b64Repr = "Zm9vYg=="; - * - * const binaryData = decodeBase64(b64Repr); - * console.log(binaryData); - * // => Uint8Array [ 102, 111, 111, 98 ] - * - * console.log(encodeBase64(binaryData)); - * // => Zm9vYg== - * ``` - * * @module */ @@ -97,24 +81,31 @@ const base64abc = [ ]; /** - * @deprecated (will be removed in 0.210.0) Use {@linkcode encodeBase64} instead. - * * CREDIT: https://gist.github.com/enepomnyaschih/72c423f727d395eeaa09697058238727 * Encodes a given Uint8Array, ArrayBuffer or string into RFC4648 base64 representation - * @param data + * + * @deprecated (will be removed in 0.210.0) Use {@linkcode encodeBase64} instead. */ -export const encode = encodeBase64; +export const encode: typeof encodeBase64 = encodeBase64; /** - * @deprecated (will be removed in 0.210.0) Use {@linkcode decodeBase64} instead. - * * Decodes a given RFC4648 base64 encoded string - * @param b64 + * + * @deprecated (will be removed in 0.210.0) Use {@linkcode decodeBase64} instead. */ -export const decode = decodeBase64; +export const decode: typeof decodeBase64 = decodeBase64; /** - * Encodes a given Uint8Array, ArrayBuffer or string into RFC4648 base64 representation + * Converts data into a base64-encoded string. + * + * @see {@link https://datatracker.ietf.org/doc/html/rfc4648#section-4} + * + * @example + * ```ts + * import { encodeBase64 } from "https://deno.land/std@$STD_VERSION/encoding/base64.ts"; + * + * encodeBase64("foobar"); // "Zm9vYmFy" + * ``` */ export function encodeBase64(data: ArrayBuffer | Uint8Array | string): string { // CREDIT: https://gist.github.com/enepomnyaschih/72c423f727d395eeaa09697058238727 @@ -145,7 +136,16 @@ export function encodeBase64(data: ArrayBuffer | Uint8Array | string): string { } /** - * Decodes a given RFC4648 base64 encoded string + * Decodes a base64-encoded string. + * + * @see {@link https://datatracker.ietf.org/doc/html/rfc4648#section-4} + * + * @example + * ```ts + * import { encodeBase64 } from "https://deno.land/std@$STD_VERSION/encoding/base64.ts"; + * + * encodeBase64("foobar"); // "Zm9vYmFy" + * ``` */ export function decodeBase64(b64: string): Uint8Array { const binString = atob(b64); diff --git a/encoding/base64url.ts b/encoding/base64url.ts index 999fab7949a8..616655e7be19 100644 --- a/encoding/base64url.ts +++ b/encoding/base64url.ts @@ -2,27 +2,12 @@ // This module is browser compatible. /** - * {@linkcode encodeBase64Url} and {@linkcode decodeBase64Url} for - * [base64 URL safe](https://en.wikipedia.org/wiki/Base64#URL_applications) encoding. + * Utilities for + * [base64url]{@link https://datatracker.ietf.org/doc/html/rfc4648#section-5} + * encoding and decoding. * * This module is browser compatible. * - * @example - * ```ts - * import { - * decodeBase64Url, - * encodeBase64Url, - * } from "https://deno.land/std@$STD_VERSION/encoding/base64url.ts"; - * - * const binary = new TextEncoder().encode("foobar"); - * const encoded = encodeBase64Url(binary); - * console.log(encoded); - * // => "Zm9vYmFy" - * - * console.log(decodeBase64Url(encoded)); - * // => Uint8Array(6) [ 102, 111, 111, 98, 97, 114 ] - * ``` - * * @module */ @@ -59,24 +44,32 @@ function convertBase64ToBase64url(b64: string) { } /** - * @deprecated (will be removed in 0.210.0) Use {@linkcode encodeBase64Url} instead. - * * Encodes a given ArrayBuffer or string into a base64url representation * @param data + * + * @deprecated (will be removed in 0.210.0) Use {@linkcode encodeBase64Url} instead. */ -export const encode = encodeBase64Url; +export const encode: typeof encodeBase64Url = encodeBase64Url; /** - * @deprecated (will be removed in 0.210.0) Use {@linkcode decodeBase64Url} instead. - * * Converts given base64url encoded data back to original * @param b64url + * + * @deprecated (will be removed in 0.210.0) Use {@linkcode decodeBase64Url} instead. */ -export const decode = decodeBase64Url; +export const decode: typeof decodeBase64Url = decodeBase64Url; /** - * Encodes a given ArrayBuffer or string into a base64url representation - * @param data + * Convert data into a base64url-encoded string. + * + * @see {@link https://datatracker.ietf.org/doc/html/rfc4648#section-5} + * + * @example + * ```ts + * import { encodeBase64Url } from "https://deno.land/std@$STD_VERSION/encoding/base64url.ts"; + * + * encodeBase64Url(new TextEncoder().encode("foobar")); // "Zm9vYmFy" + * ``` */ export function encodeBase64Url( data: ArrayBuffer | Uint8Array | string, @@ -85,8 +78,16 @@ export function encodeBase64Url( } /** - * Converts given base64url encoded data back to original - * @param b64url + * Decodes a given base64url-encoded string. + * + * @see {@link https://datatracker.ietf.org/doc/html/rfc4648#section-5} + * + * @example + * ```ts + * import { decodeBase64Url } from "https://deno.land/std@$STD_VERSION/encoding/base64url.ts"; + * + * decodeBase64Url("Zm9vYmFy"); // Uint8Array(6) [ 102, 111, 111, 98, 97, 114 ] + * ``` */ export function decodeBase64Url(b64url: string): Uint8Array { return base64.decodeBase64(convertBase64urlToBase64(b64url)); diff --git a/encoding/hex.ts b/encoding/hex.ts index 03c7d657e5b3..44c8cb126451 100644 --- a/encoding/hex.ts +++ b/encoding/hex.ts @@ -5,7 +5,8 @@ import { validateBinaryLike } from "./_util.ts"; -/** Port of the Go +/** + * Port of the Go * [encoding/hex](https://github.com/golang/go/blob/go1.12.5/src/encoding/hex/hex.go) * library. * @@ -55,9 +56,9 @@ function fromHexChar(byte: number): number { } /** - * @deprecated (will be removed in 0.210.0) Use {@linkcode encodeHex} instead. - * * Encodes `src` into `src.length * 2` bytes. + * + * @deprecated (will be removed in 0.210.0) Use {@linkcode encodeHex} instead. */ export function encode(src: Uint8Array): Uint8Array { const dst = new Uint8Array(src.length * 2); @@ -69,7 +70,16 @@ export function encode(src: Uint8Array): Uint8Array { return dst; } -/** Encodes the source into hex string. */ +/** + * Converts data into a hex-encoded string. + * + * @example + * ```ts + * import { encodeHex } from "https://deno.land/std@$STD_VERSION/encoding/hex.ts"; + * + * encodeHex("abc"); // "616263" + * ``` + */ export function encodeHex(src: string | Uint8Array | ArrayBuffer): string { const u8 = validateBinaryLike(src); @@ -83,10 +93,10 @@ export function encodeHex(src: string | Uint8Array | ArrayBuffer): string { } /** - * @deprecated (will be removed in 0.210.0) Use {@linkcode decodeHex} instead. - * * Decodes `src` into `src.length / 2` bytes. * If the input is malformed, an error will be thrown. + * + * @deprecated (will be removed in 0.210.0) Use {@linkcode decodeHex} instead. */ export function decode(src: Uint8Array): Uint8Array { const dst = new Uint8Array(src.length / 2); @@ -106,8 +116,17 @@ export function decode(src: Uint8Array): Uint8Array { return dst; } -/** Decodes the given hex string to Uint8Array. - * If the input is malformed, an error will be thrown. */ +/** + * Decodes the given hex-encoded string. If the input is malformed, an error is + * thrown. + * + * @example + * ```ts + * import { decodeHex } from "https://deno.land/std@$STD_VERSION/encoding/hex.ts"; + * + * decodeHex("616263"); // Uint8Array(3) [ 97, 98, 99 ] + * ``` + */ export function decodeHex(src: string): Uint8Array { const u8 = textEncoder.encode(src); const dst = new Uint8Array(u8.length / 2); From 58be242a7ab428386c3a241ecdf8cdf6c6128d4e Mon Sep 17 00:00:00 2001 From: Asher Gomez Date: Wed, 13 Dec 2023 11:47:14 +1100 Subject: [PATCH 2/2] tweak --- encoding/ascii85.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/encoding/ascii85.ts b/encoding/ascii85.ts index 279c3abb7df2..263c3aa347a0 100644 --- a/encoding/ascii85.ts +++ b/encoding/ascii85.ts @@ -25,7 +25,7 @@ import { validateBinaryLike } from "./_util.ts"; * @module */ -/** Supported ascii85 standards. */ +/** Supported ascii85 standards for {@linkcode Ascii85Options}. */ export type Ascii85Standard = "Adobe" | "btoa" | "RFC 1924" | "Z85"; /** Options for {@linkcode encodeAscii85} and {@linkcode decodeAscii85}. */