Quick Start

Let's see a simple example of creating Blog model for quick start!
This guide assumes basic understanding about below things from readers:

  • Typescript
  • ES6 Async & Await
  • AWS DynamoDB
    • concept of aws credential / IAM / region

1. Install

npm install @serverless-seoul/dynamorm

2. TSC setting

Dynamorm utilize reflect-metadata to read metadata (usually type of variables) from Typescript code. to do so, you must enable those options.

/**
 * tsconfig.json
 */
{
    "compilerOptions": {
        // other options..
        //
        "experimentalDecorators": true, // required
        "emitDecoratorMetadata": true // required
    }
}

2. Define your model

/**
 * src/blog_post.ts
 */
import {
  Config,
  Decorator,
  Query,
  Table,
} from "@serverless-seoul/dynamorm";

@Decorator.Table({ name: `your_table_name_on_aws_dynamodb` })
export class BlogPost extends Table {
  // Here we define this tables primaryKey as "Hash" - which means it'll only have hash key, no rangekey
  @Decorator.HashPrimaryKey("id")
  public static readonly primaryKey: Query.HashPrimaryKey<BlogPost, number>; 

  // Writer is optional syntax sugar - only needed for none instance method operations, such as batchUpdate
  @Decorator.Writer()
  public static readonly writer: Query.Writer<BlogPost>;

  // Name stands for how this attribute will be mapped into DynamoDB record's attribute
  @Decorator.Attribute({ name: "id" })
  public id: string!;

  @Decorator.Attribute({ name: "title" })
  public title: string!;

  // DynamoDB can take any json representable plain javascript object as attribute
  @Decorator.Attribute({ name: "body" })
  public body: Array<
    | { type: "text", text: string }
    | { type: "image", url: string, width: number, height: number }
  > = [];

  /**
   * You can skip "name", 
   * this is equal to @Decorator.Attribute({ name: "viewCount" })
   */
  @Decorator.Attribute()
  public viewCount: number = 0;

  @Decorator.Attribute()
  public author: {
    name: string;
    profileImageURL: string;
  }
}

3. Use it!

/**
 * src/test.ts
 */
import { BlogPost } from "./blog_post";

async function test() {
  // Create table(including index / TTL) at AWS, based on configuration from the table
  await BlogPost.createTable();

  // Drop table from AWS
  await BlogPost.dropTable();

  // Creating Record
  let post = new BlogPost();
  post.id = "first-blog-post";
  post.title = "My First Blog Post";
  post.body = [
    { type: "text", text: "Some great header" },
    { type: "image", url: "http://some-great-image", width: 1000, height: 1000 },
    { type: "text", text: "Some great footer" },
  ]
  post.viewCount = 0;
  await post.save();

  // Inserting multiple records at once (through DynamoDB batchPut API)
  await BlogPost.writer.batchPut([
    new BlogPost(),
    new BlogPost()
  ]);

  // Find Record
  let post = await BlogPost.primaryKey.get("first-blog-post");

  // BatchGet
  // This array is strongly typed such as Array<[number, string]> so don't worry.
  await BlogPost.primaryKey.batchGet([
    "first-blog-post",
    "second-blog-post"
  ])
  
  // Delete record
  await post.delete()
}
test();

4. Configure your AWS Credentials

Dynamorm rely on aws-sdk's official credential system, Docs

export AWS_ACCESS_KEY_ID = "Your AWS Access Key ID"
export AWS_SECRET_ACCESS_KEY = "Your AWS Secret Access Key"
export AWS_REGION = "ap-northeast-2"

5. Run

npx ts-node ./src/test.ts
← IntroductionModel →