@karmaniverous/entity-manager 6.10.3 → 6.11.1

package/dist/cjs/EntityManager.js

@@ -1,6 +1,7 @@
 'use strict';
 
 var tslib = require('tslib');
+var radash = require('radash');
 var addKeys = require('./addKeys.js');
 var ParsedConfig = require('./ParsedConfig.js');
 var query = require('./query.js');
@@ -60,6 +61,23 @@ class EntityManager {
     addKeys(entityToken, item, overwrite = false) {
         return addKeys.addKeys(this, entityToken, item, overwrite);
     }
+    /**
+     * Convert an {@link EntityItem | `EntityItem`} into an {@link EntityKey | `EntityKey`}.
+     *
+     * @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.
+     *
+     * @throws `Error` if `entityToken` is invalid.
+     */
+    getPrimaryKey(entityToken, item, overwrite = false) {
+        const { hashKey, rangeKey } = this.config;
+        return radash.pick(!overwrite && item[hashKey] && item[rangeKey]
+            ? item
+            : addKeys.addKeys(this, entityToken, item, overwrite), [this.config.hashKey, this.config.rangeKey]);
+    }
     /**
      * Strips generated properties, hash key, and range key from an {@link EntityItem | `EntityItem`} object.
      *

package/dist/index.d.ts

@@ -86,6 +86,16 @@ type Config<C extends BaseConfigMap = BaseConfigMap> = ConditionalProperty<'enti
  */
 type EntityItem<C extends BaseConfigMap> = Partial<FlattenEntityMap<C['EntityMap']> & Record<C['HashKey'] | C['RangeKey'] | C['ShardedKeys'] | C['UnshardedKeys'], string>> & Record<string, unknown>;
 
+/**
+ * Database-facing record key type from a {@link BaseConfigMap | `ConfigMap`} with required hash & range keys.
+ *
+ * @typeParam C - {@link ConfigMap | `ConfigMap`} that defines an {@link Config | `EntityManager configuration`}'s {@link EntityMap | `EntityMap`}, key properties, and {@link TranscodeMap | `TranscodeMap`}. If omitted, defaults to {@link BaseConfigMap | `BaseConfigMap`}.
+ *
+ * @category EntityClient
+ * @protected
+ */
+type EntityKey<C extends BaseConfigMap> = Record<C['HashKey'] | C['RangeKey'], string>;
+
 /**
  * Extracts entity tokens from a {@link ConfigMap | `ConfigMap`}.
  *
@@ -533,6 +543,18 @@ declare class EntityManager<C extends BaseConfigMap> {
      * @throws `Error` if `entityToken` is invalid.
      */
     addKeys(entityToken: EntityToken<C>, item: EntityItem<C>, overwrite?: boolean): EntityItem<C>;
+    /**
+     * Convert an {@link EntityItem | `EntityItem`} into an {@link EntityKey | `EntityKey`}.
+     *
+     * @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.
+     *
+     * @throws `Error` if `entityToken` is invalid.
+     */
+    getPrimaryKey(entityToken: EntityToken<C>, item: EntityItem<C>, overwrite?: boolean): EntityKey<C>;
     /**
      * Strips generated properties, hash key, and range key from an {@link EntityItem | `EntityItem`} object.
      *
@@ -714,16 +736,6 @@ type ConfigMap<M extends Partial<BaseConfigMap> = Partial<BaseConfigMap>> = Vali
     TranscodeMap: 'TranscodeMap' extends keyof M ? NonNullable<M['TranscodeMap']> : DefaultTranscodeMap;
 }>;
 
-/**
- * Database-facing record key type from a {@link BaseConfigMap | `ConfigMap`} with required hash & range keys.
- *
- * @typeParam C - {@link ConfigMap | `ConfigMap`} that defines an {@link Config | `EntityManager configuration`}'s {@link EntityMap | `EntityMap`}, key properties, and {@link TranscodeMap | `TranscodeMap`}. If omitted, defaults to {@link BaseConfigMap | `BaseConfigMap`}.
- *
- * @category EntityClient
- * @protected
- */
-type EntityKey<C extends BaseConfigMap> = Record<C['HashKey'] | C['RangeKey'], string>;
-
 /**
  * Database-facing record type from a {@link BaseConfigMap | `ConfigMap`} with required hash & range keys.
  *

package/dist/mjs/EntityManager.js

@@ -1,4 +1,5 @@
 import { __classPrivateFieldSet, __classPrivateFieldGet } from 'tslib';
+import { pick } from 'radash';
 import { addKeys } from './addKeys.js';
 import { configSchema } from './ParsedConfig.js';
 import { query } from './query.js';
@@ -58,6 +59,23 @@ class EntityManager {
     addKeys(entityToken, item, overwrite = false) {
         return addKeys(this, entityToken, item, overwrite);
     }
+    /**
+     * Convert an {@link EntityItem | `EntityItem`} into an {@link EntityKey | `EntityKey`}.
+     *
+     * @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.
+     *
+     * @throws `Error` if `entityToken` is invalid.
+     */
+    getPrimaryKey(entityToken, item, overwrite = false) {
+        const { hashKey, rangeKey } = this.config;
+        return pick(!overwrite && item[hashKey] && item[rangeKey]
+            ? item
+            : addKeys(this, entityToken, item, overwrite), [this.config.hashKey, this.config.rangeKey]);
+    }
     /**
      * Strips generated properties, hash key, and range key from an {@link EntityItem | `EntityItem`} object.
      *

package/package.json

@@ -5,7 +5,7 @@
   },
   "dependencies": {
     "@karmaniverous/batch-process": "^0.1.0",
-    "@karmaniverous/entity-tools": "^0.6.2",
+    "@karmaniverous/entity-tools": "^0.6.4",
     "@karmaniverous/string-utilities": "^0.2.1",
     "lz-string": "^1.5.0",
     "radash": "^12.1.0",
@@ -14,7 +14,7 @@
   },
   "description": "Rational indexing & cross-shard querying at scale in your NoSQL database so you can focus on your application logic.",
   "devDependencies": {
-    "@dotenvx/dotenvx": "^1.22.0",
+    "@dotenvx/dotenvx": "^1.22.1",
     "@eslint/js": "^9.14.0",
     "@faker-js/faker": "^9.2.0",
     "@karmaniverous/mock-db": "^0.3.4",
@@ -132,5 +132,5 @@
   },
   "type": "module",
   "types": "dist/index.d.ts",
-  "version": "6.10.3"
+  "version": "6.11.1"
 }