@karmaniverous/entity-manager 7.2.0 → 7.3.1

package/dist/cjs/EntityManager/EntityManager.js

@@ -15,6 +15,10 @@ var _EntityManager_config;
  * query strategy to NoSql data.
  *
  * @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`}.
+ * @typeParam CF - Values-first config literal type captured at construction
+ *                 time (phantom generic; type-only). This is used by downstream
+ *                 adapters to infer index-token unions (ITS) and per-index page
+ *                 key shapes.
  *
  * @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.
@@ -87,19 +91,11 @@ class EntityManager {
         }
         return removeKeys.removeKeys(this, entityToken, i);
     }
-    /**
-     * Find an index token in a {@link Config | `Config`} object based on the index `hashKey` and `rangeKey`.
-     *
-     * @param hashKeyToken - Index hash key.
-     * @param rangeKeyToken - Index range key.
-     * @param suppressError - Suppress error if no match found.
-     *
-     * @returns  Index token if found.
-     *
-     * @throws `Error` if no match found and `suppressError` is not `true`.
-     */
     findIndexToken(hashKeyToken, rangeKeyToken, suppressError) {
-        return findIndexToken.findIndexToken(this, hashKeyToken, rangeKeyToken, suppressError);
+        // Dispatch with a literal to satisfy overload selection.
+        return suppressError === true
+            ? findIndexToken.findIndexToken(this, hashKeyToken, rangeKeyToken, true)
+            : findIndexToken.findIndexToken(this, hashKeyToken, rangeKeyToken, false);
     }
     /**
      * Query a database entity across shards in a provider-generic fashion.

package/dist/cjs/EntityManager/ParsedConfig.js

@@ -227,8 +227,19 @@ const configSchema = zod.z
                     path: ['generatedProperties', 'unsharded', property],
                 });
     // Validate indexes.
-    // TODO: Vaidate no two indexes have the same hashKey & rangeKey.
+    // Validate no two indexes have the same hashKey & rangeKey.
+    const seenIndexPairs = new Set();
     for (const [indexKey, { hashKey, rangeKey, projections }] of Object.entries(data.indexes)) {
+        const pairSig = `${hashKey}|${rangeKey}`;
+        if (seenIndexPairs.has(pairSig)) {
+            ctx.addIssue({
+                code: 'custom',
+                message: `duplicate index hashKey/rangeKey pair`,
+                path: ['indexes', indexKey],
+            });
+        }
+        else
+            seenIndexPairs.add(pairSig);
         // Validate hash key is sharded.
         if (![data.hashKey, ...shardedKeys].includes(hashKey)) {
             ctx.addIssue({

package/dist/cjs/EntityManager/createEntityManager.js

@@ -11,6 +11,10 @@ var EntityManager = require('./EntityManager.js');
  *                 `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.
+ *
+ * @returns An {@link EntityManager | `EntityManager`} instance whose type
+ *          captures CF from the single values-first config literal ({@link ConfigInput | `ConfigInput`})
+ *          as the second generic parameter (phantom; type-only).
  */
 function createEntityManager(config, logger = console) {
     // Cast to the existing Config<C> shape for runtime parsing; Zod validation

package/dist/cjs/EntityManager/findIndexToken.js

@@ -1,19 +1,8 @@
 'use strict';
 
-/**
- * Find an index token in a {@link Config | `Config`} object based on the index `hashKey` and `rangeKey`.
- *
- * @param entityManager - {@link EntityManager | `EntityManager`} instance.
- * @param hashKeyToken - Index hash key.
- * @param rangeKeyToken - Index range key.
- * @param suppressError - Suppress error if no match found.
- *
- * @returns  Index token if found.
- *
- * @throws `Error` if no match found and `suppressError` is not `true`.
- */
 function findIndexToken(entityManager, hashKeyToken, rangeKeyToken, suppressError) {
-    const indexToken = Object.entries(entityManager.config.indexes).find(([, index]) => index.hashKey === hashKeyToken && index.rangeKey === rangeKeyToken)?.[0];
+    const indexToken = (Object.entries(entityManager.config.indexes).find(([, index]) => index.hashKey === hashKeyToken &&
+        index.rangeKey === rangeKeyToken)?.[0] ?? undefined);
     if (!indexToken && !suppressError)
         throw new Error(`No index token found for hashKey '${hashKeyToken}' & rangeKey '${rangeKeyToken}'.`);
     return indexToken;

package/dist/index.d.ts

@@ -148,54 +148,6 @@ type EntityKey<CC extends BaseConfigMap> = Record<CC['HashKey'] | CC['RangeKey']
  */
 type EntityToken<CC extends BaseConfigMap> = keyof Exactify<CC['EntityMap']> & string;
 
-declare const configSchema: z$1.ZodObject<{
-    entities: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodRecord<z$1.ZodString, z$1.ZodObject<{
-        defaultLimit: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodNumber>>;
-        defaultPageSize: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodNumber>>;
-        shardBumps: z$1.ZodPipe<z$1.ZodDefault<z$1.ZodOptional<z$1.ZodArray<z$1.ZodObject<{
-            timestamp: z$1.ZodNumber;
-            charBits: z$1.ZodNumber;
-            chars: z$1.ZodNumber;
-        }, z$1.core.$strict>>>>, z$1.ZodTransform<{
-            timestamp: number;
-            charBits: number;
-            chars: number;
-        }[], {
-            timestamp: number;
-            charBits: number;
-            chars: number;
-        }[]>>;
-        timestampProperty: z$1.ZodString;
-        uniqueProperty: z$1.ZodString;
-    }, z$1.core.$strict>>>>;
-    generatedProperties: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodObject<{
-        sharded: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodRecord<z$1.ZodString, z$1.ZodArray<z$1.ZodString>>>>;
-        unsharded: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodRecord<z$1.ZodString, z$1.ZodArray<z$1.ZodString>>>>;
-    }, z$1.core.$strip>>>;
-    hashKey: z$1.ZodString;
-    indexes: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodRecord<z$1.ZodString, z$1.ZodObject<{
-        hashKey: z$1.ZodString;
-        rangeKey: z$1.ZodString;
-        projections: z$1.ZodOptional<z$1.ZodArray<z$1.ZodString>>;
-    }, z$1.core.$strip>>>>;
-    generatedKeyDelimiter: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodString>>;
-    generatedValueDelimiter: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodString>>;
-    propertyTranscodes: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodRecord<z$1.ZodString, z$1.ZodString>>>;
-    rangeKey: z$1.ZodString;
-    shardKeyDelimiter: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodString>>;
-    throttle: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodNumber>>;
-    transcodes: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodRecord<z$1.ZodString, z$1.ZodObject<{
-        encode: z$1.ZodCustom<unknown, unknown>;
-        decode: z$1.ZodCustom<unknown, unknown>;
-    }, z$1.core.$strict>>>>;
-}, z$1.core.$strict>;
-/**
- * Simplified type taken on by a {@link Config | `Config`} object after parsing in the {@link EntityManager | `EntityManager`} constructor.
- *
- * @category EntityManager
- */
-type ParsedConfig = z$1.infer<typeof configSchema>;
-
 /**
  * A partial {@link EntityItem | `EntityItem`} restricted to keys defined in `C`.
  *
@@ -244,6 +196,54 @@ type IndexComponentTokens<CC extends BaseConfigMap, CF, IT extends string> = Has
  */
 type PageKeyByIndex<CC extends BaseConfigMap, ET extends EntityToken<CC>, IT extends string = string, CF = unknown> = Pick<EntityItem<CC>, IndexComponentTokens<CC, CF, IT>>;
 
+declare const configSchema: z$1.ZodObject<{
+    entities: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodRecord<z$1.ZodString, z$1.ZodObject<{
+        defaultLimit: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodNumber>>;
+        defaultPageSize: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodNumber>>;
+        shardBumps: z$1.ZodPipe<z$1.ZodDefault<z$1.ZodOptional<z$1.ZodArray<z$1.ZodObject<{
+            timestamp: z$1.ZodNumber;
+            charBits: z$1.ZodNumber;
+            chars: z$1.ZodNumber;
+        }, z$1.core.$strict>>>>, z$1.ZodTransform<{
+            timestamp: number;
+            charBits: number;
+            chars: number;
+        }[], {
+            timestamp: number;
+            charBits: number;
+            chars: number;
+        }[]>>;
+        timestampProperty: z$1.ZodString;
+        uniqueProperty: z$1.ZodString;
+    }, z$1.core.$strict>>>>;
+    generatedProperties: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodObject<{
+        sharded: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodRecord<z$1.ZodString, z$1.ZodArray<z$1.ZodString>>>>;
+        unsharded: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodRecord<z$1.ZodString, z$1.ZodArray<z$1.ZodString>>>>;
+    }, z$1.core.$strip>>>;
+    hashKey: z$1.ZodString;
+    indexes: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodRecord<z$1.ZodString, z$1.ZodObject<{
+        hashKey: z$1.ZodString;
+        rangeKey: z$1.ZodString;
+        projections: z$1.ZodOptional<z$1.ZodArray<z$1.ZodString>>;
+    }, z$1.core.$strip>>>>;
+    generatedKeyDelimiter: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodString>>;
+    generatedValueDelimiter: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodString>>;
+    propertyTranscodes: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodRecord<z$1.ZodString, z$1.ZodString>>>;
+    rangeKey: z$1.ZodString;
+    shardKeyDelimiter: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodString>>;
+    throttle: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodNumber>>;
+    transcodes: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodRecord<z$1.ZodString, z$1.ZodObject<{
+        encode: z$1.ZodCustom<unknown, unknown>;
+        decode: z$1.ZodCustom<unknown, unknown>;
+    }, z$1.core.$strict>>>>;
+}, z$1.core.$strict>;
+/**
+ * Simplified type taken on by a {@link Config | `Config`} object after parsing in the {@link EntityManager | `EntityManager`} constructor.
+ *
+ * @category EntityManager
+ */
+type ParsedConfig = z$1.infer<typeof configSchema>;
+
 /** EntityOfToken — resolves the concrete entity shape for a specific entity token. */
 type EntityOfToken<CC extends BaseConfigMap, ET extends EntityToken<CC>> = Exactify<CC['EntityMap']>[ET];
 /**
@@ -489,13 +489,17 @@ interface QueryResult<CC extends BaseConfigMap, ET extends EntityToken<CC>, ITS
  * query strategy to NoSql data.
  *
  * @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`}.
+ * @typeParam CF - Values-first config literal type captured at construction
+ *                 time (phantom generic; type-only). This is used by downstream
+ *                 adapters to infer index-token unions (ITS) and per-index page
+ *                 key shapes.
  *
  * @remarks
  * While the {@link EntityManager.query | `query`} method is `public`, normally it should not be called directly. The `query` method is used by a platform-specific {@link BaseQueryBuilder.query | `QueryBuilder.query`} method to provide a fluent query API.
  *
  * @category EntityManager
  */
-declare class EntityManager<CC extends BaseConfigMap> {
+declare class EntityManager<CC extends BaseConfigMap, CF = unknown> {
     #private;
     /** Logger object (defaults to `console`, must support `debug` & `error` methods). */
     readonly logger: Pick<Console, 'debug' | 'error'>;
@@ -582,17 +586,18 @@ declare class EntityManager<CC extends BaseConfigMap> {
      */
     removeKeys<ET extends EntityToken<CC>>(entityToken: ET, items: EntityRecordByToken<CC, ET>[]): EntityItemByToken<CC, ET>[];
     /**
-     * Find an index token in a {@link Config | `Config`} object based on the index `hashKey` and `rangeKey`.
+     * Find an index token based on the configured hash and range key tokens.
      *
-     * @param hashKeyToken - Index hash key.
-     * @param rangeKeyToken - Index range key.
-     * @param suppressError - Suppress error if no match found.
+     * @param hashKeyToken - Index hash key token (global hashKey or a sharded generated key).
+     * @param rangeKeyToken - Index range key token (global rangeKey, unsharded generated key, or a transcodable scalar).
+     * @param suppressError - When false (default), throws if no match; when true, returns undefined instead.
      *
-     * @returns  Index token if found.
+     * @returns A configured index token (narrowed to the CF.indexes key union) or undefined when allowed.
      *
-     * @throws `Error` if no match found and `suppressError` is not `true`.
+     * @throws `Error` if no match is found and `suppressError` is not `true`.
      */
-    findIndexToken(hashKeyToken: string, rangeKeyToken: string, suppressError?: boolean): string | undefined;
+    findIndexToken(hashKeyToken: CC['HashKey'] | CC['ShardedKeys'], rangeKeyToken: CC['RangeKey'] | CC['UnshardedKeys'] | CC['TranscodedProperties'], suppressError?: false): IndexTokensOf<CF>;
+    findIndexToken(hashKeyToken: CC['HashKey'] | CC['ShardedKeys'], rangeKeyToken: CC['RangeKey'] | CC['UnshardedKeys'] | CC['TranscodedProperties'], suppressError: true): IndexTokensOf<CF> | undefined;
     /**
      * Query a database entity across shards in a provider-generic fashion.
      *
@@ -712,8 +717,12 @@ type CapturedConfigMapFrom<CC, EM extends EntityMap> = {
  *                 `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.
+ *
+ * @returns An {@link EntityManager | `EntityManager`} instance whose type
+ *          captures CF from the single values-first config literal ({@link ConfigInput | `ConfigInput`})
+ *          as the second generic parameter (phantom; type-only).
  */
-declare function createEntityManager<const CC extends ConfigInput, EM extends EntityMap = EntitiesFromSchema<CC>>(config: CC, logger?: Pick<Console, 'debug' | 'error'>): EntityManager<CapturedConfigMapFrom<CC, EM>>;
+declare function createEntityManager<const CC extends ConfigInput, EM extends EntityMap = EntitiesFromSchema<CC>>(config: CC, logger?: Pick<Console, 'debug' | 'error'>): EntityManager<CapturedConfigMapFrom<CC, EM>, CC>;
 
 /**
  * Database-facing record type from a {@link BaseConfigMap | `ConfigMap`} with required hash & range keys.

package/dist/mjs/EntityManager/EntityManager.js

@@ -13,6 +13,10 @@ var _EntityManager_config;
  * query strategy to NoSql data.
  *
  * @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`}.
+ * @typeParam CF - Values-first config literal type captured at construction
+ *                 time (phantom generic; type-only). This is used by downstream
+ *                 adapters to infer index-token unions (ITS) and per-index page
+ *                 key shapes.
  *
  * @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.
@@ -85,19 +89,11 @@ class EntityManager {
         }
         return removeKeys(this, entityToken, i);
     }
-    /**
-     * Find an index token in a {@link Config | `Config`} object based on the index `hashKey` and `rangeKey`.
-     *
-     * @param hashKeyToken - Index hash key.
-     * @param rangeKeyToken - Index range key.
-     * @param suppressError - Suppress error if no match found.
-     *
-     * @returns  Index token if found.
-     *
-     * @throws `Error` if no match found and `suppressError` is not `true`.
-     */
     findIndexToken(hashKeyToken, rangeKeyToken, suppressError) {
-        return findIndexToken(this, hashKeyToken, rangeKeyToken, suppressError);
+        // Dispatch with a literal to satisfy overload selection.
+        return suppressError === true
+            ? findIndexToken(this, hashKeyToken, rangeKeyToken, true)
+            : findIndexToken(this, hashKeyToken, rangeKeyToken, false);
     }
     /**
      * Query a database entity across shards in a provider-generic fashion.

package/dist/mjs/EntityManager/ParsedConfig.js

@@ -225,8 +225,19 @@ const configSchema = z
                     path: ['generatedProperties', 'unsharded', property],
                 });
     // Validate indexes.
-    // TODO: Vaidate no two indexes have the same hashKey & rangeKey.
+    // Validate no two indexes have the same hashKey & rangeKey.
+    const seenIndexPairs = new Set();
     for (const [indexKey, { hashKey, rangeKey, projections }] of Object.entries(data.indexes)) {
+        const pairSig = `${hashKey}|${rangeKey}`;
+        if (seenIndexPairs.has(pairSig)) {
+            ctx.addIssue({
+                code: 'custom',
+                message: `duplicate index hashKey/rangeKey pair`,
+                path: ['indexes', indexKey],
+            });
+        }
+        else
+            seenIndexPairs.add(pairSig);
         // Validate hash key is sharded.
         if (![data.hashKey, ...shardedKeys].includes(hashKey)) {
             ctx.addIssue({

package/dist/mjs/EntityManager/createEntityManager.js

@@ -9,6 +9,10 @@ import { EntityManager } from './EntityManager.js';
  *                 `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.
+ *
+ * @returns An {@link EntityManager | `EntityManager`} instance whose type
+ *          captures CF from the single values-first config literal ({@link ConfigInput | `ConfigInput`})
+ *          as the second generic parameter (phantom; type-only).
  */
 function createEntityManager(config, logger = console) {
     // Cast to the existing Config<C> shape for runtime parsing; Zod validation

package/dist/mjs/EntityManager/findIndexToken.js

@@ -1,17 +1,6 @@
-/**
- * Find an index token in a {@link Config | `Config`} object based on the index `hashKey` and `rangeKey`.
- *
- * @param entityManager - {@link EntityManager | `EntityManager`} instance.
- * @param hashKeyToken - Index hash key.
- * @param rangeKeyToken - Index range key.
- * @param suppressError - Suppress error if no match found.
- *
- * @returns  Index token if found.
- *
- * @throws `Error` if no match found and `suppressError` is not `true`.
- */
 function findIndexToken(entityManager, hashKeyToken, rangeKeyToken, suppressError) {
-    const indexToken = Object.entries(entityManager.config.indexes).find(([, index]) => index.hashKey === hashKeyToken && index.rangeKey === rangeKeyToken)?.[0];
+    const indexToken = (Object.entries(entityManager.config.indexes).find(([, index]) => index.hashKey === hashKeyToken &&
+        index.rangeKey === rangeKeyToken)?.[0] ?? undefined);
     if (!indexToken && !suppressError)
         throw new Error(`No index token found for hashKey '${hashKeyToken}' & rangeKey '${rangeKeyToken}'.`);
     return indexToken;

package/package.json

@@ -1,5 +1,11 @@
 {
   "author": "Jason Williscroft",
+  "auto-changelog": {
+    "commitLimit": false,
+    "hideCredit": true,
+    "output": "CHANGELOG.md",
+    "unreleased": true
+  },
   "bugs": {
     "url": "https://github.com/karmaniverous/entity-manager/issues"
   },
@@ -81,7 +87,7 @@
   },
   "release-it": {
     "git": {
-      "changelog": "npx auto-changelog --stdout --commit-limit false --unreleased --template https://raw.githubusercontent.com/release-it/release-it/main/templates/changelog-compact.hbs",
+      "changelog": "npx auto-changelog --stdout --unreleased --template https://raw.githubusercontent.com/release-it/release-it/main/templates/changelog-compact.hbs",
       "commitMessage": "chore: release v${version}",
       "requireBranch": "main"
     },
@@ -128,5 +134,5 @@
   },
   "type": "module",
   "types": "dist/index.d.ts",
-  "version": "7.2.0"
+  "version": "7.3.1"
 }