@karmaniverous/entity-manager 7.0.1 → 7.1.0

package/README.md

@@ -1,7 +1,7 @@
-# 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
+
+[![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:
@@ -32,6 +32,12 @@ npm install --save-dev @karmaniverous/mock-db
 - 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 (CF/CC helpers):
+  - CF: drive index token unions and page‑key narrowing directly from a values‑first config literal (`QueryOptionsByCF`, `ShardQueryMapByCF`).
+  - CC: 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):
@@ -41,14 +47,18 @@ npm install --save-dev @karmaniverous/mock-db
   - 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';
+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
+  userId: z.string(), // unique property
+  created: z.number(), // timestamp property
   updated: z.number().optional(),
   firstNameCanonical: z.string(),
   lastNameCanonical: z.string(),
@@ -137,16 +147,24 @@ import type {
 const cf = {
   indexes: {
     firstName: { hashKey: 'hashKey2', rangeKey: 'firstNameRK' },
-    lastName:  { hashKey: 'hashKey2', rangeKey: 'lastNameRK'  },
+    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 });
+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> = {
@@ -182,23 +200,35 @@ import type {
 const cc = {
   indexes: {
     firstName: { hashKey: 'hashKey2', rangeKey: 'firstNameRK' },
-    lastName:  { hashKey: 'hashKey2', rangeKey: 'lastNameRK'  },
+    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 });
+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 optionsCC: QueryOptionsByCC<MyConfigMap, 'user', CC> = {
+  entityToken: 'user',
+  item: {},
+  shardQueryMap: shardQueryMapCC,
+};
 const resultCC = await manager.query(optionsCC);
 ```
 
@@ -206,7 +236,97 @@ 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()`).
@@ -216,10 +336,16 @@ Notes:
 
 ```ts
 // ESM
-import { createEntityManager, defaultTranscodes } from '@karmaniverous/entity-manager';
+import {
+  createEntityManager,
+  defaultTranscodes,
+} from '@karmaniverous/entity-manager';
 
 // CJS
-const { createEntityManager, defaultTranscodes } = require('@karmaniverous/entity-manager');
+const {
+  createEntityManager,
+  defaultTranscodes,
+} = require('@karmaniverous/entity-manager');
 ```
 
 ## Logging
@@ -243,12 +369,17 @@ const manager = createEntityManager(config, logger);
   - `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
+- build: rollup outputs ESM/CJS + .d.ts
+- test: vitest with coverage
 - lint: ESLint (type‑aware) + Prettier
 - docs: TypeDoc
 - typecheck: tsc + tsd (type‑level tests)
@@ -259,4 +390,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/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/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/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.0"
 }