@lumjs/encode 2.4.1 → 2.6.0

package/CHANGELOG.md

@@ -6,6 +6,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.6.0] - 2026-02-24
+
+
+## [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 +109,9 @@ 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.6.0...HEAD
+[2.6.0]: https://github.com/supernovus/lum.encode.js/compare/v2.5.0...v2.6.0
+[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/jsdoc.js

@@ -0,0 +1,6 @@
+"use strict";
+
+const docRules = require('@lumjs/build/jsdoc-rules');
+const ourRules = docRules.rootReadme.clone(); 
+
+module.exports = ourRules;

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/hash.js

@@ -55,7 +55,7 @@ const DATA_ENCODERS =
  * 
  * @exports module:@lumjs/encode/hash
  */
-module.exports = class
+module.exports = class Hashifier
 {
   /**
    * Build a new Hashifier

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 {