@karmaniverous/entity-manager 6.4.2 → 6.4.4

package/README.md

@@ -8,7 +8,7 @@
 
 **EntityManager implements rational indexing & cross-shard querying at scale in your NoSQL database so you can focus on your application logic.**
 
-I've just released a full Typescript refactor. Everything works beatuifully, but I'm still fleshing out [the documentation](https://karmanivero.us/projects/entity-manager/intro/).
+I've just released a full Typescript refactor. Everything works beautifully, but I'm still fleshing out [the documentation](https://karmanivero.us/projects/entity-manager/intro/).
 
 If you have any questions, please [start a discussion](https://github.com/karmaniverous/entity-manager/discussions). Otherwise stay tuned!
 

package/dist/cjs/EntityManager.js

@@ -18,10 +18,12 @@ class EntityManager {
      * Create an EntityManager instance.
      *
      * @param config - EntityManager {@link Config | `Config`} object.
+     * @param logger - Logger object (defaults to `console`, must support `debug` & `error` methods).
      */
-    constructor(config) {
+    constructor(config, logger = console) {
         _EntityManager_config.set(this, void 0);
         tslib.__classPrivateFieldSet(this, _EntityManager_config, ParsedConfig.configSchema.parse(config), "f");
+        this.logger = logger;
     }
     /**
      * Get the current EntityManager {@link Config | `Config`} object.

package/dist/cjs/addKeys.js

@@ -37,9 +37,21 @@ function addKeys(entityManager, item, entityToken, overwrite = false) {
                     delete newItem[property];
             }
         }
+        entityManager.logger.debug('updated entity item generated properties', {
+            item,
+            entityToken,
+            overwrite,
+            newItem,
+        });
         return newItem;
     }
     catch (error) {
+        if (error instanceof Error)
+            entityManager.logger.error(error.message, {
+                item,
+                entityToken,
+                overwrite,
+            });
         throw error;
     }
 }

package/dist/cjs/decodeEntityElement.js

@@ -27,9 +27,21 @@ function decodeEntityElement(entityManager, value, entityToken, element) {
         if ([hashKey, rangeKey].includes(element))
             return value;
         const decoded = transcodes[entities[entityToken].elementTranscodes[element]].decode(value);
+        entityManager.logger.debug('decoded entity element', {
+            value,
+            entityToken,
+            element,
+            decoded,
+        });
         return decoded;
     }
     catch (error) {
+        if (error instanceof Error)
+            entityManager.logger.error(error.message, {
+                value,
+                entityToken,
+                element,
+            });
         throw error;
     }
 }

package/dist/cjs/decodeGeneratedProperty.js

@@ -38,9 +38,16 @@ function decodeGeneratedProperty(entityManager, encoded, entityToken) {
         });
         // Assign decoded properties.
         Object.assign(decoded, radash.objectify(values, ([key]) => key, ([key, value]) => decodeEntityElement.decodeEntityElement(entityManager, value, entityToken, key)));
+        entityManager.logger.debug('decoded generated property', {
+            encoded,
+            entityToken,
+            decoded,
+        });
         return decoded;
     }
     catch (error) {
+        if (error instanceof Error)
+            entityManager.logger.error(error.message, { encoded, entityToken });
         throw error;
     }
 }

package/dist/cjs/dehydrateIndexItem.js

@@ -42,9 +42,22 @@ function dehydrateIndexItem(entityManager, item, entityToken, indexToken, omit =
         const dehydrated = elements
             .map((element) => encodeEntityElement.encodeEntityElement(entityManager, item, entityToken, element))
             .join(generatedKeyDelimiter);
+        entityManager.logger.debug('dehydrated index', {
+            item,
+            entityToken,
+            indexToken,
+            elements,
+            dehydrated,
+        });
         return dehydrated;
     }
     catch (error) {
+        if (error instanceof Error)
+            entityManager.logger.error(error.message, {
+                item,
+                entityToken,
+                indexToken,
+            });
         throw error;
     }
 }

package/dist/cjs/dehydratePageKeyMap.js

@@ -31,6 +31,11 @@ function dehydratePageKeyMap(entityManager, pageKeyMap, entityToken) {
         // Shortcut empty pageKeyMap.
         if (!Object.keys(pageKeyMap).length) {
             const dehydrated = [];
+            entityManager.logger.debug('dehydrated empty page key map', {
+                pageKeyMap,
+                entityToken,
+                dehydrated,
+            });
             return dehydrated;
         }
         // Extract, sort & validate indexs.
@@ -65,9 +70,18 @@ function dehydratePageKeyMap(entityManager, pageKeyMap, entityToken) {
         // Replace with empty array if all pageKeys are empty strings.
         if (dehydrated.every((pageKey) => pageKey === ''))
             dehydrated = [];
+        entityManager.logger.debug('dehydrated page key map', {
+            pageKeyMap,
+            entityToken,
+            indexes,
+            hashKeys,
+            dehydrated,
+        });
         return dehydrated;
     }
     catch (error) {
+        if (error instanceof Error)
+            entityManager.logger.error(error.message, { entityToken, pageKeyMap });
         throw error;
     }
 }

package/dist/cjs/encodeEntityElement.js

@@ -26,9 +26,17 @@ function encodeEntityElement(entityManager, item, entityToken, element) {
         if (value === undefined || [hashKey, rangeKey].includes(element))
             return value;
         const encoded = transcodes[entities[entityToken].elementTranscodes[element]].encode(item[element]) || undefined;
+        entityManager.logger.debug('encoded entity element', {
+            item,
+            entityToken,
+            element,
+            encoded,
+        });
         return encoded;
     }
     catch (error) {
+        if (error instanceof Error)
+            entityManager.logger.error(error.message, { item, entityToken, element });
         throw error;
     }
 }

package/dist/cjs/encodeGeneratedProperty.js

@@ -34,9 +34,21 @@ function encodeGeneratedProperty(entityManager, item, entityToken, property) {
             ...(sharded ? [item[entityManager.config.hashKey]] : []),
             ...elementMap.map(([element, value]) => [element, (value ?? '').toString()].join(entityManager.config.generatedValueDelimiter)),
         ].join(entityManager.config.generatedKeyDelimiter);
+        entityManager.logger.debug('encoded generated property', {
+            item,
+            entityToken,
+            property,
+            encoded,
+        });
         return encoded;
     }
     catch (error) {
+        if (error instanceof Error)
+            entityManager.logger.error(error.message, {
+                item,
+                entityToken,
+                property,
+            });
         throw error;
     }
 }

package/dist/cjs/getHashKeySpace.js

@@ -31,9 +31,21 @@ function getHashKeySpace(entityManager, entityToken, timestampFrom = 0, timestam
                 : '';
         })
             .map((shardKey) => `${entityToken}${entityManager.config.shardKeyDelimiter}${shardKey}`);
+        entityManager.logger.debug('generated hash key space', {
+            entityToken,
+            timestampFrom,
+            timestampTo,
+            hashKeySpace,
+        });
         return hashKeySpace;
     }
     catch (error) {
+        if (error instanceof Error)
+            entityManager.logger.error(error.message, {
+                entityToken,
+                timestampFrom,
+                timestampTo,
+            });
         throw error;
     }
 }

package/dist/cjs/index.js

@@ -2,12 +2,10 @@
 
 var conditionalize = require('./conditionalize.js');
 var EntityManager = require('./EntityManager.js');
-var EntityManagerClient = require('./EntityManagerClient.js');
 var ShardQueryMapBuilder = require('./ShardQueryMapBuilder.js');
 
 
 
 exports.conditionalize = conditionalize.conditionalize;
 exports.EntityManager = EntityManager.EntityManager;
-exports.EntityManagerClient = EntityManagerClient.EntityManagerClient;
 exports.ShardQueryMapBuilder = ShardQueryMapBuilder.ShardQueryMapBuilder;

package/dist/cjs/query.js

@@ -92,9 +92,35 @@ async function query(entityManager, { entityToken, hashKey, limit, pageKeyMap, p
             items: workingResult.items,
             pageKeyMap: compressToEncodedURIComponent(JSON.stringify(dehydratePageKeyMap.dehydratePageKeyMap(entityManager, workingResult.pageKeyMap, entityToken))),
         };
+        entityManager.logger.debug('queried entityToken across shards', {
+            entityToken,
+            hashKey,
+            limit,
+            pageKeyMap,
+            pageSize,
+            shardQueryMap,
+            timestampFrom,
+            timestampTo,
+            throttle,
+            rehydratedPageKeyMap,
+            workingResult,
+            result,
+        });
         return result;
     }
     catch (error) {
+        if (error instanceof Error)
+            entityManager.logger.error(error.message, {
+                entityToken,
+                hashKey,
+                limit,
+                pageKeyMap,
+                pageSize,
+                shardQueryMap,
+                timestampFrom,
+                timestampTo,
+                throttle,
+            });
         throw error;
     }
 }

package/dist/cjs/rehydrateIndexItem.js

@@ -37,9 +37,23 @@ function rehydrateIndexItem(entityManager, dehydrated, entityToken, indexToken,
             throw new Error('index rehydration key-value mismatch');
         // Assign values to elements.
         const rehydrated = radash.shake(radash.zipToObject(elements, values.map((value, i) => decodeEntityElement.decodeEntityElement(entityManager, value, entityToken, elements[i]))));
+        entityManager.logger.debug('rehydrated index', {
+            dehydrated,
+            entityToken,
+            indexToken,
+            elements,
+            values,
+            rehydrated,
+        });
         return rehydrated;
     }
     catch (error) {
+        if (error instanceof Error)
+            entityManager.logger.error(error.message, {
+                dehydrated,
+                entityToken,
+                indexToken,
+            });
         throw error;
     }
 }

package/dist/cjs/rehydratePageKeyMap.js

@@ -55,9 +55,21 @@ function rehydratePageKeyMap(entityManager, dehydrated, entityToken, indexTokens
                 ? encodeGeneratedProperty.encodeGeneratedProperty(entityManager, item, entityToken, component)
                 : item[component]);
         }));
+        entityManager.logger.debug('rehydrated page key map', {
+            dehydrated,
+            entityToken,
+            indexTokens,
+            rehydrated,
+        });
         return rehydrated;
     }
     catch (error) {
+        if (error instanceof Error)
+            entityManager.logger.error(error.message, {
+                dehydrated,
+                entityToken,
+                indexTokens,
+            });
         throw error;
     }
 }

package/dist/cjs/removeKeys.js

@@ -24,9 +24,16 @@ function removeKeys(entityManager, item, entityToken) {
         // Delete generated properties.
         for (const property in entityManager.config.entities[entityToken].generated)
             delete newItem[property];
+        entityManager.logger.debug('stripped entity item generated properties', {
+            item,
+            entityToken,
+            newItem,
+        });
         return newItem;
     }
     catch (error) {
+        if (error instanceof Error)
+            entityManager.logger.error(error.message, { item, entityToken });
         throw error;
     }
 }

package/dist/cjs/unwrapIndex.js

@@ -33,6 +33,8 @@ function unwrapIndex(entityManager, entityToken, indexToken) {
             .sort();
     }
     catch (error) {
+        if (error instanceof Error)
+            entityManager.logger.error(error.message, { indexToken, entityToken });
         throw error;
     }
 }

package/dist/cjs/updateItemHashKey.js

@@ -23,6 +23,11 @@ function updateItemHashKey(entityManager, item, entityToken, overwrite = false)
         validateEntityToken.validateEntityToken(entityManager, entityToken);
         // Return current item if hashKey exists and overwrite is false.
         if (item[entityManager.config.hashKey] && !overwrite) {
+            entityManager.logger.debug('did not overwrite existing entity item hash key', {
+                item,
+                entityToken,
+                overwrite,
+            });
             return { ...item };
         }
         // Get item timestamp property & validate.
@@ -45,9 +50,21 @@ function updateItemHashKey(entityManager, item, entityToken, overwrite = false)
                 .padStart(chars, '0');
         }
         const newItem = Object.assign({ ...item }, { [entityManager.config.hashKey]: hashKey });
+        entityManager.logger.debug('updated entity item hash key', {
+            entityToken,
+            overwrite,
+            item,
+            newItem,
+        });
         return newItem;
     }
     catch (error) {
+        if (error instanceof Error)
+            entityManager.logger.error(error.message, {
+                item,
+                entityToken,
+                overwrite,
+            });
         throw error;
     }
 }

package/dist/cjs/updateItemRangeKey.js

@@ -22,6 +22,11 @@ function updateItemRangeKey(entityManager, item, entityToken, overwrite = false)
         validateEntityToken.validateEntityToken(entityManager, entityToken);
         // Return current item if rangeKey exists and overwrite is false.
         if (item[entityManager.config.rangeKey] && !overwrite) {
+            entityManager.logger.debug('did not overwrite existing entity item range key', {
+                item,
+                entityToken,
+                overwrite,
+            });
             return { ...item };
         }
         // Get item unique property & validate.
@@ -35,9 +40,21 @@ function updateItemRangeKey(entityManager, item, entityToken, overwrite = false)
                 uniqueProperty,
             ].join(entityManager.config.generatedValueDelimiter),
         });
+        entityManager.logger.debug('updated entity item range key', {
+            entityToken,
+            overwrite,
+            item,
+            newItem,
+        });
         return newItem;
     }
     catch (error) {
+        if (error instanceof Error)
+            entityManager.logger.error(error.message, {
+                item,
+                entityToken,
+                overwrite,
+            });
         throw error;
     }
 }

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Entity, Exactify, TranscodeMap, PropertiesOfType, TranscodableProperties, Transcodes, DefaultTranscodeMap, PartialTranscodable, SortOrder } from '@karmaniverous/entity-tools';
+import { Entity, Exactify, TranscodeMap, PropertiesOfType, TranscodableProperties, Transcodes, DefaultTranscodeMap, SortOrder } from '@karmaniverous/entity-tools';
 export { DefaultTranscodeMap, Entity, Exactify, PartialTranscodable, PropertiesNotOfType, PropertiesOfType, SortOrder, TranscodableProperties, TranscodeMap, Transcodes, defaultTranscodes } from '@karmaniverous/entity-tools';
 import { z } from 'zod';
 
@@ -632,23 +632,17 @@ type ParsedConfig = z.infer<typeof configSchema>;
 /**
  * A result returned by a {@link ShardQueryFunction | `ShardQueryFunction`} querying an individual shard.
  *
- * @typeParam Item - The {@link ItemMap | `ItemMap`} type being queried.
- * @typeParam T - The {@link TranscodeMap | `TranscodeMap`} identifying property types that can be indexed.
+ * @typeParam Item - The {@link Item | `Item`} type being queried.
 
 * @category Query
  */
-interface ShardQueryResult<Item extends ItemMap<M, HashKey, RangeKey>[EntityToken], EntityToken extends keyof Exactify<M> & string, M extends EntityMap, HashKey extends string = 'hashKey', RangeKey extends string = 'rangeKey', T extends TranscodeMap = DefaultTranscodeMap> {
+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?: PartialTranscodable<Item, T>;
-}
-interface ClientShardQueryResult {
-    count: number;
-    items: Entity[];
-    pageKey?: Entity;
+    pageKey?: Partial<Item>;
 }
 
 /**
@@ -658,27 +652,24 @@ interface ClientShardQueryResult {
  * 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 ItemMap | `ItemMap`} type being queried.
- * @typeParam T - The {@link TranscodeMap | `TranscodeMap`} identifying property types that can be indexed. Defaults to {@link DefaultTranscodeMap | `DefaultTranscodeMap`}.
+ * @typeParam Item - The {@link Item | `Item`} type being queried.
 
- * @param hashKey - The {@link ConfigKeys.hashKey | `this.config.hashKey`} property value of the shard 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 ItemMap<M, HashKey, RangeKey>[EntityToken], EntityToken extends keyof Exactify<M> & string, M extends EntityMap, HashKey extends string = 'hashKey', RangeKey extends string = 'rangeKey', T extends TranscodeMap = DefaultTranscodeMap> = (hashKey: string, pageKey?: PartialTranscodable<Item, T>, pageSize?: number) => Promise<ShardQueryResult<Item, EntityToken, M, HashKey, RangeKey, T>>;
-type ClientShardQueryFunction = (hashKey: string, pageKey?: Entity, pageSize?: number) => Promise<ClientShardQueryResult>;
+type ShardQueryFunction<Item extends Entity> = (hashKey: string, pageKey?: Partial<Item>, pageSize?: number) => Promise<ShardQueryResult<Item>>;
 
-type ShardQueryMap<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> = Record<string, ShardQueryFunction<Item, EntityToken, M, HashKey, RangeKey, T>>;
-type ClientShardQueryMap = Record<string, ClientShardQueryFunction>;
+type ShardQueryMap<Item extends Entity> = Record<string, ShardQueryFunction<Item>>;
 
 /**
  * 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, T extends TranscodeMap> {
+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;
     /**
@@ -717,7 +708,7 @@ interface QueryOptions<Item extends ItemMap<M, HashKey, RangeKey>[EntityToken],
      * page key, e.g. to match the same string against `firstName` and `lastName`
      * properties without performing a table scan for either.
      */
-    shardQueryMap: ShardQueryMap<Item, EntityToken, M, HashKey, RangeKey, T>;
+    shardQueryMap: ShardQueryMap<Item>;
     /**
      * A {@link SortOrder | `SortOrder`} object specifying the sort order of the result set. Defaults to `[]`.
      */
@@ -776,12 +767,14 @@ interface QueryResult<Item extends ItemMap<M, HashKey, RangeKey>[EntityToken], E
  */
 declare class EntityManager<M extends EntityMap, HashKey extends string, RangeKey extends string, T extends TranscodeMap> {
     #private;
+    logger: Pick<Console, 'debug' | 'error'>;
     /**
      * Create an EntityManager instance.
      *
      * @param config - EntityManager {@link Config | `Config`} object.
+     * @param logger - Logger object (defaults to `console`, must support `debug` & `error` methods).
      */
-    constructor(config: Config<M, HashKey, RangeKey, T>);
+    constructor(config: Config<M, HashKey, RangeKey, T>, logger?: Pick<Console, 'debug' | 'error'>);
     /**
      * Get the current EntityManager {@link Config | `Config`} object.
      *
@@ -835,21 +828,7 @@ declare class EntityManager<M extends EntityMap, HashKey extends string, RangeKe
      *
      * @throws Error if {@link QueryOptions.pageKeyMap | `pageKeyMap`} keys do not match {@link QueryOptions.shardQueryMap | `shardQueryMap`} keys.
      */
-    query<Item extends ItemMap<M, HashKey, RangeKey>[EntityToken], EntityToken extends keyof Exactify<M> & string>(options: QueryOptions<Item, EntityToken, M, HashKey, RangeKey, T>): Promise<QueryResult<Item, EntityToken, M, HashKey, RangeKey>>;
-}
-
-/**
- * Options for EntityManager client methods that support batch operations.
- */
-interface EntityManagerClientBatchOptions {
-    /** Batch size. */
-    batchSize?: number;
-    /** Delay increment in ms for retry operations. Doubles on each retry. */
-    delayIncrement?: number;
-    /** Max retries for retry operations. */
-    maxRetries?: number;
-    /** Throttle for parallel operations. */
-    throttle?: number;
+    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>>;
 }
 
 /**
@@ -879,58 +858,18 @@ interface LoggerOptions {
     logInternals?: boolean;
 }
 
-/**
- * EntityManagerClient base class options.
- *
- * @category Client
- */
-type EntityManagerClientOptions = EntityManagerClientBatchOptions & LoggerOptions;
-/**
- * EntityManagerClient base class.
- *
- * @typeParam Options - Options type extended from {@link EntityManagerClientOptions | `EntityManagerClientOptions`}.
- *
- * @category Client
- */
-declare abstract class EntityManagerClient<Options extends EntityManagerClientOptions> {
-    #private;
-    /**
-     * EntityManagerClient base constructor.
-     * @param options - Options object extended from {@link EntityManagerClientOptions | `EntityManagerClientOptions`}.
-     */
-    constructor({ batchSize, delayIncrement, maxRetries, throttle, logger, logInternals, ...childOptions }: Options);
-    /**
-     * Returns the options used to create the EntityManagerClient instance.
-     */
-    get options(): Required<Options>;
-    /**
-     * Executes a batch operation.
-     *
-     * @param items - Items to batch execute.
-     * @param executeBatch - Function to execute the batch.
-     * @param getUnprocessedItems - Function to get unprocessed items from the output.
-     * @param options - Batch options.
-     *
-     * @typeParam Item - Input item type.
-     * @typeParam Output - Output type.
-     *
-     * @returns Output array.
-     */
-    protected batchExecute<Item, Output>(items: Item[], executeBatch: (items: Item[]) => Promise<Output>, getUnprocessedItems?: (output: Output) => Item[] | undefined, { batchSize, delayIncrement, maxRetries, throttle, }?: EntityManagerClientBatchOptions): Promise<Output[]>;
-}
-
 /**
  * {@link ShardQueryMapBuilder | `ShardQueryMapBuilder`} options.
  *
  * @category Query
  */
-interface ShardQueryMapBuilderOptions {
+interface ShardQueryMapBuilderOptions<Item extends Entity> {
     /** `entityManager.config.entities` key. */
     entityToken: string;
     /** Either the designated entity hash key or a generated property with `sharded === true`. */
     hashKeyToken: string;
     /** A partial `Item` sufficiently populated to generate the query hash key & index values. */
-    item: Entity;
+    item: Item;
     /** Dehydrated page key from the previous query data page. */
     pageKey?: string;
 }
@@ -940,10 +879,10 @@ interface ShardQueryMapBuilderOptions {
  *
  * @category Query
  */
-declare abstract class ShardQueryMapBuilder<Options extends ShardQueryMapBuilderOptions> {
+declare abstract class ShardQueryMapBuilder<Item extends Entity, Options extends ShardQueryMapBuilderOptions<Item>> {
     readonly options: Options;
     constructor(options: Options);
-    abstract getShardQueryMap(): ClientShardQueryMap;
+    abstract getShardQueryMap(): ShardQueryMap<Item>;
 }
 
 /**
@@ -956,4 +895,4 @@ type WithRequiredAndNonNullable<T, K extends keyof T> = T & {
     [P in K]-?: NonNullable<T[P]>;
 };
 
-export { type Config, type ConfigEntities, type ConfigEntity, type ConfigEntityGenerated, type ConfigKeys, type ConfigTranscodes, EntityManager, EntityManagerClient, type EntityManagerClientBatchOptions, type EntityManagerClientOptions, type EntityMap, type ExclusiveKey, type ItemMap, type Logger, type LoggerEndpoint, type LoggerOptions, type ParsedConfig, type QueryOptions, type QueryResult, type ShardBump, type ShardQueryFunction, type ShardQueryMap, ShardQueryMapBuilder, type ShardQueryMapBuilderOptions, type ShardQueryResult, type Unwrap, type WithRequiredAndNonNullable, conditionalize };
+export { type Config, type ConfigEntities, type ConfigEntity, type ConfigEntityGenerated, type ConfigKeys, type ConfigTranscodes, EntityManager, type EntityMap, type ExclusiveKey, type ItemMap, type Logger, type LoggerEndpoint, type LoggerOptions, type ParsedConfig, type QueryOptions, type QueryResult, type ShardBump, type ShardQueryFunction, type ShardQueryMap, ShardQueryMapBuilder, type ShardQueryMapBuilderOptions, type ShardQueryResult, type Unwrap, type WithRequiredAndNonNullable, conditionalize };

package/dist/mjs/EntityManager.js

@@ -16,10 +16,12 @@ class EntityManager {
      * Create an EntityManager instance.
      *
      * @param config - EntityManager {@link Config | `Config`} object.
+     * @param logger - Logger object (defaults to `console`, must support `debug` & `error` methods).
      */
-    constructor(config) {
+    constructor(config, logger = console) {
         _EntityManager_config.set(this, void 0);
         __classPrivateFieldSet(this, _EntityManager_config, configSchema.parse(config), "f");
+        this.logger = logger;
     }
     /**
      * Get the current EntityManager {@link Config | `Config`} object.

package/dist/mjs/addKeys.js

@@ -35,9 +35,21 @@ function addKeys(entityManager, item, entityToken, overwrite = false) {
                     delete newItem[property];
             }
         }
+        entityManager.logger.debug('updated entity item generated properties', {
+            item,
+            entityToken,
+            overwrite,
+            newItem,
+        });
         return newItem;
     }
     catch (error) {
+        if (error instanceof Error)
+            entityManager.logger.error(error.message, {
+                item,
+                entityToken,
+                overwrite,
+            });
         throw error;
     }
 }

package/dist/mjs/decodeEntityElement.js

@@ -25,9 +25,21 @@ function decodeEntityElement(entityManager, value, entityToken, element) {
         if ([hashKey, rangeKey].includes(element))
             return value;
         const decoded = transcodes[entities[entityToken].elementTranscodes[element]].decode(value);
+        entityManager.logger.debug('decoded entity element', {
+            value,
+            entityToken,
+            element,
+            decoded,
+        });
         return decoded;
     }
     catch (error) {
+        if (error instanceof Error)
+            entityManager.logger.error(error.message, {
+                value,
+                entityToken,
+                element,
+            });
         throw error;
     }
 }

package/dist/mjs/decodeGeneratedProperty.js

@@ -36,9 +36,16 @@ function decodeGeneratedProperty(entityManager, encoded, entityToken) {
         });
         // Assign decoded properties.
         Object.assign(decoded, objectify(values, ([key]) => key, ([key, value]) => decodeEntityElement(entityManager, value, entityToken, key)));
+        entityManager.logger.debug('decoded generated property', {
+            encoded,
+            entityToken,
+            decoded,
+        });
         return decoded;
     }
     catch (error) {
+        if (error instanceof Error)
+            entityManager.logger.error(error.message, { encoded, entityToken });
         throw error;
     }
 }

package/dist/mjs/dehydrateIndexItem.js

@@ -40,9 +40,22 @@ function dehydrateIndexItem(entityManager, item, entityToken, indexToken, omit =
         const dehydrated = elements
             .map((element) => encodeEntityElement(entityManager, item, entityToken, element))
             .join(generatedKeyDelimiter);
+        entityManager.logger.debug('dehydrated index', {
+            item,
+            entityToken,
+            indexToken,
+            elements,
+            dehydrated,
+        });
         return dehydrated;
     }
     catch (error) {
+        if (error instanceof Error)
+            entityManager.logger.error(error.message, {
+                item,
+                entityToken,
+                indexToken,
+            });
         throw error;
     }
 }

package/dist/mjs/dehydratePageKeyMap.js

@@ -29,6 +29,11 @@ function dehydratePageKeyMap(entityManager, pageKeyMap, entityToken) {
         // Shortcut empty pageKeyMap.
         if (!Object.keys(pageKeyMap).length) {
             const dehydrated = [];
+            entityManager.logger.debug('dehydrated empty page key map', {
+                pageKeyMap,
+                entityToken,
+                dehydrated,
+            });
             return dehydrated;
         }
         // Extract, sort & validate indexs.
@@ -63,9 +68,18 @@ function dehydratePageKeyMap(entityManager, pageKeyMap, entityToken) {
         // Replace with empty array if all pageKeys are empty strings.
         if (dehydrated.every((pageKey) => pageKey === ''))
             dehydrated = [];
+        entityManager.logger.debug('dehydrated page key map', {
+            pageKeyMap,
+            entityToken,
+            indexes,
+            hashKeys,
+            dehydrated,
+        });
         return dehydrated;
     }
     catch (error) {
+        if (error instanceof Error)
+            entityManager.logger.error(error.message, { entityToken, pageKeyMap });
         throw error;
     }
 }

package/dist/mjs/encodeEntityElement.js

@@ -24,9 +24,17 @@ function encodeEntityElement(entityManager, item, entityToken, element) {
         if (value === undefined || [hashKey, rangeKey].includes(element))
             return value;
         const encoded = transcodes[entities[entityToken].elementTranscodes[element]].encode(item[element]) || undefined;
+        entityManager.logger.debug('encoded entity element', {
+            item,
+            entityToken,
+            element,
+            encoded,
+        });
         return encoded;
     }
     catch (error) {
+        if (error instanceof Error)
+            entityManager.logger.error(error.message, { item, entityToken, element });
         throw error;
     }
 }

package/dist/mjs/encodeGeneratedProperty.js

@@ -32,9 +32,21 @@ function encodeGeneratedProperty(entityManager, item, entityToken, property) {
             ...(sharded ? [item[entityManager.config.hashKey]] : []),
             ...elementMap.map(([element, value]) => [element, (value ?? '').toString()].join(entityManager.config.generatedValueDelimiter)),
         ].join(entityManager.config.generatedKeyDelimiter);
+        entityManager.logger.debug('encoded generated property', {
+            item,
+            entityToken,
+            property,
+            encoded,
+        });
         return encoded;
     }
     catch (error) {
+        if (error instanceof Error)
+            entityManager.logger.error(error.message, {
+                item,
+                entityToken,
+                property,
+            });
         throw error;
     }
 }

package/dist/mjs/getHashKeySpace.js

@@ -29,9 +29,21 @@ function getHashKeySpace(entityManager, entityToken, timestampFrom = 0, timestam
                 : '';
         })
             .map((shardKey) => `${entityToken}${entityManager.config.shardKeyDelimiter}${shardKey}`);
+        entityManager.logger.debug('generated hash key space', {
+            entityToken,
+            timestampFrom,
+            timestampTo,
+            hashKeySpace,
+        });
         return hashKeySpace;
     }
     catch (error) {
+        if (error instanceof Error)
+            entityManager.logger.error(error.message, {
+                entityToken,
+                timestampFrom,
+                timestampTo,
+            });
         throw error;
     }
 }

package/dist/mjs/index.js

@@ -1,4 +1,3 @@
 export { conditionalize } from './conditionalize.js';
 export { EntityManager } from './EntityManager.js';
-export { EntityManagerClient } from './EntityManagerClient.js';
 export { ShardQueryMapBuilder } from './ShardQueryMapBuilder.js';

package/dist/mjs/query.js

@@ -90,9 +90,35 @@ async function query(entityManager, { entityToken, hashKey, limit, pageKeyMap, p
             items: workingResult.items,
             pageKeyMap: compressToEncodedURIComponent(JSON.stringify(dehydratePageKeyMap(entityManager, workingResult.pageKeyMap, entityToken))),
         };
+        entityManager.logger.debug('queried entityToken across shards', {
+            entityToken,
+            hashKey,
+            limit,
+            pageKeyMap,
+            pageSize,
+            shardQueryMap,
+            timestampFrom,
+            timestampTo,
+            throttle,
+            rehydratedPageKeyMap,
+            workingResult,
+            result,
+        });
         return result;
     }
     catch (error) {
+        if (error instanceof Error)
+            entityManager.logger.error(error.message, {
+                entityToken,
+                hashKey,
+                limit,
+                pageKeyMap,
+                pageSize,
+                shardQueryMap,
+                timestampFrom,
+                timestampTo,
+                throttle,
+            });
         throw error;
     }
 }

package/dist/mjs/rehydrateIndexItem.js

@@ -35,9 +35,23 @@ function rehydrateIndexItem(entityManager, dehydrated, entityToken, indexToken,
             throw new Error('index rehydration key-value mismatch');
         // Assign values to elements.
         const rehydrated = shake(zipToObject(elements, values.map((value, i) => decodeEntityElement(entityManager, value, entityToken, elements[i]))));
+        entityManager.logger.debug('rehydrated index', {
+            dehydrated,
+            entityToken,
+            indexToken,
+            elements,
+            values,
+            rehydrated,
+        });
         return rehydrated;
     }
     catch (error) {
+        if (error instanceof Error)
+            entityManager.logger.error(error.message, {
+                dehydrated,
+                entityToken,
+                indexToken,
+            });
         throw error;
     }
 }

package/dist/mjs/rehydratePageKeyMap.js

@@ -53,9 +53,21 @@ function rehydratePageKeyMap(entityManager, dehydrated, entityToken, indexTokens
                 ? encodeGeneratedProperty(entityManager, item, entityToken, component)
                 : item[component]);
         }));
+        entityManager.logger.debug('rehydrated page key map', {
+            dehydrated,
+            entityToken,
+            indexTokens,
+            rehydrated,
+        });
         return rehydrated;
     }
     catch (error) {
+        if (error instanceof Error)
+            entityManager.logger.error(error.message, {
+                dehydrated,
+                entityToken,
+                indexTokens,
+            });
         throw error;
     }
 }

package/dist/mjs/removeKeys.js

@@ -22,9 +22,16 @@ function removeKeys(entityManager, item, entityToken) {
         // Delete generated properties.
         for (const property in entityManager.config.entities[entityToken].generated)
             delete newItem[property];
+        entityManager.logger.debug('stripped entity item generated properties', {
+            item,
+            entityToken,
+            newItem,
+        });
         return newItem;
     }
     catch (error) {
+        if (error instanceof Error)
+            entityManager.logger.error(error.message, { item, entityToken });
         throw error;
     }
 }

package/dist/mjs/unwrapIndex.js

@@ -31,6 +31,8 @@ function unwrapIndex(entityManager, entityToken, indexToken) {
             .sort();
     }
     catch (error) {
+        if (error instanceof Error)
+            entityManager.logger.error(error.message, { indexToken, entityToken });
         throw error;
     }
 }

package/dist/mjs/updateItemHashKey.js

@@ -21,6 +21,11 @@ function updateItemHashKey(entityManager, item, entityToken, overwrite = false)
         validateEntityToken(entityManager, entityToken);
         // Return current item if hashKey exists and overwrite is false.
         if (item[entityManager.config.hashKey] && !overwrite) {
+            entityManager.logger.debug('did not overwrite existing entity item hash key', {
+                item,
+                entityToken,
+                overwrite,
+            });
             return { ...item };
         }
         // Get item timestamp property & validate.
@@ -43,9 +48,21 @@ function updateItemHashKey(entityManager, item, entityToken, overwrite = false)
                 .padStart(chars, '0');
         }
         const newItem = Object.assign({ ...item }, { [entityManager.config.hashKey]: hashKey });
+        entityManager.logger.debug('updated entity item hash key', {
+            entityToken,
+            overwrite,
+            item,
+            newItem,
+        });
         return newItem;
     }
     catch (error) {
+        if (error instanceof Error)
+            entityManager.logger.error(error.message, {
+                item,
+                entityToken,
+                overwrite,
+            });
         throw error;
     }
 }

package/dist/mjs/updateItemRangeKey.js

@@ -20,6 +20,11 @@ function updateItemRangeKey(entityManager, item, entityToken, overwrite = false)
         validateEntityToken(entityManager, entityToken);
         // Return current item if rangeKey exists and overwrite is false.
         if (item[entityManager.config.rangeKey] && !overwrite) {
+            entityManager.logger.debug('did not overwrite existing entity item range key', {
+                item,
+                entityToken,
+                overwrite,
+            });
             return { ...item };
         }
         // Get item unique property & validate.
@@ -33,9 +38,21 @@ function updateItemRangeKey(entityManager, item, entityToken, overwrite = false)
                 uniqueProperty,
             ].join(entityManager.config.generatedValueDelimiter),
         });
+        entityManager.logger.debug('updated entity item range key', {
+            entityToken,
+            overwrite,
+            item,
+            newItem,
+        });
         return newItem;
     }
     catch (error) {
+        if (error instanceof Error)
+            entityManager.logger.error(error.message, {
+                item,
+                entityToken,
+                overwrite,
+            });
         throw error;
     }
 }

package/package.json

@@ -14,50 +14,50 @@
   },
   "description": "Rational indexing & cross-shard querying at scale in your NoSQL database so you can focus on your application logic.",
   "devDependencies": {
-    "@dotenvx/dotenvx": "^1.16.1",
-    "@eslint/js": "^9.12.0",
+    "@dotenvx/dotenvx": "^1.20.0",
+    "@eslint/js": "^9.13.0",
     "@faker-js/faker": "^9.0.3",
     "@karmaniverous/mock-db": "^0.3.3",
     "@rollup/plugin-alias": "^5.1.1",
-    "@rollup/plugin-commonjs": "^28.0.0",
+    "@rollup/plugin-commonjs": "^28.0.1",
     "@rollup/plugin-json": "^6.1.0",
     "@rollup/plugin-node-resolve": "^15.3.0",
     "@rollup/plugin-strip": "^3.0.4",
-    "@rollup/plugin-typescript": "^12.1.0",
+    "@rollup/plugin-typescript": "^12.1.1",
     "@types/chai": "^5.0.0",
     "@types/eslint__js": "^8.42.3",
     "@types/eslint-config-prettier": "^6.11.3",
     "@types/eslint-plugin-mocha": "^10.4.0",
     "@types/mocha": "^10.0.9",
-    "@types/node": "^22.7.5",
+    "@types/node": "^22.7.8",
     "@types/string-hash": "^1.1.3",
     "auto-changelog": "^2.5.0",
     "chai": "^5.1.1",
     "cross-env": "^7.0.3",
-    "eslint": "^9.12.0",
+    "eslint": "^9.13.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.33.2",
-    "lefthook": "^1.7.18",
+    "knip": "^5.33.3",
+    "lefthook": "^1.7.22",
     "mocha": "^10.7.3",
     "nyc": "^17.1.0",
     "prettier": "^3.3.3",
-    "release-it": "^17.7.0",
+    "release-it": "^17.10.0",
     "rimraf": "^6.0.1",
     "rollup": "^4.24.0",
     "rollup-plugin-dts": "^6.1.1",
     "source-map-support": "^0.5.21",
     "ts-node": "^10.9.2",
-    "tslib": "^2.7.0",
-    "typedoc": "^0.26.8",
-    "typedoc-plugin-mdn-links": "^3.3.2",
+    "tslib": "^2.8.0",
+    "typedoc": "^0.26.10",
+    "typedoc-plugin-mdn-links": "^3.3.4",
     "typedoc-plugin-replace-text": "^4.0.0",
     "typedoc-plugin-zod": "^1.2.1",
     "typescript": "^5.6.3",
-    "typescript-eslint": "^8.8.1"
+    "typescript-eslint": "^8.11.0"
   },
   "exports": {
     ".": {
@@ -132,5 +132,5 @@
   },
   "type": "module",
   "types": "dist/index.d.ts",
-  "version": "6.4.2"
+  "version": "6.4.4"
 }

package/dist/cjs/EntityManagerClient.js

@@ -1,90 +0,0 @@
-'use strict';
-
-var tslib = require('tslib');
-var radash = require('radash');
-var promises = require('timers/promises');
-var conditionalize = require('./conditionalize.js');
-
-var _EntityManagerClient_options;
-/**
- * EntityManagerClient base class.
- *
- * @typeParam Options - Options type extended from {@link EntityManagerClientOptions | `EntityManagerClientOptions`}.
- *
- * @category Client
- */
-class EntityManagerClient {
-    /**
-     * EntityManagerClient base constructor.
-     * @param options - Options object extended from {@link EntityManagerClientOptions | `EntityManagerClientOptions`}.
-     */
-    constructor({ batchSize = 25, delayIncrement = 100, maxRetries = 5, throttle = 10, logger = console, logInternals = false, ...childOptions }) {
-        _EntityManagerClient_options.set(this, void 0);
-        if (!radash.isFunction(logger.debug))
-            throw new Error('logger must support debug method');
-        if (!radash.isFunction(logger.error))
-            throw new Error('logger must support error method');
-        tslib.__classPrivateFieldSet(this, _EntityManagerClient_options, {
-            batchSize,
-            delayIncrement,
-            maxRetries,
-            throttle,
-            logInternals,
-            logger: {
-                ...logger,
-                debug: conditionalize.conditionalize(logger.debug, logInternals),
-            },
-            ...childOptions,
-        }, "f");
-    }
-    /**
-     * Returns the options used to create the EntityManagerClient instance.
-     */
-    get options() {
-        return tslib.__classPrivateFieldGet(this, _EntityManagerClient_options, "f");
-    }
-    /**
-     * Executes a batch operation.
-     *
-     * @param items - Items to batch execute.
-     * @param executeBatch - Function to execute the batch.
-     * @param getUnprocessedItems - Function to get unprocessed items from the output.
-     * @param options - Batch options.
-     *
-     * @typeParam Item - Input item type.
-     * @typeParam Output - Output type.
-     *
-     * @returns Output array.
-     */
-    async batchExecute(items, executeBatch, getUnprocessedItems, { batchSize = this.options.batchSize, delayIncrement = this.options.delayIncrement, maxRetries = this.options.maxRetries, throttle = this.options.throttle, } = {}) {
-        const batches = radash.cluster(items, batchSize);
-        const outputs = [];
-        await radash.parallel(throttle, batches, async (batch) => {
-            let delay = 0;
-            let retry = 0;
-            while (batch.length) {
-                if (delay)
-                    await promises.setTimeout(delay);
-                const output = await executeBatch(batch);
-                this.options.logger.debug('executed batch', {
-                    batch,
-                    delay,
-                    retry,
-                    output,
-                });
-                outputs.push(output);
-                batch = getUnprocessedItems?.(output) ?? [];
-                if (batch.length) {
-                    if (retry === maxRetries)
-                        throw new Error('max retries exceeded');
-                    delay = delay ? delay * 2 : delayIncrement;
-                    retry++;
-                }
-            }
-        });
-        return outputs;
-    }
-}
-_EntityManagerClient_options = new WeakMap();
-
-exports.EntityManagerClient = EntityManagerClient;

package/dist/mjs/EntityManagerClient.js

@@ -1,88 +0,0 @@
-import { __classPrivateFieldSet, __classPrivateFieldGet } from 'tslib';
-import { isFunction, cluster, parallel } from 'radash';
-import { setTimeout } from 'timers/promises';
-import { conditionalize } from './conditionalize.js';
-
-var _EntityManagerClient_options;
-/**
- * EntityManagerClient base class.
- *
- * @typeParam Options - Options type extended from {@link EntityManagerClientOptions | `EntityManagerClientOptions`}.
- *
- * @category Client
- */
-class EntityManagerClient {
-    /**
-     * EntityManagerClient base constructor.
-     * @param options - Options object extended from {@link EntityManagerClientOptions | `EntityManagerClientOptions`}.
-     */
-    constructor({ batchSize = 25, delayIncrement = 100, maxRetries = 5, throttle = 10, logger = console, logInternals = false, ...childOptions }) {
-        _EntityManagerClient_options.set(this, void 0);
-        if (!isFunction(logger.debug))
-            throw new Error('logger must support debug method');
-        if (!isFunction(logger.error))
-            throw new Error('logger must support error method');
-        __classPrivateFieldSet(this, _EntityManagerClient_options, {
-            batchSize,
-            delayIncrement,
-            maxRetries,
-            throttle,
-            logInternals,
-            logger: {
-                ...logger,
-                debug: conditionalize(logger.debug, logInternals),
-            },
-            ...childOptions,
-        }, "f");
-    }
-    /**
-     * Returns the options used to create the EntityManagerClient instance.
-     */
-    get options() {
-        return __classPrivateFieldGet(this, _EntityManagerClient_options, "f");
-    }
-    /**
-     * Executes a batch operation.
-     *
-     * @param items - Items to batch execute.
-     * @param executeBatch - Function to execute the batch.
-     * @param getUnprocessedItems - Function to get unprocessed items from the output.
-     * @param options - Batch options.
-     *
-     * @typeParam Item - Input item type.
-     * @typeParam Output - Output type.
-     *
-     * @returns Output array.
-     */
-    async batchExecute(items, executeBatch, getUnprocessedItems, { batchSize = this.options.batchSize, delayIncrement = this.options.delayIncrement, maxRetries = this.options.maxRetries, throttle = this.options.throttle, } = {}) {
-        const batches = cluster(items, batchSize);
-        const outputs = [];
-        await parallel(throttle, batches, async (batch) => {
-            let delay = 0;
-            let retry = 0;
-            while (batch.length) {
-                if (delay)
-                    await setTimeout(delay);
-                const output = await executeBatch(batch);
-                this.options.logger.debug('executed batch', {
-                    batch,
-                    delay,
-                    retry,
-                    output,
-                });
-                outputs.push(output);
-                batch = getUnprocessedItems?.(output) ?? [];
-                if (batch.length) {
-                    if (retry === maxRetries)
-                        throw new Error('max retries exceeded');
-                    delay = delay ? delay * 2 : delayIncrement;
-                    retry++;
-                }
-            }
-        });
-        return outputs;
-    }
-}
-_EntityManagerClient_options = new WeakMap();
-
-export { EntityManagerClient };