@karmaniverous/entity-manager 6.7.2 → 6.7.3

package/dist/cjs/BaseShardQueryMapBuilder.js

@@ -9,17 +9,18 @@ var radash = require('radash');
  */
 class BaseShardQueryMapBuilder {
     /** BaseShardQueryMapBuilder constructor. */
-    constructor(entityManager, entityToken, hashKeyToken, pageKeyMap) {
-        this.entityManager = entityManager;
-        this.entityToken = entityToken;
-        this.hashKeyToken = hashKeyToken;
-        this.pageKeyMap = pageKeyMap;
+    constructor(options) {
         /**
-         * Maps `indexToken` values to database platform-specific parameters.
+         * Maps `indexToken` values to database platform-specific query parameters.
          *
          * @protected
          */
         this.indexParamsMap = {};
+        const { entityManager, entityToken, hashKeyToken, pageKeyMap } = options;
+        this.entityManager = entityManager;
+        this.entityToken = entityToken;
+        this.hashKeyToken = hashKeyToken;
+        this.pageKeyMap = pageKeyMap;
     }
     /**
      * Builds a {@link ShardQueryMap | `ShardQueryMap`} object.

package/dist/index.d.ts

@@ -381,119 +381,6 @@ interface QueryResult<Item extends ItemMap<M, HashKey, RangeKey>[EntityToken], E
     pageKeyMap: string;
 }
 
-/**
- * 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 query | `query`} function.
- *
- * @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;
-    /**
-     * Partial item object sufficiently populated to generate index hash keys.
-     */
-    item: Partial<Item>;
-    /**
-     * The target maximum number of records to be returned by the query across
-     * all shards.
-     *
-     * The actual number of records returned will be a product of {@link QueryOptions.pageSize | `pageSize`} and the
-     * number of shards queried, unless limited by available records in a given
-     * 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).
-     *
-     * Note that, within a given {@link EntityManager.query | `query`} method execution, these queries will be
-     * repeated until either available data is exhausted or the {@link QueryOptions.limit | `limit`} value is
-     * 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 `[]`.
-     */
-    sortOrder?: SortOrder<Item>;
-    /**
-     * Lower limit to query shard space.
-     *
-     * Only valid if the query is constrained along the dimension used by the
-     * {@link Config | `EntityManager.config.entities.<entityToken>.sharding.timestamptokens.timestamp`}
-     * function to generate `shardKey`.
-     *
-     * @defaultValue `0`
-     */
-    timestampFrom?: number;
-    /**
-     * Upper limit to query shard space.
-     *
-     * Only valid if the query is constrained along the dimension used by the
-     * {@link Config | `EntityManager.config.entities.<entityToken>.sharding.timestamptokens.timestamp`}
-     * function to generate `shardKey`.
-     *
-     * @defaultValue `Date.now()`
-     */
-    timestampTo?: number;
-    /**
-     * The maximum number of shards to query in parallel. Overrides options `throttle`.
-     *
-     * @defaultValue `options.throttle`
-     */
-    throttle?: number;
-}
-
-type BuilderQueryOptions<Item extends ItemMap<M, HashKey, RangeKey>[EntityToken], EntityToken extends keyof Exactify<M> & string, M extends EntityMap, HashKey extends string, RangeKey extends string> = Omit<QueryOptions<Item, EntityToken, M, HashKey, RangeKey>, 'entityToken' | 'pageKeyMap' | 'shardQueryMap'>;
-
 declare const configSchema: z.ZodEffects<z.ZodObject<{
     entities: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodObject<{
         defaultLimit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
@@ -805,6 +692,117 @@ 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 query | `query`} function.
+ *
+ * @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;
+    /**
+     * Partial item object sufficiently populated to generate index hash keys.
+     */
+    item: Partial<Item>;
+    /**
+     * The target maximum number of records to be returned by the query across
+     * all shards.
+     *
+     * The actual number of records returned will be a product of {@link QueryOptions.pageSize | `pageSize`} and the
+     * number of shards queried, unless limited by available records in a given
+     * 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).
+     *
+     * Note that, within a given {@link EntityManager.query | `query`} method execution, these queries will be
+     * repeated until either available data is exhausted or the {@link QueryOptions.limit | `limit`} value is
+     * 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 `[]`.
+     */
+    sortOrder?: SortOrder<Item>;
+    /**
+     * Lower limit to query shard space.
+     *
+     * Only valid if the query is constrained along the dimension used by the
+     * {@link Config | `EntityManager.config.entities.<entityToken>.sharding.timestamptokens.timestamp`}
+     * function to generate `shardKey`.
+     *
+     * @defaultValue `0`
+     */
+    timestampFrom?: number;
+    /**
+     * Upper limit to query shard space.
+     *
+     * Only valid if the query is constrained along the dimension used by the
+     * {@link Config | `EntityManager.config.entities.<entityToken>.sharding.timestamptokens.timestamp`}
+     * function to generate `shardKey`.
+     *
+     * @defaultValue `Date.now()`
+     */
+    timestampTo?: number;
+    /**
+     * The maximum number of shards to query in parallel. Overrides options `throttle`.
+     *
+     * @defaultValue `options.throttle`
+     */
+    throttle?: number;
+}
+
 /**
  * The EntityManager class applies a configuration-driven sharded data model &
  * query strategy to NoSql data.
@@ -877,24 +875,44 @@ 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>): Promise<QueryResult<Item, EntityToken, M, HashKey, RangeKey>>;
 }
 
+/**
+ * Constructor options for {@link BaseShardQueryMapBuilder | `BaseShardQueryMapBuilder`}.
+ */
+interface BaseShardQueryMapBuilderOptions<EntityToken extends keyof Exactify<M> & string, M extends EntityMap, HashKey extends string, RangeKey extends string, T extends TranscodeMap> {
+    /** {@link EntityManager | `EntityManager`} instance. */
+    entityManager: EntityManager<M, HashKey, RangeKey, T>;
+    /** Entity token. */
+    entityToken: EntityToken;
+    /** Hash key token. */
+    hashKeyToken: PropertiesOfType<M[EntityToken], never> | HashKey;
+    /** Dehydrated page key map. */
+    pageKeyMap?: string;
+}
+
+type ShardQueryMapBuilderQueryOptions<Item extends ItemMap<M, HashKey, RangeKey>[EntityToken], EntityToken extends keyof Exactify<M> & string, M extends EntityMap, HashKey extends string, RangeKey extends string> = Omit<QueryOptions<Item, EntityToken, M, HashKey, RangeKey>, 'entityToken' | 'pageKeyMap' | 'shardQueryMap'>;
+
 /**
  * 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> {
+    /** {@link EntityManager | `EntityManager`} instance. */
     readonly entityManager: EntityManager<M, HashKey, RangeKey, T>;
+    /** Entity token. */
     readonly entityToken: EntityToken;
+    /** Hash key token. */
     readonly hashKeyToken: PropertiesOfType<M[EntityToken], never> | HashKey;
-    readonly pageKeyMap?: string | undefined;
+    /** Dehydrated page key map. */
+    readonly pageKeyMap?: string;
     /**
-     * Maps `indexToken` values to database platform-specific parameters.
+     * Maps `indexToken` values to database platform-specific query parameters.
      *
      * @protected
      */
     readonly indexParamsMap: Record<string, IndexParams>;
     /** BaseShardQueryMapBuilder constructor. */
-    constructor(entityManager: EntityManager<M, HashKey, RangeKey, T>, entityToken: EntityToken, hashKeyToken: PropertiesOfType<M[EntityToken], never> | HashKey, pageKeyMap?: string | undefined);
+    constructor(options: BaseShardQueryMapBuilderOptions<EntityToken, M, HashKey, RangeKey, T>);
     protected abstract getShardQueryFunction(indexToken: string): ShardQueryFunction<Item>;
     /**
      * Builds a {@link ShardQueryMap | `ShardQueryMap`} object.
@@ -902,7 +920,7 @@ declare abstract class BaseShardQueryMapBuilder<IndexParams, Item extends ItemMa
      * @returns - The {@link ShardQueryMap | `ShardQueryMap`} object.
      */
     build(): ShardQueryMap<Item>;
-    query(options: BuilderQueryOptions<Item, EntityToken, M, HashKey, RangeKey>): Promise<QueryResult<Item, EntityToken, M, HashKey, RangeKey>>;
+    query(options: ShardQueryMapBuilderQueryOptions<Item, EntityToken, M, HashKey, RangeKey>): Promise<QueryResult<Item, EntityToken, M, HashKey, RangeKey>>;
 }
 
 /**
@@ -918,4 +936,4 @@ declare abstract class BaseShardQueryMapBuilder<IndexParams, Item extends ItemMa
  */
 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 };
+export { BaseShardQueryMapBuilder, type BaseShardQueryMapBuilderOptions, 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 ShardQueryMapBuilderQueryOptions, type ShardQueryResult, type Unwrap, conditionalize };

package/dist/mjs/BaseShardQueryMapBuilder.js

@@ -7,17 +7,18 @@ import { mapValues } from 'radash';
  */
 class BaseShardQueryMapBuilder {
     /** BaseShardQueryMapBuilder constructor. */
-    constructor(entityManager, entityToken, hashKeyToken, pageKeyMap) {
-        this.entityManager = entityManager;
-        this.entityToken = entityToken;
-        this.hashKeyToken = hashKeyToken;
-        this.pageKeyMap = pageKeyMap;
+    constructor(options) {
         /**
-         * Maps `indexToken` values to database platform-specific parameters.
+         * Maps `indexToken` values to database platform-specific query parameters.
          *
          * @protected
          */
         this.indexParamsMap = {};
+        const { entityManager, entityToken, hashKeyToken, pageKeyMap } = options;
+        this.entityManager = entityManager;
+        this.entityToken = entityToken;
+        this.hashKeyToken = hashKeyToken;
+        this.pageKeyMap = pageKeyMap;
     }
     /**
      * Builds a {@link ShardQueryMap | `ShardQueryMap`} object.

package/package.json

@@ -131,5 +131,5 @@
   },
   "type": "module",
   "types": "dist/index.d.ts",
-  "version": "6.7.2"
+  "version": "6.7.3"
 }