@karmaniverous/entity-manager 6.14.2 → 7.0.0

package/README.md

@@ -1,163 +1,72 @@
-# entity-manager
+# entity-manager
+
+[![npm version](https://img.shields.io/npm/v/@karmaniverous/entity-manager.svg)](https://www.npmjs.com/package/@karmaniverous/entity-manager) ![Node Current](https://img.shields.io/node/v/@karmaniverous/entity-manager) <!-- TYPEDOC_EXCLUDE --> [![docs](https://img.shields.io/badge/docs-website-blue)](https://docs.karmanivero.us/entity-manager) [![changelog](https://img.shields.io/badge/changelog-latest-blue.svg)](https://github.com/karmaniverous/entity-manager/tree/main/CHANGELOG.md)<!-- /TYPEDOC_EXCLUDE --> [![license](https://img.shields.io/badge/license-BSD--3--Clause-blue.svg)](https://github.com/karmaniverous/entity-manager/tree/main/LICENSE.md)
+
+Entity Manager implements rational indexing & cross‑shard querying at scale in your NoSQL database so you can focus on application logic. It is provider‑agnostic (great fit for DynamoDB) and TypeScript‑first with strong types and runtime validation.
 
-[![npm version](https://img.shields.io/npm/v/@karmaniverous/entity-manager.svg)](https://www.npmjs.com/package/@karmaniverous/entity-manager) ![Node Current](https://img.shields.io/node/v/@karmaniverous/entity-manager) <!-- TYPEDOC_EXCLUDE --> [![docs](https://img.shields.io/badge/docs-website-blue)](https://docs.karmanivero.us/entity-manager) [![changelog](https://img.shields.io/badge/changelog-latest-blue.svg)](https://github.com/karmaniverous/entity-manager/tree/main/CHANGELOG.md)<!-- /TYPEDOC_EXCLUDE --> [![license](https://img.shields.io/badge/license-BSD--3--Clause-blue.svg)](https://github.com/karmaniverous/entity-manager/tree/main/LICENSE.md)
-
-EntityManager implements rational indexing & cross-shard querying at scale in your NoSQL database so you can focus on your application logic.
-
-If you have any questions, please [start a discussion](https://github.com/karmaniverous/entity-manager/discussions). Otherwise stay tuned!
-
-## What is this?
+Key links:
 
-Entity Manager is a TypeScript-first library that applies a provider‑agnostic, highly opinionated single‑table design to your NoSQL data. It lets you:
+- Docs: https://docs.karmanivero.us/entity-manager
+- Discussions: https://github.com/karmaniverous/entity-manager/discussions
 
-- Define a global hash key and range key, plus additional generated properties used by your indexes.
-- Encode/decode indexable elements via transcodes so strings sort like their original types.
-- Configure a time‑based sharding strategy (shard bumps) that grows as you scale.
-- Query across many shards and indexes in parallel through injected “shard query” functions — results are combined, de‑duplicated, sorted, and returned with a compact, dehydrated page key for the next request.
+## Why this library?
 
-It is designed to work with stores like DynamoDB but keeps the orchestration provider‑neutral.
+Modern NoSQL puts the burden of indexing, sharding, and pagination on the application. Entity Manager gives you:
 
-Key links:
-
-- API: https://docs.karmanivero.us/entity-manager
-- Requirements: see .stan/system/stan.requirements.md (authoritative for v6.14.0)
-- Example test configuration: see test/config.ts
-
-## Features
-
-- Global model for generated properties, indexes, and property transcodes
-  - generatedProperties.sharded and generatedProperties.unsharded
-  - Global indexes: indexToken → { hashKey, rangeKey, projections? }
-  - Global propertyTranscodes: property → transcodeName
-- Deterministic sharding
-  - Time‑windowed shard bumps: { timestamp, charBits, chars }
-  - Full shard space assignment per bump (uses radix\*\*chars placeholders)
-  - Cross‑bump query enumeration over all applicable shards
-- Page key dehydration/rehydration
-  - Compact string arrays and lz‑string compression for transport
-  - Rehydrate back to pageKey objects for each index+shard
-- Provider‑agnostic parallel query orchestration
-  - Inject shard query functions for each index
-  - Parallel fan‑out with configurable throttle
-  - Combine, dedupe by unique property, and sort results
-- Strong typing + runtime validation
-  - Zod‑validated config parsing
-  - Robust TypeScript surface for config, items, keys, queries
+- Values‑first configuration with runtime validation (Zod) and best‑in‑class inference.
+- Token‑aware and index‑aware types end‑to‑end (entities, keys, page keys, queries).
+- Deterministic sharding with a time‑based scale‑up schedule.
+- Cross‑shard, multi‑index query orchestration with dedupe and sorting.
+- Dehydration/rehydration of page keys to pass a single compact token between calls.
 
 ## Install
 
 ```bash
 npm install @karmaniverous/entity-manager
-# optional: testing support used in the repo
+# optional (tests/demo helpers)
 npm install --save-dev @karmaniverous/mock-db
 ```
 
-TypeScript is strongly recommended. The library will validate configuration at runtime for JavaScript users, but you lose compile‑time guarantees.
-
-## Usage overview
-
-The pattern has three parts:
-
-1. Define your entity types and a config map
-
-- Each entity type lists all properties that exist on your records.
-- Entity‑level behaviors live in the config’s entities block (timestamp property, unique property, shard bumps).
-- Generated properties, indexes, and transcodes are defined globally.
-
-2. Create an EntityManager instance
-
-- Pass your config (validated with Zod).
-- Optionally inject a logger with debug/error methods (defaults to console).
-
-3. Use EntityManager helpers
-
-- addKeys / getPrimaryKey / removeKeys
-- encodeGeneratedProperty / decodeGeneratedProperty
-- getIndexComponents / unwrapIndex / dehydrateIndexItem / rehydrateIndexItem
-- dehydratePageKeyMap / rehydratePageKeyMap
-- query(options) to orchestrate cross‑shard multi‑index queries
-
-## Quick start (TypeScript)
-
-Below is a minimal end‑to‑end example showing shape and intent. It mirrors the current implementation’s global config model.
-
-```ts
-import {
-  defaultTranscodes,
-  type ConfigMap,
-} from '@karmaniverous/entity-manager';
-import { EntityManager } from '@karmaniverous/entity-manager';
-
-// 1) Entity definitions (Typescript types)
-interface User {
-  userId: string; // unique property
-  created: number; // timestamp property
-  updated: number;
-  firstNameCanonical: string;
-  lastNameCanonical: string;
-  // Generated properties exist on stored items but are configured globally:
-  // e.g., firstNameRK (unsharded), lastNameRK (unsharded), userPK (sharded)
-}
-
-type MyConfigMap = ConfigMap<{
-  EntityMap: { user: User };
-  HashKey: 'hashKey'; // defaults are 'hashKey' / 'rangeKey' if omitted
-  RangeKey: 'rangeKey';
-  ShardedKeys: 'userPK'; // token(s) for sharded generated properties
-  UnshardedKeys: 'firstNameRK' | 'lastNameRK';
-  TranscodedProperties:
-    | 'userId'
-    | 'created'
-    | 'updated'
-    | 'firstNameCanonical'
-    | 'lastNameCanonical';
-}>;
-
-// 2) Build a config with the global model
-const now = Date.now();
-const manager = new EntityManager<MyConfigMap>({
-  // Per-entity: unique + timestamp + shard schedule (+ optional defaults)
-  entities: {
-    user: {
-      uniqueProperty: 'userId',
-      timestampProperty: 'created',
-      shardBumps: [
-        // records with timestamp < now → effectively unsharded
-        { timestamp: now, charBits: 1, chars: 0 },
-        // records with timestamp ≥ now → 1 char at radix 4 (2^2) gives 4 shards
-        { timestamp: now, charBits: 2, chars: 1 },
-      ],
-      // optional defaults (used by query if omitted in options)
-      defaultLimit: 10,
-      defaultPageSize: 10,
-    },
-  },
+## DX highlights
+
+- Values‑first + schema‑first config:
+  - Use a config literal (prefer `as const` and `satisfies`) to preserve literal tokens.
+  - Optionally provide Zod schemas (`entitiesSchema`) to infer entity shapes without generics.
+- Token‑aware helpers:
+  - `addKeys`, `getPrimaryKey`, `removeKeys` narrow types by entity token (no casts).
+- Index‑aware page keys (optional CF channel):
+  - Provide a values‑first config literal (CF) with `indexes` and get typed page keys per index.
+  - Use `QueryOptionsByCF` and `ShardQueryMapByCF` to derive index token unions directly from CF.
+- CC-based DX sugar (values-first captured config):
+  - Use `QueryOptionsByCC` and `ShardQueryMapByCC` to derive index token unions from a captured config type (via `IndexTokensFrom`), while still benefiting from page-key narrowing.
+
+## Quick start (values‑first + schema‑first)
+
+import { z } from 'zod';
+import { createEntityManager, defaultTranscodes } from '@karmaniverous/entity-manager';
+
+// 1) Schema-first entity shapes (non-generated fields only)
+const userSchema = z.object({
+  userId: z.string(),          // unique property
+  created: z.number(),         // timestamp property
+  updated: z.number().optional(),
+  firstNameCanonical: z.string(),
+  lastNameCanonical: z.string(),
+});
 
-  // Global generated properties (tokens → element lists)
+// 2) Values-first config literal (prefer `as const`)
+const config = {
+  hashKey: 'hashKey2',
+  rangeKey: 'rangeKey',
   generatedProperties: {
     sharded: {
-      userPK: ['userId'], // atomic (all required)
+      userPK: ['userId'] as const,
     },
     unsharded: {
-      firstNameRK: ['firstNameCanonical', 'lastNameCanonical', 'created'],
-      lastNameRK: ['lastNameCanonical', 'firstNameCanonical', 'created'],
+      firstNameRK: ['firstNameCanonical', 'lastNameCanonical'] as const,
+      lastNameRK: ['lastNameCanonical', 'firstNameCanonical'] as const,
     },
   },
-
-  // Global key tokens
-  hashKey: 'hashKey',
-  rangeKey: 'rangeKey',
-
-  // Global indexes (hashKey, rangeKey must match allowed token sets)
-  indexes: {
-    created: { hashKey: 'hashKey', rangeKey: 'created' },
-    updated: { hashKey: 'hashKey', rangeKey: 'updated' },
-    firstName: { hashKey: 'hashKey', rangeKey: 'firstNameRK' },
-    lastName: { hashKey: 'hashKey', rangeKey: 'lastNameRK' },
-    userCreated: { hashKey: 'userPK', rangeKey: 'created' }, // sharded alt hash
-  },
-
-  // Transcode mapping for scalar/unsharded elements and properties
   propertyTranscodes: {
     userId: 'string',
     created: 'timestamp',
@@ -165,179 +74,183 @@ const manager = new EntityManager<MyConfigMap>({
     firstNameCanonical: 'string',
     lastNameCanonical: 'string',
   },
-
-  // Transcodes (can override/extend defaultTranscodes)
+  indexes: {
+    created: { hashKey: 'hashKey2', rangeKey: 'created' },
+    userCreated: { hashKey: 'userPK', rangeKey: 'created' },
+    firstName: { hashKey: 'hashKey2', rangeKey: 'firstNameRK' },
+    lastName: { hashKey: 'hashKey2', rangeKey: 'lastNameRK' },
+  } as const,
+  entities: {
+    user: {
+      uniqueProperty: 'userId',
+      timestampProperty: 'created',
+      shardBumps: [{ timestamp: Date.now(), charBits: 2, chars: 1 }],
+    },
+  },
+  entitiesSchema: { user: userSchema },
   transcodes: defaultTranscodes,
+} as const;
 
-  // Delimiters and query throttle (defaults shown)
-  generatedKeyDelimiter: '|',
-  generatedValueDelimiter: '#',
-  shardKeyDelimiter: '!',
-  throttle: 10,
-});
+// 3) Create the manager — types captured from values, shapes from schemas
+const manager = createEntityManager(config);
 ```
 
-### Generate keys on items
+### Token‑aware helpers
 
 ```ts
-// A partial item (no keys yet)
+// Input item (no generated keys yet)
 const user = {
-  userId: 'u123',
+  userId: 'u1',
   created: Date.now(),
-  updated: Date.now(),
   firstNameCanonical: 'lee',
   lastNameCanonical: 'zhang',
 };
 
-// Add hashKey, rangeKey, and generated properties
-const record = manager.addKeys('user', user); // returns EntityRecord<...>
+// Add generated keys (hashKey/rangeKey + index tokens)
+const record = manager.addKeys('user', user);
 
-// Get just the primary key
-const keyOnly = manager.getPrimaryKey('user', user); // { hashKey, rangeKey }
+// Compute one or more primary keys
+const keys = manager.getPrimaryKey('user', { userId: 'u1' });
 
-// Remove generated keys from a stored record
-const pruned = manager.removeKeys('user', record);
+// Strip generated keys after read
+const item = manager.removeKeys('user', record);
 ```
 
-### Encode/decode generated property strings
+Types narrow automatically from the entity token (`'user'`). No casts required.
 
-```ts
-// Encode an unsharded generated property (always returns a string)
-const fn = manager.encodeGeneratedProperty('firstNameRK', record);
-// e.g. "firstNameCanonical#lee|lastNameCanonical#zhang|created#000001711234567"
+## Index‑aware querying (CF channel)
 
-// Decode back into an object fragment
-import { decodeGeneratedProperty } from '@karmaniverous/entity-manager';
-const decoded = decodeGeneratedProperty(manager, fn); // { firstNameCanonical: 'lee', ... }
-```
+When you author a values‑first config literal with `indexes` (prefer `as const`), Entity Manager can:
 
-### Query across shards and indexes
-
-Entity Manager relies on injected shard query functions to perform provider‑specific queries on each shard/index page. The library orchestrates:
-
-- page‑key rehydration → parallel shard queries → de‑duplication and sorting → page‑key dehydration.
+- Constrain `shardQueryMap` keys to the index key union.
+- Narrow page‑key shapes per index (only its component tokens).
+- Derive ITS (index token subset) automatically from CF via `QueryOptionsByCF` and `ShardQueryMapByCF`.
 
 ```ts
 import type {
-  QueryOptions,
   ShardQueryFunction,
+  ShardQueryMapByCF,
+  QueryOptionsByCF,
 } from '@karmaniverous/entity-manager';
 
-// Example shard query using a made-up client (see @karmaniverous/mock-db in repo tests)
-const firstNameQuery: ShardQueryFunction<MyConfigMap> = async (
-  hashKey,
-  pageKey,
-  pageSize,
-) => {
-  // Return { count, items, pageKey? } for this shard+index page
-  // pageKey is a partial item object with necessary index components
-  // ... perform provider-specific work here ...
-  return { count: 0, items: [], pageKey };
+// CF: capture index tokens from a values-first literal
+const cf = {
+  indexes: {
+    firstName: { hashKey: 'hashKey2', rangeKey: 'firstNameRK' },
+    lastName:  { hashKey: 'hashKey2', rangeKey: 'lastNameRK'  },
+  },
+} as const;
+type CF = typeof cf;
+
+// SQFs are typed; pageKey is narrowed to index components per IT
+const firstNameSQF: ShardQueryFunction<MyConfigMap, 'user', 'firstName', CF> =
+  async (hashKey, pageKey, pageSize) => ({ count: 0, items: [], pageKey });
+const lastNameSQF: ShardQueryFunction<MyConfigMap, 'user', 'lastName', CF> =
+  async (hashKey, pageKey, pageSize) => ({ count: 0, items: [], pageKey });
+
+// CF-aware shardQueryMap — only 'firstName' | 'lastName' allowed
+const shardQueryMap: ShardQueryMapByCF<MyConfigMap, 'user', CF> = {
+  firstName: firstNameSQF,
+  lastName: lastNameSQF,
 };
 
-// Invoke query with shardQueryMap
-const result = await manager.query({
+// Derive ITS from CF for options
+const options: QueryOptionsByCF<MyConfigMap, 'user', CF> = {
   entityToken: 'user',
-  item: {}, // often used to supply elements for alternate hash keys
-  shardQueryMap: { firstName: firstNameQuery },
+  item: {},
+  shardQueryMap,
   limit: 50,
   pageSize: 10,
-  // optional: pageKeyMap: previousResult.pageKeyMap,
-  // optional: timestampFrom / timestampTo for shard-space windowing
-});
+};
+
+const result = await manager.query(options);
+// result.pageKeyMap is a compact string — pass it to the next call’s options.pageKeyMap
+```
+
+### CC-based aliases
+
+You can also derive ITS (index token subset) directly from a values‑first captured config type (CC) using `QueryOptionsByCC` and `ShardQueryMapByCC`. This mirrors the CF helpers but drives ITS from the CC type (via `IndexTokensFrom`) and passes the same CC through the CF channel for page‑key narrowing.
+
+```ts
+import type {
+  ShardQueryFunction,
+  ShardQueryMapByCC,
+  QueryOptionsByCC,
+} from '@karmaniverous/entity-manager';
+
+// A values-first config literal capturing index tokens (the same shape used for CF)
+const cc = {
+  indexes: {
+    firstName: { hashKey: 'hashKey2', rangeKey: 'firstNameRK' },
+    lastName:  { hashKey: 'hashKey2', rangeKey: 'lastNameRK'  },
+  },
+} as const;
+type CC = typeof cc;
+
+// Reuse typed SQFs (pageKey narrowed per index)
+const firstNameSQF: ShardQueryFunction<MyConfigMap, 'user', 'firstName', CC> =
+  async (hashKey, pageKey, pageSize) => ({ count: 0, items: [], pageKey });
+const lastNameSQF: ShardQueryFunction<MyConfigMap, 'user', 'lastName', CC> =
+  async (hashKey, pageKey, pageSize) => ({ count: 0, items: [], pageKey });
+
+// CC-aware shardQueryMap — only 'firstName' | 'lastName' allowed
+const shardQueryMapCC: ShardQueryMapByCC<MyConfigMap, 'user', CC> = {
+  firstName: firstNameSQF,
+  lastName: lastNameSQF,
+};
+const optionsCC: QueryOptionsByCC<MyConfigMap, 'user', CC> = { entityToken: 'user', item: {}, shardQueryMap: shardQueryMapCC };
+const resultCC = await manager.query(optionsCC);
 ```
 
 Notes:
 
-- The result includes a compressed pageKeyMap string for the next call.
-- Entity Manager enumerates the hash key space for the time window, rehydrates the prior page keys (if any), and fans out queries across all shard+index pairs in `shardQueryMap` (up to `throttle`).
-- Items are deduplicated by the entity’s unique property and sorted by `sortOrder` (if provided).
-
-## Configuration reference (current model, v6.14.0)
-
-- entities: Record<entityToken, { timestampProperty, uniqueProperty, shardBumps?, defaultLimit?, defaultPageSize? }>
-- generatedProperties:
-  - sharded: Record<ShardedKey, TranscodedProperties[]>
-  - unsharded: Record<UnshardedKey, TranscodedProperties[]>
-- indexes: Record<indexToken, {
-  - hashKey: HashKey | ShardedKey
-  - rangeKey: RangeKey | UnshardedKey | TranscodedProperties
-  - projections?: string[]
-    }>
-- propertyTranscodes: Record<TranscodedProperties, keyof TranscodeMap>
-- transcodes: Record<transcodeName, { encode, decode }> (defaults to defaultTranscodes)
-- hashKey: HashKey (e.g., 'hashKey')
-- rangeKey: RangeKey (e.g., 'rangeKey')
-- generatedKeyDelimiter: string (default '|', must match /\W+/)
-- generatedValueDelimiter: string (default '#', must match /\W+/)
-- shardKeyDelimiter: string (default '!', must match /\W+/)
-- throttle: number (default 10)
-
-Validation highlights:
-
-- Delimiters must not contain each other.
-- Keys and tokens must be mutually exclusive as required.
-- Generated property element lists are non‑empty and have no duplicates.
-- propertyTranscodes values must exist in transcodes.
-- Index hashKey/rangeKey must use valid token sets.
-- shardBumps are sorted, include a zero‑timestamp bump if missing, and chars must increase monotonically with timestamp.
-
-Sharding:
-
-- For assignment: a record always uses all placeholders for its applicable bump; suffix space is (2**charBits) ** chars.
-- For queries: hash key space spans all bumps overlapping [timestampFrom, timestampTo].
+- Entity Manager enumerates hash‑key space for the time window, rehydrates page keys (when present), executes shard queries in parallel (throttled), dedupes by unique property, sorts, and dehydrates a new pageKeyMap.
+- For provider integration, the SQF lambda encapsulates the platform‑specific query for one index + shard page. See tests and entity‑client‑dynamodb for examples.
+
+
+- `rehydratePageKeyMap` decodes a dehydrated array (compressed string) into a two‑layer map of `{ indexToken: { hashKeyValue: pageKey | undefined } }`.
+- `dehydratePageKeyMap` performs the inverse and emits a compact array (compressed in `query()`).
+- You rarely call these directly — `query()` composes them for you — but the API is exposed for advanced flows.
 
 ## ESM / CJS
 
 ```ts
 // ESM
-import {
-  EntityManager,
-  defaultTranscodes,
-} from '@karmaniverous/entity-manager';
+import { createEntityManager, defaultTranscodes } from '@karmaniverous/entity-manager';
 
 // CJS
-const {
-  EntityManager,
-  defaultTranscodes,
-} = require('@karmaniverous/entity-manager');
+const { createEntityManager, defaultTranscodes } = require('@karmaniverous/entity-manager');
 ```
 
 ## Logging
 
-All helpers log debug context and error detail via the injected logger (defaults to `console`). In tests, you may supply a quiet logger:
+Entity Manager logs debug and error details via the injected logger (defaults to `console`).
 
 ```ts
 const logger = { debug: () => undefined, error: console.error };
-const manager = new EntityManager(config, logger);
+const manager = createEntityManager(config, logger);
 ```
 
-## Delimiter safety
-
-Generated key/value delimiters and the shard key delimiter are used when composing strings:
-
-- generatedKeyDelimiter: '|' (between pairs)
-- generatedValueDelimiter: '#' (between key and value)
-- shardKeyDelimiter: '!' (between entity token and shard suffix)
-
-Your scalar property values used in generated properties should not include these delimiters. If they must, set custom delimiters (must match /\W+/ and not contain each other).
-
-## Types you’ll use most
+## Types you’ll reach for
 
-- ConfigMap<M>
-- EntityItem<C>, EntityRecord<C>, EntityKey<C>, EntityToken<C>
-- QueryOptions<C>, QueryResult<C>
-- PageKey<C>, PageKeyMap<C>
-- ShardQueryFunction<C>, ShardQueryMap<C>, ShardBump
+- Values/schema capture
+  - `createEntityManager(config, logger?)`
+  - `ConfigInput` (values‑first), `CapturedConfigMapFrom`, `EntitiesFromSchema`
+- Token aware
+  - `EntityToken<CC>`, `EntityItemByToken<CC, ET>`, `EntityRecordByToken<CC, ET>`
+- Index aware (CF channel)
+  - `PageKeyByIndex<CC, ET, IT, CF>`
+  - `ShardQueryFunction<CC, ET, IT, CF>`, `ShardQueryMap<CC, ET, ITS, CF>`
+  - `QueryOptions<CC, ET, ITS, CF>`, `QueryResult<CC, ET, ITS>`
+  - DX sugar: `IndexTokensOf<CF>`, `QueryOptionsByCF`, `ShardQueryMapByCF`, `IndexTokensFrom<CC>`, `QueryOptionsByCC`, `ShardQueryMapByCC`
 
 See the full API: https://docs.karmanivero.us/entity-manager
 
 ## Scripts (repo)
 
-- build: rollup outputs ESM/CJS + .d.ts
-- test: vitest with coverage
-- lint: ESLint (type‑aware) + Prettier integration
-- docs: TypeDoc (links to external type docs for shared utility packages)
- test: vitest with coverage
+- build: rollup outputs ESM/CJS + .d.ts
+- lint: ESLint (type‑aware) + Prettier
+- docs: TypeDoc
 - typecheck: tsc + tsd (type‑level tests)
 
 ## License
@@ -346,4 +259,4 @@ BSD‑3‑Clause (see package.json).
 
 ---
 
-Built for you with ❤️ on Bali! Find more great tools & templates on [my GitHub Profile](https://github.com/karmaniverous).
+Built for you with ❤️ on Bali! Find more great tools & templates on [my GitHub Profile](https://github.com/karmaniverous).

package/dist/cjs/BaseEntityClient/BaseEntityClient.js

@@ -3,7 +3,7 @@
 /**
  * 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
  */

package/dist/cjs/BaseQueryBuilder/BaseQueryBuilder.js

@@ -5,9 +5,10 @@ var radash = require('radash');
 /**
  * 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
  */
@@ -32,7 +33,7 @@ class BaseQueryBuilder {
      * @returns - The {@link ShardQueryMap | `ShardQueryMap`} object.
      */
     build() {
-        return radash.mapValues(this.indexParamsMap, (indexConfig, indexToken) => this.getShardQueryFunction(indexToken));
+        return radash.mapValues(this.indexParamsMap, (_indexConfig, indexToken) => this.getShardQueryFunction(indexToken));
     }
     async query(options) {
         const { entityClient: { entityManager }, entityToken, pageKeyMap, } = this;

package/dist/cjs/EntityManager/EntityManager.js

@@ -14,7 +14,7 @@ var _EntityManager_config;
  * 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.
@@ -70,7 +70,7 @@ class EntityManager {
     }
     getPrimaryKey(entityToken, i, overwrite = false) {
         if (Array.isArray(i)) {
-            return i.map((item) => getPrimaryKey.getPrimaryKey(this, entityToken, item, overwrite));
+            return i.flatMap((item) => getPrimaryKey.getPrimaryKey(this, entityToken, item, overwrite));
         }
         return getPrimaryKey.getPrimaryKey(this, entityToken, i, overwrite);
     }

package/dist/cjs/EntityManager/createEntityManager.js

@@ -0,0 +1,42 @@
+'use strict';
+
+var EntityManager = require('./EntityManager.js');
+
+/**
+ * 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.
+ */
+function createEntityManager(config, logger = console) {
+    // Cast to the existing Config<C> shape for runtime parsing; Zod validation
+    // remains authoritative at construction time.
+    // Optional dev guardrail: cross-check entitiesSchema keys vs config.entities keys.
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+        if (config && 'entitiesSchema' in config && config.entitiesSchema) {
+            const schemaKeys = Object.keys(config
+                .entitiesSchema ?? {});
+            const entitiesKeys = Object.keys(config
+                .entities ?? {});
+            const missingInEntities = schemaKeys.filter((k) => !entitiesKeys.includes(k));
+            const missingInSchema = entitiesKeys.filter((k) => !schemaKeys.includes(k));
+            if (missingInEntities.length || missingInSchema.length) {
+                logger.debug('entitiesSchema keys mismatch with config.entities', {
+                    missingInEntities,
+                    missingInSchema,
+                });
+            }
+        }
+    }
+    catch {
+        // Best-effort warning only; never block construction.
+    }
+    return new EntityManager.EntityManager(config, logger);
+}
+
+exports.createEntityManager = createEntityManager;

package/dist/cjs/EntityManager/decodeGeneratedProperty.js

@@ -7,14 +7,14 @@ var decodeElement = require('./decodeElement.js');
  * Decode a generated property value. Returns an {@link EntityItem | `EntityItem`}.
  *
  * @param entityManager - {@link EntityManager | `EntityManager`} instance.
- * @param entityToken - `entityManager.config.entities` key.
+ * @param entityToken - {@link Config.entities | `entityManager.config.entities`} key.
  * @param encoded - Encoded generated property value.
  *
  * @returns {@link EntityItem | `EntityItem`} object with updated properties decoded from `encoded`.
  *
  * @throws `Error` if `entityToken` is invalid.
  */
-function decodeGeneratedProperty(entityManager, encoded) {
+function decodeGeneratedProperty(entityManager, entityToken, encoded) {
     try {
         const { generatedKeyDelimiter, generatedValueDelimiter, hashKey, shardKeyDelimiter, } = entityManager.config;
         // Handle degenerate case.
@@ -39,6 +39,8 @@ function decodeGeneratedProperty(entityManager, encoded) {
             encoded,
             decoded,
         });
+        // entityToken used for typing only (ET-narrowed result).
+        void entityToken;
         return decoded;
     }
     catch (error) {