@karmaniverous/entity-manager 6.10.2 → 6.11.0

package/dist/cjs/BaseEntityClient.js

@@ -13,10 +13,10 @@ class BaseEntityClient {
      *
      * @param options - {@link BaseEntityClientOptions | `BaseEntityClientOptions`} object.
      */
-    constructor(entityManager, options = {}) {
-        this.entityManager = entityManager;
-        const { batchProcessOptions = {}, logger = console } = options;
+    constructor(options) {
+        const { batchProcessOptions = {}, entityManager, logger = console, } = options;
         this.batchProcessOptions = batchProcessOptions;
+        this.entityManager = entityManager;
         this.logger = logger;
     }
 }

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

@@ -17,20 +17,6 @@ interface BaseConfigMap {
     TranscodeMap: TranscodeMap;
 }
 
-/**
- * Base EntityClient options.
- *
- * @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
- */
-interface BaseEntityClientOptions {
-    /** Default batch process options. */
-    batchProcessOptions?: Omit<BatchProcessOptions<unknown, unknown>, 'batchHandler' | 'unprocessedItemExtractor'>;
-    /** Injected logger object. Must support `debug` and `error` methods. Default: `console` */
-    logger?: Pick<Console, 'debug' | 'error'>;
-}
-
 /**
  * Defines a single time period in an entity sharding strategy.
  *
@@ -100,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`}.
  *
@@ -217,7 +213,6 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
 }, "strict", z.ZodTypeAny, {
     hashKey: string;
     rangeKey: string;
-    throttle: number;
     entities: Record<string, {
         defaultLimit: number;
         defaultPageSize: number;
@@ -242,6 +237,7 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
     generatedValueDelimiter: string;
     propertyTranscodes: Record<string, string>;
     shardKeyDelimiter: string;
+    throttle: number;
     transcodes: Record<string, {
         encode: (args_0: any, ...args: unknown[]) => string;
         decode: (args_0: string, ...args: unknown[]) => any;
@@ -249,7 +245,6 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
 }, {
     hashKey: string;
     rangeKey: string;
-    throttle?: number | undefined;
     entities?: Record<string, {
         timestampProperty: string;
         uniqueProperty: string;
@@ -274,6 +269,7 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
     generatedValueDelimiter?: string | undefined;
     propertyTranscodes?: Record<string, string> | undefined;
     shardKeyDelimiter?: string | undefined;
+    throttle?: number | undefined;
     transcodes?: Record<string, {
         encode: (args_0: any, ...args: unknown[]) => string;
         decode: (args_0: string, ...args: unknown[]) => any;
@@ -281,7 +277,6 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
 }>, {
     hashKey: string;
     rangeKey: string;
-    throttle: number;
     entities: Record<string, {
         defaultLimit: number;
         defaultPageSize: number;
@@ -306,6 +301,7 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
     generatedValueDelimiter: string;
     propertyTranscodes: Record<string, string>;
     shardKeyDelimiter: string;
+    throttle: number;
     transcodes: Record<string, {
         encode: (args_0: any, ...args: unknown[]) => string;
         decode: (args_0: string, ...args: unknown[]) => any;
@@ -313,7 +309,6 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
 }, {
     hashKey: string;
     rangeKey: string;
-    throttle?: number | undefined;
     entities?: Record<string, {
         timestampProperty: string;
         uniqueProperty: string;
@@ -338,6 +333,7 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
     generatedValueDelimiter?: string | undefined;
     propertyTranscodes?: Record<string, string> | undefined;
     shardKeyDelimiter?: string | undefined;
+    throttle?: number | undefined;
     transcodes?: Record<string, {
         encode: (args_0: any, ...args: unknown[]) => string;
         decode: (args_0: string, ...args: unknown[]) => any;
@@ -547,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.
      *
@@ -583,6 +591,22 @@ declare class EntityManager<C extends BaseConfigMap> {
     query(options: QueryOptions<C>): Promise<QueryResult<C>>;
 }
 
+/**
+ * Base EntityClient options.
+ *
+ * @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
+ */
+interface BaseEntityClientOptions<C extends BaseConfigMap> {
+    /** Default batch process options. */
+    batchProcessOptions?: Omit<BatchProcessOptions<unknown, unknown>, 'batchHandler' | 'unprocessedItemExtractor'>;
+    /** {@link EntityManager | `EntityManager`} instance. */
+    entityManager: EntityManager<C>;
+    /** Injected logger object. Must support `debug` and `error` methods. Default: `console` */
+    logger?: Pick<Console, 'debug' | 'error'>;
+}
+
 /**
  * Base EntityClient class. Integrates {@link EntityManager | `EntityManager`} with injected logging & enhanced batch processing.
  *
@@ -591,15 +615,18 @@ declare class EntityManager<C extends BaseConfigMap> {
  * @category EntityClient
  */
 declare abstract class BaseEntityClient<C extends BaseConfigMap> {
+    /** Default batch process options. */
+    readonly batchProcessOptions: NonNullable<BaseEntityClientOptions<C>['batchProcessOptions']>;
+    /** {@link EntityManager | `EntityManager`} instance. */
     readonly entityManager: EntityManager<C>;
-    readonly batchProcessOptions: NonNullable<BaseEntityClientOptions['batchProcessOptions']>;
-    readonly logger: NonNullable<BaseEntityClientOptions['logger']>;
+    /** Injected logger object. Must support `debug` and `error` methods. Default: `console` */
+    readonly logger: NonNullable<BaseEntityClientOptions<C>['logger']>;
     /**
      * DynamoDB EntityClient constructor.
      *
      * @param options - {@link BaseEntityClientOptions | `BaseEntityClientOptions`} object.
      */
-    constructor(entityManager: EntityManager<C>, options?: BaseEntityClientOptions);
+    constructor(options: BaseEntityClientOptions<C>);
 }
 
 /**
@@ -709,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/BaseEntityClient.js

@@ -11,10 +11,10 @@ class BaseEntityClient {
      *
      * @param options - {@link BaseEntityClientOptions | `BaseEntityClientOptions`} object.
      */
-    constructor(entityManager, options = {}) {
-        this.entityManager = entityManager;
-        const { batchProcessOptions = {}, logger = console } = options;
+    constructor(options) {
+        const { batchProcessOptions = {}, entityManager, logger = console, } = options;
         this.batchProcessOptions = batchProcessOptions;
+        this.entityManager = entityManager;
         this.logger = logger;
     }
 }

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

@@ -132,5 +132,5 @@
   },
   "type": "module",
   "types": "dist/index.d.ts",
-  "version": "6.10.2"
+  "version": "6.11.0"
 }