art-aws

Streamlined APIs for AWS SDK with Promises and Art.Foundation

Currently supported:

• DynamoDb (partial support)

Streamlined DymamoDb API

Benefits

• all methods are wrapped in promises
• Streamlined API
  • cleaner and dramatically reduced param size
    • reasonable defaults
    • lowerCamelCase property names for consistency with JavaScript
    • shorter property names (without sacrificing clarity)
    • method-specific params restructuring for additional clarity and reductions
  • item data read and written is always in plain JavaScript data structures (JSON-compatible data-structures)
    • currently supported: string, number, object, array
    • future: could easily add support for all DynamoDb data-types

Streamlined API Example: property names

# Streamlined API
provisioning:
  read: 1
  write: 1

# Standard API
ProvisionedThroughput:
  ReadCapacityUnits: 1
  WriteCapacityUnits: 1

Streamlined API Example: createTable

# Streamlined API:
dynamoDb.createTable
  table: "fooBarTestTable"
  key: "chatRoom/id"
  attributes:
    id:         "number"
    chatRoom:   "string"
    createdAt:  "number"

  globalIndexes:
    chatsByChatRoomCreatedAt: "chatRoom/createdAt"
.then ->
  # ...

# Standard API:
dynamoDb.createTable
  TableName: "fooBarTestTable"
  GlobalSecondaryIndexes: [
    IndexName: "chatsByChatRoomCreatedAt"
    KeySchema: [
      {AttributeName: "chatRoom", KeyType: "HASH"}
      {AttributeName: "createdAt", KeyType: "RANGE"}
    ]
    Projection: ProjectionType: "ALL"
    ProvisionedThroughput: ReadCapacityUnits: 1, WriteCapacityUnits: 1
  ]
  KeySchema: [
    {AttributeName: "chatRoom", KeyType: "HASH"}
    {AttributeName: "id", KeyType: "RANGE"}
  ]
  AttributeDefinitions: [
    {AttributeName: "id", AttributeType: "N"}
    {AttributeName: "chatRoom", AttributeType: "S"}
    {AttributeName: "createdAt", AttributeType: "N"}
  ]
  ProvisionedThroughput: ReadCapacityUnits: 1, WriteCapacityUnits: 1
.then ->
  # ...

Streamlined API Example: query

# Streamlined API
dynamoDb.query
  table: "fooBarTestTable"
  descending: true
  where:
    chatRoom: "xyz456"
    id: gt: 1
.then ({items}) ->
  # items is an array of plain javascript objects
  # Items is the standard DynamoDb-encoded Items list

# Standard API
dynamoDb.query
  TableName: "fooBarTestTable"
  ScanIndexForward: false
  KeyConditionExpression: "(#attr1 = :val1 AND #attr2 > :val2)"
  ExpressionAttributeNames:
    "#attr1": "chatRoom"
    "#attr2": "id"

  ExpressionAttributeValues:
    ":val1": S: "xyz456"
    ":val2": N: "1"
.then ({items, Items}) ->
  # items is an array of plain javascript objects
  # Items is the standard DynamoDb-encoded Items list

Usage

• Input API
  • you can use the standard DynamoDb API params, OR
  • you can use the Streamlined API params
  • All table methods automatically detect which API you are using with this test:
    • if params.TableName
      • DynamoDb API is used
    • else
      • Streamlined API is used
      • NOTE: params.table is expected to specify the table-name
• Output API
  • The output object contains the standard DynamoDb response
    • note: DynamoDb uses UpperCamelCase property names
  • The output object may ALSO contain streamlined-api properties
    • example: the 'items' property returned by a 'query' is a list of the result items as plain-javascript objects
    • note: the streamelined-api uses lowerCamelCase property names

Creating the Client SDK

Go here: https://sdk.amazonaws.com/builder/js/

Select:

• dynamoDb
• S3

Build it, copy it locally. Then update the symlink.