@karmaniverous/entity-manager 6.3.1 → 6.4.0

package/dist/cjs/EntityManager.js

@@ -40,13 +40,13 @@ class EntityManager {
         tslib.__classPrivateFieldSet(this, _EntityManager_config, ParsedConfig.configSchema.parse(value), "f");
     }
     /**
-     * Update generated properties, hash key, and range key on an {@link ItemMap | `ItemMap`} object. Mutates `item`.
+     * Update generated properties, hash key, and range key on an {@link ItemMap | `ItemMap`} object.
      *
      * @param item - {@link ItemMap | `ItemMap`} object.
      * @param entityToken - {@link ConfigKeys.entities | `this.config.entities`} key.
      * @param overwrite - Overwrite existing properties (default `false`).
      *
-     * @returns Mutated `item` with updated properties.
+     * @returns Shallow clone of `item` with updated properties.
      *
      * @throws `Error` if `entityToken` is invalid.
      */
@@ -54,12 +54,12 @@ class EntityManager {
         return addKeys.addKeys(this, item, entityToken, overwrite);
     }
     /**
-     * Strips generated properties, hash key, and range key from an {@link ItemMap | `ItemMap`} object. Mutates `item`.
+     * Strips generated properties, hash key, and range key from an {@link ItemMap | `ItemMap`} object.
      *
      * @param item - {@link ItemMap | `ItemMap`} object.
      * @param entityToken - {@link ConfigKeys.entities | `this.config.entities`} key.
      *
-     * @returns Mutated `item` without generated properties, hash key or range key.
+     * @returns Shallow clone of `item` without generated properties, hash key or range key.
      *
      * @throws `Error` if `entityToken` is invalid.
      */

package/dist/cjs/addKeys.js

@@ -7,14 +7,14 @@ var updateItemRangeKey = require('./updateItemRangeKey.js');
 var validateEntityToken = require('./validateEntityToken.js');
 
 /**
- * Update generated properties, hash key, and range key on an {@link ItemMap | `ItemMap`} object. Mutates `item`.
+ * Update generated properties, hash key, and range key on an {@link ItemMap | `ItemMap`} object.
  *
  * @param entityManager - {@link EntityManager | `EntityManager`} instance.
  * @param item - {@link ItemMap | `ItemMap`} object.
  * @param entityToken - {@link ConfigKeys.entities | `this.config.entities`} key.
  * @param overwrite - Overwrite existing properties (default `false`).
  *
- * @returns Mutated `item` with updated properties.
+ * @returns Shallow clone of `item` with updated properties.
  *
  * @throws `Error` if `entityToken` is invalid.
  */
@@ -23,21 +23,21 @@ function addKeys(entityManager, item, entityToken, overwrite = false) {
         // Validate params.
         validateEntityToken.validateEntityToken(entityManager, entityToken);
         // Update hash key.
-        updateItemHashKey.updateItemHashKey(entityManager, item, entityToken, overwrite);
+        let newItem = updateItemHashKey.updateItemHashKey(entityManager, item, entityToken, overwrite);
         // Update range key.
-        updateItemRangeKey.updateItemRangeKey(entityManager, item, entityToken, overwrite);
+        newItem = updateItemRangeKey.updateItemRangeKey(entityManager, newItem, entityToken, overwrite);
         // Update generated properties.
         for (const property in entityManager.config.entities[entityToken]
             .generated) {
             if (overwrite || entityTools.isNil(item[property])) {
-                const encoded = encodeGeneratedProperty.encodeGeneratedProperty(entityManager, item, entityToken, property);
+                const encoded = encodeGeneratedProperty.encodeGeneratedProperty(entityManager, newItem, entityToken, property);
                 if (encoded)
-                    Object.assign(item, { [property]: encoded });
+                    Object.assign(newItem, { [property]: encoded });
                 else
-                    delete item[property];
+                    delete newItem[property];
             }
         }
-        return item;
+        return newItem;
     }
     catch (error) {
         throw error;

package/dist/cjs/rehydratePageKeyMap.js

@@ -46,11 +46,11 @@ function rehydratePageKeyMap(entityManager, dehydrated, entityToken, indexTokens
         const rehydrated = radash.mapValues(radash.zipToObject(indexTokens, radash.cluster(dehydrated, hashKeySpace.length)), (dehydratedIndexPageKeyMaps, index) => radash.zipToObject(hashKeySpace, (hashKey, i) => {
             if (!dehydratedIndexPageKeyMaps[i])
                 return;
-            const item = {
+            let item = {
                 [entityManager.config.hashKey]: hashKey,
                 ...rehydrateIndexItem.rehydrateIndexItem(entityManager, dehydratedIndexPageKeyMaps[i], entityToken, index, [entityManager.config.hashKey]),
             };
-            updateItemRangeKey.updateItemRangeKey(entityManager, item, entityToken);
+            item = updateItemRangeKey.updateItemRangeKey(entityManager, item, entityToken);
             return radash.zipToObject(entityManager.config.entities[entityToken].indexes[index], (component) => entityManager.config.entities[entityToken].generated[component]
                 ? encodeGeneratedProperty.encodeGeneratedProperty(entityManager, item, entityToken, component)
                 : item[component]);

package/dist/cjs/removeKeys.js

@@ -3,13 +3,13 @@
 var validateEntityToken = require('./validateEntityToken.js');
 
 /**
- * Strips generated properties, hash key, and range key from an {@link ItemMap | `ItemMap`} object. Mutates `item`.
+ * Strips generated properties, hash key, and range key from an {@link ItemMap | `ItemMap`} object.
  *
  * @param entityManager - {@link EntityManager | `EntityManager`} instance.
  * @param item - {@link ItemMap | `ItemMap`} object.
  * @param entityToken - {@link ConfigKeys.entities | `entityManager.config.entities`} key.
  *
- * @returns Mutated `item` without generated properties, hash key or range key.
+ * @returns Shallow clone of `item` without generated properties, hash key or range key.
  *
  * @throws `Error` if `entityToken` is invalid.
  */
@@ -18,12 +18,13 @@ function removeKeys(entityManager, item, entityToken) {
         // Validate params.
         validateEntityToken.validateEntityToken(entityManager, entityToken);
         // Delete hash & range keys.
-        delete item[entityManager.config.hashKey];
-        delete item[entityManager.config.rangeKey];
+        const newItem = { ...item };
+        delete newItem[entityManager.config.hashKey];
+        delete newItem[entityManager.config.rangeKey];
         // Delete generated properties.
         for (const property in entityManager.config.entities[entityToken].generated)
-            delete item[property];
-        return item;
+            delete newItem[property];
+        return newItem;
     }
     catch (error) {
         throw error;

package/dist/cjs/updateItemHashKey.js

@@ -6,14 +6,14 @@ var getShardBump = require('./getShardBump.js');
 var validateEntityToken = require('./validateEntityToken.js');
 
 /**
- * Update the hash key on a partial {@link ItemMap | `ItemMap`} object. Mutates `item`.
+ * Update the hash key on a partial {@link ItemMap | `ItemMap`} object.
  *
  * @param entityManager - {@link EntityManager | `EntityManager`} instance.
  * @param item - Partial {@link ItemMap | `ItemMap`} object.
  * @param entityToken - {@link ConfigKeys.entities | `this.config.entities`} key.
  * @param overwrite - Overwrite existing {@link ConfigKeys.hashKey | `this.config.hashKey`} property value (default `false`).
  *
- * @returns Mutated `item` with updated hash key.
+ * @returns Shallow clone of `item` with updated hash key.
  *
  * @throws `Error` if `entityToken` is invalid.
  */
@@ -23,7 +23,7 @@ function updateItemHashKey(entityManager, item, entityToken, overwrite = false)
         validateEntityToken.validateEntityToken(entityManager, entityToken);
         // Return current item if hashKey exists and overwrite is false.
         if (item[entityManager.config.hashKey] && !overwrite) {
-            return item;
+            return { ...item };
         }
         // Get item timestamp property & validate.
         const timestamp = item[entityManager.config.entities[entityToken].timestampProperty];
@@ -44,8 +44,8 @@ function updateItemHashKey(entityManager, item, entityToken, overwrite = false)
                 .toString(radix)
                 .padStart(chars, '0');
         }
-        Object.assign(item, { [entityManager.config.hashKey]: hashKey });
-        return item;
+        const newItem = Object.assign({ ...item }, { [entityManager.config.hashKey]: hashKey });
+        return newItem;
     }
     catch (error) {
         throw error;

package/dist/cjs/updateItemRangeKey.js

@@ -4,14 +4,14 @@ var entityTools = require('@karmaniverous/entity-tools');
 var validateEntityToken = require('./validateEntityToken.js');
 
 /**
- * Update the range key on a partial {@link ItemMap | `ItemMap`} object. Mutates `item`.
+ * Update the range key on a partial {@link ItemMap | `ItemMap`} object.
  *
  * @param entityManager - {@link EntityManager | `EntityManager`} instance.
  * @param item - Partial {@link ItemMap | `ItemMap`} object.
  * @param entityToken - {@link ConfigKeys.entities | `this.config.entities`} key.
  * @param overwrite - Overwrite existing {@link ConfigKeys.rangeKey | `this.config.rangeKey`} property value (default `false`).
  *
- * @returns Mutated `item` with updated range key.
+ * @returns Shallow clone of `item` with updated range key.
  *
  * @throws `Error` if `entityToken` is invalid.
  * @throws `Error` if `item` {@link ConfigEntity.uniqueProperty | `this.config.entities<entityToken>.uniqueProperty`} property value is missing.
@@ -22,20 +22,20 @@ function updateItemRangeKey(entityManager, item, entityToken, overwrite = false)
         validateEntityToken.validateEntityToken(entityManager, entityToken);
         // Return current item if rangeKey exists and overwrite is false.
         if (item[entityManager.config.rangeKey] && !overwrite) {
-            return item;
+            return { ...item };
         }
         // Get item unique property & validate.
         const uniqueProperty = item[entityManager.config.entities[entityToken].uniqueProperty];
         if (entityTools.isNil(uniqueProperty))
             throw new Error(`missing item unique property`);
         // Update range key.
-        Object.assign(item, {
+        const newItem = Object.assign({ ...item }, {
             [entityManager.config.rangeKey]: [
                 entityManager.config.entities[entityToken].uniqueProperty,
                 uniqueProperty,
             ].join(entityManager.config.generatedValueDelimiter),
         });
-        return item;
+        return newItem;
     }
     catch (error) {
         throw error;

package/dist/index.d.ts

@@ -788,24 +788,24 @@ declare class EntityManager<M extends EntityMap, HashKey extends string, RangeKe
      */
     set config(value: ParsedConfig);
     /**
-     * Update generated properties, hash key, and range key on an {@link ItemMap | `ItemMap`} object. Mutates `item`.
+     * Update generated properties, hash key, and range key on an {@link ItemMap | `ItemMap`} object.
      *
      * @param item - {@link ItemMap | `ItemMap`} object.
      * @param entityToken - {@link ConfigKeys.entities | `this.config.entities`} key.
      * @param overwrite - Overwrite existing properties (default `false`).
      *
-     * @returns Mutated `item` with updated properties.
+     * @returns Shallow clone of `item` with updated properties.
      *
      * @throws `Error` if `entityToken` is invalid.
      */
     addKeys<Item extends ItemMap<M, HashKey, RangeKey>[EntityToken], EntityToken extends keyof Exactify<M> & string>(item: Partial<Item>, entityToken: EntityToken, overwrite?: boolean): Partial<Item>;
     /**
-     * Strips generated properties, hash key, and range key from an {@link ItemMap | `ItemMap`} object. Mutates `item`.
+     * Strips generated properties, hash key, and range key from an {@link ItemMap | `ItemMap`} object.
      *
      * @param item - {@link ItemMap | `ItemMap`} object.
      * @param entityToken - {@link ConfigKeys.entities | `this.config.entities`} key.
      *
-     * @returns Mutated `item` without generated properties, hash key or range key.
+     * @returns Shallow clone of `item` without generated properties, hash key or range key.
      *
      * @throws `Error` if `entityToken` is invalid.
      */

package/dist/mjs/EntityManager.js

@@ -38,13 +38,13 @@ class EntityManager {
         __classPrivateFieldSet(this, _EntityManager_config, configSchema.parse(value), "f");
     }
     /**
-     * Update generated properties, hash key, and range key on an {@link ItemMap | `ItemMap`} object. Mutates `item`.
+     * Update generated properties, hash key, and range key on an {@link ItemMap | `ItemMap`} object.
      *
      * @param item - {@link ItemMap | `ItemMap`} object.
      * @param entityToken - {@link ConfigKeys.entities | `this.config.entities`} key.
      * @param overwrite - Overwrite existing properties (default `false`).
      *
-     * @returns Mutated `item` with updated properties.
+     * @returns Shallow clone of `item` with updated properties.
      *
      * @throws `Error` if `entityToken` is invalid.
      */
@@ -52,12 +52,12 @@ class EntityManager {
         return addKeys(this, item, entityToken, overwrite);
     }
     /**
-     * Strips generated properties, hash key, and range key from an {@link ItemMap | `ItemMap`} object. Mutates `item`.
+     * Strips generated properties, hash key, and range key from an {@link ItemMap | `ItemMap`} object.
      *
      * @param item - {@link ItemMap | `ItemMap`} object.
      * @param entityToken - {@link ConfigKeys.entities | `this.config.entities`} key.
      *
-     * @returns Mutated `item` without generated properties, hash key or range key.
+     * @returns Shallow clone of `item` without generated properties, hash key or range key.
      *
      * @throws `Error` if `entityToken` is invalid.
      */

package/dist/mjs/addKeys.js

@@ -5,14 +5,14 @@ import { updateItemRangeKey } from './updateItemRangeKey.js';
 import { validateEntityToken } from './validateEntityToken.js';
 
 /**
- * Update generated properties, hash key, and range key on an {@link ItemMap | `ItemMap`} object. Mutates `item`.
+ * Update generated properties, hash key, and range key on an {@link ItemMap | `ItemMap`} object.
  *
  * @param entityManager - {@link EntityManager | `EntityManager`} instance.
  * @param item - {@link ItemMap | `ItemMap`} object.
  * @param entityToken - {@link ConfigKeys.entities | `this.config.entities`} key.
  * @param overwrite - Overwrite existing properties (default `false`).
  *
- * @returns Mutated `item` with updated properties.
+ * @returns Shallow clone of `item` with updated properties.
  *
  * @throws `Error` if `entityToken` is invalid.
  */
@@ -21,21 +21,21 @@ function addKeys(entityManager, item, entityToken, overwrite = false) {
         // Validate params.
         validateEntityToken(entityManager, entityToken);
         // Update hash key.
-        updateItemHashKey(entityManager, item, entityToken, overwrite);
+        let newItem = updateItemHashKey(entityManager, item, entityToken, overwrite);
         // Update range key.
-        updateItemRangeKey(entityManager, item, entityToken, overwrite);
+        newItem = updateItemRangeKey(entityManager, newItem, entityToken, overwrite);
         // Update generated properties.
         for (const property in entityManager.config.entities[entityToken]
             .generated) {
             if (overwrite || isNil(item[property])) {
-                const encoded = encodeGeneratedProperty(entityManager, item, entityToken, property);
+                const encoded = encodeGeneratedProperty(entityManager, newItem, entityToken, property);
                 if (encoded)
-                    Object.assign(item, { [property]: encoded });
+                    Object.assign(newItem, { [property]: encoded });
                 else
-                    delete item[property];
+                    delete newItem[property];
             }
         }
-        return item;
+        return newItem;
     }
     catch (error) {
         throw error;

package/dist/mjs/rehydratePageKeyMap.js

@@ -44,11 +44,11 @@ function rehydratePageKeyMap(entityManager, dehydrated, entityToken, indexTokens
         const rehydrated = mapValues(zipToObject(indexTokens, cluster(dehydrated, hashKeySpace.length)), (dehydratedIndexPageKeyMaps, index) => zipToObject(hashKeySpace, (hashKey, i) => {
             if (!dehydratedIndexPageKeyMaps[i])
                 return;
-            const item = {
+            let item = {
                 [entityManager.config.hashKey]: hashKey,
                 ...rehydrateIndexItem(entityManager, dehydratedIndexPageKeyMaps[i], entityToken, index, [entityManager.config.hashKey]),
             };
-            updateItemRangeKey(entityManager, item, entityToken);
+            item = updateItemRangeKey(entityManager, item, entityToken);
             return zipToObject(entityManager.config.entities[entityToken].indexes[index], (component) => entityManager.config.entities[entityToken].generated[component]
                 ? encodeGeneratedProperty(entityManager, item, entityToken, component)
                 : item[component]);

package/dist/mjs/removeKeys.js

@@ -1,13 +1,13 @@
 import { validateEntityToken } from './validateEntityToken.js';
 
 /**
- * Strips generated properties, hash key, and range key from an {@link ItemMap | `ItemMap`} object. Mutates `item`.
+ * Strips generated properties, hash key, and range key from an {@link ItemMap | `ItemMap`} object.
  *
  * @param entityManager - {@link EntityManager | `EntityManager`} instance.
  * @param item - {@link ItemMap | `ItemMap`} object.
  * @param entityToken - {@link ConfigKeys.entities | `entityManager.config.entities`} key.
  *
- * @returns Mutated `item` without generated properties, hash key or range key.
+ * @returns Shallow clone of `item` without generated properties, hash key or range key.
  *
  * @throws `Error` if `entityToken` is invalid.
  */
@@ -16,12 +16,13 @@ function removeKeys(entityManager, item, entityToken) {
         // Validate params.
         validateEntityToken(entityManager, entityToken);
         // Delete hash & range keys.
-        delete item[entityManager.config.hashKey];
-        delete item[entityManager.config.rangeKey];
+        const newItem = { ...item };
+        delete newItem[entityManager.config.hashKey];
+        delete newItem[entityManager.config.rangeKey];
         // Delete generated properties.
         for (const property in entityManager.config.entities[entityToken].generated)
-            delete item[property];
-        return item;
+            delete newItem[property];
+        return newItem;
     }
     catch (error) {
         throw error;

package/dist/mjs/updateItemHashKey.js

@@ -4,14 +4,14 @@ import { getShardBump } from './getShardBump.js';
 import { validateEntityToken } from './validateEntityToken.js';
 
 /**
- * Update the hash key on a partial {@link ItemMap | `ItemMap`} object. Mutates `item`.
+ * Update the hash key on a partial {@link ItemMap | `ItemMap`} object.
  *
  * @param entityManager - {@link EntityManager | `EntityManager`} instance.
  * @param item - Partial {@link ItemMap | `ItemMap`} object.
  * @param entityToken - {@link ConfigKeys.entities | `this.config.entities`} key.
  * @param overwrite - Overwrite existing {@link ConfigKeys.hashKey | `this.config.hashKey`} property value (default `false`).
  *
- * @returns Mutated `item` with updated hash key.
+ * @returns Shallow clone of `item` with updated hash key.
  *
  * @throws `Error` if `entityToken` is invalid.
  */
@@ -21,7 +21,7 @@ function updateItemHashKey(entityManager, item, entityToken, overwrite = false)
         validateEntityToken(entityManager, entityToken);
         // Return current item if hashKey exists and overwrite is false.
         if (item[entityManager.config.hashKey] && !overwrite) {
-            return item;
+            return { ...item };
         }
         // Get item timestamp property & validate.
         const timestamp = item[entityManager.config.entities[entityToken].timestampProperty];
@@ -42,8 +42,8 @@ function updateItemHashKey(entityManager, item, entityToken, overwrite = false)
                 .toString(radix)
                 .padStart(chars, '0');
         }
-        Object.assign(item, { [entityManager.config.hashKey]: hashKey });
-        return item;
+        const newItem = Object.assign({ ...item }, { [entityManager.config.hashKey]: hashKey });
+        return newItem;
     }
     catch (error) {
         throw error;

package/dist/mjs/updateItemRangeKey.js

@@ -2,14 +2,14 @@ import { isNil } from '@karmaniverous/entity-tools';
 import { validateEntityToken } from './validateEntityToken.js';
 
 /**
- * Update the range key on a partial {@link ItemMap | `ItemMap`} object. Mutates `item`.
+ * Update the range key on a partial {@link ItemMap | `ItemMap`} object.
  *
  * @param entityManager - {@link EntityManager | `EntityManager`} instance.
  * @param item - Partial {@link ItemMap | `ItemMap`} object.
  * @param entityToken - {@link ConfigKeys.entities | `this.config.entities`} key.
  * @param overwrite - Overwrite existing {@link ConfigKeys.rangeKey | `this.config.rangeKey`} property value (default `false`).
  *
- * @returns Mutated `item` with updated range key.
+ * @returns Shallow clone of `item` with updated range key.
  *
  * @throws `Error` if `entityToken` is invalid.
  * @throws `Error` if `item` {@link ConfigEntity.uniqueProperty | `this.config.entities<entityToken>.uniqueProperty`} property value is missing.
@@ -20,20 +20,20 @@ function updateItemRangeKey(entityManager, item, entityToken, overwrite = false)
         validateEntityToken(entityManager, entityToken);
         // Return current item if rangeKey exists and overwrite is false.
         if (item[entityManager.config.rangeKey] && !overwrite) {
-            return item;
+            return { ...item };
         }
         // Get item unique property & validate.
         const uniqueProperty = item[entityManager.config.entities[entityToken].uniqueProperty];
         if (isNil(uniqueProperty))
             throw new Error(`missing item unique property`);
         // Update range key.
-        Object.assign(item, {
+        const newItem = Object.assign({ ...item }, {
             [entityManager.config.rangeKey]: [
                 entityManager.config.entities[entityToken].uniqueProperty,
                 uniqueProperty,
             ].join(entityManager.config.generatedValueDelimiter),
         });
-        return item;
+        return newItem;
     }
     catch (error) {
         throw error;

package/package.json

@@ -4,7 +4,7 @@
     "url": "https://github.com/karmaniverous/entity-manager/issues"
   },
   "dependencies": {
-    "@karmaniverous/entity-tools": "^0.3.0",
+    "@karmaniverous/entity-tools": "^0.3.1",
     "@karmaniverous/string-utilities": "^0.2.1",
     "jsonschema": "^1.4.1",
     "lz-string": "^1.5.0",
@@ -14,10 +14,10 @@
   },
   "description": "Rational indexing & cross-shard querying at scale in your NoSQL database so you can focus on your application logic.",
   "devDependencies": {
-    "@dotenvx/dotenvx": "^1.16.0",
+    "@dotenvx/dotenvx": "^1.16.1",
     "@eslint/js": "^9.12.0",
     "@faker-js/faker": "^9.0.3",
-    "@karmaniverous/mock-db": "^0.3.2",
+    "@karmaniverous/mock-db": "^0.3.3",
     "@rollup/plugin-alias": "^5.1.1",
     "@rollup/plugin-commonjs": "^28.0.0",
     "@rollup/plugin-json": "^6.1.0",
@@ -40,7 +40,7 @@
     "eslint-plugin-simple-import-sort": "^12.1.1",
     "eslint-plugin-tsdoc": "^0.3.0",
     "jsdom-global": "^3.0.2",
-    "knip": "^5.33.1",
+    "knip": "^5.33.2",
     "lefthook": "^1.7.18",
     "mocha": "^10.7.3",
     "nyc": "^17.1.0",
@@ -56,7 +56,7 @@
     "typedoc-plugin-mdn-links": "^3.3.2",
     "typedoc-plugin-replace-text": "^4.0.0",
     "typedoc-plugin-zod": "^1.2.1",
-    "typescript": "^5.6.2",
+    "typescript": "^5.6.3",
     "typescript-eslint": "^8.8.1"
   },
   "exports": {
@@ -132,5 +132,5 @@
   },
   "type": "module",
   "types": "dist/index.d.ts",
-  "version": "6.3.1"
+  "version": "6.4.0"
 }