@awsless/dynamodb NPM

@awsless/dynamodb

The @awsless/dynamodb package provides a small and tree-shakable layer around aws-sdk v3, to make working with the DynamoDB API super simple.

The Problem

Floating Point Precision - Almost no DynamoDB clients are suitable when floating point precision is important. We use our @awsless/big-float package to solve this problem.
Tree-shakable - The API is designed to balance tree-shakability vs providing a fully typed API.
Query Builder - Type safe & easy to use query expression builder.
Testing - We provide a local DynamoDB server and mock that will route all DynamoDB requests to the local DynamoDB server.

Setup

Install with (NPM):

npm i @awsless/dynamodb

Basic Usage

import { putItem, getItem, define, ... } from '@awsless/dynamodb';

const posts = define('posts', {
	hash: 'userId',
	sort: 'id',
	schema: object({
		id: number(),
		userId: number(),
		title: string(),
	})
})

// Insert a post into the posts table
await putItem(posts, {
	id: 1,
	userId: 1,
	title: 'Hello World'
})

// Get a post from the posts table
const user = await getItem(posts, { userId: 1, id: 1 })

// Update a post in the posts table
await updateItem(posts, { userId: 1, id: 1 }, {
	update(exp) {
		return exp.update('title').set('Hi...')
	}
})

// Delete a post in the posts table
await deleteItem(posts, { userId: 1, id: 1 })

// List posts from user 1
const { items, cursor } = await query(posts, {
	keyCondition(exp) {
		return exp.where('userId').eq(1)
	}
})

// List posts from user 1 but with stringified cursors
const { items, cursor } = await paginateQuery(posts, {
	keyCondition(exp) {
		return exp.where('userId').eq(1)
	}
})

// List posts
const { items, cursor } = await scan(posts)

// List all posts
for await(const items of scanAll(posts, { batch: 100 })) {
	// Processing batches of 100 items at a time...
	...
}

// Write a transaction
await transactWrite({
	items: [
		transactConditionCheck(posts, { userId: 1, id: 0 }, {
			condition(exp) {
        		return exp.where('id').not.exists
        	}
		}),

		transactPut(posts, { userId: 1, id: 1, title: 'Post 1' }),
		transactPut(posts, { userId: 1, id: 2, title: 'Post 2' }),
		transactPut(posts, { userId: 1, id: 3, title: 'Post 3' }),
	]
})

Mock for testing

import { mockDynamoDB, seedTable, ... } from "@awsless/dynamodb";

const posts = define('posts', {
	hash: 'id',
	schema: object({
		id: number(),
		title: string(),
	})
})

mockDynamoDB({
  tables: [ posts ],
  seeds: [
	seedTable(posts, {
		id: 1,
		title: 'Hello World',
	})
  ]
})

it('your test', async () => {
	const result = await getItem(posts, { id: 1 })
})

Schema Types

We provides the following schema types:

array
bigfloat
bigint
binary
boolean
date
enums
number
object
optional
record
string
ttl
unknown
uuid
bigintSet
binarySet
numberSet
stringSet

The binary & binarySet schema type supports the following input value types:

ArrayBuffer, Blob, Buffer, DataView, File, Int8Array, Uint8Array, Uint8ClampedArray, Int16Array, Uint16Array, Int32Array, Uint32Array, Float32Array, Float64Array, BigInt64Array, BigUint64Array

And the output value type is always Uint8Array.

Operation Functions

Type	Description
`getItem`	Get an item
`putItem`	Store an item
`updateItem`	Update an item
`deleteItem`	Delete an item
`getIndexedItem`	Get an item from a specific index
`query`	Query a list of items
`queryAll`	Query a list of items
`paginateQuery`	Pagination helper to query a list of items
`scan`	Scan the table for items
`scanAll`	Scan the table for items
`paginateScan`	Pagination helper to scan a list of items
`batchGetItem`	Batch get items
`batchPutItem`	Batch store items
`batchDeleteItem`	Batch delete items
`transactWrite`	Execute a transactional write
`transactPut`	Store an item transactionally
`transactUpdate`	Update an item transactionally
`transactDelete`	Delete an item transactionally
`transactConditionCheck`	Conditional check transactionally

Typescript Infer Types

`InferInput<T>`

Infer the item type of a table definition when inserting an item.

`InferOutput<T>`

Infer the item type of a table definition when querying an item.

import { define, InferInput, InferOutput, object, uuid, number, string, binary } from "@awsless/dynamodb";

const posts = define('posts', {
	hash: 'id',
	schema: object({
		id: uuid(),
		title: string(),
		likes: number(),
		data: binary(),
	})
})

/* {
  id: UUID,
  title: string,
  likes: number,
  data: BinaryValue
} */
type Post1 = InferInput<typeof posts>

/* {
  id: UUID,
  title: string,
  likes: number,
  data: Uint8Array
} */
type Post2 = InferOutput<typeof posts>