@lumjs/encode 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0] - 2022-09-30
+### Added
+- Initial release.
+
+[Unreleased]: https://github.com/supernovus/lum.encode.js/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/supernovus/lum.encode.js/releases/tag/v1.0.0
+

package/README.md

@@ -0,0 +1,18 @@
+# lum.encode.js
+
+A bunch of encoding libraries.
+
+## Official URLs
+
+This library can be found in two places:
+
+ * [Github](https://github.com/supernovus/lum.encode.js)
+ * [NPM](https://www.npmjs.com/package/@lumjs/encode)
+
+## Author
+
+Timothy Totten <2010@totten.ca>
+
+## License
+
+[MIT](https://spdx.org/licenses/MIT.html)

package/TODO.md

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

package/jsdoc.json

@@ -0,0 +1,33 @@
+{
+  "tags": 
+  {
+    "allowUnknownTags": true
+  },
+  "source":
+  {
+    "include": ["./lib"]
+  },
+  "opts": 
+  {
+    "destination": "./docs/api",
+    "recurse": true
+  },
+  "plugins": 
+  [
+    "plugins/markdown"
+  ],
+  "templates": 
+  {
+    "cleverLinks": false,
+    "monospaceLinks": false,
+    "default": 
+    {
+      "outputSourceFiles": true
+    },
+    "path": "ink-docstrap",
+    "theme": "cerulean",
+    "navType": "vertical",
+    "linenums": true,
+    "dateFormat": "YYYY-MM-DD, hh:mm:ss"
+  }
+}

package/lib/base64.js

@@ -0,0 +1,55 @@
+
+const {S,isObj} = require('@lumjs/core/types');
+const Base64 = require('crypto-js/enc-base64');
+const Utf8 = require('crypto-js/enc-utf8');
+
+/**
+ * Base64 functions.
+ * 
+ * Provides friendlier wrappers around the `crypto-js` libraries.
+ * 
+ * @module @lumjs/encode/base64
+ */
+
+/**
+ * Encode data as a `Base64` string.
+ *
+ * @param {(string|WordArray)} rawdata - The data we want to encode.
+ * 
+ * If this is a `string` we'll convert it into a `WordArray` using
+ * the `stringFormat` object.
+ * 
+ * @param {object} [stringFormat=Utf8] The string format.
+ * 
+ * Can be any encoding module from the `crypto-js` library.
+ * Default is `CryptoJS.enc.Utf8`
+ *
+ * @return {string} The encoded string.
+ */
+exports.encode = function(rawdata, stringFormat=Utf8)
+{
+  const data = typeof rawdata === S ? stringFormat.parse(rawdata) : rawdata;
+  return Base64.stringify(data);
+}
+
+/**
+ * Decode a `Base64` string back into raw data.
+ *
+ * @param {string} string - The Base64 string to decode.
+ * 
+ * @param {(object|false)} [stringFormat=Utf8] The string format.
+ * 
+ * Can be any encoder library from the `crypto-js` library.
+ * Default is `CryptoJS.enc.Utf8`
+ * 
+ * If this is `false`, we'll return a `WordArray` object.
+ *
+ * @return {(string|WordArray))} The decoded output.
+ */
+exports.decode = function(string, stringFormat=Utf8)
+{
+  const data = Base64.parse(string);
+  return (isObj(stringFormat) ? data.toString(stringFormat) : data);
+}
+
+exports.Utf8 = Utf8;

package/lib/base91.js

@@ -0,0 +1,190 @@
+const {S,U,B} = require('@lumjs/core/types');
+
+/**
+ * A pure-Javascript base91 library.
+ * 
+ * Based off a combination of the `mscdex` and `deno` versions.
+ * 
+ * @module @lumjs/encode/base91
+ */
+
+const lookup = [];
+const revLookup = [];
+const code =
+  'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789!#$%&()*+,./:;<=>?@[]^_`{|}~"';
+
+for (let i = 0, len = code.length; i < len; ++i) 
+{
+  lookup[i] = code[i];
+  revLookup[code.charCodeAt(i)] = i;
+}
+
+/**
+ * Encode data to base91
+ * 
+ * @param {*} data - Data to encode
+ * 
+ * May be a string of raw data, a typed array,
+ * an ArrayBuffer, or just an array of bytes.
+ * 
+ * @returns {string} The base91 string.
+ */
+exports.encode = function(data)
+{
+  let output = '';
+  let len = data.length,
+    isStr = (typeof data === S),
+    queue = 0,
+    numbits = 0,
+    value = 0;
+
+  for (let i = 0; i < len; i++)
+  {
+    if (isStr)
+    {
+      let byte = data.charCodeAt(i);
+      let lenj = (byte < 128
+        ? 1
+        : (byte > 127 && byte < 2048
+            ? 2
+            : 3));
+      for (let j = 0; j < lenj; ++j)
+      {
+        if (lenj === 1)
+        {
+          queue |= byte << numbits;
+        }
+        else if (lenj === 2)
+        {
+          if (j === 0)
+            queue |= ((byte >> 6) | 192) << numbits;
+          else
+            queue |= ((byte & 63) | 128) << numbits;
+        }
+        else 
+        {
+          if (j === 0)
+            queue |= ((byte >> 12) | 224) << numbits;
+          else if (j === 1)
+            queue |= (((byte >> 6) & 63) | 128) << numbits;
+          else 
+            queue |= ((byte & 63) | 128) << numbits;
+        }
+      }
+    }
+    else 
+    {
+      queue |= (data[i] & 255) << numbits;
+    }
+    numbits += 8;
+    if (numbits >= 13)
+    {
+      value = queue & 8191;
+      if (value > 88)
+      {
+        queue >>= 13;
+        numbits -= 13;
+      }
+      else 
+      {
+        value = queue & 16383;
+        queue >>= 14;
+        numbits -= 14;
+      }
+      output += lookup[value % 91];
+      output += lookup[Math.trunc(value / 91)];
+    }
+  }
+  if (numbits > 0)
+  {
+    output += lookup[queue % 91];
+    if (numbits > 7 || queue > 90)
+    {
+      output += lookup[Math.trunc(queue / 91)];
+    }
+  }
+
+  return output;
+}
+
+/**
+ * Decode a base91 value back to its original bytes.
+ * 
+ * @param {string} data - The base91 data.
+ * 
+ * May also be an array of bytes.
+ *  
+ * @param {(object|boolean)} [opts] Options
+ * 
+ * If this is a `boolean` it's a shortcut to `opts.string`.
+ * 
+ * @param {boolean} [opts.string=false] Return a String.
+ * @param {boolean} [opts.uint=false] Return a Uint8Array.
+ * @param {boolean} [opts.buffer=false] Return a `Buffer`.
+ *
+ * @returns {mixed} Output depends on options.
+ * 
+ * By default it's a simple Javascript array of raw byte values.
+ * 
+ */
+exports.decode = function(data, opts={})
+{
+  const output = [];
+  let len = data.length,
+    isStr = (typeof data === S),
+    queue = 0,
+    numbits = 0,
+    value = -1,
+    byte = 0;
+
+  for (let i = 0; i < len; i++)
+  {
+    byte = revLookup[isStr ? data.charCodeAt(i) : data[i]];
+    if (byte === undefined) continue;
+    if (value == -1)
+    {
+      value = byte;
+    }
+    else 
+    {
+      value += byte * 91;
+      queue |= value << numbits;
+      numbits += (value & 8191) > 88 ? 13 : 14;
+      do 
+      {
+        output.push(queue);
+        queue >>= 8;
+        numbits -= 8;
+      } while (numbits > 7);
+      value = -1;
+    }
+  }
+  if (value != -1)
+  {
+    output.push(queue | (value << numbits));
+  }
+
+  if (typeof opts === B)
+  {
+    opts = {string: opts};
+  }
+
+  if (opts.string && typeof Uint8Array !== U && typeof TextDecoder !== U)
+  {
+    const uint = Uint8Array.from(output);
+    const td = new TextDecoder();
+    return td.decode(uint);
+  }
+  if (opts.uint && typeof Uint8Array !== U)
+  {
+    return Uint8Array.from(output);
+  }
+  else if (opts.buffer && typeof Buffer !== U)
+  {
+    return new Buffer.from(output);
+  }
+  else 
+  {
+    return output;
+  }
+}

package/lib/crypto/index.js

@@ -0,0 +1,171 @@
+/**
+ * Crypto-JS helpers.
+ * 
+ * Uses a lot of magic proxy abilities.
+ * Look at the `test/020-crypto.js` for examples.
+ * 
+ * The top-level properties are *case-sensitive*, as
+ * is standard in Javascript. In some cases this means
+ * there are two names that differ only in case, such as
+ * `crypto.hash` (a proxy object returning hashing functions)
+ * versus `crypto.HASH` (a proxy object returning object instaces). 
+ * 
+ * The child properties of any *proxy object* properties
+ * are *case-insensitive*. So `crypto.hash.sha256` is the
+ * same as `crypto.hash.SHA256`.
+ * 
+ * @module @lumjs/encode/crypto
+ */
+const {def} = require('@lumjs/core/types');
+
+/**
+ * A link to the `crypto-js/core` library.
+ * 
+ * This corresponds to the `CryptoJS` global in the original
+ * implementation, and is used by all the other modules
+ * in the `crypto-js` collection.
+ * 
+ * @alias module:@lumjs/encode/crypto.core
+ */
+const cc = require('crypto-js/core');
+exports.core = cc;
+
+/**
+ * A link to the `crypto-js/core.lib.WordArray` library.
+ * 
+ * We always load the `lib-typedarray` plugin that allows
+ * conversion from `WordArray` objects.
+ */
+exports.WordArray = require('crypto-js/lib-typedarrays');
+
+/**
+ * Our custom module loader.
+ * 
+ * Can be used as a `function` itself, but generally one of the
+ * child methods is a lot simpler, and works around weird
+ * gotchyas in the `crypto-js` library.
+ * 
+ * All of the *proxy objects* use this as the underlying
+ * target object, and each of them corresponds to one of
+ * the methods from this.
+ * 
+ * @see {@link module:@lumjs/encode/crypto/load}
+ * @see {@link module:@lumjs/encode/crypto/load.load}
+ */
+exports.load = require('./load');
+
+// A list of loader properties to *not* make proxies for.
+const NO_LOAD = ['load'];
+
+// Make proxy objects for the loader properties.
+for (const loader in exports.load)
+{ 
+  if (NO_LOAD.includes(loader)) continue;
+  exports[loader] = new Proxy(exports.load, 
+  {
+    get(load, lib)
+    {
+      return load[loader](lib);
+    }
+  });
+}
+
+/**
+ * A proxy object for building a progressive hashing instance.
+ * 
+ * Any property of this should be the name of a *Hash algorithm*.
+ * 
+ * Each property is a `function` which takes an optional `object` 
+ * parameter called `options`, and will call `load.hash(algorithm, options)`,
+ * which will return a progressive hashing instance.
+ * 
+ * For a non-progressive hashing function, use the lowercase
+ * [hash]{@link module:@lumjs/encode/crypto.hash} property instead.
+ */
+exports.HASH = new Proxy(exports.load,
+{
+  get(load, lib)
+  {
+    return (options => load.hash(lib, options ?? {}));
+  }
+});
+
+/**
+ * A proxy object for building a progressive **HMAC** hashing instance.
+ * 
+ * Any property of this should be the name of a *Hash algorithm*.
+ * 
+ * Each property is a `function` which takes a mandatory `string` 
+ * parameter called `secret`, and will call `load.hmac(algorithm, secret)`,
+ * which will return a progressive HMAC hashing instance.
+ * 
+ * For a non-progressive HMAC hashing function, use the lowercase
+ * [hmac]{@link module:@lumjs/encode/crypto.hmac} property instead.
+ */
+exports.HMAC = new Proxy(exports.load,
+{
+  get(load, lib)
+  {
+    return (secret => load.hmac(lib, secret));
+  }
+});
+
+/**
+ * A proxy object for loading Hashing functions.
+ * 
+ * Any property of this should be the name of a *Hash algorithm*,
+ * and the property will return the corresponding hashing function.
+ * 
+ * For a progressive hashing instance, use the uppercase
+ * [HASH]{@link module:@lumjs/encode/crypto.HASH} property instead.
+ *
+ * @name module:@lumjs/encode/crypto.hash
+ */
+
+/**
+ * A proxy object for loading HMAC hashing functions.
+ * 
+ * Any property of this should be the name of a *Hash algorithm*,
+ * and the property will return the corresponding HMAC hashing function.
+ * 
+ * For a progressive HMAC hashing instance, use the uppercase
+ * [HMAC]{@link module:@lumjs/encode/crypto.HMAC} property instead.
+ * 
+ * @name module:@lumjs/encode/crypto.hmac
+ */
+
+/**
+ * A proxy object for loading Cipher libraries.
+ *
+ * @name module:@lumjs/encode/crypto.cipher
+ */
+
+/**
+ * A proxy object for loading Algorithm libraries.
+ *
+ * @name module:@lumjs/encode/crypto.algo
+ */
+
+/**
+ * A proxy object for loading Encoding libraries.
+ *
+ * @name module:@lumjs/encode/crypto.enc
+ */
+
+/**
+ * A proxy object for loading Padding plugins.
+ *
+ * @name module:@lumjs/encode/crypto.pad
+ */
+
+/**
+ * A proxy object for loading Mode plugins.
+ *
+ * @name module:@lumjs/encode/crypto.mode
+ */
+
+/**
+ * A proxy object for loading Format plugins.
+ *
+ * @name module:@lumjs/encode/crypto.format
+ */