ViewModel

The read side: projections of events into whatever storage a query needs.

Moleculer-cqrs pushes events to view models over the broker, so an event sent while a service is down is lost until someone replays. Here each view model pulls from the store from its own checkpoint, so it can’t miss anything, and delivery is at least once: a handler can see an event again after a crash and should be idempotent, unless the view model has a transaction.

Classes

UnknownViewModel

Defined in: src/ViewModel.ts:40

Extends

• object & YieldableError<this>

Constructors

Constructor

new UnknownViewModel(…args): UnknownViewModel

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

Parameters

args

…[props: object, options?: MakeOptions]

Returns

UnknownViewModel

Inherited from

Schema.TaggedError<UnknownViewModel>()("UnknownViewModel", { name: Schema.String }).constructor

Properties

name

name: string = Schema.String

Defined in: src/ViewModel.ts:41

Inherited from

Schema.TaggedError<UnknownViewModel>()("UnknownViewModel", { name: Schema.String }).name

---

ViewModelError

Defined in: src/ViewModel.ts:44

Extends

• object & YieldableError<this>

Constructors

Constructor

new ViewModelError(…args): ViewModelError

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

Parameters

args

…[props: object, options?: MakeOptions]

Returns

ViewModelError

Inherited from

Schema.TaggedError<ViewModelError>()("ViewModelError", { viewModel: Schema.String, /** The event being processed, `0` when the failure happened outside any event. */ position: Schema.Int, cause: Schema.Defect() }).constructor

Properties

cause

cause: unknown

Defined in: src/ViewModel.ts:48

Inherited from

Schema.TaggedError<ViewModelError>()("ViewModelError", { viewModel: Schema.String, /** The event being processed, `0` when the failure happened outside any event. */ position: Schema.Int, cause: Schema.Defect() }).cause

position

readonly position: number = Schema.Int

Defined in: src/ViewModel.ts:47

The event being processed, 0 when the failure happened outside any event.

Inherited from

Schema.TaggedError<ViewModelError>()("ViewModelError", { viewModel: Schema.String, /** The event being processed, `0` when the failure happened outside any event. */ position: Schema.Int, cause: Schema.Defect() }).position

viewModel

readonly viewModel: string = Schema.String

Defined in: src/ViewModel.ts:45

Inherited from

Schema.TaggedError<ViewModelError>()("ViewModelError", { viewModel: Schema.String, /** The event being processed, `0` when the failure happened outside any event. */ position: Schema.Int, cause: Schema.Defect() }).viewModel

---

ViewModels

Defined in: src/ViewModel.ts:206

Extends

• Shape<"effect-cqrs/ViewModels", { status: Effect<readonly Status[]>; caughtUp(position?): Effect<void, EventStoreError>; parked(viewModel?): Effect<readonly object[], EventStoreError | UnknownViewModel>; replay(options): Effect<ReplayResult, UnknownViewModel | ViewModelError>; retryParked(options): Effect<RetryParkedResult, EventStoreError | UnknownViewModel | ViewModelError>; }, this>

Constructors

Constructor

new ViewModels(_): ViewModels

Defined in: node_modules/.pnpm/effect@4.0.6/node_modules/effect/dist/Context.d.ts:121

Parameters

_

never

Returns

ViewModels

Inherited from

Context.Service<ViewModels, { /** * Disposes the named view models and rebuilds them from their events. A time * window limits which events are replayed: the view model then resumes from * the present and events outside the window stay out of it. */ replay(options: ReplayOptions): Effect.Effect<ReplayResult, UnknownViewModel | ViewModelError> /** * Waits until every view model has processed `position`, defaulting to the * latest event. Pair it with `CommandResult.position` to read your own writes. * A view model stalled on a failure doesn’t catch up, so consider a timeout. * View models that another process holds are not waited for. */ caughtUp(position?: number): Effect.Effect<void, EventStoreError> readonly status: Effect.Effect<ReadonlyArray<Status>> /** The events the view models of this layer parked, or those of one of them. */ parked(viewModel?: string): Effect.Effect<ReadonlyArray<ParkedEvents.ParkedEvent>, UnknownViewModel | EventStoreError> /** * Handles parked events again, in order of position. Those that succeed are no * longer parked, and the others stay parked with the new failure. */ retryParked( options: RetryParkedOptions ): Effect.Effect<RetryParkedResult, UnknownViewModel | ViewModelError | EventStoreError> }>()(“effect-cqrs/ViewModels”).constructor

Interfaces

ReplayOptions

Defined in: src/ViewModel.ts:171

Properties

finishTime?

readonly optional finishTime?: Utc

Defined in: src/ViewModel.ts:174

startTime?

readonly optional startTime?: Utc

Defined in: src/ViewModel.ts:173

viewModels

readonly viewModels: readonly string[]

Defined in: src/ViewModel.ts:172

---

ReplayResult

Defined in: src/ViewModel.ts:177

Properties

eventCount

readonly eventCount: number

Defined in: src/ViewModel.ts:179

viewModels

readonly viewModels: readonly string[]

Defined in: src/ViewModel.ts:178

---

RetryParkedOptions

Defined in: src/ViewModel.ts:193

Properties

positions?

readonly optional positions?: readonly number[]

Defined in: src/ViewModel.ts:196

The positions of the events to retry. Defaults to every event the view model parked.

viewModel

readonly viewModel: string

Defined in: src/ViewModel.ts:194

---

RetryParkedResult

Defined in: src/ViewModel.ts:199

Properties

failed

readonly failed: readonly object[]

Defined in: src/ViewModel.ts:203

The events that failed again, as they are parked now.

succeeded

readonly succeeded: readonly number[]

Defined in: src/ViewModel.ts:201

The positions of the events that were handled, and are no longer parked.

---

Status

Defined in: src/ViewModel.ts:182

Properties

holdsLease

readonly holdsLease: boolean

Defined in: src/ViewModel.ts:190

Whether this process holds the view model’s lease, and so runs it. See Leases.

lastError

readonly lastError: Option<ViewModelError>

Defined in: src/ViewModel.ts:186

The failure the view model is retrying, while it is stalled on one.

name

readonly name: string

Defined in: src/ViewModel.ts:183

parked

readonly parked: number

Defined in: src/ViewModel.ts:188

How many events the view model parked and skips, see park.

position

readonly position: number

Defined in: src/ViewModel.ts:184

---

ViewModel

Defined in: src/ViewModel.ts:66

Type Parameters

Name

Name extends string

E

E

R

R

Properties

aggregates

readonly aggregates: readonly Any[]

Defined in: src/ViewModel.ts:68

dispose

readonly dispose: Effect<void, E, R>

Defined in: src/ViewModel.ts:71

Clears everything the view model stored, before a replay rebuilds it.

handlers

readonly handlers: Record<string, (event, meta) => Effect.Effect<unknown, E, R>>

Defined in: src/ViewModel.ts:69

name

readonly name: Name

Defined in: src/ViewModel.ts:67

onFailure?

readonly optional onFailure?: FailurePolicy

Defined in: src/ViewModel.ts:75

What happens to an event its handler keeps failing on. Defaults to stall.

onForget?

readonly optional onForget?: (subject, meta) => Effect<unknown, E, R>

Defined in: src/ViewModel.ts:73

Erases what the view model stored about a forgotten subject, see PersonalData.forget.

Parameters

subject

string

meta

EventMeta

Returns

Effect<unknown, E, R>

transaction?

readonly optional transaction?: Transaction<R>

Defined in: src/ViewModel.ts:77

Runs each batch of handlers together with the checkpoint they reach, see sqlTransaction.

Type Aliases

Any

Any = ViewModel<string, any, any>

Defined in: src/ViewModel.ts:114

---

Context

Context<V> = V extends ViewModel<any, any, infer R> ? R : never

Defined in: src/ViewModel.ts:116

Type Parameters

V

V extends Any

---

FailurePolicy

FailurePolicy = { _tag: "Stall"; } | { _tag: "Park"; attempts: number; }

Defined in: src/ViewModel.ts:101

What a view model does about an event whose handler keeps failing.

• Stall retries it forever, with a growing delay, and nothing after it is processed in the meantime. Nothing is ever skipped.
• Park retries it until it has failed attempts times, then records it in ParkedEvents and moves on. ViewModels.retryParked handles it again later.

---

Handlers

Handlers<Event> = { readonly [Tag in Event["_tag"]]?: (event: Extract<Event, { _tag: Tag }>, meta: EventMeta) => Effect.Effect<unknown, any, any> }

Defined in: src/ViewModel.ts:51

Type Parameters

Event

Event extends Tagged

---

Transaction

Transaction<R> = (effect) => Effect.Effect<void, unknown, R>

Defined in: src/ViewModel.ts:84

Wraps a batch of handlers and the checkpoint after them, so that they commit or roll back together.

Type Parameters

R

R

Parameters

effect

Effect.Effect<void, ViewModelError>

Returns

Effect.Effect<void, unknown, R>

Variables

MetricNames

const MetricNames: object

Defined in: src/ViewModel.ts:236

The names of the metrics view models record through Effect’s Metric module. Each series carries a view_model attribute with the view model’s name.

Type Declaration

parkedEvents

readonly parkedEvents: "cqrs_view_model_parked_events_total" = "cqrs_view_model_parked_events_total"

Counter: events a view model parked after its handler kept failing on them.

---

sqlTransaction

const sqlTransaction: Transaction<SqlClient.SqlClient>

Defined in: src/ViewModel.ts:90

A transaction of the SqlClient in context. The read model and the checkpoints have to use that same client for their writes to join it.

---

stall

const stall: FailurePolicy

Defined in: src/ViewModel.ts:106

Retries a failing event until it succeeds, holding everything after it back. The default.

Functions

layer()

layer<VMs>(viewModels): Layer<ViewModels, EventStoreError, EventStore | Checkpoints | Context<VMs[number]>>

Defined in: src/ViewModel.ts:723

Starts the view models in the background for as long as the layer lives.

Each view model runs where its lease is held, see Leases: by default in every process, which suits a single one. Events that view models park go to the ParkedEvents in context, or to memory without one.

Type Parameters

VMs

VMs extends readonly Any[]

Parameters

viewModels

VMs

Returns

Layer<ViewModels, EventStoreError, EventStore | Checkpoints | Context<VMs[number]>>

---

make()

make<Name, Aggregates, H, E, R, FE, FR, TR>(options): ViewModel<Name, E | FE | HandlerError<H>, R | FR | TR | HandlerContext<H>>

Defined in: src/ViewModel.ts:130

Handlers are keyed by event tag, and events without one are skipped.

A view model that keeps personal data handles onForget, which runs when PersonalData.forget records that a subject was forgotten, in order with the events around it. Events the view model reads afterwards already carry the replacements, so it only has to erase what it stored before.

onFailure decides what happens to an event that keeps failing, see FailurePolicy. With transaction, each batch of handlers runs in one transaction with the checkpoint it reaches, so a crash never repeats an event.

Type Parameters

Name

Name extends string

Aggregates

Aggregates extends readonly Any[]

H

H extends Handlers<Event<Aggregates[number]>>

E

E = never

R

R = never

FE

FE = never

FR

FR = never

TR

TR = never

Parameters

options

aggregates

Aggregates

dispose

Effect<void, E, R>

handlers

H

name

Name

onFailure?

FailurePolicy

onForget?

(subject, meta) => Effect<unknown, FE, FR>

transaction?

Transaction<TR>

Returns

ViewModel<Name, E | FE | HandlerError<H>, R | FR | TR | HandlerContext<H>>

---

park()

park(options): FailurePolicy

Defined in: src/ViewModel.ts:109

Gives up on an event after it failed attempts times, and goes on with the next ones.

Parameters

options

attempts

number

Returns

FailurePolicy