BREAKING(encoding): deprecate encode/decode, add encodeFoo/decodeFoo (#…

…3660)
denoland · Sep 21, 2023 · 1a1d35a · 1a1d35a
1 parent b62f528
commit 1a1d35a
Show file tree

Hide file tree

Showing 10 changed files with 165 additions and 60 deletions.
diff --git a/encoding/ascii85.ts b/encoding/ascii85.ts
@@ -57,14 +57,35 @@ const rfc1924 =
   "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz!#$%&()*+-;<=>?@^_`{|}~";
 const Z85 =
   "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ.-:+=^!/*?&<>()[]{}@%$#";
+
+/**
+ * @deprecated (will be removed in 0.210.0) Use a `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
+ */
+export const encode = 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
  */
-export function encode(uint8: Uint8Array, options?: Ascii85Options): string {
+export function encodeAscii85(
+  data: ArrayBuffer | Uint8Array | string,
+  options?: Ascii85Options,
+): string {
+  let uint8 = typeof data === "string"
+    ? new TextEncoder().encode(data)
+    : data instanceof Uint8Array
+    ? data
+    : new Uint8Array(data);
+
   const standard = options?.standard ?? "Adobe";
   let output: string[] = [],
     v: number,
@@ -123,13 +144,27 @@ export function encode(uint8: Uint8Array, options?: Ascii85Options): string {
   }
   return output.slice(0, output.length - difference).join("");
 }
+
+/**
+ * @deprecated (will be removed in 0.210.0) Use a `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)
+ */
+export const decode = 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)
  */
-export function decode(ascii85: string, options?: Ascii85Options): Uint8Array {
+export function decodeAscii85(
+  ascii85: string,
+  options?: Ascii85Options,
+): Uint8Array {
   const encoding = options?.standard ?? "Adobe";
   // translate all encodings to most basic adobe/btoa one and decompress some special characters ("z" and "y")
   switch (encoding) {

diff --git a/encoding/ascii85_test.ts b/encoding/ascii85_test.ts
@@ -1,6 +1,6 @@
 // Copyright 2018-2023 the Deno authors. All rights reserved. MIT license.
 import { assertEquals } from "../assert/mod.ts";
-import { Ascii85Standard, decode, encode } from "./ascii85.ts";
+import { Ascii85Standard, decodeAscii85, encodeAscii85 } from "./ascii85.ts";
 type TestCases = Partial<{ [index in Ascii85Standard]: string[][] }>;
 const utf8encoder = new TextEncoder();
 const testCasesNoDelimiter: TestCases = {
@@ -123,7 +123,7 @@ for (const [standard, tests] of Object.entries(testCasesNoDelimiter)) {
     fn() {
       for (const [bin, b85] of tests) {
         assertEquals(
-          encode(utf8encoder.encode(bin), {
+          encodeAscii85(bin, {
             standard: standard as Ascii85Standard,
           }),
           b85,
@@ -137,7 +137,7 @@ for (const [standard, tests] of Object.entries(testCasesNoDelimiter)) {
     fn() {
       for (const [bin, b85] of tests) {
         assertEquals(
-          decode(b85, { standard: standard as Ascii85Standard }),
+          decodeAscii85(b85, { standard: standard as Ascii85Standard }),
           utf8encoder.encode(bin),
         );
       }
@@ -151,7 +151,7 @@ for (const [standard, tests] of Object.entries(testCasesDelimiter)) {
     fn() {
       for (const [bin, b85] of tests) {
         assertEquals(
-          encode(utf8encoder.encode(bin), {
+          encodeAscii85(bin, {
             standard: standard as Ascii85Standard,
             delimiter: true,
           }),
@@ -166,7 +166,7 @@ for (const [standard, tests] of Object.entries(testCasesDelimiter)) {
     fn() {
       for (const [bin, b85] of tests) {
         assertEquals(
-          decode(b85, {
+          decodeAscii85(b85, {
             standard: standard as Ascii85Standard,
             delimiter: true,
           }),
@@ -185,8 +185,8 @@ Deno.test({
       [0x01, 0x02, 0x03, 0x04, 0x73, 0x70, 0x61, 0x6d],
     );
 
-    const encoded1 = encode(data1);
-    const encoded2 = encode(data2.subarray(4));
+    const encoded1 = encodeAscii85(data1);
+    const encoded2 = encodeAscii85(data2.subarray(4));
 
     assertEquals(encoded1, "F)YQ)");
     assertEquals(encoded2, "F)YQ)");

diff --git a/encoding/base32.ts b/encoding/base32.ts
@@ -13,17 +13,17 @@
  * @example
  * ```ts
  * import {
- *   decode,
- *   encode,
+ *   decodeBase32,
+ *   encodeBase32,
  * } from "https://deno.land/std@$STD_VERSION/encoding/base32.ts";
  *
  * const b32Repr = "RC2E6GA=";
  *
- * const binaryData = decode(b32Repr);
+ * const binaryData = decodeBase32(b32Repr);
  * console.log(binaryData);
  * // => Uint8Array [ 136, 180, 79, 24 ]
  *
- * console.log(encode(binaryData));
+ * console.log(encodeBase32(binaryData));
  * // => RC2E6GA=
  * ```
  *
@@ -77,11 +77,19 @@ function _byteLength(validLen: number, placeHoldersLen: number): number {
   return ((validLen + placeHoldersLen) * 5) / 8 - _getPadLen(placeHoldersLen);
 }
 
+/**
+ * @deprecated (will be removed in 0.210.0) Use a `decodeBase32` instead.
+ *
+ * Decodes a given RFC4648 base32 encoded string.
+ * @param b32
+ */
+export const decode = decodeBase32;
+
 /**
  * Decodes a given RFC4648 base32 encoded string.
  * @param b32
  */
-export function decode(b32: string): Uint8Array {
+export function decodeBase32(b32: string): Uint8Array {
   let tmp: number;
   const [validLen, placeHoldersLen] = getLens(b32);
 
@@ -172,10 +180,23 @@ function encodeChunk(uint8: Uint8Array, start: number, end: number): string {
 }
 
 /**
+ * @deprecated (will be removed in 0.210.0) Use a `encodeBase32` instead.
+ *
  * Encodes a given Uint8Array into RFC4648 base32 representation
  * @param uint8
  */
-export function encode(uint8: Uint8Array): string {
+export const encode = encodeBase32;
+
+/**
+ * Encodes a given Uint8Array into RFC4648 base32 representation
+ */
+export function encodeBase32(data: ArrayBuffer | Uint8Array | string): string {
+  const uint8 = typeof data === "string"
+    ? new TextEncoder().encode(data)
+    : data instanceof Uint8Array
+    ? data
+    : new Uint8Array(data);
+
   let tmp: number;
   const len = uint8.length;
   const extraBytes = len % 5;

diff --git a/encoding/base32_test.ts b/encoding/base32_test.ts
@@ -2,7 +2,7 @@
 // Copyright (c) 2016-2017 Linus Unnebäck. MIT license.
 // Copyright 2018-2023 the Deno authors. All rights reserved. MIT license.
 import { assert, assertEquals } from "../assert/mod.ts";
-import { decode, encode } from "./base32.ts";
+import { decodeBase32, encodeBase32 } from "./base32.ts";
 
 // Lifted from https://stackoverflow.com/questions/38987784
 const fromHexString = (hexString: string): Uint8Array =>
@@ -90,7 +90,7 @@ Deno.test({
   name: "[encoding.base32] encode",
   fn() {
     for (const [bin, b32] of testCases) {
-      assertEquals(encode(fromHexString(bin)), b32);
+      assertEquals(encodeBase32(fromHexString(bin)), b32);
     }
   },
 });
@@ -99,7 +99,7 @@ Deno.test({
   name: "[encoding.base32] decode",
   fn() {
     for (const [bin, b32] of testCases) {
-      assertEquals(toHexString(decode(b32)), bin);
+      assertEquals(toHexString(decodeBase32(b32)), bin);
     }
   },
 });
@@ -109,7 +109,7 @@ Deno.test({
   fn() {
     let errorCaught = false;
     try {
-      decode("OOOO==");
+      decodeBase32("OOOO==");
     } catch (e) {
       assert(e instanceof Error);
       assert(
@@ -126,7 +126,7 @@ Deno.test({
   fn() {
     let errorCaught = false;
     try {
-      decode("OOOOOO==");
+      decodeBase32("OOOOOO==");
     } catch (e) {
       assert(e instanceof Error);
       assert(e.message.includes("Invalid pad length"));

diff --git a/encoding/base58.ts b/encoding/base58.ts
@@ -2,7 +2,7 @@
 // This module is browser compatible.
 
 /**
- * {@linkcode encode} and {@linkcode decode} for
+ * {@linkcode encodeBase58} and {@linkcode decodeBase58} for
  * [base58](https://en.wikipedia.org/wiki/Binary-to-text_encoding#Base58) encoding.
  *
  * This module is browser compatible.
@@ -24,14 +24,34 @@ const base58alphabet =
   "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz".split("");
 
 /**
+ * @deprecated (will be removed in 0.210.0) Use a `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
  */
-export function encode(data: ArrayBuffer | string): string {
+export const encode = encodeBase58;
+
+/**
+ * @deprecated (will be removed in 0.210.0) Use a `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
+ */
+export const decode = 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
+ */
+export function encodeBase58(data: ArrayBuffer | Uint8Array | string): string {
   const uint8tData = typeof data === "string"
     ? new TextEncoder().encode(data)
     : data instanceof Uint8Array
@@ -86,12 +106,8 @@ export function encode(data: ArrayBuffer | 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
- *
- * @param b58
- *
- * @returns Decoded value
  */
-export function decode(b58: string): Uint8Array {
+export function decodeBase58(b58: string): Uint8Array {
   const splitInput = b58.trim().split("");
 
   let length = 0;

diff --git a/encoding/base58_test.ts b/encoding/base58_test.ts
@@ -1,7 +1,7 @@
 // Copyright 2018-2023 the Deno authors. All rights reserved. MIT license.
 
 import { assertEquals, assertThrows } from "../assert/mod.ts";
-import { decode, encode } from "./base58.ts";
+import { decodeBase58, encodeBase58 } from "./base58.ts";
 
 const testSetString = [
   ["", ""],
@@ -41,32 +41,32 @@ const testSetBinary = testSetString.map(([data, b58]) => {
 
 Deno.test("[encoding/base58] testBase58EncodeString", () => {
   for (const [input, output] of testSetString) {
-    assertEquals(encode(input), output);
+    assertEquals(encodeBase58(input), output);
   }
 });
 
 Deno.test("[encoding/base58] testBase58EncodeBinary", () => {
   for (const [input, output] of testSetBinary) {
-    assertEquals(encode(input), output);
+    assertEquals(encodeBase58(input), output);
   }
 });
 
 Deno.test("[encoding/base58] testBase58EncodeBinaryBuffer", () => {
   for (const [input, output] of testSetBinary) {
-    assertEquals(encode(input.buffer), output);
+    assertEquals(encodeBase58(input.buffer), output);
   }
 });
 
 Deno.test("[encoding/base58] testBase58DecodeBinary", () => {
   for (const [input, output] of testSetBinary) {
-    const outputBinary = decode(output);
+    const outputBinary = decodeBase58(output);
     assertEquals(outputBinary, input);
   }
 });
 
 Deno.test("[encoding/base58] testBase58DecodeError", () => {
   assertThrows(
-    () => decode("+2NEpo7TZRRrLZSi2U"),
+    () => decodeBase58("+2NEpo7TZRRrLZSi2U"),
     `Invalid base58 char at index 0 with value +`,
   );
 });