platform-es-lib

EventStore library for DynamoDB — TypeScript, with transparent pagination.

Overview

Provides readEvents, writeEvents, and writeRawEvents bound to a DynamoDB table and stream prefix via environment variables.

| Env var | Default | Description | |---|---|---| | ES_TABLE_NAME | envelope-streams | DynamoDB event table | | ES_STREAM_PREFIX | envelope | Prepended to all stream IDs |

A separate lock table (<ES_TABLE_NAME>-lock) is used for optimistic concurrency.

API

readEvents(streamId, scanIndexForward?, limit?)

Reads events for a stream. Paginates through DynamoDB automatically (page size: 100).

import { readEvents } from '@verified/platform-es-lib'

const events = await readEvents('order-123')               // ascending, up to 100
const last10 = await readEvents('order-123', false, 10)   // descending → reversed to chronological

writeEvents(streamId, events, expectedVersion?, forceOverride?)

Writes events with optimistic concurrency via a transactional lock update.

• expectedVersion = 0 → asserts the stream does not yet exist
• expectedVersion > 0 → asserts the current version matches
• forceOverride = true → skips version check

import { writeEvents } from '@verified/platform-es-lib'

await writeEvents('order-123', [{ type: 'OrderPlaced', payload: { ... } }], 0)

writeRawEvents(streamId, events, nextVersion, expectedVersion, forceOverride?)

Low-level write accepting pre-shaped RawEventRecord objects. Used internally by writeEvents.

Types

interface StreamEvent {
  type: string
  id?: string
  aggregateId?: string
  created?: string
  payload?: Record<string, unknown>
  metadata?: EventMetadata
  position?: number   // injected by readEvents (= DynamoDB Version)
}

interface RawEventRecord {
  StreamId: string
  StreamName: string
  EventType: string
  Event: StreamEvent
  Version: number
  Created: string
}

Development

npm ci
npm run build        # tsc → dist/
npm test             # jest (ts-jest)
npm run test:coverage

Publishing

Tag a commit with v* on Bitbucket — the pipeline builds, tests, and publishes to NPM automatically using VERIFIED_NPM_TOKEN.