@karmaniverous/entity-manager 0.0.11 → 0.1.0

package/README.md

@@ -38,8 +38,8 @@ The `entity-manager` configuration object describes each entity's structured key
 
 // These tagged templates are used below to simplify template literals.
 // sn2e - Template literal returns empty string if any expression is nil.
-// sn2n - Template literal returns undefined if any expression is nil.
-import { sn2e, sn2n } from '@karmaniverous/tagged-templates';
+// sn2u - Template literal returns undefined if any expression is nil.
+import { sn2e, sn2u } from '@karmaniverous/tagged-templates';
 
 // Entity config object named export.
 export const config = {
@@ -57,31 +57,31 @@ export const config = {
 
         // Table RANGE key.
         entitySK: ({ timestamp, transactionId }) =>
-          sn2n`timestamp#${timestamp}|transactionId#${transactionId}`,
+          sn2u`timestamp#${timestamp}|transactionId#${transactionId}`,
 
         // merchants GSI HASH key. Note the optional shardId.
         merchantPK: ({ merchantId, shardId }) =>
-          sn2n`merchantId#${merchantId}|transaction${sn2e`!${shardId}`}`,
+          sn2u`merchantId#${merchantId}|transaction${sn2e`!${shardId}`}`,
 
         // merchants GSI RANGE key.
         merchantSK: ({ methodId, timestamp, transactionId }) =>
-          sn2n`timestamp#${timestamp}|methodId#${methodId}|transactionId#${transactionId}`,
+          sn2u`timestamp#${timestamp}|methodId#${methodId}|transactionId#${transactionId}`,
 
         // methods GSI HASH key. Note the optional shardId.
         methodPK: ({ methodId, shardId }) =>
-          sn2n`method#${methodId}|transaction${sn2e`!${shardId}`}`,
+          sn2u`method#${methodId}|transaction${sn2e`!${shardId}`}`,
 
         // methods GSI RANGE key.
         methodSK: ({ merchantId, timestamp, transactionId }) =>
-          sn2n`timestamp#${timestamp}|merchantId#${merchantId}|transactionId#${transactionId}`,
+          sn2u`timestamp#${timestamp}|merchantId#${merchantId}|transactionId#${transactionId}`,
 
         // users GSI HASH key. Note the optional shardId.
         userPK: ({ shardId, userId }) =>
-          sn2n`user#${userId}|transaction${sn2e`!${shardId}`}`,
+          sn2u`user#${userId}|transaction${sn2e`!${shardId}`}`,
 
         // users GSI RANGE key.
         userSK: ({ merchantId, timestamp, transactionId }) =>
-          sn2n`timestamp#${timestamp}|merchantId#${merchantId}|transactionId#${transactionId}`,
+          sn2u`timestamp#${timestamp}|merchantId#${merchantId}|transactionId#${transactionId}`,
       },
 
       // The sharding configuration for this entity.
@@ -216,10 +216,16 @@ This change can be accomplished with no breaking changes to existing implementat
 ## entity-manager
 
 * [entity-manager](#module_entity-manager)
-    * [.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>
-        * [.getKeySpace(entityToken, item, keyToken, timestamp)](#module_entity-manager.EntityManager+getKeySpace) ⇒ <code>Array.&lt;string&gt;</code>
+    * _static_
+        * [.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>
+            * [.getKeySpace(entityToken, keyToken, item, timestamp)](#module_entity-manager.EntityManager+getKeySpace) ⇒ <code>Array.&lt;string&gt;</code>
+            * [.query(entityToken, keyToken, item, shardQuery, [shardPageKeys])](#module_entity-manager.EntityManager+query) ⇒ <code>Promise.&lt;ShardedQueryResult&gt;</code>
+    * _inner_
+        * [~ShardQueryResult](#module_entity-manager..ShardQueryResult) : <code>object</code>
+        * [~ShardQueryFunction](#module_entity-manager..ShardQueryFunction) ⇒ <code>Promise.&lt;ShardQueryResult&gt;</code>
+        * [~ShardedQueryResult](#module_entity-manager..ShardedQueryResult) : <code>object</code>
 
 <a name="module_entity-manager.EntityManager"></a>
 
@@ -231,7 +237,8 @@ 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>
-    * [.getKeySpace(entityToken, item, keyToken, timestamp)](#module_entity-manager.EntityManager+getKeySpace) ⇒ <code>Array.&lt;string&gt;</code>
+    * [.getKeySpace(entityToken, keyToken, item, timestamp)](#module_entity-manager.EntityManager+getKeySpace) ⇒ <code>Array.&lt;string&gt;</code>
+    * [.query(entityToken, keyToken, item, shardQuery, [shardPageKeys])](#module_entity-manager.EntityManager+query) ⇒ <code>Promise.&lt;ShardedQueryResult&gt;</code>
 
 <a name="new_module_entity-manager.EntityManager_new"></a>
 
@@ -272,7 +279,7 @@ Decorate an entity item with keys.
 
 <a name="module_entity-manager.EntityManager+getKeySpace"></a>
 
-#### entityManager.getKeySpace(entityToken, item, keyToken, timestamp) ⇒ <code>Array.&lt;string&gt;</code>
+#### entityManager.getKeySpace(entityToken, keyToken, item, timestamp) ⇒ <code>Array.&lt;string&gt;</code>
 Return an array of sharded keys valid for a given entity token & timestamp.
 
 **Kind**: instance method of [<code>EntityManager</code>](#module_entity-manager.EntityManager)  
@@ -288,10 +295,61 @@ Return an array of sharded keys valid for a given entity token & timestamp.
 | Param | Type | Description |
 | --- | --- | --- |
 | entityToken | <code>string</code> | Entity token. |
-| item | <code>object</code> | Entity item. |
 | keyToken | <code>string</code> | Key token. |
+| item | <code>object</code> | Entity item sufficiently populated to generate property keyToken. |
 | timestamp | <code>number</code> | Timestamp. |
 
+<a name="module_entity-manager.EntityManager+query"></a>
+
+#### entityManager.query(entityToken, keyToken, item, shardQuery, [shardPageKeys]) ⇒ <code>Promise.&lt;ShardedQueryResult&gt;</code>
+Query an entity across shards.
+
+**Kind**: instance method of [<code>EntityManager</code>](#module_entity-manager.EntityManager)  
+**Returns**: <code>Promise.&lt;ShardedQueryResult&gt;</code> - Sharded query result.  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| entityToken | <code>string</code> | Entity token. |
+| 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. |
+| [shardPageKeys] | <code>object</code> | Map of shard page keys. |
+
+<a name="module_entity-manager..ShardQueryResult"></a>
+
+### entity-manager~ShardQueryResult : <code>object</code>
+**Kind**: inner typedef of [<code>entity-manager</code>](#module_entity-manager)  
+**Properties**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| items | <code>Array.&lt;any&gt;</code> | Query result array. |
+| pageKey | <code>\*</code> | Shard page key. |
+
+<a name="module_entity-manager..ShardQueryFunction"></a>
+
+### entity-manager~ShardQueryFunction ⇒ <code>Promise.&lt;ShardQueryResult&gt;</code>
+Shard query function
+
+**Kind**: inner typedef of [<code>entity-manager</code>](#module_entity-manager)  
+**Returns**: <code>Promise.&lt;ShardQueryResult&gt;</code> - Sharded query result.  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| shardedKey | <code>string</code> | Sharded key. |
+| [pageKey] | <code>\*</code> | Page key. |
+
+<a name="module_entity-manager..ShardedQueryResult"></a>
+
+### entity-manager~ShardedQueryResult : <code>object</code>
+**Kind**: inner typedef of [<code>entity-manager</code>](#module_entity-manager)  
+**Properties**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| items | <code>Array.&lt;any&gt;</code> | Query result array. |
+| shardPageKeys | <code>object</code> | Shard page keys. |
+
 
 ---
 

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

@@ -4,6 +4,9 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.EntityManager = void 0;
+var _isUndefined2 = _interopRequireDefault(require("lodash/isUndefined"));
+var _map2 = _interopRequireDefault(require("lodash/map"));
+var _fromPairs2 = _interopRequireDefault(require("lodash/fromPairs"));
 var _sortedUniq2 = _interopRequireDefault(require("lodash/sortedUniq"));
 var _forEach2 = _interopRequireDefault(require("lodash/forEach"));
 var _isNil2 = _interopRequireDefault(require("lodash/isNil"));
@@ -84,6 +87,9 @@ class EntityManager {
       if (overwrite || (0, _isNil2.default)(item[key])) item[key] = getValue(item);
     });
     _classPrivateFieldGet(this, _entityManager).logger.debug('done', item);
+
+    // Remove undefined shardKey.
+    if ((0, _isNil2.default)(item[shardKeyToken])) delete item[shardKeyToken];
     return item;
   }
 
@@ -91,8 +97,8 @@ class EntityManager {
    * Return an array of sharded keys valid for a given entity token & timestamp.
    *
    * @param {string} entityToken - Entity token.
-   * @param {object} item - Entity item.
    * @param {string} keyToken - Key token.
+   * @param {object} item - Entity item sufficiently populated to generate property keyToken.
    * @param {number} timestamp - Timestamp.
    * @returns {string[]} Array of keys.
    * @throws {Error} If entityToken is invalid.
@@ -100,7 +106,7 @@ class EntityManager {
    * @throws {Error} If keyToken is invalid.
    * @throws {Error} If timestamp is invalid.
    */
-  getKeySpace(entityToken, item, keyToken) {
+  getKeySpace(entityToken, keyToken, item) {
     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);
@@ -111,5 +117,76 @@ class EntityManager {
     _classPrivateFieldGet(this, _entityManager).logger.debug('done', result);
     return result;
   }
+
+  /**
+   * @typedef {object} ShardQueryResult
+   * @property {any[]} items - Query result array.
+   * @property {*} pageKey - Shard page key.
+   */
+
+  /**
+   * Shard query function
+   *
+   * @callback ShardQueryFunction
+   * @param {string} shardedKey - Sharded key.
+   * @param {*} [pageKey] - Page key.
+   * @returns {Promise<ShardQueryResult>} Sharded query result.
+   */
+
+  /**
+   * @typedef {object} ShardedQueryResult
+   * @property {any[]} items - Query result array.
+   * @property {object} shardPageKeys - Shard page keys.
+   */
+
+  /**
+   * Query an entity across shards.
+   *
+   * @param {string} entityToken - Entity token.
+   * @param {string} keyToken - Key token.
+   * @param {object} item - Entity item sufficiently populated to generate property keyToken.
+   * @param {ShardQueryFunction} shardQuery - Sharded query function.
+   * @param {object} [shardPageKeys] - Map of shard page keys.
+   * @returns {Promise<ShardedQueryResult>} Sharded query result.
+   */
+  async query(entityToken, keyToken, item, shardQuery, shardPageKeys) {
+    // Generate default shardPageKeys if not provided
+    shardPageKeys ??= (0, _fromPairs2.default)(this.getKeySpace(entityToken, keyToken, item).map(shardedKey => [shardedKey, undefined]));
+
+    // Query every shard in shardPageKeys.
+    const shardQueryResults = await Promise.all((0, _map2.default)(shardPageKeys, (pageKey, shardedKey) => new Promise(resolve => shardQuery(shardedKey, pageKey).then(_ref2 => {
+      let {
+        items,
+        pageKey
+      } = _ref2;
+      return resolve({
+        shardedKey,
+        items,
+        pageKey
+      });
+    }))));
+
+    // Reduce shardQueryResults into a single result.
+    const result = shardQueryResults.reduce((shardedQueryResult, _ref3) => {
+      let {
+        shardedKey,
+        items,
+        pageKey
+      } = _ref3;
+      return {
+        items: [...shardedQueryResult.items, ...items],
+        shardPageKeys: {
+          ...shardedQueryResult.shardPageKeys,
+          ...((0, _isUndefined2.default)(pageKey) ? {} : {
+            [shardedKey]: pageKey
+          })
+        }
+      };
+    }, {
+      items: [],
+      shardPageKeys: {}
+    });
+    return result;
+  }
 }
 exports.EntityManager = EntityManager;

package/lib/EntityManager/EntityManager.js

@@ -68,6 +68,9 @@ export class EntityManager {
     });
     this.#entityManager.logger.debug('done', item);
 
+    // Remove undefined shardKey.
+    if (_.isNil(item[shardKeyToken])) delete item[shardKeyToken];
+
     return item;
   }
 
@@ -75,8 +78,8 @@ export class EntityManager {
    * Return an array of sharded keys valid for a given entity token & timestamp.
    *
    * @param {string} entityToken - Entity token.
-   * @param {object} item - Entity item.
    * @param {string} keyToken - Key token.
+   * @param {object} item - Entity item sufficiently populated to generate property keyToken.
    * @param {number} timestamp - Timestamp.
    * @returns {string[]} Array of keys.
    * @throws {Error} If entityToken is invalid.
@@ -84,7 +87,7 @@ export class EntityManager {
    * @throws {Error} If keyToken is invalid.
    * @throws {Error} If timestamp is invalid.
    */
-  getKeySpace(entityToken, item, keyToken, timestamp = Date.now()) {
+  getKeySpace(entityToken, keyToken, item, timestamp = Date.now()) {
     this.#entityManager.logger.debug(
       `getting shard key space for ${entityToken} on key '${keyToken}' at timestamp ${timestamp}...`,
       item
@@ -110,4 +113,72 @@ export class EntityManager {
 
     return result;
   }
+
+  /**
+   * @typedef {object} ShardQueryResult
+   * @property {any[]} items - Query result array.
+   * @property {*} pageKey - Shard page key.
+   */
+
+  /**
+   * Shard query function
+   *
+   * @callback ShardQueryFunction
+   * @param {string} shardedKey - Sharded key.
+   * @param {*} [pageKey] - Page key.
+   * @returns {Promise<ShardQueryResult>} Sharded query result.
+   */
+
+  /**
+   * @typedef {object} ShardedQueryResult
+   * @property {any[]} items - Query result array.
+   * @property {object} shardPageKeys - Shard page keys.
+   */
+
+  /**
+   * Query an entity across shards.
+   *
+   * @param {string} entityToken - Entity token.
+   * @param {string} keyToken - Key token.
+   * @param {object} item - Entity item sufficiently populated to generate property keyToken.
+   * @param {ShardQueryFunction} shardQuery - Sharded query function.
+   * @param {object} [shardPageKeys] - Map of shard page keys.
+   * @returns {Promise<ShardedQueryResult>} Sharded query result.
+   */
+  async query(entityToken, keyToken, item, shardQuery, shardPageKeys) {
+    // Generate default shardPageKeys if not provided
+    shardPageKeys ??= _.fromPairs(
+      this.getKeySpace(entityToken, keyToken, item).map((shardedKey) => [
+        shardedKey,
+        undefined,
+      ])
+    );
+
+    // Query every shard in shardPageKeys.
+    const shardQueryResults = await Promise.all(
+      _.map(
+        shardPageKeys,
+        (pageKey, shardedKey) =>
+          new Promise((resolve) =>
+            shardQuery(shardedKey, pageKey).then(({ items, pageKey }) =>
+              resolve({ shardedKey, items, pageKey })
+            )
+          )
+      )
+    );
+
+    // Reduce shardQueryResults into a single result.
+    const result = shardQueryResults.reduce(
+      (shardedQueryResult, { shardedKey, items, pageKey }) => ({
+        items: [...shardedQueryResult.items, ...items],
+        shardPageKeys: {
+          ...shardedQueryResult.shardPageKeys,
+          ...(_.isUndefined(pageKey) ? {} : { [shardedKey]: pageKey }),
+        },
+      }),
+      { items: [], shardPageKeys: {} }
+    );
+
+    return result;
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@karmaniverous/entity-manager",
-  "version": "0.0.11",
+  "version": "0.1.0",
   "publishConfig": {
     "access": "public"
   },
@@ -63,7 +63,8 @@
     "require": [
       "@babel/register"
     ],
-    "spec": "./**/*.test.!(*.*)"
+    "spec": "./**/*.test.!(*.*)",
+    "timeout": 60000
   },
   "release-it": {
     "github": {