@karmaniverous/entity-manager 6.7.0 → 6.7.2

package/dist/cjs/BaseShardQueryMapBuilder.js

@@ -29,6 +29,16 @@ class BaseShardQueryMapBuilder {
     build() {
         return radash.mapValues(this.indexParamsMap, (indexConfig, indexToken) => this.getShardQueryFunction(indexToken));
     }
+    async query(options) {
+        const { entityManager, entityToken, pageKeyMap } = this;
+        const shardQueryMap = this.build();
+        return await entityManager.query({
+            ...options,
+            entityToken,
+            pageKeyMap,
+            shardQueryMap,
+        });
+    }
 }
 
 exports.BaseShardQueryMapBuilder = BaseShardQueryMapBuilder;

package/dist/cjs/EntityManager.js

@@ -87,16 +87,7 @@ class EntityManager {
      * @throws Error if {@link QueryOptions.shardQueryMapBuilder | `shardQueryMapBuilder`} `pageKeyMap` keys do not match its `shardQueryMap` keys.
      */
     async query(options) {
-        const { shardQueryMapBuilder, ...baseOptions } = options;
-        const { entityToken, hashKeyToken, pageKeyMap } = shardQueryMapBuilder;
-        const shardQueryMap = shardQueryMapBuilder.build();
-        return await query.query(this, {
-            entityToken,
-            hashKeyToken,
-            pageKeyMap,
-            shardQueryMap,
-            ...baseOptions,
-        });
+        return await query.query(this, options);
     }
 }
 _EntityManager_config = new WeakMap();

package/dist/cjs/dehydrateIndexItem.js

@@ -21,14 +21,13 @@ var validateEntityIndexToken = require('./validateEntityIndexToken.js');
  * @param entityToken - {@link ConfigKeys.entities | `entityManager.config.entities`} key.
  * @param indexToken - {@link ConfigEntity.indexes | `entityManager.config.entities.<entityToken>.indexes`} key.
  * @param item - Partial {@link ItemMap | `ItemMap`} object.
- * @param omit - Array of index components to omit from the output value.
  *
  * @returns Dehydrated index value.
  *
  * @throws `Error` if `entityToken` is invalid.
  * @throws `Error` if `indexToken` is invalid.
  */
-function dehydrateIndexItem(entityManager, entityToken, indexToken, item, omit = []) {
+function dehydrateIndexItem(entityManager, entityToken, indexToken, item) {
     try {
         const { generatedKeyDelimiter } = entityManager.config;
         // Validate params.
@@ -37,7 +36,10 @@ function dehydrateIndexItem(entityManager, entityToken, indexToken, item, omit =
         if (!item)
             return '';
         // Unwrap index elements.
-        const elements = unwrapIndex.unwrapIndex(entityManager, entityToken, indexToken).filter((element) => !omit.includes(element));
+        const { hashKey } = entityManager.config.entities[entityToken].indexes[indexToken];
+        const elements = unwrapIndex.unwrapIndex(entityManager, entityToken, indexToken, [
+            hashKey,
+        ]);
         // Join index element values.
         const dehydrated = elements
             .map((element) => encodeEntityElement.encodeEntityElement(entityManager, entityToken, element, item))

package/dist/cjs/dehydratePageKeyMap.js

@@ -47,7 +47,7 @@ function dehydratePageKeyMap(entityManager, entityToken, pageKeyMap) {
         let dehydrated = [];
         for (const index of indexes) {
             for (const hashKey of hashKeys) {
-                // Undefineed pageKey.
+                // Undefined pageKey.
                 if (!pageKeyMap[index][hashKey]) {
                     dehydrated.push('');
                     continue;
@@ -62,9 +62,7 @@ function dehydratePageKeyMap(entityManager, entityToken, pageKeyMap) {
                     return item;
                 }, {});
                 // Dehydrate index from item.
-                dehydrated.push(dehydrateIndexItem.dehydrateIndexItem(entityManager, entityToken, index, item, [
-                    entityManager.config.hashKey,
-                ]));
+                dehydrated.push(dehydrateIndexItem.dehydrateIndexItem(entityManager, entityToken, index, item));
             }
         }
         // Replace with empty array if all pageKeys are empty strings.

package/dist/cjs/getHashKeySpace.js

@@ -1,13 +1,16 @@
 'use strict';
 
 var radash = require('radash');
-var validateEntityToken = require('./validateEntityToken.js');
+var encodeGeneratedProperty = require('./encodeGeneratedProperty.js');
+var validateEntityGeneratedProperty = require('./validateEntityGeneratedProperty.js');
 
 /**
  * Return an array of {@link ConfigKeys.hashKey | `entityManager.config.hashKey`} property values covering the shard space bounded by `timestampFrom` & `timestampTo`.
  *
  * @param entityManager - {@link EntityManager | `EntityManager`} instance.
  * @param entityToken - {@link ConfigKeys.entities | `entityManager.config.entities`} key.
+ * @param hashKeyToken - {@link ParsedConfig | `entityManager.config.hashKey`} or {@link ParsedConfig | `entityManager.config.entities.<entityToken>.generated`} key. If a generated property, must be shardable.
+ * @param item - Partial {@link ItemMap | `ItemMap[EntityToken]`} object. Must include all properties required to generate the hash key space.
  * @param timestampFrom - Lower timestanp limit. Defaults to `0`.
  * @param timestampTo - Upper timestamp limit. Defaults to `Date.now()`.
  *
@@ -15,24 +18,42 @@ var validateEntityToken = require('./validateEntityToken.js');
  *
  * @throws `Error` if `entityToken` is invalid.
  */
-function getHashKeySpace(entityManager, entityToken, timestampFrom = 0, timestampTo = Date.now()) {
+function getHashKeySpace(entityManager, entityToken, hashKeyToken, item, timestampFrom = 0, timestampTo = Date.now()) {
     try {
-        // Validate params.
-        validateEntityToken.validateEntityToken(entityManager, entityToken);
+        // Validate hashKeyToken is either the global hash key or a sharded generated property.
+        if (hashKeyToken !== entityManager.config.hashKey)
+            validateEntityGeneratedProperty.validateEntityGeneratedProperty(entityManager, entityToken, hashKeyToken, true);
         const { shardBumps } = entityManager.config.entities[entityToken];
         const hashKeySpace = shardBumps
+            // Filter shard bumps by timestamp range.
             .filter((bump, i) => (i === shardBumps.length - 1 ||
             shardBumps[i + 1].timestamp > timestampFrom) &&
             bump.timestamp <= timestampTo)
+            // Generate shard key space.
             .flatMap(({ charBits, chars }) => {
             const radix = 2 ** charBits;
             return chars
                 ? [...radash.range(0, radix ** chars - 1)].map((char) => char.toString(radix).padStart(chars, '0'))
                 : '';
         })
-            .map((shardKey) => `${entityToken}${entityManager.config.shardKeyDelimiter}${shardKey}`);
+            // Map shard keys to hash keys.
+            .map((shardKey) => {
+            // Calculate record hash key.
+            let hashKey = `${entityToken}${entityManager.config.shardKeyDelimiter}${shardKey}`;
+            // If hash key space basis is a different property, encode it.
+            if (hashKeyToken !== entityManager.config.hashKey)
+                hashKey = encodeGeneratedProperty.encodeGeneratedProperty(entityManager, entityToken, hashKeyToken, {
+                    ...item,
+                    [entityManager.config.hashKey]: hashKey,
+                });
+            if (!hashKey)
+                throw new Error('item does not support hash key space');
+            return hashKey;
+        });
         entityManager.logger.debug('generated hash key space', {
             entityToken,
+            hashKeyToken,
+            item,
             timestampFrom,
             timestampTo,
             hashKeySpace,
@@ -43,6 +64,8 @@ function getHashKeySpace(entityManager, entityToken, timestampFrom = 0, timestam
         if (error instanceof Error)
             entityManager.logger.error(error.message, {
                 entityToken,
+                hashKeyToken,
+                item,
                 timestampFrom,
                 timestampTo,
             });

package/dist/cjs/query.js

@@ -5,7 +5,6 @@ var lzString = require('lz-string');
 var radash = require('radash');
 var dehydratePageKeyMap = require('./dehydratePageKeyMap.js');
 var rehydratePageKeyMap = require('./rehydratePageKeyMap.js');
-var validateEntityGeneratedProperty = require('./validateEntityGeneratedProperty.js');
 
 const { compressToEncodedURIComponent, decompressFromEncodedURIComponent } = lzString;
 /**
@@ -27,20 +26,19 @@ const { compressToEncodedURIComponent, decompressFromEncodedURIComponent } = lzS
  *
  * @throws Error if {@link QueryOptions.pageKeyMap | `pageKeyMap`} keys do not match {@link QueryOptions.shardQueryMap | `shardQueryMap`} keys.
  */
-async function query(entityManager, { entityToken, hashKeyToken, limit, pageKeyMap, pageSize, shardQueryMap, sortOrder = [], timestampFrom = 0, timestampTo = Date.now(), throttle = entityManager.config.throttle, }) {
+async function query(entityManager, options) {
     try {
         // Get defaults.
-        const { defaultLimit, defaultPageSize } = entityManager.config.entities[entityToken];
-        limit ?? (limit = defaultLimit);
-        pageSize ?? (pageSize = defaultPageSize);
+        const { defaultLimit, defaultPageSize } = entityManager.config.entities[options.entityToken];
+        // Extract params.
+        const { entityToken, limit = defaultLimit, item, pageKeyMap, pageSize = defaultPageSize, shardQueryMap, sortOrder = [], timestampFrom = 0, timestampTo = Date.now(), throttle = entityManager.config.throttle, } = options;
         // Validate params.
-        validateEntityGeneratedProperty.validateEntityGeneratedProperty(entityManager, entityToken, hashKeyToken, true);
         if (!(limit === Infinity || (radash.isInt(limit) && limit >= 1)))
             throw new Error('limit must be a positive integer or Infinity.');
         if (!(radash.isInt(pageSize) && pageSize >= 1))
             throw new Error('pageSize must be a positive integer');
         // Rehydrate pageKeyMap.
-        const rehydratedPageKeyMap = rehydratePageKeyMap.rehydratePageKeyMap(entityManager, entityToken, Object.keys(shardQueryMap), pageKeyMap
+        const [hashKeyToken, rehydratedPageKeyMap] = rehydratePageKeyMap.rehydratePageKeyMap(entityManager, entityToken, Object.keys(shardQueryMap), item, pageKeyMap
             ? JSON.parse(decompressFromEncodedURIComponent(pageKeyMap))
             : undefined, timestampFrom, timestampTo);
         // Shortcut if pageKeyMap is empty.
@@ -61,18 +59,18 @@ async function query(entityManager, { entityToken, hashKeyToken, limit, pageKeyM
             // iteration in order to keep shardsQueried * pageSize > (limit - items.length) but only just.
             // TODO: Test for invalid characters (path delimiters) in index keys & shard key values.
             // Query every shard on every index in pageKeyMap.
-            const shardQueryResults = await radash.parallel(throttle, Object.entries(rehydratedPageKeyMap).flatMap(([index, indexPageKeys]) => Object.entries(indexPageKeys).map(([hashKey, pageKey]) => [
-                index,
+            const shardQueryResults = await radash.parallel(throttle, Object.entries(rehydratedPageKeyMap).flatMap(([indexToken, indexPageKeys]) => Object.entries(indexPageKeys).map(([hashKey, pageKey]) => [
+                indexToken,
                 hashKey,
                 pageKey,
-            ])), async ([index, hashKey, pageKey]) => ({
-                index,
-                queryResult: await shardQueryMap[index](hashKey, pageKey, pageSize),
+            ])), async ([indexToken, hashKey, pageKey]) => ({
+                indexToken,
+                queryResult: await shardQueryMap[indexToken](hashKey, pageKey, pageSize),
                 hashKey,
             }));
             // Reduce shardQueryResults & updateworkingRresult.
-            workingResult = shardQueryResults.reduce(({ items, pageKeyMap }, { index, queryResult, hashKey }) => {
-                Object.assign(rehydratedPageKeyMap[index], {
+            workingResult = shardQueryResults.reduce(({ items, pageKeyMap }, { indexToken, queryResult, hashKey }) => {
+                Object.assign(rehydratedPageKeyMap[indexToken], {
                     [hashKey]: queryResult.pageKey,
                 });
                 return {
@@ -93,15 +91,8 @@ async function query(entityManager, { entityToken, hashKeyToken, limit, pageKeyM
             pageKeyMap: compressToEncodedURIComponent(JSON.stringify(dehydratePageKeyMap.dehydratePageKeyMap(entityManager, entityToken, workingResult.pageKeyMap))),
         };
         entityManager.logger.debug('queried entityToken across shards', {
-            entityToken,
+            options,
             hashKeyToken,
-            limit,
-            pageKeyMap,
-            pageSize,
-            shardQueryMap,
-            timestampFrom,
-            timestampTo,
-            throttle,
             rehydratedPageKeyMap,
             workingResult,
             result,
@@ -110,17 +101,7 @@ async function query(entityManager, { entityToken, hashKeyToken, limit, pageKeyM
     }
     catch (error) {
         if (error instanceof Error)
-            entityManager.logger.error(error.message, {
-                entityToken,
-                hashKeyToken,
-                limit,
-                pageKeyMap,
-                pageSize,
-                shardQueryMap,
-                timestampFrom,
-                timestampTo,
-                throttle,
-            });
+            entityManager.logger.error(error.message, options);
         throw error;
     }
 }

package/dist/cjs/rehydrateIndexItem.js

@@ -17,20 +17,22 @@ var validateEntityIndexToken = require('./validateEntityIndexToken.js');
  * @param entityToken - {@link ConfigKeys.entities | `entityManager.config.entities`} key.
  * @param indexToken - {@link ConfigEntity.indexes | `entityManager.config.entities.<entityToken>.indexes`} key.
  * @param dehydrated - Dehydrated index value.
- * @param omit - Array of index components omitted from `dehydrated`.
  *
  * @returns Partial {@link ItemMap | `ItemMap`} object containing rehydrated index component elements.
  *
  * @throws `Error` if `entityToken` is invalid.
  * @throws `Error` if `indexToken` is invalid.
  */
-function rehydrateIndexItem(entityManager, entityToken, indexToken, dehydrated, omit = []) {
+function rehydrateIndexItem(entityManager, entityToken, indexToken, dehydrated) {
     try {
         const { generatedKeyDelimiter } = entityManager.config;
         // Validate params.
         validateEntityIndexToken.validateEntityIndexToken(entityManager, entityToken, indexToken);
         // Unwrap index elements.
-        const elements = unwrapIndex.unwrapIndex(entityManager, entityToken, indexToken).filter((element) => !omit.includes(element));
+        const { hashKey } = entityManager.config.entities[entityToken].indexes[indexToken];
+        const elements = unwrapIndex.unwrapIndex(entityManager, entityToken, indexToken, [
+            hashKey,
+        ]);
         // Split dehydrated value & validate.
         const values = dehydrated.split(generatedKeyDelimiter);
         if (elements.length !== values.length)

package/dist/cjs/rehydratePageKeyMap.js

@@ -1,6 +1,7 @@
 'use strict';
 
 var radash = require('radash');
+var decodeGeneratedProperty = require('./decodeGeneratedProperty.js');
 var encodeGeneratedProperty = require('./encodeGeneratedProperty.js');
 var getHashKeySpace = require('./getHashKeySpace.js');
 var getIndexComponents = require('./getIndexComponents.js');
@@ -16,28 +17,40 @@ var validateEntityIndexToken = require('./validateEntityIndexToken.js');
  * @param entityManager - {@link EntityManager | `EntityManager`} instance.
  * @param entityToken - {@link ConfigKeys.entities | `entityManager.config.entities`} key.
  * @param indexTokens - Array of {@link ConfigEntity.indexes | `entityManager.config.entities.<entityToken>.indexes`} keys used as keys of the original {@link PageKeyMap | `PageKeyMap`}.
+ * @param item - Partial item object sufficiently populated to generate index hash keys.
  * @param dehydrated - Array of dehydrated page keys or undefined if new query.
  * @param timestampFrom - Lower timestanp limit used to generate the original {@link PageKeyMap | `PageKeyMap`}. Defaults to `0`.
  * @param timestampTo - Upper timestamp limit used to generate the original {@link PageKeyMap | `PageKeyMap`}. Defaults to `Date.now()`.
  *
- * @returns Rehydrated {@link PageKeyMap | `PageKeyMap`} object.
+ * @returns A tuple of `hashKeyToken` and rehydrated {@link PageKeyMap | `PageKeyMap`} object.
  *
  * @throws `Error` if `entityToken` is invalid.
  * @throws `Error` if `indexTokens` is empty.
  * @throws `Error` if any `indexTokens` are invalid.
+ * @throws `Error` if `indexTokens` represent indexes with inconsistent hashKeys.
  * @throws `Error` if `dehydrated` has invalid length.
  */
-function rehydratePageKeyMap(entityManager, entityToken, indexTokens, dehydrated, timestampFrom = 0, timestampTo = Date.now()) {
+function rehydratePageKeyMap(entityManager, entityToken, indexTokens, item, dehydrated, timestampFrom = 0, timestampTo = Date.now()) {
     try {
-        // Validate params.
+        // Validate indexTokens populated.
         if (!indexTokens.length)
             throw new Error('indexTokens empty');
+        // Validate indexTokens exist.
+        const hashKeys = radash.unique(indexTokens.map((indexToken) => {
+            validateEntityIndexToken.validateEntityIndexToken(entityManager, entityToken, indexToken);
+            return entityManager.config.entities[entityToken].indexes[indexToken]
+                .hashKey;
+        }));
+        // Validate hashKeys consistent.
+        if (hashKeys.length > 1)
+            throw new Error('inconsistent hashKeys');
+        const [hashKeyToken] = hashKeys;
         indexTokens.map((index) => validateEntityIndexToken.validateEntityIndexToken(entityManager, entityToken, index));
         // Shortcut empty dehydrated.
         if (dehydrated && !dehydrated.length)
-            return {};
+            return [hashKeyToken, {}];
         // Get hash key space.
-        const hashKeySpace = getHashKeySpace.getHashKeySpace(entityManager, entityToken, timestampFrom, timestampTo);
+        const hashKeySpace = getHashKeySpace.getHashKeySpace(entityManager, entityToken, hashKeyToken, item, timestampFrom, timestampTo);
         // Default dehydrated.
         dehydrated ?? (dehydrated = [...radash.range(1, hashKeySpace.length * indexTokens.length, '')]);
         // Validate dehydrated length
@@ -47,14 +60,14 @@ function rehydratePageKeyMap(entityManager, entityToken, indexTokens, dehydrated
         const rehydrated = radash.mapValues(radash.zipToObject(indexTokens, radash.cluster(dehydrated, hashKeySpace.length)), (dehydratedIndexPageKeyMaps, index) => radash.zipToObject(hashKeySpace, (hashKey, i) => {
             if (!dehydratedIndexPageKeyMaps[i])
                 return;
-            let item = {
-                [entityManager.config.hashKey]: hashKey,
-                ...rehydrateIndexItem.rehydrateIndexItem(entityManager, entityToken, index, dehydratedIndexPageKeyMaps[i], [entityManager.config.hashKey]),
+            let pageKeyItem = {
+                ...decodeGeneratedProperty.decodeGeneratedProperty(entityManager, entityToken, hashKey),
+                ...rehydrateIndexItem.rehydrateIndexItem(entityManager, entityToken, index, dehydratedIndexPageKeyMaps[i]),
             };
-            item = updateItemRangeKey.updateItemRangeKey(entityManager, entityToken, item);
+            pageKeyItem = updateItemRangeKey.updateItemRangeKey(entityManager, entityToken, pageKeyItem);
             return radash.zipToObject(getIndexComponents.getIndexComponents(entityManager, entityToken, index), (component) => entityManager.config.entities[entityToken].generated[component]
-                ? encodeGeneratedProperty.encodeGeneratedProperty(entityManager, entityToken, component, item)
-                : item[component]);
+                ? encodeGeneratedProperty.encodeGeneratedProperty(entityManager, entityToken, component, pageKeyItem)
+                : pageKeyItem[component]);
         }));
         entityManager.logger.debug('rehydrated page key map', {
             entityToken,
@@ -62,7 +75,7 @@ function rehydratePageKeyMap(entityManager, entityToken, indexTokens, dehydrated
             dehydrated,
             rehydrated,
         });
-        return rehydrated;
+        return [hashKeyToken, rehydrated];
     }
     catch (error) {
         if (error instanceof Error)

package/dist/cjs/unwrapIndex.js

@@ -10,28 +10,30 @@ var validateEntityIndexToken = require('./validateEntityIndexToken.js');
  * @param entityManager - {@link EntityManager | `EntityManager`} instance.
  * @param entityToken - {@link ConfigKeys.entities | `entityManager.config.entities`} key.
  * @param indexToken - {@link ConfigEntity.indexes | `entityManager.config.entities.<entityToken>.indexes`} key.
+ * @param omit - Array of index components or elements to omit from the output value.
  *
  * @returns Deduped, sorted array of ungenerated index component elements.
  *
  * @throws `Error` if `entityToken` is invalid.
  * @throws `Error` if `indexToken` is invalid.
  */
-function unwrapIndex(entityManager, entityToken, indexToken) {
+function unwrapIndex(entityManager, entityToken, indexToken, omit = []) {
     try {
         // Validate params.
         validateEntityIndexToken.validateEntityIndexToken(entityManager, entityToken, indexToken);
         const generated = entityManager.config.entities[entityToken].generated;
         const generatedKeys = Object.keys(radash.shake(generated));
-        return getIndexComponents.getIndexComponents(entityManager, entityToken, indexToken)
+        return radash.unique(getIndexComponents.getIndexComponents(entityManager, entityToken, indexToken)
+            .filter((component) => !omit.includes(component))
             .map((component) => component === entityManager.config.hashKey
-            ? entityManager.config.hashKey
+            ? entityManager.config.entities[entityToken].timestampProperty
             : component === entityManager.config.rangeKey
                 ? entityManager.config.entities[entityToken].uniqueProperty
                 : generatedKeys.includes(component)
                     ? generated[component].elements
                     : component)
             .flat()
-            .sort();
+            .filter((element) => !omit.includes(element))).sort();
     }
     catch (error) {
         if (error instanceof Error)

package/dist/index.d.ts

@@ -363,6 +363,137 @@ type ItemMap<M extends EntityMap, HashKey extends string = 'hashKey', RangeKey e
     } & Partial<Record<HashKey | RangeKey, string>>>;
 };
 
+/**
+ * A result returned by a query across multiple shards, where each shard may
+ * receive multiple page queries via a dynamically-generated {@link ShardQueryFunction | `ShardQueryFunction`}.
+ *
+ * @category Query
+ */
+interface QueryResult<Item extends ItemMap<M, HashKey, RangeKey>[EntityToken], EntityToken extends keyof Exactify<M> & string, M extends EntityMap, HashKey extends string, RangeKey extends string> {
+    /** Total number of records returned across all shards. */
+    count: number;
+    /** The returned records. */
+    items: Item[];
+    /**
+     * A compressed, two-layer map of page keys, used to query the next page of
+     * data for a given sort key on each shard of a given hash key.
+     */
+    pageKeyMap: string;
+}
+
+/**
+ * A result returned by a {@link ShardQueryFunction | `ShardQueryFunction`} querying an individual shard.
+ *
+ * @typeParam Item - The {@link Item | `Item`} type being queried.
+
+* @category Query
+ */
+interface ShardQueryResult<Item extends Entity> {
+    /** The number of records returned. */
+    count: number;
+    /** The returned records. */
+    items: Item[];
+    /** The page key for the next query on this shard. */
+    pageKey?: Partial<Item>;
+}
+
+/**
+ * A query function that returns a single page of results from an individual
+ * shard. This function will typically be composed dynamically to express a
+ * specific query index & logic. The arguments to this function will be
+ * provided by the {@link EntityManager.query | `EntityManager.query`} method, which assembles many returned
+ * pages queried across multiple shards into a single query result.
+ *
+ * @typeParam Item - The {@link Item | `Item`} type being queried.
+
+ * @param hashKey - The hash key value of the shard being queried.
+ * @param pageKey - The page key returned by the previous query on this shard.
+ * @param pageSize - The maximum number of items to return from this query.
+ *
+ * @category Query
+ */
+type ShardQueryFunction<Item extends Entity> = (hashKey: string, pageKey?: Partial<Item>, pageSize?: number) => Promise<ShardQueryResult<Item>>;
+
+type ShardQueryMap<Item extends Entity> = Record<string, ShardQueryFunction<Item>>;
+
+/**
+ * Options passed to the {@link query | `query`} function.
+ *
+ * @category Query
+ */
+interface QueryOptions<Item extends ItemMap<M, HashKey, RangeKey>[EntityToken], EntityToken extends keyof Exactify<M> & string, M extends EntityMap, HashKey extends string, RangeKey extends string> {
+    /** Identifies the entity to be queried. Key of {@link Config | `EntityManager.config.entities`}. */
+    entityToken: EntityToken;
+    /**
+     * Partial item object sufficiently populated to generate index hash keys.
+     */
+    item: Partial<Item>;
+    /**
+     * The target maximum number of records to be returned by the query across
+     * all shards.
+     *
+     * The actual number of records returned will be a product of {@link QueryOptions.pageSize | `pageSize`} and the
+     * number of shards queried, unless limited by available records in a given
+     * shard.
+     */
+    limit?: number;
+    /**
+     * {@link QueryResult.pageKeyMap | `pageKeyMap`} returned by the previous iteration of this query.
+     */
+    pageKeyMap?: string;
+    /**
+     * The maximum number of records to be returned by each individual query to a
+     * single shard (i.e. {@link ShardQueryFunction | `ShardQueryFunction`} execution).
+     *
+     * Note that, within a given {@link EntityManager.query | `query`} method execution, these queries will be
+     * repeated until either available data is exhausted or the {@link QueryOptions.limit | `limit`} value is
+     * reached.
+     */
+    pageSize?: number;
+    /**
+     * Each key in this object is a valid entity index token. Each value is a valid
+     * {@link ShardQueryFunction | 'ShardQueryFunction'} that specifies the query of a single page of data on a
+     * single shard for the mapped index.
+     *
+     * This allows simultaneous queries on multiple sort keys to share a single
+     * page key, e.g. to match the same string against `firstName` and `lastName`
+     * properties without performing a table scan for either.
+     */
+    shardQueryMap: ShardQueryMap<Item>;
+    /**
+     * A {@link SortOrder | `SortOrder`} object specifying the sort order of the result set. Defaults to `[]`.
+     */
+    sortOrder?: SortOrder<Item>;
+    /**
+     * Lower limit to query shard space.
+     *
+     * Only valid if the query is constrained along the dimension used by the
+     * {@link Config | `EntityManager.config.entities.<entityToken>.sharding.timestamptokens.timestamp`}
+     * function to generate `shardKey`.
+     *
+     * @defaultValue `0`
+     */
+    timestampFrom?: number;
+    /**
+     * Upper limit to query shard space.
+     *
+     * Only valid if the query is constrained along the dimension used by the
+     * {@link Config | `EntityManager.config.entities.<entityToken>.sharding.timestamptokens.timestamp`}
+     * function to generate `shardKey`.
+     *
+     * @defaultValue `Date.now()`
+     */
+    timestampTo?: number;
+    /**
+     * The maximum number of shards to query in parallel. Overrides options `throttle`.
+     *
+     * @defaultValue `options.throttle`
+     */
+    throttle?: number;
+}
+
+type BuilderQueryOptions<Item extends ItemMap<M, HashKey, RangeKey>[EntityToken], EntityToken extends keyof Exactify<M> & string, M extends EntityMap, HashKey extends string, RangeKey extends string> = Omit<QueryOptions<Item, EntityToken, M, HashKey, RangeKey>, 'entityToken' | 'pageKeyMap' | 'shardQueryMap'>;
+
 declare const configSchema: z.ZodEffects<z.ZodObject<{
     entities: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodObject<{
         defaultLimit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
@@ -674,90 +805,6 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
  */
 type ParsedConfig = z.infer<typeof configSchema>;
 
-/**
- * Base type of options passed to the {@link EntityManager.query | `EntityManager.query`} method.
- *
- * @category Query
- */
-interface BaseQueryOptions<Item extends ItemMap<M, HashKey, RangeKey>[EntityToken], EntityToken extends keyof Exactify<M> & string, M extends EntityMap, HashKey extends string, RangeKey extends string> {
-    /**
-     * The target maximum number of records to be returned by the query across
-     * all shards.
-     *
-     * The actual number of records returned will be a product of {@link QueryOptions.pageSize | `pageSize`} and the
-     * number of shards queried, unless limited by available records in a given
-     * shard.
-     */
-    limit?: number;
-    /**
-     * The maximum number of records to be returned by each individual query to a
-     * single shard (i.e. {@link ShardQueryFunction | `ShardQueryFunction`} execution).
-     *
-     * Note that, within a given {@link EntityManager.query | `query`} method execution, these queries will be
-     * repeated until either available data is exhausted or the {@link QueryOptions.limit | `limit`} value is
-     * reached.
-     */
-    pageSize?: number;
-    /**
-     * A {@link SortOrder | `SortOrder`} object specifying the sort order of the result set. Defaults to `[]`.
-     */
-    sortOrder?: SortOrder<Item>;
-    /**
-     * Lower limit to query shard space.
-     *
-     * Only valid if the query is constrained along the dimension used by the
-     * {@link Config | `EntityManager.config.entities.<entityToken>.sharding.timestamptokens.timestamp`}
-     * function to generate `shardKey`.
-     *
-     * @defaultValue `0`
-     */
-    timestampFrom?: number;
-    /**
-     * Upper limit to query shard space.
-     *
-     * Only valid if the query is constrained along the dimension used by the
-     * {@link Config | `EntityManager.config.entities.<entityToken>.sharding.timestamptokens.timestamp`}
-     * function to generate `shardKey`.
-     *
-     * @defaultValue `Date.now()`
-     */
-    timestampTo?: number;
-    /**
-     * The maximum number of shards to query in parallel. Overrides options `throttle`.
-     *
-     * @defaultValue `options.throttle`
-     */
-    throttle?: number;
-}
-
-/**
- * Options passed to the {@link EntityManager.query | `EntityManager.query`} method.
- *
- * @category Query
- */
-interface QueryOptions<IndexParams, Item extends ItemMap<M, HashKey, RangeKey>[EntityToken], EntityToken extends keyof Exactify<M> & string, M extends EntityMap, HashKey extends string, RangeKey extends string, T extends TranscodeMap> extends BaseQueryOptions<Item, EntityToken, M, HashKey, RangeKey> {
-    /** Instance of class extending {@link BaseShardQueryMapBuilder | `BaseShardQueryMapBuilder`}. */
-    shardQueryMapBuilder: BaseShardQueryMapBuilder<IndexParams, Item, EntityToken, M, HashKey, RangeKey, T>;
-}
-
-/**
- * A result returned by a query across multiple shards, where each shard may
- * receive multiple page queries via a dynamically-generated {@link ShardQueryFunction | `ShardQueryFunction`}.
- *
- * @category Query
- */
-interface QueryResult<Item extends ItemMap<M, HashKey, RangeKey>[EntityToken], EntityToken extends keyof Exactify<M> & string, M extends EntityMap, HashKey extends string, RangeKey extends string> {
-    /** Total number of records returned across all shards. */
-    count: number;
-    /** The returned records. */
-    items: Item[];
-    /**
-     * A compressed, two-layer map of page keys, used to query the next page of
-     * data for a given sort key on each shard of a given hash key.
-     */
-    pageKeyMap: string;
-}
-
 /**
  * The EntityManager class applies a configuration-driven sharded data model &
  * query strategy to NoSql data.
@@ -827,44 +874,9 @@ declare class EntityManager<M extends EntityMap, HashKey extends string, RangeKe
      *
      * @throws Error if {@link QueryOptions.shardQueryMapBuilder | `shardQueryMapBuilder`} `pageKeyMap` keys do not match its `shardQueryMap` keys.
      */
-    query<IndexParams, Item extends ItemMap<M, HashKey, RangeKey>[EntityToken], EntityToken extends keyof Exactify<M> & string>(options: QueryOptions<IndexParams, Item, EntityToken, M, HashKey, RangeKey, T>): Promise<QueryResult<Item, EntityToken, M, HashKey, RangeKey>>;
+    query<Item extends ItemMap<M, HashKey, RangeKey>[EntityToken], EntityToken extends keyof Exactify<M> & string>(options: QueryOptions<Item, EntityToken, M, HashKey, RangeKey>): Promise<QueryResult<Item, EntityToken, M, HashKey, RangeKey>>;
 }
 
-/**
- * A result returned by a {@link ShardQueryFunction | `ShardQueryFunction`} querying an individual shard.
- *
- * @typeParam Item - The {@link Item | `Item`} type being queried.
-
-* @category Query
- */
-interface ShardQueryResult<Item extends Entity> {
-    /** The number of records returned. */
-    count: number;
-    /** The returned records. */
-    items: Item[];
-    /** The page key for the next query on this shard. */
-    pageKey?: Partial<Item>;
-}
-
-/**
- * A query function that returns a single page of results from an individual
- * shard. This function will typically be composed dynamically to express a
- * specific query index & logic. The arguments to this function will be
- * provided by the {@link EntityManager.query | `EntityManager.query`} method, which assembles many returned
- * pages queried across multiple shards into a single query result.
- *
- * @typeParam Item - The {@link Item | `Item`} type being queried.
-
- * @param hashKey - The hash key value of the shard being queried.
- * @param pageKey - The page key returned by the previous query on this shard.
- * @param pageSize - The maximum number of items to return from this query.
- *
- * @category Query
- */
-type ShardQueryFunction<Item extends Entity> = (hashKey: string, pageKey?: Partial<Item>, pageSize?: number) => Promise<ShardQueryResult<Item>>;
-
-type ShardQueryMap<Item extends Entity> = Record<string, ShardQueryFunction<Item>>;
-
 /**
  * Abstract base class supporting a fluent API for building a {@link ShardQueryMap | `ShardQueryMap`} using a database client.
  *
@@ -890,6 +902,7 @@ declare abstract class BaseShardQueryMapBuilder<IndexParams, Item extends ItemMa
      * @returns - The {@link ShardQueryMap | `ShardQueryMap`} object.
      */
     build(): ShardQueryMap<Item>;
+    query(options: BuilderQueryOptions<Item, EntityToken, M, HashKey, RangeKey>): Promise<QueryResult<Item, EntityToken, M, HashKey, RangeKey>>;
 }
 
 /**

package/dist/mjs/BaseShardQueryMapBuilder.js

@@ -27,6 +27,16 @@ class BaseShardQueryMapBuilder {
     build() {
         return mapValues(this.indexParamsMap, (indexConfig, indexToken) => this.getShardQueryFunction(indexToken));
     }
+    async query(options) {
+        const { entityManager, entityToken, pageKeyMap } = this;
+        const shardQueryMap = this.build();
+        return await entityManager.query({
+            ...options,
+            entityToken,
+            pageKeyMap,
+            shardQueryMap,
+        });
+    }
 }
 
 export { BaseShardQueryMapBuilder };

package/dist/mjs/EntityManager.js

@@ -85,16 +85,7 @@ class EntityManager {
      * @throws Error if {@link QueryOptions.shardQueryMapBuilder | `shardQueryMapBuilder`} `pageKeyMap` keys do not match its `shardQueryMap` keys.
      */
     async query(options) {
-        const { shardQueryMapBuilder, ...baseOptions } = options;
-        const { entityToken, hashKeyToken, pageKeyMap } = shardQueryMapBuilder;
-        const shardQueryMap = shardQueryMapBuilder.build();
-        return await query(this, {
-            entityToken,
-            hashKeyToken,
-            pageKeyMap,
-            shardQueryMap,
-            ...baseOptions,
-        });
+        return await query(this, options);
     }
 }
 _EntityManager_config = new WeakMap();

package/dist/mjs/dehydrateIndexItem.js

@@ -19,14 +19,13 @@ import { validateEntityIndexToken } from './validateEntityIndexToken.js';
  * @param entityToken - {@link ConfigKeys.entities | `entityManager.config.entities`} key.
  * @param indexToken - {@link ConfigEntity.indexes | `entityManager.config.entities.<entityToken>.indexes`} key.
  * @param item - Partial {@link ItemMap | `ItemMap`} object.
- * @param omit - Array of index components to omit from the output value.
  *
  * @returns Dehydrated index value.
  *
  * @throws `Error` if `entityToken` is invalid.
  * @throws `Error` if `indexToken` is invalid.
  */
-function dehydrateIndexItem(entityManager, entityToken, indexToken, item, omit = []) {
+function dehydrateIndexItem(entityManager, entityToken, indexToken, item) {
     try {
         const { generatedKeyDelimiter } = entityManager.config;
         // Validate params.
@@ -35,7 +34,10 @@ function dehydrateIndexItem(entityManager, entityToken, indexToken, item, omit =
         if (!item)
             return '';
         // Unwrap index elements.
-        const elements = unwrapIndex(entityManager, entityToken, indexToken).filter((element) => !omit.includes(element));
+        const { hashKey } = entityManager.config.entities[entityToken].indexes[indexToken];
+        const elements = unwrapIndex(entityManager, entityToken, indexToken, [
+            hashKey,
+        ]);
         // Join index element values.
         const dehydrated = elements
             .map((element) => encodeEntityElement(entityManager, entityToken, element, item))

package/dist/mjs/dehydratePageKeyMap.js

@@ -45,7 +45,7 @@ function dehydratePageKeyMap(entityManager, entityToken, pageKeyMap) {
         let dehydrated = [];
         for (const index of indexes) {
             for (const hashKey of hashKeys) {
-                // Undefineed pageKey.
+                // Undefined pageKey.
                 if (!pageKeyMap[index][hashKey]) {
                     dehydrated.push('');
                     continue;
@@ -60,9 +60,7 @@ function dehydratePageKeyMap(entityManager, entityToken, pageKeyMap) {
                     return item;
                 }, {});
                 // Dehydrate index from item.
-                dehydrated.push(dehydrateIndexItem(entityManager, entityToken, index, item, [
-                    entityManager.config.hashKey,
-                ]));
+                dehydrated.push(dehydrateIndexItem(entityManager, entityToken, index, item));
             }
         }
         // Replace with empty array if all pageKeys are empty strings.

package/dist/mjs/getHashKeySpace.js

@@ -1,11 +1,14 @@
 import { range } from 'radash';
-import { validateEntityToken } from './validateEntityToken.js';
+import { encodeGeneratedProperty } from './encodeGeneratedProperty.js';
+import { validateEntityGeneratedProperty } from './validateEntityGeneratedProperty.js';
 
 /**
  * Return an array of {@link ConfigKeys.hashKey | `entityManager.config.hashKey`} property values covering the shard space bounded by `timestampFrom` & `timestampTo`.
  *
  * @param entityManager - {@link EntityManager | `EntityManager`} instance.
  * @param entityToken - {@link ConfigKeys.entities | `entityManager.config.entities`} key.
+ * @param hashKeyToken - {@link ParsedConfig | `entityManager.config.hashKey`} or {@link ParsedConfig | `entityManager.config.entities.<entityToken>.generated`} key. If a generated property, must be shardable.
+ * @param item - Partial {@link ItemMap | `ItemMap[EntityToken]`} object. Must include all properties required to generate the hash key space.
  * @param timestampFrom - Lower timestanp limit. Defaults to `0`.
  * @param timestampTo - Upper timestamp limit. Defaults to `Date.now()`.
  *
@@ -13,24 +16,42 @@ import { validateEntityToken } from './validateEntityToken.js';
  *
  * @throws `Error` if `entityToken` is invalid.
  */
-function getHashKeySpace(entityManager, entityToken, timestampFrom = 0, timestampTo = Date.now()) {
+function getHashKeySpace(entityManager, entityToken, hashKeyToken, item, timestampFrom = 0, timestampTo = Date.now()) {
     try {
-        // Validate params.
-        validateEntityToken(entityManager, entityToken);
+        // Validate hashKeyToken is either the global hash key or a sharded generated property.
+        if (hashKeyToken !== entityManager.config.hashKey)
+            validateEntityGeneratedProperty(entityManager, entityToken, hashKeyToken, true);
         const { shardBumps } = entityManager.config.entities[entityToken];
         const hashKeySpace = shardBumps
+            // Filter shard bumps by timestamp range.
             .filter((bump, i) => (i === shardBumps.length - 1 ||
             shardBumps[i + 1].timestamp > timestampFrom) &&
             bump.timestamp <= timestampTo)
+            // Generate shard key space.
             .flatMap(({ charBits, chars }) => {
             const radix = 2 ** charBits;
             return chars
                 ? [...range(0, radix ** chars - 1)].map((char) => char.toString(radix).padStart(chars, '0'))
                 : '';
         })
-            .map((shardKey) => `${entityToken}${entityManager.config.shardKeyDelimiter}${shardKey}`);
+            // Map shard keys to hash keys.
+            .map((shardKey) => {
+            // Calculate record hash key.
+            let hashKey = `${entityToken}${entityManager.config.shardKeyDelimiter}${shardKey}`;
+            // If hash key space basis is a different property, encode it.
+            if (hashKeyToken !== entityManager.config.hashKey)
+                hashKey = encodeGeneratedProperty(entityManager, entityToken, hashKeyToken, {
+                    ...item,
+                    [entityManager.config.hashKey]: hashKey,
+                });
+            if (!hashKey)
+                throw new Error('item does not support hash key space');
+            return hashKey;
+        });
         entityManager.logger.debug('generated hash key space', {
             entityToken,
+            hashKeyToken,
+            item,
             timestampFrom,
             timestampTo,
             hashKeySpace,
@@ -41,6 +62,8 @@ function getHashKeySpace(entityManager, entityToken, timestampFrom = 0, timestam
         if (error instanceof Error)
             entityManager.logger.error(error.message, {
                 entityToken,
+                hashKeyToken,
+                item,
                 timestampFrom,
                 timestampTo,
             });

package/dist/mjs/query.js

@@ -3,7 +3,6 @@ import lzString from 'lz-string';
 import { isInt, parallel, unique } from 'radash';
 import { dehydratePageKeyMap } from './dehydratePageKeyMap.js';
 import { rehydratePageKeyMap } from './rehydratePageKeyMap.js';
-import { validateEntityGeneratedProperty } from './validateEntityGeneratedProperty.js';
 
 const { compressToEncodedURIComponent, decompressFromEncodedURIComponent } = lzString;
 /**
@@ -25,20 +24,19 @@ const { compressToEncodedURIComponent, decompressFromEncodedURIComponent } = lzS
  *
  * @throws Error if {@link QueryOptions.pageKeyMap | `pageKeyMap`} keys do not match {@link QueryOptions.shardQueryMap | `shardQueryMap`} keys.
  */
-async function query(entityManager, { entityToken, hashKeyToken, limit, pageKeyMap, pageSize, shardQueryMap, sortOrder = [], timestampFrom = 0, timestampTo = Date.now(), throttle = entityManager.config.throttle, }) {
+async function query(entityManager, options) {
     try {
         // Get defaults.
-        const { defaultLimit, defaultPageSize } = entityManager.config.entities[entityToken];
-        limit ?? (limit = defaultLimit);
-        pageSize ?? (pageSize = defaultPageSize);
+        const { defaultLimit, defaultPageSize } = entityManager.config.entities[options.entityToken];
+        // Extract params.
+        const { entityToken, limit = defaultLimit, item, pageKeyMap, pageSize = defaultPageSize, shardQueryMap, sortOrder = [], timestampFrom = 0, timestampTo = Date.now(), throttle = entityManager.config.throttle, } = options;
         // Validate params.
-        validateEntityGeneratedProperty(entityManager, entityToken, hashKeyToken, true);
         if (!(limit === Infinity || (isInt(limit) && limit >= 1)))
             throw new Error('limit must be a positive integer or Infinity.');
         if (!(isInt(pageSize) && pageSize >= 1))
             throw new Error('pageSize must be a positive integer');
         // Rehydrate pageKeyMap.
-        const rehydratedPageKeyMap = rehydratePageKeyMap(entityManager, entityToken, Object.keys(shardQueryMap), pageKeyMap
+        const [hashKeyToken, rehydratedPageKeyMap] = rehydratePageKeyMap(entityManager, entityToken, Object.keys(shardQueryMap), item, pageKeyMap
             ? JSON.parse(decompressFromEncodedURIComponent(pageKeyMap))
             : undefined, timestampFrom, timestampTo);
         // Shortcut if pageKeyMap is empty.
@@ -59,18 +57,18 @@ async function query(entityManager, { entityToken, hashKeyToken, limit, pageKeyM
             // iteration in order to keep shardsQueried * pageSize > (limit - items.length) but only just.
             // TODO: Test for invalid characters (path delimiters) in index keys & shard key values.
             // Query every shard on every index in pageKeyMap.
-            const shardQueryResults = await parallel(throttle, Object.entries(rehydratedPageKeyMap).flatMap(([index, indexPageKeys]) => Object.entries(indexPageKeys).map(([hashKey, pageKey]) => [
-                index,
+            const shardQueryResults = await parallel(throttle, Object.entries(rehydratedPageKeyMap).flatMap(([indexToken, indexPageKeys]) => Object.entries(indexPageKeys).map(([hashKey, pageKey]) => [
+                indexToken,
                 hashKey,
                 pageKey,
-            ])), async ([index, hashKey, pageKey]) => ({
-                index,
-                queryResult: await shardQueryMap[index](hashKey, pageKey, pageSize),
+            ])), async ([indexToken, hashKey, pageKey]) => ({
+                indexToken,
+                queryResult: await shardQueryMap[indexToken](hashKey, pageKey, pageSize),
                 hashKey,
             }));
             // Reduce shardQueryResults & updateworkingRresult.
-            workingResult = shardQueryResults.reduce(({ items, pageKeyMap }, { index, queryResult, hashKey }) => {
-                Object.assign(rehydratedPageKeyMap[index], {
+            workingResult = shardQueryResults.reduce(({ items, pageKeyMap }, { indexToken, queryResult, hashKey }) => {
+                Object.assign(rehydratedPageKeyMap[indexToken], {
                     [hashKey]: queryResult.pageKey,
                 });
                 return {
@@ -91,15 +89,8 @@ async function query(entityManager, { entityToken, hashKeyToken, limit, pageKeyM
             pageKeyMap: compressToEncodedURIComponent(JSON.stringify(dehydratePageKeyMap(entityManager, entityToken, workingResult.pageKeyMap))),
         };
         entityManager.logger.debug('queried entityToken across shards', {
-            entityToken,
+            options,
             hashKeyToken,
-            limit,
-            pageKeyMap,
-            pageSize,
-            shardQueryMap,
-            timestampFrom,
-            timestampTo,
-            throttle,
             rehydratedPageKeyMap,
             workingResult,
             result,
@@ -108,17 +99,7 @@ async function query(entityManager, { entityToken, hashKeyToken, limit, pageKeyM
     }
     catch (error) {
         if (error instanceof Error)
-            entityManager.logger.error(error.message, {
-                entityToken,
-                hashKeyToken,
-                limit,
-                pageKeyMap,
-                pageSize,
-                shardQueryMap,
-                timestampFrom,
-                timestampTo,
-                throttle,
-            });
+            entityManager.logger.error(error.message, options);
         throw error;
     }
 }

package/dist/mjs/rehydrateIndexItem.js

@@ -15,20 +15,22 @@ import { validateEntityIndexToken } from './validateEntityIndexToken.js';
  * @param entityToken - {@link ConfigKeys.entities | `entityManager.config.entities`} key.
  * @param indexToken - {@link ConfigEntity.indexes | `entityManager.config.entities.<entityToken>.indexes`} key.
  * @param dehydrated - Dehydrated index value.
- * @param omit - Array of index components omitted from `dehydrated`.
  *
  * @returns Partial {@link ItemMap | `ItemMap`} object containing rehydrated index component elements.
  *
  * @throws `Error` if `entityToken` is invalid.
  * @throws `Error` if `indexToken` is invalid.
  */
-function rehydrateIndexItem(entityManager, entityToken, indexToken, dehydrated, omit = []) {
+function rehydrateIndexItem(entityManager, entityToken, indexToken, dehydrated) {
     try {
         const { generatedKeyDelimiter } = entityManager.config;
         // Validate params.
         validateEntityIndexToken(entityManager, entityToken, indexToken);
         // Unwrap index elements.
-        const elements = unwrapIndex(entityManager, entityToken, indexToken).filter((element) => !omit.includes(element));
+        const { hashKey } = entityManager.config.entities[entityToken].indexes[indexToken];
+        const elements = unwrapIndex(entityManager, entityToken, indexToken, [
+            hashKey,
+        ]);
         // Split dehydrated value & validate.
         const values = dehydrated.split(generatedKeyDelimiter);
         if (elements.length !== values.length)

package/dist/mjs/rehydratePageKeyMap.js

@@ -1,4 +1,5 @@
-import { range, mapValues, zipToObject, cluster } from 'radash';
+import { unique, range, mapValues, zipToObject, cluster } from 'radash';
+import { decodeGeneratedProperty } from './decodeGeneratedProperty.js';
 import { encodeGeneratedProperty } from './encodeGeneratedProperty.js';
 import { getHashKeySpace } from './getHashKeySpace.js';
 import { getIndexComponents } from './getIndexComponents.js';
@@ -14,28 +15,40 @@ import { validateEntityIndexToken } from './validateEntityIndexToken.js';
  * @param entityManager - {@link EntityManager | `EntityManager`} instance.
  * @param entityToken - {@link ConfigKeys.entities | `entityManager.config.entities`} key.
  * @param indexTokens - Array of {@link ConfigEntity.indexes | `entityManager.config.entities.<entityToken>.indexes`} keys used as keys of the original {@link PageKeyMap | `PageKeyMap`}.
+ * @param item - Partial item object sufficiently populated to generate index hash keys.
  * @param dehydrated - Array of dehydrated page keys or undefined if new query.
  * @param timestampFrom - Lower timestanp limit used to generate the original {@link PageKeyMap | `PageKeyMap`}. Defaults to `0`.
  * @param timestampTo - Upper timestamp limit used to generate the original {@link PageKeyMap | `PageKeyMap`}. Defaults to `Date.now()`.
  *
- * @returns Rehydrated {@link PageKeyMap | `PageKeyMap`} object.
+ * @returns A tuple of `hashKeyToken` and rehydrated {@link PageKeyMap | `PageKeyMap`} object.
  *
  * @throws `Error` if `entityToken` is invalid.
  * @throws `Error` if `indexTokens` is empty.
  * @throws `Error` if any `indexTokens` are invalid.
+ * @throws `Error` if `indexTokens` represent indexes with inconsistent hashKeys.
  * @throws `Error` if `dehydrated` has invalid length.
  */
-function rehydratePageKeyMap(entityManager, entityToken, indexTokens, dehydrated, timestampFrom = 0, timestampTo = Date.now()) {
+function rehydratePageKeyMap(entityManager, entityToken, indexTokens, item, dehydrated, timestampFrom = 0, timestampTo = Date.now()) {
     try {
-        // Validate params.
+        // Validate indexTokens populated.
         if (!indexTokens.length)
             throw new Error('indexTokens empty');
+        // Validate indexTokens exist.
+        const hashKeys = unique(indexTokens.map((indexToken) => {
+            validateEntityIndexToken(entityManager, entityToken, indexToken);
+            return entityManager.config.entities[entityToken].indexes[indexToken]
+                .hashKey;
+        }));
+        // Validate hashKeys consistent.
+        if (hashKeys.length > 1)
+            throw new Error('inconsistent hashKeys');
+        const [hashKeyToken] = hashKeys;
         indexTokens.map((index) => validateEntityIndexToken(entityManager, entityToken, index));
         // Shortcut empty dehydrated.
         if (dehydrated && !dehydrated.length)
-            return {};
+            return [hashKeyToken, {}];
         // Get hash key space.
-        const hashKeySpace = getHashKeySpace(entityManager, entityToken, timestampFrom, timestampTo);
+        const hashKeySpace = getHashKeySpace(entityManager, entityToken, hashKeyToken, item, timestampFrom, timestampTo);
         // Default dehydrated.
         dehydrated ?? (dehydrated = [...range(1, hashKeySpace.length * indexTokens.length, '')]);
         // Validate dehydrated length
@@ -45,14 +58,14 @@ function rehydratePageKeyMap(entityManager, entityToken, indexTokens, dehydrated
         const rehydrated = mapValues(zipToObject(indexTokens, cluster(dehydrated, hashKeySpace.length)), (dehydratedIndexPageKeyMaps, index) => zipToObject(hashKeySpace, (hashKey, i) => {
             if (!dehydratedIndexPageKeyMaps[i])
                 return;
-            let item = {
-                [entityManager.config.hashKey]: hashKey,
-                ...rehydrateIndexItem(entityManager, entityToken, index, dehydratedIndexPageKeyMaps[i], [entityManager.config.hashKey]),
+            let pageKeyItem = {
+                ...decodeGeneratedProperty(entityManager, entityToken, hashKey),
+                ...rehydrateIndexItem(entityManager, entityToken, index, dehydratedIndexPageKeyMaps[i]),
             };
-            item = updateItemRangeKey(entityManager, entityToken, item);
+            pageKeyItem = updateItemRangeKey(entityManager, entityToken, pageKeyItem);
             return zipToObject(getIndexComponents(entityManager, entityToken, index), (component) => entityManager.config.entities[entityToken].generated[component]
-                ? encodeGeneratedProperty(entityManager, entityToken, component, item)
-                : item[component]);
+                ? encodeGeneratedProperty(entityManager, entityToken, component, pageKeyItem)
+                : pageKeyItem[component]);
         }));
         entityManager.logger.debug('rehydrated page key map', {
             entityToken,
@@ -60,7 +73,7 @@ function rehydratePageKeyMap(entityManager, entityToken, indexTokens, dehydrated
             dehydrated,
             rehydrated,
         });
-        return rehydrated;
+        return [hashKeyToken, rehydrated];
     }
     catch (error) {
         if (error instanceof Error)

package/dist/mjs/unwrapIndex.js

@@ -1,4 +1,4 @@
-import { shake } from 'radash';
+import { shake, unique } from 'radash';
 import { getIndexComponents } from './getIndexComponents.js';
 import { validateEntityIndexToken } from './validateEntityIndexToken.js';
 
@@ -8,28 +8,30 @@ import { validateEntityIndexToken } from './validateEntityIndexToken.js';
  * @param entityManager - {@link EntityManager | `EntityManager`} instance.
  * @param entityToken - {@link ConfigKeys.entities | `entityManager.config.entities`} key.
  * @param indexToken - {@link ConfigEntity.indexes | `entityManager.config.entities.<entityToken>.indexes`} key.
+ * @param omit - Array of index components or elements to omit from the output value.
  *
  * @returns Deduped, sorted array of ungenerated index component elements.
  *
  * @throws `Error` if `entityToken` is invalid.
  * @throws `Error` if `indexToken` is invalid.
  */
-function unwrapIndex(entityManager, entityToken, indexToken) {
+function unwrapIndex(entityManager, entityToken, indexToken, omit = []) {
     try {
         // Validate params.
         validateEntityIndexToken(entityManager, entityToken, indexToken);
         const generated = entityManager.config.entities[entityToken].generated;
         const generatedKeys = Object.keys(shake(generated));
-        return getIndexComponents(entityManager, entityToken, indexToken)
+        return unique(getIndexComponents(entityManager, entityToken, indexToken)
+            .filter((component) => !omit.includes(component))
             .map((component) => component === entityManager.config.hashKey
-            ? entityManager.config.hashKey
+            ? entityManager.config.entities[entityToken].timestampProperty
             : component === entityManager.config.rangeKey
                 ? entityManager.config.entities[entityToken].uniqueProperty
                 : generatedKeys.includes(component)
                     ? generated[component].elements
                     : component)
             .flat()
-            .sort();
+            .filter((element) => !omit.includes(element))).sort();
     }
     catch (error) {
         if (error instanceof Error)

package/package.json

@@ -4,9 +4,8 @@
     "url": "https://github.com/karmaniverous/entity-manager/issues"
   },
   "dependencies": {
-    "@karmaniverous/entity-tools": "^0.4.0",
+    "@karmaniverous/entity-tools": "^0.4.4",
     "@karmaniverous/string-utilities": "^0.2.1",
-    "jsonschema": "^1.4.1",
     "lz-string": "^1.5.0",
     "radash": "^12.1.0",
     "string-hash": "^1.1.3",
@@ -14,9 +13,9 @@
   },
   "description": "Rational indexing & cross-shard querying at scale in your NoSQL database so you can focus on your application logic.",
   "devDependencies": {
-    "@dotenvx/dotenvx": "^1.21.0",
-    "@eslint/js": "^9.13.0",
-    "@faker-js/faker": "^9.1.0",
+    "@dotenvx/dotenvx": "^1.22.0",
+    "@eslint/js": "^9.14.0",
+    "@faker-js/faker": "^9.2.0",
     "@karmaniverous/mock-db": "^0.3.3",
     "@rollup/plugin-alias": "^5.1.1",
     "@rollup/plugin-commonjs": "^28.0.1",
@@ -29,35 +28,34 @@
     "@types/eslint-config-prettier": "^6.11.3",
     "@types/eslint-plugin-mocha": "^10.4.0",
     "@types/mocha": "^10.0.9",
-    "@types/node": "^22.8.2",
+    "@types/node": "^22.9.0",
     "@types/string-hash": "^1.1.3",
     "auto-changelog": "^2.5.0",
     "chai": "^5.1.2",
-    "cross-env": "^7.0.3",
-    "eslint": "^9.13.0",
+    "eslint": "^9.14.0",
     "eslint-config-prettier": "^9.1.0",
     "eslint-plugin-mocha": "^10.5.0",
     "eslint-plugin-simple-import-sort": "^12.1.1",
     "eslint-plugin-tsdoc": "^0.3.0",
     "jsdom-global": "^3.0.2",
-    "knip": "^5.34.2",
+    "knip": "^5.36.3",
     "lefthook": "^1.8.2",
-    "mocha": "^10.7.3",
+    "mocha": "^10.8.2",
     "nyc": "^17.1.0",
     "prettier": "^3.3.3",
     "release-it": "^17.10.0",
     "rimraf": "^6.0.1",
-    "rollup": "^4.24.2",
+    "rollup": "^4.24.4",
     "rollup-plugin-dts": "^6.1.1",
     "source-map-support": "^0.5.21",
     "ts-node": "^10.9.2",
-    "tslib": "^2.8.0",
-    "typedoc": "^0.26.10",
-    "typedoc-plugin-mdn-links": "^3.3.5",
+    "tslib": "^2.8.1",
+    "typedoc": "^0.26.11",
+    "typedoc-plugin-mdn-links": "^3.3.6",
     "typedoc-plugin-replace-text": "^4.0.0",
     "typedoc-plugin-zod": "^1.2.1",
     "typescript": "^5.6.3",
-    "typescript-eslint": "^8.12.1"
+    "typescript-eslint": "^8.13.0"
   },
   "exports": {
     ".": {
@@ -99,6 +97,7 @@
       "after:init": [
         "npm run lint",
         "npm run test",
+        "npm run knip",
         "npm run build"
       ],
       "before:npm:release": [
@@ -132,5 +131,5 @@
   },
   "type": "module",
   "types": "dist/index.d.ts",
-  "version": "6.7.0"
+  "version": "6.7.2"
 }