@lumjs/encode 2.4.1 → 2.5.0

package/CHANGELOG.md

@@ -6,6 +6,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.5.0] - 2026-02-20
+### Added
+- A bunch of extra exports that are _module-sets_.
+- `util.bytesToHex()` to be the inverse of `hexToBytes()`.
+- A new `polyfill` sub-module that is not part of the default exports.
+  Currently just has polyfills for a few newer Uint8Array methods.
+### Changed
+- Added options to `util.hexToBytes()` for returning a Uint8Array.
+- Added options to `base64.fromBytes()` and `base64.toBytes()`.
+
 ## [2.4.1] - 2026-02-09
 ### Changed
 - Refactored hashifier a bit to make resetting progressive digests simpler.
@@ -96,7 +106,8 @@ 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/v2.4.1...HEAD
+[Unreleased]: https://github.com/supernovus/lum.encode.js/compare/v2.5.0...HEAD
+[2.5.0]: https://github.com/supernovus/lum.encode.js/compare/v2.4.1...v2.5.0
 [2.4.1]: https://github.com/supernovus/lum.encode.js/compare/v2.4.0...v2.4.1
 [2.4.0]: https://github.com/supernovus/lum.encode.js/compare/v2.3.2...v2.4.0
 [2.3.2]: https://github.com/supernovus/lum.encode.js/compare/v2.3.1...v2.3.2

package/lib/base64.js

@@ -67,18 +67,24 @@ function deurlize(string)
  * 
  * This is a low-level function with minimal options.
  * See `decodeText()` for a more full-featured function.
- *
- * 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
+ * @param {string} base64 - Base64 encoded-string.
+ * @param {object} [options] Options.
+ * @param {boolean} [options.native=true] Use fromBase64() if it exists?
+ * 
+ * When enabled, this checks to see if `Uint8Array.fromBase64()` exists,
+ * and if it does, will use it, passing the options to it. 
+ * 
+ * If this is disabled, the original toBytes algorithm will be used.
+ * 
+ * This option is enabled by default, the only reason I could think of to
+ * disable it is if you are using this function as a polyfill.
+ * 
  * @returns {Uint8Array}
  */
 function toBytes(base64, options={})
 {
-  if (UI8_FB64)
+  if (UI8_FB64 && (options.native ?? true))
   {
     return Uint8Array.fromBase64(base64, options);
   }
@@ -92,18 +98,24 @@ function toBytes(base64, options={})
  * 
  * This is a low-level function with no options.
  * See `encodeText()` for a more full-featured function.
- *
- * 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
+ * @param {Uint8Array} bytes - Byte array to convert.
+ * @param {object} [options] Options.
+ * @param {boolean} [options.native=true] Use toBase64() if it exists?
+ * 
+ * When enabled, this checks to see if `bytes.toBase64()` exists,
+ * and if it does, will use it, passing the options to it. 
+ * 
+ * If this is disabled, the original fromBytes algorithm will be used.
+ * 
+ * This option is enabled by default, the only reason I could think of to
+ * disable it is if you are using this function as a polyfill.
+ * 
  * @returns {string}
  */
 function fromBytes(bytes, options={})
 {
-  if (typeof bytes.toBase64 === 'function')
+  if ((options.native ?? true) && typeof bytes.toBase64 === 'function')
   {
     return bytes.toBase64(options);
   }
@@ -127,10 +139,11 @@ function fromBytes(bytes, options={})
  * 
  * If this is a Uint8Array, we can skip the TextEncoder part.
  * 
- * @param {(object|boolean)} [options] Options
+ * @param {(object|boolean)} [options] Options.
  * 
- * - If `boolean`, used as `options.url`
- * - Passed to `urlize()` if `options.url` is `true`
+ * - If boolean, used as `options.url`.
+ * - Passed to urlize() if `options.url` is true.
+ * - Always passed to fromBytes().
  * 
  * @param {boolean} [options.url=false] Urlize the output?
  * If true, converts `+`, `/`, and `=` to URL-friendly alternatives.

package/lib/hotp.js

@@ -27,6 +27,9 @@ function needKey(key) {
 
 /**
  * HMAC-based One-Time-Passwords.
+ * 
+ * TODO: this needs documentation!
+ * 
  * @exports module:@lumjs/encode/hotp
  */
 class HOTP {

package/lib/index.js

@@ -1,5 +1,15 @@
 /**
  * A full set of encoding utilities.
+ * 
+ * This module includes alias properties for all sub-modules except `polyfill`.
+ * 
+ * This currently uses lazy-loading for everything other than `util`,
+ * but in version 3.0 I will be rewriting this package into ESM format,
+ * and the default module will become an alias for the `all` sub-module.
+ * 
+ * I'd suggest using one of the named sub-modules or module-sets if you
+ * want to load only specific components.
+ * 
  * @module @lumjs/encode
  */
 
@@ -7,6 +17,12 @@ const {df,lazy} = require('@lumjs/core');
 const E = {enumerable: true};
 const util = require('./util');
 
+/**
+ * @alias module:@lumjs/encode.util
+ * @see {@link module:@lumjs/encode/util}
+ */
+df(exports, 'Util', {value: util}, E);
+
 /**
  * @alias module:@lumjs/encode.util
  * @see {@link module:@lumjs/encode/util}

package/lib/polyfill.js

@@ -0,0 +1,135 @@
+/**
+ * Some simple polyfills.
+ * @module @lumjs/encode/polyfill
+ */
+'use strict';
+
+const cp = Object.assign;
+const { isComplex, isObj } = require('@lumjs/core/types');
+const { bytesToHex, hexToBytes } = require('./util.js');
+const { fromBytes: bytesToB64, toBytes: b64ToBytes } = require('./base64.js');
+
+const NON = { native: false };
+
+/**
+ * Polyfills for Uint8Array.
+ * 
+ * This is an array of two ruleset objects:
+ * 
+ * - Uint8Array
+ *   - fromBase64()
+ *   - fromHex()
+ * - Uint8Array.prototype
+ *   - toBase64()
+ *   - toHex()
+ * 
+ * @alias module:@lumjs/encode/polyfill.UI8
+ * @type {PolyfillRuleset[]}
+ */
+const UI8 = [
+  {
+    into: Uint8Array,
+    fill: {
+      fromBase64(string, options) {
+        return b64ToBytes(string, cp({}, options, NON));
+      },
+      fromHex(string) {
+        return hexToBytes(string, true, false);
+      },
+    },
+  },
+  {
+    into: Uint8Array.prototype,
+    fill: {
+      toBase64(options) {
+        return bytesToB64(this, cp({}, options, NON))
+      },
+      toHex() {
+        return bytesToHex(this, false);
+      },
+    },
+  },
+];
+
+const isPolyfill = v => (isObj(v) 
+  && isComplex(v.into)
+  && isObj(v.fill)
+);
+
+/**
+ * Process one or more polyfill definitions.
+ * @param {(PolyfillRuleset|PolyfillRuleset[])} rules - Rulesets to apply.
+ * 
+ * You can pass a single Ruleset object, or an array of associated Rulesets.
+ * 
+ * @returns {Map}
+ * 
+ * @example
+ * 
+ * For these examples I'll be applying the `UI8` polyfills.
+ * 
+ * **Usage if using *ESModules***:
+ * 
+ * ```js
+ * import { polyfill, UI8 } from '@lumjs/encode/polyfill';
+ * polyfill(UI8);
+ * ```
+ * 
+ * **OR if using *CommonJS***:
+ * 
+ * ```js
+ * const { polyfill, UI8 } = require('@lumjs/encode/polyfill');
+ * polyfill(UI8);
+ * ```
+ * 
+ * @alias module:@lumjs/encode/polyfill.polyfill
+ */
+function polyfill(rules) {
+  let filled = new Map();
+
+  if (!Array.isArray(rules)) {
+    rules = [rules];
+  }
+
+  for (let rule of rules) {
+
+    if (Array.isArray(rule)) {
+      polyfill(...rule);
+      continue;
+    }
+    else if (!isPolyfill(rule)) {
+      console.error('invalid polyfill definition', rule);
+      continue;
+    }
+
+    let target = rule.into;
+    for (let meth in rule.fill) {
+      if (target[meth] === undefined) {
+        target[meth] = rule.fill[meth];
+      }
+    }
+  }
+
+  return filled;
+}
+
+module.exports = {NON, UI8, isPolyfill, polyfill}
+
+/**
+ * Polyfill Ruleset
+ * @typedef {object} PolyfillRuleset
+ * 
+ * @prop {(object|function)} into - The target to polyfill.
+ * 
+ * Class constructors are functions, class prototypes are objects.
+ * Each Ruleset may only have one target, so if you need to polyfill
+ * both static and instance methods you'll need to use an array with
+ * a Ruleset for the constructor, and a Ruleset for the prototype.
+ * 
+ * @prop {object} fill - An object containing the polyfill methods.
+ * 
+ * Any method in this object that doesn't exist in the `for` target,
+ * will be added to it. As these are expected to be methods respecting
+ * the `this` context variable they should NOT be arrow (`=>`) closures.
+ * 
+ */

package/lib/sets/_inc.js

@@ -0,0 +1,18 @@
+/**
+ * Make lowercase aliases for every key in an object.
+ * @param {object} obj - Target object.
+ * @returns {object} `obj`
+ */
+function makeSet(obj) {
+  for (let key in obj) {
+    let lc = key.toLowerCase();
+    if (key !== lc) {
+      obj[lc] = obj[key];
+    }
+  }
+  return obj;
+}
+
+module.exports = {
+  makeSet,
+}

package/lib/sets/all.js

@@ -0,0 +1,14 @@
+const { makeSet } = require('./_inc.js');
+
+/**
+ * A module-set that includes all sub-modules except `polyfill`.
+ * 
+ * More specifically this composes together the `digest` and `otp`
+ * module-sets (which in turn compose `base` and `sign` respectively).
+ * 
+ * @alias module:@lumjs/encode/all
+ */
+module.exports = makeSet({
+  ...(require('./digest')),
+  ...(require('./otp')),
+});

package/lib/sets/base.js

@@ -0,0 +1,20 @@
+const { makeSet } = require('./_inc.js');
+
+/**
+ * A module-set for working with encodings.
+ * 
+ * Includes:
+ * - Base32
+ * - Base64
+ * - Base91
+ * - Util
+ * As well as lowercase aliases for all of those.
+ * 
+ * @module @lumjs/encode/base
+ */
+module.exports = makeSet({
+  Base32: require('../base32'),
+  Base64: require('../base64'),
+  Base91: require('../base91'),
+  Util: require('../util'),
+});

package/lib/sets/digest.js

@@ -0,0 +1,16 @@
+const { makeSet } = require('./_inc.js');
+
+/**
+ * A module-set for working with digests (aka data hashes).
+ * 
+ * Includes:
+ * - Hash
+ * As well as lowercase aliases for all of those, 
+ * and everything from the `base` set.
+ * 
+ * @module @lumjs/encode/digest
+ */
+module.exports = makeSet({
+  ...(require('./base.js')),
+  Hash: require('../hash.js'),
+});

package/lib/sets/otp.js

@@ -0,0 +1,18 @@
+const { makeSet } = require('./_inc.js');
+
+/**
+ * A module-set for working with One-Time-Passwords (OTP).
+ * 
+ * Includes:
+ * - HOTP
+ * - TOTP
+ * As well as lowercase aliases for all of those,
+ * and everything from the `sign` set.
+ * 
+ * @module @lumjs/encode/otp
+ */
+module.exports = makeSet({
+  ...(require('./sign')),
+  HOTP: require('../hotp'),
+  TOTP: require('../totp'),
+});

package/lib/sets/sign.js

@@ -0,0 +1,20 @@
+const { makeSet } = require('./_inc.js');
+
+/**
+ * A module-set for working with digital signatures.
+ * 
+ * Includes:
+ * - HMAC
+ * - PEM
+ * - Signature
+ * - Util
+ * As well as lowercase aliases for all of those.
+ * 
+ * @module @lumjs/encode/sign
+ */
+module.exports = makeSet({
+  HMAC: require('../hmac.js'),
+  PEM: require('../pem.js'),
+  Signature: require('../signature.js'),
+  Util: require('../util.js'),
+});

package/lib/totp.js

@@ -5,6 +5,9 @@ const DEF_OPTS = {step: 30};
 
 /**
  * Time-based One-Time-Passwords.
+ * 
+ * TODO: this needs documentation!
+ * 
  * @exports module:@lumjs/encode/totp
  */
 class TOTP extends HOTP {

package/lib/util.js

@@ -6,6 +6,8 @@
 
 const { TypedArray } = require('@lumjs/core/types');
 
+const UI8_FHEX  = (typeof Uint8Array.fromHex === 'function');
+
 /**
  * Return the ASCII/Unicode number for a character.
  * 
@@ -18,8 +20,7 @@ const { TypedArray } = require('@lumjs/core/types');
  * @param {string} string
  * @returns {number}
  */
-exports.ord = function (string)
-{
+exports.ord = function (string) {
   //  discuss at: https://locutus.io/php/ord/
   // original by: Kevin van Zonneveld (http://kevin.vanzonneveld.net)
   // bugfixed by: Onno Marsman
@@ -32,12 +33,10 @@ exports.ord = function (string)
 
   var str = string + '',
     code = str.charCodeAt(0);
-  if (0xD800 <= code && code <= 0xDBFF) 
-  {
+  if (0xD800 <= code && code <= 0xDBFF) {
     // High surrogate (could change last hex to 0xDB7F to treat high private surrogates as single characters)
     var hi = code;
-    if (str.length === 1) 
-    {
+    if (str.length === 1) {
       // This is just a high surrogate with no following low surrogate, so we return its value;
       return code;
       // we could also throw an error as it is not a complete character, but someone may want to know
@@ -45,8 +44,7 @@ exports.ord = function (string)
     var low = str.charCodeAt(1);
     return ((hi - 0xD800) * 0x400) + (low - 0xDC00) + 0x10000;
   }
-  if (0xDC00 <= code && code <= 0xDFFF) 
-  {
+  if (0xDC00 <= code && code <= 0xDFFF) {
     // Low surrogate
     // This is just a low surrogate with no preceding high surrogate, so we return its value;
     return code;
@@ -94,67 +92,56 @@ exports.ord = function (string)
  * 
  * @returns {Array} An array of integers.
  */
-exports.numByteArray = function (numStr, options={})
-{
-  if (typeof options === 'number')
-  {
-    options = {size: options};
+exports.numByteArray = function (numStr, options = {}) {
+  if (typeof options === 'number') {
+    options = { size: options };
   }
 
-  const numOpt = (name, defval, min, max) => 
-  {
+  const numOpt = (name, defval, min, max) => {
     const optval = options[name];
-    if (typeof optval !== 'number')
-    { // Was not a number, skip it.
+    if (typeof optval !== 'number') { // Was not a number, skip it.
       return defval;
     }
-    if (optval < min)
-    { // Value was lower than minimum.
+    if (optval < min) { // Value was lower than minimum.
       throw new RangeError(`${name} value ${optval} is less than ${min}`);
     }
-    if (max !== 0 && optval > max)
-    { // Value was higher than maximum.
+    if (max !== 0 && optval > max) { // Value was higher than maximum.
       throw new RangeError(`${name} value ${optval} is more than ${max}`);
     }
 
     return optval;
   }
 
-  const len  = numOpt('size', 2,  1, 0);
+  const len = numOpt('size', 2, 1, 0);
   const base = numOpt('base', 16, 2, 36);
 
   let strLen = numStr.length;
   let remainder = strLen % len;
 
-  if (options.strict && remainder !== 0)
-  {
+  if (options.strict && remainder !== 0) {
     throw new RangeError(`string length ${strLen} is not divisible by ${len}`);
   }
-  else if (options.pad && remainder !== 0)
-  {
+  else if (options.pad && remainder !== 0) {
     const padSize = len - remainder;
-    numStr = numStr.padStart(strLen+padSize, '0');
+    numStr = numStr.padStart(strLen + padSize, '0');
     strLen = numStr.length;
     remainder = strLen % len;
-    if (remainder !== 0)
-    { // Something is wrong in the universe...
-      console.error({numStr, strLen, len, remainder, arguments});
+    if (remainder !== 0) { // Something is wrong in the universe...
+      console.error({ numStr, strLen, len, remainder, arguments });
       throw new Error("string has remainder after padding");
     }
   }
 
-  const endOf = strLen - (len-1);
+  const endOf = strLen - (len - 1);
   const bytes = [];
 
-  const getBytes = (a,b) => bytes.push(parseInt(numStr.substring(a, b), base));
+  const getBytes = (a, b) => bytes.push(parseInt(numStr.substring(a, b), base));
 
-  for(let i=0; i < endOf; i+=len) 
-  {
-    getBytes(i, i+len);
+  for (let i = 0; i < endOf; i += len) {
+    getBytes(i, i + len);
   }
 
-  if (remainder !== 0)
-  {
+  if (remainder !== 0) {
     getBytes(strLen - remainder, strLen);
   }
 
@@ -167,27 +154,26 @@ exports.numByteArray = function (numStr, options={})
  * @param {WordArray} wordArray
  * @returns {Uint8Array}
  */
-exports.wordArrayToUint8Array = function(wordArray) 
-{
-  const l = wordArray.sigBytes;                                                                                                        
-  const words = wordArray.words;                                                                                                       
-  const result = new Uint8Array(l);                                                                                                    
-  var i=0 /*dst*/, j=0 /*src*/;
-  while(true) {
-      // here i is a multiple of 4
-      if (i==l)
-          break;
-      var w = words[j++];
-      result[i++] = (w & 0xff000000) >>> 24;
-      if (i==l)
-          break;
-      result[i++] = (w & 0x00ff0000) >>> 16;                                                                                            
-      if (i==l)                                                                                                                        
-          break;                                                                                                                       
-      result[i++] = (w & 0x0000ff00) >>> 8;
-      if (i==l)
-          break;
-      result[i++] = (w & 0x000000ff);                                                                                                  
+exports.wordArrayToUint8Array = function (wordArray) {
+  const l = wordArray.sigBytes;
+  const words = wordArray.words;
+  const result = new Uint8Array(l);
+  var i = 0 /*dst*/, j = 0 /*src*/;
+  while (true) {
+    // here i is a multiple of 4
+    if (i == l)
+      break;
+    var w = words[j++];
+    result[i++] = (w & 0xff000000) >>> 24;
+    if (i == l)
+      break;
+    result[i++] = (w & 0x00ff0000) >>> 16;
+    if (i == l)
+      break;
+    result[i++] = (w & 0x0000ff00) >>> 8;
+    if (i == l)
+      break;
+    result[i++] = (w & 0x000000ff);
   }
   return result;
 }
@@ -199,35 +185,70 @@ exports.wordArrayToUint8Array = function(wordArray)
  * and was borrowed from the `notp` package.
  *
  * @param {Integer} num
- * @return {Array} bytes
+ * @returns {Array} bytes
  */
-exports.intToBytes = function(num) 
-{
-	let bytes = [];
+exports.intToBytes = function (num) {
+  let bytes = [];
 
-	for(let i=7 ; i>=0 ; --i) 
-  {
-		bytes[i] = num & (255);
-		num = num >> 8;
-	}
+  for (let i = 7; i >= 0; --i) {
+    bytes[i] = num & (255);
+    num = num >> 8;
+  }
 
-	return bytes;
+  return bytes;
 }
 
 /**
- * Convert a hex value to a byte array.
+ * Convert a hex string to a byte array.
  *
- * Also taken from the `notp` package.
+ * Original version was also from the `notp` package,
+ * with some of my own enhancements added.
  *
- * @param {String} hex string of hex to convert to a byte array
- * @return {Array} bytes
+ * @param {string} hex - Hex string to convert to a byte array.
+ * @param {boolean} [uint8=false] Return a Uint8Array?
+ * @param {boolean} [native=true] Use Uint8Array.fromHex() if it exists?
+ * 
+ * Obviously only applicable if `unit8` is true, this will use the native
+ * method if it exists. The only reason I could think of to disable this 
+ * is if you are using this function as a polyfill.
+ * 
+ * @returns {(number[]|Uint8Array)}
+ */
+exports.hexToBytes = function (hex, uint8 = false, native = true) {
+
+  if (uint8 && native && UI8_FHEX) {
+    // A shortcut for modern JS runtimes.
+    return Uint8Array.fromHex(hex);
+  }
+
+  let bytes = [];
+  for (let c = 0, C = hex.length; c < C; c += 2) {
+    bytes.push(parseInt(hex.substring(c, c+2), 16));
+  }
+  return uint8 ? new Uint8Array(bytes) : bytes;
+}
+
+/**
+ * Converts a byte array to a hex string.
+ * 
+ * @param {(Uint8Array|number[])} bytes - Byte array.
+ * @param {boolean} [native=true] Use bytes.toHex() if it exists?
+ * 
+ * Like the same-named option in hexToBytes, the only reason I could
+ * think of to disable this is if you are using this as a polyfill
+ * for the `Uint8Array.prototype.toHex` method.
+ * 
+ * @returns {string}
  */
-exports.hexToBytes = function(hex) {
-	var bytes = [];
-	for(var c = 0, C = hex.length; c < C; c += 2) {
-		bytes.push(parseInt(hex.substr(c, 2), 16));
-	}
-	return bytes;
+exports.bytesToHex = function (bytes, native = true) {
+  
+  if (native && typeof bytes.toHex === 'function') {
+    return bytes.toHex();
+  }
+
+  return Array.from(bytes, function (byte) {
+    return ('0' + (byte & 0xFF).toString(16)).slice(-2);
+  }).join('');
 }
 
 /**
@@ -248,21 +269,19 @@ exports.hexToBytes = function(hex) {
  * @returns {TypedArray} Will be an instance of `typeClass`.
  * @throws {TypeError} If invalid arguments were passed.
  */
-function str2ta(str, typeClass=Uint8Array) 
-{
+function str2ta(str, typeClass = Uint8Array) {
   let valid = {
     str: (typeof str === 'string'),
     typeClass: (TypedArray.isPrototypeOf(typeClass)),
   }
   if (!valid.str || !valid.typeClass) {
-    console.error('str2ab valid:', valid, 'values: ', {str, typeClass});
+    console.error('str2ab valid:', valid, 'values: ', { str, typeClass });
     throw new TypeError("invalid arguments");
   }
 
-  let buf = new ArrayBuffer(str.length*typeClass.BYTES_PER_ELEMENT);
+  let buf = new ArrayBuffer(str.length * typeClass.BYTES_PER_ELEMENT);
   let bufView = new typeClass(buf);
-  for (let i = 0, strLen = str.length; i < strLen; i++) 
-  {
+  for (let i = 0, strLen = str.length; i < strLen; i++) {
     bufView[i] = str.charCodeAt(i);
   }
 

package/package.json

@@ -1,17 +1,23 @@
 {
   "name": "@lumjs/encode",
-  "version": "2.4.1",
+  "version": "2.5.0",
   "main": "lib/index.js",
   "exports":
   {
     ".": "./lib/index.js",
+    "./all": "./lib/sets/all.js",
+    "./base": "./lib/sets/base.js",
     "./base32": "./lib/base32.js",
     "./base64": "./lib/base64.js",
     "./base91": "./lib/base91.js",
+    "./digest": "./lib/sets/digest.js",
     "./hash": "./lib/hash.js",
     "./hmac": "./lib/hmac.js",
     "./hotp": "./lib/hotp.js",
+    "./otp": "./lib/sets/otp.js",
     "./pem": "./lib/pem.js",
+    "./polyfill": "./lib/polyfill.js",
+    "./sign": "./lib/sets/sign.js",
     "./signature": "./lib/signature.js",
     "./totp": "./lib/totp.js",
     "./util": "./lib/util.js",