EventCatalog

Describes what an aggregate writes and accepts, for consumers outside the process, and guards stored events against schema changes that would break them.

events and commands give the JSON Schema of every event, in every version declared with EventVersions, and of every command payload.
document lists them for several aggregates in an AsyncAPI 3 document.
captureSamples takes a few stored payloads of each event and version, saveSamples keeps them in a JSON file, and checkCompatibility fails when one of them no longer decodes with the current aggregate.

JSON Schema describes the JSON form of a schema, as Schema.toCodecJson encodes it. Personal fields, see PersonalData, are described in plaintext: in the store they are encrypted.

Classes

IncompatibleSamples

Defined in: src/EventCatalog.ts:230

Extends

object & YieldableError<this>

Constructors

Constructor

new IncompatibleSamples(…args): IncompatibleSamples

Defined in: node_modules/.pnpm/effect@4.0.6/node_modules/effect/dist/Schema.d.ts:10979

Parameters

args

…[props: object, options?: MakeOptions]

Returns

IncompatibleSamples

Inherited from

Schema.TaggedError<IncompatibleSamples>()("IncompatibleSamples", { aggregateName: Schema.String, failures: Schema.Array(Schema.Struct({ type: Schema.String, schemaVersion: Schema.Int, message: Schema.String })) }).constructor

Properties

aggregateName

readonly aggregateName: string = Schema.String

Defined in: src/EventCatalog.ts:231

Inherited from

failures

readonly failures: readonly object[]

Defined in: src/EventCatalog.ts:232

Inherited from

Accessors

message

Get Signature

get message(): string

Defined in: src/EventCatalog.ts:238

Returns

string

Overrides

Interfaces

AsyncApiDocument

Defined in: src/EventCatalog.ts:106

An AsyncAPI 3.0 document, with JSON Schema draft-07 payloads as AsyncAPI expects.

Properties

asyncapi

readonly asyncapi: "3.0.0"

Defined in: src/EventCatalog.ts:107

channels

readonly channels: Record<string, unknown>

Defined in: src/EventCatalog.ts:109

components

readonly components: object

Defined in: src/EventCatalog.ts:111

messages

readonly messages: Record<string, unknown>

schemas

readonly schemas: Record<string, JsonSchema.JsonSchema>

info

readonly info: object

Defined in: src/EventCatalog.ts:108

description?

readonly optional description?: string

title

readonly title: string

version

readonly version: string

operations

readonly operations: Record<string, unknown>

Defined in: src/EventCatalog.ts:110

CommandEntry

Defined in: src/EventCatalog.ts:47

Properties

aggregate

readonly aggregate: string

Defined in: src/EventCatalog.ts:48

name

readonly name: string

Defined in: src/EventCatalog.ts:49

payload

readonly payload: JsonSchema

Defined in: src/EventCatalog.ts:51

A JSON Schema draft 2020-12 of the payload.

DocumentOptions

Defined in: src/EventCatalog.ts:99

Properties

description?

readonly optional description?: string

Defined in: src/EventCatalog.ts:102

title

readonly title: string

Defined in: src/EventCatalog.ts:100

version

readonly version: string

Defined in: src/EventCatalog.ts:101

EventEntry

Defined in: src/EventCatalog.ts:36

Properties

aggregate

readonly aggregate: string

Defined in: src/EventCatalog.ts:37

personalFields

readonly personalFields: readonly string[]

Defined in: src/EventCatalog.ts:44

Paths of the personal fields in the current version, encrypted in the store.

schemaVersion

readonly schemaVersion: number

Defined in: src/EventCatalog.ts:40

The version new events are written in, the last of versions.

type

readonly type: string

Defined in: src/EventCatalog.ts:38

versions

readonly versions: readonly EventVersion[]

Defined in: src/EventCatalog.ts:42

Oldest first. Events written before versions were declared are version 1.

EventVersion

Defined in: src/EventCatalog.ts:30

Properties

schema

readonly schema: JsonSchema

Defined in: src/EventCatalog.ts:33

A JSON Schema draft 2020-12 of the payload in this version.

schemaVersion

readonly schemaVersion: number

Defined in: src/EventCatalog.ts:31

Type Aliases

Sample

Sample = typeof Sample.Type

Defined in: src/EventCatalog.ts:220

A payload as the store keeps it, to check that the current aggregate still reads it.

Variables

Sample

const Sample: Struct<{ aggregateName: String; payload: Codec<Json, Json, never, never>; schemaVersion: Int; type: String; }>

Defined in: src/EventCatalog.ts:220

A payload as the store keeps it, to check that the current aggregate still reads it.

Functions

captureSamples()

captureSamples(aggregates, options?): Effect<readonly object[], EventStoreError, EventStore>

Defined in: src/EventCatalog.ts:281

Reads the store and keeps the last perVersion payloads, one by default, of every event type and schema version of the given aggregates.

Personal fields are replaced by the value they read as once their subject is forgotten, so samples hold no personal data and can be committed, and checking them needs no keys. The rest of the payload is kept as it was stored.

Parameters

aggregates

readonly Any[]

options?

perVersion?

number

Returns

Effect<readonly object[], EventStoreError, EventStore>

checkCompatibility()

checkCompatibility(aggregate, samples): Effect<number, IncompatibleSamples>

Defined in: src/EventCatalog.ts:340

Decodes every sample of the aggregate with its current schemas and upcasts, as a store read would, and fails with IncompatibleSamples listing the ones that no longer decode. Returns how many samples were checked.

Personal fields in samples are expected in plaintext, as captureSamples leaves them, so no keys are needed.

Parameters

aggregate

Any

samples

readonly object[]

Returns

Effect<number, IncompatibleSamples>

commands()

commands(aggregate): readonly CommandEntry[]

Defined in: src/EventCatalog.ts:88

The JSON Schema of the payload of every command of an aggregate.

Parameters

aggregate

Any

Returns

readonly CommandEntry[]

document()

document(aggregates, options): AsyncApiDocument

Defined in: src/EventCatalog.ts:138

Lists the events and commands of some aggregates in an AsyncAPI 3.0 document. Each aggregate has a channel of events it sends and a channel of commands it receives. Older versions of an event are under the message’s x-versions, and its personal fields under x-personal-fields.

Parameters

aggregates

readonly Any[]

options

DocumentOptions

Returns

AsyncApiDocument

events()

events(aggregate): readonly EventEntry[]

Defined in: src/EventCatalog.ts:75

The JSON Schema of every event of an aggregate, in every version it declares.

Parameters

aggregate

Any

Returns

readonly EventEntry[]

readSamples()

readSamples(path): Effect<readonly object[], PlatformError | SchemaError, FileSystem>

Defined in: src/EventCatalog.ts:311

Reads samples written by saveSamples.

Parameters

path

string

Returns

Effect<readonly object[], PlatformError | SchemaError, FileSystem>

saveSamples()

saveSamples(path, samples): Effect<object[], PlatformError | SchemaError, FileSystem>

Defined in: src/EventCatalog.ts:322

Adds samples to a JSON file, creating it if needed. Samples of an event type and version already in the file are left as they are, so the file keeps the shapes the store held over time, also after those events are gone from it.

Parameters

path

string

samples

readonly object[]

Returns

Effect<object[], PlatformError | SchemaError, FileSystem>