@karmaniverous/entity-manager 5.0.8 → 5.0.10

package/dist/cjs/EntityManager/createEntityManager.js

@@ -0,0 +1,46 @@
+'use strict';
+
+var EntityManager = require('./EntityManager.js');
+
+/**
+ * Values-first factory that captures literal tokens and index names directly
+ * from the provided config value. Runtime config parsing/validation is
+ * unchanged (performed in the EntityManager constructor).
+ *
+ * @typeParam CC - Captured config input (values-first). Prefer `as const` and
+ *                 `satisfies` at call sites to preserve literal keys.
+ * @typeParam EM - EntityMap for the manager. Defaults to a minimal derived map
+ *                 from `CC.entitiesSchema` when present; otherwise falls back to EntityMap.
+ *
+ * @returns An {@link EntityManager | `EntityManager`} instance whose type
+ *          captures CF from the single values-first config literal ({@link ConfigInput | `ConfigInput`})
+ *          as the second generic parameter (phantom; type-only).
+ */
+function createEntityManager(config, logger = console) {
+    // Cast to the existing Config<C> shape for runtime parsing; Zod validation
+    // remains authoritative at construction time.
+    // Optional dev guardrail: cross-check entitiesSchema keys vs config.entities keys.
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+        if (config && 'entitiesSchema' in config && config.entitiesSchema) {
+            const schemaKeys = Object.keys(config
+                .entitiesSchema ?? {});
+            const entitiesKeys = Object.keys(config
+                .entities ?? {});
+            const missingInEntities = schemaKeys.filter((k) => !entitiesKeys.includes(k));
+            const missingInSchema = entitiesKeys.filter((k) => !schemaKeys.includes(k));
+            if (missingInEntities.length || missingInSchema.length) {
+                logger.debug('entitiesSchema keys mismatch with config.entities', {
+                    missingInEntities,
+                    missingInSchema,
+                });
+            }
+        }
+    }
+    catch {
+        // Best-effort warning only; never block construction.
+    }
+    return new EntityManager.EntityManager(config, logger);
+}
+
+exports.createEntityManager = createEntityManager;

package/dist/cjs/EntityManager/decodeElement.js

@@ -0,0 +1,46 @@
+'use strict';
+
+var validateTranscodedProperty = require('./validateTranscodedProperty.js');
+
+/**
+ * Decode an {@link EntityItem | `EntityItem`} 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 element - The {@link Entity | `Entity`} generated property element or ungenerated index component to encode.
+ * @param value - Encoded entity element.
+ *
+ * @returns Decoded value.
+ *
+ * @throws `Error` if `entityToken` is invalid.
+ */
+function decodeElement(entityManager, element, value) {
+    try {
+        // Validate params.
+        validateTranscodedProperty.validateTranscodedProperty(entityManager, element);
+        if (!value)
+            return;
+        const { propertyTranscodes, transcodes } = entityManager.config;
+        const decodeFn = transcodes[propertyTranscodes[element]].decode;
+        const decoded = decodeFn(value);
+        entityManager.logger.debug('decoded entity element', {
+            element,
+            value,
+            decoded,
+        });
+        return decoded;
+    }
+    catch (error) {
+        if (error instanceof Error)
+            entityManager.logger.error(error.message, {
+                element,
+                value,
+            });
+        throw error;
+    }
+}
+
+exports.decodeElement = decodeElement;

package/dist/cjs/EntityManager/decodeGeneratedProperty.js

@@ -0,0 +1,53 @@
+'use strict';
+
+var radash = require('radash');
+var decodeElement = require('./decodeElement.js');
+
+/**
+ * Decode a generated property value. Returns an {@link EntityItem | `EntityItem`}.
+ *
+ * @param entityManager - {@link EntityManager | `EntityManager`} instance.
+ * @param entityToken - {@link Config.entities | `entityManager.config.entities`} key.
+ * @param encoded - Encoded generated property value.
+ *
+ * @returns {@link EntityItem | `EntityItem`} object with updated properties decoded from `encoded`.
+ *
+ * @throws `Error` if `entityToken` is invalid.
+ */
+function decodeGeneratedProperty(entityManager, entityToken, encoded) {
+    try {
+        const { generatedKeyDelimiter, generatedValueDelimiter, hashKey, shardKeyDelimiter, } = entityManager.config;
+        // 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, radash.objectify(values, ([key]) => key, ([key, value]) => decodeElement.decodeElement(entityManager, key, value)));
+        entityManager.logger.debug('decoded generated property', {
+            encoded,
+            decoded,
+        });
+        // entityToken used for typing only (ET-narrowed result).
+        void entityToken;
+        return decoded;
+    }
+    catch (error) {
+        if (error instanceof Error)
+            entityManager.logger.error(error.message, { encoded });
+        throw error;
+    }
+}
+
+exports.decodeGeneratedProperty = decodeGeneratedProperty;

package/dist/cjs/EntityManager/dehydrateIndexItem.js

@@ -0,0 +1,68 @@
+'use strict';
+
+var encodeElement = require('./encodeElement.js');
+var unwrapIndex = require('./unwrapIndex.js');
+var validateEntityToken = require('./validateEntityToken.js');
+var validateIndexToken = require('./validateIndexToken.js');
+
+/**
+ * Condense an {@link EntityItem | `EntityItem`} into a delimited string representing the deduped, sorted, ungenerated component elements of an {@link Config.indexes | index}, leaving out those of the index hash key.
+ *
+ * @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 entityToken - {@link Config.entities | `entityManager.config.entities`} key.
+ * @param indexToken - {@link ConfigEntity.indexes | `entityManager.config.indexes`} key.
+ * @param item - {@link EntityItem | `EntityItem`} object.
+ *
+ * @returns Dehydrated index value.
+ *
+ * @throws `Error` if `indexToken` is invalid.
+ */
+function dehydrateIndexItem(entityManager, entityToken, indexToken, item) {
+    try {
+        // Validate params.
+        validateEntityToken.validateEntityToken(entityManager, entityToken);
+        validateIndexToken.validateIndexToken(entityManager, indexToken);
+        // Handle degenerate case.
+        if (!item)
+            return '';
+        // Unwrap index elements.
+        const { hashKey } = entityManager.config.indexes[indexToken];
+        const elements = unwrapIndex.unwrapIndex(entityManager, entityToken, indexToken, [
+            hashKey,
+        ]);
+        // Join index element values.
+        const { generatedKeyDelimiter } = entityManager.config;
+        const dehydrated = elements
+            .map((element) => encodeElement.encodeElement(entityManager, element, item))
+            .join(generatedKeyDelimiter);
+        entityManager.logger.debug('dehydrated index', {
+            item,
+            entityToken,
+            indexToken,
+            elements,
+            dehydrated,
+        });
+        return dehydrated;
+    }
+    catch (error) {
+        if (error instanceof Error)
+            entityManager.logger.error(error.message, {
+                item,
+                entityToken,
+                indexToken,
+            });
+        throw error;
+    }
+}
+
+exports.dehydrateIndexItem = dehydrateIndexItem;

package/dist/cjs/EntityManager/dehydratePageKeyMap.js

@@ -0,0 +1,93 @@
+'use strict';
+
+var decodeGeneratedProperty = require('./decodeGeneratedProperty.js');
+var dehydrateIndexItem = require('./dehydrateIndexItem.js');
+var validateEntityToken = require('./validateEntityToken.js');
+var validateIndexToken = require('./validateIndexToken.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 entityToken - {@link Config.entities | `entityManager.config.entities`} key.
+ * @param pageKeyMap - {@link PageKeyMap | `PageKeyMap`} object to dehydrate.
+ *
+ * @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, entityToken, pageKeyMap) {
+    try {
+        // Validate params.
+        validateEntityToken.validateEntityToken(entityManager, entityToken);
+        // Shortcut empty pageKeyMap.
+        if (!Object.keys(pageKeyMap).length) {
+            const dehydrated = [];
+            entityManager.logger.debug('dehydrated empty page key map', {
+                entityToken,
+                pageKeyMap,
+                dehydrated,
+            });
+            return dehydrated;
+        }
+        // Extract, sort & validate indexs.
+        const indexes = Object.keys(pageKeyMap).sort();
+        indexes.map((indexToken) => {
+            validateIndexToken.validateIndexToken(entityManager, indexToken);
+        });
+        // 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) {
+                // Undefined pageKey.
+                if (!pageKeyMap[index][hashKey]) {
+                    dehydrated.push('');
+                    continue;
+                }
+                // Compose item from page key
+                const pk = pageKeyMap[index][hashKey];
+                const item = Object.entries(pk).reduce((item, [property, value]) => {
+                    if (property === entityManager.config.rangeKey ||
+                        property in entityManager.config.generatedProperties.sharded ||
+                        property in entityManager.config.generatedProperties.unsharded)
+                        Object.assign(item, decodeGeneratedProperty.decodeGeneratedProperty(entityManager, entityToken, value));
+                    else
+                        Object.assign(item, { [property]: value });
+                    return item;
+                }, 
+                // eslint-disable-next-line @typescript-eslint/prefer-reduce-type-parameter
+                {});
+                // Dehydrate index from item.
+                dehydrated.push(dehydrateIndexItem.dehydrateIndexItem(entityManager, entityToken, index, item));
+            }
+        }
+        // Replace with empty array if all pageKeys are empty strings.
+        if (dehydrated.every((pageKey) => pageKey === ''))
+            dehydrated = [];
+        entityManager.logger.debug('dehydrated page key map', {
+            entityToken,
+            pageKeyMap,
+            indexes,
+            hashKeys,
+            dehydrated,
+        });
+        return dehydrated;
+    }
+    catch (error) {
+        if (error instanceof Error)
+            entityManager.logger.error(error.message, { entityToken, pageKeyMap });
+        throw error;
+    }
+}
+
+exports.dehydratePageKeyMap = dehydratePageKeyMap;

package/dist/cjs/EntityManager/encodeElement.js

@@ -0,0 +1,40 @@
+'use strict';
+
+/**
+ * Encode an {@link EntityItem | `EntityItem`} 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 element - The {@link Entity | `Entity`} generated property element or ungenerated index component to encode.
+ * @param item - {@link EntityItem | `EntityItem`} object.
+ *
+ * @returns Encoded value.
+ *
+ * @throws `Error` if `entityToken` is invalid.
+ */
+function encodeElement(entityManager, element, item) {
+    try {
+        const { hashKey, rangeKey, propertyTranscodes, transcodes } = entityManager.config;
+        const value = item[element];
+        if (value === undefined || [hashKey, rangeKey].includes(element))
+            return value;
+        const encodeFn = transcodes[propertyTranscodes[element]].encode;
+        const encoded = encodeFn(item[element]) || undefined;
+        entityManager.logger.debug('encoded entity element', {
+            element,
+            item,
+            encoded,
+        });
+        return encoded;
+    }
+    catch (error) {
+        if (error instanceof Error)
+            entityManager.logger.error(error.message, { element, item });
+        throw error;
+    }
+}
+
+exports.encodeElement = encodeElement;

package/dist/cjs/EntityManager/encodeGeneratedProperty.js

@@ -0,0 +1,55 @@
+'use strict';
+
+var entityTools = require('@karmaniverous/entity-tools');
+var validateGeneratedProperty = require('./validateGeneratedProperty.js');
+
+/**
+ * Encode a generated property value. Returns a string or undefined if atomicity requirement of sharded properties not met.
+ *
+ * @param entityManager - {@link EntityManager | `EntityManager`} instance.
+ * @param property - {@link Config.generatedProperties | Generated property} key.
+ * @param item - {@link StorageItem | `StorageItem`} object.
+ *
+ * @returns Encoded generated property value.
+ *
+ * @throws `Error` if `property` is not a {@link Config.generatedProperties | generated property}.
+ */
+function encodeGeneratedProperty(entityManager, property, item) {
+    try {
+        // Validate params.
+        validateGeneratedProperty.validateGeneratedProperty(entityManager, property);
+        const sharded = property in entityManager.config.generatedProperties.sharded;
+        const elements = entityManager.config.generatedProperties[sharded ? 'sharded' : 'unsharded'][property];
+        // Map elements to [element, value] pairs.
+        const elementMap = elements.map((element) => [
+            element,
+            item[element],
+        ]);
+        // Return undefined if sharded & atomicity requirement fails.
+        if (sharded && elementMap.some(([, value]) => entityTools.isNil(value)))
+            return;
+        // Encode property value.
+        const encoded = [
+            ...(sharded
+                ? [item[entityManager.config.hashKey]]
+                : []),
+            ...elementMap.map(([element, value]) => [element, `${value ?? ''}`].join(entityManager.config.generatedValueDelimiter)),
+        ].join(entityManager.config.generatedKeyDelimiter);
+        entityManager.logger.debug('encoded generated property', {
+            property,
+            item,
+            encoded,
+        });
+        return encoded;
+    }
+    catch (error) {
+        if (error instanceof Error)
+            entityManager.logger.error(error.message, {
+                property,
+                item,
+            });
+        throw error;
+    }
+}
+
+exports.encodeGeneratedProperty = encodeGeneratedProperty;

package/dist/cjs/EntityManager/findIndexToken.js

@@ -0,0 +1,10 @@
+'use strict';
+
+function findIndexToken(entityManager, hashKeyToken, rangeKeyToken, suppressError) {
+    const indexToken = (Object.entries(entityManager.config.indexes).find(([, index]) => index.hashKey === hashKeyToken && index.rangeKey === rangeKeyToken)?.[0] ?? undefined);
+    if (!indexToken && !suppressError)
+        throw new Error(`No index token found for hashKey '${hashKeyToken}' & rangeKey '${rangeKeyToken}'.`);
+    return indexToken;
+}
+
+exports.findIndexToken = findIndexToken;

package/dist/cjs/EntityManager/getHashKeySpace.js

@@ -0,0 +1,89 @@
+'use strict';
+
+var radash = require('radash');
+var stringHash = require('string-hash');
+var encodeGeneratedProperty = require('./encodeGeneratedProperty.js');
+var validateGeneratedProperty = require('./validateGeneratedProperty.js');
+
+/**
+ * Return an array of {@link ConfigKeys.hashKey | `entityManager.config.hashKey`} property values covering the shard space bounded by `timestampFrom` & `timestampTo`.
+ *
+ * @param entityManager - {@link EntityManager | `EntityManager`} instance.
+ * @param entityToken - {@link Config.entities | `entityManager.config.entities`} key.
+ * @param hashKeyToken - {@link ParsedConfig | `entityManager.config.hashKey`} or {@link ParsedConfig | `entityManager.config.generatedProperties.sharded`} key.
+ * @param item - {@link EntityItem | `EntityItem`} object. Must include all properties required to generate the hash key space.
+ * @param timestampFrom - Lower timestanp limit. Defaults to `0`.
+ * @param timestampTo - Upper timestamp limit. Defaults to `Date.now()`.
+ *
+ * @returns Array of {@link ConfigKeys.hashKey | `entityManager.config.hashKey`} property values covering the indicated shard space.
+ *
+ * @throws `Error` if `entityToken` is invalid.
+ */
+function getHashKeySpace(entityManager, entityToken, hashKeyToken, item, timestampFrom = 0, timestampTo = Date.now()) {
+    try {
+        // Validate hashKeyToken is either the global hash key or a sharded generated property.
+        if (hashKeyToken !== entityManager.config.hashKey)
+            validateGeneratedProperty.validateGeneratedProperty(entityManager, hashKeyToken, true);
+        const { shardBumps } = entityManager.config.entities[entityToken];
+        // Detect presence of the entity's unique property on the item.
+        const uniqueProp = entityManager.config.entities[entityToken].uniqueProperty;
+        const uniqueValue = item[uniqueProp];
+        const hashKeySpace = shardBumps
+            // Filter shard bumps by timestamp range.
+            .filter((bump, i) => (i === shardBumps.length - 1 ||
+            shardBumps[i + 1].timestamp > timestampFrom) &&
+            bump.timestamp <= timestampTo)
+            // Generate shard key space.
+            .flatMap(({ charBits, chars }) => {
+            const radix = 2 ** charBits;
+            // If the item's unique property is present, deterministically
+            // compute exactly one shard suffix for this bump. Otherwise,
+            // enumerate the full shard space for the bump.
+            if (chars) {
+                if (uniqueValue) {
+                    const space = radix ** chars;
+                    const mod = stringHash(uniqueValue) % space;
+                    return mod.toString(radix).padStart(chars, '0');
+                }
+                return [...radash.range(0, radix ** chars - 1)].map((char) => char.toString(radix).padStart(chars, '0'));
+            }
+            return '';
+        })
+            // Map shard keys to hash keys.
+            .map((shardKey) => {
+            // Calculate record hash key.
+            let hashKey = `${String(entityToken)}${entityManager.config.shardKeyDelimiter}${shardKey}`;
+            // If hash key space basis is a different property, encode it.
+            if (hashKeyToken !== entityManager.config.hashKey)
+                hashKey = encodeGeneratedProperty.encodeGeneratedProperty(entityManager, hashKeyToken, {
+                    ...item,
+                    [entityManager.config.hashKey]: hashKey,
+                });
+            if (!hashKey)
+                throw new Error('item does not support hash key space');
+            return hashKey;
+        });
+        entityManager.logger.debug('generated hash key space', {
+            entityToken,
+            hashKeyToken,
+            item,
+            timestampFrom,
+            timestampTo,
+            hashKeySpace,
+        });
+        return hashKeySpace;
+    }
+    catch (error) {
+        if (error instanceof Error)
+            entityManager.logger.error(error.message, {
+                entityToken,
+                hashKeyToken,
+                item,
+                timestampFrom,
+                timestampTo,
+            });
+        throw error;
+    }
+}
+
+exports.getHashKeySpace = getHashKeySpace;

package/dist/cjs/EntityManager/getIndexComponents.js

@@ -0,0 +1,23 @@
+'use strict';
+
+var radash = require('radash');
+var validateIndexToken = require('./validateIndexToken.js');
+
+/**
+ * Get the index components of an entity index. Adds the hash and range keys to the index components.
+ *
+ * @param entityManager - {@link EntityManager | `EntityManager`} instance.
+ * @param indexToken - {@link Config.indexes | `entityManager.config.indexes`} key.
+ *
+ * @returns Array of index components.
+ *
+ * @throws `Error` if `indexToken` is invalid.
+ */
+function getIndexComponents(entityManager, indexToken) {
+    validateIndexToken.validateIndexToken(entityManager, indexToken);
+    const { hashKey, rangeKey, indexes } = entityManager.config;
+    const { hashKey: indexHashKey, rangeKey: indexRangeKey } = indexes[indexToken];
+    return radash.unique([hashKey, rangeKey, indexHashKey, indexRangeKey]);
+}
+
+exports.getIndexComponents = getIndexComponents;

package/dist/cjs/EntityManager/getPrimaryKey.js

@@ -0,0 +1,76 @@
+'use strict';
+
+var getHashKeySpace = require('./getHashKeySpace.js');
+var updateItemHashKey = require('./updateItemHashKey.js');
+var updateItemRangeKey = require('./updateItemRangeKey.js');
+
+/**
+ * Convert an {@link EntityItem | `EntityItem`} into one or more {@link EntityKey | `EntityKey`} values.
+ *
+ * Behavior:
+ * - Always returns an array of keys.
+ * - If `overwrite` is false and the item already has both hash and range keys, returns exactly that pair.
+ * - Otherwise, computes the range key. Then:
+ *   - If the timestampProperty is present, computes exactly one hash key and returns a single key.
+ *   - If the timestampProperty is missing, enumerates the hash-key space across all shard bumps
+ *     (with uniqueProperty present → one suffix per bump) and returns one key per bump.
+ *
+ * @param entityManager - {@link EntityManager | `EntityManager`} instance.
+ * @param entityToken - {@link Config | `Config`} `entities` key.
+ * @param item - {@link EntityItem | `EntityItem`} object.
+ * @param overwrite - Overwrite existing properties (default `false`).
+ *
+ * @returns Array of {@link EntityKey | `EntityKey`} values derived from `item`.
+ *
+ * @throws `Error` if `entityToken` is invalid.
+ */
+function getPrimaryKey(entityManager, entityToken, item, overwrite = false) {
+    const { hashKey, rangeKey } = entityManager.config;
+    // If both keys are present and we're not overwriting, return the exact pair.
+    const rec = item;
+    const hk = hashKey;
+    const rk = rangeKey;
+    if (!overwrite && rec[hk] && rec[rk]) {
+        return [
+            {
+                [hashKey]: rec[hk],
+                [rangeKey]: rec[rk],
+            },
+        ];
+    }
+    // Compute/refresh the range key (throws if uniqueProperty missing).
+    const withRangeKey = updateItemRangeKey.updateItemRangeKey(entityManager, entityToken, item, true);
+    // If timestamp present, compute exactly one hash key and return single pair.
+    const tsProp = entityManager.config.entities[entityToken].timestampProperty;
+    if (withRangeKey[tsProp] !== undefined) {
+        // Note: use StorageItem here
+        const withHashKey = updateItemHashKey.updateItemHashKey(entityManager, entityToken, withRangeKey, true);
+        return [
+            {
+                [hashKey]: withHashKey[hashKey],
+                [rangeKey]: withHashKey[rangeKey],
+            },
+        ];
+    }
+    // No timestamp: enumerate hash-key space across all shard bumps (0..Infinity).
+    const hashKeys = getHashKeySpace.getHashKeySpace(entityManager, entityToken, hashKey, withRangeKey, 0, Infinity);
+    // Map to keys and de-duplicate.
+    const rangeKeyValue = withRangeKey[rangeKey];
+    const seen = new Set();
+    const keys = hashKeys
+        .map((hk) => {
+        const key = {
+            [hashKey]: hk,
+            [rangeKey]: rangeKeyValue,
+        };
+        const sig = `${hk}|${rangeKeyValue}`;
+        if (seen.has(sig))
+            return undefined;
+        seen.add(sig);
+        return key;
+    })
+        .filter((k) => !!k);
+    return keys;
+}
+
+exports.getPrimaryKey = getPrimaryKey;

package/dist/cjs/EntityManager/getShardBump.js

@@ -0,0 +1,24 @@
+'use strict';
+
+var validateEntityToken = require('./validateEntityToken.js');
+
+/**
+ * Get first entity shard bump before timestamp.
+ *
+ * @param entityManager - {@link EntityManager | `EntityManager`} instance.
+ * @param entityToken - {@link Config.entities | `this.config.entities`} key.
+ * @param timestamp - Timestamp in milliseconds.
+ *
+ * @returns {@link ShardBump | `ShardBump`} object.
+ *
+ * @throws `Error` if `entityToken` is invalid.
+ */
+function getShardBump(entityManager, entityToken, timestamp) {
+    // Validate params.
+    validateEntityToken.validateEntityToken(entityManager, entityToken);
+    return [...entityManager.config.entities[entityToken].shardBumps]
+        .reverse()
+        .find((bump) => bump.timestamp <= timestamp);
+}
+
+exports.getShardBump = getShardBump;