dynamodb-loader-model

This module integrates the following modules:

• AWS-SDK
• DataLoader

DynamoDB without the hassle.

Getting Started

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes.

Installing

Install it via pnpm.

pnpm add dynamodb-loader-model

or npm

npm install dynamodb-loader-model

or yarn

yarn add dynamodb-loader-model

You can find an example in the examples folder, or a boilerplate at this repo

Usage

Configuration

It all starts with the configuration object, this declares the keys of the DynamoDB table, the DynamoDB client config and a formatter function for the model you want to insert. Now you can start using the model directly or extend it as with any other class.

import { Model, ModelConfig } from 'dynamodb-loader-model';

interface MyModelInterface {
  pk: string;
  sk: string;
  foo: string;
}

const modelConfig: ModelConfig<MyModelInterface> = {
  tableName: 'table',
  hashKey: 'pk',
  rangeKey: 'sk',
  formatFn: (v) => ({
    pk: v.pk,
    sk: v.sk,
    foo: v.foo || 'bar'
  })
};

class MyModel {
  _model: Model;
  constructor() {
    this._model = new Model(modelConfig);
  }

  /**
   * Here we are overriding the get method to always skip DataLoader,
   * in case you want to that.
   */
  get(key: string) {
    return this._model.get(key, true);
  }
}

Configuration object

• tableName - string - required: Table name.
• hashKey - string - required: Hash Key of the table.
• rangeKey - string: Range Key of the table.
• formatFn - function: Formatter function for the element.
• client - object: DynamoDB Client config
  • accessKeyId - string: AWS Access Key ID
  • secretAccessKey - string: AWS Secret Access Key
  • region - string: AWS region
  • endpoint - string: DynamoDB endpoint

Methods

The module exposes the following methods:

• put: Creates an item and returns it.

  put(data: Partial<T>): Promise<ModelInterface>

• remove: Removes an item.

  remove(key: string | object): Promise<boolean>

• get: Gets an item, if true is passed as the second parameter, DataLoader is skipped and the object is fetched directly from DynamoDB.

  get(key: string | object, fresh?: boolean): Promise<ModelInterface>

• batchGet: Gets many items, calling the fetch method.

  batchGet(keys: (string | object)[], fresh?: boolean): Promise<ModelInterface[]>

• update: Updates an item.

  update(key: string | object, expression: Partial<AWS.DynamoDB.DocumentClient.UpdateItemInput>, getAfterUpdate?: boolean): Promise<boolean | ModelInterface>

• putInList: Creates an item in a list If the identifierField is passed, it'll check for duplicates on that field. If not, duplicates are allowed.

  putInList<T>(key: string | object, listName: keyof ModelInterface, value: T, identifierField?: keyof T): Promise<boolean>

• updateInList: Updates an item in a list If the identifierField is passed, it'll search in the list by that field. Otherwise it'll treat the subkey as a Number index.

  updateInList<T>(key: string | object, listName: keyof ModelInterface, subkey: T[keyof T] | number, value: T, identifierField?: keyof T): Promise<boolean>

• removeFromList: Removes an item from a list If the identifierField is passed, it'll search in the list by that field. Otherwise it'll treat the subkey as a Number index.

  removeFromList<T>(key: string | object, listName: keyof ModelInterface, subkey: T[keyof T] | number, identifierField?: keyof T): Promise<boolean>

• export: Exports all items from the table with optional filtering and mapping.

  export(filterFn?: (element: ModelInterface) => boolean, mapFn?: (element: ModelInterface) => ModelInterface): Promise<ModelInterface[]>

Running the tests

Prerequisites

In order to run the tests you need to have oss-serverless (osls) installed.

pnpm add -g osls

Clone the repository and install dependencies.

git clone https://gitlab.com/gotoar/dynamodb-loader-model.git
pnpm install

Run the tests.

pnpm run test

This will get you a copy of dynamodb-local, run it, run the tests and then kill the dynamodb-local process.

And coding style tests

You can check linting with this command.

pnpm run lint

Dependencies

• @aws-sdk/client-dynamodb
• @aws-sdk/lib-dynamodb
• dataloader

Contributing

Please read CONTRIBUTING.MD for details on our code of conduct, and the process for submitting merge requests to us.

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

Authors

• Tomas Gorkin - Initial work

See also the list of contributors who participated in this project.

License

This project is licensed under the MIT License - see the LICENSE.md file for details

Acknowledgments

• Hat tip to anyone whose code was used
• Inspiration
• etc