@karmaniverous/entity-manager 6.14.1 → 6.14.3

package/README.md

@@ -192,8 +192,17 @@ const user = {
 // Add hashKey, rangeKey, and generated properties
 const record = manager.addKeys('user', user); // returns EntityRecord<...>
 
-// Get just the primary key
-const keyOnly = manager.getPrimaryKey('user', user); // { hashKey, rangeKey }
+// Get one or more primary keys for an item
+// - If the timestampProperty is present, you'll usually get exactly one key.
+// - If the timestampProperty is missing but uniqueProperty is present,
+//   you'll get one key per shard bump (deterministic suffix per bump).
+const keys = manager.getPrimaryKey('user', user); // EntityKey[]
+
+// Example: reading by unique id when timestamp is unknown
+// (keys may include multiple candidates — one per bump):
+// const keys = manager.getPrimaryKey('user', { userId: 'u123' });
+// const { Items } = await entityClient.getItems(keys);
+// const found = Items[0];
 
 // Remove generated keys from a stored record
 const pruned = manager.removeKeys('user', record);

package/dist/cjs/EntityManager/EntityManager.js

@@ -70,7 +70,7 @@ class EntityManager {
     }
     getPrimaryKey(entityToken, i, overwrite = false) {
         if (Array.isArray(i)) {
-            return i.map((item) => getPrimaryKey.getPrimaryKey(this, entityToken, item, overwrite));
+            return i.flatMap((item) => getPrimaryKey.getPrimaryKey(this, entityToken, item, overwrite));
         }
         return getPrimaryKey.getPrimaryKey(this, entityToken, i, overwrite);
     }

package/dist/cjs/EntityManager/getHashKeySpace.js

@@ -1,6 +1,7 @@
 'use strict';
 
 var radash = require('radash');
+var stringHash = require('string-hash');
 var encodeGeneratedProperty = require('./encodeGeneratedProperty.js');
 var validateGeneratedProperty = require('./validateGeneratedProperty.js');
 
@@ -24,6 +25,9 @@ function getHashKeySpace(entityManager, entityToken, hashKeyToken, item, timesta
         if (hashKeyToken !== entityManager.config.hashKey)
             validateGeneratedProperty.validateGeneratedProperty(entityManager, hashKeyToken, true);
         const { shardBumps } = entityManager.config.entities[entityToken];
+        // Detect presence of the entity's unique property on the item.
+        const uniqueProp = entityManager.config.entities[entityToken].uniqueProperty;
+        const uniqueValue = item[uniqueProp];
         const hashKeySpace = shardBumps
             // Filter shard bumps by timestamp range.
             .filter((bump, i) => (i === shardBumps.length - 1 ||
@@ -32,9 +36,18 @@ function getHashKeySpace(entityManager, entityToken, hashKeyToken, item, timesta
             // Generate shard key space.
             .flatMap(({ charBits, chars }) => {
             const radix = 2 ** charBits;
-            return chars
-                ? [...radash.range(0, radix ** chars - 1)].map((char) => char.toString(radix).padStart(chars, '0'))
-                : '';
+            // If the item's unique property is present, deterministically
+            // compute exactly one shard suffix for this bump. Otherwise,
+            // enumerate the full shard space for the bump.
+            if (chars) {
+                if (uniqueValue) {
+                    const space = radix ** chars;
+                    const mod = stringHash(uniqueValue) % space;
+                    return mod.toString(radix).padStart(chars, '0');
+                }
+                return [...radash.range(0, radix ** chars - 1)].map((char) => char.toString(radix).padStart(chars, '0'));
+            }
+            return '';
         })
             // Map shard keys to hash keys.
             .map((shardKey) => {

package/dist/cjs/EntityManager/getPrimaryKey.js

@@ -1,25 +1,69 @@
 'use strict';
 
-var radash = require('radash');
-var addKeys = require('./addKeys.js');
+var getHashKeySpace = require('./getHashKeySpace.js');
+var updateItemHashKey = require('./updateItemHashKey.js');
+var updateItemRangeKey = require('./updateItemRangeKey.js');
 
 /**
- * Convert an {@link EntityItem | `EntityItem`} into an {@link EntityKey | `EntityKey`}.
+ * Convert an {@link EntityItem | `EntityItem`} into one or more {@link EntityKey | `EntityKey`} values.
+ *
+ * Behavior:
+ * - Always returns an array of keys.
+ * - If `overwrite` is false and the item already has both hash and range keys, returns exactly that pair.
+ * - Otherwise, computes the range key. Then:
+ *   - If the timestampProperty is present, computes exactly one hash key and returns a single key.
+ *   - If the timestampProperty is missing, enumerates the hash-key space across all shard bumps
+ *     (with uniqueProperty present → one suffix per bump) and returns one key per bump.
  *
  * @param entityManager - {@link EntityManager | `EntityManager`} instance.
  * @param entityToken - {@link Config | `Config`} `entities` key.
  * @param item - {@link EntityItem | `EntityItem`} object.
  * @param overwrite - Overwrite existing properties (default `false`).
  *
- * @returns {@link EntityKey | `EntityKey`} extracted from shallow clone of `item` with updated properties.
+ * @returns Array of {@link EntityKey | `EntityKey`} values derived from `item`.
  *
  * @throws `Error` if `entityToken` is invalid.
  */
 function getPrimaryKey(entityManager, entityToken, item, overwrite = false) {
     const { hashKey, rangeKey } = entityManager.config;
-    return radash.pick(!overwrite && item[hashKey] && item[rangeKey]
-        ? item
-        : addKeys.addKeys(entityManager, entityToken, item, overwrite), [entityManager.config.hashKey, entityManager.config.rangeKey]);
+    // If both keys are present and we're not overwriting, return the exact pair.
+    if (!overwrite && item[hashKey] && item[rangeKey]) {
+        return [
+            {
+                [hashKey]: item[hashKey],
+                [rangeKey]: item[rangeKey],
+            },
+        ];
+    }
+    // Compute/refresh the range key (throws if uniqueProperty missing).
+    const withRangeKey = updateItemRangeKey.updateItemRangeKey(entityManager, entityToken, item, true);
+    // If timestamp present, compute exactly one hash key and return single pair.
+    const tsProp = entityManager.config.entities[entityToken].timestampProperty;
+    if (withRangeKey[tsProp] !== undefined) {
+        const withHashKey = updateItemHashKey.updateItemHashKey(entityManager, entityToken, withRangeKey, true);
+        return [
+            {
+                [hashKey]: withHashKey[hashKey],
+                [rangeKey]: withHashKey[rangeKey],
+            },
+        ];
+    }
+    // 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 seen = new Set();
+    const keys = hashKeys
+        .map((hk) => {
+        const key = { [hashKey]: hk, [rangeKey]: rk };
+        const sig = `${hk}|${rk}`;
+        if (seen.has(sig))
+            return undefined;
+        seen.add(sig);
+        return key;
+    })
+        .filter((k) => !!k);
+    return keys;
 }
 
 exports.getPrimaryKey = getPrimaryKey;

package/dist/index.d.ts

@@ -431,32 +431,18 @@ declare class EntityManager<C extends BaseConfigMap> {
      */
     addKeys(entityToken: EntityToken<C>, item: EntityItem<C>[], overwrite?: boolean): EntityRecord<C>[];
     /**
-     * Convert an {@link EntityItem | `EntityItem`} into an {@link EntityKey | `EntityKey`}.
+     * 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.
+     * @param item - {@link EntityItem | `EntityItem`} object, or array of them.
      * @param overwrite - Overwrite existing properties (default `false`).
      *
-     * @returns {@link EntityKey | `EntityKey`} extracted from shallow clone of `item` with updated properties.
+     * @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.
      *
      * @throws `Error` if `entityToken` is invalid.
-     *
-     * @overload
-     */
-    getPrimaryKey(entityToken: EntityToken<C>, item: EntityItem<C>, overwrite?: boolean): EntityKey<C>;
-    /**
-     * Convert an array of {@link EntityItem | `EntityItem`} objects into {@link EntityKey | `EntityKey`} objects.
-     *
-     * @param entityToken - {@link Config | `Config`} `entities` key.
-     * @param items - Array of {@link EntityItem | `EntityItem`} objects.
-     * @param overwrite - Overwrite existing properties (default `false`).
-     *
-     * @returns An array of {@link EntityKey | `EntityKey`} objects extracted from shallow clone of each `item` with updated properties.
-     *
-     * @throws `Error` if `entityToken` is invalid.
-     *
-     * @overload
      */
+    getPrimaryKey(entityToken: EntityToken<C>, item: EntityItem<C>, overwrite?: boolean): EntityKey<C>[];
     getPrimaryKey(entityToken: EntityToken<C>, items: EntityItem<C>[], overwrite?: boolean): EntityKey<C>[];
     /**
      * Strips generated properties, hash key, and range key from an {@link EntityRecord | `EntityRecord`} object.

package/dist/mjs/EntityManager/EntityManager.js

@@ -68,7 +68,7 @@ class EntityManager {
     }
     getPrimaryKey(entityToken, i, overwrite = false) {
         if (Array.isArray(i)) {
-            return i.map((item) => getPrimaryKey(this, entityToken, item, overwrite));
+            return i.flatMap((item) => getPrimaryKey(this, entityToken, item, overwrite));
         }
         return getPrimaryKey(this, entityToken, i, overwrite);
     }

package/dist/mjs/EntityManager/getHashKeySpace.js

@@ -1,4 +1,5 @@
 import { range } from 'radash';
+import stringHash from 'string-hash';
 import { encodeGeneratedProperty } from './encodeGeneratedProperty.js';
 import { validateGeneratedProperty } from './validateGeneratedProperty.js';
 
@@ -22,6 +23,9 @@ function getHashKeySpace(entityManager, entityToken, hashKeyToken, item, timesta
         if (hashKeyToken !== entityManager.config.hashKey)
             validateGeneratedProperty(entityManager, hashKeyToken, true);
         const { shardBumps } = entityManager.config.entities[entityToken];
+        // Detect presence of the entity's unique property on the item.
+        const uniqueProp = entityManager.config.entities[entityToken].uniqueProperty;
+        const uniqueValue = item[uniqueProp];
         const hashKeySpace = shardBumps
             // Filter shard bumps by timestamp range.
             .filter((bump, i) => (i === shardBumps.length - 1 ||
@@ -30,9 +34,18 @@ function getHashKeySpace(entityManager, entityToken, hashKeyToken, item, timesta
             // Generate shard key space.
             .flatMap(({ charBits, chars }) => {
             const radix = 2 ** charBits;
-            return chars
-                ? [...range(0, radix ** chars - 1)].map((char) => char.toString(radix).padStart(chars, '0'))
-                : '';
+            // If the item's unique property is present, deterministically
+            // compute exactly one shard suffix for this bump. Otherwise,
+            // enumerate the full shard space for the bump.
+            if (chars) {
+                if (uniqueValue) {
+                    const space = radix ** chars;
+                    const mod = stringHash(uniqueValue) % space;
+                    return mod.toString(radix).padStart(chars, '0');
+                }
+                return [...range(0, radix ** chars - 1)].map((char) => char.toString(radix).padStart(chars, '0'));
+            }
+            return '';
         })
             // Map shard keys to hash keys.
             .map((shardKey) => {

package/dist/mjs/EntityManager/getPrimaryKey.js

@@ -1,23 +1,67 @@
-import { pick } from 'radash';
-import { addKeys } from './addKeys.js';
+import { getHashKeySpace } from './getHashKeySpace.js';
+import { updateItemHashKey } from './updateItemHashKey.js';
+import { updateItemRangeKey } from './updateItemRangeKey.js';
 
 /**
- * Convert an {@link EntityItem | `EntityItem`} into an {@link EntityKey | `EntityKey`}.
+ * Convert an {@link EntityItem | `EntityItem`} into one or more {@link EntityKey | `EntityKey`} values.
+ *
+ * Behavior:
+ * - Always returns an array of keys.
+ * - If `overwrite` is false and the item already has both hash and range keys, returns exactly that pair.
+ * - Otherwise, computes the range key. Then:
+ *   - If the timestampProperty is present, computes exactly one hash key and returns a single key.
+ *   - If the timestampProperty is missing, enumerates the hash-key space across all shard bumps
+ *     (with uniqueProperty present → one suffix per bump) and returns one key per bump.
  *
  * @param entityManager - {@link EntityManager | `EntityManager`} instance.
  * @param entityToken - {@link Config | `Config`} `entities` key.
  * @param item - {@link EntityItem | `EntityItem`} object.
  * @param overwrite - Overwrite existing properties (default `false`).
  *
- * @returns {@link EntityKey | `EntityKey`} extracted from shallow clone of `item` with updated properties.
+ * @returns Array of {@link EntityKey | `EntityKey`} values derived from `item`.
  *
  * @throws `Error` if `entityToken` is invalid.
  */
 function getPrimaryKey(entityManager, entityToken, item, overwrite = false) {
     const { hashKey, rangeKey } = entityManager.config;
-    return pick(!overwrite && item[hashKey] && item[rangeKey]
-        ? item
-        : addKeys(entityManager, entityToken, item, overwrite), [entityManager.config.hashKey, entityManager.config.rangeKey]);
+    // If both keys are present and we're not overwriting, return the exact pair.
+    if (!overwrite && item[hashKey] && item[rangeKey]) {
+        return [
+            {
+                [hashKey]: item[hashKey],
+                [rangeKey]: item[rangeKey],
+            },
+        ];
+    }
+    // Compute/refresh the range key (throws if uniqueProperty missing).
+    const withRangeKey = updateItemRangeKey(entityManager, entityToken, item, true);
+    // If timestamp present, compute exactly one hash key and return single pair.
+    const tsProp = entityManager.config.entities[entityToken].timestampProperty;
+    if (withRangeKey[tsProp] !== undefined) {
+        const withHashKey = updateItemHashKey(entityManager, entityToken, withRangeKey, true);
+        return [
+            {
+                [hashKey]: withHashKey[hashKey],
+                [rangeKey]: withHashKey[rangeKey],
+            },
+        ];
+    }
+    // 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 seen = new Set();
+    const keys = hashKeys
+        .map((hk) => {
+        const key = { [hashKey]: hk, [rangeKey]: rk };
+        const sig = `${hk}|${rk}`;
+        if (seen.has(sig))
+            return undefined;
+        seen.add(sig);
+        return key;
+    })
+        .filter((k) => !!k);
+    return keys;
 }
 
 export { getPrimaryKey };

package/package.json

@@ -131,5 +131,5 @@
   },
   "type": "module",
   "types": "dist/index.d.ts",
-  "version": "6.14.1"
+  "version": "6.14.3"
 }