@karmaniverous/entity-manager 0.1.2-1 → 2.0.0

package/README.md

@@ -221,7 +221,8 @@ This change can be accomplished with no breaking changes to existing implementat
             * [new exports.EntityManager(options)](#new_module_entity-manager.EntityManager_new)
             * [.addKeys(entityToken, item, [overwrite])](#module_entity-manager.EntityManager+addKeys) ⇒ <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>
         * [~ShardQueryFunction](#module_entity-manager..ShardQueryFunction) ⇒ <code>Promise.&lt;ShardQueryResult&gt;</code>
@@ -238,7 +239,8 @@ Manage DynamoDb entities.
     * [new exports.EntityManager(options)](#new_module_entity-manager.EntityManager_new)
     * [.addKeys(entityToken, item, [overwrite])](#module_entity-manager.EntityManager+addKeys) ⇒ <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>
 
@@ -261,7 +263,7 @@ Create an EntityManager instance.
 <a name="module_entity-manager.EntityManager+addKeys"></a>
 
 #### entityManager.addKeys(entityToken, item, [overwrite]) ⇒ <code>object</code>
-Decorate an entity item with keys.
+Add sharded keys to an entity item. Does not mutate original item.
 
 **Kind**: instance method of [<code>EntityManager</code>](#module_entity-manager.EntityManager)  
 **Returns**: <code>object</code> - Decorated entity item.  
@@ -301,7 +303,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)  
@@ -313,7 +315,27 @@ 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>
+
+#### entityManager.removeKeys(entityToken, item) ⇒ <code>object</code>
+Remove sharded keys from an entity item. Does not mutate original item.
+
+**Kind**: instance method of [<code>EntityManager</code>](#module_entity-manager.EntityManager)  
+**Returns**: <code>object</code> - Stripped entity item.  
+**Throws**:
+
+- <code>Error</code> If entityToken is invalid.
+- <code>Error</code> If item is invalid.
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| entityToken | <code>string</code> | Entity token. |
+| item | <code>object</code> | Entity item. |
 
 <a name="module_entity-manager..ShardQueryResult"></a>
 
@@ -337,7 +359,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,12 +4,18 @@ 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 _forEach2 = _interopRequireDefault(require("lodash/forEach"));
 var _isNil2 = _interopRequireDefault(require("lodash/isNil"));
+var _cloneDeep2 = _interopRequireDefault(require("lodash/cloneDeep"));
 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); }
@@ -52,7 +58,7 @@ class EntityManager {
   }
 
   /**
-   * Decorate an entity item with keys.
+   * Add sharded keys to an entity item. Does not mutate original item.
    *
    * @param {string} entityToken - Entity token.
    * @param {object} item - Entity item.
@@ -65,6 +71,12 @@ class EntityManager {
     let overwrite = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : false;
     _classPrivateFieldGet(this, _entityManager).logger.debug(`adding sharded index keys to ${entityToken}${overwrite ? ' with overwrite' : ''}...`, item);
 
+    // Validate item.
+    _classPrivateFieldGet(this, _entityManager).validateItem(item);
+
+    // Clone item.
+    const newItem = (0, _cloneDeep2.default)(item);
+
     // Get entity config.
     const {
       shardKeyToken
@@ -75,22 +87,21 @@ class EntityManager {
     } = _classPrivateFieldGet(this, _entityManager).getEntityConfig(entityToken);
 
     // Add shardKey.
-    _classPrivateFieldGet(this, _entityManager).validateItem(item);
-    if (overwrite || (0, _isNil2.default)(item[shardKeyToken])) {
-      const entityKey = sharding.entityKey(item);
-      const timestamp = sharding.timestamp(item);
-      item[shardKeyToken] = _classPrivateFieldGet(this, _entityManager).getShardKey(entityToken, entityKey, timestamp);
+    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);
     }
 
     // Add keys.
     (0, _forEach2.default)(keys, (getValue, key) => {
-      if (overwrite || (0, _isNil2.default)(item[key])) item[key] = getValue(item);
+      if (overwrite || (0, _isNil2.default)(newItem[key])) newItem[key] = getValue(newItem);
     });
-    _classPrivateFieldGet(this, _entityManager).logger.debug('done', item);
+    _classPrivateFieldGet(this, _entityManager).logger.debug('done', newItem);
 
     // Remove undefined shardKey.
-    if ((0, _isNil2.default)(item[shardKeyToken])) delete item[shardKeyToken];
-    return item;
+    if ((0, _isNil2.default)(newItem[shardKeyToken])) delete newItem[shardKeyToken];
+    return newItem;
   }
 
   /**
@@ -129,7 +140,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.
    */
 
@@ -146,31 +159,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) => {
@@ -194,5 +226,42 @@ class EntityManager {
     });
     return result;
   }
+
+  /**
+   * Remove sharded keys from an entity item. Does not mutate original item.
+   *
+   * @param {string} entityToken - Entity token.
+   * @param {object} item - Entity item.
+   * @returns {object} Stripped entity item.
+   * @throws {Error} If entityToken is invalid.
+   * @throws {Error} If item is invalid.
+   */
+  removeKeys(entityToken, item) {
+    _classPrivateFieldGet(this, _entityManager).logger.debug(`removing sharded index keys from ${entityToken}...`, item);
+
+    // Validate item.
+    _classPrivateFieldGet(this, _entityManager).validateItem(item);
+
+    // Clone item.
+    const newItem = (0, _cloneDeep2.default)(item);
+
+    // Get entity config.
+    const {
+      shardKeyToken
+    } = _classPrivateFieldGet(this, _entityManager);
+    const {
+      keys
+    } = _classPrivateFieldGet(this, _entityManager).getEntityConfig(entityToken);
+
+    // Remove shardKey.
+    delete newItem[shardKeyToken];
+
+    // Remove keys.
+    (0, _forEach2.default)(keys, (getValue, key) => {
+      delete newItem[key];
+    });
+    _classPrivateFieldGet(this, _entityManager).logger.debug('done', newItem);
+    return newItem;
+  }
 }
 exports.EntityManager = EntityManager;

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

@@ -379,6 +379,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

@@ -29,7 +29,7 @@ export class EntityManager {
   }
 
   /**
-   * Decorate an entity item with keys.
+   * Add sharded keys to an entity item. Does not mutate original item.
    *
    * @param {string} entityToken - Entity token.
    * @param {object} item - Entity item.
@@ -46,16 +46,21 @@ export class EntityManager {
       item
     );
 
+    // Validate item.
+    this.#entityManager.validateItem(item);
+
+    // Clone item.
+    const newItem = _.cloneDeep(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(
+    if (overwrite || _.isNil(newItem[shardKeyToken])) {
+      const entityKey = sharding.entityKey(newItem);
+      const timestamp = sharding.timestamp(newItem);
+      newItem[shardKeyToken] = this.#entityManager.getShardKey(
         entityToken,
         entityKey,
         timestamp
@@ -64,14 +69,14 @@ export class EntityManager {
 
     // Add keys.
     _.forEach(keys, (getValue, key) => {
-      if (overwrite || _.isNil(item[key])) item[key] = getValue(item);
+      if (overwrite || _.isNil(newItem[key])) newItem[key] = getValue(newItem);
     });
-    this.#entityManager.logger.debug('done', item);
+    this.#entityManager.logger.debug('done', newItem);
 
     // Remove undefined shardKey.
-    if (_.isNil(item[shardKeyToken])) delete item[shardKeyToken];
+    if (_.isNil(newItem[shardKeyToken])) delete newItem[shardKeyToken];
 
-    return item;
+    return newItem;
   }
 
   /**
@@ -125,7 +130,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.
    */
 
@@ -142,10 +149,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) => [
@@ -154,22 +179,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 }) => ({
@@ -184,4 +214,41 @@ export class EntityManager {
 
     return result;
   }
+
+  /**
+   * Remove sharded keys from an entity item. Does not mutate original item.
+   *
+   * @param {string} entityToken - Entity token.
+   * @param {object} item - Entity item.
+   * @returns {object} Stripped entity item.
+   * @throws {Error} If entityToken is invalid.
+   * @throws {Error} If item is invalid.
+   */
+  removeKeys(entityToken, item) {
+    this.#entityManager.logger.debug(
+      `removing sharded index keys from ${entityToken}...`,
+      item
+    );
+
+    // Validate item.
+    this.#entityManager.validateItem(item);
+
+    // Clone item.
+    const newItem = _.cloneDeep(item);
+
+    // Get entity config.
+    const { shardKeyToken } = this.#entityManager;
+    const { keys } = this.#entityManager.getEntityConfig(entityToken);
+
+    // Remove shardKey.
+    delete newItem[shardKeyToken];
+
+    // Remove keys.
+    _.forEach(keys, (getValue, key) => {
+      delete newItem[key];
+    });
+    this.#entityManager.logger.debug('done', newItem);
+
+    return newItem;
+  }
 }

package/lib/EntityManager/PrivateEntityManager.js

@@ -348,6 +348,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": "0.1.2-1",
+  "version": "2.0.0",
   "publishConfig": {
     "access": "public"
   },