Polish binary.js a little bit.

Internal functions now have some code documentation, and the runtime
dependency on arrays being iterable (for splatting arguments) was
removed.

diff --git a/binary.js b/binary.js
index dc4b6120ebfffb0e5ed845de73808b40c937b90a..272775fd2939b05959610ba12917e5906ceae2f9 100644 (file)
--- a/binary.js
+++ b/binary.js
@@ -32,6 +32,29 @@ const { [iteratorSymbol]: arrayIterator } = arrayPrototype;
 const {
   next: arrayIteratorNext,
 } = Object.getPrototypeOf([][iteratorSymbol]());
+const argumentIterablePrototype = {
+  [iteratorSymbol]() {
+    return {
+      next: bind(
+        arrayIteratorNext,
+        call(arrayIterator, this.args, []),
+        [],
+      ),
+    };
+  },
+};
+const binaryCodeUnitIterablePrototype = {
+  [iteratorSymbol]() {
+    return {
+      next: bind(
+        arrayIteratorNext,
+        call(arrayIterator, this, []),
+        [],
+      ),
+    };
+  },
+};
+
 const getBufferByteLength =
   Object.getOwnPropertyDescriptor(bufferPrototype, "byteLength").get;
 const getTypedArrayBuffer =
@@ -70,22 +93,21 @@ const bufferFromArgs = ($, $s) =>
         typeof $ == "string"
           ? $
           : hasOwnProperty($, "raw")
-          ? rawString($, ...$s)
+          ? rawString(
+            $,
+            ...objectCreate(argumentIterablePrototype, {
+              args: { value: $s },
+            }),
+          )
           : `${$}`,
       );
 
-const binaryCodeUnitIterablePrototype = {
-  [iteratorSymbol]() {
-    return {
-      next: bind(
-        arrayIteratorNext,
-        call(arrayIterator, this, []),
-        [],
-      ),
-    };
-  },
-};
-
+/**
+ * Returns the result of decoding the provided base64 string into an
+ * ArrayBuffer.
+ *
+ * ※ This function is not exposed.
+ */
 const decodeBase64 = (source, safe = false) => {
   const u6s = map(
     source.length % 4 == 0
@@ -138,6 +160,12 @@ const decodeBase64 = (source, safe = false) => {
   return call(getViewBuffer, dataView, []);
 };
 
+/**
+ * Returns the result of encoding the provided ArrayBuffer into a
+ * base64 string.
+ *
+ * ※ This function is not exposed.
+ */
 const encodeBase64 = (buffer, safe = false) => {
   const dataView = new View(buffer);
   const byteLength = call(getBufferByteLength, buffer, []);
@@ -193,19 +221,28 @@ const encodeBase64 = (buffer, safe = false) => {
   return stringFromCodeUnits(...resultingCodeUnits);
 };
 
+/**
+ * Returns a source string generated from the arguments passed to a
+ * tag function.
+ *
+ * ※ This function is not exposed.
+ */
 const sourceFromArgs = ($, $s) =>
   stringReplace(
-    typeof $ == "string"
-      ? $
-      : hasOwnProperty($, "raw")
-      ? rawString($, ...$s)
+    typeof $ == "string" ? $ : hasOwnProperty($, "raw")
+      ? rawString(
+        $,
+        ...objectCreate(argumentIterablePrototype, {
+          args: { value: $s },
+        }),
+      )
       : `${$}`,
     /[\t\n\f\r ]+/gu,
     "",
   );
 
 /**
- * Returns an ArrayBuffer generated from the provided Base64.
+ * Returns an ArrayBuffer generated from the provided base64 string.
  *
  * This function can also be used as a tag for a template literal. The
  * literal will be interpreted akin to `String.raw`.
@@ -214,8 +251,8 @@ export const base64Binary = ($, ...$s) =>
   decodeBase64(sourceFromArgs($, $s));
 
 /**
- * Returns a (big‐endian) base64 string created from a typed array,
- * buffer, or (16‐bit) string.
+ * Returns a (big‐endian) base64 string created from the provided typed
+ * array, buffer, or (16‐bit) string.
  *
  * This function can also be used as a tag for a template literal. The
  * literal will be interpreted akin to `String.raw`.
@@ -225,7 +262,7 @@ export const base64String = ($, ...$s) =>
 
 /**
  * Returns an ArrayBuffer generated from the provided filename‐safe
- * Base64.
+ * base64 string.
  *
  * This function can also be used as a tag for a template literal. The
  * literal will be interpreted akin to `String.raw`.
@@ -234,8 +271,8 @@ export const filenameSafeBase64Binary = ($, ...$s) =>
   decodeBase64(sourceFromArgs($, $s), true);
 
 /**
- * Returns a (big‐endian) filename‐safe base64 string created from a
- * typed array, buffer, or (16‐bit) string.
+ * Returns a (big‐endian) filename‐safe base64 string created from the
+ * provided typed array, buffer, or (16‐bit) string.
  *
  * This function can also be used as a tag for a template literal. The
  * literal will be interpreted akin to `String.raw`.
@@ -246,7 +283,8 @@ export const filenameSafeBase64String = ($, ...$s) =>
 /**
  * Returns whether the provided value is a Base64 string.
  *
- * Returns false if the provided value is not a string primitive.
+ * ※ This function returns false if the provided value is not a string
+ * primitive.
  */
 export const isBase64 = ($) => {
   if (typeof $ !== "string") {
@@ -264,7 +302,8 @@ export const isBase64 = ($) => {
 /**
  * Returns whether the provided value is a filename‐safe base64 string.
  *
- * Returns false if the provided value is not a string primitive.
+ * ※ This function returns false if the provided value is not a string
+ * primitive.
  */
 export const isFilenameSafeBase64 = ($) => {
   if (typeof $ !== "string") {