# 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](https://effect-cqrs.dambox.ch/reference/api/eventcatalog/#events) and [commands](https://effect-cqrs.dambox.ch/reference/api/eventcatalog/#commands) give the JSON Schema of every event, in every version declared with `EventVersions`, and of every command payload. * [document](https://effect-cqrs.dambox.ch/reference/api/eventcatalog/#document) lists them for several aggregates in an AsyncAPI 3 document. * [captureSamples](https://effect-cqrs.dambox.ch/reference/api/eventcatalog/#capturesamples) takes a few stored payloads of each event and version, [saveSamples](https://effect-cqrs.dambox.ch/reference/api/eventcatalog/#savesamples) keeps them in a JSON file, and [checkCompatibility](https://effect-cqrs.dambox.ch/reference/api/eventcatalog/#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](https://github.com/davidnussio/effect-cqrs/blob/9d66af7141782f3f89655e6868abe3f141c97632/src/EventCatalog.ts#L230) #### Extends * `object` & `YieldableError`<`this`> #### Constructors ##### Constructor > **new IncompatibleSamples**(…`args`): [`IncompatibleSamples`](https://effect-cqrs.dambox.ch/reference/api/eventcatalog/#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`](https://effect-cqrs.dambox.ch/reference/api/eventcatalog/#incompatiblesamples) ###### Inherited from `Schema.TaggedError()("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](https://github.com/davidnussio/effect-cqrs/blob/9d66af7141782f3f89655e6868abe3f141c97632/src/EventCatalog.ts#L231) ###### Inherited from `Schema.TaggedError()("IncompatibleSamples", { aggregateName: Schema.String, failures: Schema.Array(Schema.Struct({ type: Schema.String, schemaVersion: Schema.Int, message: Schema.String })) }).aggregateName` ##### failures > `readonly` **failures**: readonly `object`\[] Defined in: [src/EventCatalog.ts:232](https://github.com/davidnussio/effect-cqrs/blob/9d66af7141782f3f89655e6868abe3f141c97632/src/EventCatalog.ts#L232) ###### Inherited from `Schema.TaggedError()("IncompatibleSamples", { aggregateName: Schema.String, failures: Schema.Array(Schema.Struct({ type: Schema.String, schemaVersion: Schema.Int, message: Schema.String })) }).failures` #### Accessors ##### message ###### Get Signature > **get** **message**(): `string` Defined in: [src/EventCatalog.ts:238](https://github.com/davidnussio/effect-cqrs/blob/9d66af7141782f3f89655e6868abe3f141c97632/src/EventCatalog.ts#L238) ###### Returns `string` ###### Overrides `Schema.TaggedError()("IncompatibleSamples", { aggregateName: Schema.String, failures: Schema.Array(Schema.Struct({ type: Schema.String, schemaVersion: Schema.Int, message: Schema.String })) }).message` ## Interfaces ### AsyncApiDocument Defined in: [src/EventCatalog.ts:106](https://github.com/davidnussio/effect-cqrs/blob/9d66af7141782f3f89655e6868abe3f141c97632/src/EventCatalog.ts#L106) 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](https://github.com/davidnussio/effect-cqrs/blob/9d66af7141782f3f89655e6868abe3f141c97632/src/EventCatalog.ts#L107) ##### channels > `readonly` **channels**: `Record`<`string`, `unknown`> Defined in: [src/EventCatalog.ts:109](https://github.com/davidnussio/effect-cqrs/blob/9d66af7141782f3f89655e6868abe3f141c97632/src/EventCatalog.ts#L109) ##### components > `readonly` **components**: `object` Defined in: [src/EventCatalog.ts:111](https://github.com/davidnussio/effect-cqrs/blob/9d66af7141782f3f89655e6868abe3f141c97632/src/EventCatalog.ts#L111) ###### messages > `readonly` **messages**: `Record`<`string`, `unknown`> ###### schemas > `readonly` **schemas**: `Record`<`string`, `JsonSchema.JsonSchema`> ##### info > `readonly` **info**: `object` Defined in: [src/EventCatalog.ts:108](https://github.com/davidnussio/effect-cqrs/blob/9d66af7141782f3f89655e6868abe3f141c97632/src/EventCatalog.ts#L108) ###### 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](https://github.com/davidnussio/effect-cqrs/blob/9d66af7141782f3f89655e6868abe3f141c97632/src/EventCatalog.ts#L110) *** ### CommandEntry Defined in: [src/EventCatalog.ts:47](https://github.com/davidnussio/effect-cqrs/blob/9d66af7141782f3f89655e6868abe3f141c97632/src/EventCatalog.ts#L47) #### Properties ##### aggregate > `readonly` **aggregate**: `string` Defined in: [src/EventCatalog.ts:48](https://github.com/davidnussio/effect-cqrs/blob/9d66af7141782f3f89655e6868abe3f141c97632/src/EventCatalog.ts#L48) ##### name > `readonly` **name**: `string` Defined in: [src/EventCatalog.ts:49](https://github.com/davidnussio/effect-cqrs/blob/9d66af7141782f3f89655e6868abe3f141c97632/src/EventCatalog.ts#L49) ##### payload > `readonly` **payload**: `JsonSchema` Defined in: [src/EventCatalog.ts:51](https://github.com/davidnussio/effect-cqrs/blob/9d66af7141782f3f89655e6868abe3f141c97632/src/EventCatalog.ts#L51) A JSON Schema draft 2020-12 of the payload. *** ### DocumentOptions Defined in: [src/EventCatalog.ts:99](https://github.com/davidnussio/effect-cqrs/blob/9d66af7141782f3f89655e6868abe3f141c97632/src/EventCatalog.ts#L99) #### Properties ##### description? > `readonly` `optional` **description?**: `string` Defined in: [src/EventCatalog.ts:102](https://github.com/davidnussio/effect-cqrs/blob/9d66af7141782f3f89655e6868abe3f141c97632/src/EventCatalog.ts#L102) ##### title > `readonly` **title**: `string` Defined in: [src/EventCatalog.ts:100](https://github.com/davidnussio/effect-cqrs/blob/9d66af7141782f3f89655e6868abe3f141c97632/src/EventCatalog.ts#L100) ##### version > `readonly` **version**: `string` Defined in: [src/EventCatalog.ts:101](https://github.com/davidnussio/effect-cqrs/blob/9d66af7141782f3f89655e6868abe3f141c97632/src/EventCatalog.ts#L101) *** ### EventEntry Defined in: [src/EventCatalog.ts:36](https://github.com/davidnussio/effect-cqrs/blob/9d66af7141782f3f89655e6868abe3f141c97632/src/EventCatalog.ts#L36) #### Properties ##### aggregate > `readonly` **aggregate**: `string` Defined in: [src/EventCatalog.ts:37](https://github.com/davidnussio/effect-cqrs/blob/9d66af7141782f3f89655e6868abe3f141c97632/src/EventCatalog.ts#L37) ##### personalFields > `readonly` **personalFields**: readonly `string`\[] Defined in: [src/EventCatalog.ts:44](https://github.com/davidnussio/effect-cqrs/blob/9d66af7141782f3f89655e6868abe3f141c97632/src/EventCatalog.ts#L44) Paths of the personal fields in the current version, encrypted in the store. ##### schemaVersion > `readonly` **schemaVersion**: `number` Defined in: [src/EventCatalog.ts:40](https://github.com/davidnussio/effect-cqrs/blob/9d66af7141782f3f89655e6868abe3f141c97632/src/EventCatalog.ts#L40) The version new events are written in, the last of `versions`. ##### type > `readonly` **type**: `string` Defined in: [src/EventCatalog.ts:38](https://github.com/davidnussio/effect-cqrs/blob/9d66af7141782f3f89655e6868abe3f141c97632/src/EventCatalog.ts#L38) ##### versions > `readonly` **versions**: readonly [`EventVersion`](https://effect-cqrs.dambox.ch/reference/api/eventcatalog/#eventversion)\[] Defined in: [src/EventCatalog.ts:42](https://github.com/davidnussio/effect-cqrs/blob/9d66af7141782f3f89655e6868abe3f141c97632/src/EventCatalog.ts#L42) Oldest first. Events written before versions were declared are version 1. *** ### EventVersion Defined in: [src/EventCatalog.ts:30](https://github.com/davidnussio/effect-cqrs/blob/9d66af7141782f3f89655e6868abe3f141c97632/src/EventCatalog.ts#L30) #### Properties ##### schema > `readonly` **schema**: `JsonSchema` Defined in: [src/EventCatalog.ts:33](https://github.com/davidnussio/effect-cqrs/blob/9d66af7141782f3f89655e6868abe3f141c97632/src/EventCatalog.ts#L33) A JSON Schema draft 2020-12 of the payload in this version. ##### schemaVersion > `readonly` **schemaVersion**: `number` Defined in: [src/EventCatalog.ts:31](https://github.com/davidnussio/effect-cqrs/blob/9d66af7141782f3f89655e6868abe3f141c97632/src/EventCatalog.ts#L31) ## Type Aliases ### Sample > **Sample** = *typeof* `Sample.Type` Defined in: [src/EventCatalog.ts:220](https://github.com/davidnussio/effect-cqrs/blob/9d66af7141782f3f89655e6868abe3f141c97632/src/EventCatalog.ts#L220) 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](https://github.com/davidnussio/effect-cqrs/blob/9d66af7141782f3f89655e6868abe3f141c97632/src/EventCatalog.ts#L220) A payload as the store keeps it, to check that the current aggregate still reads it. ## Functions ### captureSamples() > **captureSamples**(`aggregates`, `options?`): `Effect`\ Defined in: [src/EventCatalog.ts:281](https://github.com/davidnussio/effect-cqrs/blob/9d66af7141782f3f89655e6868abe3f141c97632/src/EventCatalog.ts#L281) 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`](https://effect-cqrs.dambox.ch/reference/api/aggregate/#any)\[] ##### options? ###### perVersion? `number` #### Returns `Effect`\ *** ### checkCompatibility() > **checkCompatibility**(`aggregate`, `samples`): `Effect`<`number`, [`IncompatibleSamples`](https://effect-cqrs.dambox.ch/reference/api/eventcatalog/#incompatiblesamples)> Defined in: [src/EventCatalog.ts:340](https://github.com/davidnussio/effect-cqrs/blob/9d66af7141782f3f89655e6868abe3f141c97632/src/EventCatalog.ts#L340) Decodes every sample of the aggregate with its current schemas and upcasts, as a store read would, and fails with [IncompatibleSamples](https://effect-cqrs.dambox.ch/reference/api/eventcatalog/#incompatiblesamples) listing the ones that no longer decode. Returns how many samples were checked. Personal fields in samples are expected in plaintext, as [captureSamples](https://effect-cqrs.dambox.ch/reference/api/eventcatalog/#capturesamples) leaves them, so no keys are needed. #### Parameters ##### aggregate [`Any`](https://effect-cqrs.dambox.ch/reference/api/aggregate/#any) ##### samples readonly `object`\[] #### Returns `Effect`<`number`, [`IncompatibleSamples`](https://effect-cqrs.dambox.ch/reference/api/eventcatalog/#incompatiblesamples)> *** ### commands() > **commands**(`aggregate`): readonly [`CommandEntry`](https://effect-cqrs.dambox.ch/reference/api/eventcatalog/#commandentry)\[] Defined in: [src/EventCatalog.ts:88](https://github.com/davidnussio/effect-cqrs/blob/9d66af7141782f3f89655e6868abe3f141c97632/src/EventCatalog.ts#L88) The JSON Schema of the payload of every command of an aggregate. #### Parameters ##### aggregate [`Any`](https://effect-cqrs.dambox.ch/reference/api/aggregate/#any) #### Returns readonly [`CommandEntry`](https://effect-cqrs.dambox.ch/reference/api/eventcatalog/#commandentry)\[] *** ### document() > **document**(`aggregates`, `options`): [`AsyncApiDocument`](https://effect-cqrs.dambox.ch/reference/api/eventcatalog/#asyncapidocument) Defined in: [src/EventCatalog.ts:138](https://github.com/davidnussio/effect-cqrs/blob/9d66af7141782f3f89655e6868abe3f141c97632/src/EventCatalog.ts#L138) 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`](https://effect-cqrs.dambox.ch/reference/api/aggregate/#any)\[] ##### options [`DocumentOptions`](https://effect-cqrs.dambox.ch/reference/api/eventcatalog/#documentoptions) #### Returns [`AsyncApiDocument`](https://effect-cqrs.dambox.ch/reference/api/eventcatalog/#asyncapidocument) *** ### events() > **events**(`aggregate`): readonly [`EventEntry`](https://effect-cqrs.dambox.ch/reference/api/eventcatalog/#evententry)\[] Defined in: [src/EventCatalog.ts:75](https://github.com/davidnussio/effect-cqrs/blob/9d66af7141782f3f89655e6868abe3f141c97632/src/EventCatalog.ts#L75) The JSON Schema of every event of an aggregate, in every version it declares. #### Parameters ##### aggregate [`Any`](https://effect-cqrs.dambox.ch/reference/api/aggregate/#any) #### Returns readonly [`EventEntry`](https://effect-cqrs.dambox.ch/reference/api/eventcatalog/#evententry)\[] *** ### readSamples() > **readSamples**(`path`): `Effect`\ Defined in: [src/EventCatalog.ts:311](https://github.com/davidnussio/effect-cqrs/blob/9d66af7141782f3f89655e6868abe3f141c97632/src/EventCatalog.ts#L311) Reads samples written by [saveSamples](https://effect-cqrs.dambox.ch/reference/api/eventcatalog/#savesamples). #### Parameters ##### path `string` #### Returns `Effect`\ *** ### saveSamples() > **saveSamples**(`path`, `samples`): `Effect`<`object`\[], `PlatformError` | `SchemaError`, `FileSystem`> Defined in: [src/EventCatalog.ts:322](https://github.com/davidnussio/effect-cqrs/blob/9d66af7141782f3f89655e6868abe3f141c97632/src/EventCatalog.ts#L322) 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`>