dynamo-light

A light library for easy access to dynamodb tables

Installation

npm install --save dynamo-light

AWS Configurations

Set AWS configurations in environment variables:

export AWS_ACCESS_KEY_ID="Your AWS Access Key ID"
export AWS_SECRET_ACCESS_KEY="Your AWS Secret Access Key"
export AWS_REGION="us-west-2"

Quick Start:

Assume you have a simple table - Users with partitionKey userName (demo purpose only, use unique field - such as uuid, in real projects).

const { Table } = require("dynamo-light");
const userTable = new Table("Users");

Get:

const user = await userTable.get("WarrenBuffett"); // implicit keyExpression

OR

const user = await userTable.get({ userName: "WarrenBuffett" }); // explicit keyExpression

Put:

await userTable.put({
  username: "JackMa",
  age: 53,
  occupation: "investor"
});

Update:

await userTable.update("JackMa", {
  age: 54,
  occupation: "entrepreneur"
});

OR

await userTable.update(
  { userName: "JackMa" },
  {
    age: 54,
    occupation: "entrepreneur"
  }
);

Delete:

await userTable.delete("JackMa");

Scan:

const users = await userTable.scan(); // with pagination
const users = await userTable.scan({}, { pagination: false }); // fetch all

More examples:

Tables with sortKey/hashKey:

For a table populationTable that has country as partitionKey and year as sortKey:

Get

await populationTable.get({
  country: "Canada",
  year: 2000
});

Put

await populationTable.put({
  country: "Canada",
  year: 2001,
  population: 31.01,
  unit: "million",
  alias: "CA"
});

Update:

await populationTable.update(
  {
    country: "Canada",
    year: 2001
  },
  {
    population: 31.02
    // ... other new fields
  }
);

Delete:

await populationTable.delete({
  country: "Canada",
  year: 2001
});

Query:

await populationTable.query(
  {
    country: "Canada"
  },
  { pagination: false }
); // Returns all canada population records

await populationTable.query({
  country: "Canada",
  year: 1949,
  sortKeyOperator: ">="
}); // Returns canada population records whose year is larger or equals to 1949

await populationTable.query({
  country: "Canada",
  year: [1949, 1960],
  sortKeyOperator: "BETWEEN"
}); // Returns canada population records whose year is between 1949 and 1960 (inclusive)

Here is a list of the available sortKeyOperators.

Tables with indexes:

Assume table populationTable has a global secondary index alias-year-index. Its partitionKey is alias and sortKey is year:

Query:

await populationTable.query({
  indexName: "alias-year-index",
  alias: "CA",
  year: 1949,
  sortKeyOperator: ">="
}); // Returns records whose year is larger or equals to 1949 and alias is "CA"

Available SortKeyOperators:

= | < | <= | > | >= | BEGINS_WITH | BETWEEN

Develop:

Install dependencies

npm ci

Test

Install dynamodb local:

npm run setupTestEnv

Spin up a local dynamodb and seed DB tables:

npm run startDynamo

In a different tab, you can run tests using

npm run test