@karmaniverous/entity-manager 1.0.0 → 2.1.0

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, 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, [pageKeys])](#module_entity-manager.EntityManager+query) ⇒ <code>Promise.&lt;ShardedQueryResult&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>
     * _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, 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, [pageKeys])](#module_entity-manager.EntityManager+query) ⇒ <code>Promise.&lt;ShardedQueryResult&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>
 
 <a name="new_module_entity-manager.EntityManager_new"></a>
@@ -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>
@@ -303,7 +363,7 @@ Return an array of sharded keys valid for a given entity token & timestamp.
 
 <a name="module_entity-manager.EntityManager+query"></a>
 
-#### entityManager.query(entityToken, keyToken, item, shardQuery, [pageKeys]) ⇒ <code>Promise.&lt;ShardedQueryResult&gt;</code>
+#### entityManager.query(entityToken, keyToken, item, shardQuery, [options]) ⇒ <code>Promise.&lt;ShardedQueryResult&gt;</code>
 Query an entity across shards.
 
 **Kind**: instance method of [<code>EntityManager</code>](#module_entity-manager.EntityManager)  
@@ -315,7 +375,9 @@ Query an entity across shards.
 | keyToken | <code>string</code> | Key token. |
 | item | <code>object</code> | Entity item sufficiently populated to generate property keyToken. |
 | shardQuery | <code>ShardQueryFunction</code> | Sharded query function. |
-| [pageKeys] | <code>object</code> | Map of shard page keys. |
+| [options] | <code>object</code> | Options object. |
+| [options.limit] | <code>number</code> | Request limit. |
+| [options.pageKeys] | <code>object</code> | Map of shard page keys. |
 
 <a name="module_entity-manager.EntityManager+removeKeys"></a>
 
@@ -357,7 +419,9 @@ Shard query function
 | Param | Type | Description |
 | --- | --- | --- |
 | shardedKey | <code>string</code> | Sharded key. |
-| [pageKey] | <code>\*</code> | Page key. |
+| [options] | <code>object</code> | Options object. |
+| [options.limit] | <code>number</code> | Request limit. |
+| [options.pageKey] | <code>\*</code> | Page key. |
 
 <a name="module_entity-manager..ShardedQueryResult"></a>
 

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

@@ -4,13 +4,25 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.EntityManager = void 0;
-var _isUndefined2 = _interopRequireDefault(require("lodash/isUndefined"));
 var _map2 = _interopRequireDefault(require("lodash/map"));
+var _size2 = _interopRequireDefault(require("lodash/size"));
+var _isEmpty2 = _interopRequireDefault(require("lodash/isEmpty"));
 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 _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); }
@@ -21,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.
  *
@@ -46,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
@@ -77,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.
@@ -99,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.
    *
@@ -135,7 +214,9 @@ class EntityManager {
    *
    * @callback ShardQueryFunction
    * @param {string} shardedKey - Sharded key.
-   * @param {*} [pageKey] - Page key.
+   * @param {object} [options] - Options object.
+   * @param {number} [options.limit] - Request limit.
+   * @param {*} [options.pageKey] - Page key.
    * @returns {Promise<ShardQueryResult>} Sharded query result.
    */
 
@@ -152,31 +233,50 @@ class EntityManager {
    * @param {string} keyToken - Key token.
    * @param {object} item - Entity item sufficiently populated to generate property keyToken.
    * @param {ShardQueryFunction} shardQuery - Sharded query function.
-   * @param {object} [pageKeys] - Map of shard page keys.
+   * @param {object} [options] - Options object.
+   * @param {number} [options.limit] - Request limit.
+   * @param {object} [options.pageKeys] - Map of shard page keys.
    * @returns {Promise<ShardedQueryResult>} Sharded query result.
    */
-  async query(entityToken, keyToken, item, shardQuery, pageKeys) {
+  async query(entityToken, keyToken, item, shardQuery) {
+    let {
+      limit,
+      pageKeys
+    } = arguments.length > 4 && arguments[4] !== undefined ? arguments[4] : {};
+    // Validate params.
+    _classPrivateFieldGet(this, _entityManager).validateKeyToken(entityToken, keyToken);
+    _classPrivateFieldGet(this, _entityManager).validateItem(item);
+    if (!(0, _isFunction2.default)(shardQuery)) throw new Error('shardQuery must be a function');
+    if (!(0, _isUndefined2.default)(limit) && !(0, _isInteger2.default)(limit)) throw new Error('limit must be an integer');
+    if (!(0, _isUndefined2.default)(pageKeys) && !(0, _isPlainObject2.default)(pageKeys)) throw new Error('pageKeys must be an object');
+
     // Generate default pageKeys if not provided
     pageKeys ??= (0, _fromPairs2.default)(this.getKeySpace(entityToken, keyToken, item).map(shardedKey => [shardedKey, undefined]));
 
+    // Return empty result if no pageKeys.
+    if ((0, _isEmpty2.default)(pageKeys)) return {
+      items: [],
+      pageKeys: {}
+    };
+
+    // Calculate shard limit.
+    const shardLimit = (0, _isUndefined2.default)(limit) ? undefined : Math.ceil(limit / (0, _size2.default)(pageKeys));
+
     // Query every shard in pageKeys.
-    const shardQueryResults = await Promise.all((0, _map2.default)(pageKeys, (pageKey, shardedKey) => new Promise(resolve => shardQuery(shardedKey, pageKey).then(_ref2 => {
+    const shardQueryResults = await Promise.all((0, _map2.default)(pageKeys, (pageKey, shardedKey) => new Promise(resolve => shardQuery(shardedKey, {
+      pageKey,
+      limit: shardLimit
+    }).then(_ref2 => {
       let {
         items,
         pageKey
       } = _ref2;
-      console.log('shardQueryResult', {
-        shardedKey,
-        items,
-        pageKey
-      });
       return resolve({
         shardedKey,
         items,
         pageKey
       });
     }))));
-    console.log('shardQueryResults', shardQueryResults);
 
     // Reduce shardQueryResults into a single result.
     const result = shardQueryResults.reduce((shardedQueryResult, _ref3) => {

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
@@ -379,6 +415,22 @@ class PrivateEntityManager {
     } else return true;
   }
 
+  /**
+   * Tests whether a key token is valid.
+   *
+   * @param {string} entityToken - Entity token.
+   * @param {string} keyToken - Key token.
+   * @returns {boolean} true if keyToken is valid.
+   */
+  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;
+  }
+
   /**
    * Tests whether an item is valid.
    *

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.
    *
@@ -130,7 +227,9 @@ export class EntityManager {
    *
    * @callback ShardQueryFunction
    * @param {string} shardedKey - Sharded key.
-   * @param {*} [pageKey] - Page key.
+   * @param {object} [options] - Options object.
+   * @param {number} [options.limit] - Request limit.
+   * @param {*} [options.pageKey] - Page key.
    * @returns {Promise<ShardQueryResult>} Sharded query result.
    */
 
@@ -147,10 +246,28 @@ export class EntityManager {
    * @param {string} keyToken - Key token.
    * @param {object} item - Entity item sufficiently populated to generate property keyToken.
    * @param {ShardQueryFunction} shardQuery - Sharded query function.
-   * @param {object} [pageKeys] - Map of shard page keys.
+   * @param {object} [options] - Options object.
+   * @param {number} [options.limit] - Request limit.
+   * @param {object} [options.pageKeys] - Map of shard page keys.
    * @returns {Promise<ShardedQueryResult>} Sharded query result.
    */
-  async query(entityToken, keyToken, item, shardQuery, pageKeys) {
+  async query(
+    entityToken,
+    keyToken,
+    item,
+    shardQuery,
+    { limit, pageKeys } = {}
+  ) {
+    // Validate params.
+    this.#entityManager.validateKeyToken(entityToken, keyToken);
+    this.#entityManager.validateItem(item);
+    if (!_.isFunction(shardQuery))
+      throw new Error('shardQuery must be a function');
+    if (!_.isUndefined(limit) && !_.isInteger(limit))
+      throw new Error('limit must be an integer');
+    if (!_.isUndefined(pageKeys) && !_.isPlainObject(pageKeys))
+      throw new Error('pageKeys must be an object');
+
     // Generate default pageKeys if not provided
     pageKeys ??= _.fromPairs(
       this.getKeySpace(entityToken, keyToken, item).map((shardedKey) => [
@@ -159,22 +276,27 @@ export class EntityManager {
       ])
     );
 
+    // Return empty result if no pageKeys.
+    if (_.isEmpty(pageKeys)) return { items: [], pageKeys: {} };
+
+    // Calculate shard limit.
+    const shardLimit = _.isUndefined(limit)
+      ? undefined
+      : Math.ceil(limit / _.size(pageKeys));
+
     // Query every shard in pageKeys.
     const shardQueryResults = await Promise.all(
       _.map(
         pageKeys,
         (pageKey, shardedKey) =>
           new Promise((resolve) =>
-            shardQuery(shardedKey, pageKey).then(({ items, pageKey }) => {
-              console.log('shardQueryResult', { shardedKey, items, pageKey });
-              return resolve({ shardedKey, items, pageKey });
-            })
+            shardQuery(shardedKey, { pageKey, limit: shardLimit }).then(
+              ({ items, pageKey }) => resolve({ shardedKey, items, pageKey })
+            )
           )
       )
     );
 
-    console.log('shardQueryResults', shardQueryResults);
-
     // Reduce shardQueryResults into a single result.
     const result = shardQueryResults.reduce(
       (shardedQueryResult, { shardedKey, items, pageKey }) => ({

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);
 
@@ -348,6 +383,23 @@ export class PrivateEntityManager {
     } else return true;
   }
 
+  /**
+   * Tests whether a key token is valid.
+   *
+   * @param {string} entityToken - Entity token.
+   * @param {string} keyToken - Key token.
+   * @returns {boolean} true if keyToken is valid.
+   */
+  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;
+  }
+
   /**
    * Tests whether an item is valid.
    *

package/package.json

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