@photon-grove/evt 0.1.1 → 0.1.2

package/src/dynamodb/repository.ts

@@ -54,11 +54,13 @@ import {
   ttlFromItem,
 } from './item.js'
 import {FEATURES_PK, manifestFromItem, markerItem} from './marker.js'
+import {DYNAMODB_BACKEND, transactItemSize} from './views.js'
 import {
   type CommitTtl,
   commitTransaction,
   controlKey,
   headKey,
+  projectorItems,
   snapshotTransaction,
 } from './requests.js'
 
@@ -194,7 +196,12 @@ export class DynamoRepository implements Repository, StoreInitializer {
     const ttl = this.#ttlFor(entityType)
 
     // Every backend budgets a commit the same way, so an oversized one fails before any request.
-    checkBudget(commitSizes(commit, (type) => (type === entityType ? ttl : undefined)))
+    // The projector operations are sized from the actions this repository sends, which refuses a
+    // group for another backend here too.
+    const sizes = projectorItems(commit).map(transactItemSize)
+    const group = {backend: DYNAMODB_BACKEND, operations: sizes, sizes}
+    const budgeted = {...commit, projections: [group]}
+    checkBudget(commitSizes(budgeted, (type) => (type === entityType ? ttl : undefined)))
 
     const request = requestOptions(options)
     const version = await this.#markerVersion(request)
@@ -542,8 +549,10 @@ export class DynamoRepository implements Repository, StoreInitializer {
       return new RebuildInProgressError()
     }
 
-    // The stream's head update, then its event puts and its snapshot put.
-    const head = 2
+    // The projector operations, then the stream's head update, its event puts and its snapshot
+    // put.
+    const projected = projectorItems(commit).length
+    const head = 2 + projected
     const eventsEnd = head + 1 + commit.events.length
     const eventFailed = codes.slice(head + 1, eventsEnd).includes(CONDITION_FAILED)
     const {entityId} = commit
@@ -562,12 +571,21 @@ export class DynamoRepository implements Repository, StoreInitializer {
       // The head update passed and an event put failed: an event sits above the head. With
       // retention, TTL can delete the head before an expired event, so a create passes its head
       // condition and fails on the leftover item: a conflict until TTL deletes the rest.
+      // The probe already read the remaining items when it found the head item absent below the
+      // head its log derives; read them only if it didn't.
       const verdict = await this.#probe(entityId, retained, request)
-      if (!retained || !(await this.#remainingItemsExpired(entityId, request))) {
+      const expired =
+        retained && (verdict.expired ?? (await this.#remainingItemsExpired(entityId, request)))
+      if (!expired) {
         return verdict.drift ?? drift(entityId, verdict.head, verdict.derived)
       }
     }
 
+    // Only a projector operation's condition failed: its own error, as Go reports it.
+    if (failed < head && !codes.slice(head).includes(CONDITION_FAILED)) {
+      return error
+    }
+
     return new ConflictError(
       entityId,
       'conditional check failed: the sequence or snapshot changed since it was read',
@@ -584,8 +602,11 @@ export class DynamoRepository implements Repository, StoreInitializer {
     const head = (await this.#readHead(entityId, request))?.head ?? null
     const stored = head ?? 0n
     if (stored < derived) {
-      if (retained && head === null && (await this.#remainingItemsExpired(entityId, request))) {
-        return {healthy: false, drift: null, stored, head, derived}
+      if (retained && head === null) {
+        const expired = await this.#remainingItemsExpired(entityId, request)
+        const drifted = expired ? null : drift(entityId, head, derived)
+
+        return {healthy: false, drift: drifted, stored, head, derived, expired}
       }
 
       return {healthy: false, drift: drift(entityId, head, derived), stored, head, derived}
@@ -958,6 +979,8 @@ interface Verdict {
   stored: bigint
   head: bigint | null
   derived: bigint
+  /** What `#remainingItemsExpired` found, when the probe read the remaining items. */
+  expired?: boolean
 }
 
 function drift(entityId: string, head: bigint | null, derived: bigint): StreamHeadDriftError {

package/src/dynamodb/requests.ts

@@ -1,15 +1,17 @@
 // The `TransactWriteItems` actions of a commit and of a snapshot write, built from the storage
 // format alone (storage format, "Writes"). Every commit opens with the two control checks, the
-// feature marker's and the rebuild lock's, then writes the stream: its head update, its event
-// puts, and its snapshot put when it has one.
+// feature marker's and the rebuild lock's, then its projector operations, then writes the stream:
+// its head update, its event puts, and its snapshot put when it has one.
 
 import type {SerializedEvent, SerializedSnapshot} from '../event.js'
 import {int64Argument, safeIntegerArgument} from '../fields.js'
+import {EvtError} from '../errors.js'
 import type {Commit} from '../repository.js'
 import type {TransactItem} from './client.js'
 import {type HeadAction, headUpdate} from './head.js'
 import {HEAD_SORT_KEY, type Item, SNAPSHOT_SORT_KEY, eventItem, snapshotItem} from './item.js'
 import {FEATURES_PK, REBUILD_LOCK_PK} from './marker.js'
+import {DYNAMODB_BACKEND} from './views.js'
 
 /** The marker check of a writer that validated the manifest at version `:v`. */
 export const MARKER_CHECK_CONDITION = 'attribute_not_exists(pk) OR version = :v'
@@ -99,8 +101,9 @@ export interface SnapshotTtl {
 
 /**
  * The actions of a commit with at least one event, in order, by a writer that validated the
- * feature manifest at `markerVersion`. `ttl` is given only for a stream with retention. Exported
- * for the compatibility fixtures: its signature changes when commits span streams.
+ * feature manifest at `markerVersion`. `ttl` is given only for a stream with retention. A projector
+ * group for any backend but DynamoDB is refused. Exported for the compatibility fixtures: its
+ * signature changes when commits span streams.
  */
 export function commitTransaction(
   table: string,
@@ -115,6 +118,7 @@ export function commitTransaction(
   }
 
   const items = [markerCheck(table, markerVersion), rebuildLockCheck(table)]
+  items.push(...projectorItems(commit))
   const head = headUpdate(commit.entityId, first.sequence, last.sequence, ttl?.head)
   items.push(headUpdateItem(table, head))
   for (const event of commit.events) {
@@ -200,6 +204,22 @@ function snapshotGuard(
   }
 }
 
+/** The DynamoDB actions of a commit's projector groups, in order. */
+export function projectorItems(commit: Commit): TransactItem[] {
+  const items: TransactItem[] = []
+  for (const group of commit.projections ?? []) {
+    if (group.backend !== DYNAMODB_BACKEND) {
+      throw new EvtError(
+        'invalidCommit',
+        `invalid commit: a DynamoDB repository can't write a ${group.backend} projector group`,
+      )
+    }
+    items.push(...(group.operations as TransactItem[]))
+  }
+
+  return items
+}
+
 function headUpdateItem(table: string, action: HeadAction): TransactItem {
   const update: NonNullable<TransactItem['Update']> = {
     TableName: table,

package/src/dynamodb/views.ts

@@ -0,0 +1,67 @@
+// The per-entity view projector: one row per entity in a views table, its state as the aggregate's
+// codec encodes it, put in the same transaction as the commit's events (storage format, "Views").
+// Commit-wide projectors, which own their keys, supersede it in Go and Rust, but a TypeScript
+// writer of an entity type that a Go service projects this way must write the row too.
+
+import type {Projection, Projector} from '../aggregate.js'
+import {utf8Length} from '../utf8.js'
+import type {TransactItem} from './client.js'
+import {itemSize, viewItem} from './item.js'
+
+/** The backend name of the projector groups the DynamoDB repository writes. */
+export const DYNAMODB_BACKEND = 'dynamodb'
+
+/**
+ * A projector that puts the entity's view row in `viewsTable` with every commit:
+ * `pk = {entityType}#{entityId}`, `sk = "VIEW"`, and the encoded state as its payload, as Go's
+ * `dynamo.NewViewProjector` writes it. The put is unconditional, so the row is the state after the
+ * entity's latest commit.
+ */
+export function viewProjector<S>(viewsTable: string): Projector<S> {
+  if (viewsTable === '') {
+    throw new RangeError('a view projector needs a views table')
+  }
+
+  return {
+    project({entityType, entityId, encodedState}: Projection<S>) {
+      if (entityId === '') {
+        return null
+      }
+
+      const put: TransactItem = {
+        Put: {TableName: viewsTable, Item: viewItem(entityType, entityId, encodedState)},
+      }
+
+      return {backend: DYNAMODB_BACKEND, operations: [put], sizes: [transactItemSize(put)]}
+    },
+  }
+}
+
+/**
+ * An action's size in the commit budget: a put counts its item, and an update, delete or condition
+ * check counts its key plus its expression strings, name placeholders (the placeholder and the
+ * name) and attribute values.
+ */
+export function transactItemSize(action: TransactItem): number {
+  if (action.Put) {
+    return itemSize(action.Put.Item)
+  }
+
+  const body = action.Update ?? action.Delete ?? action.ConditionCheck
+  if (!body) {
+    return 0
+  }
+
+  let size = itemSize(body.Key) + utf8Length(body.ConditionExpression ?? '')
+  if (action.Update) {
+    size += utf8Length(action.Update.UpdateExpression)
+  }
+  for (const [placeholder, name] of Object.entries(body.ExpressionAttributeNames ?? {})) {
+    size += utf8Length(placeholder) + utf8Length(name)
+  }
+  for (const [placeholder, value] of Object.entries(body.ExpressionAttributeValues ?? {})) {
+    size += utf8Length(placeholder) + itemSize({'': value})
+  }
+
+  return size
+}

package/src/errors.ts

@@ -30,6 +30,8 @@
  * - `transient`: the backend throttled the write. Retryable. Nothing was written.
  * - `rebuildInProgress`: a projection rebuild holds the store, so commits wait. Retryable.
  * - `historyDependentProjection`: compaction was refused for a history-dependent entity type.
+ * - `projectorOnlyCommit`: a commit carries projector operations but no events. Nothing was
+ *   written.
  * - `replay`: a stored event failed to upcast or decode while an aggregate loaded.
  * - `snapshot`: a stored snapshot failed to decode while an aggregate loaded.
  */
@@ -51,6 +53,7 @@ export type EvtErrorCode =
   | 'transient'
   | 'rebuildInProgress'
   | 'historyDependentProjection'
+  | 'projectorOnlyCommit'
   | 'replay'
   | 'snapshot'
 
@@ -301,6 +304,26 @@ export class HistoryDependentProjectionError extends EvtError {
   }
 }
 
+/**
+ * A commit carried projector operations but no events. Views are projections of committed events,
+ * so operations with no event behind them are refused on every backend. Nothing was written.
+ */
+export class ProjectorOnlyCommitError extends EvtError {
+  override readonly name = 'ProjectorOnlyCommitError'
+  override readonly code = 'projectorOnlyCommit'
+  /** How many projector operations the commit carried. */
+  readonly operations: number
+
+  constructor(operations: number) {
+    super(
+      'projectorOnlyCommit',
+      `a commit carries ${operations} projector operations but no events; views need a ` +
+        'backing event in the same commit',
+    )
+    this.operations = operations
+  }
+}
+
 /** A load failed closed on a stored event: an upcaster threw, or the payload didn't decode. */
 export class ReplayError extends EvtError {
   override readonly name = 'ReplayError'

package/src/index.ts

@@ -9,6 +9,8 @@ export {
   type EventDefinition,
   type EventDefinitions,
   type EventOf,
+  type Projection,
+  type Projector,
   type Rejection,
   type Upcaster,
   defineAggregate,
@@ -32,6 +34,7 @@ export {
   type EvtErrorCode,
   FeatureManifestChangedError,
   HistoryDependentProjectionError,
+  ProjectorOnlyCommitError,
   RebuildInProgressError,
   ReplayError,
   ReservedEntityIdError,
@@ -77,6 +80,7 @@ export type {
   CallOptions,
   Commit,
   NewSnapshot,
+  ProjectorGroup,
   Repository,
   StoreInitializer,
 } from './repository.js'

package/src/postgres/client.ts

@@ -0,0 +1,37 @@
+// The PostgreSQL client a PgRepository takes: a structural interface that `pg`'s Pool, Neon's
+// serverless Pool and PGlite satisfy without an adapter, so this package imports no driver.
+
+/** The result of one statement: its rows, as the driver returns them. */
+export interface PgResult {
+  readonly rows: readonly unknown[]
+}
+
+/** Something that runs one statement: `$1`, `$2` and so on in `text` take `values` in order. */
+export interface PgQueryable {
+  query(text: string, values?: unknown[]): Promise<PgResult>
+}
+
+/**
+ * A connection held for one transaction, as a pool lends it. `release` returns it to the pool, and
+ * gets the error when the connection may be unusable, so the pool can discard it.
+ */
+export interface PgConnection extends PgQueryable {
+  release(error?: Error): void
+}
+
+/**
+ * The client a {@link PgRepository} runs on.
+ *
+ * - A pool, such as `pg`'s `Pool` or Neon's serverless `Pool`, has `connect`, which lends one
+ *   connection for each transaction. Single statements outside a transaction go to `query`.
+ * - A single connection without `connect`, such as PGlite, runs everything itself, so every
+ *   repository on it runs one operation at a time on it. Nothing else may use the connection
+ *   meanwhile: a statement sent inside a repository's transaction would join it.
+ *
+ * Every value the repository sends is a string or null, with casts in the SQL, and every column it
+ * reads is text, so no driver's type parsing touches a stored value. A `pg` `Client` has a
+ * `connect` that opens the client rather than lending a connection, so pass a `Pool` instead.
+ */
+export interface PgClient extends PgQueryable {
+  connect?(): Promise<PgConnection>
+}

package/src/postgres/index.ts

@@ -0,0 +1,23 @@
+// @photon-grove/evt/postgres: the PostgreSQL backend. It imports no driver: the repository takes
+// `pg`'s Pool, or anything shaped like it, as a PgClient.
+
+export {type PgClient, type PgConnection, type PgQueryable, type PgResult} from './client.js'
+export {POSTGRES_BACKEND, PgRepository, type PgRepositoryOptions} from './repository.js'
+
+export {
+  DEFAULT_EVENTS_TABLE,
+  DEFAULT_SNAPSHOTS_TABLE,
+  MAX_EVENTS_TABLE_NAME_BYTES,
+  MAX_SNAPSHOTS_TABLE_NAME_BYTES,
+  type PgTables,
+  RESERVED_INFIX,
+  SCHEMA_LOCK,
+  entityTypeIndex,
+  featuresTable,
+  outcomesTable,
+  pgTables,
+  rebuildGenerationTable,
+  rebuildLockTable,
+  schemaDdl,
+  streamHeadsTable,
+} from './schema.js'