@karmaniverous/entity-manager 8.0.0 → 8.0.1

package/dist/cjs/BaseQueryBuilder/BaseQueryBuilder.js

@@ -2,6 +2,7 @@
 
 var radash = require('radash');
 
+/* eslint-disable @typescript-eslint/no-unused-vars */
 /**
  * Abstract base class supporting a fluent API for building a {@link ShardQueryMap | `ShardQueryMap`} using a database client.
  *
@@ -36,6 +37,16 @@ class BaseQueryBuilder {
     build() {
         return radash.mapValues(this.indexParamsMap, (_indexConfig, indexToken) => this.getShardQueryFunction(indexToken));
     }
+    /**
+     * Execute the built query across shards and indexes via {@link EntityManager.query | `EntityManager.query`}.
+     *
+     * @param options - Query options excluding `entityToken`, `pageKeyMap`, and `shardQueryMap`, which are supplied by the builder.
+     *
+     * @returns The merged, de-duplicated, sorted query result, including a compact `pageKeyMap` token for the next page.
+     *
+     * @remarks
+     * This delegates orchestration to Entity Manager; provider-specific behavior lives in {@link getShardQueryFunction | `getShardQueryFunction`}.
+     */
     async query(options) {
         const { entityClient: { entityManager }, entityToken, pageKeyMap, } = this;
         const shardQueryMap = this.build();

package/dist/cjs/EntityManager/ParsedConfig.js

@@ -29,19 +29,54 @@ const componentArray = zod.z
     .array(zod.z.string().min(1))
     .nonempty()
     .superRefine(validateArrayUnique);
+/**
+ * Runtime configuration schema for {@link EntityManager | `EntityManager`}.
+ *
+ * @remarks
+ * This is authoritative at runtime and used internally by the {@link EntityManager | `EntityManager`} constructor.
+ * It is also used by tests. It is not intended as a user-facing TypeDoc artifact.
+ *
+ * @hidden
+ */
 const configSchema = zod.z
     .object({
     entities: zod.z
         .record(zod.z.string(), zod.z
         .object({
-        defaultLimit: zod.z.number().int().positive().optional().default(10),
-        defaultPageSize: zod.z.number().int().positive().optional().default(10),
+        defaultLimit: zod.z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .default(10)
+            .describe('Default max items returned by EntityManager.query for this entity (across all shards).'),
+        defaultPageSize: zod.z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .default(10)
+            .describe('Default per-shard page size used by EntityManager.query for this entity.'),
         shardBumps: zod.z
             .array(zod.z
             .object({
-            timestamp: zod.z.number().int().nonnegative(),
-            charBits: zod.z.number().int().min(1).max(5),
-            chars: zod.z.number().int().min(0).max(40),
+            timestamp: zod.z
+                .number()
+                .int()
+                .nonnegative()
+                .describe('Start timestamp (ms) for this shard bump (inclusive).'),
+            charBits: zod.z
+                .number()
+                .int()
+                .min(1)
+                .max(5)
+                .describe('Bits per shard character (radix = 2**charBits).'),
+            chars: zod.z
+                .number()
+                .int()
+                .min(0)
+                .max(40)
+                .describe('Shard suffix width (chars); controls shard space.'),
         })
             .strict())
             .optional()
@@ -73,45 +108,92 @@ const configSchema = zod.z
                         });
             }
         }),
-        timestampProperty: zod.z.string().min(1),
-        uniqueProperty: zod.z.string().min(1),
+        timestampProperty: zod.z
+            .string()
+            .min(1)
+            .describe('Property token whose value selects the shard bump (typically a timestamp).'),
+        uniqueProperty: zod.z
+            .string()
+            .min(1)
+            .describe('Property token used to dedupe and build the global range key.'),
     })
         .strict())
         .optional()
-        .default({}),
+        .default({})
+        .describe('Entity definitions keyed by entity token.'),
     generatedProperties: zod.z
         .object({
-        sharded: zod.z.record(zod.z.string(), componentArray).optional().default({}),
-        unsharded: zod.z.record(zod.z.string(), componentArray).optional().default({}),
+        sharded: zod.z
+            .record(zod.z.string(), componentArray)
+            .optional()
+            .default({})
+            .describe('Sharded generated property tokens (hash-side); atomic encoding semantics.'),
+        unsharded: zod.z
+            .record(zod.z.string(), componentArray)
+            .optional()
+            .default({})
+            .describe('Unsharded generated property tokens (range-side); non-atomic encoding semantics.'),
     })
         .optional()
         .default({ sharded: {}, unsharded: {} }),
-    hashKey: zod.z.string(),
+    hashKey: zod.z.string().describe('Global hash key property name.'),
     indexes: zod.z
         .record(zod.z.string(), zod.z.object({
-        hashKey: zod.z.string().min(1),
-        rangeKey: zod.z.string().min(1),
+        hashKey: zod.z
+            .string()
+            .min(1)
+            .describe('Index hash key token (global hash key or a sharded generated key).'),
+        rangeKey: zod.z
+            .string()
+            .min(1)
+            .describe('Index range key token (global range key, an unsharded generated key, or a transcoded property).'),
         projections: zod.z
             .array(zod.z.string().min(1))
             .superRefine(validateArrayUnique)
             .optional(),
     }))
         .optional()
-        .default({}),
-    generatedKeyDelimiter: zod.z.string().regex(/\W+/).optional().default('|'),
-    generatedValueDelimiter: zod.z.string().regex(/\W+/).optional().default('#'),
+        .default({})
+        .describe('Index definitions keyed by index token.'),
+    generatedKeyDelimiter: zod.z
+        .string()
+        .regex(/\W+/)
+        .optional()
+        .default('|')
+        .describe('Delimiter between generated key elements (default `|`).'),
+    generatedValueDelimiter: zod.z
+        .string()
+        .regex(/\W+/)
+        .optional()
+        .default('#')
+        .describe('Delimiter between generated element name and value (default `#`).'),
     propertyTranscodes: zod.z.record(zod.z.string(), zod.z.string()).optional().default({}),
-    rangeKey: zod.z.string(),
-    shardKeyDelimiter: zod.z.string().regex(/\W+/).optional().default('!'),
-    throttle: zod.z.number().int().positive().optional().default(10),
+    rangeKey: zod.z.string().describe('Global range key property name.'),
+    shardKeyDelimiter: zod.z
+        .string()
+        .regex(/\W+/)
+        .optional()
+        .default('!')
+        .describe('Delimiter between entity token and shard suffix in hash key values.'),
+    throttle: zod.z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .default(10)
+        .describe('Default max concurrency for shard queries during EntityManager.query.'),
     transcodes: zod.z
         .record(zod.z.string(), zod.z
         .object({
         // Accept function shapes without relying on z.function()
         // to avoid TS inference conflicts across Zod versions and
         // to remain compatible with narrower parameter types.
-        encode: zod.z.custom((fn) => typeof fn === 'function'),
-        decode: zod.z.custom((fn) => typeof fn === 'function'),
+        encode: zod.z
+            .custom((fn) => typeof fn === 'function')
+            .describe('Encode a value to a lexicographically sortable string.'),
+        decode: zod.z
+            .custom((fn) => typeof fn === 'function')
+            .describe('Decode a previously encoded string back to the value type.'),
     })
         .strict())
         .optional()

package/dist/cjs/EntityManager/findIndexToken.js

@@ -1,8 +1,7 @@
 'use strict';
 
 function findIndexToken(entityManager, hashKeyToken, rangeKeyToken, suppressError) {
-    const indexToken = (Object.entries(entityManager.config.indexes).find(([, index]) => index.hashKey === hashKeyToken &&
-        index.rangeKey === rangeKeyToken)?.[0] ?? undefined);
+    const indexToken = (Object.entries(entityManager.config.indexes).find(([, index]) => index.hashKey === hashKeyToken && index.rangeKey === rangeKeyToken)?.[0] ?? undefined);
     if (!indexToken && !suppressError)
         throw new Error(`No index token found for hashKey '${hashKeyToken}' & rangeKey '${rangeKeyToken}'.`);
     return indexToken;

package/dist/cjs/EntityManager/getIndexComponents.js

@@ -17,12 +17,7 @@ function getIndexComponents(entityManager, indexToken) {
     validateIndexToken.validateIndexToken(entityManager, indexToken);
     const { hashKey, rangeKey, indexes } = entityManager.config;
     const { hashKey: indexHashKey, rangeKey: indexRangeKey } = indexes[indexToken];
-    return radash.unique([
-        hashKey,
-        rangeKey,
-        indexHashKey,
-        indexRangeKey,
-    ]);
+    return radash.unique([hashKey, rangeKey, indexHashKey, indexRangeKey]);
 }
 
 exports.getIndexComponents = getIndexComponents;

package/dist/cjs/EntityManager/query.js

@@ -40,7 +40,7 @@ async function query(entityManager, options) {
         if (!(radash.isInt(pageSize) && pageSize >= 1))
             throw new Error('pageSize must be a positive integer');
         // Rehydrate pageKeyMap.
-        const [hashKeyToken, rehydratedPageKeyMap] = rehydratePageKeyMap.rehydratePageKeyMap(entityManager, entityToken, Object.keys(shardQueryMap), item, pageKeyMap
+        const [hashKeyToken, rehydratedPageKeyMap] = rehydratePageKeyMap.rehydratePageKeyMap(entityManager, entityToken, Object.keys(shardQueryMap).sort(), item, pageKeyMap
             ? JSON.parse(decompressFromEncodedURIComponent(pageKeyMap))
             : undefined, timestampFrom, timestampTo);
         // Shortcut if pageKeyMap is empty.

package/dist/index.d.ts

@@ -9,12 +9,19 @@ import { BatchProcessOptions } from '@karmaniverous/batch-process';
  * @category EntityManager
  */
 interface BaseConfigMap {
+    /** Entity map type (entity token -\> entity shape). */
     EntityMap: EntityMap;
+    /** Global hash-key property name used by the storage layer. */
     HashKey: string;
+    /** Global range-key property name used by the storage layer. */
     RangeKey: string;
+    /** Union of sharded generated key tokens (string-valued generated properties). */
     ShardedKeys: string;
+    /** Union of unsharded generated key tokens (string-valued generated properties). */
     UnshardedKeys: string;
+    /** Union of transcoded property tokens (domain properties mapped in `propertyTranscodes`). */
     TranscodedProperties: string;
+    /** Transcode registry mapping transcode names to value types. */
     TranscodeRegistry: TranscodeRegistry;
 }
 
@@ -55,25 +62,45 @@ interface ShardBump {
  */
 type Config<C extends BaseConfigMap = BaseConfigMap> = ConditionalProperty<'entities', keyof Exactify<C['EntityMap']>, {
     [E in keyof Exactify<C['EntityMap']>]: {
+        /** Default max number of items returned by {@link EntityManager.query | `query`} for this entity (across all shards). */
         defaultLimit?: number;
+        /** Default per-shard page size used by {@link EntityManager.query | `query`} for this entity. */
         defaultPageSize?: number;
+        /** Shard bump schedule for this entity (time-based sharding scale-up). */
         shardBumps?: ShardBump[];
+        /** Property token whose value selects the active shard bump (must be a transcoded numeric property). */
         timestampProperty: Extract<Extract<C['TranscodedProperties'], PropertiesOfType<C['EntityMap'][E], number>>, TranscodableProperties<C['EntityMap'], C['TranscodeRegistry']>>;
+        /** Property token used as the logical unique identifier for this entity (must be a transcoded scalar). */
         uniqueProperty: Extract<Extract<C['TranscodedProperties'], keyof C['EntityMap'][E]>, TranscodableProperties<C['EntityMap'], C['TranscodeRegistry']>>;
     };
 }> & ConditionalProperty<'generatedProperties', C['ShardedKeys'] | C['UnshardedKeys'], ConditionalProperty<'sharded', C['ShardedKeys'], Record<C['ShardedKeys'], (C['TranscodedProperties'] & TranscodableProperties<C['EntityMap'], C['TranscodeRegistry']>)[]>> & ConditionalProperty<'unsharded', C['UnshardedKeys'], Record<C['UnshardedKeys'], (C['TranscodedProperties'] & TranscodableProperties<C['EntityMap'], C['TranscodeRegistry']>)[]>>> & ConditionalProperty<'propertyTranscodes', C['TranscodedProperties'] & TranscodableProperties<C['EntityMap'], C['TranscodeRegistry']>, {
     [P in C['TranscodedProperties'] & TranscodableProperties<C['EntityMap'], C['TranscodeRegistry']>]: PropertiesOfType<C['TranscodeRegistry'], FlattenEntityMap<C['EntityMap']>[P]>;
 }> & ConditionalProperty<'transcodes', keyof C['TranscodeRegistry'], Transcodes<C['TranscodeRegistry']>> & {
+    /** Delimiter between generated key elements (default `|`). Must not collide with other delimiters. */
     generatedKeyDelimiter?: string;
+    /** Delimiter between a generated property key and its encoded value (default `#`). Must not collide with other delimiters. */
     generatedValueDelimiter?: string;
+    /** Global hash key property name. */
     hashKey: C['HashKey'];
+    /**
+     * Index token map. Keys are index names; values define the index hash/range key tokens and optional projections.
+     *
+     * @remarks
+     * This is provider-agnostic metadata used for page-key narrowing and (de)hydration; provider adapters map this to platform-specific indexes.
+     */
     indexes?: Record<string, {
+        /** Index hash key token (global hash key or a sharded generated key token). */
         hashKey: C['HashKey'] | C['ShardedKeys'];
+        /** Index range key token (global range key, an unsharded generated key token, or a transcoded scalar property token). */
         rangeKey: C['RangeKey'] | C['UnshardedKeys'] | (C['TranscodedProperties'] & TranscodableProperties<C['EntityMap'], C['TranscodeRegistry']>);
+        /** Optional list of projected attribute names (validated to exclude key tokens). */
         projections?: string[];
     }>;
+    /** Global range key property name. */
     rangeKey: C['RangeKey'];
+    /** Delimiter between entity token and shard suffix in the global hash key value (default `!`). */
     shardKeyDelimiter?: string;
+    /** Maximum number of shard queries to execute concurrently during {@link EntityManager.query | `query`}. */
     throttle?: number;
 };
 
@@ -109,12 +136,19 @@ type ValidateConfigMap<CC extends BaseConfigMap> = MutuallyExclusive<[
  * @category EntityManager
  */
 type ConfigMap<M extends Partial<BaseConfigMap> = Partial<BaseConfigMap>> = ValidateConfigMap<{
+    /** Entity map type (entity token -\> entity shape). */
     EntityMap: 'EntityMap' extends keyof M ? NonNullable<M['EntityMap']> : Record<string, never>;
+    /** Global hash key property name (defaults to `"hashKey"`). */
     HashKey: 'HashKey' extends keyof M ? NonNullable<M['HashKey']> : 'hashKey';
+    /** Global range key property name (defaults to `"rangeKey"`). */
     RangeKey: 'RangeKey' extends keyof M ? NonNullable<M['RangeKey']> : 'rangeKey';
+    /** Union of sharded generated key tokens (defaults to `never`). */
     ShardedKeys: 'ShardedKeys' extends keyof M ? NonNullable<M['ShardedKeys']> : never;
+    /** Union of unsharded generated key tokens (defaults to `never`). */
     UnshardedKeys: 'UnshardedKeys' extends keyof M ? NonNullable<M['UnshardedKeys']> : never;
+    /** Union of transcoded property tokens (defaults to `never`). */
     TranscodedProperties: 'TranscodedProperties' extends keyof M ? NonNullable<M['TranscodedProperties']> : never;
+    /** Transcode registry type (defaults to {@link DefaultTranscodeRegistry | `DefaultTranscodeRegistry`}). */
     TranscodeRegistry: 'TranscodeRegistry' extends keyof M ? NonNullable<M['TranscodeRegistry']> : DefaultTranscodeRegistry;
 }>;
 
@@ -167,13 +201,23 @@ type PageKey<CC extends BaseConfigMap> = Pick<StorageItem<CC>, CC['HashKey'] | C
  * literal types when available.
  */
 type IndexHashKeyOf<CF, IT extends string> = CF extends {
+    /** Optional values-first index map used for literal narrowing. */
     indexes?: infer I;
 } ? I extends Record<string, unknown> ? IT extends keyof I ? I[IT] extends {
+    /** Index hash key token. */
     hashKey: infer HK;
 } ? HK & string : never : never : never : never;
+/**
+ * Derive the index range-key token for a specific index token.
+ *
+ * When CF carries an `indexes` object and IT is a member key, this extracts the
+ * concrete `rangeKey` token type.
+ */
 type IndexRangeKeyOf<CF, IT extends string> = CF extends {
+    /** Optional values-first index map used for literal narrowing. */
     indexes?: infer I;
 } ? I extends Record<string, unknown> ? IT extends keyof I ? I[IT] extends {
+    /** Index range key token. */
     rangeKey: infer RK;
 } ? RK & string : never : never : never : never;
 /**
@@ -183,9 +227,17 @@ type IndexRangeKeyOf<CF, IT extends string> = CF extends {
  * this helper captures the index token union. Falls back to `string` if absent.
  */
 type IndexTokensOf<CF> = CF extends {
+    /** Optional values-first index map used for index-token narrowing. */
     indexes?: infer I;
 } ? I extends Record<string, unknown> ? Extract<keyof I, string> : string : string;
+/**
+ * Test whether a values-first config literal CF carries a concrete index IT.
+ *
+ * @remarks
+ * Used to decide whether index-aware narrowing is available.
+ */
 type HasIndexFor<CF, IT extends string> = CF extends {
+    /** Optional values-first index map used for literal narrowing. */
     indexes?: infer I;
 } ? I extends Record<string, unknown> ? IT extends keyof I ? true : false : false : false;
 /**
@@ -216,6 +268,13 @@ type PresentIndexTokenSet<CC extends BaseConfigMap, CF, IT extends string> = Rec
  * @category QueryBuilder
  */
 type FallbackIndexTokenSet<CC extends BaseConfigMap> = Record<CC['HashKey'] | CC['RangeKey'] | CC['ShardedKeys'] | CC['UnshardedKeys'] | CC['TranscodedProperties'], true>;
+/**
+ * Derive the union of token names that may appear in a page key for a specific index.
+ *
+ * @remarks
+ * If CF carries a concrete `indexes` map and IT is a member key, this narrows to the
+ * exact component-token set for that index. Otherwise, it falls back to the broad key set.
+ */
 type IndexComponentTokens<CC extends BaseConfigMap, CF, IT extends string> = HasIndexFor<CF, IT> extends true ? keyof PresentIndexTokenSet<CC, CF, IT> : keyof FallbackIndexTokenSet<CC>;
 /**
  * Page key typed for a specific index token.
@@ -226,6 +285,15 @@ type IndexComponentTokens<CC extends BaseConfigMap, CF, IT extends string> = Has
  */
 type PageKeyByIndex<CC extends BaseConfigMap, ET extends EntityToken<CC>, IT extends string = string, CF = unknown> = Pick<StorageItem<CC>, IndexComponentTokens<CC, CF, IT>>;
 
+/**
+ * Runtime configuration schema for {@link EntityManager | `EntityManager`}.
+ *
+ * @remarks
+ * This is authoritative at runtime and used internally by the {@link EntityManager | `EntityManager`} constructor.
+ * It is also used by tests. It is not intended as a user-facing TypeDoc artifact.
+ *
+ * @hidden
+ */
 declare const configSchema: z$1.ZodObject<{
     entities: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodRecord<z$1.ZodString, z$1.ZodObject<{
         defaultLimit: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodNumber>>;
@@ -268,11 +336,88 @@ declare const configSchema: z$1.ZodObject<{
     }, z$1.core.$strict>>>>;
 }, z$1.core.$strict>;
 /**
- * Simplified type taken on by a {@link Config | `Config`} object after parsing in the {@link EntityManager | `EntityManager`} constructor.
+ * Parsed transcoder entry.
+ *
+ * @remarks
+ * This reflects the runtime contract enforced by Zod for entries in `transcodes`.
+ */
+interface ParsedTranscoder {
+    /** Encode a value to a lexicographically sortable string. */
+    encode: unknown;
+    /** Decode a previously encoded string back to the value type. */
+    decode: unknown;
+}
+/**
+ * Parsed index definition (provider-agnostic).
+ *
+ * @remarks
+ * Provider adapters map these tokens to provider-specific index queries.
+ */
+interface ParsedIndexConfig {
+    /** Index hash key token (global hash key or a sharded generated key). */
+    hashKey: string;
+    /** Index range key token (global range key, an unsharded generated key, or a transcoded scalar). */
+    rangeKey: string;
+    /** Optional list of projected attribute names (validated to exclude key tokens). */
+    projections?: string[] | undefined;
+}
+/**
+ * Parsed generated properties configuration.
+ */
+interface ParsedGeneratedPropertiesConfig {
+    /** Sharded generated property tokens (hash-side); atomic encoding semantics. */
+    sharded: Record<string, string[]>;
+    /** Unsharded generated property tokens (range-side); non-atomic encoding semantics. */
+    unsharded: Record<string, string[]>;
+}
+/**
+ * Parsed per-entity configuration.
+ */
+interface ParsedEntityConfig {
+    /** Default max items returned by EntityManager.query for this entity (across all shards). */
+    defaultLimit: number;
+    /** Default per-shard page size used by EntityManager.query for this entity. */
+    defaultPageSize: number;
+    /** Shard bump schedule for this entity (time-based sharding scale-up). */
+    shardBumps: ShardBump[];
+    /** Property token whose value selects the shard bump (typically a timestamp). */
+    timestampProperty: string;
+    /** Property token used to dedupe and build the global range key. */
+    uniqueProperty: string;
+}
+/**
+ * Simplified runtime configuration shape after parsing/validation.
+ *
+ * @remarks
+ * This is the type exposed by {@link EntityManager.config | `EntityManager.config`}.
+ * It mirrors the validated Zod schema output.
  *
  * @category EntityManager
  */
-type ParsedConfig = z$1.infer<typeof configSchema>;
+interface ParsedConfig {
+    /** Entity definitions keyed by entity token. */
+    entities: Record<string, ParsedEntityConfig>;
+    /** Generated property token maps. */
+    generatedProperties: ParsedGeneratedPropertiesConfig;
+    /** Global hash key property name. */
+    hashKey: string;
+    /** Provider-agnostic index definitions keyed by index token. */
+    indexes: Record<string, ParsedIndexConfig>;
+    /** Delimiter between generated key elements (default `|`). */
+    generatedKeyDelimiter: string;
+    /** Delimiter between generated element name and value (default `#`). */
+    generatedValueDelimiter: string;
+    /** Map of transcoded property token -\> transcode name. */
+    propertyTranscodes: Record<string, string>;
+    /** Global range key property name. */
+    rangeKey: string;
+    /** Delimiter between entity token and shard suffix in hash key values (default `!`). */
+    shardKeyDelimiter: string;
+    /** Default max concurrency for shard queries during EntityManager.query. */
+    throttle: number;
+    /** Transcoder registry used for encoding/decoding values. */
+    transcodes: Record<string, ParsedTranscoder>;
+}
 
 /** EntityOfToken — resolves the concrete entity shape for a specific entity token. */
 type EntityOfToken<CC extends BaseConfigMap, ET extends EntityToken<CC>> = Exactify<CC['EntityMap']>[ET];
@@ -340,6 +485,7 @@ interface ShardQueryResult<CC extends BaseConfigMap, ET extends EntityToken<CC>,
  * @protected
  */
 type ShardQueryFunction<CC extends BaseConfigMap, ET extends EntityToken<CC>, IT extends string, CF = unknown, K = unknown> = CF extends {
+    /** Optional values-first index map used for index-token narrowing. */
     indexes?: infer I;
 } ? I extends Record<string, unknown> ? IT extends Extract<keyof I, string> ? (hashKey: string, pageKey?: PageKeyByIndex<CC, ET, IT, CF>, pageSize?: number) => Promise<ShardQueryResult<CC, ET, IT, CF, K>> : never : (hashKey: string, pageKey?: PageKeyByIndex<CC, ET, IT, CF>, pageSize?: number) => Promise<ShardQueryResult<CC, ET, IT, CF, K>> : (hashKey: string, pageKey?: PageKeyByIndex<CC, ET, IT, CF>, pageSize?: number) => Promise<ShardQueryResult<CC, ET, IT, CF, K>>;
 
@@ -360,6 +506,7 @@ type ShardQueryFunction<CC extends BaseConfigMap, ET extends EntityToken<CC>, IT
  * @protected
  */
 type ShardQueryMap<CC extends BaseConfigMap, ET extends EntityToken<CC>, ITS extends string, CF = unknown, K = unknown> = CF extends {
+    /** Optional values-first index map used for index-token narrowing. */
     indexes?: infer I;
 } ? I extends Record<string, unknown> ? Record<Extract<ITS, Extract<keyof I, string>>, ShardQueryFunction<CC, ET, Extract<ITS, Extract<keyof I, string>>, CF, K>> : Record<ITS, ShardQueryFunction<CC, ET, ITS, CF, K>> : Record<ITS, ShardQueryFunction<CC, ET, ITS, CF, K>>;
 /**
@@ -567,9 +714,9 @@ declare class EntityManager<CC extends BaseConfigMap, CF = unknown> {
     /**
      * Update generated properties, hash key, and range key on an {@link EntityItem | `EntityItem`} object.
      *
-     * @param entityToken - {@link Config | `Config`} `entities` key.
-     * @param item - {@link EntityItem | `EntityItem`} object.
-     * @param overwrite - Overwrite existing properties (default `false`).
+     * @param entityToken - Entity token (narrows types by token).
+     * @param item - Single item to update with generated keys/properties.
+     * @param overwrite - Overwrite existing keys/properties (default `false`).
      *
      * @returns {@link EntityRecord | `EntityRecord`} object with updated properties.
      *
@@ -579,22 +726,44 @@ declare class EntityManager<CC extends BaseConfigMap, CF = unknown> {
      */
     addKeys<ET extends EntityToken<CC>>(entityToken: ET, item: EntityItemPartial<CC, ET>, overwrite?: boolean): EntityRecordPartial<CC, ET>;
     /**
+     * Update generated properties, hash key, and range key on an array of {@link EntityItem | `EntityItem`} objects.
+     *
+     * @param entityToken - Entity token (narrows types by token).
+     * @param item - Items to update with generated keys/properties.
+     * @param overwrite - Overwrite existing keys/properties (default `false`).
+     *
+     * @returns Array of {@link EntityRecord | `EntityRecord`} objects with updated properties.
+     *
+     * @throws `Error` if `entityToken` is invalid.
+     *
      * @overload
      */
     addKeys<ET extends EntityToken<CC>>(entityToken: ET, item: EntityItemPartial<CC, ET>[], overwrite?: boolean): EntityRecordPartial<CC, ET>[];
     /**
      * Convert one or more {@link EntityItem | `EntityItem`} objects into an array of {@link EntityKey | `EntityKey`} values.
      *
-     * @param entityToken - {@link Config | `Config`} `entities` key.
-     * @param item - {@link EntityItem | `EntityItem`} object.
-     * @param overwrite - Overwrite existing properties (default `false`).
+     * @param entityToken - Entity token (narrows types by token).
+     * @param item - Single item to derive primary keys for.
+     * @param overwrite - Overwrite existing keys on the item before deriving (default `false`).
      *
      * @returns Array of {@link EntityKey | `EntityKey`} values derived from `item`.
      *
      * @throws `Error` if `entityToken` is invalid.
+     *
+     * @overload
      */
     getPrimaryKey<ET extends EntityToken<CC>>(entityToken: ET, item: EntityItemPartial<CC, ET>, overwrite?: boolean): EntityKey<CC>[];
     /**
+     * Convert an array of {@link EntityItem | `EntityItem`} objects into {@link EntityKey | `EntityKey`} values.
+     *
+     * @param entityToken - Entity token (narrows types by token).
+     * @param items - Array of items to derive primary keys for.
+     * @param overwrite - Overwrite existing keys on each item before deriving (default `false`).
+     *
+     * @returns Array of {@link EntityKey | `EntityKey`} values derived from all `items`.
+     *
+     * @throws `Error` if `entityToken` is invalid.
+     *
      * @overload
      */
     getPrimaryKey<ET extends EntityToken<CC>>(entityToken: ET, items: EntityItemPartial<CC, ET>[], overwrite?: boolean): EntityKey<CC>[];
@@ -660,56 +829,110 @@ declare class EntityManager<CC extends BaseConfigMap, CF = unknown> {
  * Keep this intentionally permissive to maximize inference from `as const`.
  */
 interface ConfigInput {
+    /** Global hash key property name (e.g., `"pk"`). */
     hashKey: string;
+    /** Global range key property name (e.g., `"sk"`). */
     rangeKey: string;
+    /**
+     * Optional generated property token maps.
+     *
+     * @remarks
+     * - `sharded` keys are hash-side generated property tokens and are encoded atomically.
+     * - `unsharded` keys are range-side generated property tokens.
+     */
     generatedProperties?: {
+        /** Sharded generated property tokens (hash-side). */
         sharded?: Record<string, readonly string[]>;
+        /** Unsharded generated property tokens (range-side). */
         unsharded?: Record<string, readonly string[]>;
     };
+    /**
+     * Optional map of transcodable property token -\> transcode name.
+     *
+     * @remarks
+     * Only properties present here are treated as “transcoded properties”.
+     */
     propertyTranscodes?: Record<string, string>;
+    /**
+     * Optional index token map used for typing and paging-key narrowing.
+     *
+     * @remarks
+     * This is provider-agnostic metadata (not a provider-specific index definition).
+     */
     indexes?: Record<string, {
+        /** Index hash key token (global hash key or sharded generated key). */
         hashKey: string;
+        /** Index range key token (global range key, unsharded generated key, or transcoded scalar). */
         rangeKey: string;
+        /** Optional list of projected attribute names (validated at runtime to exclude key tokens). */
         projections?: string[];
     }>;
+    /**
+     * Optional per-entity configuration (runtime semantics).
+     *
+     * @remarks
+     * This is intentionally permissive in `ConfigInput`; runtime validation occurs
+     * in the {@link EntityManager | `EntityManager`} constructor via Zod.
+     */
     entities?: Record<string, unknown>;
     /**
      * Optional Zod schemas for per-entity domain shapes (non-generated fields only).
      *
-     * Important: Schemas MUST declare only base (non-generated) properties. Do not include
-     * global keys (hashKey/rangeKey) or any generated tokens (sharded/unsharded).
+     * @remarks
+     * Schemas MUST declare only base (non-generated) properties. Do not include:
+     * - global keys (hashKey/rangeKey), or
+     * - generated property tokens (sharded/unsharded keys).
      */
     entitiesSchema?: Record<string, ZodType>;
+    /** Optional delimiter between generated key elements (default `|`). */
     generatedKeyDelimiter?: string;
+    /** Optional delimiter between a generated element name and its value (default `#`). */
     generatedValueDelimiter?: string;
+    /** Optional delimiter between entity token and shard suffix in hash key values (default `!`). */
     shardKeyDelimiter?: string;
+    /** Optional transcode registry/value (validated at runtime). */
     transcodes?: unknown;
+    /** Optional maximum concurrency for shard queries. */
     throttle?: number;
 }
+/** Extract the hash key token string literal from a values-first config input type. */
 type HashKeyFrom<CC> = CC extends {
+    /** Hash key token property name. */
     hashKey: infer H;
 } ? H & string : 'hashKey';
+/** Extract the range key token string literal from a values-first config input type. */
 type RangeKeyFrom<CC> = CC extends {
+    /** Range key token property name. */
     rangeKey: infer R;
 } ? R & string : 'rangeKey';
+/** Extract the union of sharded generated key tokens from a values-first config input type. */
 type ShardedKeysFrom<CC> = CC extends {
+    /** Optional generated properties object containing sharded/unsharded maps. */
     generatedProperties?: infer GP;
 } ? GP extends {
+    /** Sharded generated property token map. */
     sharded?: infer S;
 } ? keyof S & string : never : never;
+/** Extract the union of unsharded generated key tokens from a values-first config input type. */
 type UnshardedKeysFrom<CC> = CC extends {
+    /** Optional generated properties object containing sharded/unsharded maps. */
     generatedProperties?: infer GP;
 } ? GP extends {
+    /** Unsharded generated property token map. */
     unsharded?: infer U;
 } ? keyof U & string : never : never;
+/** Extract the union of transcoded property tokens from a values-first config input type. */
 type TranscodedPropertiesFrom<CC> = CC extends {
+    /** Optional map of property token -\> transcode name. */
     propertyTranscodes?: infer PT;
 } ? keyof PT & string : never;
 /**
  * Derive an EntityMap from CC.entitiesSchema when provided (values-first, no generics).
+ *
  * Fallback to broad EntityMap if schemas are absent.
  */
 type EntitiesFromSchema<CC> = CC extends {
+    /** Optional per-entity Zod schema map used only for type inference. */
     entitiesSchema?: infer S;
 } ? S extends Record<string, ZodType> ? {
     [K in Extract<keyof S, string>]: z.infer<S[K]>;
@@ -722,6 +945,7 @@ type EntitiesFromSchema<CC> = CC extends {
  * index token union. Falls back to `string` if absent.
  */
 type IndexTokensFrom<CC> = CC extends {
+    /** Optional index token map used for index-token inference. */
     indexes?: infer I;
 } ? keyof I & string : string;
 /**
@@ -729,12 +953,19 @@ type IndexTokensFrom<CC> = CC extends {
  * and an EntityMap (defaults to MinimalEntityMapFrom<CC>).
  */
 interface CapturedConfigMapFrom<CC, EM extends EntityMap> extends BaseConfigMap {
+    /** Entity map type (from schemas when provided; otherwise broad). */
     EntityMap: EM;
+    /** Hash key token captured from the config literal. */
     HashKey: HashKeyFrom<CC>;
+    /** Range key token captured from the config literal. */
     RangeKey: RangeKeyFrom<CC>;
+    /** Sharded generated key token union captured from the config literal. */
     ShardedKeys: ShardedKeysFrom<CC>;
+    /** Unsharded generated key token union captured from the config literal. */
     UnshardedKeys: UnshardedKeysFrom<CC>;
+    /** Transcoded property token union captured from the config literal. */
     TranscodedProperties: TranscodedPropertiesFrom<CC>;
+    /** Transcode registry type (default registry; runtime validation still applies). */
     TranscodeRegistry: DefaultTranscodeRegistry;
 }
 /**
@@ -804,8 +1035,32 @@ declare abstract class BaseEntityClient<CC extends BaseConfigMap, CF = unknown>
     constructor(options: BaseEntityClientOptions<CC, CF>);
 }
 
+/**
+ * Extract the captured config map type from a {@link BaseEntityClient | `BaseEntityClient`} instance type.
+ *
+ * @typeParam EC - A {@link BaseEntityClient | `BaseEntityClient`} instance type.
+ *
+ * @remarks
+ * This is a pure type-level helper used to derive token-aware types from a client
+ * instance type without requiring callers to restate the config map type.
+ */
 type ConfigOfClient<EC> = EC extends BaseEntityClient<infer CC> ? CC : never;
+/**
+ * Map a client instance type + entity token to the storage-facing record type.
+ *
+ * @typeParam EC - A {@link BaseEntityClient | `BaseEntityClient`} instance type.
+ * @typeParam ET - An {@link EntityToken | `EntityToken`} for that client’s config.
+ */
 type EntityClientRecordByToken<EC, ET extends EntityToken<ConfigOfClient<EC>>> = EntityRecord<ConfigOfClient<EC>, ET>;
+/**
+ * Map a client instance type + entity token to the domain-facing item type.
+ *
+ * This is the “item-facing” shape (global keys and generated property tokens are
+ * not required and are typically stripped via {@link EntityManager.removeKeys | `removeKeys`}).
+ *
+ * @typeParam EC - A {@link BaseEntityClient | `BaseEntityClient`} instance type.
+ * @typeParam ET - An {@link EntityToken | `EntityToken`} for that client’s config.
+ */
 type EntityClientItemByToken<EC, ET extends EntityToken<ConfigOfClient<EC>>> = EntityItem<ConfigOfClient<EC>, ET>;
 
 /**
@@ -867,6 +1122,23 @@ declare abstract class BaseQueryBuilder<CC extends BaseConfigMap, EntityClient e
     readonly indexParamsMap: Record<ITS, IndexParams>;
     /** BaseQueryBuilder constructor. */
     constructor(options: BaseQueryBuilderOptions<CC, EntityClient>);
+    /**
+     * Build a shard query function for a specific index token.
+     *
+     * @param indexToken - Index token identifying which index to query.
+     *
+     * @returns A {@link ShardQueryFunction | `ShardQueryFunction`} that queries a single shard for this index.
+     *
+     * @remarks
+     * Implementations are provider-specific (e.g., DynamoDB). The returned function must:
+     * - Query exactly one shard (partition) per invocation using the provided hash key value.
+     * - Respect `pageKey` and `pageSize` for pagination.
+     * - Return `pageKey: undefined` when that shard is exhausted.
+     *
+     * Entity Manager will orchestrate calling these functions across shards and indexes.
+     *
+     * @protected
+     */
     protected abstract getShardQueryFunction(indexToken: ITS): ShardQueryFunction<CC, ET, ITS, CF, K>;
     /**
      * Builds a {@link ShardQueryMap | `ShardQueryMap`} object.
@@ -874,8 +1146,18 @@ declare abstract class BaseQueryBuilder<CC extends BaseConfigMap, EntityClient e
      * @returns - The {@link ShardQueryMap | `ShardQueryMap`} object.
      */
     build(): ShardQueryMap<CC, ET, ITS, CF, K>;
+    /**
+     * Execute the built query across shards and indexes via {@link EntityManager.query | `EntityManager.query`}.
+     *
+     * @param options - Query options excluding `entityToken`, `pageKeyMap`, and `shardQueryMap`, which are supplied by the builder.
+     *
+     * @returns The merged, de-duplicated, sorted query result, including a compact `pageKeyMap` token for the next page.
+     *
+     * @remarks
+     * This delegates orchestration to Entity Manager; provider-specific behavior lives in {@link getShardQueryFunction | `getShardQueryFunction`}.
+     */
     query(options: QueryBuilderQueryOptions<CC, ET, CF>): Promise<QueryResult<CC, ET, ITS, K>>;
 }
 
 export { BaseEntityClient, BaseQueryBuilder, EntityManager, configSchema, createEntityManager };
-export type { BaseConfigMap, BaseEntityClientOptions, BaseKeyTokens, BaseQueryBuilderOptions, CapturedConfigMapFrom, Config, ConfigInput, ConfigMap, ConfigOfClient, EntitiesFromSchema, EntityClientItemByToken, EntityClientRecordByToken, EntityItem, EntityItemPartial, EntityKey, EntityOfToken, EntityRecord, EntityRecordPartial, EntityToken, FallbackIndexTokenSet, HasIndexFor, HashKeyFrom, IndexComponentTokens, IndexHashKeyOf, IndexRangeKeyOf, IndexTokensFrom, IndexTokensOf, KeysFrom, PageKey, PageKeyByIndex, ParsedConfig, PresentIndexTokenSet, Projected, QueryBuilderQueryOptions, QueryOptions, QueryOptionsByCC, QueryOptionsByCF, QueryResult, RangeKeyFrom, ShardBump, ShardQueryFunction, ShardQueryMap, ShardQueryMapByCC, ShardQueryMapByCF, ShardQueryResult, ShardedKeysFrom, StorageItem, StorageRecord, TranscodedPropertiesFrom, UnshardedKeysFrom, ValidateConfigMap };
+export type { BaseConfigMap, BaseEntityClientOptions, BaseKeyTokens, BaseQueryBuilderOptions, CapturedConfigMapFrom, Config, ConfigInput, ConfigMap, ConfigOfClient, EntitiesFromSchema, EntityClientItemByToken, EntityClientRecordByToken, EntityItem, EntityItemPartial, EntityKey, EntityOfToken, EntityRecord, EntityRecordPartial, EntityToken, FallbackIndexTokenSet, HasIndexFor, HashKeyFrom, IndexComponentTokens, IndexHashKeyOf, IndexRangeKeyOf, IndexTokensFrom, IndexTokensOf, KeysFrom, PageKey, PageKeyByIndex, ParsedConfig, ParsedEntityConfig, ParsedGeneratedPropertiesConfig, ParsedIndexConfig, ParsedTranscoder, PresentIndexTokenSet, Projected, QueryBuilderQueryOptions, QueryOptions, QueryOptionsByCC, QueryOptionsByCF, QueryResult, RangeKeyFrom, ShardBump, ShardQueryFunction, ShardQueryMap, ShardQueryMapByCC, ShardQueryMapByCF, ShardQueryResult, ShardedKeysFrom, StorageItem, StorageRecord, TranscodedPropertiesFrom, UnshardedKeysFrom, ValidateConfigMap };

package/dist/mjs/BaseQueryBuilder/BaseQueryBuilder.js

@@ -1,5 +1,6 @@
 import { mapValues } from 'radash';
 
+/* eslint-disable @typescript-eslint/no-unused-vars */
 /**
  * Abstract base class supporting a fluent API for building a {@link ShardQueryMap | `ShardQueryMap`} using a database client.
  *
@@ -34,6 +35,16 @@ class BaseQueryBuilder {
     build() {
         return mapValues(this.indexParamsMap, (_indexConfig, indexToken) => this.getShardQueryFunction(indexToken));
     }
+    /**
+     * Execute the built query across shards and indexes via {@link EntityManager.query | `EntityManager.query`}.
+     *
+     * @param options - Query options excluding `entityToken`, `pageKeyMap`, and `shardQueryMap`, which are supplied by the builder.
+     *
+     * @returns The merged, de-duplicated, sorted query result, including a compact `pageKeyMap` token for the next page.
+     *
+     * @remarks
+     * This delegates orchestration to Entity Manager; provider-specific behavior lives in {@link getShardQueryFunction | `getShardQueryFunction`}.
+     */
     async query(options) {
         const { entityClient: { entityManager }, entityToken, pageKeyMap, } = this;
         const shardQueryMap = this.build();

package/dist/mjs/EntityManager/ParsedConfig.js

@@ -27,19 +27,54 @@ const componentArray = z
     .array(z.string().min(1))
     .nonempty()
     .superRefine(validateArrayUnique);
+/**
+ * Runtime configuration schema for {@link EntityManager | `EntityManager`}.
+ *
+ * @remarks
+ * This is authoritative at runtime and used internally by the {@link EntityManager | `EntityManager`} constructor.
+ * It is also used by tests. It is not intended as a user-facing TypeDoc artifact.
+ *
+ * @hidden
+ */
 const configSchema = z
     .object({
     entities: z
         .record(z.string(), z
         .object({
-        defaultLimit: z.number().int().positive().optional().default(10),
-        defaultPageSize: z.number().int().positive().optional().default(10),
+        defaultLimit: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .default(10)
+            .describe('Default max items returned by EntityManager.query for this entity (across all shards).'),
+        defaultPageSize: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .default(10)
+            .describe('Default per-shard page size used by EntityManager.query for this entity.'),
         shardBumps: z
             .array(z
             .object({
-            timestamp: z.number().int().nonnegative(),
-            charBits: z.number().int().min(1).max(5),
-            chars: z.number().int().min(0).max(40),
+            timestamp: z
+                .number()
+                .int()
+                .nonnegative()
+                .describe('Start timestamp (ms) for this shard bump (inclusive).'),
+            charBits: z
+                .number()
+                .int()
+                .min(1)
+                .max(5)
+                .describe('Bits per shard character (radix = 2**charBits).'),
+            chars: z
+                .number()
+                .int()
+                .min(0)
+                .max(40)
+                .describe('Shard suffix width (chars); controls shard space.'),
         })
             .strict())
             .optional()
@@ -71,45 +106,92 @@ const configSchema = z
                         });
             }
         }),
-        timestampProperty: z.string().min(1),
-        uniqueProperty: z.string().min(1),
+        timestampProperty: z
+            .string()
+            .min(1)
+            .describe('Property token whose value selects the shard bump (typically a timestamp).'),
+        uniqueProperty: z
+            .string()
+            .min(1)
+            .describe('Property token used to dedupe and build the global range key.'),
     })
         .strict())
         .optional()
-        .default({}),
+        .default({})
+        .describe('Entity definitions keyed by entity token.'),
     generatedProperties: z
         .object({
-        sharded: z.record(z.string(), componentArray).optional().default({}),
-        unsharded: z.record(z.string(), componentArray).optional().default({}),
+        sharded: z
+            .record(z.string(), componentArray)
+            .optional()
+            .default({})
+            .describe('Sharded generated property tokens (hash-side); atomic encoding semantics.'),
+        unsharded: z
+            .record(z.string(), componentArray)
+            .optional()
+            .default({})
+            .describe('Unsharded generated property tokens (range-side); non-atomic encoding semantics.'),
     })
         .optional()
         .default({ sharded: {}, unsharded: {} }),
-    hashKey: z.string(),
+    hashKey: z.string().describe('Global hash key property name.'),
     indexes: z
         .record(z.string(), z.object({
-        hashKey: z.string().min(1),
-        rangeKey: z.string().min(1),
+        hashKey: z
+            .string()
+            .min(1)
+            .describe('Index hash key token (global hash key or a sharded generated key).'),
+        rangeKey: z
+            .string()
+            .min(1)
+            .describe('Index range key token (global range key, an unsharded generated key, or a transcoded property).'),
         projections: z
             .array(z.string().min(1))
             .superRefine(validateArrayUnique)
             .optional(),
     }))
         .optional()
-        .default({}),
-    generatedKeyDelimiter: z.string().regex(/\W+/).optional().default('|'),
-    generatedValueDelimiter: z.string().regex(/\W+/).optional().default('#'),
+        .default({})
+        .describe('Index definitions keyed by index token.'),
+    generatedKeyDelimiter: z
+        .string()
+        .regex(/\W+/)
+        .optional()
+        .default('|')
+        .describe('Delimiter between generated key elements (default `|`).'),
+    generatedValueDelimiter: z
+        .string()
+        .regex(/\W+/)
+        .optional()
+        .default('#')
+        .describe('Delimiter between generated element name and value (default `#`).'),
     propertyTranscodes: z.record(z.string(), z.string()).optional().default({}),
-    rangeKey: z.string(),
-    shardKeyDelimiter: z.string().regex(/\W+/).optional().default('!'),
-    throttle: z.number().int().positive().optional().default(10),
+    rangeKey: z.string().describe('Global range key property name.'),
+    shardKeyDelimiter: z
+        .string()
+        .regex(/\W+/)
+        .optional()
+        .default('!')
+        .describe('Delimiter between entity token and shard suffix in hash key values.'),
+    throttle: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .default(10)
+        .describe('Default max concurrency for shard queries during EntityManager.query.'),
     transcodes: z
         .record(z.string(), z
         .object({
         // Accept function shapes without relying on z.function()
         // to avoid TS inference conflicts across Zod versions and
         // to remain compatible with narrower parameter types.
-        encode: z.custom((fn) => typeof fn === 'function'),
-        decode: z.custom((fn) => typeof fn === 'function'),
+        encode: z
+            .custom((fn) => typeof fn === 'function')
+            .describe('Encode a value to a lexicographically sortable string.'),
+        decode: z
+            .custom((fn) => typeof fn === 'function')
+            .describe('Decode a previously encoded string back to the value type.'),
     })
         .strict())
         .optional()

package/dist/mjs/EntityManager/findIndexToken.js

@@ -1,6 +1,5 @@
 function findIndexToken(entityManager, hashKeyToken, rangeKeyToken, suppressError) {
-    const indexToken = (Object.entries(entityManager.config.indexes).find(([, index]) => index.hashKey === hashKeyToken &&
-        index.rangeKey === rangeKeyToken)?.[0] ?? undefined);
+    const indexToken = (Object.entries(entityManager.config.indexes).find(([, index]) => index.hashKey === hashKeyToken && index.rangeKey === rangeKeyToken)?.[0] ?? undefined);
     if (!indexToken && !suppressError)
         throw new Error(`No index token found for hashKey '${hashKeyToken}' & rangeKey '${rangeKeyToken}'.`);
     return indexToken;

package/dist/mjs/EntityManager/getIndexComponents.js

@@ -15,12 +15,7 @@ function getIndexComponents(entityManager, indexToken) {
     validateIndexToken(entityManager, indexToken);
     const { hashKey, rangeKey, indexes } = entityManager.config;
     const { hashKey: indexHashKey, rangeKey: indexRangeKey } = indexes[indexToken];
-    return unique([
-        hashKey,
-        rangeKey,
-        indexHashKey,
-        indexRangeKey,
-    ]);
+    return unique([hashKey, rangeKey, indexHashKey, indexRangeKey]);
 }
 
 export { getIndexComponents };

package/dist/mjs/EntityManager/query.js

@@ -38,7 +38,7 @@ async function query(entityManager, options) {
         if (!(isInt(pageSize) && pageSize >= 1))
             throw new Error('pageSize must be a positive integer');
         // Rehydrate pageKeyMap.
-        const [hashKeyToken, rehydratedPageKeyMap] = rehydratePageKeyMap(entityManager, entityToken, Object.keys(shardQueryMap), item, pageKeyMap
+        const [hashKeyToken, rehydratedPageKeyMap] = rehydratePageKeyMap(entityManager, entityToken, Object.keys(shardQueryMap).sort(), item, pageKeyMap
             ? JSON.parse(decompressFromEncodedURIComponent(pageKeyMap))
             : undefined, timestampFrom, timestampTo);
         // Shortcut if pageKeyMap is empty.

package/package.json

@@ -10,53 +10,53 @@
     "url": "https://github.com/karmaniverous/entity-manager/issues"
   },
   "dependencies": {
-    "@karmaniverous/batch-process": "^0.1.0",
-    "@karmaniverous/entity-tools": "^0.8.0",
-    "@karmaniverous/string-utilities": "^0.2.2",
+    "@karmaniverous/batch-process": "^0.1.1",
+    "@karmaniverous/entity-tools": "^0.8.1",
+    "@karmaniverous/string-utilities": "^0.2.3",
     "lz-string": "^1.5.0",
     "radash": "^12.1.1",
     "string-hash": "^1.1.3",
-    "zod": "^4.1.13"
+    "zod": "^4.4.3"
   },
   "description": "Rational indexing & cross-shard querying at scale in your NoSQL database so you can focus on your application logic.",
   "devDependencies": {
-    "@dotenvx/dotenvx": "^1.51.1",
-    "@eslint/js": "^9.39.1",
-    "@faker-js/faker": "^10.1.0",
-    "@karmaniverous/mock-db": "^0.4.0",
+    "@dotenvx/dotenvx": "^2.9.0",
+    "@eslint/js": "^10.0.1",
+    "@faker-js/faker": "^10.5.0",
+    "@karmaniverous/mock-db": "^0.4.1",
     "@rollup/plugin-alias": "^6.0.0",
-    "@rollup/plugin-commonjs": "^29.0.0",
+    "@rollup/plugin-commonjs": "^29.0.3",
     "@rollup/plugin-json": "^6.1.0",
     "@rollup/plugin-node-resolve": "^16.0.3",
     "@rollup/plugin-strip": "^3.0.4",
     "@rollup/plugin-typescript": "^12.3.0",
-    "@types/node": "^24.10.1",
+    "@types/node": "^26.1.1",
     "@types/string-hash": "^1.1.3",
-    "auto-changelog": "^2.5.0",
+    "auto-changelog": "^2.6.0",
     "cross-env": "^10.1.0",
-    "eslint": "^9.39.1",
+    "eslint": "^10.7.0",
     "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-prettier": "^5.5.4",
-    "eslint-plugin-simple-import-sort": "^12.1.1",
-    "eslint-plugin-tsdoc": "^0.5.0",
-    "knip": "^5.70.2",
-    "lefthook": "^2.0.4",
-    "prettier": "^3.7.3",
-    "release-it": "^19.0.6",
-    "rimraf": "^6.1.2",
-    "rollup": "^4.53.3",
-    "rollup-plugin-dts": "^6.3.0",
+    "eslint-plugin-prettier": "^5.5.6",
+    "eslint-plugin-simple-import-sort": "^13.0.0",
+    "eslint-plugin-tsdoc": "^0.5.2",
+    "knip": "^6.27.0",
+    "lefthook": "^2.1.10",
+    "prettier": "^3.9.5",
+    "release-it": "^20.2.1",
+    "rimraf": "^6.1.3",
+    "rollup": "^4.62.2",
+    "rollup-plugin-dts": "^6.4.1",
     "tsd": "^0.33.0",
     "tslib": "^2.8.1",
-    "typedoc": "^0.28.15",
-    "typedoc-plugin-mdn-links": "^5.0.10",
+    "typedoc": "^0.28.20",
+    "typedoc-plugin-mdn-links": "^5.1.1",
     "typedoc-plugin-replace-text": "^4.2.0",
     "typedoc-plugin-zod": "^1.4.3",
-    "@vitest/coverage-v8": "^4.0.14",
-    "@vitest/eslint-plugin": "^1.5.1",
-    "vitest": "^4.0.14",
-    "typescript": "^5.9.3",
-    "typescript-eslint": "^8.48.0"
+    "@vitest/coverage-v8": "^4.1.10",
+    "@vitest/eslint-plugin": "^1.6.23",
+    "vitest": "^4.1.10",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.64.0"
   },
   "exports": {
     ".": {
@@ -101,15 +101,15 @@
         "npm run knip",
         "npm run build"
       ],
-      "before:npm:release": [
-        "npx auto-changelog -p",
-        "npm run docs",
-        "git add -A"
-      ],
       "after:release": [
         "git switch -c release/${version}",
         "git push -u origin release/${version}",
         "git switch ${branchName}"
+      ],
+      "after:bump": [
+        "npx auto-changelog -p",
+        "npm run docs",
+        "git add CHANGELOG.md"
       ]
     },
     "npm": {
@@ -134,5 +134,5 @@
   },
   "type": "module",
   "types": "dist/index.d.ts",
-  "version": "8.0.0"
+  "version": "8.0.1"
 }