@karmaniverous/entity-manager 2.0.0 → 2.1.1

package/README.md

@@ -220,8 +220,11 @@ 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, index, [delimiter])](#module_entity-manager.EntityManager+dehydrateIndex) ⇒ <code>string</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>
+            * [.rehydrateIndex(entityToken, indexToken, value, [delimiter])](#module_entity-manager.EntityManager+rehydrateIndex) ⇒ <code>object</code>
             * [.removeKeys(entityToken, item)](#module_entity-manager.EntityManager+removeKeys) ⇒ <code>object</code>
     * _inner_
         * [~ShardQueryResult](#module_entity-manager..ShardQueryResult) : <code>object</code>
@@ -238,8 +241,11 @@ 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, index, [delimiter])](#module_entity-manager.EntityManager+dehydrateIndex) ⇒ <code>string</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>
+    * [.rehydrateIndex(entityToken, indexToken, value, [delimiter])](#module_entity-manager.EntityManager+rehydrateIndex) ⇒ <code>object</code>
     * [.removeKeys(entityToken, item)](#module_entity-manager.EntityManager+removeKeys) ⇒ <code>object</code>
 
 <a name="new_module_entity-manager.EntityManager_new"></a>
@@ -279,6 +285,40 @@ 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, index, [delimiter]) ⇒ <code>string</code>
+Condense an index object into a delimited string.
+
+**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. |
+| index | <code>object</code> |  | Index object. |
+| [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>
@@ -319,6 +359,26 @@ Query an entity across shards.
 | [options.limit] | <code>number</code> | Request limit. |
 | [options.pageKeys] | <code>object</code> | Map of shard page keys. |
 
+<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+removeKeys"></a>
 
 #### entityManager.removeKeys(entityToken, item) ⇒ <code>object</code>

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

@@ -4,6 +4,7 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.EntityManager = void 0;
+var _zipObject2 = _interopRequireDefault(require("lodash/zipObject"));
 var _map2 = _interopRequireDefault(require("lodash/map"));
 var _size2 = _interopRequireDefault(require("lodash/size"));
 var _isEmpty2 = _interopRequireDefault(require("lodash/isEmpty"));
@@ -11,11 +12,15 @@ var _fromPairs2 = _interopRequireDefault(require("lodash/fromPairs"));
 var _isPlainObject2 = _interopRequireDefault(require("lodash/isPlainObject"));
 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 _entries2 = _interopRequireDefault(require("lodash/entries"));
+var _sortBy2 = _interopRequireDefault(require("lodash/sortBy"));
+var _sortedUniqBy2 = _interopRequireDefault(require("lodash/sortedUniqBy"));
+var _isFunction2 = _interopRequireDefault(require("lodash/isFunction"));
 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); }
@@ -82,20 +87,20 @@ 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.
-    (0, _forEach2.default)(keys, (getValue, key) => {
-      if (overwrite || (0, _isNil2.default)(newItem[key])) newItem[key] = getValue(newItem);
+    (0, _forEach2.default)(keys, (_ref2, key) => {
+      let {
+        encode
+      } = _ref2;
+      if (overwrite || (0, _isNil2.default)(newItem[key])) newItem[key] = encode(newItem);
     });
     _classPrivateFieldGet(this, _entityManager).logger.debug('done', newItem);
 
@@ -104,6 +109,61 @@ 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);
+  }
+
+  /**
+   * Condense an index object into a delimited string.
+   *
+   * @param {string} entityToken - Entity token.
+   * @param {string} indexToken - Index token.
+   * @param {object} index - Index object.
+   * @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, index) {
+    let delimiter = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : '~';
+    // Validate item.
+    _classPrivateFieldGet(this, _entityManager).validateItem(index);
+    const indexComponents = _classPrivateFieldGet(this, _entityManager).getIndexComponents(entityToken, indexToken);
+    const indexProperties = indexComponents.reduce((properties, component) => {
+      const {
+        decode
+      } = _classPrivateFieldGet(this, _entityManager).getKey(entityToken, component);
+      if (!(0, _isFunction2.default)(decode)) throw new Error(`no decode function defined on ${entityToken} entity key '${component}'`);
+      return {
+        ...properties,
+        ...decode(index[component])
+      };
+    }, {});
+    return (0, _sortedUniqBy2.default)((0, _sortBy2.default)((0, _entries2.default)(indexProperties), _ref3 => {
+      let [key] = _ref3;
+      return key;
+    }), _ref4 => {
+      let [key] = _ref4;
+      return key;
+    }).map(_ref5 => {
+      let [, value] = _ref5;
+      return value;
+    }).join(delimiter);
+  }
+
   /**
    * Return an array of sharded keys valid for a given entity token & timestamp.
    *
@@ -121,7 +181,7 @@ class EntityManager {
     let timestamp = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : Date.now();
     _classPrivateFieldGet(this, _entityManager).logger.debug(`getting shard key space for ${entityToken} on key '${keyToken}' at timestamp ${timestamp}...`, item);
     const shardKeySpace = _classPrivateFieldGet(this, _entityManager).getShardKeySpace(entityToken, timestamp);
-    const result = (0, _sortedUniq2.default)(shardKeySpace.map(shardKey => _classPrivateFieldGet(this, _entityManager).getKeyGenerator(entityToken, keyToken)({
+    const result = (0, _sortedUniq2.default)(shardKeySpace.map(shardKey => _classPrivateFieldGet(this, _entityManager).getKey(entityToken, keyToken).encode({
       ...item,
       [_classPrivateFieldGet(this, _entityManager).shardKeyToken]: shardKey
     })));
@@ -192,11 +252,11 @@ class EntityManager {
     const shardQueryResults = await Promise.all((0, _map2.default)(pageKeys, (pageKey, shardedKey) => new Promise(resolve => shardQuery(shardedKey, {
       pageKey,
       limit: shardLimit
-    }).then(_ref2 => {
+    }).then(_ref6 => {
       let {
         items,
         pageKey
-      } = _ref2;
+      } = _ref6;
       return resolve({
         shardedKey,
         items,
@@ -205,12 +265,12 @@ class EntityManager {
     }))));
 
     // Reduce shardQueryResults into a single result.
-    const result = shardQueryResults.reduce((shardedQueryResult, _ref3) => {
+    const result = shardQueryResults.reduce((shardedQueryResult, _ref7) => {
       let {
         shardedKey,
         items,
         pageKey
-      } = _ref3;
+      } = _ref7;
       return {
         items: [...shardedQueryResult.items, ...items],
         pageKeys: {
@@ -227,6 +287,39 @@ class EntityManager {
     return result;
   }
 
+  /**
+   * 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 indexKeys = (0, _sortBy2.default)(indexComponents.reduce((keys, component) => {
+      const {
+        encode
+      } = _classPrivateFieldGet(this, _entityManager).getKey(entityToken, component);
+      return [...new Set([...keys, ...(0, _inspectParametersDeclaration.getParametersNames)(encode)]).values()];
+    }, []));
+    const indexProperies = (0, _zipObject2.default)(indexKeys, value.split(delimiter));
+    return indexComponents.reduce((index, component) => {
+      const {
+        encode
+      } = _classPrivateFieldGet(this, _entityManager).getKey(entityToken, component);
+      return {
+        ...index,
+        [component]: encode(indexProperies)
+      };
+    }, {});
+  }
+
   /**
    * Remove sharded keys from an entity item. Does not mutate original item.
    *

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

@@ -12,8 +12,12 @@ var _filter2 = _interopRequireDefault(require("lodash/filter"));
 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 _isUndefined2 = _interopRequireDefault(require("lodash/isUndefined"));
+var _isFunction2 = _interopRequireDefault(require("lodash/isFunction"));
+var _forEach2 = _interopRequireDefault(require("lodash/forEach"));
+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 +47,16 @@ const configSchema = {
         '^\\w+$': {
           type: 'object',
           properties: {
+            indexes: {
+              type: 'object',
+              additionalProperties: {
+                type: 'array',
+                items: {
+                  type: 'string'
+                },
+                minItems: 1
+              }
+            },
             keys: {
               type: 'object'
             },
@@ -90,6 +104,15 @@ const configSchema = {
   },
   additionalProperties: false
 };
+const keySchema = {
+  type: 'object',
+  properties: {
+    encode: {},
+    decode: {}
+  },
+  additionalProperties: false,
+  required: ['encode']
+};
 
 /**
  * Private EntityManager implementation.
@@ -160,6 +183,7 @@ class PrivateEntityManager {
     const conformedConfig = {
       entities: (0, _mapValues2.default)(entities, _ref => {
         let {
+          indexes = {},
           keys = {},
           sharding: {
             bumps = {},
@@ -170,6 +194,7 @@ class PrivateEntityManager {
           } = {}
         } = _ref;
         return {
+          indexes,
           keys,
           sharding: {
             bumps: (0, _fromPairs2.default)((0, _sortBy2.default)((0, _toPairs2.default)(bumps), 0)),
@@ -183,9 +208,10 @@ class PrivateEntityManager {
       shardKeyToken
     };
 
-    // Validate entity properties.
+    // Conform & validate entity properties.
     (0, _some2.default)(conformedConfig.entities, (_ref2, entityToken) => {
       let {
+        indexes,
         keys,
         sharding: {
           bumps,
@@ -195,15 +221,38 @@ class PrivateEntityManager {
           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.`;
+      // 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;
       });
 
+      // Conform & validate entity keys.
+      (0, _forEach2.default)(keys, (value, key) => {
+        keys[key] = (0, _isFunction2.default)(value) ? {
+          encode: value
+        } : value;
+
+        // Validate key against schema.
+        const validatorResult = (0, _jsonschema.validate)(keys[key], keySchema);
+        if (!validatorResult.valid) {
+          validatorResult.errors.forEach(error => this.logger.error(error.message));
+          throw new Error(validatorResult.errors);
+        }
+        const {
+          decode
+        } = keys[key];
+        if (!(0, _isUndefined2.default)(decode) && !(0, _isFunction2.default)(decode)) {
+          const message = `entity ${entityKey} key '${key}' decode must be a function or undefined.`;
+          this.logger.error(message);
+          throw new Error(message);
+        }
+      });
+
       // Validate sharding bump values increase monotonically with keys.
       (0, _some2.default)((0, _toPairs2.default)(bumps), (_ref3, i, c) => {
         let [bump, value] = _ref3;
@@ -284,7 +333,18 @@ class PrivateEntityManager {
     this.validateEntityToken(entityToken);
     return this.config.entities[entityToken];
   }
-  getKeyGenerator(entityToken, keyToken) {
+  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];
+  }
+  getKey(entityToken, keyToken) {
     const {
       keys
     } = this.getEntityConfig(entityToken);
@@ -380,30 +440,30 @@ class PrivateEntityManager {
   }
 
   /**
-   * Tests whether a key token is valid.
+   * Tests whether an item is valid.
    *
-   * @param {string} entityToken - Entity token.
-   * @param {string} keyToken - Key token.
-   * @returns {boolean} true if keyToken is valid.
+   * @param {string} item - Entity token.
+   * @returns {boolean} true if entityToken is valid.
    */
-  validateKeyToken(entityToken, keyToken) {
-    this.validateEntityToken(entityToken);
-    if (!this.config.entities[entityToken].keys[keyToken]) {
-      const message = `Invalid entity ${entityToken} keyToken: ${keyToken}`;
+  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 an item is valid.
+   * Tests whether a key token is valid.
    *
-   * @param {string} item - Entity token.
-   * @returns {boolean} true if entityToken is valid.
+   * @param {string} entityToken - Entity token.
+   * @param {string} keyToken - Key token.
+   * @returns {boolean} true if keyToken is valid.
    */
-  validateItem(item) {
-    if (!(0, _isPlainObject2.default)(item)) {
-      const message = `Invalid item: ${item}`;
+  validateKeyToken(entityToken, keyToken) {
+    this.validateEntityToken(entityToken);
+    if (!this.config.entities[entityToken].keys[keyToken]) {
+      const message = `Invalid entity ${entityToken} keyToken: ${keyToken}`;
       this.logger.error(message);
       throw new Error(message);
     } else return true;

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,22 +55,16 @@ 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.
-    _.forEach(keys, (getValue, key) => {
-      if (overwrite || _.isNil(newItem[key])) newItem[key] = getValue(newItem);
+    _.forEach(keys, ({ encode }, key) => {
+      if (overwrite || _.isNil(newItem[key])) newItem[key] = encode(newItem);
     });
     this.#entityManager.logger.debug('done', newItem);
 
@@ -79,6 +74,60 @@ 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);
+  }
+
+  /**
+   * Condense an index object into a delimited string.
+   *
+   * @param {string} entityToken - Entity token.
+   * @param {string} indexToken - Index token.
+   * @param {object} index - Index object.
+   * @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, index, delimiter = '~') {
+    // Validate item.
+    this.#entityManager.validateItem(index);
+
+    const indexComponents = this.#entityManager.getIndexComponents(
+      entityToken,
+      indexToken
+    );
+
+    const indexProperties = indexComponents.reduce((properties, component) => {
+      const { decode } = this.#entityManager.getKey(entityToken, component);
+      if (!_.isFunction(decode))
+        throw new Error(
+          `no decode function defined on ${entityToken} entity key '${component}'`
+        );
+
+      return { ...properties, ...decode(index[component]) };
+    }, {});
+
+    return _.sortedUniqBy(
+      _.sortBy(_.entries(indexProperties), ([key]) => key),
+      ([key]) => key
+    )
+      .map(([, value]) => value)
+      .join(delimiter);
+  }
+
   /**
    * Return an array of sharded keys valid for a given entity token & timestamp.
    *
@@ -105,10 +154,7 @@ export class EntityManager {
 
     const result = _.sortedUniq(
       shardKeySpace.map((shardKey) =>
-        this.#entityManager.getKeyGenerator(
-          entityToken,
-          keyToken
-        )({
+        this.#entityManager.getKey(entityToken, keyToken).encode({
           ...item,
           [this.#entityManager.shardKeyToken]: shardKey,
         })
@@ -215,6 +261,38 @@ export class EntityManager {
     return result;
   }
 
+  /**
+   * 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 indexKeys = _.sortBy(
+      indexComponents.reduce((keys, component) => {
+        const { encode } = this.#entityManager.getKey(entityToken, component);
+        return [...new Set([...keys, ...getParametersNames(encode)]).values()];
+      }, [])
+    );
+
+    const indexProperies = _.zipObject(indexKeys, value.split(delimiter));
+
+    return indexComponents.reduce((index, component) => {
+      const { encode } = this.#entityManager.getKey(entityToken, component);
+      return { ...index, [component]: encode(indexProperies) };
+    }, {});
+  }
+
   /**
    * Remove sharded keys from an entity item. Does not mutate original item.
    *

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',
             },
@@ -57,6 +67,16 @@ const configSchema = {
   additionalProperties: false,
 };
 
+const keySchema = {
+  type: 'object',
+  properties: {
+    encode: {},
+    decode: {},
+  },
+  additionalProperties: false,
+  required: ['encode'],
+};
+
 /**
  * Private EntityManager implementation.
  *
@@ -117,6 +137,7 @@ export class PrivateEntityManager {
       entities: _.mapValues(
         entities,
         ({
+          indexes = {},
           keys = {},
           sharding: {
             bumps = {},
@@ -126,6 +147,7 @@ export class PrivateEntityManager {
             timestamp,
           } = {},
         }) => ({
+          indexes,
           keys,
           sharding: {
             bumps: _.fromPairs(_.sortBy(_.toPairs(bumps), 0)),
@@ -139,25 +161,48 @@ export class PrivateEntityManager {
       shardKeyToken,
     };
 
-    // Validate entity properties.
+    // Conform & validate entity properties.
     _.some(
       conformedConfig.entities,
       (
         {
+          indexes,
           keys,
           sharding: { bumps, entityKey, nibbleBits, nibbles, timestamp },
         },
         entityToken
       ) => {
-        // Validate entity keys are functions or undefined.
-        _.some(keys, (value, key) => {
-          if (!_.isNil(value) && !_.isFunction(value)) {
-            const message = `${entityToken} key '${key}' must be a function or nil.`;
+        // 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;
         });
 
+        // Conform & validate entity keys.
+        _.forEach(keys, (value, key) => {
+          keys[key] = _.isFunction(value) ? { encode: value } : value;
+
+          // Validate key against schema.
+          const validatorResult = validate(keys[key], keySchema);
+          if (!validatorResult.valid) {
+            validatorResult.errors.forEach((error) =>
+              this.logger.error(error.message)
+            );
+            throw new Error(validatorResult.errors);
+          }
+
+          const { decode } = keys[key];
+          if (!_.isUndefined(decode) && !_.isFunction(decode)) {
+            const message = `entity ${entityKey} key '${key}' decode must be a function or undefined.`;
+            this.logger.error(message);
+            throw new Error(message);
+          }
+        });
+
         // Validate sharding bump values increase monotonically with keys.
         _.some(_.toPairs(bumps), ([bump, value], i, c) => {
           const [lastBump, lastValue] = i ? c[i - 1] : [];
@@ -240,7 +285,19 @@ export class PrivateEntityManager {
     return this.config.entities[entityToken];
   }
 
-  getKeyGenerator(entityToken, keyToken) {
+  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];
+  }
+
+  getKey(entityToken, keyToken) {
     const { keys } = this.getEntityConfig(entityToken);
 
     if (!_.has(keys, keyToken)) {
@@ -348,6 +405,20 @@ export class PrivateEntityManager {
     } else return true;
   }
 
+  /**
+   * Tests whether an item is valid.
+   *
+   * @param {string} item - Entity token.
+   * @returns {boolean} true if entityToken is valid.
+   */
+  validateItem(item) {
+    if (!_.isPlainObject(item)) {
+      const message = `Invalid item: ${item}`;
+      this.logger.error(message);
+      throw new Error(message);
+    } else return true;
+  }
+
   /**
    * Tests whether a key token is valid.
    *
@@ -365,20 +436,6 @@ export class PrivateEntityManager {
     } else return true;
   }
 
-  /**
-   * Tests whether an item is valid.
-   *
-   * @param {string} item - Entity token.
-   * @returns {boolean} true if entityToken is valid.
-   */
-  validateItem(item) {
-    if (!_.isPlainObject(item)) {
-      const message = `Invalid item: ${item}`;
-      this.logger.error(message);
-      throw new Error(message);
-    } else return true;
-  }
-
   /**
    * Tests whether a timestamp is valid.
    *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@karmaniverous/entity-manager",
-  "version": "2.0.0",
+  "version": "2.1.1",
   "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"