saibotsivad / dynamodb

Minimalist DynamoDB request generator.

@saibotsivad/dynamodb

Generate signed HTTP requests to AWS DynamoDB.

Install

The normal way:

npm install @saibotsivad/dynamodb

Overview

Instantiate with the normal AWS credentials and a fetch-like interface (see below for compatability notes), then call it to make requests:

import { dynamodb } from '@saibotsivad/dynamodb'

// Normal AWS IAM credentials:
const credentials = {
	region: 'us-east-1',
	secretAccessKey: 'hKVU_EXAMPLE_SECRET_5rjo',
	accessKeyId: 'AKIA_EXAMPLE_KEY'
}

// In a Worker environment (aka Cloudflare Workers) you can use the
// global fetch directly:
const db = dynamodb({ credentials, fetch: globalThis.fetch })

// But in the NodeJS environment, you'll need to use something like "httpie":
import { post } from 'httpie' // only POST is used
const fetch = async (url, options) => post(url, options)
const db = dynamodb({ credentials, fetch })

const response = await db('PutItem', {
	ReturnConsumedCapacity: 'TOTAL',
	TableName: 'Music',
	Item: {
		AlbumTitle: {
			S: 'Somewhat Famous'
		},
		Artist: {
			S: 'No One You Know'
		},
		SongTitle: {
			S: 'Call Me Today'
		}
	},
})
// response => { ConsumedCapacity: { CapacityUnits: 1, TableName: 'Music' } }

Error Handling

If the response is an error, for example if you try to PutItem on a table that doesn't exist, calling await db will throw an error named AwsException that contains the following properties:

• name: String - Will always be AwsException.
• method: String - This is simply the method name that you provided, e.g. PutItem.
• params: Object - These are the parameters that were used, e.g. { TableName, Item }.
• type: String - The long-form error code from AWS, e.g. com.amazonaws.dynamodb.v20120810#ResourceNotFoundException.
• code: String - The short-form error code, e.g. ResourceNotFoundException.

API

Instantiate a database using the AWS credentials, and a fetch-like object:

import { dynamodb } from '@saibotsivad/dynamodb'
const db = dynamodb({
	credentials: {
		region: 'us-east-1',
		secretAccessKey: 'hKVU_EXAMPLE_SECRET_5rjo',
		accessKeyId: 'AKIA_EXAMPLE_KEY'
	},
	fetch: globalThis.fetch
})

The fetch function must have a signature like async (method: string, params: object) and return one of the following:

• { json: async function } - The normal fetch does this.
• { data: string | object } - If the data property is an object it'll get returned, or if it's a string it'll get JSON-parsed.
• { body: string | object } - Same thing with the body property.

Methods

The DynamoDB API supports all valid DynamoDB service methods.

How to Read the Docs

To figure out what your request parameters and response object should look like, have a look at the AWS docs.

• v2: For each link, there is a description of the service and an example of its use. For each service, after the example is a long, sometimes difficult to read, list of parameters and their meaning.
• v3: For each link you'll find the same description and examples, but the request parameters are called "input" and the response is called "output". For example, on the BatchGetItem docs page, you'll find a link to BatchGetItemCommandInput and BatchGetItemCommandOutput which you'll need to click into to figure out the parameters of each.

• BatchGetItem (v2 docs | v3 docs)
• BatchWriteItem (v2 docs | v3 docs)
• CreateBackup (v2 docs | v3 docs)
• CreateGlobalTable (v2 docs | v3 docs)
• CreateTable (v2 docs | v3 docs)
• DeleteBackup (v2 docs | v3 docs)
• DeleteItem (v2 docs | v3 docs)
• DeleteTable (v2 docs | v3 docs)
• DescribeBackup (v2 docs | v3 docs)
• DescribeContinuousBackups (v2 docs | v3 docs)
• DescribeContributorInsights (v2 docs | v3 docs)
• DescribeEndpoints (v2 docs | v3 docs)
• DescribeGlobalTable (v2 docs | v3 docs)
• DescribeGlobalTableSettings (v2 docs | v3 docs)
• DescribeLimits (v2 docs | v3 docs)
• DescribeTable (v2 docs | v3 docs)
• DescribeTableReplicaAutoScaling (v2 docs | v3 docs)
• DescribeTimeToLive (v2 docs | v3 docs)
• GetItem (v2 docs | v3 docs)
• ListBackups (v2 docs | v3 docs)
• ListContributorInsights (v2 docs | v3 docs)
• ListGlobalTables (v2 docs | v3 docs)
• ListTables (v2 docs | v3 docs)
• ListTagsOfResource (v2 docs | v3 docs)
• PutItem (v2 docs | v3 docs)
• Query (v2 docs | v3 docs)
• RestoreTableFromBackup (v2 docs | v3 docs)
• RestoreTableToPointInTime (v2 docs | v3 docs)
• Scan (v2 docs | v3 docs)
• TagResource (v2 docs | v3 docs)
• TransactGetItems (v2 docs | v3 docs)
• TransactWriteItems (v2 docs | v3 docs)
• UntagResource (v2 docs | v3 docs)
• UpdateContinuousBackups (v2 docs | v3 docs)
• UpdateContributorInsights (v2 docs | v3 docs)
• UpdateGlobalTable (v2 docs | v3 docs)
• UpdateGlobalTableSettings (v2 docs | v3 docs)
• UpdateItem (v2 docs | v3 docs)
• UpdateTable (v2 docs | v3 docs)
• UpdateTableReplicaAutoScaling (v2 docs | v3 docs)
• UpdateTimeToLive (v2 docs | v3 docs)

License

Published and released under the VOL.