@karmaniverous/entity-manager 2.0.0 → 2.1.0

package/README.md

@@ -220,6 +220,9 @@ This change can be accomplished with no breaking changes to existing implementat
         * [.EntityManager](#module_entity-manager.EntityManager)
             * [new exports.EntityManager(options)](#new_module_entity-manager.EntityManager_new)
             * [.addKeys(entityToken, item, [overwrite])](#module_entity-manager.EntityManager+addKeys) ⇒ <code>object</code>
+            * [.calcShardKey(entityToken, item)](#module_entity-manager.EntityManager+calcShardKey) ⇒ <code>string</code>
+            * [.dehydrateIndex(entityToken, indexToken, item, [delimiter])](#module_entity-manager.EntityManager+dehydrateIndex) ⇒ <code>string</code>
+            * [.rehydrateIndex(entityToken, indexToken, value, [delimiter])](#module_entity-manager.EntityManager+rehydrateIndex) ⇒ <code>object</code>
             * [.getKeySpace(entityToken, keyToken, item, timestamp)](#module_entity-manager.EntityManager+getKeySpace) ⇒ <code>Array.&lt;string&gt;</code>
             * [.query(entityToken, keyToken, item, shardQuery, [options])](#module_entity-manager.EntityManager+query) ⇒ <code>Promise.&lt;ShardedQueryResult&gt;</code>
             * [.removeKeys(entityToken, item)](#module_entity-manager.EntityManager+removeKeys) ⇒ <code>object</code>
@@ -238,6 +241,9 @@ Manage DynamoDb entities.
 * [.EntityManager](#module_entity-manager.EntityManager)
     * [new exports.EntityManager(options)](#new_module_entity-manager.EntityManager_new)
     * [.addKeys(entityToken, item, [overwrite])](#module_entity-manager.EntityManager+addKeys) ⇒ <code>object</code>
+    * [.calcShardKey(entityToken, item)](#module_entity-manager.EntityManager+calcShardKey) ⇒ <code>string</code>
+    * [.dehydrateIndex(entityToken, indexToken, item, [delimiter])](#module_entity-manager.EntityManager+dehydrateIndex) ⇒ <code>string</code>
+    * [.rehydrateIndex(entityToken, indexToken, value, [delimiter])](#module_entity-manager.EntityManager+rehydrateIndex) ⇒ <code>object</code>
     * [.getKeySpace(entityToken, keyToken, item, timestamp)](#module_entity-manager.EntityManager+getKeySpace) ⇒ <code>Array.&lt;string&gt;</code>
     * [.query(entityToken, keyToken, item, shardQuery, [options])](#module_entity-manager.EntityManager+query) ⇒ <code>Promise.&lt;ShardedQueryResult&gt;</code>
     * [.removeKeys(entityToken, item)](#module_entity-manager.EntityManager+removeKeys) ⇒ <code>object</code>
@@ -279,6 +285,60 @@ Add sharded keys to an entity item. Does not mutate original item.
 | item | <code>object</code> |  | Entity item. |
 | [overwrite] | <code>boolean</code> | <code>false</code> | Overwrite existing properties. |
 
+<a name="module_entity-manager.EntityManager+calcShardKey"></a>
+
+#### entityManager.calcShardKey(entityToken, item) ⇒ <code>string</code>
+Calculated the shard key for an entity item.
+
+**Kind**: instance method of [<code>EntityManager</code>](#module_entity-manager.EntityManager)  
+**Returns**: <code>string</code> - Shard key.  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| entityToken | <code>string</code> | Entity token. |
+| item | <code>object</code> | Entity item. |
+
+<a name="module_entity-manager.EntityManager+dehydrateIndex"></a>
+
+#### entityManager.dehydrateIndex(entityToken, indexToken, item, [delimiter]) ⇒ <code>string</code>
+Convert a item into a delimited string containing the properties of a named index.
+
+**Kind**: instance method of [<code>EntityManager</code>](#module_entity-manager.EntityManager)  
+**Returns**: <code>string</code> - Dehydrated index.  
+**Throws**:
+
+- <code>Error</code> If entityToken is invalid.
+- <code>Error</code> If indexToken is invalid.
+- <code>Error</code> If item is invalid.
+
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| entityToken | <code>string</code> |  | Entity token. |
+| indexToken | <code>string</code> |  | Index token. |
+| item | <code>object</code> |  | Entity item. |
+| [delimiter] | <code>string</code> | <code>&quot;~&quot;</code> | Delimiter. |
+
+<a name="module_entity-manager.EntityManager+rehydrateIndex"></a>
+
+#### entityManager.rehydrateIndex(entityToken, indexToken, value, [delimiter]) ⇒ <code>object</code>
+Convert a delimited string into a named index key.
+
+**Kind**: instance method of [<code>EntityManager</code>](#module_entity-manager.EntityManager)  
+**Returns**: <code>object</code> - Rehydrated index key.  
+**Throws**:
+
+- <code>Error</code> If entityToken is invalid.
+- <code>Error</code> If indexToken is invalid.
+
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| entityToken | <code>string</code> |  | Entity token. |
+| indexToken | <code>string</code> |  | Index token. |
+| value | <code>string</code> |  | Dehydrated index value. |
+| [delimiter] | <code>string</code> | <code>&quot;~&quot;</code> | Delimiter. |
+
 <a name="module_entity-manager.EntityManager+getKeySpace"></a>
 
 #### entityManager.getKeySpace(entityToken, keyToken, item, timestamp) ⇒ <code>Array.&lt;string&gt;</code>

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

@@ -13,9 +13,16 @@ var _isInteger2 = _interopRequireDefault(require("lodash/isInteger"));
 var _isUndefined2 = _interopRequireDefault(require("lodash/isUndefined"));
 var _isFunction2 = _interopRequireDefault(require("lodash/isFunction"));
 var _sortedUniq2 = _interopRequireDefault(require("lodash/sortedUniq"));
+var _zipObject2 = _interopRequireDefault(require("lodash/zipObject"));
+var _flatten2 = _interopRequireDefault(require("lodash/flatten"));
+var _uniq2 = _interopRequireDefault(require("lodash/uniq"));
+var _sortBy2 = _interopRequireDefault(require("lodash/sortBy"));
+var _pick2 = _interopRequireDefault(require("lodash/pick"));
+var _values2 = _interopRequireDefault(require("lodash/values"));
 var _forEach2 = _interopRequireDefault(require("lodash/forEach"));
 var _isNil2 = _interopRequireDefault(require("lodash/isNil"));
 var _cloneDeep2 = _interopRequireDefault(require("lodash/cloneDeep"));
+var _inspectParametersDeclaration = require("inspect-parameters-declaration");
 var _PrivateEntityManager = require("./PrivateEntityManager.js");
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
 function _classPrivateFieldInitSpec(obj, privateMap, value) { _checkPrivateRedeclaration(obj, privateMap); privateMap.set(obj, value); }
@@ -26,6 +33,7 @@ function _classPrivateFieldSet(receiver, privateMap, value) { var descriptor = _
 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; } }
 var _entityManager = /*#__PURE__*/new WeakMap();
+var _getIndexProperties = /*#__PURE__*/new WeakMap();
 /**
  * Manage DynamoDb entities.
  *
@@ -51,6 +59,10 @@ class EntityManager {
       writable: true,
       value: void 0
     });
+    _classPrivateFieldInitSpec(this, _getIndexProperties, {
+      writable: true,
+      value: (entityToken, indexComponents) => (0, _sortBy2.default)((0, _uniq2.default)((0, _flatten2.default)(indexComponents.map(keyToken => (0, _inspectParametersDeclaration.getParametersNames)(_classPrivateFieldGet(this, _entityManager).getKeyGenerator(entityToken, keyToken))))))
+    });
     _classPrivateFieldSet(this, _entityManager, new _PrivateEntityManager.PrivateEntityManager({
       config,
       logger
@@ -82,15 +94,12 @@ class EntityManager {
       shardKeyToken
     } = _classPrivateFieldGet(this, _entityManager);
     const {
-      keys,
-      sharding
+      keys
     } = _classPrivateFieldGet(this, _entityManager).getEntityConfig(entityToken);
 
     // Add shardKey.
     if (overwrite || (0, _isNil2.default)(newItem[shardKeyToken])) {
-      const entityKey = sharding.entityKey(newItem);
-      const timestamp = sharding.timestamp(newItem);
-      newItem[shardKeyToken] = _classPrivateFieldGet(this, _entityManager).getShardKey(entityToken, entityKey, timestamp);
+      newItem[shardKeyToken] = this.calcShardKey(entityToken, newItem);
     }
 
     // Add keys.
@@ -104,6 +113,71 @@ class EntityManager {
     return newItem;
   }
 
+  /**
+   * Calculated the shard key for an entity item.
+   *
+   * @param {string} entityToken - Entity token.
+   * @param {object} item - Entity item.
+   * @returns {string} Shard key.
+   */
+  calcShardKey(entityToken, item) {
+    const {
+      sharding
+    } = _classPrivateFieldGet(this, _entityManager).getEntityConfig(entityToken);
+    const entityKey = sharding.entityKey(item);
+    const timestamp = sharding.timestamp(item);
+    return _classPrivateFieldGet(this, _entityManager).getShardKey(entityToken, entityKey, timestamp);
+  }
+
+  /**
+   * Convert a item into a delimited string containing the properties of a named index.
+   *
+   * @param {string} entityToken - Entity token.
+   * @param {string} indexToken - Index token.
+   * @param {object} item - Entity item.
+   * @param {string} [delimiter] - Delimiter.
+   * @returns {string} Dehydrated index.
+   * @throws {Error} If entityToken is invalid.
+   * @throws {Error} If indexToken is invalid.
+   * @throws {Error} If item is invalid.
+   */
+  dehydrateIndex(entityToken, indexToken, item) {
+    let delimiter = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : '~';
+    // Validate item.
+    _classPrivateFieldGet(this, _entityManager).validateItem(item);
+    const indexComponents = _classPrivateFieldGet(this, _entityManager).getIndexComponents(entityToken, indexToken);
+    const indexProperties = _classPrivateFieldGet(this, _getIndexProperties).call(this, entityToken, indexComponents);
+    const {
+      shardKeyToken
+    } = _classPrivateFieldGet(this, _entityManager);
+    return (0, _values2.default)((0, _pick2.default)({
+      ...item,
+      [shardKeyToken]: this.calcShardKey(entityToken, item)
+    }, indexProperties)).join(delimiter);
+  }
+  /**
+   * Convert a delimited string into a named index key.
+   *
+   * @param {string} entityToken - Entity token.
+   * @param {string} indexToken - Index token.
+   * @param {string} value - Dehydrated index value.
+   * @param {string} [delimiter] - Delimiter.
+   * @returns {object} Rehydrated index key.
+   * @throws {Error} If entityToken is invalid.
+   * @throws {Error} If indexToken is invalid.
+   */
+  rehydrateIndex(entityToken, indexToken) {
+    let value = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : '';
+    let delimiter = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : '~';
+    const indexComponents = _classPrivateFieldGet(this, _entityManager).getIndexComponents(entityToken, indexToken);
+    const indexProperties = _classPrivateFieldGet(this, _getIndexProperties).call(this, entityToken, indexComponents);
+    const item = (0, _zipObject2.default)(indexProperties, value.split(delimiter));
+    return indexComponents.reduce((index, component) => ({
+      ...index,
+      [component]: _classPrivateFieldGet(this, _entityManager).getKeyGenerator(entityToken, component)(item)
+    }), {});
+  }
+
   /**
    * Return an array of sharded keys valid for a given entity token & timestamp.
    *

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

@@ -14,6 +14,8 @@ 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 _keys2 = _interopRequireDefault(require("lodash/keys"));
+var _difference2 = _interopRequireDefault(require("lodash/difference"));
 var _some2 = _interopRequireDefault(require("lodash/some"));
 var _toPairs2 = _interopRequireDefault(require("lodash/toPairs"));
 var _sortBy2 = _interopRequireDefault(require("lodash/sortBy"));
@@ -43,6 +45,16 @@ const configSchema = {
         '^\\w+$': {
           type: 'object',
           properties: {
+            indexes: {
+              type: 'object',
+              additionalProperties: {
+                type: 'array',
+                items: {
+                  type: 'string'
+                },
+                minItems: 1
+              }
+            },
             keys: {
               type: 'object'
             },
@@ -160,6 +172,7 @@ class PrivateEntityManager {
     const conformedConfig = {
       entities: (0, _mapValues2.default)(entities, _ref => {
         let {
+          indexes = {},
           keys = {},
           sharding: {
             bumps = {},
@@ -170,6 +183,7 @@ class PrivateEntityManager {
           } = {}
         } = _ref;
         return {
+          indexes,
           keys,
           sharding: {
             bumps: (0, _fromPairs2.default)((0, _sortBy2.default)((0, _toPairs2.default)(bumps), 0)),
@@ -186,6 +200,7 @@ class PrivateEntityManager {
     // Validate entity properties.
     (0, _some2.default)(conformedConfig.entities, (_ref2, entityToken) => {
       let {
+        indexes,
         keys,
         sharding: {
           bumps,
@@ -195,6 +210,16 @@ class PrivateEntityManager {
           timestamp
         }
       } = _ref2;
+      // Validate entity index components are entity keys.
+      (0, _some2.default)(indexes, (index, indexToken) => {
+        const invalidIndexComponents = (0, _difference2.default)(index, (0, _keys2.default)(keys));
+        if (invalidIndexComponents.length) {
+          const message = `${entityToken} index '${indexToken}' components '${invalidIndexComponents}' are not entity keys.`;
+          this.logger.error(message);
+          throw new Error(message);
+        } else return false;
+      });
+
       // Validate entity keys are functions or undefined.
       (0, _some2.default)(keys, (value, key) => {
         if (!(0, _isNil2.default)(value) && !(0, _isFunction2.default)(value)) {
@@ -284,6 +309,17 @@ class PrivateEntityManager {
     this.validateEntityToken(entityToken);
     return this.config.entities[entityToken];
   }
+  getIndexComponents(entityToken, indexToken) {
+    const {
+      indexes
+    } = this.getEntityConfig(entityToken);
+    if (!(0, _has2.default)(indexes, indexToken)) {
+      const message = `Index '${indexToken}' does not exist for entity '${entityToken}'.`;
+      this.logger.error(message);
+      throw new Error(message);
+    }
+    return indexes[indexToken];
+  }
   getKeyGenerator(entityToken, keyToken) {
     const {
       keys

package/lib/EntityManager/EntityManager.js

@@ -2,6 +2,7 @@
  * @module entity-manager
  */
 
+import { getParametersNames } from 'inspect-parameters-declaration';
 import _ from 'lodash';
 
 import { PrivateEntityManager } from './PrivateEntityManager.js';
@@ -54,17 +55,11 @@ export class EntityManager {
 
     // Get entity config.
     const { shardKeyToken } = this.#entityManager;
-    const { keys, sharding } = this.#entityManager.getEntityConfig(entityToken);
+    const { keys } = this.#entityManager.getEntityConfig(entityToken);
 
     // Add shardKey.
     if (overwrite || _.isNil(newItem[shardKeyToken])) {
-      const entityKey = sharding.entityKey(newItem);
-      const timestamp = sharding.timestamp(newItem);
-      newItem[shardKeyToken] = this.#entityManager.getShardKey(
-        entityToken,
-        entityKey,
-        timestamp
-      );
+      newItem[shardKeyToken] = this.calcShardKey(entityToken, newItem);
     }
 
     // Add keys.
@@ -79,6 +74,108 @@ export class EntityManager {
     return newItem;
   }
 
+  /**
+   * Calculated the shard key for an entity item.
+   *
+   * @param {string} entityToken - Entity token.
+   * @param {object} item - Entity item.
+   * @returns {string} Shard key.
+   */
+  calcShardKey(entityToken, item) {
+    const { sharding } = this.#entityManager.getEntityConfig(entityToken);
+    const entityKey = sharding.entityKey(item);
+    const timestamp = sharding.timestamp(item);
+
+    return this.#entityManager.getShardKey(entityToken, entityKey, timestamp);
+  }
+
+  /**
+   * Convert a item into a delimited string containing the properties of a named index.
+   *
+   * @param {string} entityToken - Entity token.
+   * @param {string} indexToken - Index token.
+   * @param {object} item - Entity item.
+   * @param {string} [delimiter] - Delimiter.
+   * @returns {string} Dehydrated index.
+   * @throws {Error} If entityToken is invalid.
+   * @throws {Error} If indexToken is invalid.
+   * @throws {Error} If item is invalid.
+   */
+  dehydrateIndex(entityToken, indexToken, item, delimiter = '~') {
+    // Validate item.
+    this.#entityManager.validateItem(item);
+
+    const indexComponents = this.#entityManager.getIndexComponents(
+      entityToken,
+      indexToken
+    );
+
+    const indexProperties = this.#getIndexProperties(
+      entityToken,
+      indexComponents
+    );
+
+    const { shardKeyToken } = this.#entityManager;
+    return _.values(
+      _.pick(
+        {
+          ...item,
+          [shardKeyToken]: this.calcShardKey(entityToken, item),
+        },
+        indexProperties
+      )
+    ).join(delimiter);
+  }
+
+  #getIndexProperties = (entityToken, indexComponents) =>
+    _.sortBy(
+      _.uniq(
+        _.flatten(
+          indexComponents.map((keyToken) =>
+            getParametersNames(
+              this.#entityManager.getKeyGenerator(entityToken, keyToken)
+            )
+          )
+        )
+      )
+    );
+
+  /**
+   * Convert a delimited string into a named index key.
+   *
+   * @param {string} entityToken - Entity token.
+   * @param {string} indexToken - Index token.
+   * @param {string} value - Dehydrated index value.
+   * @param {string} [delimiter] - Delimiter.
+   * @returns {object} Rehydrated index key.
+   * @throws {Error} If entityToken is invalid.
+   * @throws {Error} If indexToken is invalid.
+   */
+  rehydrateIndex(entityToken, indexToken, value = '', delimiter = '~') {
+    const indexComponents = this.#entityManager.getIndexComponents(
+      entityToken,
+      indexToken
+    );
+
+    const indexProperties = this.#getIndexProperties(
+      entityToken,
+      indexComponents
+    );
+
+    const item = _.zipObject(indexProperties, value.split(delimiter));
+
+    return indexComponents.reduce(
+      (index, component) => ({
+        ...index,
+        [component]: this.#entityManager.getKeyGenerator(
+          entityToken,
+          component
+        )(item),
+      }),
+      {}
+    );
+  }
+
   /**
    * Return an array of sharded keys valid for a given entity token & timestamp.
    *

package/lib/EntityManager/PrivateEntityManager.js

@@ -16,6 +16,16 @@ const configSchema = {
         '^\\w+$': {
           type: 'object',
           properties: {
+            indexes: {
+              type: 'object',
+              additionalProperties: {
+                type: 'array',
+                items: {
+                  type: 'string',
+                },
+                minItems: 1,
+              },
+            },
             keys: {
               type: 'object',
             },
@@ -117,6 +127,7 @@ export class PrivateEntityManager {
       entities: _.mapValues(
         entities,
         ({
+          indexes = {},
           keys = {},
           sharding: {
             bumps = {},
@@ -126,6 +137,7 @@ export class PrivateEntityManager {
             timestamp,
           } = {},
         }) => ({
+          indexes,
           keys,
           sharding: {
             bumps: _.fromPairs(_.sortBy(_.toPairs(bumps), 0)),
@@ -144,11 +156,22 @@ export class PrivateEntityManager {
       conformedConfig.entities,
       (
         {
+          indexes,
           keys,
           sharding: { bumps, entityKey, nibbleBits, nibbles, timestamp },
         },
         entityToken
       ) => {
+        // Validate entity index components are entity keys.
+        _.some(indexes, (index, indexToken) => {
+          const invalidIndexComponents = _.difference(index, _.keys(keys));
+          if (invalidIndexComponents.length) {
+            const message = `${entityToken} index '${indexToken}' components '${invalidIndexComponents}' are not entity keys.`;
+            this.logger.error(message);
+            throw new Error(message);
+          } else return false;
+        });
+
         // Validate entity keys are functions or undefined.
         _.some(keys, (value, key) => {
           if (!_.isNil(value) && !_.isFunction(value)) {
@@ -240,6 +263,18 @@ export class PrivateEntityManager {
     return this.config.entities[entityToken];
   }
 
+  getIndexComponents(entityToken, indexToken) {
+    const { indexes } = this.getEntityConfig(entityToken);
+
+    if (!_.has(indexes, indexToken)) {
+      const message = `Index '${indexToken}' does not exist for entity '${entityToken}'.`;
+      this.logger.error(message);
+      throw new Error(message);
+    }
+
+    return indexes[indexToken];
+  }
+
   getKeyGenerator(entityToken, keyToken) {
     const { keys } = this.getEntityConfig(entityToken);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@karmaniverous/entity-manager",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "publishConfig": {
     "access": "public"
   },
@@ -20,6 +20,7 @@
   ],
   "license": "BSD-3-Clause",
   "dependencies": {
+    "inspect-parameters-declaration": "^0.1.0",
     "jsonschema": "^1.4.1",
     "lodash": "^4.17.21",
     "string-hash": "^1.1.3"