@karmaniverous/entity-manager 6.6.0 → 6.7.1

package/dist/cjs/BaseShardQueryMapBuilder.js

@@ -0,0 +1,34 @@
+'use strict';
+
+var radash = require('radash');
+
+/**
+ * Abstract base class supporting a fluent API for building a {@link ShardQueryMap | `ShardQueryMap`} using a database client.
+ *
+ * @category ShardQueryMapBuilder
+ */
+class BaseShardQueryMapBuilder {
+    /** BaseShardQueryMapBuilder constructor. */
+    constructor(entityManager, entityToken, hashKeyToken, pageKeyMap) {
+        this.entityManager = entityManager;
+        this.entityToken = entityToken;
+        this.hashKeyToken = hashKeyToken;
+        this.pageKeyMap = pageKeyMap;
+        /**
+         * Maps `indexToken` values to database platform-specific parameters.
+         *
+         * @protected
+         */
+        this.indexParamsMap = {};
+    }
+    /**
+     * Builds a {@link ShardQueryMap | `ShardQueryMap`} object.
+     *
+     * @returns - The {@link ShardQueryMap | `ShardQueryMap`} object.
+     */
+    build() {
+        return radash.mapValues(this.indexParamsMap, (indexConfig, indexToken) => this.getShardQueryFunction(indexToken));
+    }
+}
+
+exports.BaseShardQueryMapBuilder = BaseShardQueryMapBuilder;

package/dist/cjs/EntityManager.js

@@ -72,7 +72,7 @@ class EntityManager {
      * Query a database entity across shards in a provider-generic fashion.
      *
      * @remarks
-     * The provided {@link ShardQueryFunction | `ShardQueryFunction`} performs the actual query of individual data pages on individual shards. This function is presumed to express provider-specific query logic, including any necessary indexing or search constraints.
+     * The provided `shardQueryMap` performs the actual query of individual data pages on individual index/shard combinations.
      *
      * Individual shard query results will be combined, deduped by {@link ConfigEntity.uniqueProperty} property value, and sorted by {@link QueryOptions.sortOrder | `sortOrder`}.
      *
@@ -84,7 +84,7 @@ class EntityManager {
      *
      * @returns {@link QueryResult} object.
      *
-     * @throws Error if {@link QueryOptions.pageKeyMap | `pageKeyMap`} keys do not match {@link QueryOptions.shardQueryMap | `shardQueryMap`} keys.
+     * @throws Error if {@link QueryOptions.shardQueryMapBuilder | `shardQueryMapBuilder`} `pageKeyMap` keys do not match its `shardQueryMap` keys.
      */
     async query(options) {
         return await query.query(this, options);

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/index.js

@@ -1,9 +1,11 @@
 'use strict';
 
+var BaseShardQueryMapBuilder = require('./BaseShardQueryMapBuilder.js');
 var conditionalize = require('./conditionalize.js');
 var EntityManager = require('./EntityManager.js');
 
 
 
+exports.BaseShardQueryMapBuilder = BaseShardQueryMapBuilder.BaseShardQueryMapBuilder;
 exports.conditionalize = conditionalize.conditionalize;
 exports.EntityManager = EntityManager.EntityManager;

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, hashKey, 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, hashKey, 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, hashKey, limit, pageKeyMap, p
             // 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, hashKey, limit, pageKeyMap, p
             pageKeyMap: compressToEncodedURIComponent(JSON.stringify(dehydratePageKeyMap.dehydratePageKeyMap(entityManager, entityToken, workingResult.pageKeyMap))),
         };
         entityManager.logger.debug('queried entityToken across shards', {
-            entityToken,
-            hashKey,
-            limit,
-            pageKeyMap,
-            pageSize,
-            shardQueryMap,
-            timestampFrom,
-            timestampTo,
-            throttle,
+            options,
+            hashKeyToken,
             rehydratedPageKeyMap,
             workingResult,
             result,
@@ -110,17 +101,7 @@ async function query(entityManager, { entityToken, hashKey, limit, pageKeyMap, p
     }
     catch (error) {
         if (error instanceof Error)
-            entityManager.logger.error(error.message, {
-                entityToken,
-                hashKey,
-                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

@@ -1,19 +1,6 @@
 import { Entity, Exactify, TranscodeMap, PropertiesOfType, TranscodableProperties, Transcodes, DefaultTranscodeMap, SortOrder } from '@karmaniverous/entity-tools';
 import { z } from 'zod';
 
-/**
- * Transforms a function such that it only executes when `condition` is truthy.
- *
- * @param fn - The function to conditionally execute.
- * @param condition - The condition to check before executing `fn`.
- *
- * @typeParam F - The type of the function to conditionally execute.
- *
- * @returns The conditionalized function with the same signature as `fn`.
- *
- */
-declare function conditionalize<F extends (...args: Parameters<F>) => ReturnType<F>>(fn: F, condition?: unknown): (...args: Parameters<F>) => ReturnType<F> | undefined;
-
 /**
  * The base EntityMap type. All EntityMaps should extend this type.
  *
@@ -723,7 +710,7 @@ type ShardQueryFunction<Item extends Entity> = (hashKey: string, pageKey?: Parti
 type ShardQueryMap<Item extends Entity> = Record<string, ShardQueryFunction<Item>>;
 
 /**
- * Options passed to the {@link EntityManager.query | `EntityManager.query`} method.
+ * Options passed to the {@link query | `query`} function.
  *
  * @category Query
  */
@@ -731,10 +718,9 @@ interface QueryOptions<Item extends ItemMap<M, HashKey, RangeKey>[EntityToken],
     /** Identifies the entity to be queried. Key of {@link Config | `EntityManager.config.entities`}. */
     entityToken: EntityToken;
     /**
-     * Identifies the entity key across which the query will be sharded. Key of
-     * {@link Config | `EntityManager.config.entities.<entityToken>.keys`}.
+     * Partial item object sufficiently populated to generate index hash keys.
      */
-    hashKey: string;
+    item: Partial<Item>;
     /**
      * The target maximum number of records to be returned by the query across
      * all shards.
@@ -872,7 +858,7 @@ declare class EntityManager<M extends EntityMap, HashKey extends string, RangeKe
      * Query a database entity across shards in a provider-generic fashion.
      *
      * @remarks
-     * The provided {@link ShardQueryFunction | `ShardQueryFunction`} performs the actual query of individual data pages on individual shards. This function is presumed to express provider-specific query logic, including any necessary indexing or search constraints.
+     * The provided `shardQueryMap` performs the actual query of individual data pages on individual index/shard combinations.
      *
      * Individual shard query results will be combined, deduped by {@link ConfigEntity.uniqueProperty} property value, and sorted by {@link QueryOptions.sortOrder | `sortOrder`}.
      *
@@ -884,9 +870,49 @@ declare class EntityManager<M extends EntityMap, HashKey extends string, RangeKe
      *
      * @returns {@link QueryResult} object.
      *
-     * @throws Error if {@link QueryOptions.pageKeyMap | `pageKeyMap`} keys do not match {@link QueryOptions.shardQueryMap | `shardQueryMap`} keys.
+     * @throws Error if {@link QueryOptions.shardQueryMapBuilder | `shardQueryMapBuilder`} `pageKeyMap` keys do not match its `shardQueryMap` keys.
      */
     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>>;
 }
 
-export { type Config, type ConfigEntities, type ConfigEntity, type ConfigEntityGenerated, type ConfigEntityIndexComponent, type ConfigKeys, type ConfigTranscodes, EntityManager, type EntityMap, type ExclusiveKey, type ItemMap, type ParsedConfig, type QueryOptions, type QueryResult, type ShardBump, type ShardQueryFunction, type ShardQueryMap, type ShardQueryResult, type Unwrap, conditionalize };
+/**
+ * Abstract base class supporting a fluent API for building a {@link ShardQueryMap | `ShardQueryMap`} using a database client.
+ *
+ * @category ShardQueryMapBuilder
+ */
+declare abstract class BaseShardQueryMapBuilder<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> {
+    readonly entityManager: EntityManager<M, HashKey, RangeKey, T>;
+    readonly entityToken: EntityToken;
+    readonly hashKeyToken: PropertiesOfType<M[EntityToken], never> | HashKey;
+    readonly pageKeyMap?: string | undefined;
+    /**
+     * Maps `indexToken` values to database platform-specific parameters.
+     *
+     * @protected
+     */
+    readonly indexParamsMap: Record<string, IndexParams>;
+    /** BaseShardQueryMapBuilder constructor. */
+    constructor(entityManager: EntityManager<M, HashKey, RangeKey, T>, entityToken: EntityToken, hashKeyToken: PropertiesOfType<M[EntityToken], never> | HashKey, pageKeyMap?: string | undefined);
+    protected abstract getShardQueryFunction(indexToken: string): ShardQueryFunction<Item>;
+    /**
+     * Builds a {@link ShardQueryMap | `ShardQueryMap`} object.
+     *
+     * @returns - The {@link ShardQueryMap | `ShardQueryMap`} object.
+     */
+    build(): ShardQueryMap<Item>;
+}
+
+/**
+ * Transforms a function such that it only executes when `condition` is truthy.
+ *
+ * @param fn - The function to conditionally execute.
+ * @param condition - The condition to check before executing `fn`.
+ *
+ * @typeParam F - The type of the function to conditionally execute.
+ *
+ * @returns The conditionalized function with the same signature as `fn`.
+ *
+ */
+declare function conditionalize<F extends (...args: Parameters<F>) => ReturnType<F>>(fn: F, condition?: unknown): (...args: Parameters<F>) => ReturnType<F> | undefined;
+
+export { BaseShardQueryMapBuilder, type Config, type ConfigEntities, type ConfigEntity, type ConfigEntityGenerated, type ConfigEntityIndexComponent, type ConfigKeys, type ConfigTranscodes, EntityManager, type EntityMap, type ExclusiveKey, type ItemMap, type ParsedConfig, type QueryOptions, type QueryResult, type ShardBump, type ShardQueryFunction, type ShardQueryMap, type ShardQueryResult, type Unwrap, conditionalize };

package/dist/mjs/BaseShardQueryMapBuilder.js

@@ -0,0 +1,32 @@
+import { mapValues } from 'radash';
+
+/**
+ * Abstract base class supporting a fluent API for building a {@link ShardQueryMap | `ShardQueryMap`} using a database client.
+ *
+ * @category ShardQueryMapBuilder
+ */
+class BaseShardQueryMapBuilder {
+    /** BaseShardQueryMapBuilder constructor. */
+    constructor(entityManager, entityToken, hashKeyToken, pageKeyMap) {
+        this.entityManager = entityManager;
+        this.entityToken = entityToken;
+        this.hashKeyToken = hashKeyToken;
+        this.pageKeyMap = pageKeyMap;
+        /**
+         * Maps `indexToken` values to database platform-specific parameters.
+         *
+         * @protected
+         */
+        this.indexParamsMap = {};
+    }
+    /**
+     * Builds a {@link ShardQueryMap | `ShardQueryMap`} object.
+     *
+     * @returns - The {@link ShardQueryMap | `ShardQueryMap`} object.
+     */
+    build() {
+        return mapValues(this.indexParamsMap, (indexConfig, indexToken) => this.getShardQueryFunction(indexToken));
+    }
+}
+
+export { BaseShardQueryMapBuilder };

package/dist/mjs/EntityManager.js

@@ -70,7 +70,7 @@ class EntityManager {
      * Query a database entity across shards in a provider-generic fashion.
      *
      * @remarks
-     * The provided {@link ShardQueryFunction | `ShardQueryFunction`} performs the actual query of individual data pages on individual shards. This function is presumed to express provider-specific query logic, including any necessary indexing or search constraints.
+     * The provided `shardQueryMap` performs the actual query of individual data pages on individual index/shard combinations.
      *
      * Individual shard query results will be combined, deduped by {@link ConfigEntity.uniqueProperty} property value, and sorted by {@link QueryOptions.sortOrder | `sortOrder`}.
      *
@@ -82,7 +82,7 @@ class EntityManager {
      *
      * @returns {@link QueryResult} object.
      *
-     * @throws Error if {@link QueryOptions.pageKeyMap | `pageKeyMap`} keys do not match {@link QueryOptions.shardQueryMap | `shardQueryMap`} keys.
+     * @throws Error if {@link QueryOptions.shardQueryMapBuilder | `shardQueryMapBuilder`} `pageKeyMap` keys do not match its `shardQueryMap` keys.
      */
     async query(options) {
         return await query(this, options);

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/index.js

@@ -1,2 +1,3 @@
+export { BaseShardQueryMapBuilder } from './BaseShardQueryMapBuilder.js';
 export { conditionalize } from './conditionalize.js';
 export { EntityManager } from './EntityManager.js';

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, hashKey, 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, hashKey, 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, hashKey, limit, pageKeyMap, p
             // 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, hashKey, limit, pageKeyMap, p
             pageKeyMap: compressToEncodedURIComponent(JSON.stringify(dehydratePageKeyMap(entityManager, entityToken, workingResult.pageKeyMap))),
         };
         entityManager.logger.debug('queried entityToken across shards', {
-            entityToken,
-            hashKey,
-            limit,
-            pageKeyMap,
-            pageSize,
-            shardQueryMap,
-            timestampFrom,
-            timestampTo,
-            throttle,
+            options,
+            hashKeyToken,
             rehydratedPageKeyMap,
             workingResult,
             result,
@@ -108,17 +99,7 @@ async function query(entityManager, { entityToken, hashKey, limit, pageKeyMap, p
     }
     catch (error) {
         if (error instanceof Error)
-            entityManager.logger.error(error.message, {
-                entityToken,
-                hashKey,
-                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.6.0"
+  "version": "6.7.1"
 }