@karmaniverous/entity-manager 6.6.0 → 6.7.0

package/dist/cjs/BaseShardQueryMapBuilder.js

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

package/dist/cjs/EntityManager.js

@@ -72,7 +72,7 @@ class EntityManager {
      * Query a database entity across shards in a provider-generic fashion.
      *
      * @remarks
-     * The provided {@link ShardQueryFunction | `ShardQueryFunction`} performs the actual query of individual data pages on individual shards. This function is presumed to express provider-specific query logic, including any necessary indexing or search constraints.
+     * The provided `shardQueryMap` performs the actual query of individual data pages on individual index/shard combinations.
      *
      * Individual shard query results will be combined, deduped by {@link ConfigEntity.uniqueProperty} property value, and sorted by {@link QueryOptions.sortOrder | `sortOrder`}.
      *
@@ -84,10 +84,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.query(this, options);
+        const { shardQueryMapBuilder, ...baseOptions } = options;
+        const { entityToken, hashKeyToken, pageKeyMap } = shardQueryMapBuilder;
+        const shardQueryMap = shardQueryMapBuilder.build();
+        return await query.query(this, {
+            entityToken,
+            hashKeyToken,
+            pageKeyMap,
+            shardQueryMap,
+            ...baseOptions,
+        });
     }
 }
 _EntityManager_config = new WeakMap();

package/dist/cjs/index.js

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

package/dist/cjs/query.js

@@ -27,14 +27,14 @@ const { compressToEncodedURIComponent, decompressFromEncodedURIComponent } = lzS
  *
  * @throws Error if {@link QueryOptions.pageKeyMap | `pageKeyMap`} keys do not match {@link QueryOptions.shardQueryMap | `shardQueryMap`} keys.
  */
-async function query(entityManager, { entityToken, hashKey, limit, pageKeyMap, pageSize, shardQueryMap, sortOrder = [], timestampFrom = 0, timestampTo = Date.now(), throttle = entityManager.config.throttle, }) {
+async function query(entityManager, { entityToken, hashKeyToken, limit, pageKeyMap, pageSize, shardQueryMap, sortOrder = [], timestampFrom = 0, timestampTo = Date.now(), throttle = entityManager.config.throttle, }) {
     try {
         // Get defaults.
         const { defaultLimit, defaultPageSize } = entityManager.config.entities[entityToken];
         limit ?? (limit = defaultLimit);
         pageSize ?? (pageSize = defaultPageSize);
         // Validate params.
-        validateEntityGeneratedProperty.validateEntityGeneratedProperty(entityManager, entityToken, hashKey, true);
+        validateEntityGeneratedProperty.validateEntityGeneratedProperty(entityManager, entityToken, hashKeyToken, true);
         if (!(limit === Infinity || (radash.isInt(limit) && limit >= 1)))
             throw new Error('limit must be a positive integer or Infinity.');
         if (!(radash.isInt(pageSize) && pageSize >= 1))
@@ -94,7 +94,7 @@ async function query(entityManager, { entityToken, hashKey, limit, pageKeyMap, p
         };
         entityManager.logger.debug('queried entityToken across shards', {
             entityToken,
-            hashKey,
+            hashKeyToken,
             limit,
             pageKeyMap,
             pageSize,
@@ -112,7 +112,7 @@ async function query(entityManager, { entityToken, hashKey, limit, pageKeyMap, p
         if (error instanceof Error)
             entityManager.logger.error(error.message, {
                 entityToken,
-                hashKey,
+                hashKeyToken,
                 limit,
                 pageKeyMap,
                 pageSize,

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.
  *
@@ -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`}.
@@ -872,7 +813,7 @@ declare class EntityManager<M extends EntityMap, HashKey extends string, RangeKe
      * Query a database entity across shards in a provider-generic fashion.
      *
      * @remarks
-     * The provided {@link ShardQueryFunction | `ShardQueryFunction`} performs the actual query of individual data pages on individual shards. This function is presumed to express provider-specific query logic, including any necessary indexing or search constraints.
+     * The provided `shardQueryMap` performs the actual query of individual data pages on individual index/shard combinations.
      *
      * Individual shard query results will be combined, deduped by {@link ConfigEntity.uniqueProperty} property value, and sorted by {@link QueryOptions.sortOrder | `sortOrder`}.
      *
@@ -884,9 +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
      */
-    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>>;
+    readonly indexParamsMap: Record<string, IndexParams>;
+    /** BaseShardQueryMapBuilder constructor. */
+    constructor(entityManager: EntityManager<M, HashKey, RangeKey, T>, entityToken: EntityToken, hashKeyToken: PropertiesOfType<M[EntityToken], never> | HashKey, pageKeyMap?: string | undefined);
+    protected abstract getShardQueryFunction(indexToken: string): ShardQueryFunction<Item>;
+    /**
+     * Builds a {@link ShardQueryMap | `ShardQueryMap`} object.
+     *
+     * @returns - The {@link ShardQueryMap | `ShardQueryMap`} object.
+     */
+    build(): ShardQueryMap<Item>;
 }
 
-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

@@ -70,7 +70,7 @@ class EntityManager {
      * Query a database entity across shards in a provider-generic fashion.
      *
      * @remarks
-     * The provided {@link ShardQueryFunction | `ShardQueryFunction`} performs the actual query of individual data pages on individual shards. This function is presumed to express provider-specific query logic, including any necessary indexing or search constraints.
+     * The provided `shardQueryMap` performs the actual query of individual data pages on individual index/shard combinations.
      *
      * Individual shard query results will be combined, deduped by {@link ConfigEntity.uniqueProperty} property value, and sorted by {@link QueryOptions.sortOrder | `sortOrder`}.
      *
@@ -82,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/index.js

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

package/dist/mjs/query.js

@@ -25,14 +25,14 @@ const { compressToEncodedURIComponent, decompressFromEncodedURIComponent } = lzS
  *
  * @throws Error if {@link QueryOptions.pageKeyMap | `pageKeyMap`} keys do not match {@link QueryOptions.shardQueryMap | `shardQueryMap`} keys.
  */
-async function query(entityManager, { entityToken, hashKey, limit, pageKeyMap, pageSize, shardQueryMap, sortOrder = [], timestampFrom = 0, timestampTo = Date.now(), throttle = entityManager.config.throttle, }) {
+async function query(entityManager, { entityToken, hashKeyToken, limit, pageKeyMap, pageSize, shardQueryMap, sortOrder = [], timestampFrom = 0, timestampTo = Date.now(), throttle = entityManager.config.throttle, }) {
     try {
         // Get defaults.
         const { defaultLimit, defaultPageSize } = entityManager.config.entities[entityToken];
         limit ?? (limit = defaultLimit);
         pageSize ?? (pageSize = defaultPageSize);
         // Validate params.
-        validateEntityGeneratedProperty(entityManager, entityToken, hashKey, true);
+        validateEntityGeneratedProperty(entityManager, entityToken, hashKeyToken, true);
         if (!(limit === Infinity || (isInt(limit) && limit >= 1)))
             throw new Error('limit must be a positive integer or Infinity.');
         if (!(isInt(pageSize) && pageSize >= 1))
@@ -92,7 +92,7 @@ async function query(entityManager, { entityToken, hashKey, limit, pageKeyMap, p
         };
         entityManager.logger.debug('queried entityToken across shards', {
             entityToken,
-            hashKey,
+            hashKeyToken,
             limit,
             pageKeyMap,
             pageSize,
@@ -110,7 +110,7 @@ async function query(entityManager, { entityToken, hashKey, limit, pageKeyMap, p
         if (error instanceof Error)
             entityManager.logger.error(error.message, {
                 entityToken,
-                hashKey,
+                hashKeyToken,
                 limit,
                 pageKeyMap,
                 pageSize,

package/package.json

@@ -132,5 +132,5 @@
   },
   "type": "module",
   "types": "dist/index.d.ts",
-  "version": "6.6.0"
+  "version": "6.7.0"
 }