easy-ddb

    1.0.9 • Public • Published

    Easy Dynamo DB

    The idiot-proof way to interact with AWS DynamoDB from JS/TS

    Overview

    Easy Dynamo was made so that you don't have to think about the AWS wrappers when dealing with DynamoDB at all. All interactions will give you JSON objects that look the way they did in your code when they were added to dynamo, so you can move data back and forth to dynamo effortlessly.

    Getting Started

    Install

    npm install easy-ddb

    Example

    For simplicity, here's example code and output so you can start building right away (see ./examples/example.js for the runnable example)

    Code

    const EasyDynamo = require("easy-ddb");
    
    // Assume the keys to MyTable are
    // Hash key: myHashKey of type string
    // Range key: myRangeKey of type string
    const tableName = "MyTable";
    
    const dynamo = new EasyDynamo({
      accessKeyId: "Enter yours here",
      secretAccessKey: "Enter yours here",
      region: "Enter yours here",
      // Uncomment endpoint if you are testing with the local dynamodb server
      // endpoint: "http://localhost:8000",
    });
    
    (async () => {
      const keys = { myHashKey: "abc", myRangeKey: "def" };
      const myItem1 = {
        myHashKey: "abc",
        myRangeKey: "def",
        myNum: 1,
        myList: ["foo", "bar"],
        myNested: { nestedString: "abc", nestedNum: 2 },
      };
      await dynamo.put({ item: myItem1, tableName });
      console.log("After put myItem1", await dynamo.get({ keys, tableName }));
    
      const myItem2 = {
        myHashKey: "abc",
        myRangeKey: "woah",
        isFriend: true,
      };
      await dynamo.put({ item: myItem2, tableName });
      console.log(
        "Query after put of myItem2",
        await dynamo.query({
          keyName: "myHashKey",
          value: "abc",
          tableName,
        })
      );
    
      await dynamo.update({
        keys,
        propsToUpdate: { myNum: 3, poptartType: "Smores" },
        tableName,
      });
      console.log(
        "Get myItem1 after update",
        await dynamo.get({ keys, tableName })
      );
      await dynamo.incrementValue({ keys, attrNames: ["myNum"], tableName });
      console.log(
        "Get myItem1 after increment attribute",
        await dynamo.get({ keys, tableName })
      );
    
      await dynamo.incrementValue({
        keys,
        attrNames: ["myNested", "nestedNum"],
        tableName,
      });
      console.log(
        "Get myItem1 after increment nested attribute",
        await dynamo.get({ keys, tableName })
      );
    
      const gotItemAfterIncr = await dynamo.get({ keys, tableName });
      console.log("Get myItem1 after increment nested attribute", gotItemAfterIncr);
    })();
    

    Output

    After put myItem1 {
      myHashKey: 'abc',
      myNum: 1,
      myNested: { nestedNum: 2, nestedString: 'abc' },
      myRangeKey: 'def',
      myList: [ 'bar', 'foo' ]
    }
    Query after put of myItem2 [
      {
        myHashKey: 'abc',
        myNum: 1,
        myNested: { nestedNum: 2, nestedString: 'abc' },
        myRangeKey: 'def',
        myList: [ 'bar', 'foo' ]
      },
      { myHashKey: 'abc', myRangeKey: 'woah', isFriend: true }
    ]
    Get myItem1 after update {
      myHashKey: 'abc',
      myNested: { nestedNum: 2, nestedString: 'abc' },
      myNum: 3,
      myRangeKey: 'def',
      poptartType: 'Smores',
      myList: [ 'bar', 'foo' ]
    }
    Get myItem1 after increment attribute {
      myHashKey: 'abc',
      myNested: { nestedNum: 2, nestedString: 'abc' },
      myNum: 4,
      myRangeKey: 'def',
      poptartType: 'Smores',
      myList: [ 'bar', 'foo' ]
    }
    Get myItem1 after increment nested attribute {
      myHashKey: 'abc',
      myNested: { nestedNum: 3, nestedString: 'abc' },
      myNum: 4,
      myRangeKey: 'def',
      poptartType: 'Smores',
      myList: [ 'bar', 'foo' ]
    }
    Get myItem1 after increment nested attribute {
      myHashKey: 'abc',
      myNested: { nestedNum: 3, nestedString: 'abc' },
      myNum: 4,
      myRangeKey: 'def',
      poptartType: 'Smores',
      myList: [ 'bar', 'foo' ]
    }
    

    Functions

    put: Add an item to a dynamo table
    get: Get an item from a dynamo table
    delete: Delete an item from a dynamo table
    update: Update an item in a dynamo table (adding the item if it does not yet exist)
    query: Query a dynamo table
    queryOnSecondaryIndex: Query a dynamo table on its secondary index
    scan: Scan a dynamo table
    clearTable: Clear a dynamo table
    updateAddToSet: Add element to a set in a dynamo table
    updateDeleteFromSet: Delete element from a set in a dynamo table
    incrementValue: Increment the value of a particular attribute of a particular entry
    decrementValue: Decrement the value of a particular attribute of a particular entry.
    

    Quick pointers

    • Look at the example, it should make everything obvious
    • All functions are async
    • For write operations (put, update, updateAddToSet, incrementValue, etc.), the return type is promise resolving to void unless an error occurs, in which case the promise will reject with that error
    • For read operations (get, query, scan, queryOnSecondaryIndex, etc.), the return type is promise resolving to the item (or null if item is not found), a list of items, a count of the items (if onlyCount is true) unless an error occurs, in which case the promise will reject with that error

    Install

    npm i easy-ddb

    DownloadsWeekly Downloads

    23

    Version

    1.0.9

    License

    MIT

    Unpacked Size

    44.8 kB

    Total Files

    8

    Last publish

    Collaborators

    • paluter