@lumjs/encode 1.2.0 → 2.1.0

package/CHANGELOG.md

@@ -6,6 +6,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.1.0]
+### Changed
+- The `base64` library now supports the `Uint8Array.fromBase64` static method,
+  and the corresponding `toBase64()` instance method. As those are rather new
+  APIs and aren't supported by every JS runtime yet, it will check for them and
+  use them if found, and fall back to the prior implementation otherwise.
+- Updated this changelog, as I forgot to after 2.0 was released last year.
+
+## [2.0.0] - 2024-08-14
+### Changed
+- A major overhaul, removing the dependency on `crypto-js` library.
+- Rewrote `base64` library to use `atob`, `btoa`, `TextEncoder`, and `TextDecoder`.
+- Rewrote `hash` library using the modern `SubtleCrypto` APIs.
+- Moved `urlize()` and `deurlize()` functions into `base64` library.
+### Removed
+- The `crypto` sub-module which was designed as a wrapper for `crypto-js`.
+- The `safe64` library has been moved into a standalone [safe64-data] package.
+- Dependencies on `php-serialize` and `ubjson` which were only used by `safe64`.
+
 ## [1.2.0] - 2023-01-06
 ### Changed
 - Bumped `@lumjs/core` to `1.8.0`.
@@ -23,7 +42,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 - Initial release.
 
-[Unreleased]: https://github.com/supernovus/lum.encode.js/compare/v1.2.0...HEAD
+[Unreleased]: https://github.com/supernovus/lum.encode.js/compare/v2.1.0...HEAD
+[2.1.0]: https://github.com/supernovus/lum.encode.js/compare/v2.0.0...v2.1.0
+[2.0.0]: https://github.com/supernovus/lum.encode.js/compare/v1.2.0...v2.0.0
 [1.2.0]: https://github.com/supernovus/lum.encode.js/compare/v1.1.0...v1.2.0
 [1.1.0]: https://github.com/supernovus/lum.encode.js/compare/v1.0.0...v1.1.0
 [1.0.0]: https://github.com/supernovus/lum.encode.js/releases/tag/v1.0.0
+[safe64-data]: https://github.com/supernovus/lum.safe64-data.js
+

package/README.md

@@ -2,9 +2,20 @@
 
 A bunch of encoding libraries.
 
-Among other things, it offers a pure JS implementation of my 
-[Safe64](https://github.com/supernovus/lum.encode.php)
-data serialization and encoding format.
+## 2.x Release Notes
+
+Version `2.0` is pretty much a complete rewrite, and as the major version
+change indicates, is not 100% backwards compatible. I've tried to make the
+migration process as painless as possible, but some changes will be required.
+
+- Split the [Safe64] libraries into their own package.
+- Rewrote the `base64` and `hash` libraries to use modern `ES2015+` APIs.
+- Dropped the dependency on the legacy `crypto-js` package.
+- The `base64` libraries now have additional `async` functions for working
+  with arbitrary data in addition to the synchronous ones for Unicode text.
+- The `hash` library now uses `async` methods due to the `SubtleCrypto` API
+  that we're now using for generating the hashes.
+- Minor cleanups in `base91` and `utils` modules.
 
 ## Official URLs
 
@@ -20,3 +31,7 @@ Timothy Totten <2010@totten.ca>
 ## License
 
 [MIT](https://spdx.org/licenses/MIT.html)
+
+---
+
+[Safe64]: https://github.com/supernovus/lum.safe64-data.js

package/lib/base64.js

@@ -1,55 +1,430 @@
 
-const {S,isObj} = require('@lumjs/core/types');
-const Base64 = require('crypto-js/enc-base64');
-const Utf8 = require('crypto-js/enc-utf8');
+const {S,B,F,isObj} = require('@lumjs/core/types');
+
+const D_MIME = 'application/octet-stream';
+const D_ENC  = 'utf-8';
+const P_DATA = 'data:';
+const P_B64  = ';base64,';
+const R_PRE  = /^data\:(.*?);base64,/;
+const B_64U  = 'base64url';
+
+const UI8_FB64  = (typeof Uint8Array.fromBase64 === F);
+const URL_CHARS = /_-/;
 
 /**
  * Base64 functions.
  * 
- * Provides friendlier wrappers around the `crypto-js` libraries.
+ * Several functions based on code from MDN guides: 
+ * https://developer.mozilla.org/en-US/docs/Glossary/Base64
  * 
  * @module @lumjs/encode/base64
  */
 
 /**
- * Encode data as a `Base64` string.
- *
- * @param {(string|WordArray)} rawdata - The data we want to encode.
+ * Make a Base64 string URL-safe.
+ * 
+ * Converts `+` to `-` and `/` to `_`.
+ * By default it also strips `=` padding characters.
  * 
- * If this is a `string` we'll convert it into a `WordArray` using
- * the `stringFormat` object.
+ * @param {string} string - A Base64-encoded string
+ * @param {object} [options] Options
+ * @param {boolean} [options.useTildes=false] Use tildes?
  * 
- * @param {object} [stringFormat=Utf8] The string format.
+ * Replaces `=` with `~` characters instead of stripping them.
+ * This option is for backwards-compatibility with old code only,
+ * and there's no reason to use it these days.
+ * 
+ * @returns {string}
+ */
+function urlize(string, options={})
+{
+  string = string.replaceAll('+', '-');
+  string = string.replaceAll('/', '_');
+  string = string.replaceAll('=', options.useTildes ? '~' : '');
+  return string;
+}
+
+/**
+ * Undoes the effects of `urlize()`
+ * 
+ * Doesn't matter if the string has actually been passed to `urlize()`, 
+ * nor if the obsolete `options.useTildes` option was used when encoding.
+ * 
+ * @param {string} string
+ * @returns {string}
+ */
+function deurlize(string)
+{
+  string = string.replaceAll('-', '+');
+  string = string.replaceAll('_', '/');
+  string = string.replaceAll('~', '=');
+  string += "===".substring((string.length+3)%4);
+  return string;
+}
+
+/**
+ * Convert a Base64-encoded string into a Uint8Array.
  * 
- * Can be any encoding module from the `crypto-js` library.
- * Default is `CryptoJS.enc.Utf8`
+ * This is a low-level function with no options.
+ * See `decodeText()` for a more full-featured function.
  *
- * @return {string} The encoded string.
+ * This now checks to see if `Uint8Array.fromBase64()` exists,
+ * and if it does, will use it. Otherwise it uses the original
+ * encoding algorithm.
+ * 
+ * @param {string} base64 - Base64 encoded-string
+ * @param {object} [options] Passed to fromBase64() if it exists
+ * @returns {Uint8Array}
  */
-exports.encode = function(rawdata, stringFormat=Utf8)
+function toBytes(base64, options={})
 {
-  const data = typeof rawdata === S ? stringFormat.parse(rawdata) : rawdata;
-  return Base64.stringify(data);
+  if (UI8_FB64)
+  {
+    return Uint8Array.fromBase64(base64, options);
+  }
+
+  const binString = atob(base64);
+  return Uint8Array.from(binString, (m) => m.codePointAt(0));
 }
 
 /**
- * Decode a `Base64` string back into raw data.
+ * Convert a Uint8Array into Base64-encoded string.
+ * 
+ * This is a low-level function with no options.
+ * See `encodeText()` for a more full-featured function.
  *
- * @param {string} string - The Base64 string to decode.
+ * This now checks to see if `bytes.toBase64()` exists,
+ * and if it does, will use it. Otherwise it uses the original
+ * decoding algorithm.
+ * 
+ * @param {Uint8Array} bytes - Byte array to convert
+ * @param {object} [options] Passed to toBase64() if it exists
+ * @returns {string}
+ */
+function fromBytes(bytes, options={})
+{
+  if (typeof bytes.toBase64 === F)
+  {
+    return bytes.toBase64(options);
+  }
+
+  const binString = Array.from(bytes, (byte) =>
+    String.fromCodePoint(byte),
+  ).join("");
+  return btoa(binString);
+}
+
+/**
+ * Encode a string to Base64.
+ * 
+ * Uses the `TextEncoder` API and `fromBytes()`.
+ * May optionally pass the output through `urlize()`.
+ * 
+ * @param {string} data - Any valid (Unicode) string
+ * @param {(object|boolean)} [options] Options
+ * 
+ * - If `boolean`, used as `options.url`
+ * - Passed to `urlize()` if `options.url` is `true`
+ * 
+ * @param {boolean} [options.url=false] Urlize the output?
+ * If true, converts `+`, `/`, and `=` to URL-friendly alternatives.
+ * 
+ * @returns {string} A Base64-encoded string
+ */
+function encodeText(data, options={})
+{
+  if (typeof options === B) 
+  { // Assume the 'url' option.
+    options = {url: options};
+  }
+
+  const encoder = new TextEncoder();
+  data = encoder.encode(data);
+  const toB64 = (typeof data.toBase64 === F);
+
+  if (toB64 && options.url)
+  {
+    if (typeof options.alphabet !== S)
+    {
+      options.alphabet = B_64U;
+    }
+    if (!options.useTildes && typeof options.omitPadding !== B)
+    {
+      options.omitPadding = true;
+    }
+  }
+
+  const base64 = fromBytes(data, options);
+  return (options.url && !toB64) ? urlize(base64, options) : base64;
+}
+
+/**
+ * Decode a Base64 string into a Unicode string.
+ * 
+ * Uses `toBytes()` and the `TextDecoder` API.
+ * Will pass input through `deurlize()` by default.
+ * 
+ * @param {string} base64 - A Base64 string to decode
+ * @param {(object|boolean)} [options] Options 
+ * 
+ * - If `boolean`, used as `options.url`
+ * - Passed to `new TextDecoder()`
+ * - Passed to `decoder.decode()`
+ * 
+ * @param {boolean} [options.url=true] Deurlize the output?
+ * 
+ * Unless this is explicitly set as `false`, the `base64`
+ * string will be passed to `deurlize()` before being
+ * processed further.
+ * 
+ * @returns {string} A Unicode string
+ */
+function decodeText(base64, options={})
+{
+  if (typeof options === B) 
+  { // Assume the 'url' option.
+    options = {url: options};
+  }
+
+  if (options.url !== false)
+  { // Unless explicitly disabled, use deurlize() first.
+    if (UI8_FB64)
+    {
+      if (typeof options.alphabet !== S)
+      {
+        if (URL_CHARS.test(base64))
+        {
+          options.alphabet = B_64U;
+        }
+      }
+    }
+    else
+    { 
+      base64 = deurlize(base64);
+    }
+  }
+
+  const encoding = options.encoding ?? D_ENC;
+  const decoder = new TextDecoder(encoding, options);
+  return decoder.decode(toBytes(base64, options), options);
+}
+
+/**
+ * Encode binary data into a Base64-encoded Data URL.
+ * 
+ * @param {(File|Blob|Array|TypedArray|ArrayBuffer)} data - Data to encode
+ * 
+ * If this is not a `Blob` or `File`, it will be converted into one.
+ * 
+ * @param {object} [options] Options
+ * 
+ * @param {object} [options.blob] Options for Blob instances.
+ * 
+ * If specified, this will be passed to the `Blob()` constructor.
+ * 
+ * Only used if `data` is not already a `Blob` or `File` instance,
+ * and `options.file` was not specified or set to `false`.
  * 
- * @param {(object|false)} [stringFormat=Utf8] The string format.
+ * @param {(object|boolean)} [options.file] Options for File instances.
  * 
- * Can be any encoder library from the `crypto-js` library.
- * Default is `CryptoJS.enc.Utf8`
+ * If this is any non-false value, and `data` is not already a `Blob`,
+ * then we will convert `data` into a `File` instance instead of a `Blob`.
  * 
- * If this is `false`, we'll return a `WordArray` object.
+ * If this is an `object`, it will be passed to the `File()` constructor.
+ * 
+ * @param {string} [options.file.name] Filename for the `File` instance.
+ * 
+ * This is likely never needed, but is kept for completion sake.
+ * 
+ * @returns {Promise<string>} Resolves to the Data URL
+ */
+async function toDataUrl(data, options={})
+{
+  if (!(data instanceof Blob))
+  { // Build a Blob or File instance out of the passed data.
+    if (!Array.isArray(data))
+    { // Wrap the data in an Array.
+      data = [data];
+    }
+
+    // Sources for our Blob/File options.
+    const optsrc = [{type: D_MIME}, options];
+
+    if (options.file)
+    { // Let's build a File.
+      if (isObj(options.file))
+      {
+        optsrc.push(options.file);
+      }
+      const fopts = Object.assign(...optsrc);
+      const fname = fopts.filename ?? fopts.name ?? '';
+      data = new File(data, fname, fopts);
+    }
+    else
+    { // Let's build a Blob.
+      if (isObj(options.blob))
+      {
+        optsrc.push(options.blob);
+      }
+      const bopts = Object.assign(...optsrc);
+      data = new Blob(data, bopts);
+    }
+  } // Ensure sufficient Blobiness.
+
+  return await new Promise((resolve, reject) => 
+  {
+    const reader = Object.assign(new FileReader(), 
+    {
+      onload:  () => resolve(reader.result),
+      onerror: () => reject(reader.error),
+    });
+    reader.readAsDataURL(data);
+  });
+
+} // toDataUrl()
+
+/**
+ * Decode a Data URL into arbitrary binary data.
+ * 
+ * @param {string} dataUrl - A valid Data URL
+ * @param {object} [options] Options
+ * @param {boolean} [options.response=false] Return `Response`
+ * @param {boolean} [options.buffer=false] Return `ArrayBuffer`
  *
- * @return {(string|WordArray)} The decoded output.
+ * @returns {Promise<(Uint8Array|ArrayBuffer|Response)>} Promise of data
+ * 
+ * By default this resolves to a `Uint8Array` instance.
+ * 
+ * See `options.response` and `options.buffer` for alternative values that
+ * this may resolve to if requested.
+ * 
+ */
+async function fromDataUrl(dataUrl, options={})
+{
+  const res = await fetch(dataUrl);
+  if (options.response) return res;
+  const buf = await res.arrayBuffer();
+  if (options.buffer) return buf;
+  return new Uint8Array(buf);
+}
+
+/**
+ * A wrapper around `toDataUrl()` that strips the Data URL header,
+ * leaving just the Base64 string, and can emit URL-safe strings.
+ * 
+ * @param {mixed} data - See `toDataUrl()` for valid values
+ * @param {object} [options] Options
+ * 
+ * - Passed to `toDataUrl()`
+ * - Passed to `urlize()` if `options.url` is `true`
+ * 
+ * @param {boolean} [options.url=false] Use `urlize()` on encoded string?
+ * 
+ * @returns {Promise<string>} Resolves to a Base64 string
+ */
+async function encodeData(data, options={})
+{
+  let base64 = await toDataUrl(data, options).replace(R_PRE, '');
+  return options.url ? urlize(base64, options) : base64;
+}
+
+/**
+ * A wrapper around `fromDataUrl()` that adds a Data URL header
+ * if necessary, and can handle URL-safe Base64 strings.
+ * 
+ * @param {*} base64 
+ * @param {*} options 
+ * 
+ * - Passed to `fromDataUrl()`
+ * - Passed to `deurlize()` if `options.url` is NOT set to `false`
+ * 
+ * @param {boolean} [options.url=true] Use `deurlize()` on decoded string?
+ * 
+ * @returns {Promise} See `fromDataUrl()` for more details
+ */
+async function decodeData(base64, options={})
+{
+  if (!R_PRE.test(base64))
+  { // Assume a raw base64 string.
+    if (options.url !== false)
+    { // Unless explicitly disabled, use deurlize() first.
+      base64 = deurlize(base64);
+    }
+    const type = (typeof options.type === S) ? options.type : D_MIME;
+    base64 = P_DATA+type+P_B64+base64;
+  }
+  
+  return fromDataUrl(base64, options);
+}
+
+/**
+ * Encode data into a base64 string
+ * 
+ * Uses `encodeText()` unless the `data` or `options` have specific
+ * values that indicate `encodeData()` should be used instead.
+ * 
+ * @param {*} data - Data to encode
+ * 
+ * If this is anything other than a `string`, `encodeData()` will be used.
+ * 
+ * @param {object} [options] Options
+ * 
+ * If either `options.blob` or `options.file` are specified,
+ * `encodeData()` will be used.
+ * 
+ * @returns {(string|Promise<string>)} 
+ * See `encodeText()` and `encodeData()` for details.
  */
-exports.decode = function(string, stringFormat=Utf8)
+function encode(data, options={})
+{
+  if (options.blob || options.file || (typeof data !== S))
+  {
+    return encodeData(data, options);
+  }
+  else
+  {
+    return encodeText(data, options);
+  }
+}
+
+/**
+ * Decode a base64 string into data
+ * 
+ * Uses `decodeText()` unless the `base64` or `options` have specific
+ * values that indicate `decodeData()` should be used.
+ * 
+ * @param {string} base64 - Base64-encoded string (or a Data URL).
+ * 
+ * If this begins with a Data URL header, `decodeData()` will be used.
+ * 
+ * @param {object} [options] Options 
+ * 
+ * If either `options.response` or `options.buffer` are true,
+ * `decodeData()` will be used.
+ * 
+ * @returns {mixed} See `decodeText()` and `decodeData()` for details;
+ * will always be a `Promise` if `decodeData()` was used.
+ */
+function decode(base64, options={})
+{
+  if (options.response || options.buffer || R_PRE.test(base64))
+  {
+    return decodeData(base64, options);
+  }
+  else
+  {
+    return decodeText(base64, options);
+  }
+}
+
+module.exports =
 {
-  const data = Base64.parse(string);
-  return (isObj(stringFormat) ? data.toString(stringFormat) : data);
+  urlize, deurlize,
+  toBytes, fromBytes, 
+  encodeText, decodeText,
+  toDataUrl, fromDataUrl,
+  encodeData, decodeData,
+  encode, decode,
+  NATIVE_BASE64: UI8_FB64,
 }
 
-exports.Utf8 = Utf8;

package/lib/base91.js

@@ -1,4 +1,4 @@
-const {S,U,B} = require('@lumjs/core/types');
+const {S,B} = require('@lumjs/core/types');
 
 /**
  * A pure-Javascript base91 library.
@@ -169,17 +169,17 @@ exports.decode = function(data, opts={})
     opts = {string: opts};
   }
 
-  if (opts.string && typeof Uint8Array !== U && typeof TextDecoder !== U)
+  if (opts.string)
   {
     const uint = Uint8Array.from(output);
     const td = new TextDecoder();
     return td.decode(uint);
   }
-  if (opts.uint && typeof Uint8Array !== U)
+  if (opts.uint)
   {
     return Uint8Array.from(output);
   }
-  else if (opts.buffer && typeof Buffer !== U)
+  else if (opts.buffer)
   {
     return new Buffer.from(output);
   }