EventLog.ts

EventLog.ts overview

Runtime for writing typed events to an event journal.

EventLog combines event groups, handlers, a journal, local identity, optional remote replicas, and reactivity hooks. Writers send typed payloads through a client; the matching handler runs first, and the journal entry is committed only after the handler succeeds. This module also contains the layers and helpers needed to assemble that runtime.

Since v4.0.0

---

Exports Grouped by Category

• client
  • makeClient
• compaction
  • groupCompaction
• constructors
  • decodeIdentityString
  • encodeIdentityString
  • makeIdentity
• handlers
  • Handlers (interface)
  • group
  • makeReplayFromRemote
• layers
  • layer
  • layerEventLog
  • layerRegistry
• models
  • CurrentStoreId (class)
• reactivity
  • groupReactivity
• schemas
  • EventLogSchema (interface)
  • IdentitySchema
  • isEventLogSchema
  • schema
• services
  • EventLog (class)
  • Identity (class)
  • Registry (class)
• type IDs
  • HandlersTypeId
  • HandlersTypeId (type alias)
  • SchemaTypeId
  • SchemaTypeId (type alias)
• utils
  • Handlers (namespace)
    • Any (interface)
    • Item (type alias)
    • ValidateReturn (type alias)
    • Error (type alias)
    • Services (type alias)

---

client

makeClient

Creates a typed client function for writing events defined by an EventLogSchema.

Details

The returned function delegates to the EventLog service and preserves each event’s success and error types.

Signature

declare const makeClient: <Groups extends EventGroup.Any>(
  schema: EventLogSchema<Groups>
) => Effect.Effect<
  <Tag extends Event.Tag<EventGroup.Events<Groups>>>(
    event: Tag,
    payload: Event.PayloadWithTag<EventGroup.Events<Groups>, Tag>
  ) => Effect.Effect<
    Event.SuccessWithTag<EventGroup.Events<Groups>, Tag>,
    Event.ErrorWithTag<EventGroup.Events<Groups>, Tag> | EventJournalError
  >,
  never,
  EventLog
>

Source

Since v4.0.0

compaction

groupCompaction

Registers a compaction handler for an event group.

Details

During remote replay, matching entries are decoded, grouped by primary key, and passed to the compaction effect, which may write replacement entries.

Signature

declare const groupCompaction: <Events extends Event.Any, R>(
  group: EventGroup.EventGroup<Events>,
  effect: (options: {
    readonly primaryKey: string
    readonly entries: ReadonlyArray<Entry>
    readonly events: ReadonlyArray<Event.TaggedPayload<Events>>
    readonly write: <Tag extends Event.Tag<Events>>(
      tag: Tag,
      payload: Event.PayloadWithTag<Events, Tag>
    ) => Effect.Effect<void, never, Event.PayloadSchemaWithTag<Events, Tag>["EncodingServices"]>
  }) => Effect.Effect<void, never, R>
) => Layer.Layer<never, never, R | Event.PayloadSchema<Events>["DecodingServices"] | Registry>

Source

Since v4.0.0

constructors

decodeIdentityString

Decodes a base64url identity string produced by encodeIdentityString.

Gotchas

Invalid input throws a schema decoding error.

Signature

declare const decodeIdentityString: (value: string) => Identity["Service"]

Source

Since v4.0.0

encodeIdentityString

Encodes an event-log identity as a base64url string containing the public key and private key bytes.

Signature

declare const encodeIdentityString: (identity: Identity["Service"]) => string

Source

Since v4.0.0

makeIdentity

Generates a new event-log identity using the configured EventLogEncryption service.

Signature

declare const makeIdentity: Effect.Effect<
  { readonly publicKey: string; readonly privateKey: Redacted.Redacted<Uint8Array<ArrayBuffer>> },
  never,
  EventLogEncryption.EventLogEncryption
>

Source

Since v4.0.0

handlers

Handlers (interface)

Builder for the handlers associated with an EventGroup.

Details

The Events type parameter tracks the event tags that still need handlers, and each call to handle records a handler while accumulating any required services.

Signature

export interface Handlers<R, Events extends Event.Any = never> extends Pipeable {
  readonly [HandlersTypeId]: {
    _Events: Covariant<Events>
  }
  readonly group: EventGroup.AnyWithProps
  readonly handlers: Record.ReadonlyRecord<string, Handlers.Item<R>>
  readonly context: Context.Context<R>

  /**
   * Add the implementation for an `Event` to a `Handlers` group.
   */
  handle<Tag extends Event.Tag<Events>, R1>(
    name: Tag,
    handler: (options: {
      readonly storeId: StoreId
      readonly payload: Event.PayloadWithTag<Events, Tag>
      readonly entry: Entry
      readonly conflicts: ReadonlyArray<{
        readonly entry: Entry
        readonly payload: Event.PayloadWithTag<Events, Tag>
      }>
    }) => Effect.Effect<Event.SuccessWithTag<Events, Tag>, Event.ErrorWithTag<Events, Tag>, R1>
  ): Handlers<R | R1, Event.ExcludeTag<Events, Tag>>
}

Source

Since v4.0.0

group

Creates a layer that registers handlers for every event in an event group.

Details

The callback receives a Handlers builder; its return type is checked so every event in the group is handled.

Signature

declare const group: <Events extends Event.Any, Return>(
  group: EventGroup.EventGroup<Events>,
  f: (handlers: Handlers<never, Events>) => Handlers.ValidateReturn<Return>
) => Layer.Layer<
  Event.ToService<Events>,
  Handlers.Error<Return>,
  Exclude<Handlers.Services<Return>, Scope.Scope | Identity> | Registry
>

Source

Since v4.0.0

makeReplayFromRemote

Builds the effect used to replay entries received from a remote event log.

Details

The returned handler decodes the entry and conflicts with the registered event schema, runs the matching handler with the supplied identity and store id, logs failures, and invalidates configured reactivity keys.

Signature

declare const makeReplayFromRemote: (options: {
  readonly handlers: ReadonlyMap<string, Handlers.Item<any>>
  readonly storeId: StoreId
  readonly identity: Identity["Service"]
  readonly reactivity: Reactivity["Service"]
  readonly reactivityKeys: Record<string, ReadonlyArray<string>>
  readonly logAnnotations: { readonly service: string; readonly effect: string }
}) => (args_0: { readonly entry: Entry; readonly conflicts: ReadonlyArray<Entry> }) => Effect.Effect<void, never, never>

Source

Since v4.0.0

layers

layer

Combines event-group handler layers with the EventLog runtime for a schema.

When to use

Use when you need one layer that installs the shared EventLog runtime for an EventLogSchema and registers an event-group handler layer for typed writes.

Details

The supplied handler layer is provided with layerEventLog. The returned layer provides EventLog | Registry, preserves the handler layer’s error type, and still requires its remaining services plus EventJournal and Identity.

Gotchas

The schema argument does not register handlers by itself. Handler registration comes from the supplied layer, and writing an event without a registered handler dies with Event handler not found for: "<tag>".

See

• schema for creating the schema argument from event groups
• group for building the handler layer consumed by this layer
• layerEventLog for installing the runtime and registry without combining a handler layer

Signature

declare const layer: <Groups extends EventGroup.Any, E, R>(
  _schema: EventLogSchema<Groups>,
  layer: Layer.Layer<EventGroup.ToService<Groups>, E, R>
) => Layer.Layer<EventLog | Registry, E, Exclude<R, EventLog | Registry> | EventJournal | Identity>

Source

Since v4.0.0

layerEventLog

Provides EventLog and Registry using the configured EventJournal and Identity.

Signature

declare const layerEventLog: Layer.Layer<Registry | EventLog, never, EventJournal | Identity>

Source

Since v4.0.0

layerRegistry

Provides an in-memory Registry for event handlers, compactors, remote replicas, and reactivity keys.

Signature

declare const layerRegistry: Layer.Layer<Registry, never, never>

Source

Since v4.0.0

models

CurrentStoreId (class)

Context reference for the store id used by event-log writes and remote replication.

Details

Defaults to the branded store id "default".

Signature

declare class CurrentStoreId

Source

Since v4.0.0

reactivity

groupReactivity

Registers reactivity keys to invalidate when events from a group are written or replayed.

Details

Pass a single key list for all events or a mapping from event tag to key list.

Signature

declare const groupReactivity: <Events extends Event.Any>(
  group: EventGroup.EventGroup<Events>,
  keys: { readonly [Tag in Event.Tag<Events>]?: ReadonlyArray<string> } | ReadonlyArray<string>
) => Layer.Layer<never, never, Registry>

Source

Since v4.0.0

schemas

EventLogSchema (interface)

Schema describing the event groups that can be written through an EventLog.

Signature

export interface EventLogSchema<Groups extends EventGroup.Any> {
  readonly [SchemaTypeId]: SchemaTypeId
  readonly groups: ReadonlyArray<Groups>
}

Source

Since v4.0.0

IdentitySchema

Schema for an event-log identity with a string public key and redacted base64-encoded private key bytes.

Signature

declare const IdentitySchema: Schema.Struct<{
  readonly publicKey: Schema.String
  readonly privateKey: Schema.decodeTo<Schema.Redacted<Schema.Uint8Array>, Schema.Uint8ArrayFromBase64, never, never>
}>

Source

Since v4.0.0

isEventLogSchema

Returns true when a value carries the EventLogSchema marker.

Signature

declare const isEventLogSchema: (u: unknown) => u is EventLogSchema<EventGroup.Any>

Source

Since v4.0.0

schema

Creates an EventLogSchema from one or more event groups.

Signature

declare const schema: <Groups extends ReadonlyArray<EventGroup.Any>>(
  ...groups: Groups
) => EventLogSchema<Groups[number]>

Source

Since v4.0.0

services

EventLog (class)

Service for writing typed event-log events through registered handlers.

Details

write encodes the event payload, runs the matching handler, commits the entry only when the handler succeeds, and exposes access to the underlying journal entries and destroy operation.

Signature

declare class EventLog

Source

Since v4.0.0

Identity (class)

Context service for an event-log identity containing a public key and redacted private key material.

Details

The identity is used by remote replication for authentication and by the encryption service to derive signing and encryption keys.

Signature

declare class Identity

Source

Since v4.0.0

Registry (class)

Service that collects event handlers, compaction handlers, remote replicas, and reactivity invalidation keys.

Signature

declare class Registry

Source

Since v4.0.0

type IDs

HandlersTypeId

Runtime property key used to identify Handlers values.

Signature

declare const HandlersTypeId: "~effect/eventlog/EventLog/Handlers"

Source

Since v4.0.0

HandlersTypeId (type alias)

Type-level identifier used to brand Handlers values.

Signature

type HandlersTypeId = "~effect/eventlog/EventLog/Handlers"

Source

Since v4.0.0

SchemaTypeId

Runtime property key used to identify EventLogSchema values.

Signature

declare const SchemaTypeId: "~effect/eventlog/EventLog/Schema"

Source

Since v4.0.0

SchemaTypeId (type alias)

Type-level identifier used to brand EventLogSchema values.

Signature

type SchemaTypeId = "~effect/eventlog/EventLog/Schema"

Source

Since v4.0.0

utils

Handlers (namespace)

Namespace containing helper types for Handlers values and handler-producing layers.

Source

Since v4.0.0

Any (interface)

Type that matches any Handlers value regardless of its services or remaining events.

Signature

export interface Any {
  readonly [HandlersTypeId]: unknown
}

Source

Since v4.0.0

Item (type alias)

Runtime representation of one registered event handler, including its event metadata, captured context, and handler function.

Signature

type Item<R> = {
  readonly event: Event.AnyWithProps
  readonly context: Context.Context<R>
  readonly handler: (options: {
    readonly storeId: StoreId
    readonly payload: unknown
    readonly entry: Entry
    readonly conflicts: ReadonlyArray<{
      readonly entry: Entry
      readonly payload: unknown
    }>
  }) => Effect.Effect<unknown, unknown, R>
}

Source

Since v4.0.0

ValidateReturn (type alias)

Validates that a handler builder returned all required handlers.

Details

If any event tag remains unhandled, the type evaluates to an explanatory compile-time error string.

Signature

type ValidateReturn<A> = A extends
  | Handlers<infer _R, infer _Events>
  | Effect.Effect<Handlers<infer _R, infer _Events>, infer _EX, infer _RX>
  ? [_Events] extends [never]
    ? A
    : `Event not handled: ${Event.Tag<_Events>}`
  : `Must return the implemented handlers`

Source

Since v4.0.0

Error (type alias)

Extracts the error type from an effect that produces Handlers.

Signature

type Error<A> = A extends Effect.Effect<Handlers<infer _R, infer _Events>, infer _EX, infer _RX> ? _EX : never

Source

Since v4.0.0

Services (type alias)

Computes the services required by a Handlers value or by an effect that produces one, including event schema services.

Signature

type Services<A> =
  A extends Handlers<infer _R, infer _Events>
    ? _R | Event.Services<_Events>
    : A extends Effect.Effect<Handlers<infer _R, infer _Events>, infer _EX, infer _RX>
      ? _R | _RX | Event.Services<_Events>
      : never

Source

Since v4.0.0