Sign Up for Free

RunKit +

Try any Node.js package right in your browser

This is a playground to test code. It runs a full Node.js environment and already has all of npm’s 1,000,000+ packages pre-installed, including dynamo-easy with all npm packages installed. Try it out:

require("aws-sdk/package.json"); // aws-sdk is a peer dependency. require("lodash/package.json"); // lodash is a peer dependency. require("moment/package.json"); // moment is a peer dependency. require("rxjs/package.json"); // rxjs is a peer dependency. var dynamoEasy = require("dynamo-easy")

This service is provided by RunKit and is not affiliated with npm, Inc or the package authors.

dynamo-easy v0.10.1

Use the power of typescript to define your object mapping when using dynamodb. This library also provides a fluent api for easy interaction with dynamodb.


Travis Coverage Status Dev Dependencies Greenkeeper badge styled with prettier All Contributors

Abstracts away the complexity of the low level aws dynamosdk. Provides an easy to use fluent api to for requests and supports typescript decorators, to define some metadata for your models. You don't need to care about the mapping of javascript types to their dynamo types any more. We got you covered.

Checkout the full technical api documentation here.

Built with :heart: by shiftcode.

Get Started

class Person{
  id: string
  name: string

const dynamoStore = new DynamoStore(Person)

// add a new item
dynamoStore.put({name: 'peter'})
    console.log('peter was saved')

// search for all persons which start with the character 'p'
  .subscribe((persons: Person[])=>{
    console.log('got persons')
// returns all persons
  .subscribe((persons: Person[]) => {
    console.log('all persons')

Want to use this library with Angular (>4) checkout our angular-service.


Decorators are used to add some metadata to our model classes, relevant to our javascript-to-dynamo mapper.

This is an experimental feature and requires to set the following typescript compiler options:

  • "experimentalDecorators": true
  • "emitDecoratorMetadata": true

Additionally we rely on the reflect-metadata ( library for reflection api.

To get started with decorators just add a @Model() Decorator to any typescript class.

If you need to read the metadata by hand for some purpose, use the MetadataHelper to read the informations.

We make heavy usage of compile time informations about our models and the property types. Here is a list of the types that can be retrieved from compile time information for the key design:type. (The metadata will only be added if at least one decorator is present on a property)

  • String
  • Number
  • Boolean
  • Array (no generics)
  • Custom Types
  • ES6 types like Set, Map will be mapped to Object when calling for the type via Reflect.get(design:type), so we need some extra info.

Generic information is never available due to some serialization limitations at the time of writing.


Custom TableName

Here is the rule how a table name is built ${kebabCase(modelName)}s so for a model called Product the table will be named products, this is a default implementation.

There are two possibilities to change the name:

  • override the name using the tableName parameter @Model({tableName: tableName})
  • provide a TableNameResolver function when instantiating a DynamoStore. This method will receive the default table name (either resolved using the model name or custom value when a tableName was provided in @Model decorator)



We do the mapping from javascript objects to dynamodb types for you in requests and responses

Simple Type (no decorators required to work)

  • String
  • Number
  • Boolean
  • Null
  • Array
  • Date (we only support MomentJS)

Complex Types (properties with these types need some decorators to work properly)

  • Set<simpleType | complexType>
  • Map
  • Array
TS TypeDynamo Type
moment.MomentS (ISO-8601 formatted)
ArrayL, (S,N,B)S
ES6 SetL, (S,N,B)S
BinaryNot Supported
ES6 MapNot Supported
DateNot Supported

Custom Attribute Mapping

It is always possible to define a custom mapping strategy, just implement the MapperForType class.

Collection Mapping (Array & Set)


Javascript Arrays with a items of type String, Number or Binary will be mapped to a S(et) type, by default all other types are mapped to L(ist) type. If the items have a complex type it will be mapped to a L(ist).


An instance of ES6 Set type will be mapped to a S(et) type if the type of the items is supported (String, Number, Binary), otherwise it is mapped to a L(ist).

When one of the following decorators is present, the value is always mapped to a L(ist).

  • @SortedSet(itemType?: ModelClazz) - only L(ist) type preserves order
  • @TypedSet(itemType?: ModelClazz) - if the itemType is not one of String | Number | Binary
  • @TypedArray()


Right now we only support MomentJS Dates.

If you want to explicitly mark a property to be a Date use the @Date() decorator. If we find a moment value we automatically map it to a String (using ISO-8601 format). When coming from db we do a regex test for ISO-8601 format and map it back to a moment object.


Enum values are persisted as Numbers (index of enum).

Request API

To start making requests create an instance of DynamoStore and execute the desired operation using the provided api. We support the following dynamodb operations with a fluent api:

  • Put
  • Get
  • Update
  • Delete
  • Scan
  • Query
  • BatchGet
  • MakeRequest (generic low level method for special scenarios)

There is always the possibility to access the Params object directly to add values which are not covered with our api.


In a real world scenario you'll have some kind of authentication to protect your dynamodb ressources. You can customize on how to authenticate when providing a custom SessionValidityEnsurer function to the DynamoStore when creating a new instance. The default implementation is a no-op function.

Session Validity Ensurer

Here is an example of an implementation using amazon cognito

function sessionValidityEnsurer(): Observable<boolean> {
  return Observable.of(this.isLoggedIn())
    .switchMap(isLoggedIn => {
       if (isLoggedIn) {
          this.logger.debug('withValidSession :: cognitoService.isLoggedIn() -> we have a valid session -> proceed')
          return Observable.of(true)
        } else {
          this.logger.debug('withValidSession :: cognitoService.isLoggedIn() -> user is not logged in or token expired, try to get a new session')
          return this.getUser()
            .catch((err, caught): Observable<boolean> => {
              this.logger.error('withValidSession :: there was an error when refreshing the session', err)
              throw new AuthError('SC_UNAUTHENTICATED', 'Could not refresh the token' + JSON.stringify(err))
            .do(user => this.logger.debug('withValidSession :: we got new valid session', user))
      .map((value: boolean | CognitoUser) => {

Expressions (AWS Doc)

By default we create a substitution placeholder for all the attributes, just to not implement a blacklist with reserved words in the context of aws dynamodb.

attributename: age

expression: '#age = :age' 
attributeExpressionNames: {'#age': 'age'}
attributeExpressionValues: {':age': {N: '10'}}

this works seemlesly for top level attribtues, but if we wanna build an expression for where the attribute needs to be accessed with a document path, we need some special logic nested attribute: person.age

attributeExpressionNames: {'#person':'person', '#age': 'age'}
attributeExpressionValues: {':age': {N: '10'}}
expression: '#person.#age = :age'

we can't use #personAge as a placeholder for 'person.age' because if the dot is part of an attribute name it is not treated as a metacharacter compared to when using directly in expression, so the above solution needs to be used

these are the accessor rules for nested attribute types

  • [n] — for list elements
  • . (dot) — for map elements




There are two scenarios for a batch get item request. One is requesting multiple items from one table by id and the other is requesting multiple items by id from multiple tables. The first scenario is support using DynamoStore.batchGet() the second one must be implemented using the BatchGetItem class.

const request = new BatchRequest()

// table with simple primary key
request.forModel(MyModelClass, ['idValue', 'idValue2'])

// table with composite primary key (sortkey is optional)
request.forModel(MyOtherModelClass, [{partitionKey: 'id', sortKey: 'sortKeyValue'}])

request.exec().subscribe(response => {
  // an object where the items are mapped to the table name 


NPM scripts

  • npm t: Run test suite
  • npm start: Runs npm run build in watch mode
  • npm run test:watch: Run test suite in interactive watch mode
  • npm run test:prod: Run linting and generate coverage
  • npm run build: Generage bundles and typings, create docs
  • npm run lint: Lints code
  • npm run commit: Commit using conventional commit style (husky will tell you to use it if you haven't :wink:)

Automatic releases

Use the npm comand npm run commit, which is a convenient way to create conventional commits. Those messages are used to run semantic releases, which publishes our code automatically on github and npm, plus generates automatically a changelog. This setup is highly influenced by Kent C. Dodds course on

Git Hooks

We use 2 git hooks:



  • to check if the code can be built running npm run build
  • to check if all tests pass



Made with :heart: by @michaelwittwer and all these wonderful contributors (emoji key):

| [
Michael Wittwer](
[💻]( "Code") [📖]( "Documentation") [⚠️]( "Tests") | | :---: |

This project follows the all-contributors specification. Contributions of any kind welcome!


RunKit is a free, in-browser JavaScript dev environment for prototyping Node.js code, with every npm package installed. Sign up to share your code.
Sign Up for Free