@karmaniverous/entity-manager
Advanced tools
Configurably decorate entity objects with sharded index keys.
The DynamoDB single-table design pattern requires highly-structured key attributes that...
Entity relationships in a traditional RDBMS are expressed in a set of Foreign Key constraints that map straightforwardly into an entity-relationship diagram (ERD). Keeping implementation and design in sync is painless, and scaling is a matter of hardware and server configuration.
All of this takes place at design time. At run time, database structure is more or less fixed.
GSIs on a NoSQL platform like DynamoDB are declared as a matter of design-time configuration. Everything ELSE happens at run time, encoded into those critical key attributes at every data write.
The logic to accomplish this can be both complex and fragmented across the implementation. Unlike a set of RDBMS foreign key constraints that map one-for-one to the lines in an ERD, the structure of this logic is difficult to visualize and rarely collected in one place.
This package shifts the implementation of DynamoDB structure & scaling from logic to configuration. It features:
A simple, declarative configuration format that permits articulation of every index key for every entity, all in one place.
A rational approach to partition sharding that can be encoded directly into table & GSI hash keys and permits scaling over time.
High-performance decoration of entity-specific data objects with configured, shard-aware index values.
High-performance transformation of an entity-specific data object into a key space permitting query of related objects across all partition shards.
npm install @karmaniverous/entity-manager
The entity-manager configuration object describes each entity's structured keys and sharding strategy. For broadest compatibility, express this object as a named export from an ES6 module like this:
// entityConfig.js
// These tagged templates are used below to simplify template literals.
// sn2e - Template literal returns empty string if any expression is nil.
// sn2u - Template literal returns undefined if any expression is nil.
import { sn2e, sn2u } from '@karmaniverous/tagged-templates';
// Entity config object named export.
export const config = {
entities: {
// Repeat this structure for each entity type. Valid keys match /\w+/
transaction: {
// Each property of the keys object defines a structured index key for
// this entity. Each property value is a function expects an entity
// object as its one argument. In the examples below, entity attributes
// are destructured in the function declaration and the return value is
// expressed as a template literal.
keys: {
// Table HASH key. Note the optional shardId.
entityPK: ({ shardId }) => `transaction${sn2e`!${shardId}`}`,
// Table RANGE key.
transactionSK: ({ timestamp, transactionId }) =>
sn2u`timestamp#${timestamp}|transactionId#${transactionId}`,
// merchants GSI HASH key. Note the optional shardId.
merchantPK: ({ merchantId, shardId }) =>
sn2u`merchantId#${merchantId}|transaction${sn2e`!${shardId}`}`,
// merchants GSI RANGE key.
merchantSK: ({ methodId, timestamp, transactionId }) =>
sn2u`timestamp#${timestamp}|methodId#${methodId}|transactionId#${transactionId}`,
// methods GSI HASH key. Note the optional shardId.
methodPK: ({ methodId, shardId }) =>
sn2u`method#${methodId}|transaction${sn2e`!${shardId}`}`,
// methods GSI RANGE key.
methodSK: ({ merchantId, timestamp, transactionId }) =>
sn2u`timestamp#${timestamp}|merchantId#${merchantId}|transactionId#${transactionId}`,
// users GSI HASH key. Note the optional shardId.
userPK: ({ shardId, userId }) =>
sn2u`user#${userId}|transaction${sn2e`!${shardId}`}`,
// users GSI RANGE key.
userSK: ({ merchantId, timestamp, transactionId }) =>
sn2u`timestamp#${timestamp}|merchantId#${merchantId}|transactionId#${transactionId}`,
},
// The sharding configuration for this entity.
sharding: {
// Default number of shard key characters (0 means no shard key).
nibbles: 0,
// Bits represented by each shard key character, so 3 bits means an
// octal shard key. Running with no shard key produces a single shard.
// The first shard key character yields another 8 shards, and the second
// yields an additional 64, for an eventual total of 73.
nibbleBits: 3,
// Scheduled increases in shard key length. Keys are expressed as
// millisecond UTC timestamps. In production, these should not be
// updated after they go into effect.
bumps: {
1676874972686: 1,
1708411134487: 2,
},
// Extracts entity key to be hashed for shard key.
entityKey: ({ transactionId }) => transactionId,
// Extracts timestamp to determine shard key length.
timestamp: ({ timestamp }) => timestamp,
},
},
},
// Will be added to every entity object as appropriate. Pick a value that
// won't collide with entity data!
shardKeyToken: 'shardId',
};
// Import an optional logger.
import { Logger } from '@karmaniverous/edge-logger';
const logger = new Logger('debug');
// Import EntityManager & config object.
import { EntityManager } from '@karmaniverous/entity-manager';
import { config } from './entityConfig.js';
// Create & configure an EntityManager (logger defaults to console object).
const entityManager = new EntityManager({ config, logger });
// Define a transaction object.
const transaction = {
methodId: 'methodIdValue',
merchantId: 'merchantIdValue',
timestamp: 1676869312851,
transactionId: 'transactionIdValue',
userId: 'userIdValue',
};
// Transform the transaction for posting to the database.
entityManager.addKeys(transaction);
// debug: adding sharded index keys to transaction...
// debug: {
// debug: "methodId": "methodIdValue",
// debug: "merchantId": "merchantIdValue",
// debug: "timestamp": 1676869312851,
// debug: "transactionId": "transactionIdValue",
// debug: "userId": "userIdValue"
// debug: }
// debug: generated shard key '7' for transaction id 'transactionIdValue' at timestamp 1676869312851.
// debug:
// debug: done
// debug: {
// debug: "methodId": "methodIdValue",
// debug: "merchantId": "merchantIdValue",
// debug: "timestamp": 1676869312851,
// debug: "transactionId": "transactionIdValue",
// debug: "userId": "userIdValue",
// debug: "shardId": "7",
// debug: "entityPK": "transaction!7",
// debug: "transactionSK": "timestamp#1676869312851|transactionId#transactionIdValue",
// debug: "merchantPK": "merchantId#merchantIdValue|transaction!7",
// debug: "merchantSK": "timestamp#1676869312851|methodId#methodIdValue|transactionId#transactionIdValue",
// debug: "methodPK": "method#methodIdValue|transaction!7",
// debug: "methodSK": "timestamp#1676869312851|merchantId#merchantIdValue|transactionId#transactionIdValue",
// debug: "userPK": "user#userIdValue|transaction!7",
// debug: "userSK": "timestamp#1676869312851|merchantId#merchantIdValue|transactionId#transactionIdValue"
// debug: }
// Extract key space for querying across shards by related entity.
entityManager.getKeySpace('transaction', transaction, 'userPK', 1686874972686);
// debug: getting shard key space for transaction on key 'userPK' at timestamp 1686874972686...
// debug: {
// debug: "methodId": "methodIdValue",
// debug: "merchantId": "merchantIdValue",
// debug: "timestamp": 1676876779118,
// debug: "transactionId": "transactionIdValue",
// debug: "userId": "userIdValue"
// debug: }
// debug:
// debug: done
// debug: [
// debug: "user#userIdValue|transaction",
// debug: "user#userIdValue|transaction!0",
// debug: "user#userIdValue|transaction!1",
// debug: "user#userIdValue|transaction!2",
// debug: "user#userIdValue|transaction!3",
// debug: "user#userIdValue|transaction!4",
// debug: "user#userIdValue|transaction!5",
// debug: "user#userIdValue|transaction!6",
// debug: "user#userIdValue|transaction!7"
// debug: ]
See unit tests for more usage examples.
The current design provides for scaling via planned increases in shard key length. The number of shards per key character does not need to be decided until shard keys are first applied.
This design assumes that currently-defined key structures will remain stable across the life of the database, meaning new ones could be layered on but existing ones should not be changed once in use.
The same technique that provides for shard key length bumps could also be applied to such schema changes, permitting unified query across schema changes in the same manner as the package currently supports unified query across shards.
This change can be accomplished with no breaking changes to existing implementations.
objectstringstringobjectArray.<string>Promise.<ShardedQueryResult>objectobjectobjectPromise.<ShardQueryResult>objectManage DynamoDb entities.
Kind: static class of entity-manager
objectstringstringobjectArray.<string>Promise.<ShardedQueryResult>objectobjectCreate an EntityManager instance.
Returns: EntityManager - EntityManager instance.
Throws:
Error If config is invalid.Error If logger is invalid.| Param | Type | Description |
|---|---|---|
| options | object | Options object. |
| [options.config] | object | EntityManager configuration object (see README for a breakdown). |
| [options.logger] | object | Logger instance (defaults to console, must support error & debug methods). |
objectAdd sharded keys to an entity item. Does not mutate original item.
Kind: instance method of EntityManager
Returns: object - Decorated entity item.
Throws:
Error If entityToken is invalid.Error If item is invalid.| Param | Type | Default | Description |
|---|---|---|---|
| entityToken | string | Entity token. | |
| item | object | Entity item. | |
| [overwrite] | boolean | false | Overwrite existing properties. |
stringCalculated the shard key for an entity item.
Kind: instance method of EntityManager
Returns: string - Shard key.
| Param | Type | Description |
|---|---|---|
| entityToken | string | Entity token. |
| item | object | Entity item. |
stringCondense an index object into a delimited string.
Kind: instance method of EntityManager
Returns: string - Dehydrated index.
Throws:
Error If entityToken is invalid.Error If indexToken is invalid.Error If item is invalid.| Param | Type | Default | Description |
|---|---|---|---|
| entityToken | string | Entity token. | |
| indexToken | string | Array.<string> | Index token or array of key tokens. | |
| index | object | Index object. | |
| [delimiter] | string | "~" | Delimiter. |
objectReturn the config for a given entity key token.
Kind: instance method of EntityManager
Returns: object - Entity key config.
| Param | Type | Description |
|---|---|---|
| entityToken | string | Entity token. |
| keyToken | string | Key token. |
Array.<string>Return an array of sharded keys valid for a given entity token & timestamp.
Kind: instance method of EntityManager
Returns: Array.<string> - Array of keys.
Throws:
Error If entityToken is invalid.Error If item is invalid.Error If keyToken is invalid.Error If timestamp is invalid.| Param | Type | Description |
|---|---|---|
| entityToken | string | Entity token. |
| keyToken | string | Key token. |
| item | object | Entity item sufficiently populated to generate property keyToken. |
| timestamp | number | Timestamp. |
Promise.<ShardedQueryResult>Query an entity across shards.
Kind: instance method of EntityManager
Returns: Promise.<ShardedQueryResult> - Sharded query result.
| Param | Type | Description |
|---|---|---|
| options | object | Query options. |
| options.entityToken | string | Entity token. |
| [options.keyToken] | string | Key token. |
| [options.item] | object | Entity item sufficiently populated to generate property keyToken. |
| options.shardQuery | ShardQueryFunction | Sharded query function. |
| [options.limit] | number | Request limit. |
| [options.pageKeys] | object | Map of shard page keys. |
| [options.pageSize] | number | Request page size. |
objectConvert a delimited string into a named index key.
Kind: instance method of EntityManager
Returns: object - Rehydrated index key.
Throws:
Error If entityToken is invalid.Error If indexToken is invalid.| Param | Type | Default | Description |
|---|---|---|---|
| entityToken | string | Entity token. | |
| indexToken | string | Array.<string> | Index token or array of key tokens. | |
| value | string | Dehydrated index value. | |
| [delimiter] | string | "~" | Delimiter. |
objectRemove sharded keys from an entity item. Does not mutate original item.
Kind: instance method of EntityManager
Returns: object - Stripped entity item.
Throws:
Error If entityToken is invalid.Error If item is invalid.| Param | Type | Description |
|---|---|---|
| entityToken | string | Entity token. |
| item | object | Entity item. |
objectKind: inner typedef of entity-manager
Properties
| Name | Type | Description |
|---|---|---|
| items | Array.<any> | Query result array. |
| pageKey | * | Shard page key. |
Promise.<ShardQueryResult>Shard query function
Kind: inner typedef of entity-manager
Returns: Promise.<ShardQueryResult> - Sharded query result.
| Param | Type | Description |
|---|---|---|
| shardedKey | string | Sharded key. |
| [pageKey] | * | Page key. |
| [limit] | number | Request limit. |
objectKind: inner typedef of entity-manager
Properties
| Name | Type | Description |
|---|---|---|
| items | Array.<any> | Query result array. |
| pageKeys | object | Shard page keys. |
See more great templates and other tools on my GitHub Profile!
FAQs
Rational indexing & cross-shard querying at scale in your NoSQL database so you can focus on your application logic.
The npm package @karmaniverous/entity-manager receives a total of 333 weekly downloads. As such, @karmaniverous/entity-manager popularity was classified as not popular.
We found that @karmaniverous/entity-manager demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
At its inaugural meeting, the JSR Working Group outlined plans for an open governance model and a roadmap to enhance JavaScript package management.
Security News
Research
An advanced npm supply chain attack is leveraging Ethereum smart contracts for decentralized, persistent malware control, evading traditional defenses.
Security News
Research
Attackers are impersonating Sindre Sorhus on npm with a fake 'chalk-node' package containing a malicious backdoor to compromise developers' projects.