@photon-grove/evt 0.1.0 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@photon-grove/evt",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Event sourcing for TypeScript, wire-compatible with the Go and Rust evt implementations.",
   "keywords": [
     "event-sourcing",
@@ -38,20 +38,33 @@
       "types": "./dist/memory/index.d.ts",
       "default": "./dist/memory/index.js"
     },
+    "./postgres": {
+      "types": "./dist/postgres/index.d.ts",
+      "default": "./dist/postgres/index.js"
+    },
     "./testing": {
       "types": "./dist/testing/index.d.ts",
       "default": "./dist/testing/index.js"
     },
     "./package.json": "./package.json"
   },
+  "peerDependencies": {
+    "@aws-sdk/client-dynamodb": "^3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@aws-sdk/client-dynamodb": {
+      "optional": true
+    }
+  },
   "scripts": {
     "build": "tsc",
     "check": "tsc --noEmit && tsc -p tsconfig.test.json && oxlint --deny-warnings && node scripts/check-imports.ts",
     "test": "vitest run"
   },
   "devDependencies": {
-    "@types/node": "^25.9.9",
-    "oxlint": "1.88.0",
+    "@aws-sdk/client-dynamodb": "3.1161.0",
+    "@types/node": "^26.6.6",
+    "oxlint": "1.90.0",
     "typescript": "^7.0.2",
     "vitest": "5.0.5"
   }

package/src/aggregate.ts

@@ -5,6 +5,7 @@ import type {Codec} from './codec.js'
 import {EvtError, ReplayError, messageOf} from './errors.js'
 import type {SerializedEvent} from './event.js'
 import {type JsonValue, parseJson, stringifyJson} from './json.js'
+import type {ProjectorGroup} from './repository.js'
 import {utf8Decode, utf8Encode} from './utf8.js'
 
 /**
@@ -103,6 +104,33 @@ export interface AggregateDefinition<S, C, D extends EventDefinitions> {
    * snapshots.
    */
   readonly snapshotInterval?: number | undefined
+  /**
+   * The projectors whose operations every commit of this type writes in the same transaction as
+   * its events, in this order, such as the DynamoDB backend's `viewProjector`.
+   */
+  readonly projectors?: readonly Projector<S>[] | undefined
+}
+
+/** What a projector sees of a commit: its entity, the state after its events, and the events. */
+export interface Projection<S> {
+  readonly entityType: string
+  readonly entityId: string
+  /** The state after the commit's events. */
+  readonly state: S
+  /** The state as the aggregate's state codec encodes it, as a snapshot stores it. */
+  readonly encodedState: Uint8Array
+  /** Copies of the commit's events, as they are stored. */
+  readonly events: readonly Readonly<SerializedEvent>[]
+}
+
+/**
+ * Builds the operations a commit writes beside its events, in the same transaction, such as a
+ * view of the entity's state. Its group names the backend that writes it. `project` returns null
+ * when the commit needs none. It runs only for a commit with events, again on every retry, and it
+ * must not fail or change the state.
+ */
+export interface Projector<S> {
+  project(projection: Projection<S>): ProjectorGroup | null
 }
 
 /** A checked aggregate type. */

package/src/dynamodb/client.ts

@@ -0,0 +1,102 @@
+// The DynamoDB calls the repository makes, as a structural interface. The AWS SDK's aggregated
+// `DynamoDB` client (`@aws-sdk/client-dynamodb`) satisfies it, so this package imports nothing
+// from the SDK. Requests and responses use the low-level `AttributeValue` maps, never the document
+// client's marshalling, because the storage format pins every attribute's type.
+
+import type {Item} from './item.js'
+
+/** The options the repository passes with every call. */
+export interface RequestOptions {
+  abortSignal?: AbortSignal
+}
+
+/** One action of a `TransactWriteItems` call. */
+export interface TransactItem {
+  ConditionCheck?: ConditionCheckAction
+  Put?: PutAction
+  Update?: UpdateAction
+  Delete?: DeleteAction
+}
+
+/** The expression parts an action or a query may carry. */
+export interface Expressions {
+  ConditionExpression?: string
+  ExpressionAttributeNames?: Record<string, string>
+  ExpressionAttributeValues?: Item
+}
+
+export interface ConditionCheckAction extends Expressions {
+  TableName: string
+  Key: Item
+  ConditionExpression: string
+}
+
+export interface PutAction extends Expressions {
+  TableName: string
+  Item: Item
+}
+
+export interface UpdateAction extends Expressions {
+  TableName: string
+  Key: Item
+  UpdateExpression: string
+}
+
+export interface DeleteAction extends Expressions {
+  TableName: string
+  Key: Item
+}
+
+export interface GetItemInput {
+  TableName: string
+  Key: Item
+  ConsistentRead?: boolean
+  ProjectionExpression?: string
+  ExpressionAttributeNames?: Record<string, string>
+}
+
+export interface PutItemInput extends Expressions {
+  TableName: string
+  Item: Item
+}
+
+export interface QueryInput {
+  TableName: string
+  KeyConditionExpression: string
+  ExpressionAttributeNames?: Record<string, string>
+  ExpressionAttributeValues: Item
+  ConsistentRead?: boolean
+  ProjectionExpression?: string
+  ScanIndexForward?: boolean
+  Limit?: number
+  ExclusiveStartKey?: Item
+}
+
+export interface ScanInput {
+  TableName: string
+  ConsistentRead?: boolean
+  ProjectionExpression?: string
+  Limit?: number
+  ExclusiveStartKey?: Item
+}
+
+/** A page of a query or a scan. Items come back as the SDK decodes them. */
+export interface Page {
+  Items?: Record<string, unknown>[] | undefined
+  LastEvaluatedKey?: Record<string, unknown> | undefined
+}
+
+/** The calls {@link DynamoRepository} makes: the SDK's `DynamoDB` client has them all. */
+export interface DynamoClient {
+  getItem(
+    input: GetItemInput,
+    options?: RequestOptions,
+  ): Promise<{Item?: Record<string, unknown> | undefined}>
+  putItem(input: PutItemInput, options?: RequestOptions): Promise<unknown>
+  query(input: QueryInput, options?: RequestOptions): Promise<Page>
+  scan(input: ScanInput, options?: RequestOptions): Promise<Page>
+  transactWriteItems(
+    input: {TransactItems: TransactItem[]},
+    options?: RequestOptions,
+  ): Promise<unknown>
+}

package/src/dynamodb/index.ts

@@ -1,5 +1,5 @@
-// @photon-grove/evt/dynamodb: the DynamoDB backend. So far it holds the item codec, which imports
-// nothing from the AWS SDK.
+// @photon-grove/evt/dynamodb: the DynamoDB backend. It imports nothing from the AWS SDK: the
+// repository takes the SDK's `DynamoDB` client, or anything shaped like it, as a DynamoClient.
 
 export {
   type AttributeValue,
@@ -17,5 +17,30 @@ export {
   snapshotFromItem,
   snapshotItem,
   sortKey,
+  ttlFromItem,
   viewItem,
 } from './item.js'
+export {
+  type ConditionCheckAction,
+  type DeleteAction,
+  type DynamoClient,
+  type Expressions,
+  type GetItemInput,
+  type Page,
+  type PutAction,
+  type PutItemInput,
+  type QueryInput,
+  type RequestOptions,
+  type ScanInput,
+  type TransactItem,
+  type UpdateAction,
+} from './client.js'
+export {FEATURES_PK, REBUILD_LOCK_PK, manifestFromItem, markerItem} from './marker.js'
+export {DynamoRepository, type DynamoRepositoryOptions} from './repository.js'
+export {DYNAMODB_BACKEND, transactItemSize, viewProjector} from './views.js'
+export {
+  type CommitTtl,
+  type SnapshotTtl,
+  commitTransaction,
+  snapshotTransaction,
+} from './requests.js'

package/src/dynamodb/item.ts

@@ -151,12 +151,14 @@ export function snapshotFromItem(item: Item): SerializedSnapshot {
 
 /** Decodes a head item into its head and its `ttl`, if it has one. */
 export function headFromItem(item: Item): {head: bigint; ttl: number | undefined} {
+  return {head: requiredNumber(item, 'head'), ttl: ttlFromItem(item)}
+}
+
+/** An item's `ttl` in Unix seconds, or undefined when it has none. */
+export function ttlFromItem(item: Item): number | undefined {
   const ttl = optionalNumber(item, 'ttl')
 
-  return {
-    head: requiredNumber(item, 'head'),
-    ttl: ttl === undefined ? undefined : safeInteger(ttl, 'ttl'),
-  }
+  return ttl === undefined ? undefined : safeInteger(ttl, 'ttl')
 }
 
 /** Whether an item is a stream's inline snapshot (`sk = 0`). */

package/src/dynamodb/marker.ts

@@ -0,0 +1,64 @@
+// The DynamoDB item of the feature-marker row. The control rows live in the reserved SYSTEM#
+// namespace at sort key 0.
+//
+// | Attribute          | Type | Feature-marker item (`pk = SYSTEM#FEATURES`, `sk = 0`)       |
+// | ------------------ | ---- | ------------------------------------------------------------ |
+// | `version`          | N    | bumped on every change to the manifest                       |
+// | `features`         | S    | JSON object, feature name → stored-format version, sorted    |
+// | `historyDependent` | S    | JSON array of entity types, sorted. Absent when empty        |
+// | `retention`        | S    | JSON array of entity types, sorted. Absent when empty        |
+
+import {checkInt64, invalid} from '../fields.js'
+import {type FeatureManifest, decodeManifest, encodeManifest} from '../features.js'
+import {type Item, SNAPSHOT_SORT_KEY} from './item.js'
+
+/** The partition key of the feature-marker row. */
+export const FEATURES_PK = 'SYSTEM#FEATURES'
+
+/** The partition key of the rebuild-lock row, which every commit checks is absent. */
+export const REBUILD_LOCK_PK = 'SYSTEM#REBUILD'
+
+/** Encodes a feature manifest as its marker item. Empty entity-type sets are left out. */
+export function markerItem(manifest: FeatureManifest): Item {
+  const texts = encodeManifest(manifest)
+  const item: Item = {
+    pk: {S: FEATURES_PK},
+    sk: {N: SNAPSHOT_SORT_KEY.toString()},
+    version: {N: manifest.version.toString()},
+    features: {S: texts.features},
+  }
+  if (manifest.historyDependent.length > 0) {
+    item['historyDependent'] = {S: texts.historyDependent}
+  }
+  if (manifest.retention.length > 0) {
+    item['retention'] = {S: texts.retention}
+  }
+
+  return item
+}
+
+/** Decodes a marker item. An absent text attribute is an empty map or set. */
+export function manifestFromItem(item: Item): FeatureManifest {
+  const version = item['version']
+  if (version === undefined || !('N' in version) || !/^\d+$/.test(version.N)) {
+    throw invalid('the feature marker has no version')
+  }
+
+  return decodeManifest(checkInt64(BigInt(version.N), 'the feature marker version'), {
+    features: text(item, 'features'),
+    historyDependent: text(item, 'historyDependent'),
+    retention: text(item, 'retention'),
+  })
+}
+
+function text(item: Item, name: string): string {
+  const value = item[name]
+  if (value === undefined) {
+    return ''
+  }
+  if (!('S' in value)) {
+    throw invalid(`the feature marker's ${name} attribute is not a string`)
+  }
+
+  return value.S
+}