@karmaniverous/entity-manager 6.0.0 → 6.1.0-0

package/README.md

@@ -1,10 +1,14 @@
-# entity-manager
+<!-- TYPEDOC_EXCLUDE -->
+
+> [API Documentation](https://docs.karmanivero.us/entity-manager/) • [CHANGELOG](https://github.com/karmaniverous/entity-manager/tree/main/CHANGELOG.md)
 
-> [API Documentation](https://karmanivero.us/entity-manager/) • [CHANGELOG](https://github.com/karmaniverous/entity-manager/tree/main/CHANGELOG.md)
+<!-- /TYPEDOC_EXCLUDE -->
+
+# entity-manager
 
 **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.
+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/).
 
 If you have any questions, please [start a discussion](https://github.com/karmaniverous/entity-manager/discussions). Otherwise stay tuned!
 
@@ -29,4 +33,3 @@ With EntityManager, you can:
 ---
 
 Built for you with ❤️ on Bali! Find more great tools & templates on [my GitHub Profile](https://github.com/karmaniverous).
-

package/dist/cjs/src/EntityManagerClient.js

@@ -0,0 +1,37 @@
+'use strict';
+
+var tslib_es6 = require('../node_modules/tslib/tslib.es6.js');
+var conditionalize = require('./conditionalize.js');
+
+var _EntityManagerClient_options;
+/**
+ * EntityManagerClient base class.
+ *
+ * @category Client
+ */
+class EntityManagerClient {
+    constructor({ batchSize = 25, delayIncrement = 100, maxRetries = 5, throttle = 10, logger = console, logInternals = false, ...options }) {
+        _EntityManagerClient_options.set(this, void 0);
+        tslib_es6.__classPrivateFieldSet(this, _EntityManagerClient_options, {
+            ...options,
+            batchSize,
+            delayIncrement,
+            maxRetries,
+            throttle,
+            logInternals,
+            logger: {
+                ...logger,
+                debug: conditionalize.conditionalize(logger.debug, logInternals),
+            },
+        }, "f");
+    }
+    /**
+     * Returns the options used to create the EntityManagerClient instance.
+     */
+    get options() {
+        return tslib_es6.__classPrivateFieldGet(this, _EntityManagerClient_options, "f");
+    }
+}
+_EntityManagerClient_options = new WeakMap();
+
+exports.EntityManagerClient = EntityManagerClient;

package/dist/cjs/src/ParsedConfig.js

@@ -55,7 +55,7 @@ const configSchema = index.default
             .optional())
             .optional()
             .default({}),
-        elementTypes: index.default.record(index.default.string()).optional().default({}),
+        elementTranscodes: index.default.record(index.default.string()).optional().default({}),
         indexes: index.default
             .record(index.default
             .array(index.default.string().min(1))
@@ -184,16 +184,16 @@ const configSchema = index.default
     const transcodes = Object.keys(data.transcodes);
     for (const [entityToken, entity] of Object.entries(data.entities)) {
         // validate all entity generated element type values are transcode keys.
-        for (const [element, generatedElementType] of Object.entries(entity.elementTypes))
+        for (const [element, generatedElementType] of Object.entries(entity.elementTranscodes))
             if (!transcodes.includes(generatedElementType))
                 ctx.addIssue({
                     code: index.default.ZodIssueCode.invalid_enum_value,
                     options: transcodes,
-                    path: ['entities', entityToken, 'elementTypes', element],
+                    path: ['entities', entityToken, 'elementTranscodes', element],
                     received: generatedElementType,
                 });
         // validate all entity generated property elements have a corresponding entity element type.
-        const typedElements = Object.keys(entity.elementTypes);
+        const typedElements = Object.keys(entity.elementTranscodes);
         for (const [generatedKey, generated] of Object.entries(entity.generated))
             for (const element of generated?.elements ?? [])
                 if (!typedElements.includes(element))

package/dist/cjs/src/conditionalize.js

@@ -0,0 +1,25 @@
+'use strict';
+
+/**
+ * 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`.
+ *
+ */
+function conditionalize(fn, condition) {
+    return (...args) => {
+        if (condition) {
+            return fn(...args);
+        }
+        else {
+            return undefined;
+        }
+    };
+}
+
+exports.conditionalize = conditionalize;

package/dist/cjs/src/decodeEntityElement.js

@@ -26,7 +26,7 @@ function decodeEntityElement(entityManager, value, entityToken, element) {
             return;
         if ([hashKey, rangeKey].includes(element))
             return value;
-        const decoded = transcodes[entities[entityToken].elementTypes[element]].decode(value);
+        const decoded = transcodes[entities[entityToken].elementTranscodes[element]].decode(value);
         return decoded;
     }
     catch (error) {

package/dist/cjs/src/encodeEntityElement.js

@@ -25,7 +25,7 @@ function encodeEntityElement(entityManager, item, entityToken, element) {
         const value = item[element];
         if (value === undefined || [hashKey, rangeKey].includes(element))
             return value;
-        const encoded = transcodes[entities[entityToken].elementTypes[element]].encode(item[element]) || undefined;
+        const encoded = transcodes[entities[entityToken].elementTranscodes[element]].encode(item[element]) || undefined;
         return encoded;
     }
     catch (error) {

package/dist/cjs/src/index.js

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

package/dist/index.d.cts

@@ -2,6 +2,19 @@ import { Entity, Exactify, TranscodeMap, PropertiesOfType, TranscodablePropertie
 export { DefaultTranscodeMap, Entity, PropertiesOfType, SortOrder, TranscodableProperties, TranscodeMap, Transcodes, defaultTranscodes } 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.
  *
@@ -153,7 +166,7 @@ type ConfigEntity<EntityToken extends keyof Exactify<M>, M extends EntityMap, Ha
      * };
      * ```
      */
-    elementTypes?: ([TranscodableProperties<M[EntityToken], T>] extends [never] ? never : {
+    elementTranscodes?: ([TranscodableProperties<M[EntityToken], T>] extends [never] ? never : {
         [P in TranscodableProperties<M[EntityToken], T>]?: PropertiesOfType<T, M[EntityToken][P]>;
     }) | ([TranscodableProperties<M[EntityToken], T>] extends [never] ? Record<string, never> : never);
     /**
@@ -366,7 +379,7 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
             atomic?: boolean | undefined;
             sharded?: boolean | undefined;
         }>>>>>;
-        elementTypes: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>>;
+        elementTranscodes: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>>;
         indexes: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodArray<z.ZodString, "atleastone">, [string, ...string[]], [string, ...string[]]>>>>;
         shardBumps: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
             timestamp: z.ZodNumber;
@@ -410,7 +423,7 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
     }, "strict", z.ZodTypeAny, {
         defaultLimit: number;
         defaultPageSize: number;
-        elementTypes: Record<string, string>;
+        elementTranscodes: Record<string, string>;
         indexes: Record<string, [string, ...string[]]>;
         shardBumps: {
             timestamp: number;
@@ -429,7 +442,7 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
         uniqueProperty: string;
         defaultLimit?: number | undefined;
         defaultPageSize?: number | undefined;
-        elementTypes?: Record<string, string> | undefined;
+        elementTranscodes?: Record<string, string> | undefined;
         indexes?: Record<string, [string, ...string[]]> | undefined;
         shardBumps?: {
             timestamp: number;
@@ -444,7 +457,7 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
     }>, {
         defaultLimit: number;
         defaultPageSize: number;
-        elementTypes: Record<string, string>;
+        elementTranscodes: Record<string, string>;
         indexes: Record<string, [string, ...string[]]>;
         shardBumps: {
             timestamp: number;
@@ -463,7 +476,7 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
         uniqueProperty: string;
         defaultLimit?: number | undefined;
         defaultPageSize?: number | undefined;
-        elementTypes?: Record<string, string> | undefined;
+        elementTranscodes?: Record<string, string> | undefined;
         indexes?: Record<string, [string, ...string[]]> | undefined;
         shardBumps?: {
             timestamp: number;
@@ -498,7 +511,7 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
     entities: Record<string, {
         defaultLimit: number;
         defaultPageSize: number;
-        elementTypes: Record<string, string>;
+        elementTranscodes: Record<string, string>;
         indexes: Record<string, [string, ...string[]]>;
         shardBumps: {
             timestamp: number;
@@ -529,7 +542,7 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
         uniqueProperty: string;
         defaultLimit?: number | undefined;
         defaultPageSize?: number | undefined;
-        elementTypes?: Record<string, string> | undefined;
+        elementTranscodes?: Record<string, string> | undefined;
         indexes?: Record<string, [string, ...string[]]> | undefined;
         shardBumps?: {
             timestamp: number;
@@ -556,7 +569,7 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
     entities: Record<string, {
         defaultLimit: number;
         defaultPageSize: number;
-        elementTypes: Record<string, string>;
+        elementTranscodes: Record<string, string>;
         indexes: Record<string, [string, ...string[]]>;
         shardBumps: {
             timestamp: number;
@@ -587,7 +600,7 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
         uniqueProperty: string;
         defaultLimit?: number | undefined;
         defaultPageSize?: number | undefined;
-        elementTypes?: Record<string, string> | undefined;
+        elementTranscodes?: Record<string, string> | undefined;
         indexes?: Record<string, [string, ...string[]]> | undefined;
         shardBumps?: {
             timestamp: number;
@@ -823,4 +836,65 @@ declare class EntityManager<M extends EntityMap, HashKey extends string, RangeKe
     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>>;
 }
 
-export { type Config, type ConfigEntities, type ConfigEntity, type ConfigEntityGenerated, type ConfigKeys, type ConfigTranscodes, EntityManager, type EntityMap, type ExclusiveKey, type ItemMap, type ParsedConfig, type QueryOptions, type QueryResult, type ShardBump, type ShardQueryFunction, type ShardQueryResult, type Unwrap };
+/**
+ * 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;
+}
+
+/**
+ * Generic logger endpoint type.
+ *
+ * @category Logger
+ */
+type LoggerEndpoint = (...args: unknown[]) => void;
+/**
+ * Logger interface.
+ *
+ * @category Logger
+ */
+interface Logger {
+    debug: LoggerEndpoint;
+    error: LoggerEndpoint;
+}
+/**
+ * Logger options.
+ *
+ * @category Logger
+ */
+interface LoggerOptions {
+    /** Logger to use for internal logging. Must support the `debug` & `error` methods. Defaults to `console`. */
+    logger?: Logger;
+    /** Enables internal logging when `true`. */
+    logInternals?: boolean;
+}
+
+/**
+ * EntityManagerClient base class options.
+ *
+ * @category Client
+ */
+type EntityManagerClientOptions = EntityManagerClientBatchOptions & LoggerOptions;
+/**
+ * EntityManagerClient base class.
+ *
+ * @category Client
+ */
+declare abstract class EntityManagerClient<O extends EntityManagerClientOptions> {
+    #private;
+    constructor({ batchSize, delayIncrement, maxRetries, throttle, logger, logInternals, ...options }: O);
+    /**
+     * Returns the options used to create the EntityManagerClient instance.
+     */
+    get options(): Required<O>;
+}
+
+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 ShardQueryResult, type Unwrap, conditionalize };

package/dist/index.d.mts

@@ -2,6 +2,19 @@ import { Entity, Exactify, TranscodeMap, PropertiesOfType, TranscodablePropertie
 export { DefaultTranscodeMap, Entity, PropertiesOfType, SortOrder, TranscodableProperties, TranscodeMap, Transcodes, defaultTranscodes } 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.
  *
@@ -153,7 +166,7 @@ type ConfigEntity<EntityToken extends keyof Exactify<M>, M extends EntityMap, Ha
      * };
      * ```
      */
-    elementTypes?: ([TranscodableProperties<M[EntityToken], T>] extends [never] ? never : {
+    elementTranscodes?: ([TranscodableProperties<M[EntityToken], T>] extends [never] ? never : {
         [P in TranscodableProperties<M[EntityToken], T>]?: PropertiesOfType<T, M[EntityToken][P]>;
     }) | ([TranscodableProperties<M[EntityToken], T>] extends [never] ? Record<string, never> : never);
     /**
@@ -366,7 +379,7 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
             atomic?: boolean | undefined;
             sharded?: boolean | undefined;
         }>>>>>;
-        elementTypes: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>>;
+        elementTranscodes: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>>;
         indexes: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodArray<z.ZodString, "atleastone">, [string, ...string[]], [string, ...string[]]>>>>;
         shardBumps: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
             timestamp: z.ZodNumber;
@@ -410,7 +423,7 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
     }, "strict", z.ZodTypeAny, {
         defaultLimit: number;
         defaultPageSize: number;
-        elementTypes: Record<string, string>;
+        elementTranscodes: Record<string, string>;
         indexes: Record<string, [string, ...string[]]>;
         shardBumps: {
             timestamp: number;
@@ -429,7 +442,7 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
         uniqueProperty: string;
         defaultLimit?: number | undefined;
         defaultPageSize?: number | undefined;
-        elementTypes?: Record<string, string> | undefined;
+        elementTranscodes?: Record<string, string> | undefined;
         indexes?: Record<string, [string, ...string[]]> | undefined;
         shardBumps?: {
             timestamp: number;
@@ -444,7 +457,7 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
     }>, {
         defaultLimit: number;
         defaultPageSize: number;
-        elementTypes: Record<string, string>;
+        elementTranscodes: Record<string, string>;
         indexes: Record<string, [string, ...string[]]>;
         shardBumps: {
             timestamp: number;
@@ -463,7 +476,7 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
         uniqueProperty: string;
         defaultLimit?: number | undefined;
         defaultPageSize?: number | undefined;
-        elementTypes?: Record<string, string> | undefined;
+        elementTranscodes?: Record<string, string> | undefined;
         indexes?: Record<string, [string, ...string[]]> | undefined;
         shardBumps?: {
             timestamp: number;
@@ -498,7 +511,7 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
     entities: Record<string, {
         defaultLimit: number;
         defaultPageSize: number;
-        elementTypes: Record<string, string>;
+        elementTranscodes: Record<string, string>;
         indexes: Record<string, [string, ...string[]]>;
         shardBumps: {
             timestamp: number;
@@ -529,7 +542,7 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
         uniqueProperty: string;
         defaultLimit?: number | undefined;
         defaultPageSize?: number | undefined;
-        elementTypes?: Record<string, string> | undefined;
+        elementTranscodes?: Record<string, string> | undefined;
         indexes?: Record<string, [string, ...string[]]> | undefined;
         shardBumps?: {
             timestamp: number;
@@ -556,7 +569,7 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
     entities: Record<string, {
         defaultLimit: number;
         defaultPageSize: number;
-        elementTypes: Record<string, string>;
+        elementTranscodes: Record<string, string>;
         indexes: Record<string, [string, ...string[]]>;
         shardBumps: {
             timestamp: number;
@@ -587,7 +600,7 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
         uniqueProperty: string;
         defaultLimit?: number | undefined;
         defaultPageSize?: number | undefined;
-        elementTypes?: Record<string, string> | undefined;
+        elementTranscodes?: Record<string, string> | undefined;
         indexes?: Record<string, [string, ...string[]]> | undefined;
         shardBumps?: {
             timestamp: number;
@@ -823,4 +836,65 @@ declare class EntityManager<M extends EntityMap, HashKey extends string, RangeKe
     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>>;
 }
 
-export { type Config, type ConfigEntities, type ConfigEntity, type ConfigEntityGenerated, type ConfigKeys, type ConfigTranscodes, EntityManager, type EntityMap, type ExclusiveKey, type ItemMap, type ParsedConfig, type QueryOptions, type QueryResult, type ShardBump, type ShardQueryFunction, type ShardQueryResult, type Unwrap };
+/**
+ * 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;
+}
+
+/**
+ * Generic logger endpoint type.
+ *
+ * @category Logger
+ */
+type LoggerEndpoint = (...args: unknown[]) => void;
+/**
+ * Logger interface.
+ *
+ * @category Logger
+ */
+interface Logger {
+    debug: LoggerEndpoint;
+    error: LoggerEndpoint;
+}
+/**
+ * Logger options.
+ *
+ * @category Logger
+ */
+interface LoggerOptions {
+    /** Logger to use for internal logging. Must support the `debug` & `error` methods. Defaults to `console`. */
+    logger?: Logger;
+    /** Enables internal logging when `true`. */
+    logInternals?: boolean;
+}
+
+/**
+ * EntityManagerClient base class options.
+ *
+ * @category Client
+ */
+type EntityManagerClientOptions = EntityManagerClientBatchOptions & LoggerOptions;
+/**
+ * EntityManagerClient base class.
+ *
+ * @category Client
+ */
+declare abstract class EntityManagerClient<O extends EntityManagerClientOptions> {
+    #private;
+    constructor({ batchSize, delayIncrement, maxRetries, throttle, logger, logInternals, ...options }: O);
+    /**
+     * Returns the options used to create the EntityManagerClient instance.
+     */
+    get options(): Required<O>;
+}
+
+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 ShardQueryResult, type Unwrap, conditionalize };

package/dist/index.d.ts

@@ -2,6 +2,19 @@ import { Entity, Exactify, TranscodeMap, PropertiesOfType, TranscodablePropertie
 export { DefaultTranscodeMap, Entity, PropertiesOfType, SortOrder, TranscodableProperties, TranscodeMap, Transcodes, defaultTranscodes } 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.
  *
@@ -153,7 +166,7 @@ type ConfigEntity<EntityToken extends keyof Exactify<M>, M extends EntityMap, Ha
      * };
      * ```
      */
-    elementTypes?: ([TranscodableProperties<M[EntityToken], T>] extends [never] ? never : {
+    elementTranscodes?: ([TranscodableProperties<M[EntityToken], T>] extends [never] ? never : {
         [P in TranscodableProperties<M[EntityToken], T>]?: PropertiesOfType<T, M[EntityToken][P]>;
     }) | ([TranscodableProperties<M[EntityToken], T>] extends [never] ? Record<string, never> : never);
     /**
@@ -366,7 +379,7 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
             atomic?: boolean | undefined;
             sharded?: boolean | undefined;
         }>>>>>;
-        elementTypes: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>>;
+        elementTranscodes: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>>;
         indexes: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodArray<z.ZodString, "atleastone">, [string, ...string[]], [string, ...string[]]>>>>;
         shardBumps: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
             timestamp: z.ZodNumber;
@@ -410,7 +423,7 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
     }, "strict", z.ZodTypeAny, {
         defaultLimit: number;
         defaultPageSize: number;
-        elementTypes: Record<string, string>;
+        elementTranscodes: Record<string, string>;
         indexes: Record<string, [string, ...string[]]>;
         shardBumps: {
             timestamp: number;
@@ -429,7 +442,7 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
         uniqueProperty: string;
         defaultLimit?: number | undefined;
         defaultPageSize?: number | undefined;
-        elementTypes?: Record<string, string> | undefined;
+        elementTranscodes?: Record<string, string> | undefined;
         indexes?: Record<string, [string, ...string[]]> | undefined;
         shardBumps?: {
             timestamp: number;
@@ -444,7 +457,7 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
     }>, {
         defaultLimit: number;
         defaultPageSize: number;
-        elementTypes: Record<string, string>;
+        elementTranscodes: Record<string, string>;
         indexes: Record<string, [string, ...string[]]>;
         shardBumps: {
             timestamp: number;
@@ -463,7 +476,7 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
         uniqueProperty: string;
         defaultLimit?: number | undefined;
         defaultPageSize?: number | undefined;
-        elementTypes?: Record<string, string> | undefined;
+        elementTranscodes?: Record<string, string> | undefined;
         indexes?: Record<string, [string, ...string[]]> | undefined;
         shardBumps?: {
             timestamp: number;
@@ -498,7 +511,7 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
     entities: Record<string, {
         defaultLimit: number;
         defaultPageSize: number;
-        elementTypes: Record<string, string>;
+        elementTranscodes: Record<string, string>;
         indexes: Record<string, [string, ...string[]]>;
         shardBumps: {
             timestamp: number;
@@ -529,7 +542,7 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
         uniqueProperty: string;
         defaultLimit?: number | undefined;
         defaultPageSize?: number | undefined;
-        elementTypes?: Record<string, string> | undefined;
+        elementTranscodes?: Record<string, string> | undefined;
         indexes?: Record<string, [string, ...string[]]> | undefined;
         shardBumps?: {
             timestamp: number;
@@ -556,7 +569,7 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
     entities: Record<string, {
         defaultLimit: number;
         defaultPageSize: number;
-        elementTypes: Record<string, string>;
+        elementTranscodes: Record<string, string>;
         indexes: Record<string, [string, ...string[]]>;
         shardBumps: {
             timestamp: number;
@@ -587,7 +600,7 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
         uniqueProperty: string;
         defaultLimit?: number | undefined;
         defaultPageSize?: number | undefined;
-        elementTypes?: Record<string, string> | undefined;
+        elementTranscodes?: Record<string, string> | undefined;
         indexes?: Record<string, [string, ...string[]]> | undefined;
         shardBumps?: {
             timestamp: number;
@@ -823,4 +836,65 @@ declare class EntityManager<M extends EntityMap, HashKey extends string, RangeKe
     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>>;
 }
 
-export { type Config, type ConfigEntities, type ConfigEntity, type ConfigEntityGenerated, type ConfigKeys, type ConfigTranscodes, EntityManager, type EntityMap, type ExclusiveKey, type ItemMap, type ParsedConfig, type QueryOptions, type QueryResult, type ShardBump, type ShardQueryFunction, type ShardQueryResult, type Unwrap };
+/**
+ * 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;
+}
+
+/**
+ * Generic logger endpoint type.
+ *
+ * @category Logger
+ */
+type LoggerEndpoint = (...args: unknown[]) => void;
+/**
+ * Logger interface.
+ *
+ * @category Logger
+ */
+interface Logger {
+    debug: LoggerEndpoint;
+    error: LoggerEndpoint;
+}
+/**
+ * Logger options.
+ *
+ * @category Logger
+ */
+interface LoggerOptions {
+    /** Logger to use for internal logging. Must support the `debug` & `error` methods. Defaults to `console`. */
+    logger?: Logger;
+    /** Enables internal logging when `true`. */
+    logInternals?: boolean;
+}
+
+/**
+ * EntityManagerClient base class options.
+ *
+ * @category Client
+ */
+type EntityManagerClientOptions = EntityManagerClientBatchOptions & LoggerOptions;
+/**
+ * EntityManagerClient base class.
+ *
+ * @category Client
+ */
+declare abstract class EntityManagerClient<O extends EntityManagerClientOptions> {
+    #private;
+    constructor({ batchSize, delayIncrement, maxRetries, throttle, logger, logInternals, ...options }: O);
+    /**
+     * Returns the options used to create the EntityManagerClient instance.
+     */
+    get options(): Required<O>;
+}
+
+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 ShardQueryResult, type Unwrap, conditionalize };

package/dist/mjs/src/EntityManagerClient.js

@@ -0,0 +1,35 @@
+import { __classPrivateFieldSet, __classPrivateFieldGet } from '../node_modules/tslib/tslib.es6.js';
+import { conditionalize } from './conditionalize.js';
+
+var _EntityManagerClient_options;
+/**
+ * EntityManagerClient base class.
+ *
+ * @category Client
+ */
+class EntityManagerClient {
+    constructor({ batchSize = 25, delayIncrement = 100, maxRetries = 5, throttle = 10, logger = console, logInternals = false, ...options }) {
+        _EntityManagerClient_options.set(this, void 0);
+        __classPrivateFieldSet(this, _EntityManagerClient_options, {
+            ...options,
+            batchSize,
+            delayIncrement,
+            maxRetries,
+            throttle,
+            logInternals,
+            logger: {
+                ...logger,
+                debug: conditionalize(logger.debug, logInternals),
+            },
+        }, "f");
+    }
+    /**
+     * Returns the options used to create the EntityManagerClient instance.
+     */
+    get options() {
+        return __classPrivateFieldGet(this, _EntityManagerClient_options, "f");
+    }
+}
+_EntityManagerClient_options = new WeakMap();
+
+export { EntityManagerClient };

package/dist/mjs/src/ParsedConfig.js

@@ -53,7 +53,7 @@ const configSchema = z
             .optional())
             .optional()
             .default({}),
-        elementTypes: z.record(z.string()).optional().default({}),
+        elementTranscodes: z.record(z.string()).optional().default({}),
         indexes: z
             .record(z
             .array(z.string().min(1))
@@ -182,16 +182,16 @@ const configSchema = z
     const transcodes = Object.keys(data.transcodes);
     for (const [entityToken, entity] of Object.entries(data.entities)) {
         // validate all entity generated element type values are transcode keys.
-        for (const [element, generatedElementType] of Object.entries(entity.elementTypes))
+        for (const [element, generatedElementType] of Object.entries(entity.elementTranscodes))
             if (!transcodes.includes(generatedElementType))
                 ctx.addIssue({
                     code: z.ZodIssueCode.invalid_enum_value,
                     options: transcodes,
-                    path: ['entities', entityToken, 'elementTypes', element],
+                    path: ['entities', entityToken, 'elementTranscodes', element],
                     received: generatedElementType,
                 });
         // validate all entity generated property elements have a corresponding entity element type.
-        const typedElements = Object.keys(entity.elementTypes);
+        const typedElements = Object.keys(entity.elementTranscodes);
         for (const [generatedKey, generated] of Object.entries(entity.generated))
             for (const element of generated?.elements ?? [])
                 if (!typedElements.includes(element))

package/dist/mjs/src/conditionalize.js

@@ -0,0 +1,23 @@
+/**
+ * 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`.
+ *
+ */
+function conditionalize(fn, condition) {
+    return (...args) => {
+        if (condition) {
+            return fn(...args);
+        }
+        else {
+            return undefined;
+        }
+    };
+}
+
+export { conditionalize };

package/dist/mjs/src/decodeEntityElement.js

@@ -24,7 +24,7 @@ function decodeEntityElement(entityManager, value, entityToken, element) {
             return;
         if ([hashKey, rangeKey].includes(element))
             return value;
-        const decoded = transcodes[entities[entityToken].elementTypes[element]].decode(value);
+        const decoded = transcodes[entities[entityToken].elementTranscodes[element]].decode(value);
         return decoded;
     }
     catch (error) {

package/dist/mjs/src/encodeEntityElement.js

@@ -23,7 +23,7 @@ function encodeEntityElement(entityManager, item, entityToken, element) {
         const value = item[element];
         if (value === undefined || [hashKey, rangeKey].includes(element))
             return value;
-        const encoded = transcodes[entities[entityToken].elementTypes[element]].encode(item[element]) || undefined;
+        const encoded = transcodes[entities[entityToken].elementTranscodes[element]].encode(item[element]) || undefined;
         return encoded;
     }
     catch (error) {

package/dist/mjs/src/index.js

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

package/package.json

@@ -12,7 +12,7 @@
     "string-hash": "^1.1.3",
     "zod": "^3.23.8"
   },
-  "description": "Configurably decorate entity objects with sharded index keys.",
+  "description": "Rational indexing & cross-shard querying at scale in your NoSQL database so you can focus on your application logic.",
   "devDependencies": {
     "@dotenvx/dotenvx": "^1.14.1",
     "@eslint/js": "^9.10.0",
@@ -132,5 +132,5 @@
   },
   "type": "module",
   "types": "dist/index.d.ts",
-  "version": "6.0.0"
+  "version": "6.1.0-0"
 }