@othree.io/chisel-aws

AWS infrastructure bindings for Chisel — DynamoDB event sourcing and SNS event publishing.

Install

npm install @othree.io/chisel-aws

Peer dependencies

npm install @aws-sdk/client-dynamodb @aws-sdk/client-sns @aws-sdk/util-dynamodb @othree.io/chisel @othree.io/optional

API

Event Source (DynamoDB)

Persist and retrieve events from a DynamoDB table.

import { awsEventSource, ChiselDynamoConfiguration } from '@othree.io/chisel-aws'
import { DynamoDBClient } from '@aws-sdk/client-dynamodb'

const configuration: ChiselDynamoConfiguration = {
    TableName: 'MyEvents',
    SnapshotFrequency: 100
}

const dynamoDb = new DynamoDBClient({})

// Persist an event
const persistEvent = awsEventSource.persist({ dynamoDb, configuration })
const maybeEvent = await persistEvent(event)

// Get events for a context
const getEvents = awsEventSource.getEvents({ dynamoDb, configuration })
const maybeEvents = await getEvents('context-id-123')

Actor (SNS)

Publish domain events to an SNS topic after command processing.

Single topic

import { awsActor, ChiselSnsConfiguration } from '@othree.io/chisel-aws'
import { SNSClient } from '@aws-sdk/client-sns'

const configuration: ChiselSnsConfiguration<MyAggregateRoot> = {
    TopicArn: 'arn:aws:sns:us-east-1:123456789:my-topic',
    BoundedContext: 'Orders',
    IsFifo: false,
    IncludeState: true
}

const snsClient = new SNSClient({})

const publish = awsActor.publishEvent({ snsClient, configuration })

Sharded topics

Distribute events across multiple SNS topics using consistent hashing on the context ID.

import { awsActor, ChiselShardedSnsConfiguration } from '@othree.io/chisel-aws'

const configuration: ChiselShardedSnsConfiguration<MyAggregateRoot> = {
    TopicsArn: [
        'arn:aws:sns:us-east-1:123456789:my-topic-0',
        'arn:aws:sns:us-east-1:123456789:my-topic-1',
        'arn:aws:sns:us-east-1:123456789:my-topic-2'
    ],
    BoundedContext: 'Orders',
    IsFifo: false,
    IncludeState: true
}

const publish = awsActor.publishShardedEvent({
    hashCode: awsActor.hashCode,
    snsClient,
    configuration
})

FIFO topics

For FIFO topics, set IsFifo: true. By default, contextId is used as the message group ID and eventId as the deduplication ID. Override either with custom functions:

const configuration: ChiselSnsConfiguration<MyAggregateRoot> = {
    TopicArn: 'arn:aws:sns:us-east-1:123456789:my-topic.fifo',
    BoundedContext: 'Orders',
    IsFifo: true,
    IncludeState: true,
    GetMessageGroupId: (event, state) => state.customerId,
    GetMessageDeduplicationId: (event, state) => `${event.contextId}-${event.eventId}`
}

Lambda Command Handler

Adapter for invoking a Chisel command handler from an AWS Lambda function.

import { handlers } from '@othree.io/chisel-aws'

const handle = /* chisel actor.Handle<MyAggregateRoot> */

export const handler = handlers.handleLambdaCommand({ handle })

The Lambda receives events with the shape { command: Command } and returns the unwrapped CommandResult.

SNS Message Format

Published SNS messages have the following structure:

Body:

{
    "event": { "contextId": "...", "eventId": "...", "type": "...", "body": {}, "eventDate": 0 },
    "state": {}
}

Message attributes:

• bc — bounded context name
• eventType — the event type
• Any keys from the event's metadata field

License

ISC