@karmaniverous/entity-manager 6.5.1 → 6.7.0

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.
  *
@@ -81,7 +68,7 @@ interface ShardBump {
     chars: number;
 }
 /**
- * Returns a Config entity index components type.
+ * Returns a Config entity index component type.
  *
  * @typeParam EntityToken - The {@link Entity | `Entity`} token.
  * @typeParam M - The {@link EntityMap | `EntityMap`}.
@@ -688,53 +675,11 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
 type ParsedConfig = z.infer<typeof configSchema>;
 
 /**
- * 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 EntityManager.query | `EntityManager.query`} method.
+ * Base type of options passed to the {@link EntityManager.query | `EntityManager.query`} method.
  *
  * @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;
-    /**
-     * Identifies the entity key across which the query will be sharded. Key of
-     * {@link Config | `EntityManager.config.entities.<entityToken>.keys`}.
-     */
-    hashKey: string;
+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.
@@ -744,10 +689,6 @@ interface QueryOptions<Item extends ItemMap<M, HashKey, RangeKey>[EntityToken],
      * 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).
@@ -757,16 +698,6 @@ interface QueryOptions<Item extends ItemMap<M, HashKey, RangeKey>[EntityToken],
      * 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 `[]`.
      */
@@ -799,6 +730,16 @@ interface QueryOptions<Item extends ItemMap<M, HashKey, RangeKey>[EntityToken],
     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`}.
@@ -848,31 +789,31 @@ declare class EntityManager<M extends EntityMap, HashKey extends string, RangeKe
     /**
      * Update generated properties, hash key, and range key on an {@link ItemMap | `ItemMap`} object.
      *
-     * @param item - {@link ItemMap | `ItemMap`} object.
      * @param entityToken - {@link ConfigKeys.entities | `this.config.entities`} key.
+     * @param item - {@link ItemMap | `ItemMap`} object.
      * @param overwrite - Overwrite existing properties (default `false`).
      *
      * @returns Shallow clone of `item` with updated properties.
      *
      * @throws `Error` if `entityToken` is invalid.
      */
-    addKeys<Item extends ItemMap<M, HashKey, RangeKey>[EntityToken], EntityToken extends keyof Exactify<M> & string>(item: Partial<Item>, entityToken: EntityToken, overwrite?: boolean): Partial<Item>;
+    addKeys<Item extends ItemMap<M, HashKey, RangeKey>[EntityToken], EntityToken extends keyof Exactify<M> & string>(entityToken: EntityToken, item: Partial<Item>, overwrite?: boolean): Partial<Item>;
     /**
      * Strips generated properties, hash key, and range key from an {@link ItemMap | `ItemMap`} object.
      *
-     * @param item - {@link ItemMap | `ItemMap`} object.
      * @param entityToken - {@link ConfigKeys.entities | `this.config.entities`} key.
+     * @param item - {@link ItemMap | `ItemMap`} object.
      *
      * @returns Shallow clone of `item` without generated properties, hash key or range key.
      *
      * @throws `Error` if `entityToken` is invalid.
      */
-    removeKeys<Item extends ItemMap<M, HashKey, RangeKey>[EntityToken], EntityToken extends keyof Exactify<M> & string>(item: Partial<Item>, entityToken: EntityToken): Partial<Item>;
+    removeKeys<Item extends ItemMap<M, HashKey, RangeKey>[EntityToken], EntityToken extends keyof Exactify<M> & string>(entityToken: EntityToken, item: Partial<Item>): Partial<Item>;
     /**
      * 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 +825,84 @@ 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<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>>;
+}
+
+/**
+ * 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.
+ *
+ * @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.
      */
-    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>>;
+    build(): ShardQueryMap<Item>;
 }
 
-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 };
+/**
+ * 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

@@ -42,35 +42,35 @@ class EntityManager {
     /**
      * Update generated properties, hash key, and range key on an {@link ItemMap | `ItemMap`} object.
      *
-     * @param item - {@link ItemMap | `ItemMap`} object.
      * @param entityToken - {@link ConfigKeys.entities | `this.config.entities`} key.
+     * @param item - {@link ItemMap | `ItemMap`} object.
      * @param overwrite - Overwrite existing properties (default `false`).
      *
      * @returns Shallow clone of `item` with updated properties.
      *
      * @throws `Error` if `entityToken` is invalid.
      */
-    addKeys(item, entityToken, overwrite = false) {
-        return addKeys(this, item, entityToken, overwrite);
+    addKeys(entityToken, item, overwrite = false) {
+        return addKeys(this, entityToken, item, overwrite);
     }
     /**
      * Strips generated properties, hash key, and range key from an {@link ItemMap | `ItemMap`} object.
      *
-     * @param item - {@link ItemMap | `ItemMap`} object.
      * @param entityToken - {@link ConfigKeys.entities | `this.config.entities`} key.
+     * @param item - {@link ItemMap | `ItemMap`} object.
      *
      * @returns Shallow clone of `item` without generated properties, hash key or range key.
      *
      * @throws `Error` if `entityToken` is invalid.
      */
-    removeKeys(item, entityToken) {
-        return removeKeys(this, item, entityToken);
+    removeKeys(entityToken, item) {
+        return removeKeys(this, entityToken, item);
     }
     /**
      * 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,10 +82,19 @@ 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);
+        const { shardQueryMapBuilder, ...baseOptions } = options;
+        const { entityToken, hashKeyToken, pageKeyMap } = shardQueryMapBuilder;
+        const shardQueryMap = shardQueryMapBuilder.build();
+        return await query(this, {
+            entityToken,
+            hashKeyToken,
+            pageKeyMap,
+            shardQueryMap,
+            ...baseOptions,
+        });
     }
 }
 _EntityManager_config = new WeakMap();

package/dist/mjs/addKeys.js

@@ -8,27 +8,27 @@ import { validateEntityToken } from './validateEntityToken.js';
  * Update generated properties, hash key, and range key on an {@link ItemMap | `ItemMap`} object.
  *
  * @param entityManager - {@link EntityManager | `EntityManager`} instance.
- * @param item - {@link ItemMap | `ItemMap`} object.
  * @param entityToken - {@link ConfigKeys.entities | `this.config.entities`} key.
+ * @param item - {@link ItemMap | `ItemMap`} object.
  * @param overwrite - Overwrite existing properties (default `false`).
  *
  * @returns Shallow clone of `item` with updated properties.
  *
  * @throws `Error` if `entityToken` is invalid.
  */
-function addKeys(entityManager, item, entityToken, overwrite = false) {
+function addKeys(entityManager, entityToken, item, overwrite = false) {
     try {
         // Validate params.
         validateEntityToken(entityManager, entityToken);
         // Update hash key.
-        let newItem = updateItemHashKey(entityManager, item, entityToken, overwrite);
+        let newItem = updateItemHashKey(entityManager, entityToken, item, overwrite);
         // Update range key.
-        newItem = updateItemRangeKey(entityManager, newItem, entityToken, overwrite);
+        newItem = updateItemRangeKey(entityManager, entityToken, newItem, overwrite);
         // Update generated properties.
         for (const property in entityManager.config.entities[entityToken]
             .generated) {
             if (overwrite || isNil(item[property])) {
-                const encoded = encodeGeneratedProperty(entityManager, newItem, entityToken, property);
+                const encoded = encodeGeneratedProperty(entityManager, entityToken, property, newItem);
                 if (encoded)
                     Object.assign(newItem, { [property]: encoded });
                 else

package/dist/mjs/decodeEntityElement.js

@@ -8,15 +8,15 @@ import { validateEntityToken } from './validateEntityToken.js';
  * If `element` is the {@link Config.hashKey | `hashKey`} or {@link Config.rangeKey | `rangeKey`}, returns the value as-is.
  *
  * @param entityManager - {@link EntityManager | `EntityManager`} instance.
- * @param item - Partial {@link ItemMap | `ItemMap`} object.
  * @param entityToken - {@link ConfigKeys.entities | `entityManager.config.entities`} key.
  * @param element - The {@link Entity | `Entity`} generated property element or ungenerated index component to encode.
+ * @param value - Encoded entity element.
  *
  * @returns Decoded value.
  *
  * @throws `Error` if `entityToken` is invalid.
  */
-function decodeEntityElement(entityManager, value, entityToken, element) {
+function decodeEntityElement(entityManager, entityToken, element, value) {
     try {
         validateEntityToken(entityManager, entityToken);
         const { entities, hashKey, rangeKey, transcodes } = entityManager.config;
@@ -26,9 +26,9 @@ function decodeEntityElement(entityManager, value, entityToken, element) {
             return value;
         const decoded = transcodes[entities[entityToken].elementTranscodes[element]].decode(value);
         entityManager.logger.debug('decoded entity element', {
-            value,
             entityToken,
             element,
+            value,
             decoded,
         });
         return decoded;
@@ -36,9 +36,9 @@ function decodeEntityElement(entityManager, value, entityToken, element) {
     catch (error) {
         if (error instanceof Error)
             entityManager.logger.error(error.message, {
-                value,
                 entityToken,
                 element,
+                value,
             });
         throw error;
     }

package/dist/mjs/decodeGeneratedProperty.js

@@ -6,14 +6,14 @@ import { validateEntityToken } from './validateEntityToken.js';
  * Decode a generated property value. Returns a partial ItemMap.
  *
  * @param entityManager - {@link EntityManager | `EntityManager`} instance.
- * @param encoded - Encoded generated property value.
  * @param entityToken - `entityManager.config.entities` key.
+ * @param encoded - Encoded generated property value.
  *
  * @returns Partial {@link ItemMap | `ItemMap`} object with updated properties decoded from `encoded`.
  *
  * @throws `Error` if `entityToken` is invalid.
  */
-function decodeGeneratedProperty(entityManager, encoded, entityToken) {
+function decodeGeneratedProperty(entityManager, entityToken, encoded) {
     try {
         const { generatedKeyDelimiter, generatedValueDelimiter, hashKey, shardKeyDelimiter, } = entityManager.config;
         // Validate params.
@@ -35,17 +35,17 @@ function decodeGeneratedProperty(entityManager, encoded, entityToken) {
             return pair;
         });
         // Assign decoded properties.
-        Object.assign(decoded, objectify(values, ([key]) => key, ([key, value]) => decodeEntityElement(entityManager, value, entityToken, key)));
+        Object.assign(decoded, objectify(values, ([key]) => key, ([key, value]) => decodeEntityElement(entityManager, entityToken, key, value)));
         entityManager.logger.debug('decoded generated property', {
-            encoded,
             entityToken,
+            encoded,
             decoded,
         });
         return decoded;
     }
     catch (error) {
         if (error instanceof Error)
-            entityManager.logger.error(error.message, { encoded, entityToken });
+            entityManager.logger.error(error.message, { entityToken, encoded });
         throw error;
     }
 }

package/dist/mjs/dehydrateIndexItem.js

@@ -16,9 +16,9 @@ import { validateEntityIndexToken } from './validateEntityIndexToken.js';
  * `item` must be populated with all required index component elements!
  *
  * @param entityManager - {@link EntityManager | `EntityManager`} instance.
- * @param item - Partial {@link ItemMap | `ItemMap`} object.
  * @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.
@@ -26,7 +26,7 @@ import { validateEntityIndexToken } from './validateEntityIndexToken.js';
  * @throws `Error` if `entityToken` is invalid.
  * @throws `Error` if `indexToken` is invalid.
  */
-function dehydrateIndexItem(entityManager, item, entityToken, indexToken, omit = []) {
+function dehydrateIndexItem(entityManager, entityToken, indexToken, item, omit = []) {
     try {
         const { generatedKeyDelimiter } = entityManager.config;
         // Validate params.
@@ -38,7 +38,7 @@ function dehydrateIndexItem(entityManager, item, entityToken, indexToken, omit =
         const elements = unwrapIndex(entityManager, entityToken, indexToken).filter((element) => !omit.includes(element));
         // Join index element values.
         const dehydrated = elements
-            .map((element) => encodeEntityElement(entityManager, item, entityToken, element))
+            .map((element) => encodeEntityElement(entityManager, entityToken, element, item))
             .join(generatedKeyDelimiter);
         entityManager.logger.debug('dehydrated index', {
             item,

package/dist/mjs/dehydratePageKeyMap.js

@@ -9,8 +9,8 @@ import { validateEntityToken } from './validateEntityToken.js';
  * Reverses {@link EntityManager.rehydratePageKeyMap | `rehydratePageKeyMap`}.
  *
  * @param entityManager - {@link EntityManager | `EntityManager`} instance.
- * @param pageKeyMap - {@link PageKeyMap | `PageKeyMap`} object to dehydrate.
  * @param entityToken - {@link ConfigKeys.entities | `entityManager.config.entities`} key.
+ * @param pageKeyMap - {@link PageKeyMap | `PageKeyMap`} object to dehydrate.
  *
  * @returns  Array of dehydrated page keys.
  *
@@ -22,7 +22,7 @@ import { validateEntityToken } from './validateEntityToken.js';
  *
  * An empty returned array indicates all page keys are `undefined`.
  */
-function dehydratePageKeyMap(entityManager, pageKeyMap, entityToken) {
+function dehydratePageKeyMap(entityManager, entityToken, pageKeyMap) {
     try {
         // Validate params.
         validateEntityToken(entityManager, entityToken);
@@ -30,8 +30,8 @@ function dehydratePageKeyMap(entityManager, pageKeyMap, entityToken) {
         if (!Object.keys(pageKeyMap).length) {
             const dehydrated = [];
             entityManager.logger.debug('dehydrated empty page key map', {
-                pageKeyMap,
                 entityToken,
+                pageKeyMap,
                 dehydrated,
             });
             return dehydrated;
@@ -54,13 +54,13 @@ function dehydratePageKeyMap(entityManager, pageKeyMap, entityToken) {
                 const item = Object.entries(pageKeyMap[index][hashKey]).reduce((item, [property, value]) => {
                     if (property in entityManager.config.entities[entityToken].generated ||
                         property === entityManager.config.rangeKey)
-                        Object.assign(item, decodeGeneratedProperty(entityManager, value, entityToken));
+                        Object.assign(item, decodeGeneratedProperty(entityManager, entityToken, value));
                     else
                         Object.assign(item, { [property]: value });
                     return item;
                 }, {});
                 // Dehydrate index from item.
-                dehydrated.push(dehydrateIndexItem(entityManager, item, entityToken, index, [
+                dehydrated.push(dehydrateIndexItem(entityManager, entityToken, index, item, [
                     entityManager.config.hashKey,
                 ]));
             }
@@ -69,8 +69,8 @@ function dehydratePageKeyMap(entityManager, pageKeyMap, entityToken) {
         if (dehydrated.every((pageKey) => pageKey === ''))
             dehydrated = [];
         entityManager.logger.debug('dehydrated page key map', {
-            pageKeyMap,
             entityToken,
+            pageKeyMap,
             indexes,
             hashKeys,
             dehydrated,

package/dist/mjs/encodeEntityElement.js

@@ -8,15 +8,15 @@ import { validateEntityToken } from './validateEntityToken.js';
  * If `element` is the {@link Config.hashKey | `hashKey`} or {@link Config.rangeKey | `rangeKey`}, returns the value as-is.
  *
  * @param entityManager - {@link EntityManager | `EntityManager`} instance.
- * @param item - Partial {@link ItemMap | `ItemMap`} object.
  * @param entityToken - {@link ConfigKeys.entities | `entityManager.config.entities`} key.
  * @param element - The {@link Entity | `Entity`} generated property element or ungenerated index component to encode.
+ * @param item - Partial {@link ItemMap | `ItemMap`} object.
  *
  * @returns Encoded value.
  *
  * @throws `Error` if `entityToken` is invalid.
  */
-function encodeEntityElement(entityManager, item, entityToken, element) {
+function encodeEntityElement(entityManager, entityToken, element, item) {
     try {
         validateEntityToken(entityManager, entityToken);
         const { entities, hashKey, rangeKey, transcodes } = entityManager.config;
@@ -25,16 +25,16 @@ function encodeEntityElement(entityManager, item, entityToken, element) {
             return value;
         const encoded = transcodes[entities[entityToken].elementTranscodes[element]].encode(item[element]) || undefined;
         entityManager.logger.debug('encoded entity element', {
-            item,
             entityToken,
             element,
+            item,
             encoded,
         });
         return encoded;
     }
     catch (error) {
         if (error instanceof Error)
-            entityManager.logger.error(error.message, { item, entityToken, element });
+            entityManager.logger.error(error.message, { entityToken, element, item });
         throw error;
     }
 }

package/dist/mjs/encodeGeneratedProperty.js

@@ -5,16 +5,16 @@ import { validateEntityGeneratedProperty } from './validateEntityGeneratedProper
  * Encode a generated property value. Returns a string or undefined if atomicity requirement not met.
  *
  * @param entityManager - {@link EntityManager | `EntityManager`} instance.
- * @param item - Partial {@link ItemMap | `ItemMap`} object.
  * @param entityToken - `entityManager.config.entities` key.
  * @param property - {@link ConfigEntityGenerated | `entityManager.config.entities.<entityToken>.generated`} key.
+ * @param item - Partial {@link ItemMap | `ItemMap`} object.
  *
  * @returns Encoded generated property value.
  *
  * @throws `Error` if `entityToken` is invalid.
  * @throws `Error` if `property` is invalid.
  */
-function encodeGeneratedProperty(entityManager, item, entityToken, property) {
+function encodeGeneratedProperty(entityManager, entityToken, property, item) {
     try {
         // Validate params.
         validateEntityGeneratedProperty(entityManager, entityToken, property);
@@ -33,9 +33,9 @@ function encodeGeneratedProperty(entityManager, item, entityToken, property) {
             ...elementMap.map(([element, value]) => [element, (value ?? '').toString()].join(entityManager.config.generatedValueDelimiter)),
         ].join(entityManager.config.generatedKeyDelimiter);
         entityManager.logger.debug('encoded generated property', {
-            item,
             entityToken,
             property,
+            item,
             encoded,
         });
         return encoded;
@@ -43,9 +43,9 @@ function encodeGeneratedProperty(entityManager, item, entityToken, property) {
     catch (error) {
         if (error instanceof Error)
             entityManager.logger.error(error.message, {
-                item,
                 entityToken,
                 property,
+                item,
             });
         throw error;
     }

package/dist/mjs/index.js

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