@karmaniverous/entity-manager 0.0.8

package/dist/default/lib/EntityManager/PrivateEntityManager.js

@@ -0,0 +1,408 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.PrivateEntityManager = void 0;
+var _isInteger2 = _interopRequireDefault(require("lodash/isInteger"));
+var _isPlainObject2 = _interopRequireDefault(require("lodash/isPlainObject"));
+var _range2 = _interopRequireDefault(require("lodash/range"));
+var _flatten2 = _interopRequireDefault(require("lodash/flatten"));
+var _filter2 = _interopRequireDefault(require("lodash/filter"));
+var _size2 = _interopRequireDefault(require("lodash/size"));
+var _findLast2 = _interopRequireDefault(require("lodash/findLast"));
+var _has2 = _interopRequireDefault(require("lodash/has"));
+var _map2 = _interopRequireDefault(require("lodash/map"));
+var _isFunction2 = _interopRequireDefault(require("lodash/isFunction"));
+var _isNil2 = _interopRequireDefault(require("lodash/isNil"));
+var _some2 = _interopRequireDefault(require("lodash/some"));
+var _toPairs2 = _interopRequireDefault(require("lodash/toPairs"));
+var _sortBy2 = _interopRequireDefault(require("lodash/sortBy"));
+var _fromPairs2 = _interopRequireDefault(require("lodash/fromPairs"));
+var _mapValues2 = _interopRequireDefault(require("lodash/mapValues"));
+var _jsonschema = require("jsonschema");
+var _stringHash = _interopRequireDefault(require("string-hash"));
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+function _classPrivateFieldInitSpec(obj, privateMap, value) { _checkPrivateRedeclaration(obj, privateMap); privateMap.set(obj, value); }
+function _checkPrivateRedeclaration(obj, privateCollection) { if (privateCollection.has(obj)) { throw new TypeError("Cannot initialize the same private elements twice on an object"); } }
+function _classPrivateFieldGet(receiver, privateMap) { var descriptor = _classExtractFieldDescriptor(receiver, privateMap, "get"); return _classApplyDescriptorGet(receiver, descriptor); }
+function _classApplyDescriptorGet(receiver, descriptor) { if (descriptor.get) { return descriptor.get.call(receiver); } return descriptor.value; }
+function _classPrivateFieldSet(receiver, privateMap, value) { var descriptor = _classExtractFieldDescriptor(receiver, privateMap, "set"); _classApplyDescriptorSet(receiver, descriptor, value); return value; }
+function _classExtractFieldDescriptor(receiver, privateMap, action) { if (!privateMap.has(receiver)) { throw new TypeError("attempted to " + action + " private field on non-instance"); } return privateMap.get(receiver); }
+function _classApplyDescriptorSet(receiver, descriptor, value) { if (descriptor.set) { descriptor.set.call(receiver, value); } else { if (!descriptor.writable) { throw new TypeError("attempted to set read only private field"); } descriptor.value = value; } }
+/**
+ * EntityManager config validation schema.
+ *
+ * @private
+ */
+const configSchema = {
+  type: 'object',
+  properties: {
+    entities: {
+      type: 'object',
+      patternProperties: {
+        '^\\w+$': {
+          type: 'object',
+          properties: {
+            keys: {
+              type: 'object'
+            },
+            sharding: {
+              type: 'object',
+              properties: {
+                bumps: {
+                  type: 'object',
+                  patternProperties: {
+                    '^\\d+$': {
+                      type: 'integer',
+                      minimum: 0
+                    }
+                  },
+                  additionalProperties: false
+                },
+                entityKey: {
+                  type: 'function'
+                },
+                nibbleBits: {
+                  type: 'integer',
+                  minimum: 1,
+                  maximum: 5
+                },
+                nibbles: {
+                  type: 'integer',
+                  minimum: 0
+                },
+                timestamp: {
+                  type: 'function'
+                }
+              },
+              additionalProperties: false
+            }
+          },
+          additionalProperties: false
+        }
+      },
+      additionalProperties: false
+    },
+    shardKeyToken: {
+      type: 'string',
+      pattern: '^\\w+$'
+    }
+  },
+  additionalProperties: false
+};
+
+/**
+ * Private EntityManager implementation.
+ *
+ * @private
+ */
+var _config = /*#__PURE__*/new WeakMap();
+var _logger = /*#__PURE__*/new WeakMap();
+class PrivateEntityManager {
+  /**
+   * Create a PrivateEntityManager instance.
+   *
+   * @param {object} options - Options object.
+   * @param {object} [options.config] - EntityManager configuration object.
+   * @param {object} [options.logger] - Logger instance (defaults to console, must support error & debug methods).
+   * @throws {Error} If config is invalid.
+   * @throws {Error} If logger is invalid.
+   */
+  constructor() {
+    let {
+      config = {},
+      logger = console
+    } = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+    _classPrivateFieldInitSpec(this, _config, {
+      writable: true,
+      value: void 0
+    });
+    _classPrivateFieldInitSpec(this, _logger, {
+      writable: true,
+      value: void 0
+    });
+    // Validate logger.
+    if (!logger.error || !logger.debug) throw new Error('logger must implement error & debug methods.');
+    _classPrivateFieldSet(this, _logger, logger);
+    this.config = config;
+  }
+
+  /**
+   * Get the current config.
+   *
+   * @returns {object} Current config.
+   */
+  get config() {
+    return _classPrivateFieldGet(this, _config);
+  }
+
+  /**
+   * Set the current config.
+   *
+   * @param {object} value - Config object.
+   * @throws {Error} If config is invalid.
+   * @throws {Error} If entity bumps do not monotonically increase.
+   * @throws {Error} If entity nibbles are greater than minimum bump value.
+   */
+  set config(value) {
+    // Validate config against schema.
+    const validatorResult = (0, _jsonschema.validate)(value, configSchema);
+    if (!validatorResult.valid) {
+      validatorResult.errors.forEach(error => this.logger.error(error.message));
+      throw new Error(validatorResult.errors);
+    }
+
+    // Conform config.
+    const {
+      entities = {},
+      shardKeyToken = 'shardId'
+    } = value;
+    const conformedConfig = {
+      entities: (0, _mapValues2.default)(entities, _ref => {
+        let {
+          keys = {},
+          sharding: {
+            bumps = {},
+            entityKey,
+            nibbleBits = 1,
+            nibbles = 0,
+            timestamp
+          } = {}
+        } = _ref;
+        return {
+          keys,
+          sharding: {
+            bumps: (0, _fromPairs2.default)((0, _sortBy2.default)((0, _toPairs2.default)(bumps), 0)),
+            entityKey,
+            nibbleBits,
+            nibbles,
+            timestamp
+          }
+        };
+      }),
+      shardKeyToken
+    };
+
+    // Validate entity properties.
+    (0, _some2.default)(conformedConfig.entities, (_ref2, entityToken) => {
+      let {
+        keys,
+        sharding: {
+          bumps,
+          entityKey,
+          nibbleBits,
+          nibbles,
+          timestamp
+        }
+      } = _ref2;
+      // Validate entity keys are functions or undefined.
+      (0, _some2.default)(keys, (value, key) => {
+        if (!(0, _isNil2.default)(value) && !(0, _isFunction2.default)(value)) {
+          const message = `${entityToken} key '${key}' must be a function or nil.`;
+          this.logger.error(message);
+          throw new Error(message);
+        } else return false;
+      });
+
+      // Validate sharding bump values increase monotonically with keys.
+      (0, _some2.default)((0, _toPairs2.default)(bumps), (_ref3, i, c) => {
+        let [bump, value] = _ref3;
+        const [lastBump, lastValue] = i ? c[i - 1] : [];
+        if (value <= lastValue) {
+          const message = `${entityToken} sharding bumps do not monotonically increase from '${lastBump}: ${lastValue}' to '${bump}: ${value}'.)`;
+          this.logger.error(message);
+          throw new Error(message);
+        } else return false;
+      });
+
+      // Validate sharding entityKey is a function or undefined.
+      if (!(0, _isNil2.default)(entityKey) && !(0, _isFunction2.default)(entityKey)) {
+        const message = `${entityToken} sharding entityKey must be a function or nil`;
+        this.logger.error(message);
+        throw new Error(message);
+      }
+
+      // Validate sharding nibbles do not exceed 32 bits.
+      if (nibbles * nibbleBits > 32) {
+        const message = `${entityToken} nibbles (${nibbles} nibbles at ${nibbleBits} nibbleBits) exceed 32 bits`;
+        this.logger.error(message);
+        throw new Error(message);
+      }
+
+      // Validate sharding nibbles are less than first bump value.
+      const firstBumpValue = (0, _map2.default)(bumps)[0];
+      if (nibbles >= firstBumpValue) {
+        const message = `${entityToken} nibbles (${nibbles}) not less than minimum bump value (${firstBumpValue})`;
+        this.logger.error(message);
+        throw new Error(message);
+      }
+
+      // Validate last bump value does not exceed 32 bits.
+      const lastBumpValue = (0, _map2.default)(bumps).slice(-1);
+      if (lastBumpValue * nibbleBits > 32) {
+        const message = `${entityToken} maximum bump value (${lastBumpValue} nibbles at ${nibbleBits} nibbleBits) exceed 32 bits`;
+        this.logger.error(message);
+        throw new Error(message);
+      }
+
+      // Validate sharding timestamp is a function or undefined.
+      if (!(0, _isNil2.default)(timestamp) && !(0, _isFunction2.default)(timestamp)) {
+        const message = `${entityToken} sharding timestamp must be a function or nil.`;
+        this.logger.error(message);
+        throw new Error(message);
+      } else return false;
+    });
+    _classPrivateFieldSet(this, _config, conformedConfig);
+  }
+
+  /**
+   * Get logger instance.
+   *
+   * @returns {object} Logger instance.
+   */
+  get logger() {
+    return _classPrivateFieldGet(this, _logger);
+  }
+
+  /**
+   * Get shard key token.
+   *
+   * @returns {string} Shard key token.
+   */
+  get shardKeyToken() {
+    return _classPrivateFieldGet(this, _config).shardKeyToken;
+  }
+
+  /**
+   * Get entity config.
+   *
+   * @param {string} entityToken - Entity token.
+   * @returns {object} Entity config.
+   * @throws {Error} If entityToken is invalid.
+   */
+  getEntityConfig(entityToken) {
+    this.validateEntityToken(entityToken);
+    return this.config.entities[entityToken];
+  }
+  getKeyGenerator(entityToken, keyToken) {
+    const {
+      keys
+    } = this.getEntityConfig(entityToken);
+    if (!(0, _has2.default)(keys, keyToken)) {
+      const message = `Key '${keyToken}' does not exist for entity '${entityToken}'.`;
+      this.logger.error(message);
+      throw new Error(message);
+    }
+    return keys[keyToken];
+  }
+
+  /**
+   * Get the number of nibbles & nibbleBits for a given entityToken at a given timestamp.
+   *
+   * @param {string} entityToken - Entity token.
+   * @param {number} [timestamp] - Timestamp in milliseconds (defaults to current time).
+   * @returns {{nibbleBits: number, nibbles: number}} Result object.
+   */
+  getNibbles(entityToken) {
+    let timestamp = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : Date.now();
+    const {
+      nibbleBits,
+      nibbles,
+      bumps
+    } = this.getEntityConfig(entityToken).sharding;
+    this.validateTimestamp(timestamp);
+    return {
+      nibbleBits,
+      nibbles: (0, _findLast2.default)(bumps, (value, key) => key <= timestamp) ?? nibbles
+    };
+  }
+
+  /**
+   * Return a shard key for a given entity token, entity id & timestamp.
+   *
+   * @param {string} entityToken - Entity token.
+   * @param {string} entityKey - Entity id.
+   * @param {number} [timestamp] - Timestamp in milliseconds (defaults to current time).
+   * @returns {string} shard key.
+   */
+  getShardKey(entityToken, entityKey) {
+    let timestamp = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : Date.now();
+    // Get nibbles for entityToken at timestamp (validates entityToken)
+    const {
+      nibbleBits,
+      nibbles
+    } = this.getNibbles(entityToken, timestamp);
+
+    // Calculate shardKey.
+    const radix = 2 ** nibbleBits;
+    const shardKey = nibbles ? ((0, _stringHash.default)(entityKey) % (nibbles * radix)).toString(radix).padStart(nibbles, '0') : undefined;
+    if ((0, _isNil2.default)(shardKey)) this.logger.debug(`no shard key generated for ${entityToken} id '${entityKey}' at timestamp ${timestamp}.`);else this.logger.debug(`generated shard key '${shardKey}' for ${entityToken} id '${entityKey}' at timestamp ${timestamp}.`);
+    return shardKey;
+  }
+
+  /**
+   * Return an array of shard keys valid for a given entity token & timestamp.
+   *
+   * @param {string} entityToken - Entity token.
+   * @param {number} [timestamp] - Timestamp in milliseconds (defaults to current time).
+   * @returns {string[]} shard key space.
+   */
+  getShardKeySpace(entityToken) {
+    let timestamp = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : Date.now();
+    const {
+      nibbleBits,
+      nibbles,
+      bumps
+    } = this.getEntityConfig(entityToken).sharding;
+    if (!nibbles && !(0, _size2.default)(bumps)) return [];
+    this.validateTimestamp(timestamp);
+    const nibbleSpace = [nibbles, ...(0, _map2.default)((0, _filter2.default)(bumps, (value, key) => key <= timestamp))];
+    const radix = 2 ** nibbleBits;
+    const shardKeySpace = (0, _flatten2.default)((0, _map2.default)(nibbleSpace, nibbles => {
+      return nibbles ? (0, _range2.default)(0, radix ** nibbles).map(nibble => nibble.toString(radix).padStart(nibbles, '0')) : undefined;
+    }));
+    return shardKeySpace;
+  }
+
+  /**
+   * Tests whether an entityToken is valid.
+   *
+   * @param {string} entityToken - Entity token.
+   * @returns {boolean} true if entityToken is valid.
+   */
+  validateEntityToken(entityToken) {
+    if (!this.config.entities[entityToken]) {
+      const message = `Invalid entityToken: ${entityToken}`;
+      this.logger.error(message);
+      throw new Error(message);
+    } else return true;
+  }
+
+  /**
+   * Tests whether an item is valid.
+   *
+   * @param {string} item - Entity token.
+   * @returns {boolean} true if entityToken is valid.
+   */
+  validateItem(item) {
+    if (!(0, _isPlainObject2.default)(item)) {
+      const message = `Invalid item: ${item}`;
+      this.logger.error(message);
+      throw new Error(message);
+    } else return true;
+  }
+
+  /**
+   * Tests whether a timestamp is valid.
+   *
+   * @param {number} timestamp - timestamp.
+   * @param {boolean} [future=false] - true if timestamp must be in the future.
+   * @returns {boolean} true if timestamp is valid.
+   */
+  validateTimestamp(timestamp) {
+    let future = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : false;
+    if (!(0, _isInteger2.default)(timestamp) || future && timestamp <= Date.now()) throw new Error(`invalid timestamp (must be an integer${future ? ' in the future' : ''})`);else return true;
+  }
+}
+exports.PrivateEntityManager = PrivateEntityManager;

package/dist/default/lib/index.js

@@ -0,0 +1,12 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "EntityManager", {
+  enumerable: true,
+  get: function () {
+    return _EntityManager.EntityManager;
+  }
+});
+var _EntityManager = require("./EntityManager/EntityManager.js");

package/dist/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/lib/EntityManager/EntityManager.js

@@ -0,0 +1,113 @@
+/**
+ * @module entity-manager
+ */
+
+import _ from 'lodash';
+
+import { PrivateEntityManager } from './PrivateEntityManager.js';
+
+/**
+ * Manage DynamoDb entities.
+ *
+ * @class
+ */
+export class EntityManager {
+  #entityManager;
+
+  /**
+   * Create an EntityManager instance.
+   *
+   * @param {object} options - Options object.
+   * @param {object} [options.config] - EntityManager configuration object (see {@link https://github.com/karmaniverous/entity-manager#configuration README} for a breakdown).
+   * @param {object} [options.logger] - Logger instance (defaults to console, must support error & debug methods).
+   * @returns {EntityManager} EntityManager instance.
+   * @throws {Error} If config is invalid.
+   * @throws {Error} If logger is invalid.
+   */
+  constructor({ config, logger }) {
+    this.#entityManager = new PrivateEntityManager({ config, logger });
+  }
+
+  /**
+   * Decorate an entity item with keys.
+   *
+   * @param {string} entityToken - Entity token.
+   * @param {object} item - Entity item.
+   * @param {boolean} [overwrite=false] - Overwrite existing properties.
+   * @returns {object} Decorated entity item.
+   * @throws {Error} If entityToken is invalid.
+   * @throws {Error} If item is invalid.
+   */
+  addKeys(entityToken, item, overwrite = false) {
+    this.#entityManager.logger.debug(
+      `adding sharded index keys to ${entityToken}${
+        overwrite ? ' with overwrite' : ''
+      }...`,
+      item
+    );
+
+    // Get entity config.
+    const { shardKeyToken } = this.#entityManager;
+    const { keys, sharding } = this.#entityManager.getEntityConfig(entityToken);
+
+    // Add shardKey.
+    this.#entityManager.validateItem(item);
+    if (overwrite || _.isNil(item[shardKeyToken])) {
+      const entityKey = sharding.entityKey(item);
+      const timestamp = sharding.timestamp(item);
+      item[shardKeyToken] = this.#entityManager.getShardKey(
+        entityToken,
+        entityKey,
+        timestamp
+      );
+    }
+
+    // Add keys.
+    _.forEach(keys, (getValue, key) => {
+      if (overwrite || _.isNil(item[key])) item[key] = getValue(item);
+    });
+    this.#entityManager.logger.debug('done', item);
+
+    return item;
+  }
+
+  /**
+   * Return an array of sharded keys valid for a given entity token & timestamp.
+   *
+   * @param {string} entityToken - Entity token.
+   * @param {object} item - Entity item.
+   * @param {string} keyToken - Key token.
+   * @param {number} timestamp - Timestamp.
+   * @returns {string[]} Array of keys.
+   * @throws {Error} If entityToken is invalid.
+   * @throws {Error} If item is invalid.
+   * @throws {Error} If keyToken is invalid.
+   * @throws {Error} If timestamp is invalid.
+   */
+  getKeySpace(entityToken, item, keyToken, timestamp = Date.now()) {
+    this.#entityManager.logger.debug(
+      `getting shard key space for ${entityToken} on key '${keyToken}' at timestamp ${timestamp}...`,
+      item
+    );
+
+    const shardKeySpace = this.#entityManager.getShardKeySpace(
+      entityToken,
+      timestamp
+    );
+
+    const result = _.sortedUniq(
+      shardKeySpace.map((shardKey) =>
+        this.#entityManager.getKeyGenerator(
+          entityToken,
+          keyToken
+        )({
+          ...item,
+          [this.#entityManager.shardKeyToken]: shardKey,
+        })
+      )
+    );
+    this.#entityManager.logger.debug('done', result);
+
+    return result;
+  }
+}