@karmaniverous/entity-manager 7.3.4 → 8.0.0

package/README.md

@@ -363,7 +363,11 @@ const manager = createEntityManager(config, logger);
   - `createEntityManager(config, logger?)`
   - `ConfigInput` (values‑first), `CapturedConfigMapFrom`, `EntitiesFromSchema`
 - Token aware
-  - `EntityToken<CC>`, `EntityItemByToken<CC, ET>`, `EntityRecordByToken<CC, ET>`
+  - `EntityToken<CC>`
+  - `EntityItem<CC, ET>` — strict domain (full), includes optional key/token properties
+  - `EntityItemPartial<CC, ET, K>` — projected/seed domain; required keys when K provided, permissive partial when K omitted
+  - `EntityRecord<CC, ET>` — DB record (required keys) + partial domain fields
+  - `EntityRecordPartial<CC, ET, K>` — projected DB record
 - Index aware (values‑first config literal, “CF” channel)
   - `PageKeyByIndex<CC, ET, IT, CF>`
   - `ShardQueryFunction<CC, ET, IT, CF>`, `ShardQueryMap<CC, ET, ITS, CF>`
@@ -373,6 +377,8 @@ const manager = createEntityManager(config, logger);
   - `KeysFrom<K>`
   - `Projected<T, K>`
   - `ProjectedItemByToken<CC, ET, K>`
+ - Advanced (storage shapes; exported for reference and TypeDoc)
+   - `StorageItem<CC>`, `StorageRecord<CC>`
 
 See the full API: https://docs.karmanivero.us/entity-manager
 

package/dist/cjs/EntityManager/EntityManager.js

@@ -64,7 +64,7 @@ class EntityManager {
      * Encode a generated property value. Returns a string or undefined if atomicity requirement of sharded properties not met.
      *
      * @param property - {@link Config | Config} `generatedProperties` key.
-     * @param item - {@link EntityItem | `EntityItem`} object.
+     * @param item - {@link StorageItem | `StorageItem`} object.
      *
      * @returns Encoded generated property value.
      *
@@ -87,9 +87,11 @@ class EntityManager {
     }
     removeKeys(entityToken, i) {
         if (Array.isArray(i)) {
-            return i.map((item) => removeKeys.removeKeys(this, entityToken, item));
+            const out = i.map((item) => removeKeys.removeKeys(this, entityToken, item));
+            return out;
         }
-        return removeKeys.removeKeys(this, entityToken, i);
+        const out = removeKeys.removeKeys(this, entityToken, i);
+        return out;
     }
     findIndexToken(hashKeyToken, rangeKeyToken, suppressError) {
         // Dispatch with a literal to satisfy overload selection.
@@ -120,7 +122,8 @@ class EntityManager {
      * @protected
      */
     async query(options) {
-        return await query.query(this, options);
+        const result = await query.query(this, options);
+        return result;
     }
 }
 _EntityManager_config = new WeakMap();

package/dist/cjs/EntityManager/encodeGeneratedProperty.js

@@ -8,7 +8,7 @@ var validateGeneratedProperty = require('./validateGeneratedProperty.js');
  *
  * @param entityManager - {@link EntityManager | `EntityManager`} instance.
  * @param property - {@link Config.generatedProperties | Generated property} key.
- * @param item - {@link EntityItem | `EntityItem`} object.
+ * @param item - {@link StorageItem | `StorageItem`} object.
  *
  * @returns Encoded generated property value.
  *
@@ -21,7 +21,10 @@ function encodeGeneratedProperty(entityManager, property, item) {
         const sharded = property in entityManager.config.generatedProperties.sharded;
         const elements = entityManager.config.generatedProperties[sharded ? 'sharded' : 'unsharded'][property];
         // Map elements to [element, value] pairs.
-        const elementMap = elements.map((element) => [element, item[element]]);
+        const elementMap = elements.map((element) => [
+            element,
+            item[element],
+        ]);
         // Return undefined if sharded & atomicity requirement fails.
         if (sharded && elementMap.some(([, value]) => entityTools.isNil(value)))
             return;

package/dist/cjs/EntityManager/getHashKeySpace.js

@@ -52,7 +52,7 @@ function getHashKeySpace(entityManager, entityToken, hashKeyToken, item, timesta
             // Map shard keys to hash keys.
             .map((shardKey) => {
             // Calculate record hash key.
-            let hashKey = `${entityToken}${entityManager.config.shardKeyDelimiter}${shardKey}`;
+            let hashKey = `${String(entityToken)}${entityManager.config.shardKeyDelimiter}${shardKey}`;
             // If hash key space basis is a different property, encode it.
             if (hashKeyToken !== entityManager.config.hashKey)
                 hashKey = encodeGeneratedProperty.encodeGeneratedProperty(entityManager, hashKeyToken, {

package/dist/cjs/EntityManager/getPrimaryKey.js

@@ -27,11 +27,14 @@ var updateItemRangeKey = require('./updateItemRangeKey.js');
 function getPrimaryKey(entityManager, entityToken, item, overwrite = false) {
     const { hashKey, rangeKey } = entityManager.config;
     // If both keys are present and we're not overwriting, return the exact pair.
-    if (!overwrite && item[hashKey] && item[rangeKey]) {
+    const rec = item;
+    const hk = hashKey;
+    const rk = rangeKey;
+    if (!overwrite && rec[hk] && rec[rk]) {
         return [
             {
-                [hashKey]: item[hashKey],
-                [rangeKey]: item[rangeKey],
+                [hashKey]: rec[hk],
+                [rangeKey]: rec[rk],
             },
         ];
     }
@@ -40,6 +43,7 @@ function getPrimaryKey(entityManager, entityToken, item, overwrite = false) {
     // If timestamp present, compute exactly one hash key and return single pair.
     const tsProp = entityManager.config.entities[entityToken].timestampProperty;
     if (withRangeKey[tsProp] !== undefined) {
+        // Note: use StorageItem here
         const withHashKey = updateItemHashKey.updateItemHashKey(entityManager, entityToken, withRangeKey, true);
         return [
             {
@@ -51,12 +55,15 @@ function getPrimaryKey(entityManager, entityToken, item, overwrite = false) {
     // No timestamp: enumerate hash-key space across all shard bumps (0..Infinity).
     const hashKeys = getHashKeySpace.getHashKeySpace(entityManager, entityToken, hashKey, withRangeKey, 0, Infinity);
     // Map to keys and de-duplicate.
-    const rk = withRangeKey[rangeKey];
+    const rangeKeyValue = withRangeKey[rangeKey];
     const seen = new Set();
     const keys = hashKeys
         .map((hk) => {
-        const key = { [hashKey]: hk, [rangeKey]: rk };
-        const sig = `${hk}|${rk}`;
+        const key = {
+            [hashKey]: hk,
+            [rangeKey]: rangeKeyValue,
+        };
+        const sig = `${hk}|${rangeKeyValue}`;
         if (seen.has(sig))
             return undefined;
         seen.add(sig);

package/dist/cjs/EntityManager/removeKeys.js

@@ -25,14 +25,21 @@ function removeKeys(entityManager, entityToken, item) {
             ...Object.keys(sharded),
             ...Object.keys(unsharded),
         ]);
-        // Create a shallow copy of item omitting the keys above (no delete operator).
-        const newItem = Object.fromEntries(Object.entries(item).filter(([key]) => !keysToStrip.has(key)));
+        // Create a shallow copy of item omitting the keys above (no delete operator),
+        // avoiding any-typed assignments.
+        const source = item;
+        const newItemObj = {};
+        for (const [key, value] of Object.entries(source)) {
+            if (!keysToStrip.has(key)) {
+                newItemObj[key] = value;
+            }
+        }
         entityManager.logger.debug('stripped entity item generated properties', {
             entityToken,
             item,
-            newItem,
+            newItem: newItemObj,
         });
-        return newItem;
+        return newItemObj;
     }
     catch (error) {
         if (error instanceof Error)

package/dist/cjs/EntityManager/updateItemHashKey.js

@@ -6,11 +6,11 @@ var getShardBump = require('./getShardBump.js');
 var validateEntityToken = require('./validateEntityToken.js');
 
 /**
- * Update the hash key on an partial {@link EntityItem | `EntityItem`} object.
+ * Update the hash key on an {@link EntityItemPartial | `EntityItemPartial`} object.
  *
  * @param entityManager - {@link EntityManager | `EntityManager`} instance.
  * @param entityToken - {@link Config.entities | `this.config.entities`} key.
- * @param item - {@link EntityItem | `EntityItem`} object.
+ * @param item - {@link StorageItem | `StorageItem`} object.
  * @param overwrite - Overwrite existing {@link ConfigKeys.hashKey | `this.config.hashKey`} property value (default `false`).
  *
  * @returns Shallow clone of `item` with updated hash key.
@@ -32,13 +32,14 @@ function updateItemHashKey(entityManager, entityToken, item, overwrite = false)
             return { ...item };
         }
         // Get item timestamp property & validate.
-        const timestamp = item[entityManager.config.entities[entityToken]
-            .timestampProperty];
+        const tsProp = entityManager.config.entities[entityToken]
+            .timestampProperty;
+        const timestamp = item[tsProp];
         if (entityTools.isNil(timestamp))
             throw new Error(`missing item timestamp property`);
         // Find first entity sharding bump before timestamp.
         const { charBits, chars } = getShardBump.getShardBump(entityManager, entityToken, timestamp);
-        let hashKey = `${entityToken}${entityManager.config.shardKeyDelimiter}`;
+        let hashKey = `${String(entityToken)}${entityManager.config.shardKeyDelimiter}`;
         if (chars) {
             // Radix is the numerical base of the shardKey.
             const radix = 2 ** charBits;
@@ -46,8 +47,9 @@ function updateItemHashKey(entityManager, entityToken, item, overwrite = false)
             // all placeholders are utilized (e.g., chars=2, charBits=2 => 16 combos).
             const space = radix ** chars;
             // Get item unique property & validate.
-            const uniqueId = item[entityManager.config.entities[entityToken]
-                .uniqueProperty];
+            const upProp = entityManager.config.entities[entityToken]
+                .uniqueProperty;
+            const uniqueId = item[upProp];
             if (entityTools.isNil(uniqueId))
                 throw new Error(`missing item unique property`);
             hashKey += (stringHash(uniqueId) % space)

package/dist/cjs/EntityManager/updateItemRangeKey.js

@@ -4,11 +4,11 @@ var entityTools = require('@karmaniverous/entity-tools');
 var validateEntityToken = require('./validateEntityToken.js');
 
 /**
- * Update the range key on an {@link EntityItem | `EntityItem`} object.
+ * Update the range key on an {@link EntityItemPartial | `EntityItemPartial`} object.
  *
  * @param entityManager - {@link EntityManager | `EntityManager`} instance.
  * @param entityToken - {@link Config.entities | `this.config.entities`} key.
- * @param item - {@link EntityItem | `EntityItem`} object.
+ * @param item - {@link StorageItem | `StorageItem`} object.
  * @param overwrite - Overwrite existing {@link ConfigKeys.rangeKey | `this.config.rangeKey`} property value (default `false`).
  *
  * @returns Shallow clone of `item` with updated range key.
@@ -21,8 +21,8 @@ function updateItemRangeKey(entityManager, entityToken, item, overwrite = false)
         // Validate params.
         validateEntityToken.validateEntityToken(entityManager, entityToken);
         // Return current item if rangeKey exists and overwrite is false.
-        if (item[entityManager.config.rangeKey] &&
-            !overwrite) {
+        const rkProp = entityManager.config.rangeKey;
+        if (item[rkProp] && !overwrite) {
             entityManager.logger.debug('did not overwrite existing entity item range key', {
                 entityToken,
                 item,
@@ -31,15 +31,16 @@ function updateItemRangeKey(entityManager, entityToken, item, overwrite = false)
             return { ...item };
         }
         // Get item unique property & validate.
-        const uniqueProperty = item[entityManager.config.entities[entityToken]
-            .uniqueProperty];
-        if (entityTools.isNil(uniqueProperty))
+        const upProp = entityManager.config.entities[entityToken]
+            .uniqueProperty;
+        const uniqueValue = item[upProp];
+        if (entityTools.isNil(uniqueValue))
             throw new Error(`missing item unique property`);
         // Update range key.
         const newItem = Object.assign({ ...item }, {
             [entityManager.config.rangeKey]: [
                 entityManager.config.entities[entityToken].uniqueProperty,
-                uniqueProperty,
+                uniqueValue,
             ].join(entityManager.config.generatedValueDelimiter),
         });
         entityManager.logger.debug('updated entity item range key', {

package/dist/index.d.ts

@@ -58,8 +58,8 @@ type Config<C extends BaseConfigMap = BaseConfigMap> = ConditionalProperty<'enti
         defaultLimit?: number;
         defaultPageSize?: number;
         shardBumps?: ShardBump[];
-        timestampProperty: C['TranscodedProperties'] & PropertiesOfType<C['EntityMap'][E], number> & TranscodableProperties<C['EntityMap'], C['TranscodeRegistry']>;
-        uniqueProperty: C['TranscodedProperties'] & keyof C['EntityMap'][E] & TranscodableProperties<C['EntityMap'], C['TranscodeRegistry']>;
+        timestampProperty: Extract<Extract<C['TranscodedProperties'], PropertiesOfType<C['EntityMap'][E], number>>, TranscodableProperties<C['EntityMap'], C['TranscodeRegistry']>>;
+        uniqueProperty: Extract<Extract<C['TranscodedProperties'], keyof C['EntityMap'][E]>, TranscodableProperties<C['EntityMap'], C['TranscodeRegistry']>>;
     };
 }> & ConditionalProperty<'generatedProperties', C['ShardedKeys'] | C['UnshardedKeys'], ConditionalProperty<'sharded', C['ShardedKeys'], Record<C['ShardedKeys'], (C['TranscodedProperties'] & TranscodableProperties<C['EntityMap'], C['TranscodeRegistry']>)[]>> & ConditionalProperty<'unsharded', C['UnshardedKeys'], Record<C['UnshardedKeys'], (C['TranscodedProperties'] & TranscodableProperties<C['EntityMap'], C['TranscodeRegistry']>)[]>>> & ConditionalProperty<'propertyTranscodes', C['TranscodedProperties'] & TranscodableProperties<C['EntityMap'], C['TranscodeRegistry']>, {
     [P in C['TranscodedProperties'] & TranscodableProperties<C['EntityMap'], C['TranscodeRegistry']>]: PropertiesOfType<C['TranscodeRegistry'], FlattenEntityMap<C['EntityMap']>[P]>;
@@ -119,44 +119,46 @@ type ConfigMap<M extends Partial<BaseConfigMap> = Partial<BaseConfigMap>> = Vali
 }>;
 
 /**
- * Extracts a database-facing partial item type from a {@link BaseConfigMap | `ConfigMap`}.
+ * Database-facing record key type from a {@link BaseConfigMap | `ConfigMap`} with required hash & range keys.
  *
  * @typeParam CC - {@link ConfigMap | `ConfigMap`} that defines an {@link Config | `EntityManager configuration`}'s {@link EntityMap | `EntityMap`}, key properties, and {@link TranscodeRegistry | `TranscodeRegistry`}. If omitted, defaults to {@link BaseConfigMap | `BaseConfigMap`}.
  *
- * @category EntityManager
+ * @category EntityClient
  * @protected
  */
-type EntityItem<CC extends BaseConfigMap> = Partial<FlattenEntityMap<CC['EntityMap']> & Record<CC['HashKey'] | CC['RangeKey'] | CC['ShardedKeys'] | CC['UnshardedKeys'], string>> & Record<string, unknown>;
+type EntityKey<CC extends BaseConfigMap> = Record<CC['HashKey'] | CC['RangeKey'], string>;
 
 /**
- * Database-facing record key type from a {@link BaseConfigMap | `ConfigMap`} with required hash & range keys.
+ * Extracts entity tokens from a {@link ConfigMap | `ConfigMap`}.
  *
  * @typeParam CC - {@link ConfigMap | `ConfigMap`} that defines an {@link Config | `EntityManager configuration`}'s {@link EntityMap | `EntityMap`}, key properties, and {@link TranscodeRegistry | `TranscodeRegistry`}. If omitted, defaults to {@link BaseConfigMap | `BaseConfigMap`}.
  *
- * @category EntityClient
+ * @category EntityManager
  * @protected
  */
-type EntityKey<CC extends BaseConfigMap> = Record<CC['HashKey'] | CC['RangeKey'], string>;
+type EntityToken<CC extends BaseConfigMap> = Extract<keyof Exactify<CC['EntityMap']>, string>;
 
 /**
- * Extracts entity tokens from a {@link ConfigMap | `ConfigMap`}.
+ * Storage-facing partial item type from a {@link BaseConfigMap | `ConfigMap`}.
+ *
+ * Token-agnostic shape used by encoding/decoding, key updates, and
+ * (de)hydration services.
  *
  * @typeParam CC - {@link ConfigMap | `ConfigMap`} that defines an {@link Config | `EntityManager configuration`}'s {@link EntityMap | `EntityMap`}, key properties, and {@link TranscodeRegistry | `TranscodeRegistry`}. If omitted, defaults to {@link BaseConfigMap | `BaseConfigMap`}.
  *
  * @category EntityManager
- * @protected
  */
-type EntityToken<CC extends BaseConfigMap> = keyof Exactify<CC['EntityMap']> & string;
+type StorageItem<CC extends BaseConfigMap> = Partial<FlattenEntityMap<CC['EntityMap']> & Record<CC['HashKey'] | CC['RangeKey'] | CC['ShardedKeys'] | CC['UnshardedKeys'], string>> & Record<string, unknown>;
 
 /**
- * A partial {@link EntityItem | `EntityItem`} restricted to keys defined in `C`.
+ * A partial {@link StorageItem | `StorageItem`} restricted to keys defined in `C`.
  *
  * @typeParam CC - {@link ConfigMap | `ConfigMap`} that defines an {@link Config | `EntityManager configuration`}'s {@link EntityMap | `EntityMap`}, key properties, and {@link TranscodeRegistry | `TranscodeRegistry`}. If omitted, defaults to {@link BaseConfigMap | `BaseConfigMap`}.
  *
  * @category QueryBuilder
  * @protected
  */
-type PageKey<CC extends BaseConfigMap> = Pick<EntityItem<CC>, CC['HashKey'] | CC['RangeKey'] | CC['ShardedKeys'] | CC['UnshardedKeys'] | CC['TranscodedProperties']>;
+type PageKey<CC extends BaseConfigMap> = Pick<StorageItem<CC>, CC['HashKey'] | CC['RangeKey'] | CC['ShardedKeys'] | CC['UnshardedKeys'] | CC['TranscodedProperties']>;
 /**
  * Internal helpers to safely derive index component tokens for an index IT.
  *
@@ -182,11 +184,39 @@ type IndexRangeKeyOf<CF, IT extends string> = CF extends {
  */
 type IndexTokensOf<CF> = CF extends {
     indexes?: infer I;
-} ? I extends Record<string, unknown> ? keyof I & string : string : string;
+} ? I extends Record<string, unknown> ? Extract<keyof I, string> : string : string;
 type HasIndexFor<CF, IT extends string> = CF extends {
     indexes?: infer I;
 } ? I extends Record<string, unknown> ? IT extends keyof I ? true : false : false : false;
-type IndexComponentTokens<CC extends BaseConfigMap, CF, IT extends string> = HasIndexFor<CF, IT> extends true ? CC['HashKey'] | CC['RangeKey'] | IndexHashKeyOf<CF, IT> | IndexRangeKeyOf<CF, IT> : CC['HashKey'] | CC['RangeKey'] | CC['ShardedKeys'] | CC['UnshardedKeys'] | CC['TranscodedProperties'];
+/**
+ * Base index component tokens shared by all indexes
+ * (the global hashKey and rangeKey defined in the Config).
+ *
+ * @category QueryBuilder
+ */
+type BaseKeyTokens<CC extends BaseConfigMap> = CC['HashKey'] | CC['RangeKey'];
+/**
+ * Key set for index component tokens when CF/IT identify a concrete index.
+ * - Always includes base key tokens (global hash/range).
+ * - Conditionally includes index hashKey/rangeKey when they do not collapse
+ *   to the base key union.
+ *
+ * @category QueryBuilder
+ */
+type PresentIndexTokenSet<CC extends BaseConfigMap, CF, IT extends string> = Record<BaseKeyTokens<CC>, true> & {
+    [K in IndexHashKeyOf<CF, IT> as K extends BaseKeyTokens<CC> ? never : K]: true;
+} & {
+    [K in IndexRangeKeyOf<CF, IT> as K extends BaseKeyTokens<CC> ? never : K]: true;
+};
+/**
+ * Key set for index component tokens when CF does not carry an `indexes` map
+ * or IT is unknown. Includes global keys, generated keys, and transcodable
+ * properties.
+ *
+ * @category QueryBuilder
+ */
+type FallbackIndexTokenSet<CC extends BaseConfigMap> = Record<CC['HashKey'] | CC['RangeKey'] | CC['ShardedKeys'] | CC['UnshardedKeys'] | CC['TranscodedProperties'], true>;
+type IndexComponentTokens<CC extends BaseConfigMap, CF, IT extends string> = HasIndexFor<CF, IT> extends true ? keyof PresentIndexTokenSet<CC, CF, IT> : keyof FallbackIndexTokenSet<CC>;
 /**
  * Page key typed for a specific index token.
  *
@@ -194,7 +224,7 @@ type IndexComponentTokens<CC extends BaseConfigMap, CF, IT extends string> = Has
  *   shape narrows to exactly the component tokens of IT.
  * - Without CF, falls back to the broad PageKey<CC> shape.
  */
-type PageKeyByIndex<CC extends BaseConfigMap, ET extends EntityToken<CC>, IT extends string = string, CF = unknown> = Pick<EntityItem<CC>, IndexComponentTokens<CC, CF, IT>>;
+type PageKeyByIndex<CC extends BaseConfigMap, ET extends EntityToken<CC>, IT extends string = string, CF = unknown> = Pick<StorageItem<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<{
@@ -247,15 +277,11 @@ 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];
 /**
- * EntityItemByToken — database-facing partial item narrowed to a specific entity token.
- * Mirrors `EntityItem<CC>` with the entity surface restricted to `EntityOfToken<CC, ET>`.
- *
- * Note: If using createEntityManager with entitiesSchema, the schema must declare
- * only base (non-generated) properties. Generated keys/tokens are layered by EntityManager.
+ * EntityItem — domain-facing item narrowed to a specific entity token, plus
+ * optional key/token properties. Required fields per captured entitiesSchema
+ * (when present); no string index signature.
  */
-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>;
+type EntityItem<CC extends BaseConfigMap, ET extends EntityToken<CC>> = EntityOfToken<CC, ET> & Partial<Record<CC['HashKey'] | CC['RangeKey'] | CC['ShardedKeys'] | CC['UnshardedKeys'], string>>;
 /**
  * Normalize literals: string | readonly string[] -\> union of strings.
  */
@@ -264,10 +290,15 @@ type KeysFrom<K> = K extends readonly (infer E)[] ? Extract<E, string> : K exten
  * 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>;
+/** EntityRecord — DB-facing record (keys required), narrowed to a specific entity token. */
+type EntityRecord<CC extends BaseConfigMap, ET extends EntityToken<CC>> = Partial<EntityItem<CC, ET>> & EntityKey<CC>;
+/** EntityItemPartial — projected/seed domain shape by token.
+ * - If K provided: required projected keys (`Projected<EntityItem<CC, ET>, K>`).
+ * - If K omitted: permissive seed (`Partial<EntityItem<CC, ET>>`).
+ */
+type EntityItemPartial<CC extends BaseConfigMap, ET extends EntityToken<CC>, K = unknown> = [KeysFrom<K>] extends [never] ? Partial<EntityItem<CC, ET>> : Projected<EntityItem<CC, ET>, K>;
+/** EntityRecordPartial — projected DB record shape by token. */
+type EntityRecordPartial<CC extends BaseConfigMap, ET extends EntityToken<CC>, K = unknown> = Projected<EntityRecord<CC, ET>, K>;
 
 /**
  * A result returned by a {@link ShardQueryFunction | `ShardQueryFunction`} querying an individual shard.
@@ -285,7 +316,7 @@ interface ShardQueryResult<CC extends BaseConfigMap, ET extends EntityToken<CC>,
     /** The number of records returned. */
     count: number;
     /** The returned records. */
-    items: ProjectedItemByToken<CC, ET, K>[];
+    items: EntityItemPartial<CC, ET, K>[];
     /** The page key for the next query on this shard. */
     pageKey?: PageKeyByIndex<CC, ET, IT, CF>;
 }
@@ -310,7 +341,7 @@ interface ShardQueryResult<CC extends BaseConfigMap, ET extends EntityToken<CC>,
  */
 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, 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>>;
+} ? I extends Record<string, unknown> ? IT extends Extract<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.
@@ -330,7 +361,7 @@ type ShardQueryFunction<CC extends BaseConfigMap, ET extends EntityToken<CC>, IT
  */
 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, K>> : Record<ITS, ShardQueryFunction<CC, ET, ITS, CF, K>> : Record<ITS, ShardQueryFunction<CC, ET, ITS, CF, K>>;
+} ? I extends Record<string, unknown> ? Record<Extract<ITS, Extract<keyof I, string>>, ShardQueryFunction<CC, ET, Extract<ITS, Extract<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).
@@ -373,7 +404,7 @@ interface QueryOptions<CC extends BaseConfigMap, ET extends EntityToken<CC> = En
     /**
      * Partial item object sufficiently populated to generate index hash keys.
      */
-    item: EntityItemByToken<CC, ET>;
+    item: EntityItemPartial<CC, ET>;
     /**
      * The target maximum number of records to be returned by the query across
      * all shards.
@@ -409,7 +440,7 @@ interface QueryOptions<CC extends BaseConfigMap, ET extends EntityToken<CC> = En
     /**
      * 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<ProjectedItemByToken<CC, ET, K>> | undefined;
+    sortOrder?: SortOrder<EntityItemPartial<CC, ET, K>> | undefined;
     /**
      * Lower limit to query shard space.
      *
@@ -476,7 +507,7 @@ interface QueryResult<CC extends BaseConfigMap, ET extends EntityToken<CC>, ITS
     /** Total number of records returned across all shards. */
     count: number;
     /** The returned records. */
-    items: ProjectedItemByToken<CC, ET, K>[];
+    items: EntityItemPartial<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.
@@ -526,13 +557,13 @@ declare class EntityManager<CC extends BaseConfigMap, CF = unknown> {
      * Encode a generated property value. Returns a string or undefined if atomicity requirement of sharded properties not met.
      *
      * @param property - {@link Config | Config} `generatedProperties` key.
-     * @param item - {@link EntityItem | `EntityItem`} object.
+     * @param item - {@link StorageItem | `StorageItem`} object.
      *
      * @returns Encoded generated property value.
      *
      * @throws `Error` if `property` is not a {@link Config | Config} `generatedProperties` key.
      */
-    encodeGeneratedProperty(property: CC['ShardedKeys'] | CC['UnshardedKeys'], item: EntityItem<CC>): string | undefined;
+    encodeGeneratedProperty(property: CC['ShardedKeys'] | CC['UnshardedKeys'], item: StorageItem<CC>): string | undefined;
     /**
      * Update generated properties, hash key, and range key on an {@link EntityItem | `EntityItem`} object.
      *
@@ -546,28 +577,27 @@ declare class EntityManager<CC extends BaseConfigMap, CF = unknown> {
      *
      * @overload
      */
-    addKeys<ET extends EntityToken<CC>>(entityToken: ET, item: EntityItemByToken<CC, ET>, overwrite?: boolean): EntityRecordByToken<CC, ET>;
+    addKeys<ET extends EntityToken<CC>>(entityToken: ET, item: EntityItemPartial<CC, ET>, overwrite?: boolean): EntityRecordPartial<CC, ET>;
     /**
      * @overload
      */
-    addKeys<ET extends EntityToken<CC>>(entityToken: ET, item: EntityItemByToken<CC, ET>[], overwrite?: boolean): EntityRecordByToken<CC, ET>[];
+    addKeys<ET extends EntityToken<CC>>(entityToken: ET, item: EntityItemPartial<CC, ET>[], overwrite?: boolean): EntityRecordPartial<CC, ET>[];
     /**
      * Convert one or more {@link EntityItem | `EntityItem`} objects into an array of {@link EntityKey | `EntityKey`} values.
      *
      * @param entityToken - {@link Config | `Config`} `entities` key.
-     * @param item - {@link EntityItem | `EntityItem`} object, or array of them.
+     * @param item - {@link EntityItem | `EntityItem`} object.
      * @param overwrite - Overwrite existing properties (default `false`).
      *
-     * @returns An array of {@link EntityKey | `EntityKey`} values. For a single input item, returns 0..N keys (usually 1).
-     *          For an array input, returns a single flattened array of keys across all inputs.
+     * @returns Array of {@link EntityKey | `EntityKey`} values derived from `item`.
      *
      * @throws `Error` if `entityToken` is invalid.
      */
-    getPrimaryKey<ET extends EntityToken<CC>>(entityToken: ET, item: EntityItemByToken<CC, ET>, overwrite?: boolean): EntityKey<CC>[];
+    getPrimaryKey<ET extends EntityToken<CC>>(entityToken: ET, item: EntityItemPartial<CC, ET>, overwrite?: boolean): EntityKey<CC>[];
     /**
      * @overload
      */
-    getPrimaryKey<ET extends EntityToken<CC>>(entityToken: ET, items: EntityItemByToken<CC, ET>[], overwrite?: boolean): EntityKey<CC>[];
+    getPrimaryKey<ET extends EntityToken<CC>>(entityToken: ET, items: EntityItemPartial<CC, ET>[], overwrite?: boolean): EntityKey<CC>[];
     /**
      * Strips generated properties, hash key, and range key from an {@link EntityRecord | `EntityRecord`} object.
      *
@@ -578,13 +608,12 @@ declare class EntityManager<CC extends BaseConfigMap, CF = unknown> {
      *
      * @throws `Error` if `entityToken` is invalid.
      *
-     * @overload
+     * Overloads:
      */
-    removeKeys<ET extends EntityToken<CC>>(entityToken: ET, item: EntityRecordByToken<CC, ET>): EntityItemByToken<CC, ET>;
-    /**
-     * @overload
-     */
-    removeKeys<ET extends EntityToken<CC>>(entityToken: ET, items: EntityRecordByToken<CC, ET>[]): EntityItemByToken<CC, ET>[];
+    removeKeys<ET extends EntityToken<CC>>(entityToken: ET, item: EntityRecord<CC, ET>): EntityItem<CC, ET>;
+    removeKeys<ET extends EntityToken<CC>, K = unknown>(entityToken: ET, item: EntityRecordPartial<CC, ET, K>): EntityItemPartial<CC, ET, K>;
+    removeKeys<ET extends EntityToken<CC>>(entityToken: ET, items: EntityRecord<CC, ET>[]): EntityItem<CC, ET>[];
+    removeKeys<ET extends EntityToken<CC>, K = unknown>(entityToken: ET, items: EntityRecordPartial<CC, ET, K>[]): EntityItemPartial<CC, ET, K>[];
     /**
      * Find an index token based on the configured hash and range key tokens.
      *
@@ -683,7 +712,7 @@ type TranscodedPropertiesFrom<CC> = CC extends {
 type EntitiesFromSchema<CC> = CC extends {
     entitiesSchema?: infer S;
 } ? S extends Record<string, ZodType> ? {
-    [K in keyof S & string]: z.infer<S[K]>;
+    [K in Extract<keyof S, string>]: z.infer<S[K]>;
 } & EntityMap : EntityMap : EntityMap;
 /**
  * Derive the union of index token names from a values-first config input.
@@ -699,7 +728,7 @@ type IndexTokensFrom<CC> = CC extends {
  * Captures a BaseConfigMap-compatible type from a literal ConfigInput value
  * and an EntityMap (defaults to MinimalEntityMapFrom<CC>).
  */
-type CapturedConfigMapFrom<CC, EM extends EntityMap> = {
+interface CapturedConfigMapFrom<CC, EM extends EntityMap> extends BaseConfigMap {
     EntityMap: EM;
     HashKey: HashKeyFrom<CC>;
     RangeKey: RangeKeyFrom<CC>;
@@ -707,7 +736,7 @@ type CapturedConfigMapFrom<CC, EM extends EntityMap> = {
     UnshardedKeys: UnshardedKeysFrom<CC>;
     TranscodedProperties: TranscodedPropertiesFrom<CC>;
     TranscodeRegistry: DefaultTranscodeRegistry;
-} & BaseConfigMap;
+}
 /**
  * Values-first factory that captures literal tokens and index names directly
  * from the provided config value. Runtime config parsing/validation is
@@ -725,14 +754,13 @@ type CapturedConfigMapFrom<CC, EM extends EntityMap> = {
 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.
+ * Storage-facing record type with required keys.
  *
  * @typeParam CC - {@link ConfigMap | `ConfigMap`} that defines an {@link Config | `EntityManager configuration`}'s {@link EntityMap | `EntityMap`}, key properties, and {@link TranscodeRegistry | `TranscodeRegistry`}. If omitted, defaults to {@link BaseConfigMap | `BaseConfigMap`}.
  *
  * @category EntityManager
- * @protected
  */
-type EntityRecord<CC extends BaseConfigMap> = EntityItem<CC> & EntityKey<CC>;
+type StorageRecord<CC extends BaseConfigMap> = StorageItem<CC> & EntityKey<CC>;
 
 /**
  * Base EntityClient options.
@@ -777,8 +805,8 @@ declare abstract class BaseEntityClient<CC extends BaseConfigMap, CF = unknown>
 }
 
 type ConfigOfClient<EC> = EC extends BaseEntityClient<infer CC> ? CC : never;
-type EntityClientRecordByToken<EC, ET extends EntityToken<ConfigOfClient<EC>>> = EntityRecordByToken<ConfigOfClient<EC>, ET>;
-type EntityClientItemByToken<EC, ET extends EntityToken<ConfigOfClient<EC>>> = EntityItemByToken<ConfigOfClient<EC>, ET>;
+type EntityClientRecordByToken<EC, ET extends EntityToken<ConfigOfClient<EC>>> = EntityRecord<ConfigOfClient<EC>, ET>;
+type EntityClientItemByToken<EC, ET extends EntityToken<ConfigOfClient<EC>>> = EntityItem<ConfigOfClient<EC>, ET>;
 
 /**
  * Constructor options for {@link BaseQueryBuilder | `BaseQueryBuilder`}.
@@ -850,4 +878,4 @@ declare abstract class BaseQueryBuilder<CC extends BaseConfigMap, EntityClient e
 }
 
 export { BaseEntityClient, BaseQueryBuilder, EntityManager, configSchema, createEntityManager };
-export type { BaseConfigMap, BaseEntityClientOptions, BaseQueryBuilderOptions, CapturedConfigMapFrom, Config, ConfigInput, ConfigMap, ConfigOfClient, EntitiesFromSchema, EntityClientItemByToken, EntityClientRecordByToken, 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 };
+export type { BaseConfigMap, BaseEntityClientOptions, BaseKeyTokens, BaseQueryBuilderOptions, CapturedConfigMapFrom, Config, ConfigInput, ConfigMap, ConfigOfClient, EntitiesFromSchema, EntityClientItemByToken, EntityClientRecordByToken, EntityItem, EntityItemPartial, EntityKey, EntityOfToken, EntityRecord, EntityRecordPartial, EntityToken, FallbackIndexTokenSet, HasIndexFor, HashKeyFrom, IndexComponentTokens, IndexHashKeyOf, IndexRangeKeyOf, IndexTokensFrom, IndexTokensOf, KeysFrom, PageKey, PageKeyByIndex, ParsedConfig, PresentIndexTokenSet, Projected, QueryBuilderQueryOptions, QueryOptions, QueryOptionsByCC, QueryOptionsByCF, QueryResult, RangeKeyFrom, ShardBump, ShardQueryFunction, ShardQueryMap, ShardQueryMapByCC, ShardQueryMapByCF, ShardQueryResult, ShardedKeysFrom, StorageItem, StorageRecord, TranscodedPropertiesFrom, UnshardedKeysFrom, ValidateConfigMap };

package/dist/mjs/EntityManager/EntityManager.js

@@ -62,7 +62,7 @@ class EntityManager {
      * Encode a generated property value. Returns a string or undefined if atomicity requirement of sharded properties not met.
      *
      * @param property - {@link Config | Config} `generatedProperties` key.
-     * @param item - {@link EntityItem | `EntityItem`} object.
+     * @param item - {@link StorageItem | `StorageItem`} object.
      *
      * @returns Encoded generated property value.
      *
@@ -85,9 +85,11 @@ class EntityManager {
     }
     removeKeys(entityToken, i) {
         if (Array.isArray(i)) {
-            return i.map((item) => removeKeys(this, entityToken, item));
+            const out = i.map((item) => removeKeys(this, entityToken, item));
+            return out;
         }
-        return removeKeys(this, entityToken, i);
+        const out = removeKeys(this, entityToken, i);
+        return out;
     }
     findIndexToken(hashKeyToken, rangeKeyToken, suppressError) {
         // Dispatch with a literal to satisfy overload selection.
@@ -118,7 +120,8 @@ class EntityManager {
      * @protected
      */
     async query(options) {
-        return await query(this, options);
+        const result = await query(this, options);
+        return result;
     }
 }
 _EntityManager_config = new WeakMap();

package/dist/mjs/EntityManager/encodeGeneratedProperty.js

@@ -6,7 +6,7 @@ import { validateGeneratedProperty } from './validateGeneratedProperty.js';
  *
  * @param entityManager - {@link EntityManager | `EntityManager`} instance.
  * @param property - {@link Config.generatedProperties | Generated property} key.
- * @param item - {@link EntityItem | `EntityItem`} object.
+ * @param item - {@link StorageItem | `StorageItem`} object.
  *
  * @returns Encoded generated property value.
  *
@@ -19,7 +19,10 @@ function encodeGeneratedProperty(entityManager, property, item) {
         const sharded = property in entityManager.config.generatedProperties.sharded;
         const elements = entityManager.config.generatedProperties[sharded ? 'sharded' : 'unsharded'][property];
         // Map elements to [element, value] pairs.
-        const elementMap = elements.map((element) => [element, item[element]]);
+        const elementMap = elements.map((element) => [
+            element,
+            item[element],
+        ]);
         // Return undefined if sharded & atomicity requirement fails.
         if (sharded && elementMap.some(([, value]) => isNil(value)))
             return;

package/dist/mjs/EntityManager/getHashKeySpace.js

@@ -50,7 +50,7 @@ function getHashKeySpace(entityManager, entityToken, hashKeyToken, item, timesta
             // Map shard keys to hash keys.
             .map((shardKey) => {
             // Calculate record hash key.
-            let hashKey = `${entityToken}${entityManager.config.shardKeyDelimiter}${shardKey}`;
+            let hashKey = `${String(entityToken)}${entityManager.config.shardKeyDelimiter}${shardKey}`;
             // If hash key space basis is a different property, encode it.
             if (hashKeyToken !== entityManager.config.hashKey)
                 hashKey = encodeGeneratedProperty(entityManager, hashKeyToken, {

package/dist/mjs/EntityManager/getPrimaryKey.js

@@ -25,11 +25,14 @@ import { updateItemRangeKey } from './updateItemRangeKey.js';
 function getPrimaryKey(entityManager, entityToken, item, overwrite = false) {
     const { hashKey, rangeKey } = entityManager.config;
     // If both keys are present and we're not overwriting, return the exact pair.
-    if (!overwrite && item[hashKey] && item[rangeKey]) {
+    const rec = item;
+    const hk = hashKey;
+    const rk = rangeKey;
+    if (!overwrite && rec[hk] && rec[rk]) {
         return [
             {
-                [hashKey]: item[hashKey],
-                [rangeKey]: item[rangeKey],
+                [hashKey]: rec[hk],
+                [rangeKey]: rec[rk],
             },
         ];
     }
@@ -38,6 +41,7 @@ function getPrimaryKey(entityManager, entityToken, item, overwrite = false) {
     // If timestamp present, compute exactly one hash key and return single pair.
     const tsProp = entityManager.config.entities[entityToken].timestampProperty;
     if (withRangeKey[tsProp] !== undefined) {
+        // Note: use StorageItem here
         const withHashKey = updateItemHashKey(entityManager, entityToken, withRangeKey, true);
         return [
             {
@@ -49,12 +53,15 @@ function getPrimaryKey(entityManager, entityToken, item, overwrite = false) {
     // No timestamp: enumerate hash-key space across all shard bumps (0..Infinity).
     const hashKeys = getHashKeySpace(entityManager, entityToken, hashKey, withRangeKey, 0, Infinity);
     // Map to keys and de-duplicate.
-    const rk = withRangeKey[rangeKey];
+    const rangeKeyValue = withRangeKey[rangeKey];
     const seen = new Set();
     const keys = hashKeys
         .map((hk) => {
-        const key = { [hashKey]: hk, [rangeKey]: rk };
-        const sig = `${hk}|${rk}`;
+        const key = {
+            [hashKey]: hk,
+            [rangeKey]: rangeKeyValue,
+        };
+        const sig = `${hk}|${rangeKeyValue}`;
         if (seen.has(sig))
             return undefined;
         seen.add(sig);

package/dist/mjs/EntityManager/removeKeys.js

@@ -23,14 +23,21 @@ function removeKeys(entityManager, entityToken, item) {
             ...Object.keys(sharded),
             ...Object.keys(unsharded),
         ]);
-        // Create a shallow copy of item omitting the keys above (no delete operator).
-        const newItem = Object.fromEntries(Object.entries(item).filter(([key]) => !keysToStrip.has(key)));
+        // Create a shallow copy of item omitting the keys above (no delete operator),
+        // avoiding any-typed assignments.
+        const source = item;
+        const newItemObj = {};
+        for (const [key, value] of Object.entries(source)) {
+            if (!keysToStrip.has(key)) {
+                newItemObj[key] = value;
+            }
+        }
         entityManager.logger.debug('stripped entity item generated properties', {
             entityToken,
             item,
-            newItem,
+            newItem: newItemObj,
         });
-        return newItem;
+        return newItemObj;
     }
     catch (error) {
         if (error instanceof Error)

package/dist/mjs/EntityManager/updateItemHashKey.js

@@ -4,11 +4,11 @@ import { getShardBump } from './getShardBump.js';
 import { validateEntityToken } from './validateEntityToken.js';
 
 /**
- * Update the hash key on an partial {@link EntityItem | `EntityItem`} object.
+ * Update the hash key on an {@link EntityItemPartial | `EntityItemPartial`} object.
  *
  * @param entityManager - {@link EntityManager | `EntityManager`} instance.
  * @param entityToken - {@link Config.entities | `this.config.entities`} key.
- * @param item - {@link EntityItem | `EntityItem`} object.
+ * @param item - {@link StorageItem | `StorageItem`} object.
  * @param overwrite - Overwrite existing {@link ConfigKeys.hashKey | `this.config.hashKey`} property value (default `false`).
  *
  * @returns Shallow clone of `item` with updated hash key.
@@ -30,13 +30,14 @@ function updateItemHashKey(entityManager, entityToken, item, overwrite = false)
             return { ...item };
         }
         // Get item timestamp property & validate.
-        const timestamp = item[entityManager.config.entities[entityToken]
-            .timestampProperty];
+        const tsProp = entityManager.config.entities[entityToken]
+            .timestampProperty;
+        const timestamp = item[tsProp];
         if (isNil(timestamp))
             throw new Error(`missing item timestamp property`);
         // Find first entity sharding bump before timestamp.
         const { charBits, chars } = getShardBump(entityManager, entityToken, timestamp);
-        let hashKey = `${entityToken}${entityManager.config.shardKeyDelimiter}`;
+        let hashKey = `${String(entityToken)}${entityManager.config.shardKeyDelimiter}`;
         if (chars) {
             // Radix is the numerical base of the shardKey.
             const radix = 2 ** charBits;
@@ -44,8 +45,9 @@ function updateItemHashKey(entityManager, entityToken, item, overwrite = false)
             // all placeholders are utilized (e.g., chars=2, charBits=2 => 16 combos).
             const space = radix ** chars;
             // Get item unique property & validate.
-            const uniqueId = item[entityManager.config.entities[entityToken]
-                .uniqueProperty];
+            const upProp = entityManager.config.entities[entityToken]
+                .uniqueProperty;
+            const uniqueId = item[upProp];
             if (isNil(uniqueId))
                 throw new Error(`missing item unique property`);
             hashKey += (stringHash(uniqueId) % space)

package/dist/mjs/EntityManager/updateItemRangeKey.js

@@ -2,11 +2,11 @@ import { isNil } from '@karmaniverous/entity-tools';
 import { validateEntityToken } from './validateEntityToken.js';
 
 /**
- * Update the range key on an {@link EntityItem | `EntityItem`} object.
+ * Update the range key on an {@link EntityItemPartial | `EntityItemPartial`} object.
  *
  * @param entityManager - {@link EntityManager | `EntityManager`} instance.
  * @param entityToken - {@link Config.entities | `this.config.entities`} key.
- * @param item - {@link EntityItem | `EntityItem`} object.
+ * @param item - {@link StorageItem | `StorageItem`} object.
  * @param overwrite - Overwrite existing {@link ConfigKeys.rangeKey | `this.config.rangeKey`} property value (default `false`).
  *
  * @returns Shallow clone of `item` with updated range key.
@@ -19,8 +19,8 @@ function updateItemRangeKey(entityManager, entityToken, item, overwrite = false)
         // Validate params.
         validateEntityToken(entityManager, entityToken);
         // Return current item if rangeKey exists and overwrite is false.
-        if (item[entityManager.config.rangeKey] &&
-            !overwrite) {
+        const rkProp = entityManager.config.rangeKey;
+        if (item[rkProp] && !overwrite) {
             entityManager.logger.debug('did not overwrite existing entity item range key', {
                 entityToken,
                 item,
@@ -29,15 +29,16 @@ function updateItemRangeKey(entityManager, entityToken, item, overwrite = false)
             return { ...item };
         }
         // Get item unique property & validate.
-        const uniqueProperty = item[entityManager.config.entities[entityToken]
-            .uniqueProperty];
-        if (isNil(uniqueProperty))
+        const upProp = entityManager.config.entities[entityToken]
+            .uniqueProperty;
+        const uniqueValue = item[upProp];
+        if (isNil(uniqueValue))
             throw new Error(`missing item unique property`);
         // Update range key.
         const newItem = Object.assign({ ...item }, {
             [entityManager.config.rangeKey]: [
                 entityManager.config.entities[entityToken].uniqueProperty,
-                uniqueProperty,
+                uniqueValue,
             ].join(entityManager.config.generatedValueDelimiter),
         });
         entityManager.logger.debug('updated entity item range key', {

package/package.json

@@ -11,12 +11,12 @@
   },
   "dependencies": {
     "@karmaniverous/batch-process": "^0.1.0",
-    "@karmaniverous/entity-tools": "^0.7.1",
-    "@karmaniverous/string-utilities": "^0.2.1",
+    "@karmaniverous/entity-tools": "^0.8.0",
+    "@karmaniverous/string-utilities": "^0.2.2",
     "lz-string": "^1.5.0",
     "radash": "^12.1.1",
     "string-hash": "^1.1.3",
-    "zod": "^4.1.12"
+    "zod": "^4.1.13"
   },
   "description": "Rational indexing & cross-shard querying at scale in your NoSQL database so you can focus on your application logic.",
   "devDependencies": {
@@ -39,24 +39,24 @@
     "eslint-plugin-prettier": "^5.5.4",
     "eslint-plugin-simple-import-sort": "^12.1.1",
     "eslint-plugin-tsdoc": "^0.5.0",
-    "knip": "^5.69.1",
+    "knip": "^5.70.2",
     "lefthook": "^2.0.4",
-    "prettier": "^3.6.2",
+    "prettier": "^3.7.3",
     "release-it": "^19.0.6",
-    "rimraf": "^6.1.0",
-    "rollup": "^4.53.2",
-    "rollup-plugin-dts": "^6.2.3",
+    "rimraf": "^6.1.2",
+    "rollup": "^4.53.3",
+    "rollup-plugin-dts": "^6.3.0",
     "tsd": "^0.33.0",
     "tslib": "^2.8.1",
-    "typedoc": "^0.28.14",
+    "typedoc": "^0.28.15",
     "typedoc-plugin-mdn-links": "^5.0.10",
     "typedoc-plugin-replace-text": "^4.2.0",
     "typedoc-plugin-zod": "^1.4.3",
-    "@vitest/coverage-v8": "^4.0.9",
-    "@vitest/eslint-plugin": "^1.4.3",
-    "vitest": "^4.0.9",
+    "@vitest/coverage-v8": "^4.0.14",
+    "@vitest/eslint-plugin": "^1.5.1",
+    "vitest": "^4.0.14",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.46.4"
+    "typescript-eslint": "^8.48.0"
   },
   "exports": {
     ".": {
@@ -134,5 +134,5 @@
   },
   "type": "module",
   "types": "dist/index.d.ts",
-  "version": "7.3.4"
+  "version": "8.0.0"
 }