@lumjs/encode 1.1.0 → 2.0.0

package/lib/hash.js

@@ -1,18 +1,50 @@
 const {S,F,isObj,isNil} = require('@lumjs/core/types');
 
 const util   = require('./util');
-const Base91 = require('./base91');
-const Safe64 = require('./safe64');
-const Crypto = require('./crypto');
-const cload  = Crypto.load;
+const base64 = require('./base64');
+const base91 = require('./base91');
 
-const DEFALGO = 'SHA256';
+const D_ALGO     = 'SHA-256';
+const D_ADD_ENC  = 'base64';
+const D_TIMEOUT  = 10000;
+const D_TRY_TIME = 100;
+
+const ALGO_ALIASES = 
+{
+  SHA1:   'SHA-1',
+  SHA256: 'SHA-256',
+  SHA384: 'SHA-384',
+  SHA512: 'SHA-512',
+}
+
+const ALGO_INFO =
+{
+  'SHA-1':   {length: 160, block: 512},
+  'SHA-256': {length: 256, block: 512},
+  'SHA-384': {length: 384, block: 1024},
+  'SHA-512': {length: 512, block: 1024},
+}
+
+const DATA_ENCODERS = 
+{
+  base64, base91,
+};
+
+/**
+ * Algorithm info object
+ * @typedef {object} module:@lumjs/encode/hash~Algo
+ * @property {string} id     - The formal id/name of the algorithm
+ * @property {number} length - The output length (in bits)
+ * @property {number} block  - The block size (in bits)
+ */
 
 /**
- * Hashifier
- * 
  * A simple yet flexible class for building cryptographic hashes.
  * 
+ * @property {module:@lumjs/encode/hash~Algo} algo - Digest algorithm in use
+ * @property {object} current - Progressive digest generation data (internal)
+ * @property {object} defaults - Default options for various methods.
+ * 
  * @exports module:@lumjs/encode/hash
  */
 module.exports = class
@@ -24,23 +56,69 @@ module.exports = class
    * 
    * If this is a `string`, it's assumed to be the `options.algo` option.
    * 
-   * @param {string} [options.algo="SHA256"] Hashing algorithm
+   * @param {string} [options.algo="SHA-256"] Digest (hash) algorithm
    *
-   * By default we use "SHA256" for backwards compatibility with my
-   * older libraries and apps. You can set it to any *hashing algorithm*
-   * from the `crypto-js` library (we use our own 
-   * [crypto]{@link module:@lumjs/encode/crypto} helper.)
+   * By default we use `SHA-256` for backwards compatibility with my
+   * older libraries and apps. You can set it to any *digest algorithm*
+   * supported by the `SubtleCrypto` API.
    * 
-   * @param {object} [options.safe64] Default options for `safe64()`
+   * We look up the algorithm with 
+   * [getAlgorithm()]{@link module:@lumjs/encode/hash#getAlgorithm},
+   * and so support hyphenless aliases and case-insensitive ids.
+   * 
+   * For more information on supported digest algorithms, see:
+   * https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/digest
+   * 
+   * @param {object} [options.base64] Default options for `base64()`
    * 
    * If specified, this will become the default options for the
-   * [safe64()]{@link module:@lumjs/encode/hash#safe64} method.
+   * [base64()]{@link module:@lumjs/encode/hash#base64} method.
    * 
    * @param {object} [options.base91] Default options for `base91()`
    * 
    * If specified, this will become the default options for the
-   * [base91()]{@link module:@lumjs/encode/hash#base9164} method.
+   * [base91()]{@link module:@lumjs/encode/hash#base91} method.
+   * 
+   * @param {(string|function|object)} [options.addUsing="base64"]
+   * Encoder for `add()` to use when non-string values are passed.
+   * 
+   * If this is a `string`, it may be either `"base64"` or `"base91"`.
+   * 
+   * If it is a `function`, it will be sent the data value and must
+   * return an encoded string representation of that value.
+   * 
+   * If this is an `object`, it must have a method called `encode()`
+   * that works the same way as if you'd passed a `function`.
    *
+   * @param {(string|function)} [options.joinWith=""]
+   * What `hash()` will use to join progressive data values.
+   * 
+   * If this is a `string` the array of data values will be joined
+   * using the `array.join()` method.
+   * 
+   * If it is a `function`, it will be sent the array of values,
+   * and must return an encoded representation of those values
+   * having been joined together in some fashion.
+   * 
+   * The default value is an empty string, which means the data
+   * values are simply concatenated together with no separator.
+   * 
+   * @param {number} [options.timeout=10000] Timeout for async encoding
+   * 
+   * This is how long `hash()` will wait for async encoding to finish
+   * before throwing an error indicating something went wrong.
+   * 
+   * Value is in milliseconds.
+   * 
+   * @param {number} [options.tryEvery=100] Interval to test async encoding
+   * 
+   * If async encoding is ongoing, this is the interval `hash()` will
+   * test to see if encoding has finished.
+   * 
+   * Value is in milliseconds.
+   * 
+   * @throws {Error} If `options.algo` was an invalid algorithm.
+   * 
    */
   constructor(options={})
   {
@@ -49,22 +127,67 @@ module.exports = class
       options = {algo: options};
     }
 
-    const algo = options.algo ?? DEFALGO;
+    this.options = options;
 
-    this.algoLib = cload.algo(algo);
-    this.hashFunction = cload.hash(algo);
+    this.current =
+    {
+      queue: 0,
+      hash: [],
+      encoder: options.addUsing ?? D_ADD_ENC,
+      joiner:  options.joinWith ?? '',
+    }
 
-    //console.debug("<hash>", {hash: this, algo, options});
+    this.algo = this.getAlgorithm(
+      (typeof options.algo === S) 
+      ? options.algo
+      : D_ALGO);
 
-    if (!isObj(this.algoLib) || typeof this.hashFunction !== F)
+    if (this.algo === null)
     {
-      throw new Error("Invalid hashing algorithm");
+      throw new Error("Invalid 'algo' specified: "+options.algo);
     }
 
-    this.safe64Options = options.safe64 ?? {};
-    this.base91Options = options.base91 ?? {};
+    this.defaults =
+    {
+      base64: options.base64 ?? {},
+      base91: options.base91 ?? {},
+    }
 
-  } // construct()
+    this.timeout  = options.timeout  ?? D_TIMEOUT;
+    this.tryEvery = options.tryEvery ?? D_TRY_TIME;
+
+  } // construct
+
+  /**
+   * Lookup a hashing algorithm and return details about it
+   * 
+   * @param {string} id - The name of the algorithm.
+   * 
+   * It's case-insensitive (will be forced to uppercase),
+   * and you may omit the hyphen in the algorithm name.
+   * Thus `sha256` is the same as `SHA-256`.
+   * 
+   * @returns {?module:@lumjs/encode/hash~Algo}
+   * Will be an Algo info object if the `id` was valid,
+   * or `null` otherwise.
+   */
+  getAlgorithm(id)
+  {
+    id = id.toString().toUpperCase();
+
+    if (id in ALGO_ALIASES)
+    {
+      id = ALGO_ALIASES[id];
+    }
+
+    if (id in ALGO_INFO)
+    {
+      return Object.assign({id}, ALGO_INFO[id]);
+    }
+
+    // Invalid algorithm id, nothing to return.
+    return null;
+  }
 
   /**
    * Get a cryptographic *hash*.
@@ -74,120 +197,118 @@ module.exports = class
    * Otherwise, if there is a current *progressive hash* in the process of
    * being built, it will be *finalized* and returned.
    *
-   * This will return `undefined` if there is no valid data to be hashed.
-   *
-   * @param {(string|WordArray)} [input] Input to hash immediately.
+   * @param {(string|object)} [input] Input to hash immediately
    *
-   * @return {WordArray|undefined}
+   * @return {Promise<ArrayBuffer>} See `SubtleCrypto.digest()` for details.
+   * 
+   * @throws {TypeError} If the `options.joinWith` value is invalid,
+   * and no `input` was passed.
+   * 
    */
-  hash(input)
+  async hash(input)
   {
     if (isNil(input))
     { // No input, let's see if we have a progrssive hash being built.
-      if (typeof this.currentHash === 'object')
-      { // Let's return the finalized hash.
-        let value = this.currentHash.finalize();
-        delete this.currentHash;
-        return value;
+      if (this.current.queue !== 0)
+      { // We need to wait for some asynchronous encoding to finish.
+        return new Promise((resolve, reject) =>
+        {
+          const timeout = setTimeout(() =>
+          {
+            clearInterval(test);
+            clearTimeout(timeout);
+            reject(new Error("Timed out waiting for async encoding"));
+          }, this.timeout);
+    
+          const test = setInterval(() =>
+          {
+            if (this.current.queue === 0)
+            {
+              clearInterval(test);
+              clearTimeout(timeout);
+              resolve(this.hash(input));
+            }
+          }, this.tryEvery);
+        });
+      }
+
+      const joiner = this.current.joiner;
+
+      if (typeof joiner === F)
+      {
+        input = joiner.call(this, this.current.hash);
       }
+      else if (typeof joiner === S)
+      {
+        input = this.current.hash.join(joiner);
+      }
+      else
+      {
+        console.error({joiner, input, hashifier: this});
+        throw new TypeError("Invalid 'joinWith' value");
+      }
+
+      // Now clear the current hash values.
+      this.current.hash.length = 0;
     }
-    else if (typeof input === 'string' || this.valid(hash))
-    { // Input data was passed, let's hash it now.
-      return this.hashFunction(input);
+
+    if (typeof input === S)
+    { // This is super simple.
+      const encoder = new TextEncoder();
+      input = encoder.encode(input);
     }
-  }
+    else if (input instanceof Blob)
+    { // As is this.
+      input = await input.arrayBuffer();
+    }
+
+    //console.debug({algo: this.algo, input});
 
-  // Not really a useful public method.
-  valid(hash)
-  { // WordArray is not a standard object and doesn't work with instanceof.
-    return (isObj(hash) && typeof hash.toString === 'function');
+    return crypto.subtle.digest(this.algo.id, input);
   }
 
   /**
    * Get hash as a Hex string.
    *
-   * @param {(string|WordArray)} [input] 
-   * See [hash()]{@link module:@lumjs/encode/hash#hash}
-   * @returns {string}
+   * @param {(string|object|null)} [input]
+   * See [hash()]{@link module:@lumjs/encode/hash#hash} for details.
    * 
-   * This uses the default `Hex` encoder from `crypto-js` to perform
-   * the hashing, so output is directly as if you'd used that library.
+   * @returns {string}
    */
-  hex(input)
+  async hex(input)
   {
-    const hash = this.hash(input);
-    if (this.valid(hash)) return hash.toString();
+    const hashBuf = await this.hash(input);
+    const hashArr = Array.from(new Uint8Array(hashBuf));
+    return (hashArr.map((b)=>b.toString(16).padStart(2, "0")).join(""));
   }
 
   /**
    * Get hash as a Base64-encoded string.
    *
-   * @param {(string|WordArray)} [input] 
-   * See [hash()]{@link module:@lumjs/encode/hash#hash}
-   * @returns {string}
+   * @param {(string|object|null)} [input]
+   * See [hash()]{@link module:@lumjs/encode/hash#hash} for details.
    * 
-   * This uses the direct `Base64` encoder from `crypto-js` to perform
-   * the hashing, so output is directly as if you'd used that library.
-   */
-  base64(input)
-  {
-    const hash = this.hash(input);
-    const base64 = Crypto.enc.Base64;
-    if (this.valid(hash)) return hash.toString(base64);
-  }
-
-  /**
-   * Get hash as a Safe64-encoded string.
-   * 
-   * Calls [base64()]{@link module:@lumjs/encode/hash#base64},
-   * then passes the output from that to
-   * [urlize()]{@link module:@lumjs/encode/safe64.urlize} to
-   * convert into the *Safe64* format.
-   *
-   * @param {(string|WordArray)} [input] 
-   * See [hash()]{@link module:@lumjs/encode/hash#hash}
-   * @param {object} [opts]
-   * Options for `urlize()`.
-   * @returns {string}
+   * @param {object} [options] Options for Base64 encoding
    * 
-   * By default it's a raw *Safe64* string with **no** header,
-   * and **no** tildes. The `opts` passed can change the format
-   * by enabling *tildes* or adding a *header*.
+   * @param {boolean} [options.url=false] Use URL-safe variant?
    * 
+   * @returns {string}
    */
-  safe64(input, opts={})
+  async base64(input, opts=this.defaults.base64)
   {
-    let base64 = this.base64(input); 
-    if (base64)
-      return Safe64.urlize(base64, opts);
+    const hash = await this.hash(input);
+    const b64str = base64.fromBytes(new Uint8Array(hash));
+    return opts.url ? base64.urlize(b64str) : b64str;
   }
 
   /**
    * Get hash as a Base91-encoded string.
    * 
-   * The `crypto-js` library set currently does not natively support
-   * the `base91` encoding format.
-   * 
-   * So this offers a few different ways to encode `crypto-js` hashes
-   * in `base91` format using our own 
-   * [base91]{@link module:@lumjs/encode/base91} module.
-   *
    * @param {(string|WordArray)} [input] 
    * See [hash()]{@link module:@lumjs/encode/hash#hash}
    * @param {object} [opts] Options for how to encode the hash.
-   * @param {boolean} [opts.words=false] Use `hash.words`?
-   * 
-   * If this is `true`, we will pass the `hash.words` array to
-   * the `base91.encode()` method to encode them.
    * 
-   * If this is true, then `opts.enc` and `opts.nba` are ignored.
-   * 
-   * @param {object} [opts.enc] The `crypto-js` encoder.
-   * 
-   * That can be any of the `crypto.enc.*` plugins.
-   * If not specified, the default `Hex` encoding format will be used.
-   * 
-   * @param {(boolean|object)} [opts.nba=true] Use `numByteArray()` ?
+   * @param {(boolean|object)} [opts.nba=false] Use `numByteArray()` ?
    * 
    * If this is `true` the *hash string* will be passed to `numByteArray()`
    * with the *default options* and the output from that will be passed to 
@@ -196,42 +317,90 @@ module.exports = class
    * If this is an `object`, then the same logic as `true` applies, except this
    * will be used as the *explicit options* for the `numByteArray()` method.
    * 
-   * If this is `false` the *hash string* itself will be passed directly to
-   * `base91.encode()` without further encoding.
-   * 
-   * The default value of `true` is provided for backwards compatibility with
-   * the previous version of this library which did not have as many options.
+   * If this is `false` the `ArrayBffer` will be converted into a `Uint8Array`,
+   * and that will be passed to `base91.encode()`.
    * 
    * @returns {string}
    */
-  base91(input, opts={})
+  async base91(input, opts=this.defaults.base91)
   {
-    let hash = this.hash(input);
-    if (this.valid(hash)) 
-      return Base91.encode(util.numByteArray(hash.toString()))
+    const nba = isObj(opts.nba) ? opts.nba : (opts.nba === true ? {} : null);
+
+    let hash = await (nba ? this.hex(input) : this.hash(input));
+
+    if (nba)
+    {
+      hash = util.numByteArray(hash);
+    }
+
+    return base91.encode(new Uint8Array(hash));
   }
 
   /**
    * Add input to a progressive hash.
    *
-   * If there is not already a progressive hash being built, we will
-   * create one automatically. Use the `hash()` method with no parameter
-   * to retrieve the finalized hash as a `WordArray` object, or one of
-   * the other convenience methods to return it in a specific string
-   * format.
-   *
-   * @param {string|WordArray} input  A value to add to the hash.
+   * @param {(string|object)} input - A value to add to the hash.
+   * 
+   * If it is an `object` then it will be processed with the `addWith`
+   * handler. See the constructor for details on supported formats.
+   * 
+   * String values are simply added _as-is_.
    *
-   * @return Lum.Hashifier  The current object.
+   * @return {object} `this`
    */
-  add(input)
+  add(input, opts={})
   {
-    if (!isObj(this.currentHash))
-    { // We need to start a new hash.
-      this.currentHash = this.algoLib.create();
+    if (typeof input !== S)
+    {
+      let enc   = this.current.encoder, 
+          eopts = null;
+
+      if (typeof enc === S)
+      {
+        enc = DATA_ENCODERS[enc];
+        eopts = this.defaults[enc];
+      }
+
+      // Compile the options for the encoder.
+      eopts = Object.assign({hashifier: this}, eopts, opts);
+
+      if (typeof enc === F)
+      { // Call the function, using the hashifier instance as `this`.
+        input = enc.call(this, input, eopts);
+      }
+      else if (isObj(enc) && typeof enc.encode === F)
+      { // Using an encoder object/instance.
+        input = enc.encode(input, eopts);
+      }
+      else
+      {
+        console.error({enc, input, opts, hashifier: this});
+        throw new TypeError("Invalid 'addUsing' value");
+      }
     }
 
-    this.currentHash.update(input);
+    let pos = this.current.hash.length + this.current.queue;
+
+    if (input instanceof Promise)
+    {
+      this.current.queue++;
+
+      input.then((data) =>
+      {
+        this.current.hash[pos] = data;
+        this.current.queue--;
+      }).catch((err) =>
+      {
+        console.error("An error occurred encoding data", err);
+        this.current.hash[pos] = '';
+        this.current.queue--;
+      });
+
+    }
+    else
+    {
+      this.current.hash[pos] = input;
+    }
     
     return this;
   }

package/lib/index.js

@@ -3,47 +3,39 @@
  * @module @lumjs/encode
  */
 
-const {can,from} = require('@lumjs/core').buildModule(module);
+const {def,lazy} = require('@lumjs/core/types');
+
+const E = def.e;
+
+const util = require('./util');
 
 /**
- * @name module:@lumjs/encode.ord
- * @function
+ * @alias module:@lumjs/encode.ord
  * @see {@link module:@lumjs/encode/util.ord}
  */
+def(exports, 'ord', util.ord, E);
 
 /**
  * @name module:@lumjs/encode.numByteArray
  * @function
  * @see {@link module:@lumjs/encode/util.numByteArray}
  */
-from('./util', 'ord', 'numByteArray');
+def(exports, 'numByteArray', util.numByteArray, E);
 
 /**
  * @name module:@lumjs/encode.Base64
  * @see {@link module:@lumjs/encode/base64}
  */
-can('Base64', true);
+lazy(exports, 'Base64', () => require('./base64'), E);
 
 /**
  * @name module:@lumjs/encode.Base91
  * @see {@link module:@lumjs/encode/base91}
  */
-can('Base91', true);
-
-/**
- * @name module:@lumjs/encode.Safe64
- * @see {@link module:@lumjs/encode/safe64}
- */
-can('Safe64', true);
+lazy(exports, 'Base91', () => require('./base91'), E);
 
 /**
  * @name module:@lumjs/encode.Hash
  * @see {@link module:@lumjs/encode/hash}
  */
-can('Hash', true);
-
-/**
- * @name module:@lumjs/encode.Crypto
- * @see {@link module:@lumjs/encode/crypto}
- */
-can('Crypto', true);
+lazy(exports, 'Hash', () => require('./hash'), E);

package/lib/util.js

@@ -69,6 +69,7 @@ exports.ord = function (string)
  * 
  * @param {number} [options.base=16] The numeric base for the string.
  * 
+ * The valid range is between `2` and `36`.
  * This defaults to `16` which is Hexadecimal.
  * 
  * @param {boolean} [options.strict=false] Do not allow indivisible strings

package/package.json

@@ -1,17 +1,13 @@
 {
   "name": "@lumjs/encode",
-  "version": "1.1.0",
+  "version": "2.0.0",
   "main": "lib/index.js",
   "exports":
   {
     ".": "./lib/index.js",
     "./base64": "./lib/base64.js",
     "./base91": "./lib/base91.js",
-    "./crypto": "./lib/crypto/index.js",
-    "./crypto/load": "./lib/crypto/load.js",
     "./hash": "./lib/hash.js",
-    "./safe64": "./lib/safe64/index.js",
-    "./safe64/header": "./lib/safe64/header.js",
     "./util": "./lib/util.js",
     "./package.json": "./package.json"
   },
@@ -21,15 +17,13 @@
     "type": "git",
     "url": "https://github.com/supernovus/lum.encode.js.git"
   },
-  "dependencies": {
-    "@lumjs/core": "^1.7.1",
-    "crypto-js": "^4.1.1",
-    "php-serialize": "^4.0.2",
-    "@shelacek/ubjson": "^1.1.1"
+  "dependencies": 
+  {
+    "@lumjs/core": "^1.26.0"
   },
   "devDependencies":
   {
-    "@lumjs/tests": "^1.7.0"
+    "@lumjs/tests": "^2.0.0"
   },
   "scripts":
   {

package/TODO.md

@@ -1,3 +0,0 @@
-# TODO
-
-- Nothing on the current list.