@karmaniverous/entity-manager 6.14.3 → 7.0.1

package/dist/index.d.ts

@@ -1,5 +1,6 @@
-import { EntityMap, TranscodeMap, ConditionalProperty, Exactify, PropertiesOfType, TranscodableProperties, FlattenEntityMap, Transcodes, MutuallyExclusive, NotNever, DefaultTranscodeMap, SortOrder } from '@karmaniverous/entity-tools';
-import { z } from 'zod';
+import { EntityMap, TranscodeRegistry, ConditionalProperty, Exactify, PropertiesOfType, TranscodableProperties, FlattenEntityMap, Transcodes, MutuallyExclusive, NotNever, DefaultTranscodeRegistry, SortOrder } from '@karmaniverous/entity-tools';
+import * as z from 'zod';
+import { z as z$1, ZodType } from 'zod';
 import { BatchProcessOptions } from '@karmaniverous/batch-process';
 
 /**
@@ -14,7 +15,7 @@ interface BaseConfigMap {
     ShardedKeys: string;
     UnshardedKeys: string;
     TranscodedProperties: string;
-    TranscodeMap: TranscodeMap;
+    TranscodeRegistry: TranscodeRegistry;
 }
 
 /**
@@ -48,7 +49,7 @@ interface ShardBump {
 /**
  * Configuration object for an {@link EntityManager | `EntityManager`} instance.
  *
- * @typeParam C - {@link ConfigMap | `ConfigMap`} that defines the configuration's {@link EntityMap | `EntityMap`}, key properties, and {@link TranscodeMap | `TranscodeMap`}. If omitted, defaults to {@link BaseConfigMap | `BaseConfigMap`}.
+ * @typeParam C - {@link ConfigMap | `ConfigMap`} that defines the configuration's {@link EntityMap | `EntityMap`}, key properties, and {@link TranscodeRegistry | `TranscodeRegistry`}. If omitted, defaults to {@link BaseConfigMap | `BaseConfigMap`}.
  *
  * @category EntityManager
  */
@@ -57,18 +58,18 @@ type Config<C extends BaseConfigMap = BaseConfigMap> = ConditionalProperty<'enti
         defaultLimit?: number;
         defaultPageSize?: number;
         shardBumps?: ShardBump[];
-        timestampProperty: C['TranscodedProperties'] & PropertiesOfType<C['EntityMap'][E], number> & TranscodableProperties<C['EntityMap'], C['TranscodeMap']>;
-        uniqueProperty: C['TranscodedProperties'] & keyof C['EntityMap'][E] & TranscodableProperties<C['EntityMap'], C['TranscodeMap']>;
+        timestampProperty: C['TranscodedProperties'] & PropertiesOfType<C['EntityMap'][E], number> & TranscodableProperties<C['EntityMap'], C['TranscodeRegistry']>;
+        uniqueProperty: 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['TranscodeMap']>)[]>> & ConditionalProperty<'unsharded', C['UnshardedKeys'], Record<C['UnshardedKeys'], (C['TranscodedProperties'] & TranscodableProperties<C['EntityMap'], C['TranscodeMap']>)[]>>> & ConditionalProperty<'propertyTranscodes', C['TranscodedProperties'] & TranscodableProperties<C['EntityMap'], C['TranscodeMap']>, {
-    [P in C['TranscodedProperties'] & TranscodableProperties<C['EntityMap'], C['TranscodeMap']>]: PropertiesOfType<C['TranscodeMap'], FlattenEntityMap<C['EntityMap']>[P]>;
-}> & ConditionalProperty<'transcodes', keyof C['TranscodeMap'], Transcodes<C['TranscodeMap']>> & {
+}> & 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']>> & {
     generatedKeyDelimiter?: string;
     generatedValueDelimiter?: string;
     hashKey: C['HashKey'];
     indexes?: Record<string, {
         hashKey: C['HashKey'] | C['ShardedKeys'];
-        rangeKey: C['RangeKey'] | C['UnshardedKeys'] | (C['TranscodedProperties'] & TranscodableProperties<C['EntityMap'], C['TranscodeMap']>);
+        rangeKey: C['RangeKey'] | C['UnshardedKeys'] | (C['TranscodedProperties'] & TranscodableProperties<C['EntityMap'], C['TranscodeRegistry']>);
         projections?: string[];
     }>;
     rangeKey: C['RangeKey'];
@@ -79,27 +80,27 @@ type Config<C extends BaseConfigMap = BaseConfigMap> = ConditionalProperty<'enti
 /**
  * Validates a type derived from {@link BaseConfigMap | `BaseConfigMap`} to ensure HashKey and RangeKey are both defined and that all sets of special keys are mutually exclusive.
  *
- * @typeParam C - {@link ConfigMap | `ConfigMap`} that defines an {@link Config | `EntityManager configuration`}'s {@link EntityMap | `EntityMap`}, key properties, and {@link TranscodeMap | `TranscodeMap`}. If omitted, defaults to {@link BaseConfigMap | `BaseConfigMap`}.
+ * @typeParam CC - {@link ConfigMap | `ConfigMap`} that defines an {@link Config | `EntityManager configuration`}'s {@link EntityMap | `EntityMap`}, key properties, and {@link TranscodeRegistry | `TranscodeRegistry`}. If omitted, defaults to {@link BaseConfigMap | `BaseConfigMap`}.
  *
  * @category EntityManager
  * @protected
  */
-type ValidateConfigMap<C extends BaseConfigMap> = MutuallyExclusive<[
-    C['HashKey'],
-    C['RangeKey'],
-    C['ShardedKeys'],
-    C['UnshardedKeys'],
-    keyof FlattenEntityMap<C['EntityMap']>
-]> extends true ? NotNever<C, ['HashKey' | 'RangeKey']> extends true ? C : Exclude<NotNever<C, ['HashKey' | 'RangeKey']>, true> : Exclude<MutuallyExclusive<[
-    C['HashKey'],
-    C['RangeKey'],
-    C['ShardedKeys'],
-    C['UnshardedKeys'],
-    keyof FlattenEntityMap<C['EntityMap']>
+type ValidateConfigMap<CC extends BaseConfigMap> = MutuallyExclusive<[
+    CC['HashKey'],
+    CC['RangeKey'],
+    CC['ShardedKeys'],
+    CC['UnshardedKeys'],
+    keyof FlattenEntityMap<CC['EntityMap']>
+]> extends true ? NotNever<CC, ['HashKey' | 'RangeKey']> extends true ? CC : Exclude<NotNever<CC, ['HashKey' | 'RangeKey']>, true> : Exclude<MutuallyExclusive<[
+    CC['HashKey'],
+    CC['RangeKey'],
+    CC['ShardedKeys'],
+    CC['UnshardedKeys'],
+    keyof FlattenEntityMap<CC['EntityMap']>
 ]>, true>;
 
 /**
- * Generates & validates the map defining defines an {@link EntityManager | `EntityManager`} configuration's {@link EntityMap | `EntityMap`}, key properties, and {@link TranscodeMap | `TranscodeMap`}.
+ * Generates & validates the map defining defines an {@link EntityManager | `EntityManager`} configuration's {@link EntityMap | `EntityMap`}, key properties, and {@link TranscodeRegistry | `TranscodeRegistry`}.
  *
  * Unspecified properties will default to those defined in {@link BaseConfigMap | `BaseConfigMap`}.
  *
@@ -114,58 +115,48 @@ type ConfigMap<M extends Partial<BaseConfigMap> = Partial<BaseConfigMap>> = Vali
     ShardedKeys: 'ShardedKeys' extends keyof M ? NonNullable<M['ShardedKeys']> : never;
     UnshardedKeys: 'UnshardedKeys' extends keyof M ? NonNullable<M['UnshardedKeys']> : never;
     TranscodedProperties: 'TranscodedProperties' extends keyof M ? NonNullable<M['TranscodedProperties']> : never;
-    TranscodeMap: 'TranscodeMap' extends keyof M ? NonNullable<M['TranscodeMap']> : DefaultTranscodeMap;
+    TranscodeRegistry: 'TranscodeRegistry' extends keyof M ? NonNullable<M['TranscodeRegistry']> : DefaultTranscodeRegistry;
 }>;
 
 /**
  * Extracts a database-facing partial item type from a {@link BaseConfigMap | `ConfigMap`}.
  *
- * @typeParam C - {@link ConfigMap | `ConfigMap`} that defines an {@link Config | `EntityManager configuration`}'s {@link EntityMap | `EntityMap`}, key properties, and {@link TranscodeMap | `TranscodeMap`}. If omitted, defaults to {@link BaseConfigMap | `BaseConfigMap`}.
+ * @typeParam CC - {@link ConfigMap | `ConfigMap`} that defines an {@link Config | `EntityManager configuration`}'s {@link EntityMap | `EntityMap`}, key properties, and {@link TranscodeRegistry | `TranscodeRegistry`}. If omitted, defaults to {@link BaseConfigMap | `BaseConfigMap`}.
  *
  * @category EntityManager
  * @protected
  */
-type EntityItem<C extends BaseConfigMap> = Partial<FlattenEntityMap<C['EntityMap']> & Record<C['HashKey'] | C['RangeKey'] | C['ShardedKeys'] | C['UnshardedKeys'], string>> & Record<string, unknown>;
+type EntityItem<CC extends BaseConfigMap> = Partial<FlattenEntityMap<CC['EntityMap']> & Record<CC['HashKey'] | CC['RangeKey'] | CC['ShardedKeys'] | CC['UnshardedKeys'], string>> & Record<string, unknown>;
 
 /**
  * Database-facing record key type from a {@link BaseConfigMap | `ConfigMap`} with required hash & range keys.
  *
- * @typeParam C - {@link ConfigMap | `ConfigMap`} that defines an {@link Config | `EntityManager configuration`}'s {@link EntityMap | `EntityMap`}, key properties, and {@link TranscodeMap | `TranscodeMap`}. If omitted, defaults to {@link BaseConfigMap | `BaseConfigMap`}.
+ * @typeParam CC - {@link ConfigMap | `ConfigMap`} that defines an {@link Config | `EntityManager configuration`}'s {@link EntityMap | `EntityMap`}, key properties, and {@link TranscodeRegistry | `TranscodeRegistry`}. If omitted, defaults to {@link BaseConfigMap | `BaseConfigMap`}.
  *
  * @category EntityClient
  * @protected
  */
-type EntityKey<C extends BaseConfigMap> = Record<C['HashKey'] | C['RangeKey'], string>;
-
-/**
- * Database-facing record type from a {@link BaseConfigMap | `ConfigMap`} with required hash & range keys.
- *
- * @typeParam C - {@link ConfigMap | `ConfigMap`} that defines an {@link Config | `EntityManager configuration`}'s {@link EntityMap | `EntityMap`}, key properties, and {@link TranscodeMap | `TranscodeMap`}. If omitted, defaults to {@link BaseConfigMap | `BaseConfigMap`}.
- *
- * @category EntityManager
- * @protected
- */
-type EntityRecord<C extends BaseConfigMap> = EntityItem<C> & EntityKey<C>;
+type EntityKey<CC extends BaseConfigMap> = Record<CC['HashKey'] | CC['RangeKey'], string>;
 
 /**
  * Extracts entity tokens from a {@link ConfigMap | `ConfigMap`}.
  *
- * @typeParam C - {@link ConfigMap | `ConfigMap`} that defines an {@link Config | `EntityManager configuration`}'s {@link EntityMap | `EntityMap`}, key properties, and {@link TranscodeMap | `TranscodeMap`}. If omitted, defaults to {@link BaseConfigMap | `BaseConfigMap`}.
+ * @typeParam CC - {@link ConfigMap | `ConfigMap`} that defines an {@link Config | `EntityManager configuration`}'s {@link EntityMap | `EntityMap`}, key properties, and {@link TranscodeRegistry | `TranscodeRegistry`}. If omitted, defaults to {@link BaseConfigMap | `BaseConfigMap`}.
  *
  * @category EntityManager
  * @protected
  */
-type EntityToken<C extends BaseConfigMap> = keyof Exactify<C['EntityMap']> & string;
+type EntityToken<CC extends BaseConfigMap> = keyof Exactify<CC['EntityMap']> & string;
 
-declare const configSchema: z.ZodObject<{
-    entities: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
-        defaultLimit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
-        defaultPageSize: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
-        shardBumps: z.ZodPipe<z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
-            timestamp: z.ZodNumber;
-            charBits: z.ZodNumber;
-            chars: z.ZodNumber;
-        }, z.core.$strict>>>>, z.ZodTransform<{
+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>>;
+        defaultPageSize: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodNumber>>;
+        shardBumps: z$1.ZodPipe<z$1.ZodDefault<z$1.ZodOptional<z$1.ZodArray<z$1.ZodObject<{
+            timestamp: z$1.ZodNumber;
+            charBits: z$1.ZodNumber;
+            chars: z$1.ZodNumber;
+        }, z$1.core.$strict>>>>, z$1.ZodTransform<{
             timestamp: number;
             charBits: number;
             chars: number;
@@ -174,62 +165,116 @@ declare const configSchema: z.ZodObject<{
             charBits: number;
             chars: number;
         }[]>>;
-        timestampProperty: z.ZodString;
-        uniqueProperty: z.ZodString;
-    }, z.core.$strict>>>>;
-    generatedProperties: z.ZodDefault<z.ZodOptional<z.ZodObject<{
-        sharded: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>>;
-        unsharded: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>>;
-    }, z.core.$strip>>>;
-    hashKey: z.ZodString;
-    indexes: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
-        hashKey: z.ZodString;
-        rangeKey: z.ZodString;
-        projections: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    }, z.core.$strip>>>>;
-    generatedKeyDelimiter: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-    generatedValueDelimiter: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-    propertyTranscodes: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>>;
-    rangeKey: z.ZodString;
-    shardKeyDelimiter: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-    throttle: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
-    transcodes: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
-        encode: z.ZodCustom<unknown, unknown>;
-        decode: z.ZodCustom<unknown, unknown>;
-    }, z.core.$strict>>>>;
-}, z.core.$strict>;
+        timestampProperty: z$1.ZodString;
+        uniqueProperty: z$1.ZodString;
+    }, z$1.core.$strict>>>>;
+    generatedProperties: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodObject<{
+        sharded: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodRecord<z$1.ZodString, z$1.ZodArray<z$1.ZodString>>>>;
+        unsharded: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodRecord<z$1.ZodString, z$1.ZodArray<z$1.ZodString>>>>;
+    }, z$1.core.$strip>>>;
+    hashKey: z$1.ZodString;
+    indexes: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodRecord<z$1.ZodString, z$1.ZodObject<{
+        hashKey: z$1.ZodString;
+        rangeKey: z$1.ZodString;
+        projections: z$1.ZodOptional<z$1.ZodArray<z$1.ZodString>>;
+    }, z$1.core.$strip>>>>;
+    generatedKeyDelimiter: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodString>>;
+    generatedValueDelimiter: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodString>>;
+    propertyTranscodes: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodRecord<z$1.ZodString, z$1.ZodString>>>;
+    rangeKey: z$1.ZodString;
+    shardKeyDelimiter: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodString>>;
+    throttle: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodNumber>>;
+    transcodes: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodRecord<z$1.ZodString, z$1.ZodObject<{
+        encode: z$1.ZodCustom<unknown, unknown>;
+        decode: z$1.ZodCustom<unknown, unknown>;
+    }, 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.
  *
  * @category EntityManager
  */
-type ParsedConfig = z.infer<typeof configSchema>;
+type ParsedConfig = z$1.infer<typeof configSchema>;
 
 /**
  * A partial {@link EntityItem | `EntityItem`} restricted to keys defined in `C`.
  *
- * @typeParam C - {@link ConfigMap | `ConfigMap`} that defines an {@link Config | `EntityManager configuration`}'s {@link EntityMap | `EntityMap`}, key properties, and {@link TranscodeMap | `TranscodeMap`}. If omitted, defaults to {@link BaseConfigMap | `BaseConfigMap`}.
+ * @typeParam CC - {@link ConfigMap | `ConfigMap`} that defines an {@link Config | `EntityManager configuration`}'s {@link EntityMap | `EntityMap`}, key properties, and {@link TranscodeRegistry | `TranscodeRegistry`}. If omitted, defaults to {@link BaseConfigMap | `BaseConfigMap`}.
  *
  * @category QueryBuilder
  * @protected
  */
-type PageKey<C extends BaseConfigMap> = Pick<EntityItem<C>, C['HashKey'] | C['RangeKey'] | C['ShardedKeys'] | C['UnshardedKeys'] | C['TranscodedProperties']>;
+type PageKey<CC extends BaseConfigMap> = Pick<EntityItem<CC>, CC['HashKey'] | CC['RangeKey'] | CC['ShardedKeys'] | CC['UnshardedKeys'] | CC['TranscodedProperties']>;
+/**
+ * Internal helpers to safely derive index component tokens for an index IT.
+ *
+ * These helpers avoid direct generic indexing into `CF['indexes'][IT]` which can
+ * trigger TS2536. They guard presence and key membership before extracting
+ * literal types when available.
+ */
+type IndexHashKeyOf<CF, IT extends string> = CF extends {
+    indexes?: infer I;
+} ? I extends Record<string, unknown> ? IT extends keyof I ? I[IT] extends {
+    hashKey: infer HK;
+} ? HK & string : never : never : never : never;
+type IndexRangeKeyOf<CF, IT extends string> = CF extends {
+    indexes?: infer I;
+} ? I extends Record<string, unknown> ? IT extends keyof I ? I[IT] extends {
+    rangeKey: infer RK;
+} ? RK & string : never : never : never : never;
+/**
+ * Derive the union of index token names from a values-first config literal.
+ *
+ * When CF carries an `indexes` object with preserved literal keys (prefer `as const`),
+ * this helper captures the index token union. Falls back to `string` if absent.
+ */
+type IndexTokensOf<CF> = CF extends {
+    indexes?: infer I;
+} ? I extends Record<string, unknown> ? keyof I & string : string : string;
+type HasIndexFor<CF, IT extends string> = CF extends {
+    indexes?: infer I;
+} ? I extends Record<string, unknown> ? IT extends keyof I ? true : false : false : false;
+type IndexComponentTokens<CC extends BaseConfigMap, CF, IT extends string> = HasIndexFor<CF, IT> extends true ? CC['HashKey'] | CC['RangeKey'] | IndexHashKeyOf<CF, IT> | IndexRangeKeyOf<CF, IT> : CC['HashKey'] | CC['RangeKey'] | CC['ShardedKeys'] | CC['UnshardedKeys'] | CC['TranscodedProperties'];
+/**
+ * Page key typed for a specific index token.
+ *
+ * - With CF (values-first config literal) present and carrying `indexes`, the
+ *   shape narrows to exactly the component tokens of IT.
+ * - Without CF, falls back to the broad PageKey<CC> shape.
+ */
+type PageKeyByIndex<CC extends BaseConfigMap, ET extends EntityToken<CC>, IT extends string = string, CF = unknown> = Pick<EntityItem<CC>, IndexComponentTokens<CC, CF, IT>>;
+
+/** EntityOfToken — resolves the concrete entity shape for a specific entity token. */
+type EntityOfToken<CC extends BaseConfigMap, ET extends EntityToken<CC>> = Exactify<CC['EntityMap']>[ET];
+/**
+ * EntityItemByToken — database-facing partial item narrowed to a specific entity token.
+ * Mirrors `EntityItem<CC>` with the entity surface restricted to `EntityOfToken<CC, ET>`.
+ *
+ * Note: If using createEntityManager with entitiesSchema, the schema must declare
+ * only base (non-generated) properties. Generated keys/tokens are layered by EntityManager.
+ */
+type EntityItemByToken<CC extends BaseConfigMap, ET extends EntityToken<CC>> = Partial<EntityOfToken<CC, ET> & Record<CC['HashKey'] | CC['RangeKey'] | CC['ShardedKeys'] | CC['UnshardedKeys'], string>> & Record<string, unknown>;
+/** EntityRecordByToken — database-facing record (keys required) narrowed to a specific entity token. */
+type EntityRecordByToken<CC extends BaseConfigMap, ET extends EntityToken<CC>> = EntityItemByToken<CC, ET> & EntityKey<CC>;
 
 /**
  * A result returned by a {@link ShardQueryFunction | `ShardQueryFunction`} querying an individual shard.
  *
- * @typeParam C - {@link ConfigMap | `ConfigMap`} that defines an {@link Config | `EntityManager configuration`}'s {@link EntityMap | `EntityMap`}, key properties, and {@link TranscodeMap | `TranscodeMap`}. If omitted, defaults to {@link BaseConfigMap | `BaseConfigMap`}.
+ * @typeParam CC - {@link ConfigMap | `ConfigMap`}.
+ * @typeParam ET - Entity token narrowing the item type.
+ * @typeParam IT - Index token (for page key typing).
+ * @typeParam CF - Optional values-first config literal type for narrowing.
  *
  * @category EntityManager
  * @protected
  */
-interface ShardQueryResult<C extends BaseConfigMap> {
+interface ShardQueryResult<CC extends BaseConfigMap, ET extends EntityToken<CC>, IT extends string, CF = unknown> {
     /** The number of records returned. */
     count: number;
     /** The returned records. */
-    items: EntityItem<C>[];
+    items: EntityItemByToken<CC, ET>[];
     /** The page key for the next query on this shard. */
-    pageKey?: PageKey<C>;
+    pageKey?: PageKeyByIndex<CC, ET, IT, CF>;
 }
 
 /**
@@ -238,41 +283,81 @@ interface ShardQueryResult<C extends BaseConfigMap> {
  * 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.
  *
  * @param hashKey - The hash key value of the shard being queried.
- * @param pageKey - The {@link PageKey | `PageKey`} returned by the previous query on this shard.
+ * @param pageKey - The typed page key for the index being queried.
  * @param pageSize - The maximum number of items to return from this query.
  *
- * @typeParam C - {@link ConfigMap | `ConfigMap`} that defines an {@link Config | `EntityManager configuration`}'s {@link EntityMap | `EntityMap`}, key properties, and {@link TranscodeMap | `TranscodeMap`}. If omitted, defaults to {@link BaseConfigMap | `BaseConfigMap`}.
+ * @typeParam CC - {@link ConfigMap | `ConfigMap`}.
+ * @typeParam ET - Entity token narrowing the item/record types.
+ * @typeParam IT - Index token (inferred from shardQueryMap keys).
+ * @typeParam CF - Optional values-first config literal type for narrowing.
  *
  * @category EntityManager
  * @protected
  */
-type ShardQueryFunction<C extends BaseConfigMap> = (hashKey: string, pageKey?: PageKey<C>, pageSize?: number) => Promise<ShardQueryResult<C>>;
+type ShardQueryFunction<CC extends BaseConfigMap, ET extends EntityToken<CC>, IT extends string, CF = unknown> = CF extends {
+    indexes?: infer I;
+} ? I extends Record<string, unknown> ? IT extends keyof I & string ? (hashKey: string, pageKey?: PageKeyByIndex<CC, ET, IT, CF>, pageSize?: number) => Promise<ShardQueryResult<CC, ET, IT, CF>> : never : (hashKey: string, pageKey?: PageKeyByIndex<CC, ET, IT, CF>, pageSize?: number) => Promise<ShardQueryResult<CC, ET, IT, CF>> : (hashKey: string, pageKey?: PageKeyByIndex<CC, ET, IT, CF>, pageSize?: number) => Promise<ShardQueryResult<CC, ET, IT, CF>>;
 
 /**
  * Relates a specific index token to a {@link ShardQueryFunction | `ShardQueryFunction`} to be performed on that index.
  *
- * @typeParam C - {@link ConfigMap | `ConfigMap`} that defines an {@link Config | `EntityManager configuration`}'s {@link EntityMap | `EntityMap`}, key properties, and {@link TranscodeMap | `TranscodeMap`}. If omitted, defaults to {@link BaseConfigMap | `BaseConfigMap`}.
+ * @typeParam CC - {@link ConfigMap | `ConfigMap`}.
+ * @typeParam ET - Entity token narrowing the function item types.
+ * @typeParam ITS - Index token subset (inferred from object keys).
+ * @typeParam CF - Optional values-first config literal type for narrowing. When
+ *                 provided and it carries an `indexes` object with preserved
+ *                 literal keys (prefer `as const` at call sites), the map keys
+ *                 are constrained to that set. Excess keys are rejected by
+ *                 excess property checks on object literals.
  *
  * @category EntityManager
  * @protected
  */
-type ShardQueryMap<C extends BaseConfigMap> = Record<string, ShardQueryFunction<C>>;
+type ShardQueryMap<CC extends BaseConfigMap, ET extends EntityToken<CC>, ITS extends string, CF = unknown> = CF extends {
+    indexes?: infer I;
+} ? I extends Record<string, unknown> ? Record<ITS & (keyof I & string), ShardQueryFunction<CC, ET, ITS & (keyof I & string), CF>> : Record<ITS, ShardQueryFunction<CC, ET, ITS, CF>> : Record<ITS, ShardQueryFunction<CC, ET, ITS, CF>>;
+/**
+ * Convenience alias for ShardQueryMap that derives ITS (index token subset)
+ * from a values-first captured config CC (e.g., your config literal type).
+ *
+ * - If CC has `indexes`, ITS becomes the union of its keys.
+ * - Otherwise, ITS defaults to `string`.
+ *
+ * It also passes CC through the CF channel so per-index page-key narrowing
+ * applies consistently.
+ *
+ * This is optional DX sugar; it does not change runtime behavior.
+ */
+type ShardQueryMapByCC<CC extends BaseConfigMap, ET extends EntityToken<CC>, CCLit = unknown> = ShardQueryMap<CC, ET, IndexTokensFrom<CCLit>, CCLit>;
+/**
+ * Convenience alias for ShardQueryMap that derives ITS (index token subset)
+ * directly from a values-first config literal CF when it carries `indexes`.
+ *
+ * - If CF has `indexes`, ITS becomes the union of its keys.
+ * - Otherwise, ITS defaults to `string`.
+ *
+ * This is optional DX sugar; it does not change runtime behavior.
+ */
+type ShardQueryMapByCF<CC extends BaseConfigMap, ET extends EntityToken<CC>, CF = unknown> = ShardQueryMap<CC, ET, IndexTokensOf<CF>, CF>;
 
 /**
  * Options passed to the {@link EntityManager.query | `EntityManager.query`} method.
  *
- * @typeParam C - {@link ConfigMap | `ConfigMap`} that defines an {@link Config | `EntityManager configuration`}'s {@link EntityMap | `EntityMap`}, key properties, and {@link TranscodeMap | `TranscodeMap`}. If omitted, defaults to {@link BaseConfigMap | `BaseConfigMap`}.
+ * @typeParam CC - {@link ConfigMap | `ConfigMap`} that defines an {@link Config | `EntityManager configuration`}'s {@link EntityMap | `EntityMap`}, key properties, and {@link TranscodeRegistry | `TranscodeRegistry`}. If omitted, defaults to {@link BaseConfigMap | `BaseConfigMap`}.
+ * @typeParam ET - Entity token narrowing the item types.
+ * @typeParam ITS - Index token subset (inferred from shardQueryMap keys).
+ * @typeParam CF - Optional values-first config literal type used for index-aware narrowing.
  *
  * @category EntityManager
  * @protected
  */
-interface QueryOptions<C extends BaseConfigMap> {
+interface QueryOptions<CC extends BaseConfigMap, ET extends EntityToken<CC> = EntityToken<CC>, ITS extends string = string, CF = unknown> {
     /** Identifies the entity to be queried. Key of {@link Config | `Config`} `entities`. */
-    entityToken: EntityToken<C>;
+    entityToken: ET;
     /**
      * Partial item object sufficiently populated to generate index hash keys.
      */
-    item: EntityItem<C>;
+    item: EntityItemByToken<CC, ET>;
     /**
      * The target maximum number of records to be returned by the query across
      * all shards.
@@ -304,11 +389,11 @@ interface QueryOptions<C extends BaseConfigMap> {
      * page key, e.g. to match the same string against `firstName` and `lastName`
      * properties without performing a table scan for either.
      */
-    shardQueryMap: ShardQueryMap<C>;
+    shardQueryMap: ShardQueryMap<CC, ET, ITS, CF>;
     /**
      * A {@link SortOrder | `SortOrder`} object specifying the sort order of the result set. Defaults to `[]`.
      */
-    sortOrder?: SortOrder<EntityItem<C>>;
+    sortOrder?: SortOrder<EntityItemByToken<CC, ET>>;
     /**
      * Lower limit to query shard space.
      *
@@ -336,20 +421,45 @@ interface QueryOptions<C extends BaseConfigMap> {
      */
     throttle?: number;
 }
+/**
+ * Convenience alias for QueryOptions that derives ITS (index token subset)
+ * directly from a values-first config literal CF when it carries `indexes`.
+ *
+ * - If CF has `indexes`, ITS becomes the union of its keys.
+ * - Otherwise, ITS defaults to `string`.
+ *
+ * This is optional DX sugar; it does not change runtime behavior.
+ */
+type QueryOptionsByCF<CC extends BaseConfigMap, ET extends EntityToken<CC> = EntityToken<CC>, CF = unknown> = QueryOptions<CC, ET, IndexTokensOf<CF>, CF>;
+/**
+ * Convenience alias for QueryOptions that derives ITS (index token subset)
+ * from a values-first captured config CC (e.g., your config literal type).
+ *
+ * - If CC has `indexes`, ITS becomes the union of its keys.
+ * - Otherwise, ITS defaults to `string`.
+ *
+ * It also passes CC through the CF channel so page-key narrowing and other
+ * CF-aware typing applies consistently.
+ *
+ * This is optional DX sugar; it does not change runtime behavior.
+ */
+type QueryOptionsByCC<CCMap extends BaseConfigMap, ET extends EntityToken<CCMap> = EntityToken<CCMap>, CC = unknown> = QueryOptions<CCMap, ET, IndexTokensFrom<CC>, CC>;
 
 /**
  * A result returned by a query across multiple shards, where each shard may receive multiple page queries via a dynamically-generated {@link ShardQueryFunction | `ShardQueryFunction`}.
  *
- * @typeParam C - {@link ConfigMap | `ConfigMap`} that defines an {@link Config | `EntityManager configuration`}'s {@link EntityMap | `EntityMap`}, key properties, and {@link TranscodeMap | `TranscodeMap`}. If omitted, defaults to {@link BaseConfigMap | `BaseConfigMap`}.
+ * @typeParam CC - {@link ConfigMap | `ConfigMap`}.
+ * @typeParam ET - Entity token narrowing the result item type.
+ * @typeParam ITS - Index token subset (carried for symmetry; not represented in the shape).
  *
  * @category EntityManager
  * @protected
  */
-interface QueryResult<C extends BaseConfigMap> {
+interface QueryResult<CC extends BaseConfigMap, ET extends EntityToken<CC>, ITS extends string> {
     /** Total number of records returned across all shards. */
     count: number;
     /** The returned records. */
-    items: EntityItem<C>[];
+    items: EntityItemByToken<CC, ET>[];
     /**
      * 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.
@@ -361,14 +471,14 @@ interface QueryResult<C extends BaseConfigMap> {
  * The EntityManager class applies a configuration-driven sharded data model &
  * query strategy to NoSql data.
  *
- * @typeParam C - {@link ConfigMap | `ConfigMap`} that defines the configuration's {@link EntityMap | `EntityMap`}, key properties, and {@link TranscodeMap | `TranscodeMap`}. If omitted, defaults to {@link BaseConfigMap | `BaseConfigMap`}.
+ * @typeParam CC - {@link ConfigMap | `ConfigMap`} that defines the configuration's {@link EntityMap | `EntityMap`}, key properties, and {@link TranscodeRegistry | `TranscodeRegistry`}. If omitted, defaults to {@link BaseConfigMap | `BaseConfigMap`}.
  *
  * @remarks
  * While the {@link EntityManager.query | `query`} method is `public`, normally it should not be called directly. The `query` method is used by a platform-specific {@link BaseQueryBuilder.query | `QueryBuilder.query`} method to provide a fluent query API.
  *
  * @category EntityManager
  */
-declare class EntityManager<C extends BaseConfigMap> {
+declare class EntityManager<CC extends BaseConfigMap> {
     #private;
     /** Logger object (defaults to `console`, must support `debug` & `error` methods). */
     readonly logger: Pick<Console, 'debug' | 'error'>;
@@ -378,7 +488,7 @@ declare class EntityManager<C extends BaseConfigMap> {
      * @param config - EntityManager {@link Config | `Config`} object.
      * @param logger - Logger object (defaults to `console`, must support `debug` & `error` methods).
      */
-    constructor(config: Config<C>, logger?: Pick<Console, 'debug' | 'error'>);
+    constructor(config: Config<CC>, logger?: Pick<Console, 'debug' | 'error'>);
     /**
      * Get the current EntityManager {@link Config | `Config`} object.
      *
@@ -401,7 +511,7 @@ declare class EntityManager<C extends BaseConfigMap> {
      *
      * @throws `Error` if `property` is not a {@link Config | Config} `generatedProperties` key.
      */
-    encodeGeneratedProperty<C extends BaseConfigMap>(property: C['ShardedKeys'] | C['UnshardedKeys'], item: EntityItem<C>): string | undefined;
+    encodeGeneratedProperty(property: CC['ShardedKeys'] | CC['UnshardedKeys'], item: EntityItem<CC>): string | undefined;
     /**
      * Update generated properties, hash key, and range key on an {@link EntityItem | `EntityItem`} object.
      *
@@ -415,21 +525,11 @@ declare class EntityManager<C extends BaseConfigMap> {
      *
      * @overload
      */
-    addKeys(entityToken: EntityToken<C>, item: EntityItem<C>, overwrite?: boolean): EntityRecord<C>;
+    addKeys<ET extends EntityToken<CC>>(entityToken: ET, item: EntityItemByToken<CC, ET>, overwrite?: boolean): EntityRecordByToken<CC, ET>;
     /**
-     * Update generated properties, hash key, and range key on an array of {@link EntityItem | `EntityItem`} objects.
-     *
-     * @param entityToken - {@link Config | `Config`} `entities` key.
-     * @param item - Array of {@link EntityItem | `EntityItem`} objects.
-     * @param overwrite - Overwrite existing properties (default `false`).
-     *
-     * @returns An array of {@link EntityRecord | `EntityRecord`} objects with updated properties.
-     *
-     * @throws `Error` if `entityToken` is invalid.
-     *
      * @overload
      */
-    addKeys(entityToken: EntityToken<C>, item: EntityItem<C>[], overwrite?: boolean): EntityRecord<C>[];
+    addKeys<ET extends EntityToken<CC>>(entityToken: ET, item: EntityItemByToken<CC, ET>[], overwrite?: boolean): EntityRecordByToken<CC, ET>[];
     /**
      * Convert one or more {@link EntityItem | `EntityItem`} objects into an array of {@link EntityKey | `EntityKey`} values.
      *
@@ -442,8 +542,11 @@ declare class EntityManager<C extends BaseConfigMap> {
      *
      * @throws `Error` if `entityToken` is invalid.
      */
-    getPrimaryKey(entityToken: EntityToken<C>, item: EntityItem<C>, overwrite?: boolean): EntityKey<C>[];
-    getPrimaryKey(entityToken: EntityToken<C>, items: EntityItem<C>[], overwrite?: boolean): EntityKey<C>[];
+    getPrimaryKey<ET extends EntityToken<CC>>(entityToken: ET, item: EntityItemByToken<CC, ET>, overwrite?: boolean): EntityKey<CC>[];
+    /**
+     * @overload
+     */
+    getPrimaryKey<ET extends EntityToken<CC>>(entityToken: ET, items: EntityItemByToken<CC, ET>[], overwrite?: boolean): EntityKey<CC>[];
     /**
      * Strips generated properties, hash key, and range key from an {@link EntityRecord | `EntityRecord`} object.
      *
@@ -456,20 +559,11 @@ declare class EntityManager<C extends BaseConfigMap> {
      *
      * @overload
      */
-    removeKeys(entityToken: EntityToken<C>, item: EntityRecord<C>): EntityItem<C>;
+    removeKeys<ET extends EntityToken<CC>>(entityToken: ET, item: EntityRecordByToken<CC, ET>): EntityItemByToken<CC, ET>;
     /**
-     * Strips generated properties, hash key, and range key from an array of {@link EntityRecord | `EntityRecord`} objects.
-     *
-     * @param entityToken - {@link Config | `Config`} `entities` key.
-     * @param items - Array of {@link EntityRecord | `EntityRecord`} objects.
-     *
-     * @returns Array of {@link EntityItem | `EntityItem`} objects with generated properties, hash key & range key removed.
-     *
-     * @throws `Error` if `entityToken` is invalid.
-     *
      * @overload
      */
-    removeKeys(entityToken: EntityToken<C>, items: EntityRecord<C>[]): EntityItem<C>[];
+    removeKeys<ET extends EntityToken<CC>>(entityToken: ET, items: EntityRecordByToken<CC, ET>[]): EntityItemByToken<CC, ET>[];
     /**
      * Find an index token in a {@link Config | `Config`} object based on the index `hashKey` and `rangeKey`.
      *
@@ -504,21 +598,128 @@ declare class EntityManager<C extends BaseConfigMap> {
      *
      * @protected
      */
-    query(options: QueryOptions<C>): Promise<QueryResult<C>>;
+    query<ET extends EntityToken<CC>, ITS extends string, CF = unknown>(options: QueryOptions<CC, ET, ITS, CF>): Promise<QueryResult<CC, ET, ITS>>;
+}
+
+/**
+ * Values-first config input used to capture literal tokens from the provided
+ * configuration value. This does not enforce full Config shape at compile
+ * time; runtime validation still occurs via Zod in the EntityManager.
+ *
+ * Keep this intentionally permissive to maximize inference from `as const`.
+ */
+interface ConfigInput {
+    hashKey: string;
+    rangeKey: string;
+    generatedProperties?: {
+        sharded?: Record<string, readonly string[]>;
+        unsharded?: Record<string, readonly string[]>;
+    };
+    propertyTranscodes?: Record<string, string>;
+    indexes?: Record<string, {
+        hashKey: string;
+        rangeKey: string;
+        projections?: string[];
+    }>;
+    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).
+     */
+    entitiesSchema?: Record<string, ZodType>;
+    generatedKeyDelimiter?: string;
+    generatedValueDelimiter?: string;
+    shardKeyDelimiter?: string;
+    transcodes?: unknown;
+    throttle?: number;
 }
+type HashKeyFrom<CC> = CC extends {
+    hashKey: infer H;
+} ? H & string : 'hashKey';
+type RangeKeyFrom<CC> = CC extends {
+    rangeKey: infer R;
+} ? R & string : 'rangeKey';
+type ShardedKeysFrom<CC> = CC extends {
+    generatedProperties?: infer GP;
+} ? GP extends {
+    sharded?: infer S;
+} ? keyof S & string : never : never;
+type UnshardedKeysFrom<CC> = CC extends {
+    generatedProperties?: infer GP;
+} ? GP extends {
+    unsharded?: infer U;
+} ? keyof U & string : never : never;
+type TranscodedPropertiesFrom<CC> = CC extends {
+    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 {
+    entitiesSchema?: infer S;
+} ? S extends Record<string, ZodType> ? {
+    [K in keyof S & string]: z.infer<S[K]>;
+} & EntityMap : EntityMap : EntityMap;
+/**
+ * Derive the union of index token names from a values-first config input.
+ *
+ * When the provided config literal carries an `indexes` object with preserved
+ * literal keys (prefer `as const` at call sites), this helper captures the
+ * index token union. Falls back to `string` if absent.
+ */
+type IndexTokensFrom<CC> = CC extends {
+    indexes?: infer I;
+} ? keyof I & string : string;
+/**
+ * Captures a BaseConfigMap-compatible type from a literal ConfigInput value
+ * and an EntityMap (defaults to MinimalEntityMapFrom<CC>).
+ */
+type CapturedConfigMapFrom<CC, EM extends EntityMap> = {
+    EntityMap: EM;
+    HashKey: HashKeyFrom<CC>;
+    RangeKey: RangeKeyFrom<CC>;
+    ShardedKeys: ShardedKeysFrom<CC>;
+    UnshardedKeys: UnshardedKeysFrom<CC>;
+    TranscodedProperties: TranscodedPropertiesFrom<CC>;
+    TranscodeRegistry: DefaultTranscodeRegistry;
+} & BaseConfigMap;
+/**
+ * Values-first factory that captures literal tokens and index names directly
+ * from the provided config value. Runtime config parsing/validation is
+ * unchanged (performed in the EntityManager constructor).
+ *
+ * @typeParam CC - Captured config input (values-first). Prefer `as const` and
+ *                 `satisfies` at call sites to preserve literal keys.
+ * @typeParam EM - EntityMap for the manager. Defaults to a minimal derived map
+ *                 from `CC.entitiesSchema` when present; otherwise falls back to EntityMap.
+ */
+declare function createEntityManager<const CC extends ConfigInput, EM extends EntityMap = EntitiesFromSchema<CC>>(config: CC, logger?: Pick<Console, 'debug' | 'error'>): EntityManager<CapturedConfigMapFrom<CC, EM>>;
+
+/**
+ * Database-facing record type from a {@link BaseConfigMap | `ConfigMap`} with required hash & range keys.
+ *
+ * @typeParam CC - {@link ConfigMap | `ConfigMap`} that defines an {@link Config | `EntityManager configuration`}'s {@link EntityMap | `EntityMap`}, key properties, and {@link TranscodeRegistry | `TranscodeRegistry`}. If omitted, defaults to {@link BaseConfigMap | `BaseConfigMap`}.
+ *
+ * @category EntityManager
+ * @protected
+ */
+type EntityRecord<CC extends BaseConfigMap> = EntityItem<CC> & EntityKey<CC>;
 
 /**
  * Base EntityClient options.
  *
- * @typeParam C - {@link ConfigMap | `ConfigMap`} that defines an {@link Config | `EntityManager configuration`}'s {@link EntityMap | `EntityMap`}, key properties, and {@link TranscodeMap | `TranscodeMap`}. If omitted, defaults to {@link BaseConfigMap | `BaseConfigMap`}.
+ * @typeParam CC - {@link ConfigMap | `ConfigMap`} that defines an {@link Config | `EntityManager configuration`}'s {@link EntityMap | `EntityMap`}, key properties, and {@link TranscodeRegistry | `TranscodeRegistry`}. If omitted, defaults to {@link BaseConfigMap | `BaseConfigMap`}.
  *
  * @category EntityClient
  */
-interface BaseEntityClientOptions<C extends BaseConfigMap> {
+interface BaseEntityClientOptions<CC extends BaseConfigMap> {
     /** Default batch process options. */
     batchProcessOptions?: Omit<BatchProcessOptions<unknown, unknown>, 'batchHandler' | 'unprocessedItemExtractor'>;
     /** {@link EntityManager | `EntityManager`} instance. */
-    entityManager: EntityManager<C>;
+    entityManager: EntityManager<CC>;
     /** Injected logger object. Must support `debug` and `error` methods. Default: `console` */
     logger?: Pick<Console, 'debug' | 'error'>;
 }
@@ -526,40 +727,40 @@ interface BaseEntityClientOptions<C extends BaseConfigMap> {
 /**
  * Base EntityClient class. Integrates {@link EntityManager | `EntityManager`} with injected logging & enhanced batch processing.
  *
- * @typeParam C - {@link ConfigMap | `ConfigMap`} that defines an {@link Config | `EntityManager configuration`}'s {@link EntityMap | `EntityMap`}, key properties, and {@link TranscodeMap | `TranscodeMap`}. If omitted, defaults to {@link BaseConfigMap | `BaseConfigMap`}.
+ * @typeParam CC - {@link ConfigMap | `ConfigMap`} that defines an {@link Config | `EntityManager configuration`}'s {@link EntityMap | `EntityMap`}, key properties, and {@link TranscodeRegistry | `TranscodeRegistry`}. If omitted, defaults to {@link BaseConfigMap | `BaseConfigMap`}.
  *
  * @category EntityClient
  */
-declare abstract class BaseEntityClient<C extends BaseConfigMap> {
+declare abstract class BaseEntityClient<CC extends BaseConfigMap> {
     /** Default batch process options. */
-    readonly batchProcessOptions: NonNullable<BaseEntityClientOptions<C>['batchProcessOptions']>;
+    readonly batchProcessOptions: NonNullable<BaseEntityClientOptions<CC>['batchProcessOptions']>;
     /** {@link EntityManager | `EntityManager`} instance. */
-    readonly entityManager: EntityManager<C>;
+    readonly entityManager: EntityManager<CC>;
     /** Injected logger object. Must support `debug` and `error` methods. Default: `console` */
-    readonly logger: NonNullable<BaseEntityClientOptions<C>['logger']>;
+    readonly logger: NonNullable<BaseEntityClientOptions<CC>['logger']>;
     /**
      * DynamoDB EntityClient constructor.
      *
      * @param options - {@link BaseEntityClientOptions | `BaseEntityClientOptions`} object.
      */
-    constructor(options: BaseEntityClientOptions<C>);
+    constructor(options: BaseEntityClientOptions<CC>);
 }
 
 /**
  * Constructor options for {@link BaseQueryBuilder | `BaseQueryBuilder`}.
  *
- * @typeParam C - {@link ConfigMap | `ConfigMap`} that defines an {@link Config | `EntityManager configuration`}'s {@link EntityMap | `EntityMap`}, key properties, and {@link TranscodeMap | `TranscodeMap`}. If omitted, defaults to {@link BaseConfigMap | `BaseConfigMap`}.
+ * @typeParam CC - {@link ConfigMap | `ConfigMap`} that defines an {@link Config | `EntityManager configuration`}'s {@link EntityMap | `EntityMap`}, key properties, and {@link TranscodeRegistry | `TranscodeRegistry`}. If omitted, defaults to {@link BaseConfigMap | `BaseConfigMap`}.
  * @typeParam EntityClient - {@link BaseEntityClient | `BaseEntityClient`} derived class instance.
  *
  * @category QueryBuilder
  */
-interface BaseQueryBuilderOptions<C extends BaseConfigMap, EntityClient extends BaseEntityClient<C>> {
+interface BaseQueryBuilderOptions<CC extends BaseConfigMap, EntityClient extends BaseEntityClient<CC>> {
     /** {@link BaseEntityClient | `EntityClient`} instance. */
     entityClient: EntityClient;
     /** Entity token. */
-    entityToken: EntityToken<C>;
+    entityToken: EntityToken<CC>;
     /** Hash key token. */
-    hashKeyToken: C['HashKey'] | C['ShardedKeys'];
+    hashKeyToken: CC['HashKey'] | CC['ShardedKeys'];
     /** Dehydrated page key map. */
     pageKeyMap?: string;
 }
@@ -569,28 +770,29 @@ interface BaseQueryBuilderOptions<C extends BaseConfigMap, EntityClient extends
  *
  * Same as {@link QueryOptions | `QueryOptions`} for {@link EntityManager.query | `EntityManager.query`}, excluding `entityToken`, `pageKeyMap`, and `shardQueryMap`.
  *
- * @typeParam C - {@link ConfigMap | `ConfigMap`} that defines an {@link Config | `EntityManager configuration`}'s {@link EntityMap | `EntityMap`}, key properties, and {@link TranscodeMap | `TranscodeMap`}. If omitted, defaults to {@link BaseConfigMap | `BaseConfigMap`}.
+ * @typeParam CC - {@link ConfigMap | `ConfigMap`} that defines an {@link Config | `EntityManager configuration`}'s {@link EntityMap | `EntityMap`}, key properties, and {@link TranscodeRegistry | `TranscodeRegistry`}. If omitted, defaults to {@link BaseConfigMap | `BaseConfigMap`}.
  *
  * @category QueryBuilder
  */
-type QueryBuilderQueryOptions<C extends BaseConfigMap> = Omit<QueryOptions<C>, 'entityToken' | 'pageKeyMap' | 'shardQueryMap'>;
+type QueryBuilderQueryOptions<CC extends BaseConfigMap, CF = unknown> = Omit<QueryOptions<CC, never, string, CF>, 'entityToken' | 'pageKeyMap' | 'shardQueryMap'>;
 
 /**
  * Abstract base class supporting a fluent API for building a {@link ShardQueryMap | `ShardQueryMap`} using a database client.
  *
- * @typeParam C - {@link ConfigMap | `ConfigMap`} that defines an {@link Config | `EntityManager configuration`}'s {@link EntityMap | `EntityMap`}, key properties, and {@link TranscodeMap | `TranscodeMap`}. If omitted, defaults to {@link BaseConfigMap | `BaseConfigMap`}.
+ * @typeParam CC - {@link ConfigMap | `ConfigMap`} that defines an {@link Config | `EntityManager configuration`}'s {@link EntityMap | `EntityMap`}, key properties, and {@link TranscodeRegistry | `TranscodeRegistry`}. If omitted, defaults to {@link BaseConfigMap | `BaseConfigMap`}.
  * @typeParam EntityClient - {@link BaseEntityClient | `BaseEntityClient`} derived class instance.
  * @typeParam IndexParams - Database platform-specific, index-specific query parameters.
+ * @typeParam CF - Optional values-first config literal type for page key narrowing.
  *
  * @category QueryBuilder
  */
-declare abstract class BaseQueryBuilder<C extends BaseConfigMap, EntityClient extends BaseEntityClient<C>, IndexParams> {
+declare abstract class BaseQueryBuilder<CC extends BaseConfigMap, EntityClient extends BaseEntityClient<CC>, IndexParams, ET extends EntityToken<CC> = EntityToken<CC>, ITS extends string = string, CF = unknown> {
     /** {@link BaseEntityClient | `EntityClient`} instance. */
     readonly entityClient: EntityClient;
     /** Entity token. */
-    readonly entityToken: EntityToken<C>;
+    readonly entityToken: EntityToken<CC>;
     /** Hash key token. */
-    readonly hashKeyToken: C['HashKey'] | C['ShardedKeys'];
+    readonly hashKeyToken: CC['HashKey'] | CC['ShardedKeys'];
     /** Dehydrated page key map. */
     readonly pageKeyMap?: string;
     /**
@@ -598,18 +800,18 @@ declare abstract class BaseQueryBuilder<C extends BaseConfigMap, EntityClient ex
      *
      * @protected
      */
-    readonly indexParamsMap: Record<string, IndexParams>;
+    readonly indexParamsMap: Record<ITS, IndexParams>;
     /** BaseQueryBuilder constructor. */
-    constructor(options: BaseQueryBuilderOptions<C, EntityClient>);
-    protected abstract getShardQueryFunction(indexToken: string): ShardQueryFunction<C>;
+    constructor(options: BaseQueryBuilderOptions<CC, EntityClient>);
+    protected abstract getShardQueryFunction(indexToken: ITS): ShardQueryFunction<CC, ET, ITS, CF>;
     /**
      * Builds a {@link ShardQueryMap | `ShardQueryMap`} object.
      *
      * @returns - The {@link ShardQueryMap | `ShardQueryMap`} object.
      */
-    build(): ShardQueryMap<C>;
-    query(options: QueryBuilderQueryOptions<C>): Promise<QueryResult<C>>;
+    build(): ShardQueryMap<CC, ET, ITS, CF>;
+    query(options: QueryBuilderQueryOptions<CC, CF>): Promise<QueryResult<CC, ET, ITS>>;
 }
 
-export { BaseEntityClient, BaseQueryBuilder, EntityManager, configSchema };
-export type { BaseConfigMap, BaseEntityClientOptions, BaseQueryBuilderOptions, Config, ConfigMap, EntityItem, EntityKey, EntityRecord, EntityToken, PageKey, ParsedConfig, QueryBuilderQueryOptions, QueryOptions, QueryResult, ShardBump, ShardQueryFunction, ShardQueryMap, ShardQueryResult, ValidateConfigMap };
+export { BaseEntityClient, BaseQueryBuilder, EntityManager, configSchema, createEntityManager };
+export type { BaseConfigMap, BaseEntityClientOptions, BaseQueryBuilderOptions, CapturedConfigMapFrom, Config, ConfigInput, ConfigMap, EntitiesFromSchema, EntityItem, EntityItemByToken, EntityKey, EntityOfToken, EntityRecord, EntityRecordByToken, EntityToken, HasIndexFor, HashKeyFrom, IndexComponentTokens, IndexHashKeyOf, IndexRangeKeyOf, IndexTokensFrom, IndexTokensOf, PageKey, PageKeyByIndex, ParsedConfig, QueryBuilderQueryOptions, QueryOptions, QueryOptionsByCC, QueryOptionsByCF, QueryResult, RangeKeyFrom, ShardBump, ShardQueryFunction, ShardQueryMap, ShardQueryMapByCC, ShardQueryMapByCF, ShardQueryResult, ShardedKeysFrom, TranscodedPropertiesFrom, UnshardedKeysFrom, ValidateConfigMap };