type-dynamodb

type-dynamodb is simple but powerful dynamodb ORM that uses decorator design pattern to get the most benefits from typescript and oop like inheritance, overload methods and adding multiple layers of decorators.

Installation

• first install the lib and its peerDependencies

npm i class-transformer aws-sdk type-dynamodb --save

• install reflect-metadata :

npm install `reflect-metadata` --save

• add reflect-metadata to the root file of your project

import "reflect-metadata";

• make sure to set AWS credients in your env variables using command line or .env ...etc:

export AWS_ACCESS_KEY_ID=<AWS_ID> # macos or linux
export AWS_SECRET_ACCESS_KEY=<AWS_ACCESS_KEY>
export AWS_DEFAULT_REGION=<AWS_REGION>

or here for other os.

• in typescript, you need to add the following config to your tsconfig.json:

"emitDecoratorMetadata": true,
"experimentalDecorators": true,

Usage example with table User:

1- first we add @DyTable decorator and extends BaseDyTable to get the db functionalities.

@DyTable('<TableName>') // default is User
class User extends BaseDyTable{
    id: string
    name: string
    userPassword: string
    created: string
}

2- then we determined which fields are part of our dynamodb table by adding @DyField:

@DyTable()
class User extends BaseDyTable{
    @DyField()
    id: string

    @DyField()
    name: string

    @DyField()
    userPassword: string

    @DyField()
    created: string
}

3- then we specify the partition key field in @DyField and sorting key fields if exist:

    ...

    @DyField({isPartitionKey: true})
    id: string

    @DyField({isSortingKey: true})
    created: string
    
    ...

4- now we can use the db functions (dyGet, dyUpdate, dyDelete, dyPut, dyScan, dyQuery) as shown here:

    /* using await */
    
    const user = await User.dyGet({id: "id1"})
    await user.dyUpdate({userPassword: "12345"});
    await user.dyDelete();
    // scan function
    const scannedUsers = await User.dyScan(
        {
            filter: {
                created: {range: {to:"<ISOSTRING>"}},
                name: {equal: "Amro"}
            },// note every key can have only one   filter parameter.
            limit: 50,
        }
    );
    // faster query method that uses PartitionKey(must be specified) and specify sortingKey automatically
    const users = await User.dyQuery(
        "PARTITION_KEY_VALUE",
        {
        filter: {
                created: {range: {from:"<ISOSTRING>"}},
                name: {contains: "Amro"}
            } 
        }
    );

    /* using then */
    User.dyGet({id: "user1"})
        .then((user)=> user.dyUpdate( {userPassword: "12345"}))
        .then((updatedUser)=> {
            // some other logic
            updatedUser.dyDelete();
        })

DyGlobalSecondaryIndex and DyLocalSecondaryIndex

• for specifying local and global secondary index, use the following decorators:

@DyTable()
class User {
    ... 

    @DyGlobalSecondaryIndex("name_index", {isPartitionKey: true})
    @DyField()
    name: string

    @DyLocalSecondaryIndex("created_index")
    @DyField({isSortingKey: true})
    created: string
    
    ...
}

• to use it specify the IndexName in the filter options: