@karmaniverous/entity-manager 5.0.9 → 6.0.0

package/dist/cjs/src/EntityManager.js

@@ -0,0 +1,93 @@
+'use strict';
+
+var tslib_es6 = require('../node_modules/tslib/tslib.es6.js');
+var addKeys = require('./addKeys.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.
+ *
+ * @category Entity Manager
+ */
+class EntityManager {
+    /**
+     * Create an EntityManager instance.
+     *
+     * @param config - EntityManager {@link Config | `Config`} object.
+     */
+    constructor(config) {
+        _EntityManager_config.set(this, void 0);
+        tslib_es6.__classPrivateFieldSet(this, _EntityManager_config, ParsedConfig.configSchema.parse(config), "f");
+    }
+    /**
+     * Get the current EntityManager {@link Config | `Config`} object.
+     *
+     * @returns Current {@link Config | `Config`} object.
+     */
+    get config() {
+        return tslib_es6.__classPrivateFieldGet(this, _EntityManager_config, "f");
+    }
+    /**
+     * Set the current EntityManager {@link Config | `Config`} object.
+     *
+     * @param value - {@link Config | `Config`} object.
+     */
+    set config(value) {
+        tslib_es6.__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`.
+     *
+     * @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.
+     *
+     * @throws `Error` if `entityToken` is invalid.
+     */
+    addKeys(item, entityToken, overwrite = false) {
+        return addKeys.addKeys(this, item, entityToken, overwrite);
+    }
+    /**
+     * Strips generated properties, hash key, and range key from an {@link ItemMap | `ItemMap`} object. Mutates `item`.
+     *
+     * @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.
+     *
+     * @throws `Error` if `entityToken` is invalid.
+     */
+    removeKeys(item, entityToken) {
+        return removeKeys.removeKeys(this, item, entityToken);
+    }
+    /**
+     * Query a database entity across shards in a provider-generic fashion.
+     *
+     * @remarks
+     * The provided {@link ShardQueryFunction | `ShardQueryFunction`} performs the actual query of individual data pages on individual shards. This function is presumed to express provider-specific query logic, including any necessary indexing or search constraints.
+     *
+     * Individual shard query results will be combined, deduped by {@link ConfigEntity.uniqueProperty} property 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.
+     *
+     * @param options - {@link QueryOptions | `QueryOptions`} object.
+     *
+     * @returns {@link QueryResult} object.
+     *
+     * @throws Error if {@link QueryOptions.pageKeyMap | `pageKeyMap`} keys do not match {@link QueryOptions.queryMap | `queryMap`} keys.
+     */
+    async query(options) {
+        return await query.query(this, options);
+    }
+}
+_EntityManager_config = new WeakMap();
+
+exports.EntityManager = EntityManager;

package/dist/cjs/src/ParsedConfig.js

@@ -0,0 +1,227 @@
+'use strict';
+
+var defaultTranscodes = require('../node_modules/@karmaniverous/entity-tools/dist/mjs/defaultTranscodes.js');
+var index = require('../node_modules/zod/lib/index.js');
+var array = require('../node_modules/radash/dist/esm/array.js');
+
+const defaultShardBump = { timestamp: 0, charBits: 1, chars: 0 };
+const validateArrayUnique = (arr, ctx, identity = (item) => item, path = []) => {
+    const counts = array.counting(arr, identity);
+    for (const [element, count] of Object.entries(counts)) {
+        if (count > 1)
+            ctx.addIssue({
+                code: index.default.ZodIssueCode.custom,
+                message: `duplicate array element '${element}'`,
+                path,
+            });
+    }
+};
+const validateKeyExclusive = (key, label, ref, ctx) => {
+    if (ref.includes(key))
+        ctx.addIssue({
+            code: index.default.ZodIssueCode.custom,
+            message: `${label} '${key}' is not exclusive`,
+        });
+};
+const configSchema = index.default
+    .object({
+    entities: index.default
+        .record(index.default
+        .object({
+        defaultLimit: index.default
+            .number()
+            .int()
+            .positive()
+            .safe()
+            .optional()
+            .default(10),
+        defaultPageSize: index.default
+            .number()
+            .int()
+            .positive()
+            .safe()
+            .optional()
+            .default(10),
+        generated: index.default
+            .record(index.default
+            .object({
+            atomic: index.default.boolean().optional().default(false),
+            elements: index.default
+                .array(index.default.string().min(1))
+                .nonempty()
+                .superRefine(validateArrayUnique),
+            sharded: index.default.boolean().optional().default(false),
+        })
+            .optional())
+            .optional()
+            .default({}),
+        elementTypes: index.default.record(index.default.string()).optional().default({}),
+        indexes: index.default
+            .record(index.default
+            .array(index.default.string().min(1))
+            .nonempty()
+            .superRefine(validateArrayUnique))
+            .optional()
+            .default({}),
+        shardBumps: index.default
+            .array(index.default
+            .object({
+            timestamp: index.default.number().nonnegative().safe(),
+            charBits: index.default.number().int().min(1).max(5),
+            chars: index.default.number().int().min(0).max(40),
+        })
+            .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 = array.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: index.default.ZodIssueCode.custom,
+                            message: `shardBump chars do not monotonically increase at timestamp ${val[i].timestamp.toString()}`,
+                            path: [i],
+                        });
+            }
+        }),
+        timestampProperty: index.default.string().min(1),
+        uniqueProperty: index.default.string().min(1),
+    })
+        .strict()
+        .superRefine((data, ctx) => {
+        const generatedKeys = Object.keys(data.generated);
+        // validate timestampProperty is not a generated key.
+        validateKeyExclusive(data.timestampProperty, 'timestampProperty', generatedKeys, ctx);
+        // validate uniqueProperty is not a generated key.
+        validateKeyExclusive(data.uniqueProperty, 'uniqueProperty', generatedKeys, ctx);
+    }))
+        .optional()
+        .default({}),
+    generatedKeyDelimiter: index.default.string().regex(/\W+/).optional().default('|'),
+    generatedValueDelimiter: index.default.string().regex(/\W+/).optional().default('#'),
+    shardKeyDelimiter: index.default.string().regex(/\W+/).optional().default('!'),
+    hashKey: index.default.string().optional().default('hashKey'),
+    rangeKey: index.default.string().optional().default('rangeKey'),
+    throttle: index.default.number().int().positive().safe().optional().default(10),
+    transcodes: index.default
+        .record(index.default
+        .object({
+        encode: index.default.function().args(index.default.any()).returns(index.default.string()),
+        decode: index.default.function().args(index.default.string()).returns(index.default.any()),
+    })
+        .strict())
+        .optional()
+        .default(defaultTranscodes.defaultTranscodes),
+})
+    .strict()
+    .superRefine((data, ctx) => {
+    // validate no generated key delimiter collision
+    if (data.generatedKeyDelimiter.includes(data.generatedValueDelimiter))
+        ctx.addIssue({
+            code: index.default.ZodIssueCode.custom,
+            message: 'generatedKeyDelimiter contains generatedValueDelimiter',
+            path: ['generatedKeyDelimiter'],
+        });
+    if (data.generatedKeyDelimiter.includes(data.shardKeyDelimiter))
+        ctx.addIssue({
+            code: index.default.ZodIssueCode.custom,
+            message: 'generatedKeyDelimiter contains shardKeyDelimiter',
+            path: ['generatedKeyDelimiter'],
+        });
+    // validate no generated value delimiter collision
+    if (data.generatedValueDelimiter.includes(data.generatedKeyDelimiter))
+        ctx.addIssue({
+            code: index.default.ZodIssueCode.custom,
+            message: 'generatedValueDelimiter contains generatedKeyDelimiter',
+            path: ['generatedValueDelimiter'],
+        });
+    if (data.generatedValueDelimiter.includes(data.shardKeyDelimiter))
+        ctx.addIssue({
+            code: index.default.ZodIssueCode.custom,
+            message: 'generatedValueDelimiter contains shardKeyDelimiter',
+            path: ['generatedValueDelimiter'],
+        });
+    // validate no shard key delimiter collision
+    if (data.shardKeyDelimiter.includes(data.generatedKeyDelimiter))
+        ctx.addIssue({
+            code: index.default.ZodIssueCode.custom,
+            message: 'shardKeyDelimiter contains generatedKeyDelimiter',
+            path: ['shardKeyDelimiter'],
+        });
+    if (data.shardKeyDelimiter.includes(data.generatedValueDelimiter))
+        ctx.addIssue({
+            code: index.default.ZodIssueCode.custom,
+            message: 'shardKeyDelimiter contains generatedValueDelimiter',
+            path: ['shardKeyDelimiter'],
+        });
+    const reservedKeys = Object.values(data.entities).reduce((reserved, { generated, timestampProperty, uniqueProperty }) => new Set([
+        ...reserved,
+        ...Object.keys(generated),
+        timestampProperty,
+        uniqueProperty,
+    ]), new Set());
+    // validate hashKey is not a reserved key.
+    validateKeyExclusive(data.hashKey, 'hashKey', [...reservedKeys, data.rangeKey], ctx);
+    // validate rangeKey is not a reserved key.
+    validateKeyExclusive(data.rangeKey, 'rangeKey', [...reservedKeys, data.hashKey], ctx);
+    // validate entities
+    const transcodes = Object.keys(data.transcodes);
+    for (const [entityToken, entity] of Object.entries(data.entities)) {
+        // validate all entity generated element type values are transcode keys.
+        for (const [element, generatedElementType] of Object.entries(entity.elementTypes))
+            if (!transcodes.includes(generatedElementType))
+                ctx.addIssue({
+                    code: index.default.ZodIssueCode.invalid_enum_value,
+                    options: transcodes,
+                    path: ['entities', entityToken, 'elementTypes', element],
+                    received: generatedElementType,
+                });
+        // validate all entity generated property elements have a corresponding entity element type.
+        const typedElements = Object.keys(entity.elementTypes);
+        for (const [generatedKey, generated] of Object.entries(entity.generated))
+            for (const element of generated?.elements ?? [])
+                if (!typedElements.includes(element))
+                    ctx.addIssue({
+                        code: index.default.ZodIssueCode.invalid_enum_value,
+                        options: typedElements,
+                        path: [
+                            'entities',
+                            entityToken,
+                            'generated',
+                            generatedKey,
+                            'elements',
+                        ],
+                        received: element,
+                    });
+        // validate all ungenerated entity index components have a corresponding entity element type.
+        const generatedProperties = Object.keys(entity.generated);
+        for (const [indexKey, index$1] of Object.entries(entity.indexes))
+            for (const component of index$1)
+                if (![data.hashKey, data.rangeKey, ...generatedProperties].includes(component) &&
+                    !typedElements.includes(component))
+                    ctx.addIssue({
+                        code: index.default.ZodIssueCode.invalid_enum_value,
+                        options: typedElements,
+                        path: ['entities', entityToken, 'indexes', indexKey],
+                        received: component,
+                    });
+    }
+});
+
+exports.configSchema = configSchema;

package/dist/cjs/src/addKeys.js

@@ -0,0 +1,47 @@
+'use strict';
+
+var Nil = require('../node_modules/@karmaniverous/entity-tools/dist/mjs/Nil.js');
+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 ItemMap | `ItemMap`} object. Mutates `item`.
+ *
+ * @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.
+ *
+ * @throws `Error` if `entityToken` is invalid.
+ */
+function addKeys(entityManager, item, entityToken, overwrite = false) {
+    try {
+        // Validate params.
+        validateEntityToken.validateEntityToken(entityManager, entityToken);
+        // Update hash key.
+        updateItemHashKey.updateItemHashKey(entityManager, item, entityToken, overwrite);
+        // Update range key.
+        updateItemRangeKey.updateItemRangeKey(entityManager, item, entityToken, overwrite);
+        // Update generated properties.
+        for (const property in entityManager.config.entities[entityToken]
+            .generated) {
+            if (overwrite || Nil.isNil(item[property])) {
+                const encoded = encodeGeneratedProperty.encodeGeneratedProperty(entityManager, item, entityToken, property);
+                if (encoded)
+                    Object.assign(item, { [property]: encoded });
+                else
+                    delete item[property];
+            }
+        }
+        return item;
+    }
+    catch (error) {
+        throw error;
+    }
+}
+
+exports.addKeys = addKeys;

package/dist/cjs/src/decodeEntityElement.js

@@ -0,0 +1,37 @@
+'use strict';
+
+var validateEntityToken = require('./validateEntityToken.js');
+
+/**
+ * Decode an {@link Entity | `Entity`} generated property element or ungenerated index component using the associated {@link Transcodes | Transcodes} `encode` function.
+ *
+ * Returns all `undefined` values.
+ *
+ * If `element` is the {@link Config.hashKey | `hashKey`} or {@link Config.rangeKey | `rangeKey`}, returns the value as-is.
+ *
+ * @param entityManager - {@link EntityManager | `EntityManager`} instance.
+ * @param item - Partial {@link ItemMap | `ItemMap`} object.
+ * @param entityToken - {@link ConfigKeys.entities | `entityManager.config.entities`} key.
+ * @param element - The {@link Entity | `Entity`} generated property element or ungenerated index component to encode.
+ *
+ * @returns Decoded value.
+ *
+ * @throws `Error` if `entityToken` is invalid.
+ */
+function decodeEntityElement(entityManager, value, entityToken, element) {
+    try {
+        validateEntityToken.validateEntityToken(entityManager, entityToken);
+        const { entities, hashKey, rangeKey, transcodes } = entityManager.config;
+        if (!value)
+            return;
+        if ([hashKey, rangeKey].includes(element))
+            return value;
+        const decoded = transcodes[entities[entityToken].elementTypes[element]].decode(value);
+        return decoded;
+    }
+    catch (error) {
+        throw error;
+    }
+}
+
+exports.decodeEntityElement = decodeEntityElement;

package/dist/cjs/src/decodeGeneratedProperty.js

@@ -0,0 +1,48 @@
+'use strict';
+
+var decodeEntityElement = require('./decodeEntityElement.js');
+var validateEntityToken = require('./validateEntityToken.js');
+var array = require('../node_modules/radash/dist/esm/array.js');
+
+/**
+ * Decode a generated property value. Returns a partial ItemMap.
+ *
+ * @param entityManager - {@link EntityManager | `EntityManager`} instance.
+ * @param encoded - Encoded generated property value.
+ * @param entityToken - `entityManager.config.entities` key.
+ *
+ * @returns Partial {@link ItemMap | `ItemMap`} object with updated properties decoded from `encoded`.
+ *
+ * @throws `Error` if `entityToken` is invalid.
+ */
+function decodeGeneratedProperty(entityManager, encoded, entityToken) {
+    try {
+        const { generatedKeyDelimiter, generatedValueDelimiter, hashKey, shardKeyDelimiter, } = entityManager.config;
+        // Validate params.
+        validateEntityToken.validateEntityToken(entityManager, entityToken);
+        // Handle degenerate case.
+        if (!encoded)
+            return {};
+        // Split encoded into keys.
+        const keys = encoded.split(generatedKeyDelimiter);
+        // Initiate result with hashKey if sharded.
+        const decoded = keys[0].includes(shardKeyDelimiter)
+            ? { [hashKey]: keys.shift() }
+            : {};
+        // Split keys into values & validate.
+        const values = keys.map((key) => {
+            const pair = key.split(generatedValueDelimiter);
+            if (pair.length !== 2)
+                throw new Error(`invalid generated property value '${key}'`);
+            return pair;
+        });
+        // Assign decoded properties.
+        Object.assign(decoded, array.objectify(values, ([key]) => key, ([key, value]) => decodeEntityElement.decodeEntityElement(entityManager, value, entityToken, key)));
+        return decoded;
+    }
+    catch (error) {
+        throw error;
+    }
+}
+
+exports.decodeGeneratedProperty = decodeGeneratedProperty;

package/dist/cjs/src/dehydrateIndexItem.js

@@ -0,0 +1,52 @@
+'use strict';
+
+var encodeEntityElement = require('./encodeEntityElement.js');
+var unwrapIndex = require('./unwrapIndex.js');
+var validateEntityIndexToken = require('./validateEntityIndexToken.js');
+
+/**
+ * Condense a partial {@link ItemMap | `ItemMap`} object into a delimited string representing the deduped, sorted, ungenerated component elements of an {@link ConfigEntity.indexes | Entity index}.
+ *
+ * @remarks
+ * Reverses {@link EntityManager.rehydrateIndexItem | `rehydrateIndexItem`}.
+ *
+ * To create the output value, entityManager method:
+ *
+ * * Unwraps `index` components into deduped, sorted, ungenerated elements.
+ * * Joins `item` element values with {@link Config.generatedKeyDelimiter | `entityManager.config.generatedKeyDelimiter`}.
+ *
+ * `item` must be populated with all required index component elements!
+ *
+ * @param entityManager - {@link EntityManager | `EntityManager`} instance.
+ * @param item - Partial {@link ItemMap | `ItemMap`} object.
+ * @param entityToken - {@link ConfigKeys.entities | `entityManager.config.entities`} key.
+ * @param indexToken - {@link ConfigEntity.indexes | `entityManager.config.entities.<entityToken>.indexes`} key.
+ * @param omit - Array of index components to omit from the output value.
+ *
+ * @returns Dehydrated index value.
+ *
+ * @throws `Error` if `entityToken` is invalid.
+ * @throws `Error` if `indexToken` is invalid.
+ */
+function dehydrateIndexItem(entityManager, item, entityToken, indexToken, omit = []) {
+    try {
+        const { generatedKeyDelimiter } = entityManager.config;
+        // Validate params.
+        validateEntityIndexToken.validateEntityIndexToken(entityManager, entityToken, indexToken);
+        // Handle degenerate case.
+        if (!item)
+            return '';
+        // Unwrap index elements.
+        const elements = unwrapIndex.unwrapIndex(entityManager, entityToken, indexToken).filter((element) => !omit.includes(element));
+        // Join index element values.
+        const dehydrated = elements
+            .map((element) => encodeEntityElement.encodeEntityElement(entityManager, item, entityToken, element))
+            .join(generatedKeyDelimiter);
+        return dehydrated;
+    }
+    catch (error) {
+        throw error;
+    }
+}
+
+exports.dehydrateIndexItem = dehydrateIndexItem;

package/dist/cjs/src/dehydratePageKeyMap.js

@@ -0,0 +1,75 @@
+'use strict';
+
+var decodeGeneratedProperty = require('./decodeGeneratedProperty.js');
+var dehydrateIndexItem = require('./dehydrateIndexItem.js');
+var validateEntityIndexToken = require('./validateEntityIndexToken.js');
+var validateEntityToken = require('./validateEntityToken.js');
+
+/**
+ * Dehydrate a {@link PageKeyMap | `PageKeyMap`} object into an array of dehydrated page keys.
+ *
+ * Reverses {@link EntityManager.rehydratePageKeyMap | `rehydratePageKeyMap`}.
+ *
+ * @param entityManager - {@link EntityManager | `EntityManager`} instance.
+ * @param pageKeyMap - {@link PageKeyMap | `PageKeyMap`} object to dehydrate.
+ * @param entityToken - {@link ConfigKeys.entities | `entityManager.config.entities`} key.
+ *
+ * @returns  Array of dehydrated page keys.
+ *
+ * @throws `Error` if `entityToken` is invalid.
+ * @throws `Error` if any `pageKeyMap` key is an invalid indexToken is invalid {@link ConfigEntity.indexes | `entityManager.config.entities.<entityToken>.indexes`} key.
+ *
+ * @remarks
+ * In the returned array, an empty string member indicates the corresponding page key is `undefined`.
+ *
+ * An empty returned array indicates all page keys are `undefined`.
+ */
+function dehydratePageKeyMap(entityManager, pageKeyMap, entityToken) {
+    try {
+        // Validate params.
+        validateEntityToken.validateEntityToken(entityManager, entityToken);
+        // Shortcut empty pageKeyMap.
+        if (!Object.keys(pageKeyMap).length) {
+            const dehydrated = [];
+            return dehydrated;
+        }
+        // Extract, sort & validate indexs.
+        const indexes = Object.keys(pageKeyMap).sort();
+        indexes.map((index) => validateEntityIndexToken.validateEntityIndexToken(entityManager, entityToken, index));
+        // Extract & sort hash keys.
+        const hashKeys = Object.keys(pageKeyMap[indexes[0]]);
+        // Dehydrate page keys.
+        let dehydrated = [];
+        for (const index of indexes) {
+            for (const hashKey of hashKeys) {
+                // Undefineed pageKey.
+                if (!pageKeyMap[index][hashKey]) {
+                    dehydrated.push('');
+                    continue;
+                }
+                // Compose item from page key
+                const item = Object.entries(pageKeyMap[index][hashKey]).reduce((item, [property, value]) => {
+                    if (property in entityManager.config.entities[entityToken].generated ||
+                        property === entityManager.config.rangeKey)
+                        Object.assign(item, decodeGeneratedProperty.decodeGeneratedProperty(entityManager, value, entityToken));
+                    else
+                        Object.assign(item, { [property]: value });
+                    return item;
+                }, {});
+                // Dehydrate index from item.
+                dehydrated.push(dehydrateIndexItem.dehydrateIndexItem(entityManager, item, entityToken, index, [
+                    entityManager.config.hashKey,
+                ]));
+            }
+        }
+        // Replace with empty array if all pageKeys are empty strings.
+        if (dehydrated.every((pageKey) => pageKey === ''))
+            dehydrated = [];
+        return dehydrated;
+    }
+    catch (error) {
+        throw error;
+    }
+}
+
+exports.dehydratePageKeyMap = dehydratePageKeyMap;

package/dist/cjs/src/encodeEntityElement.js

@@ -0,0 +1,36 @@
+'use strict';
+
+var validateEntityToken = require('./validateEntityToken.js');
+
+/**
+ * Encode an {@link Entity | `Entity`} generated property element or ungenerated index component using the associated {@link Transcodes | Transcodes} `encode` function.
+ *
+ * Returns all `undefined` values.
+ *
+ * If `element` is the {@link Config.hashKey | `hashKey`} or {@link Config.rangeKey | `rangeKey`}, returns the value as-is.
+ *
+ * @param entityManager - {@link EntityManager | `EntityManager`} instance.
+ * @param item - Partial {@link ItemMap | `ItemMap`} object.
+ * @param entityToken - {@link ConfigKeys.entities | `entityManager.config.entities`} key.
+ * @param element - The {@link Entity | `Entity`} generated property element or ungenerated index component to encode.
+ *
+ * @returns Encoded value.
+ *
+ * @throws `Error` if `entityToken` is invalid.
+ */
+function encodeEntityElement(entityManager, item, entityToken, element) {
+    try {
+        validateEntityToken.validateEntityToken(entityManager, entityToken);
+        const { entities, hashKey, rangeKey, transcodes } = entityManager.config;
+        const value = item[element];
+        if (value === undefined || [hashKey, rangeKey].includes(element))
+            return value;
+        const encoded = transcodes[entities[entityToken].elementTypes[element]].encode(item[element]) || undefined;
+        return encoded;
+    }
+    catch (error) {
+        throw error;
+    }
+}
+
+exports.encodeEntityElement = encodeEntityElement;

package/dist/cjs/src/encodeGeneratedProperty.js

@@ -0,0 +1,44 @@
+'use strict';
+
+var Nil = require('../node_modules/@karmaniverous/entity-tools/dist/mjs/Nil.js');
+var validateEntityGeneratedProperty = require('./validateEntityGeneratedProperty.js');
+
+/**
+ * Encode a generated property value. Returns a string or undefined if atomicity requirement not met.
+ *
+ * @param entityManager - {@link EntityManager | `EntityManager`} instance.
+ * @param item - Partial {@link ItemMap | `ItemMap`} object.
+ * @param entityToken - `entityManager.config.entities` key.
+ * @param property - {@link ConfigEntityGenerated | `entityManager.config.entities.<entityToken>.generated`} key.
+ *
+ * @returns Encoded generated property value.
+ *
+ * @throws `Error` if `entityToken` is invalid.
+ * @throws `Error` if `property` is invalid.
+ */
+function encodeGeneratedProperty(entityManager, item, entityToken, property) {
+    try {
+        // Validate params.
+        validateEntityGeneratedProperty.validateEntityGeneratedProperty(entityManager, entityToken, property);
+        const { atomic, elements, sharded } = entityManager.config.entities[entityToken].generated[property];
+        // Map elements to [element, value] pairs.
+        const elementMap = elements.map((element) => [
+            element,
+            item[element],
+        ]);
+        // Validate atomicity requirement.
+        if (atomic && elementMap.some(([, value]) => Nil.isNil(value)))
+            return;
+        // Encode property value.
+        const encoded = [
+            ...(sharded ? [item[entityManager.config.hashKey]] : []),
+            ...elementMap.map(([element, value]) => [element, (value ?? '').toString()].join(entityManager.config.generatedValueDelimiter)),
+        ].join(entityManager.config.generatedKeyDelimiter);
+        return encoded;
+    }
+    catch (error) {
+        throw error;
+    }
+}
+
+exports.encodeGeneratedProperty = encodeGeneratedProperty;