@karmaniverous/entity-manager 6.7.1 → 6.7.2

package/dist/cjs/BaseShardQueryMapBuilder.js

@@ -29,6 +29,16 @@ class BaseShardQueryMapBuilder {
     build() {
         return radash.mapValues(this.indexParamsMap, (indexConfig, indexToken) => this.getShardQueryFunction(indexToken));
     }
+    async query(options) {
+        const { entityManager, entityToken, pageKeyMap } = this;
+        const shardQueryMap = this.build();
+        return await entityManager.query({
+            ...options,
+            entityToken,
+            pageKeyMap,
+            shardQueryMap,
+        });
+    }
 }
 
 exports.BaseShardQueryMapBuilder = BaseShardQueryMapBuilder;

package/dist/index.d.ts

@@ -363,6 +363,137 @@ type ItemMap<M extends EntityMap, HashKey extends string = 'hashKey', RangeKey e
     } & Partial<Record<HashKey | RangeKey, string>>>;
 };
 
+/**
+ * A result returned by a query across multiple shards, where each shard may
+ * receive multiple page queries via a dynamically-generated {@link ShardQueryFunction | `ShardQueryFunction`}.
+ *
+ * @category Query
+ */
+interface QueryResult<Item extends ItemMap<M, HashKey, RangeKey>[EntityToken], EntityToken extends keyof Exactify<M> & string, M extends EntityMap, HashKey extends string, RangeKey extends string> {
+    /** Total number of records returned across all shards. */
+    count: number;
+    /** The returned records. */
+    items: Item[];
+    /**
+     * A compressed, two-layer map of page keys, used to query the next page of
+     * data for a given sort key on each shard of a given hash key.
+     */
+    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>>;
@@ -674,135 +805,6 @@ 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;
-}
-
-/**
- * A result returned by a query across multiple shards, where each shard may
- * receive multiple page queries via a dynamically-generated {@link ShardQueryFunction | `ShardQueryFunction`}.
- *
- * @category Query
- */
-interface QueryResult<Item extends ItemMap<M, HashKey, RangeKey>[EntityToken], EntityToken extends keyof Exactify<M> & string, M extends EntityMap, HashKey extends string, RangeKey extends string> {
-    /** Total number of records returned across all shards. */
-    count: number;
-    /** The returned records. */
-    items: Item[];
-    /**
-     * A compressed, two-layer map of page keys, used to query the next page of
-     * data for a given sort key on each shard of a given hash key.
-     */
-    pageKeyMap: string;
-}
-
 /**
  * The EntityManager class applies a configuration-driven sharded data model &
  * query strategy to NoSql data.
@@ -900,6 +902,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>>;
 }
 
 /**

package/dist/mjs/BaseShardQueryMapBuilder.js

@@ -27,6 +27,16 @@ class BaseShardQueryMapBuilder {
     build() {
         return mapValues(this.indexParamsMap, (indexConfig, indexToken) => this.getShardQueryFunction(indexToken));
     }
+    async query(options) {
+        const { entityManager, entityToken, pageKeyMap } = this;
+        const shardQueryMap = this.build();
+        return await entityManager.query({
+            ...options,
+            entityToken,
+            pageKeyMap,
+            shardQueryMap,
+        });
+    }
 }
 
 export { BaseShardQueryMapBuilder };

package/package.json

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