@karmaniverous/entity-manager 5.0.8 → 5.0.10

package/.github/FUNDING.yml

@@ -0,0 +1,3 @@
+# These are supported funding model platforms
+
+github: [karmaniverous]

package/README.md

@@ -452,5 +452,4 @@ Shard query function
 
 ---
 
-See more great templates and other tools on
-[my GitHub Profile](https://github.com/karmaniverous)!
+Built with ❤️ on Bali! Find more great tools & templates on [my GitHub Profile](https://github.com/karmaniverous).

package/dist/cjs/BaseEntityClient/BaseEntityClient.js

@@ -0,0 +1,28 @@
+'use strict';
+
+/**
+ * Base EntityClient class. Integrates {@link EntityManager | `EntityManager`} with injected logging & enhanced batch processing.
+ *
+ * @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`}.
+ * @typeParam CF - Values-first config literal type captured by the manager (phantom; type-only). Propagated so
+ *                 client-facing calls that return `IndexTokensOf<CF>` retain the narrowed union.
+ *
+ * @category EntityClient
+ */
+class BaseEntityClient {
+    /**
+     * Base EntityClient constructor.
+     *
+     * @param options - {@link BaseEntityClientOptions | `BaseEntityClientOptions`} object.
+     */
+    constructor(options) {
+        const { batchProcessOptions = {}, entityManager, logger = console, } = options;
+        this.batchProcessOptions = batchProcessOptions;
+        this.entityManager = entityManager;
+        this.logger = logger;
+    }
+}
+
+exports.BaseEntityClient = BaseEntityClient;

package/dist/cjs/BaseQueryBuilder/BaseQueryBuilder.js

@@ -0,0 +1,62 @@
+'use strict';
+
+var radash = require('radash');
+
+/* eslint-disable @typescript-eslint/no-unused-vars */
+/**
+ * Abstract base class supporting a fluent API for building a {@link ShardQueryMap | `ShardQueryMap`} using a database client.
+ *
+ * @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`}.
+ * @typeParam EntityClient - {@link BaseEntityClient | `BaseEntityClient`} derived class instance.
+ * @typeParam IndexParams - Database platform-specific, index-specific query parameters.
+ * @typeParam CF - Optional values-first config literal type for page key narrowing.
+ * @typeParam K - Optional projection keys; narrows item shape when provided.
+ *
+ * @category QueryBuilder
+ */
+class BaseQueryBuilder {
+    /** BaseQueryBuilder constructor. */
+    constructor(options) {
+        /**
+         * Maps `indexToken` values to database platform-specific query parameters.
+         *
+         * @protected
+         */
+        this.indexParamsMap = {};
+        const { entityClient, entityToken, hashKeyToken, pageKeyMap } = options;
+        this.entityClient = entityClient;
+        this.entityToken = entityToken;
+        this.hashKeyToken = hashKeyToken;
+        this.pageKeyMap = pageKeyMap;
+    }
+    /**
+     * Builds a {@link ShardQueryMap | `ShardQueryMap`} object.
+     *
+     * @returns - The {@link ShardQueryMap | `ShardQueryMap`} object.
+     */
+    build() {
+        return radash.mapValues(this.indexParamsMap, (_indexConfig, indexToken) => this.getShardQueryFunction(indexToken));
+    }
+    /**
+     * Execute the built query across shards and indexes via {@link EntityManager.query | `EntityManager.query`}.
+     *
+     * @param options - Query options excluding `entityToken`, `pageKeyMap`, and `shardQueryMap`, which are supplied by the builder.
+     *
+     * @returns The merged, de-duplicated, sorted query result, including a compact `pageKeyMap` token for the next page.
+     *
+     * @remarks
+     * This delegates orchestration to Entity Manager; provider-specific behavior lives in {@link getShardQueryFunction | `getShardQueryFunction`}.
+     */
+    async query(options) {
+        const { entityClient: { entityManager }, entityToken, pageKeyMap, } = this;
+        const shardQueryMap = this.build();
+        return await entityManager.query({
+            ...options,
+            entityToken,
+            pageKeyMap,
+            shardQueryMap,
+        });
+    }
+}
+
+exports.BaseQueryBuilder = BaseQueryBuilder;

package/dist/cjs/EntityManager/EntityManager.js

@@ -0,0 +1,131 @@
+'use strict';
+
+var tslib = require('tslib');
+var addKeys = require('./addKeys.js');
+var encodeGeneratedProperty = require('./encodeGeneratedProperty.js');
+var findIndexToken = require('./findIndexToken.js');
+var getPrimaryKey = require('./getPrimaryKey.js');
+var ParsedConfig = require('./ParsedConfig.js');
+var query = require('./query.js');
+var removeKeys = require('./removeKeys.js');
+
+var _EntityManager_config;
+/**
+ * The EntityManager class applies a configuration-driven sharded data model &
+ * query strategy to NoSql data.
+ *
+ * @typeParam CC - {@link ConfigMap | `ConfigMap`} that defines the configuration's {@link EntityMap | `EntityMap`}, key properties, and {@link TranscodeRegistry | `TranscodeRegistry`}. If omitted, defaults to {@link BaseConfigMap | `BaseConfigMap`}.
+ * @typeParam CF - Values-first config literal type captured at construction
+ *                 time (phantom generic; type-only). This is used by downstream
+ *                 adapters to infer index-token unions (ITS) and per-index page
+ *                 key shapes.
+ *
+ * @remarks
+ * While the {@link EntityManager.query | `query`} method is `public`, normally it should not be called directly. The `query` method is used by a platform-specific {@link BaseQueryBuilder.query | `QueryBuilder.query`} method to provide a fluent query API.
+ *
+ * @category EntityManager
+ */
+class EntityManager {
+    /**
+     * Create an EntityManager instance.
+     *
+     * @param config - EntityManager {@link Config | `Config`} object.
+     * @param logger - Logger object (defaults to `console`, must support `debug` & `error` methods).
+     */
+    constructor(config, logger = console) {
+        _EntityManager_config.set(this, void 0);
+        // Accept a compile-time-only `entitiesSchema` key on values-first configs.
+        // We strip it here so the same literal config can be used with either the
+        // factory or the direct constructor without tripping Zod's strict parser.
+        //
+        // This keeps runtime semantics unchanged and avoids widening ParsedConfig.
+        const cfgWithOptionalES = config;
+        const { entitiesSchema: _ignored, ...configForParse } = cfgWithOptionalES;
+        tslib.__classPrivateFieldSet(this, _EntityManager_config, ParsedConfig.configSchema.parse(configForParse), "f");
+        this.logger = logger;
+    }
+    /**
+     * Get the current EntityManager {@link Config | `Config`} object.
+     *
+     * @returns Current {@link Config | `Config`} object.
+     */
+    get config() {
+        return tslib.__classPrivateFieldGet(this, _EntityManager_config, "f");
+    }
+    /**
+     * Set the current EntityManager {@link Config | `Config`} object.
+     *
+     * @param value - {@link Config | `Config`} object.
+     */
+    set config(value) {
+        tslib.__classPrivateFieldSet(this, _EntityManager_config, ParsedConfig.configSchema.parse(value), "f");
+    }
+    /**
+     * 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 StorageItem | `StorageItem`} object.
+     *
+     * @returns Encoded generated property value.
+     *
+     * @throws `Error` if `property` is not a {@link Config | Config} `generatedProperties` key.
+     */
+    encodeGeneratedProperty(property, item) {
+        return encodeGeneratedProperty.encodeGeneratedProperty(this, property, item);
+    }
+    addKeys(entityToken, i, overwrite = false) {
+        if (Array.isArray(i)) {
+            return i.map((item) => addKeys.addKeys(this, entityToken, item, overwrite));
+        }
+        return addKeys.addKeys(this, entityToken, i, overwrite);
+    }
+    getPrimaryKey(entityToken, i, overwrite = false) {
+        if (Array.isArray(i)) {
+            return i.flatMap((item) => getPrimaryKey.getPrimaryKey(this, entityToken, item, overwrite));
+        }
+        return getPrimaryKey.getPrimaryKey(this, entityToken, i, overwrite);
+    }
+    removeKeys(entityToken, i) {
+        if (Array.isArray(i)) {
+            const out = i.map((item) => removeKeys.removeKeys(this, entityToken, item));
+            return out;
+        }
+        const out = removeKeys.removeKeys(this, entityToken, i);
+        return out;
+    }
+    findIndexToken(hashKeyToken, rangeKeyToken, suppressError) {
+        // Dispatch with a literal to satisfy overload selection.
+        return suppressError === true
+            ? findIndexToken.findIndexToken(this, hashKeyToken, rangeKeyToken, true)
+            : findIndexToken.findIndexToken(this, hashKeyToken, rangeKeyToken, false);
+    }
+    /**
+     * Query a database entity across shards in a provider-generic fashion.
+     *
+     * @remarks
+     * The provided `shardQueryMap` performs the actual query of individual data pages on individual index/shard combinations.
+     *
+     * Individual shard query results will be combined, deduped by {@link Config | `Config`} `uniqueProperty` value, and sorted by {@link QueryOptions.sortOrder | `sortOrder`}.
+     *
+     * In queries on sharded data, expect the leading and trailing edges of returned data pages to interleave somewhat with preceding & following pages.
+     *
+     * Unsharded query results should sort & page as expected.
+     *
+     * **Normally this method should not be called directly!** It is used by a platform-specific {@link BaseQueryBuilder.query | `QueryBuilder.query`} method to provide a fluent query API.
+     *
+     * @param options - {@link QueryOptions | `QueryOptions`} object.
+     *
+     * @returns {@link QueryResult} object.
+     *
+     * @throws Error if `options` {@link QueryOptions.pageKeyMap | `pageKeyMap`} `pageKeyMap` keys do not match {@link QueryOptions.shardQueryMap | `shardQueryMap`} keys.
+     *
+     * @protected
+     */
+    async query(options) {
+        const result = await query.query(this, options);
+        return result;
+    }
+}
+_EntityManager_config = new WeakMap();
+
+exports.EntityManager = EntityManager;

package/dist/cjs/EntityManager/ParsedConfig.js

@@ -0,0 +1,385 @@
+'use strict';
+
+var entityTools = require('@karmaniverous/entity-tools');
+var radash = require('radash');
+var zod = require('zod');
+
+const defaultShardBump = { timestamp: 0, charBits: 1, chars: 0 };
+const validateArrayUnique = (arr, ctx, identity = (item) => item, path = []) => {
+    const counts = radash.counting(arr, identity);
+    for (const [element, count] of Object.entries(counts)) {
+        if (count > 1)
+            ctx.addIssue({
+                code: 'custom',
+                message: `duplicate array element`,
+                params: { element },
+                path,
+            });
+    }
+};
+const validateKeysExclusive = (keys, label, ref, ctx) => {
+    const intersection = keys.filter((key) => ref.includes(key));
+    if (intersection.length)
+        ctx.addIssue({
+            code: 'custom',
+            message: `${label} key collision: ${intersection.toString()}`,
+        });
+};
+const componentArray = zod.z
+    .array(zod.z.string().min(1))
+    .nonempty()
+    .superRefine(validateArrayUnique);
+/**
+ * Runtime configuration schema for {@link EntityManager | `EntityManager`}.
+ *
+ * @remarks
+ * This is authoritative at runtime and used internally by the {@link EntityManager | `EntityManager`} constructor.
+ * It is also used by tests. It is not intended as a user-facing TypeDoc artifact.
+ *
+ * @hidden
+ */
+const configSchema = zod.z
+    .object({
+    entities: zod.z
+        .record(zod.z.string(), zod.z
+        .object({
+        defaultLimit: zod.z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .default(10)
+            .describe('Default max items returned by EntityManager.query for this entity (across all shards).'),
+        defaultPageSize: zod.z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .default(10)
+            .describe('Default per-shard page size used by EntityManager.query for this entity.'),
+        shardBumps: zod.z
+            .array(zod.z
+            .object({
+            timestamp: zod.z
+                .number()
+                .int()
+                .nonnegative()
+                .describe('Start timestamp (ms) for this shard bump (inclusive).'),
+            charBits: zod.z
+                .number()
+                .int()
+                .min(1)
+                .max(5)
+                .describe('Bits per shard character (radix = 2**charBits).'),
+            chars: zod.z
+                .number()
+                .int()
+                .min(0)
+                .max(40)
+                .describe('Shard suffix width (chars); controls shard space.'),
+        })
+            .strict())
+            .optional()
+            .default([defaultShardBump])
+            // validate shardBump uniqueness by timestamp.
+            .superRefine((val, ctx) => {
+            validateArrayUnique(val, ctx, ({ timestamp }) => timestamp, [
+                'timestamp',
+            ]);
+        })
+            .transform((val) => {
+            // sort shardBumps by timestamp.
+            let sorted = radash.sort(val, ({ timestamp }) => timestamp);
+            // prepend defaultShardBump if missing zero-timestamp bump.
+            if (sorted[0].timestamp !== 0) {
+                sorted = [defaultShardBump, ...sorted];
+            }
+            return sorted;
+        })
+            // validate shardBump chars mootonically increase with timestamp.
+            .superRefine((val, ctx) => {
+            if (val.length > 1) {
+                for (let i = 1; i < val.length; i++)
+                    if (val[i].chars <= val[i - 1].chars)
+                        ctx.addIssue({
+                            code: 'custom',
+                            message: `shardBump chars do not monotonically increase at timestamp ${val[i].timestamp.toString()}`,
+                            path: [i],
+                        });
+            }
+        }),
+        timestampProperty: zod.z
+            .string()
+            .min(1)
+            .describe('Property token whose value selects the shard bump (typically a timestamp).'),
+        uniqueProperty: zod.z
+            .string()
+            .min(1)
+            .describe('Property token used to dedupe and build the global range key.'),
+    })
+        .strict())
+        .optional()
+        .default({})
+        .describe('Entity definitions keyed by entity token.'),
+    generatedProperties: zod.z
+        .object({
+        sharded: zod.z
+            .record(zod.z.string(), componentArray)
+            .optional()
+            .default({})
+            .describe('Sharded generated property tokens (hash-side); atomic encoding semantics.'),
+        unsharded: zod.z
+            .record(zod.z.string(), componentArray)
+            .optional()
+            .default({})
+            .describe('Unsharded generated property tokens (range-side); non-atomic encoding semantics.'),
+    })
+        .optional()
+        .default({ sharded: {}, unsharded: {} }),
+    hashKey: zod.z.string().describe('Global hash key property name.'),
+    indexes: zod.z
+        .record(zod.z.string(), zod.z.object({
+        hashKey: zod.z
+            .string()
+            .min(1)
+            .describe('Index hash key token (global hash key or a sharded generated key).'),
+        rangeKey: zod.z
+            .string()
+            .min(1)
+            .describe('Index range key token (global range key, an unsharded generated key, or a transcoded property).'),
+        projections: zod.z
+            .array(zod.z.string().min(1))
+            .superRefine(validateArrayUnique)
+            .optional(),
+    }))
+        .optional()
+        .default({})
+        .describe('Index definitions keyed by index token.'),
+    generatedKeyDelimiter: zod.z
+        .string()
+        .regex(/\W+/)
+        .optional()
+        .default('|')
+        .describe('Delimiter between generated key elements (default `|`).'),
+    generatedValueDelimiter: zod.z
+        .string()
+        .regex(/\W+/)
+        .optional()
+        .default('#')
+        .describe('Delimiter between generated element name and value (default `#`).'),
+    propertyTranscodes: zod.z.record(zod.z.string(), zod.z.string()).optional().default({}),
+    rangeKey: zod.z.string().describe('Global range key property name.'),
+    shardKeyDelimiter: zod.z
+        .string()
+        .regex(/\W+/)
+        .optional()
+        .default('!')
+        .describe('Delimiter between entity token and shard suffix in hash key values.'),
+    throttle: zod.z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .default(10)
+        .describe('Default max concurrency for shard queries during EntityManager.query.'),
+    transcodes: zod.z
+        .record(zod.z.string(), zod.z
+        .object({
+        // Accept function shapes without relying on z.function()
+        // to avoid TS inference conflicts across Zod versions and
+        // to remain compatible with narrower parameter types.
+        encode: zod.z
+            .custom((fn) => typeof fn === 'function')
+            .describe('Encode a value to a lexicographically sortable string.'),
+        decode: zod.z
+            .custom((fn) => typeof fn === 'function')
+            .describe('Decode a previously encoded string back to the value type.'),
+    })
+        .strict())
+        .optional()
+        .default(entityTools.defaultTranscodes),
+})
+    .strict()
+    .superRefine((data, ctx) => {
+    // validate no generated key delimiter collision
+    if (data.generatedKeyDelimiter.includes(data.generatedValueDelimiter))
+        ctx.addIssue({
+            code: 'custom',
+            message: 'generatedKeyDelimiter contains generatedValueDelimiter',
+            params: {
+                generatedKeyDelimiter: data.generatedKeyDelimiter,
+                generatedValueDelimiter: data.generatedValueDelimiter,
+            },
+            path: ['generatedKeyDelimiter'],
+        });
+    if (data.generatedKeyDelimiter.includes(data.shardKeyDelimiter))
+        ctx.addIssue({
+            code: 'custom',
+            message: 'generatedKeyDelimiter contains shardKeyDelimiter',
+            params: {
+                generatedKeyDelimiter: data.generatedKeyDelimiter,
+                shardKeyDelimiter: data.shardKeyDelimiter,
+            },
+            path: ['generatedKeyDelimiter'],
+        });
+    // validate no generated value delimiter collision
+    if (data.generatedValueDelimiter.includes(data.generatedKeyDelimiter))
+        ctx.addIssue({
+            code: 'custom',
+            message: 'generatedValueDelimiter contains generatedKeyDelimiter',
+            params: {
+                generatedValueDelimiter: data.generatedValueDelimiter,
+                generatedKeyDelimiter: data.generatedKeyDelimiter,
+            },
+            path: ['generatedValueDelimiter'],
+        });
+    if (data.generatedValueDelimiter.includes(data.shardKeyDelimiter))
+        ctx.addIssue({
+            code: 'custom',
+            message: 'generatedValueDelimiter contains shardKeyDelimiter',
+            params: {
+                generatedValueDelimiter: data.generatedValueDelimiter,
+                shardKeyDelimiter: data.shardKeyDelimiter,
+            },
+            path: ['generatedValueDelimiter'],
+        });
+    // validate no shard key delimiter collision
+    if (data.shardKeyDelimiter.includes(data.generatedKeyDelimiter))
+        ctx.addIssue({
+            code: 'custom',
+            message: 'shardKeyDelimiter contains generatedKeyDelimiter',
+            params: {
+                generatedKeyDelimiter: data.generatedKeyDelimiter,
+                shardKeyDelimiter: data.shardKeyDelimiter,
+            },
+            path: ['shardKeyDelimiter'],
+        });
+    if (data.shardKeyDelimiter.includes(data.generatedValueDelimiter))
+        ctx.addIssue({
+            code: 'custom',
+            message: 'shardKeyDelimiter contains generatedValueDelimiter',
+            params: {
+                generatedValueDelimiter: data.generatedValueDelimiter,
+                shardKeyDelimiter: data.shardKeyDelimiter,
+            },
+            path: ['shardKeyDelimiter'],
+        });
+    // get reserved keys
+    const shardedKeys = Object.keys(data.generatedProperties.sharded);
+    const unshardedKeys = Object.keys(data.generatedProperties.unsharded);
+    const transcodedProperties = Object.keys(data.propertyTranscodes);
+    // validate hashKey exclusive.
+    validateKeysExclusive([data.hashKey], 'hashKey', [
+        data.rangeKey,
+        ...shardedKeys,
+        ...unshardedKeys,
+        ...transcodedProperties,
+    ], ctx);
+    // validate rangeKey exclusive.
+    validateKeysExclusive([data.rangeKey], 'rangeKey', [...shardedKeys, ...unshardedKeys, ...transcodedProperties], ctx);
+    // validate shardedKeys exclusive.
+    validateKeysExclusive(shardedKeys, 'shardedKeys', [...unshardedKeys, ...transcodedProperties], ctx);
+    // validate unshardedKeys exclusive.
+    validateKeysExclusive(unshardedKeys, 'unshardedKeys', transcodedProperties, ctx);
+    // validate all propertyTranscode values are transcode keys.
+    const transcodes = Object.keys(data.transcodes);
+    for (const [property, transcode] of Object.entries(data.propertyTranscodes))
+        if (!transcodes.includes(transcode))
+            ctx.addIssue({
+                code: 'custom',
+                message: `propertyTranscodes['${property}'] references unknown transcode '${transcode}'`,
+                path: ['propertyTranscodes', property],
+            });
+    // Validate all sharded property elements are transcoded properties.
+    for (const [property, elements] of Object.entries(data.generatedProperties.sharded))
+        for (const element of elements)
+            if (!transcodedProperties.includes(element))
+                ctx.addIssue({
+                    code: 'custom',
+                    message: `generatedProperties.sharded['${property}'] contains non-transcoded element '${element}'`,
+                    path: ['generatedProperties', 'sharded', property],
+                });
+    // Validate all unsharded property elements are transcoded properties.
+    for (const [property, elements] of Object.entries(data.generatedProperties.unsharded))
+        for (const element of elements)
+            if (!transcodedProperties.includes(element))
+                ctx.addIssue({
+                    code: 'custom',
+                    message: `generatedProperties.unsharded['${property}'] contains non-transcoded element '${element}'`,
+                    path: ['generatedProperties', 'unsharded', property],
+                });
+    // Validate indexes.
+    // Validate no two indexes have the same hashKey & rangeKey.
+    const seenIndexPairs = new Set();
+    for (const [indexKey, { hashKey, rangeKey, projections }] of Object.entries(data.indexes)) {
+        const pairSig = `${hashKey}|${rangeKey}`;
+        if (seenIndexPairs.has(pairSig)) {
+            ctx.addIssue({
+                code: 'custom',
+                message: `duplicate index hashKey/rangeKey pair`,
+                path: ['indexes', indexKey],
+            });
+        }
+        else
+            seenIndexPairs.add(pairSig);
+        // Validate hash key is sharded.
+        if (![data.hashKey, ...shardedKeys].includes(hashKey)) {
+            ctx.addIssue({
+                code: 'custom',
+                message: `index '${indexKey}' hashKey '${hashKey}' must be one of [${[
+                    data.hashKey,
+                    ...shardedKeys,
+                ].join(', ')}]`,
+                path: ['indexes', indexKey, 'hashKey'],
+            });
+        }
+        // Validate range key is unsharded or transcodable.
+        if (![data.rangeKey, ...unshardedKeys, ...transcodedProperties].includes(rangeKey)) {
+            ctx.addIssue({
+                code: 'custom',
+                message: `index '${indexKey}' rangeKey '${rangeKey}' must be one of [${[
+                    data.rangeKey,
+                    ...unshardedKeys,
+                    ...transcodedProperties,
+                ].join(', ')}]`,
+                path: ['indexes', indexKey, 'rangeKey'],
+            });
+        }
+        // Validate no index projections are keys.
+        if (projections)
+            for (const projection of projections)
+                if ([
+                    data.hashKey,
+                    data.rangeKey,
+                    hashKey,
+                    rangeKey,
+                    ...shardedKeys,
+                    ...unshardedKeys,
+                ].includes(projection))
+                    ctx.addIssue({
+                        code: 'custom',
+                        message: 'index projection is a key',
+                        params: { projection },
+                        path: ['indexes', indexKey, 'projections'],
+                    });
+    }
+    // validate entities
+    for (const [entityToken, { timestampProperty, uniqueProperty },] of Object.entries(data.entities)) {
+        // validate timestampProperty is a transcoded property.
+        if (!transcodedProperties.includes(timestampProperty))
+            ctx.addIssue({
+                code: 'custom',
+                message: `entities['${entityToken}'].timestampProperty '${timestampProperty}' must be one of [${transcodedProperties.join(', ')}]`,
+                path: ['entities', entityToken, 'timestampProperty'],
+            });
+        // validate uniqueProperty is a transcoded property.
+        if (!transcodedProperties.includes(uniqueProperty))
+            ctx.addIssue({
+                code: 'custom',
+                message: `entities['${entityToken}'].uniqueProperty '${uniqueProperty}' must be one of [${transcodedProperties.join(', ')}]`,
+                path: ['entities', entityToken, 'uniqueProperty'],
+            });
+    }
+});
+
+exports.configSchema = configSchema;

package/dist/cjs/EntityManager/addKeys.js

@@ -0,0 +1,60 @@
+'use strict';
+
+var entityTools = require('@karmaniverous/entity-tools');
+var encodeGeneratedProperty = require('./encodeGeneratedProperty.js');
+var updateItemHashKey = require('./updateItemHashKey.js');
+var updateItemRangeKey = require('./updateItemRangeKey.js');
+var validateEntityToken = require('./validateEntityToken.js');
+
+/**
+ * Update generated properties, hash key, and range key on an {@link EntityItem | `EntityItem`} object.
+ *
+ * @param entityManager - {@link EntityManager | `EntityManager`} instance.
+ * @param entityToken - {@link ConfigEntity.uniqueProperty | `this.config.entities`} key.
+ * @param item - {@link EntityItem | `EntityItem`} object.
+ * @param overwrite - Overwrite existing properties (default `false`).
+ *
+ * @returns {@link EntityRecord | `EntityRecord`} object with updated properties.
+ *
+ * @throws `Error` if `entityToken` is invalid.
+ */
+function addKeys(entityManager, entityToken, item, overwrite = false) {
+    try {
+        // Validate params.
+        validateEntityToken.validateEntityToken(entityManager, entityToken);
+        // Update hash key.
+        let newItem = updateItemHashKey.updateItemHashKey(entityManager, entityToken, item, overwrite);
+        // Update range key.
+        newItem = updateItemRangeKey.updateItemRangeKey(entityManager, entityToken, newItem, overwrite);
+        // Update generated properties.
+        const { sharded, unsharded } = entityManager.config.generatedProperties;
+        for (const property in { ...sharded, ...unsharded }) {
+            if (overwrite || entityTools.isNil(item[property])) {
+                const encoded = encodeGeneratedProperty.encodeGeneratedProperty(entityManager, property, newItem);
+                if (encoded)
+                    Object.assign(newItem, { [property]: encoded });
+                else
+                    // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+                    delete newItem[property];
+            }
+        }
+        entityManager.logger.debug('updated entity item generated properties', {
+            item,
+            entityToken,
+            overwrite,
+            newItem,
+        });
+        return newItem;
+    }
+    catch (error) {
+        if (error instanceof Error)
+            entityManager.logger.error(error.message, {
+                item,
+                entityToken,
+                overwrite,
+            });
+        throw error;
+    }
+}
+
+exports.addKeys = addKeys;