@awsless/dynamodb-server

A local DynamoDB server for testing and development. Provides both a fast in-memory implementation and a Java-based implementation using the official AWS DynamoDB Local.

Features

• Fast In-Memory Engine - Lightning fast in-memory implementation for rapid testing
• Java Engine - Full compatibility mode using the official AWS DynamoDB Local
• DynamoDB Streams - Support for stream callbacks on item changes
• TTL Support - Time-to-live expiration for items
• GSI/LSI Support - Global and Local Secondary Index support
• Multi Key for GSI Support - Multi-key support for Global Secondary Indexes

Setup

Install with (NPM):

npm i @awsless/dynamodb-server

Basic Usage

import { DynamoDBServer } from '@awsless/dynamodb-server'

// Create a server with the fast in-memory engine (default)
const server = new DynamoDBServer()

// Or use the Java engine for full compatibility
const server = new DynamoDBServer({ engine: 'java' })

// Start the server
await server.listen(8000)

// Get a DynamoDB client configured to use the local server
const client = server.getClient()

// Get a DynamoDB Document client
const documentClient = server.getDocumentClient()

// Stop the server when done
await server.stop()

Engines

Memory Engine (Default)

The in-memory engine is optimized for speed and is perfect for unit tests. It implements the core DynamoDB operations without requiring Java.

const server = new DynamoDBServer({ engine: 'memory' })

Java Engine

The Java engine uses AWS DynamoDB Local for full compatibility with DynamoDB behavior. Requires Java to be installed.

const server = new DynamoDBServer({ engine: 'java' })

Configuration Options

const server = new DynamoDBServer({
	// Engine type: "memory" (default) or "java"
	engine: 'memory',

	// Hostname to bind to (default: "localhost")
	hostname: 'localhost',

	// Port to listen on (default: auto-assigned)
	port: 8000,

	// AWS region (default: "us-east-1")
	region: 'us-east-1',
})

Stream Support

You can subscribe to item changes using stream callbacks:

const unsubscribe = server.onStreamRecord('my-table', record => {
	console.log('Stream event:', record.eventName) // INSERT, MODIFY, or REMOVE
	console.log('Keys:', record.dynamodb.Keys)
	console.log('New Image:', record.dynamodb.NewImage)
	console.log('Old Image:', record.dynamodb.OldImage)
})

// Unsubscribe when done
unsubscribe()

Testing with Vitest/Jest

import { DynamoDBServer } from '@awsless/dynamodb-server'
import { CreateTableCommand } from '@aws-sdk/client-dynamodb'
import { PutCommand, GetCommand } from '@aws-sdk/lib-dynamodb'

describe('My DynamoDB Tests', () => {
	const server = new DynamoDBServer()

	beforeAll(async () => {
		await server.listen()

		// Create your tables
		await server.getClient().send(
			new CreateTableCommand({
				TableName: 'users',
				KeySchema: [{ AttributeName: 'id', KeyType: 'HASH' }],
				AttributeDefinitions: [{ AttributeName: 'id', AttributeType: 'N' }],
				BillingMode: 'PAY_PER_REQUEST',
			})
		)
	})

	afterAll(async () => {
		await server.stop()
	})

	it('should store and retrieve items', async () => {
		const client = server.getDocumentClient()

		await client.send(
			new PutCommand({
				TableName: 'users',
				Item: { id: 1, name: 'John' },
			})
		)

		const result = await client.send(
			new GetCommand({
				TableName: 'users',
				Key: { id: 1 },
			})
		)

		expect(result.Item).toEqual({ id: 1, name: 'John' })
	})
})

License

MIT