@karmaniverous/entity-manager 7.0.1 → 7.1.1

package/README.md

@@ -2,261 +2,392 @@
 
 [![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.
-
-Key links:
-
-- Docs: https://docs.karmanivero.us/entity-manager
-- Discussions: https://github.com/karmaniverous/entity-manager/discussions
-
-## Why this library?
-
-Modern NoSQL puts the burden of indexing, sharding, and pagination on the application. Entity Manager gives you:
-
-- 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 (tests/demo helpers)
-npm install --save-dev @karmaniverous/mock-db
-```
-
-## 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(),
-});
-
-// 2) Values-first config literal (prefer `as const`)
-const config = {
-  hashKey: 'hashKey2',
-  rangeKey: 'rangeKey',
-  generatedProperties: {
-    sharded: {
-      userPK: ['userId'] as const,
-    },
-    unsharded: {
-      firstNameRK: ['firstNameCanonical', 'lastNameCanonical'] as const,
-      lastNameRK: ['lastNameCanonical', 'firstNameCanonical'] as const,
-    },
-  },
-  propertyTranscodes: {
-    userId: 'string',
-    created: 'timestamp',
-    updated: 'timestamp',
-    firstNameCanonical: 'string',
-    lastNameCanonical: 'string',
-  },
-  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;
-
-// 3) Create the manager — types captured from values, shapes from schemas
-const manager = createEntityManager(config);
-```
-
-### Token‑aware helpers
-
-```ts
-// Input item (no generated keys yet)
-const user = {
-  userId: 'u1',
-  created: Date.now(),
-  firstNameCanonical: 'lee',
-  lastNameCanonical: 'zhang',
-};
-
-// Add generated keys (hashKey/rangeKey + index tokens)
-const record = manager.addKeys('user', user);
-
-// Compute one or more primary keys
-const keys = manager.getPrimaryKey('user', { userId: 'u1' });
-
-// Strip generated keys after read
-const item = manager.removeKeys('user', record);
-```
-
-Types narrow automatically from the entity token (`'user'`). No casts required.
-
-## Index‑aware querying (CF channel)
-
-When you author a values‑first config literal with `indexes` (prefer `as const`), Entity Manager can:
-
-- 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 {
-  ShardQueryFunction,
-  ShardQueryMapByCF,
-  QueryOptionsByCF,
-} from '@karmaniverous/entity-manager';
-
-// 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,
-};
-
-// Derive ITS from CF for options
-const options: QueryOptionsByCF<MyConfigMap, 'user', CF> = {
-  entityToken: 'user',
-  item: {},
-  shardQueryMap,
-  limit: 50,
-  pageSize: 10,
-};
-
-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:
-
-- 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 { createEntityManager, defaultTranscodes } from '@karmaniverous/entity-manager';
-
-// CJS
-const { createEntityManager, defaultTranscodes } = require('@karmaniverous/entity-manager');
-```
-
-## Logging
-
-Entity Manager logs debug and error details via the injected logger (defaults to `console`).
-
-```ts
-const logger = { debug: () => undefined, error: console.error };
-const manager = createEntityManager(config, logger);
-```
-
-## Types you’ll reach for
-
-- 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
-- docs: TypeDoc
-- typecheck: tsc + tsd (type‑level tests)
-
-## License
-
-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).
+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.
+
+Key links:
+
+- Docs: https://docs.karmanivero.us/entity-manager
+- Discussions: https://github.com/karmaniverous/entity-manager/discussions
+
+## Why this library?
+
+Modern NoSQL puts the burden of indexing, sharding, and pagination on the application. Entity Manager gives you:
+
+- 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 (tests/demo helpers)
+npm install --save-dev @karmaniverous/mock-db
+```
+
+## 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.
+- Projection‑aware typing (type‑only K):
+  - Pass attributes as a const tuple (K) through your query types to narrow result items to Pick<…> of those properties.
+  - No runtime change; adapters execute projections. Adapters should auto‑include `uniqueProperty` and any explicit sort keys when callers omit them to preserve dedupe/sort invariants.
+- Index‑aware typing (values‑first config literal “CF” and captured config “CC” helpers):
+  - CF (values‑first config literal): drive index token unions and page‑key narrowing directly from a values‑first config literal (`QueryOptionsByCF`, `ShardQueryMapByCF`).
+  - CC (Captured Config): derive index tokens from a captured config type while reusing CF for narrowing (`QueryOptionsByCC`, `ShardQueryMapByCC`).
+- 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)
+
+```ts
+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(),
+});
+
+// 2) Values-first config literal (prefer `as const`)
+const config = {
+  hashKey: 'hashKey2',
+  rangeKey: 'rangeKey',
+  generatedProperties: {
+    sharded: {
+      userPK: ['userId'] as const,
+    },
+    unsharded: {
+      firstNameRK: ['firstNameCanonical', 'lastNameCanonical'] as const,
+      lastNameRK: ['lastNameCanonical', 'firstNameCanonical'] as const,
+    },
+  },
+  propertyTranscodes: {
+    userId: 'string',
+    created: 'timestamp',
+    updated: 'timestamp',
+    firstNameCanonical: 'string',
+    lastNameCanonical: 'string',
+  },
+  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;
+
+// 3) Create the manager — types captured from values, shapes from schemas
+const manager = createEntityManager(config);
+```
+
+### Token‑aware helpers
+
+```ts
+// Input item (no generated keys yet)
+const user = {
+  userId: 'u1',
+  created: Date.now(),
+  firstNameCanonical: 'lee',
+  lastNameCanonical: 'zhang',
+};
+
+// Add generated keys (hashKey/rangeKey + index tokens)
+const record = manager.addKeys('user', user);
+
+// Compute one or more primary keys
+const keys = manager.getPrimaryKey('user', { userId: 'u1' });
+
+// Strip generated keys after read
+const item = manager.removeKeys('user', record);
+```
+
+Types narrow automatically from the entity token (`'user'`). No casts required.
+
+## Index‑aware querying (values‑first config literal, “CF” channel)
+
+When you author a values‑first config literal with `indexes` (prefer `as const`), Entity Manager can:
+
+- 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 {
+  ShardQueryFunction,
+  ShardQueryMapByCF,
+  QueryOptionsByCF,
+} from '@karmaniverous/entity-manager';
+
+// 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,
+};
+
+// Derive ITS from CF for options
+const options: QueryOptionsByCF<MyConfigMap, 'user', CF> = {
+  entityToken: 'user',
+  item: {},
+  shardQueryMap,
+  limit: 50,
+  pageSize: 10,
+};
+
+const result = await manager.query(options);
+// result.pageKeyMap is a compact string — pass it to the next call’s options.pageKeyMap
+```
+
+### Captured Config (“CC”) 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:
+
+- 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.
+
+## Projection‑aware typing (K)
+
+Entity Manager supports a type‑only projection channel K that narrows result item shapes when a provider adapter projects a subset of attributes at runtime. Pass your attributes as a const tuple and thread K through `ShardQueryFunction/Map`, `QueryOptions`, and `QueryResult`.
+
+```ts
+import type {
+  ConfigMap,
+  EntityItemByToken,
+  QueryOptions,
+  QueryResult,
+  ShardQueryFunction,
+  ShardQueryMap,
+} from '@karmaniverous/entity-manager';
+
+// Minimal entities (example)
+interface Email {
+  created: number;
+  email: string;
+  userId: string;
+}
+interface User {
+  beneficiaryId: string;
+  created: number;
+  firstNameCanonical: string;
+  lastNameCanonical: string;
+  phone?: string;
+  updated: number;
+  userId: string;
+}
+
+type MyConfigMap = ConfigMap<{
+  EntityMap: { email: Email; user: User };
+  HashKey: 'hashKey2';
+  RangeKey: 'rangeKey';
+  ShardedKeys: 'beneficiaryPK' | 'userPK';
+  UnshardedKeys: 'firstNameRK' | 'lastNameRK' | 'phoneRK';
+  TranscodedProperties:
+    | 'beneficiaryId'
+    | 'created'
+    | 'email'
+    | 'firstNameCanonical'
+    | 'lastNameCanonical'
+    | 'phone'
+    | 'updated'
+    | 'userId';
+}>;
+
+// CF capturing a single index
+const cf = {
+  indexes: {
+    firstName: { hashKey: 'hashKey2', rangeKey: 'firstNameRK' },
+  },
+} as const;
+type CF = typeof cf;
+
+// Projection attributes as const tuple — narrows K.
+const attrs = ['userId', 'created'] as const;
+type K = typeof attrs;
+
+// A typed SQF: pageKey narrows via CF; items narrow via K (type-only).
+const sqf: ShardQueryFunction<MyConfigMap, 'user', 'firstName', CF, K> = async (
+  _hashKey,
+  _pageKey,
+  _pageSize,
+) => ({
+  count: 0,
+  items: [], // never[] is assignable to the projected array
+  pageKey: _pageKey,
+});
+
+// ShardQueryMap carrying CF and K.
+const map: ShardQueryMap<MyConfigMap, 'user', 'firstName', CF, K> = {
+  firstName: sqf,
+};
+const options: QueryOptions<MyConfigMap, 'user', 'firstName', CF, K> = {
+  entityToken: 'user',
+  item: {},
+  shardQueryMap: map,
+};
+const result: QueryResult<MyConfigMap, 'user', 'firstName', K> =
+  await manager.query(options);
+// result.items: Pick<EntityItemByToken<MyConfigMap, 'user'>, 'userId' | 'created'>[]
+```
+
+Notes:
+
+- K is a type‑only channel; it does not change runtime behavior. Providers (e.g., DynamoDB adapters) execute projections.
+- Dedupe/sort invariants: Entity Manager dedupes by `uniqueProperty` and applies `QueryOptions.sortOrder`. If your adapter projects attributes, ensure it auto‑includes `uniqueProperty` and any explicit sort keys when callers omit them from K.
+
+## Page keys in a nutshell
+
+- `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 {
+  createEntityManager,
+  defaultTranscodes,
+} from '@karmaniverous/entity-manager';
+
+// CJS
+const {
+  createEntityManager,
+  defaultTranscodes,
+} = require('@karmaniverous/entity-manager');
+```
+
+## Logging
+
+Entity Manager logs debug and error details via the injected logger (defaults to `console`).
+
+```ts
+const logger = { debug: () => undefined, error: console.error };
+const manager = createEntityManager(config, logger);
+```
+
+## Types you’ll reach for
+
+- Values/schema capture
+  - `createEntityManager(config, logger?)`
+  - `ConfigInput` (values‑first), `CapturedConfigMapFrom`, `EntitiesFromSchema`
+- Token aware
+  - `EntityToken<CC>`, `EntityItemByToken<CC, ET>`, `EntityRecordByToken<CC, ET>`
+- Index aware (values‑first config literal, “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`
+- Projection helpers
+  - `KeysFrom<K>`
+  - `Projected<T, K>`
+  - `ProjectedItemByToken<CC, ET, K>`
+
+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
+- docs: TypeDoc
+- typecheck: tsc + tsd (type‑level tests)
+
+## License
+
+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).

package/dist/cjs/BaseQueryBuilder/BaseQueryBuilder.js

@@ -9,6 +9,7 @@ var radash = require('radash');
  * @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.
+ * @typeParam K - Optional projection keys; narrows item shape when provided.
  *
  * @category QueryBuilder
  */

package/dist/cjs/EntityManager/EntityManager.js

@@ -30,7 +30,14 @@ class EntityManager {
      */
     constructor(config, logger = console) {
         _EntityManager_config.set(this, void 0);
-        tslib.__classPrivateFieldSet(this, _EntityManager_config, ParsedConfig.configSchema.parse(config), "f");
+        // Accept a compile-time-only `entitiesSchema` key on values-first configs.
+        // We strip it here so the same literal config can be used with either the
+        // factory or the direct constructor without tripping Zod's strict parser.
+        //
+        // This keeps runtime semantics unchanged and avoids widening ParsedConfig.
+        const cfgWithOptionalES = config;
+        const { entitiesSchema: _ignored, ...configForParse } = cfgWithOptionalES;
+        tslib.__classPrivateFieldSet(this, _EntityManager_config, ParsedConfig.configSchema.parse(configForParse), "f");
         this.logger = logger;
     }
     /**

package/dist/cjs/EntityManager/query.js

@@ -28,8 +28,10 @@ const { compressToEncodedURIComponent, decompressFromEncodedURIComponent } = lzS
  */
 async function query(entityManager, options) {
     try {
-        // Get defaults.
-        const { defaultLimit, defaultPageSize } = entityManager.config.entities[options.entityToken];
+        // Get defaults (avoid unsafe destructuring on generic access).
+        const entityDefaults = entityManager.config.entities[options.entityToken];
+        const defaultLimit = entityDefaults.defaultLimit;
+        const defaultPageSize = entityDefaults.defaultPageSize;
         // Extract params.
         const { entityToken, limit = defaultLimit, item, pageKeyMap, pageSize = defaultPageSize, shardQueryMap, sortOrder = [], timestampFrom = 0, timestampTo = Date.now(), throttle = entityManager.config.throttle, } = options;
         // Validate params.
@@ -98,8 +100,12 @@ async function query(entityManager, options) {
                 break;
         } while (workingResult.items.length < limit);
         // Dedupe & sort working result.
-        workingResult.items = entityTools.sort(radash.unique(workingResult.items, (i) => i[entityManager.config.entities[entityToken]
+        // Note: when projecting, callers may omit uniqueProperty/sort keys.
+        // We perform operations on the full item shape and then cast back.
+        const itemsForOps = workingResult.items;
+        const dedupedSorted = entityTools.sort(radash.unique(itemsForOps, (i) => i[entityManager.config.entities[entityToken]
             .uniqueProperty].toString()), sortOrder);
+        workingResult.items = dedupedSorted;
         const result = {
             count: workingResult.items.length,
             items: workingResult.items,

package/dist/index.d.ts

@@ -256,6 +256,18 @@ type EntityOfToken<CC extends BaseConfigMap, ET extends EntityToken<CC>> = Exact
 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>;
+/**
+ * Normalize literals: string | readonly string[] -\> union of strings.
+ */
+type KeysFrom<K> = K extends readonly (infer E)[] ? Extract<E, string> : K extends string ? K : never;
+/**
+ * Project item shape by keys; if K is never/unknown, fall back to T.
+ */
+type Projected<T, K> = [KeysFrom<K>] extends [never] ? T : T extends object ? Pick<T, Extract<KeysFrom<K>, keyof Exactify<T>>> : T;
+/**
+ * Projected item by token — narrows EntityItemByToken by K when provided.
+ */
+type ProjectedItemByToken<CC extends BaseConfigMap, ET extends EntityToken<CC>, K = unknown> = Projected<EntityItemByToken<CC, ET>, K>;
 
 /**
  * A result returned by a {@link ShardQueryFunction | `ShardQueryFunction`} querying an individual shard.
@@ -264,15 +276,16 @@ type EntityRecordByToken<CC extends BaseConfigMap, ET extends EntityToken<CC>> =
  * @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.
+ * @typeParam K - Optional projection keys; narrows item shape when provided.
  *
  * @category EntityManager
  * @protected
  */
-interface ShardQueryResult<CC extends BaseConfigMap, ET extends EntityToken<CC>, IT extends string, CF = unknown> {
+interface ShardQueryResult<CC extends BaseConfigMap, ET extends EntityToken<CC>, IT extends string, CF = unknown, K = unknown> {
     /** The number of records returned. */
     count: number;
     /** The returned records. */
-    items: EntityItemByToken<CC, ET>[];
+    items: ProjectedItemByToken<CC, ET, K>[];
     /** The page key for the next query on this shard. */
     pageKey?: PageKeyByIndex<CC, ET, IT, CF>;
 }
@@ -290,13 +303,14 @@ interface ShardQueryResult<CC extends BaseConfigMap, ET extends EntityToken<CC>,
  * @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.
+ * @typeParam K - Optional projection keys; narrows item shape when provided.
  *
  * @category EntityManager
  * @protected
  */
-type ShardQueryFunction<CC extends BaseConfigMap, ET extends EntityToken<CC>, IT extends string, CF = unknown> = CF extends {
+type ShardQueryFunction<CC extends BaseConfigMap, ET extends EntityToken<CC>, IT extends string, CF = unknown, K = 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>>;
+} ? 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, 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>>;
 
 /**
  * Relates a specific index token to a {@link ShardQueryFunction | `ShardQueryFunction`} to be performed on that index.
@@ -309,13 +323,14 @@ type ShardQueryFunction<CC extends BaseConfigMap, ET extends EntityToken<CC>, IT
  *                 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.
+ * @typeParam K - Optional projection keys; narrows item shape when provided.
  *
  * @category EntityManager
  * @protected
  */
-type ShardQueryMap<CC extends BaseConfigMap, ET extends EntityToken<CC>, ITS extends string, CF = unknown> = CF extends {
+type ShardQueryMap<CC extends BaseConfigMap, ET extends EntityToken<CC>, ITS extends string, CF = unknown, K = 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>>;
+} ? I extends Record<string, unknown> ? Record<ITS & (keyof I & string), ShardQueryFunction<CC, ET, ITS & (keyof I & string), CF, K>> : Record<ITS, ShardQueryFunction<CC, ET, ITS, CF, K>> : Record<ITS, ShardQueryFunction<CC, ET, ITS, CF, K>>;
 /**
  * Convenience alias for ShardQueryMap that derives ITS (index token subset)
  * from a values-first captured config CC (e.g., your config literal type).
@@ -328,7 +343,7 @@ type ShardQueryMap<CC extends BaseConfigMap, ET extends EntityToken<CC>, ITS ext
  *
  * 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>;
+type ShardQueryMapByCC<CC extends BaseConfigMap, ET extends EntityToken<CC>, CCLit = unknown, K = unknown> = ShardQueryMap<CC, ET, IndexTokensFrom<CCLit>, CCLit, K>;
 /**
  * Convenience alias for ShardQueryMap that derives ITS (index token subset)
  * directly from a values-first config literal CF when it carries `indexes`.
@@ -338,7 +353,7 @@ type ShardQueryMapByCC<CC extends BaseConfigMap, ET extends EntityToken<CC>, CCL
  *
  * 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>;
+type ShardQueryMapByCF<CC extends BaseConfigMap, ET extends EntityToken<CC>, CF = unknown, K = unknown> = ShardQueryMap<CC, ET, IndexTokensOf<CF>, CF, K>;
 
 /**
  * Options passed to the {@link EntityManager.query | `EntityManager.query`} method.
@@ -347,11 +362,12 @@ type ShardQueryMapByCF<CC extends BaseConfigMap, ET extends EntityToken<CC>, CF
  * @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.
+ * @typeParam K - Optional projection keys; narrows item/sort shapes when provided.
  *
  * @category EntityManager
  * @protected
  */
-interface QueryOptions<CC extends BaseConfigMap, ET extends EntityToken<CC> = EntityToken<CC>, ITS extends string = string, CF = unknown> {
+interface QueryOptions<CC extends BaseConfigMap, ET extends EntityToken<CC> = EntityToken<CC>, ITS extends string = string, CF = unknown, K = unknown> {
     /** Identifies the entity to be queried. Key of {@link Config | `Config`} `entities`. */
     entityToken: ET;
     /**
@@ -389,11 +405,11 @@ interface QueryOptions<CC extends BaseConfigMap, ET extends EntityToken<CC> = En
      * page key, e.g. to match the same string against `firstName` and `lastName`
      * properties without performing a table scan for either.
      */
-    shardQueryMap: ShardQueryMap<CC, ET, ITS, CF>;
+    shardQueryMap: ShardQueryMap<CC, ET, ITS, CF, K>;
     /**
-     * A {@link SortOrder | `SortOrder`} object specifying the sort order of the result set. Defaults to `[]`.
+     * A {@link SortOrder | `SortOrder`} object specifying the sort order of the result set. Defaults to `[]`. Aligned with the projected item shape when K is provided.
      */
-    sortOrder?: SortOrder<EntityItemByToken<CC, ET>>;
+    sortOrder?: SortOrder<ProjectedItemByToken<CC, ET, K>>;
     /**
      * Lower limit to query shard space.
      *
@@ -430,7 +446,7 @@ interface QueryOptions<CC extends BaseConfigMap, ET extends EntityToken<CC> = En
  *
  * 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>;
+type QueryOptionsByCF<CC extends BaseConfigMap, ET extends EntityToken<CC> = EntityToken<CC>, CF = unknown, K = unknown> = QueryOptions<CC, ET, IndexTokensOf<CF>, CF, K>;
 /**
  * Convenience alias for QueryOptions that derives ITS (index token subset)
  * from a values-first captured config CC (e.g., your config literal type).
@@ -443,7 +459,7 @@ type QueryOptionsByCF<CC extends BaseConfigMap, ET extends EntityToken<CC> = Ent
  *
  * 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>;
+type QueryOptionsByCC<CCMap extends BaseConfigMap, ET extends EntityToken<CCMap> = EntityToken<CCMap>, CC = unknown, K = unknown> = QueryOptions<CCMap, ET, IndexTokensFrom<CC>, CC, K>;
 
 /**
  * A result returned by a query across multiple shards, where each shard may receive multiple page queries via a dynamically-generated {@link ShardQueryFunction | `ShardQueryFunction`}.
@@ -451,15 +467,16 @@ type QueryOptionsByCC<CCMap extends BaseConfigMap, ET extends EntityToken<CCMap>
  * @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).
+ * @typeParam K - Optional projection keys; narrows item shape when provided.
  *
  * @category EntityManager
  * @protected
  */
-interface QueryResult<CC extends BaseConfigMap, ET extends EntityToken<CC>, ITS extends string> {
+interface QueryResult<CC extends BaseConfigMap, ET extends EntityToken<CC>, ITS extends string, K = unknown> {
     /** Total number of records returned across all shards. */
     count: number;
     /** The returned records. */
-    items: EntityItemByToken<CC, ET>[];
+    items: ProjectedItemByToken<CC, ET, K>[];
     /**
      * 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.
@@ -598,7 +615,7 @@ declare class EntityManager<CC extends BaseConfigMap> {
      *
      * @protected
      */
-    query<ET extends EntityToken<CC>, ITS extends string, CF = unknown>(options: QueryOptions<CC, ET, ITS, CF>): Promise<QueryResult<CC, ET, ITS>>;
+    query<ET extends EntityToken<CC>, ITS extends string, CF = unknown, K = unknown>(options: QueryOptions<CC, ET, ITS, CF, K>): Promise<QueryResult<CC, ET, ITS, K>>;
 }
 
 /**
@@ -783,10 +800,11 @@ type QueryBuilderQueryOptions<CC extends BaseConfigMap, CF = unknown> = Omit<Que
  * @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.
+ * @typeParam K - Optional projection keys; narrows item shape when provided.
  *
  * @category QueryBuilder
  */
-declare abstract class BaseQueryBuilder<CC extends BaseConfigMap, EntityClient extends BaseEntityClient<CC>, IndexParams, ET extends EntityToken<CC> = EntityToken<CC>, ITS extends string = string, CF = unknown> {
+declare abstract class BaseQueryBuilder<CC extends BaseConfigMap, EntityClient extends BaseEntityClient<CC>, IndexParams, ET extends EntityToken<CC> = EntityToken<CC>, ITS extends string = string, CF = unknown, K = unknown> {
     /** {@link BaseEntityClient | `EntityClient`} instance. */
     readonly entityClient: EntityClient;
     /** Entity token. */
@@ -803,15 +821,15 @@ declare abstract class BaseQueryBuilder<CC extends BaseConfigMap, EntityClient e
     readonly indexParamsMap: Record<ITS, IndexParams>;
     /** BaseQueryBuilder constructor. */
     constructor(options: BaseQueryBuilderOptions<CC, EntityClient>);
-    protected abstract getShardQueryFunction(indexToken: ITS): ShardQueryFunction<CC, ET, ITS, CF>;
+    protected abstract getShardQueryFunction(indexToken: ITS): ShardQueryFunction<CC, ET, ITS, CF, K>;
     /**
      * Builds a {@link ShardQueryMap | `ShardQueryMap`} object.
      *
      * @returns - The {@link ShardQueryMap | `ShardQueryMap`} object.
      */
-    build(): ShardQueryMap<CC, ET, ITS, CF>;
-    query(options: QueryBuilderQueryOptions<CC, CF>): Promise<QueryResult<CC, ET, ITS>>;
+    build(): ShardQueryMap<CC, ET, ITS, CF, K>;
+    query(options: QueryBuilderQueryOptions<CC, CF>): Promise<QueryResult<CC, ET, ITS, K>>;
 }
 
 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 };
+export type { BaseConfigMap, BaseEntityClientOptions, BaseQueryBuilderOptions, CapturedConfigMapFrom, Config, ConfigInput, ConfigMap, EntitiesFromSchema, EntityItem, EntityItemByToken, EntityKey, EntityOfToken, EntityRecord, EntityRecordByToken, EntityToken, HasIndexFor, HashKeyFrom, IndexComponentTokens, IndexHashKeyOf, IndexRangeKeyOf, IndexTokensFrom, IndexTokensOf, KeysFrom, PageKey, PageKeyByIndex, ParsedConfig, Projected, ProjectedItemByToken, QueryBuilderQueryOptions, QueryOptions, QueryOptionsByCC, QueryOptionsByCF, QueryResult, RangeKeyFrom, ShardBump, ShardQueryFunction, ShardQueryMap, ShardQueryMapByCC, ShardQueryMapByCF, ShardQueryResult, ShardedKeysFrom, TranscodedPropertiesFrom, UnshardedKeysFrom, ValidateConfigMap };

package/dist/mjs/BaseQueryBuilder/BaseQueryBuilder.js

@@ -7,6 +7,7 @@ import { mapValues } from 'radash';
  * @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.
+ * @typeParam K - Optional projection keys; narrows item shape when provided.
  *
  * @category QueryBuilder
  */

package/dist/mjs/EntityManager/EntityManager.js

@@ -28,7 +28,14 @@ class EntityManager {
      */
     constructor(config, logger = console) {
         _EntityManager_config.set(this, void 0);
-        __classPrivateFieldSet(this, _EntityManager_config, configSchema.parse(config), "f");
+        // Accept a compile-time-only `entitiesSchema` key on values-first configs.
+        // We strip it here so the same literal config can be used with either the
+        // factory or the direct constructor without tripping Zod's strict parser.
+        //
+        // This keeps runtime semantics unchanged and avoids widening ParsedConfig.
+        const cfgWithOptionalES = config;
+        const { entitiesSchema: _ignored, ...configForParse } = cfgWithOptionalES;
+        __classPrivateFieldSet(this, _EntityManager_config, configSchema.parse(configForParse), "f");
         this.logger = logger;
     }
     /**

package/dist/mjs/EntityManager/query.js

@@ -26,8 +26,10 @@ const { compressToEncodedURIComponent, decompressFromEncodedURIComponent } = lzS
  */
 async function query(entityManager, options) {
     try {
-        // Get defaults.
-        const { defaultLimit, defaultPageSize } = entityManager.config.entities[options.entityToken];
+        // Get defaults (avoid unsafe destructuring on generic access).
+        const entityDefaults = entityManager.config.entities[options.entityToken];
+        const defaultLimit = entityDefaults.defaultLimit;
+        const defaultPageSize = entityDefaults.defaultPageSize;
         // Extract params.
         const { entityToken, limit = defaultLimit, item, pageKeyMap, pageSize = defaultPageSize, shardQueryMap, sortOrder = [], timestampFrom = 0, timestampTo = Date.now(), throttle = entityManager.config.throttle, } = options;
         // Validate params.
@@ -96,8 +98,12 @@ async function query(entityManager, options) {
                 break;
         } while (workingResult.items.length < limit);
         // Dedupe & sort working result.
-        workingResult.items = sort(unique(workingResult.items, (i) => i[entityManager.config.entities[entityToken]
+        // Note: when projecting, callers may omit uniqueProperty/sort keys.
+        // We perform operations on the full item shape and then cast back.
+        const itemsForOps = workingResult.items;
+        const dedupedSorted = sort(unique(itemsForOps, (i) => i[entityManager.config.entities[entityToken]
             .uniqueProperty].toString()), sortOrder);
+        workingResult.items = dedupedSorted;
         const result = {
             count: workingResult.items.length,
             items: workingResult.items,

package/package.json

@@ -128,5 +128,5 @@
   },
   "type": "module",
   "types": "dist/index.d.ts",
-  "version": "7.0.1"
+  "version": "7.1.1"
 }