effect-cqrs 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019-2026 David Nussio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,299 @@
-# Temporary Holding Version
+# effect-cqrs
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+This is a trial port of an old project,
+[moleculer-cqrs](https://github.com/davidnussio/moleculer-cqrs), to
+[Effect](https://effect.website) v4. The original is a CQRS and event sourcing module
+for [Moleculer](https://moleculer.services), written in 2019. This repository
+rebuilds the same ideas on Effect to find out how well they carry over.
+
+It's an experiment, not a maintained library: the API may change, and
+[Limitations](#limitations) lists what the port leaves out.
+
+The documentation, with a walkthrough of the bank demo, is at
+https://davidnussio.github.io/effect-cqrs/.
+
+Commands decide on events, events are the only source of truth, and read models
+are projections you can throw away and rebuild.
+
+## Install
+
+```bash
+pnpm add effect-cqrs effect
+```
+
+It needs Node 24 or later and Effect 4. To store events in SQLite or PostgreSQL, add
+that database's `effect/sql` driver too, `@effect/sql-sqlite-node` or `@effect/sql-pg`.
+
+## Develop
+
+```bash
+pnpm install
+pnpm test
+pnpm example
+```
+
+The example needs `node:sqlite` and runs TypeScript directly. `pnpm build` compiles
+`src` into `dist`, which is what npm gets.
+
+`pnpm ui` serves an interactive demo at http://localhost:5173, also published at
+https://davidnussio.github.io/effect-cqrs/demo/. It runs the framework
+in the browser on the in-memory store: a bank whose accounts are aggregates, three
+view models, and a saga for transfers. Its devtools slow commands and projections
+down, pause and step the command bus, crash a projection, scrub through the log and
+replay view models up to a chosen event.
+
+## Define an aggregate
+
+An aggregate is a schema of events, a projection folding them into state, and
+commands deciding on new events.
+
+```ts
+import { DateTime, Effect, Schema } from "effect"
+import { Aggregate } from "effect-cqrs"
+
+const TodoEvent = Schema.TaggedUnion({
+  TodoCreated: { title: Schema.NonEmptyString, createdAt: Schema.DateTimeUtc },
+  TodoDeleted: { deletedAt: Schema.DateTimeUtc }
+})
+
+class TodoAlreadyDeleted extends Schema.TaggedError<TodoAlreadyDeleted>()("TodoAlreadyDeleted", {}) {}
+
+type TodoState = { readonly title: string; readonly deleted: boolean }
+
+const Todo = Aggregate.make<TodoState>()({
+  name: "todo",
+  events: TodoEvent,
+  initial: { title: "", deleted: false },
+  projection: {
+    TodoCreated: (state, { title }) => ({ ...state, title }),
+    TodoDeleted: (state) => ({ ...state, deleted: true })
+  }
+})
+  .command("createTodo", {
+    payload: Schema.Struct({ title: Schema.NonEmptyString }),
+    handler: Effect.fnUntraced(function*(_, { title }) {
+      return TodoEvent.cases.TodoCreated.make({ title, createdAt: yield* DateTime.now })
+    })
+  })
+  .command("deleteTodo", {
+    payload: Schema.Struct({}),
+    handler: Effect.fnUntraced(function*(state) {
+      if (state.deleted) return yield* new TodoAlreadyDeleted()
+      return TodoEvent.cases.TodoDeleted.make({ deletedAt: yield* DateTime.now })
+    })
+  })
+```
+
+The projection must cover every event or it doesn't compile. A handler returns one
+event, several, or `[]` to record nothing. It can use services, fail with typed
+errors, and may run more than once, so it should only decide. Projections and
+handlers must not mutate the state, which is kept between commands.
+
+## Run commands
+
+```ts
+import { AggregateService, EventStore } from "effect-cqrs"
+
+const program = Effect.gen(function*() {
+  const todos = yield* AggregateService.make(Todo)
+
+  // Typed call
+  yield* todos.commands.createTodo("todo-1", { title: "Buy Milk" })
+
+  // Untyped JSON from a transport, validated before running
+  yield* todos.dispatch({ aggregateId: "todo-2", type: "createTodo", payload: { title: "Buy Eggs" } })
+
+  yield* todos.readModel("todo-1")
+  yield* todos.readModel("todo-1", { finishTime }) // state as it was before finishTime
+  yield* todos.history("todo-1", { payload: true })
+}).pipe(Effect.provide(EventStore.layerMemory))
+```
+
+Commands on one stream take turns inside a service, so they can't race. A handler must
+not run a command on its own stream, which would wait for itself. Across processes
+writers use optimistic concurrency: a command that loses a race backs off, reloads the
+state and decides again, up to `maxRetries` times (5 by default), then fails with
+`ConcurrencyConflict`.
+
+The service remembers the state of recent aggregates (`stateCacheSize`, 10,000 by
+default), so a command only reads the events it hasn't seen.
+
+## Project into view models
+
+A view model reads the event store from its own checkpoint, so it catches up after
+downtime and can't miss an event. Delivery is at least once, so handlers should be
+idempotent.
+
+```ts
+import { Checkpoints, ViewModel } from "effect-cqrs"
+
+const TodoList = ViewModel.make({
+  name: "todo-list",
+  aggregates: [Todo],
+  dispose: clearList, // runs before a replay
+  handlers: {
+    TodoCreated: ({ title }, { aggregateId }) => addToList(aggregateId, title),
+    TodoDeleted: (_, { aggregateId }) => removeFromList(aggregateId)
+  }
+})
+
+const program = Effect.gen(function*() {
+  const todos = yield* AggregateService.make(Todo)
+  const viewModels = yield* ViewModel.ViewModels
+
+  const { position } = yield* todos.commands.createTodo("todo-1", { title: "Buy Milk" })
+  yield* viewModels.caughtUp(position) // read your own write
+
+  yield* viewModels.replay({ viewModels: ["todo-list"] })
+  yield* viewModels.status
+}).pipe(
+  Effect.provide(ViewModel.layer([TodoList]).pipe(
+    Layer.provideMerge(Layer.merge(EventStore.layerMemory, Checkpoints.layerMemory))
+  ))
+)
+```
+
+A failing handler stalls its view model on that event and retries with backoff, so
+events are never skipped or reordered. `viewModels.status` exposes the failure.
+
+Anything else that reacts to events can use `store.subscribe(filter)`, a stream of
+past events followed by live ones.
+
+## Test an aggregate
+
+`Fixture` runs commands through the real service on an in-memory store, so payload
+validation and event encoding are tested too. It reads like `CQRSFixture`, and the
+chain runs when you yield it or hand it to `it.effect`:
+
+```ts
+import { assert, it } from "@effect/vitest"
+import { Fixture } from "effect-cqrs"
+
+it.effect("creates a todo", () =>
+  Fixture.make(Todo)
+    .givenEvents()
+    .when("createTodo", { title: "Buy Milk" })
+    .expectEvent(TodoEvent.cases.TodoCreated.make({ title: "Buy Milk", createdAt: DateTime.makeUnsafe(0) }))
+    .inspectState((state) => assert.strictEqual(state.title, "Buy Milk")))
+
+it.effect("runs commands one after another", () =>
+  Fixture.make(Todo)
+    .givenEvents([created])
+    .when("deleteTodo", {})
+    .expectEvent("TodoDeleted")
+    .when("createTodo", { title: "Buy Eggs" })
+    .expectEvents(["TodoCreated"]))
+
+it.effect("rejects deleting twice", () =>
+  Effect.gen(function*() {
+    const error = yield* Fixture.make(Todo)
+      .givenEvents([created, deleted])
+      .whenFails("deleteTodo", {})
+
+    assert.strictEqual(error._tag, "TodoAlreadyDeleted")
+  }))
+```
+
+- `when` runs a command by name, typed against the aggregate. Commands that fail
+  stop the chain with their typed error.
+- `expectEvent` expects exactly one event and `expectEvents` an exact, ordered list,
+  so `expectEvents([])` asserts that nothing was recorded. Each entry is a whole
+  event, compared with the aggregate's schema, or only its tag.
+- `inspectState` takes a callback that throws to fail the test, so any assertion
+  library works.
+- Yielding the chain gives `{ events, state, version, fixture }` for the last
+  command, if you prefer plain assertions.
+
+`it.effect` runs on a test clock stopped at zero, so timestamps need no mocking: an
+event created by `DateTime.now` has `DateTime.makeUnsafe(0)` until
+`TestClock.adjust` moves time.
+
+## Storage
+
+`EventStore.layerMemory` keeps events in memory. For SQLite, provide any
+`effect/sql` SQLite client:
+
+```ts
+import { SqliteClient } from "@effect/sql-sqlite-node"
+import { SqliteEventStore } from "effect-cqrs"
+
+const Storage = Layer.merge(SqliteEventStore.layer(), SqliteEventStore.layerCheckpoints()).pipe(
+  Layer.provide(SqliteClient.layer({ filename: "./data/events.sqlite" }))
+)
+```
+
+Tables are created on startup. Use durable checkpoints only with a durable view
+model: an in-memory view model paired with `Checkpoints.layerMemory` rebuilds itself
+on every start, which is usually what you want.
+
+For PostgreSQL, provide an `effect/sql` PostgreSQL client:
+
+```ts
+import { PgClient } from "@effect/sql-pg"
+import { PostgresEventStore } from "effect-cqrs"
+
+const Storage = Layer.merge(PostgresEventStore.layer(), PostgresEventStore.layerCheckpoints()).pipe(
+  Layer.provide(PgClient.layer({ url: Redacted.make("postgres://localhost:5432/cqrs") }))
+)
+```
+
+Writers wait for each other at one step of each commit, which keeps positions in commit
+order. Several processes can write to one database, but a view model only wakes on
+appends from its own process. After a bulk load, run `ANALYZE`, or reads for view models
+are slow until autovacuum gets to the table.
+
+To run the tests on Postgres, `docker compose up -d --wait` starts one, and setting
+`POSTGRES_URL=postgres://postgres:postgres@localhost:5432/cqrs` includes it in
+`pnpm test`.
+
+Another database needs an `EventStore.Backend`: `append`, `readBatch` and `head`.
+Positions must follow commit order, so a backend on a database with concurrent
+writers has to guarantee that itself.
+
+## Performance
+
+On a SQLite file a command takes about 0.1 ms, however long its stream is and however
+many events the store holds, and a million events replay in under 5 seconds. On Postgres
+a command takes about 1 ms. The first use of a stream after a restart replays it, at
+about 3 µs per event. See the [performance and stress report](bench/REPORT.md) for the
+numbers and the remaining limits.
+
+`pnpm bench` measures each operation and `pnpm stress` loads the framework while
+checking that nothing is lost.
+
+## Coming from moleculer-cqrs
+
+| moleculer-cqrs | effect-cqrs |
+| --- | --- |
+| `CQRSEventSourcing({ aggregate })` mixin | `AggregateService.make(aggregate)` |
+| `call todo.command` | `todos.commands.x(id, payload)` or `todos.dispatch(json)` |
+| `call todo.read-model` | `todos.readModel(id, { finishTime })` |
+| `call todo.history` | `todos.history(id, { payload, startTime, finishTime })` |
+| `call todo.replay` | `viewModels.replay({ viewModels, startTime, finishTime })` |
+| view model service with `events` | `ViewModel.make({ handlers, dispose })` |
+| `new CQRSFixture(aggregate)` | `Fixture.make(aggregate)` |
+| `.givenEvents([...])` | `.givenEvents([...])` |
+| `.when(createNews, payload)` | `.when("createNews", payload)` |
+| `.expectEvent(event)` | `.expectEvent(event)` or `.expectEvent("Tag")` |
+| `.inspectState(cb)` | `.inspectState(cb)` |
+| `.whenThrow(command).toThrow(...)` | `.whenFails(command, payload)`, which returns the error |
+| `fastest-validator` | `Schema` |
+| `throw` in a command | typed errors |
+| `resolve-storage-*` adapters | `EventStore.Backend` |
+
+The largest change is on the read side. moleculer-cqrs broadcasts events over the
+broker and only replay recovers one that was lost; here view models pull from the
+store, so `replay` is for rebuilding, not for recovery.
+
+## Limitations
+
+- **New events stay in their process.** They wake subscribers in the same process only.
+  There is no transport equivalent to the Moleculer broker, so `dispatch` is the entry
+  point to wire into your own HTTP or RPC layer.
+- **SQLite, PostgreSQL and memory only.** There are no adapters for MongoDB or MySQL.
+- **No code generator.** There is no equivalent of `cqrs generate`.
+- **No persistent snapshots.** Recent state is only kept in memory, so after a restart
+  each stream is replayed the first time it is used, at a cost that grows with its
+  length.
+- **No schema migration.** A stored event that no longer decodes fails with
+  `EventDecodeError`, so evolve event schemas compatibly.

package/dist/Aggregate.d.ts

@@ -0,0 +1,86 @@
+/**
+ * The write side of the domain: a schema of events, a projection that folds them
+ * into state, and commands that inspect that state and decide on new events.
+ *
+ * An aggregate is plain data. {@link AggregateService} gives it a store to run
+ * against, and `Fixture` runs it in tests.
+ */
+import type { DateTime, Effect, Schema } from "effect";
+export interface Tagged {
+    readonly _tag: string;
+}
+export type EventSchema<Event extends Tagged = Tagged> = Schema.Top & {
+    readonly Type: Event;
+    readonly DecodingServices: never;
+    readonly EncodingServices: never;
+};
+export type PayloadSchema = Schema.Top & {
+    readonly DecodingServices: never;
+    readonly EncodingServices: never;
+};
+/** Where an event sits in its stream and in the store. */
+export interface EventMeta {
+    readonly aggregateName: string;
+    readonly aggregateId: string;
+    readonly version: number;
+    readonly position: number;
+    readonly timestamp: DateTime.Utc;
+}
+export interface CommandContext {
+    readonly aggregateId: string;
+    readonly version: number;
+}
+/** Exhaustive by event tag, so adding an event to the schema without folding it does not compile. */
+export type Projection<State, Event extends Tagged> = {
+    readonly [Tag in Event["_tag"]]: (state: State, event: Extract<Event, {
+        readonly _tag: Tag;
+    }>, meta: EventMeta) => State;
+};
+/**
+ * Decides on the events a command produces. It may run several times when
+ * concurrent writers collide, so it should only decide and leave side effects to
+ * view models. Returning an empty array records nothing.
+ */
+export type CommandHandler<State, Payload, Event, E, R> = (state: State, payload: Payload, context: CommandContext) => Effect.Effect<Event | ReadonlyArray<Event>, E, R>;
+export interface Command<Payload extends PayloadSchema, State, Event, E, R> {
+    readonly payload: Payload;
+    readonly handler: CommandHandler<State, Payload["Type"], Event, E, R>;
+}
+export interface AnyCommand {
+    readonly payload: PayloadSchema;
+    readonly handler: CommandHandler<any, any, any, any, any>;
+}
+export interface Aggregate<Name extends string, State, Events extends EventSchema<any>, Commands extends Record<string, AnyCommand>> {
+    readonly name: Name;
+    readonly events: Events;
+    readonly initial: State;
+    readonly projection: Projection<State, Events["Type"]>;
+    readonly commands: Commands;
+    /** Returns a new aggregate that also accepts this command. */
+    command<const CommandName extends string, Payload extends PayloadSchema, E = never, R = never>(name: CommandName, options: {
+        readonly payload: Payload;
+        readonly handler: CommandHandler<State, Payload["Type"], Events["Type"], E, R>;
+    }): Aggregate<Name, State, Events, Commands & Record<CommandName, Command<Payload, State, Events["Type"], E, R>>>;
+}
+export type Any = Aggregate<string, any, EventSchema<any>, Record<string, AnyCommand>>;
+export type Name<A extends Any> = A["name"];
+export type State<A extends Any> = A["initial"];
+export type Event<A extends Any> = A["events"]["Type"];
+export type Commands<A extends Any> = A["commands"];
+export type CommandName<A extends Any> = keyof A["commands"] & string;
+export type Payload<A extends Any, K extends CommandName<A>> = A["commands"][K]["payload"]["Type"];
+export type CommandError<A extends Any, K extends CommandName<A> = CommandName<A>> = A["commands"][K] extends Command<any, any, any, infer E, any> ? E : never;
+export type Context<A extends Any> = A["commands"][CommandName<A>] extends Command<any, any, any, any, infer R> ? R : never;
+/**
+ * The state is given explicitly, `Aggregate.make<State>()({ ... })`, so that the
+ * projection's return values are checked against it rather than widened.
+ */
+export declare const make: <State>() => <const Name extends string, Events extends EventSchema<any>>(options: {
+    readonly name: Name;
+    readonly events: Events;
+    readonly initial: State;
+    readonly projection: Projection<State, Events["Type"]>;
+}) => Aggregate<Name, State, Events, {}>;
+/** Folds one event into the state. */
+export declare const evolve: <A extends Any>(aggregate: A, state: State<A>, event: Event<A>, meta: EventMeta) => State<A>;
+//# sourceMappingURL=Aggregate.d.ts.map

package/dist/Aggregate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Aggregate.d.ts","sourceRoot":"","sources":["../src/Aggregate.ts"],"names":[],"mappings":"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"}

package/dist/Aggregate.js

@@ -0,0 +1,15 @@
+const build = (definition) => ({
+    ...definition,
+    command: (name, options) => build({
+        ...definition,
+        commands: { ...definition.commands, [name]: options }
+    })
+});
+/**
+ * The state is given explicitly, `Aggregate.make<State>()({ ... })`, so that the
+ * projection's return values are checked against it rather than widened.
+ */
+export const make = () => (options) => build({ ...options, commands: {} });
+/** Folds one event into the state. */
+export const evolve = (aggregate, state, event, meta) => aggregate.projection[event._tag](state, event, meta);
+//# sourceMappingURL=Aggregate.js.map

package/dist/Aggregate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Aggregate.js","sourceRoot":"","sources":["../src/Aggregate.ts"],"names":[],"mappings":"AAkGA,MAAM,KAAK,GAAG,CAMZ,UAAqH,EAC3E,EAAE,CAAC,CAAC;IAC9C,GAAG,UAAU;IACb,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,CACzB,KAAK,CAAC;QACJ,GAAG,UAAU;QACb,QAAQ,EAAE,EAAE,GAAG,UAAU,CAAC,QAAQ,EAAE,CAAC,IAAI,CAAC,EAAE,OAAO,EAAS;KAC7D,CAAC;CACL,CAAC,CAAA;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,GAAU,EAAE,CAChC,CAA6D,OAK5D,EAAsC,EAAE,CAAC,KAAK,CAAC,EAAE,GAAG,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,CAAA;AAE7E,sCAAsC;AACtC,MAAM,CAAC,MAAM,MAAM,GAAG,CAAgB,SAAY,EAAE,KAAe,EAAE,KAAe,EAAE,IAAe,EAAY,EAAE,CAChH,SAAS,CAAC,UAA8F,CAAC,KAAK,CAAC,IAAI,CAAE,CACpH,KAAK,EACL,KAAK,EACL,IAAI,CACL,CAAA"}

package/dist/AggregateService.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Runs an aggregate against the {@link EventStore}: the `command`, `read-model`
+ * and `history` actions of moleculer-cqrs, as a typed service.
+ */
+import { type DateTime, Effect, Schema } from "effect";
+import * as Aggregate from "./Aggregate.ts";
+import { ConcurrencyConflict, EventStore, type EventStoreError, type StoredEvent } from "./EventStore.ts";
+declare const UnknownCommand_base: Schema.Class<UnknownCommand, Schema.TaggedStruct<"UnknownCommand", {
+    readonly aggregateName: Schema.String;
+    readonly type: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class UnknownCommand extends UnknownCommand_base {
+}
+declare const InvalidCommand_base: Schema.Class<InvalidCommand, Schema.TaggedStruct<"InvalidCommand", {
+    readonly aggregateName: Schema.String;
+    readonly type: Schema.String;
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class InvalidCommand extends InvalidCommand_base {
+}
+declare const EventDecodeError_base: Schema.Class<EventDecodeError, Schema.TaggedStruct<"EventDecodeError", {
+    readonly aggregateName: Schema.String;
+    readonly aggregateId: Schema.String;
+    readonly version: Schema.Int;
+    readonly type: Schema.String;
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** A stored event no longer matches the schema, which means the data needs a migration. */
+export declare class EventDecodeError extends EventDecodeError_base {
+}
+export type ReadError = EventStoreError | EventDecodeError;
+/** How a command can fail, on top of the errors its own handler declares. */
+export type CommandFailure = ConcurrencyConflict | InvalidCommand | ReadError;
+export interface CommandResult<Event> {
+    readonly aggregateName: string;
+    readonly aggregateId: string;
+    /** The stream version after the command. */
+    readonly version: number;
+    /** The store position of the last event, to pass to `ViewModels.caughtUp`. */
+    readonly position: number;
+    readonly events: ReadonlyArray<Event>;
+}
+export interface HistoryEntry<Event> {
+    readonly version: number;
+    readonly timestamp: DateTime.Utc;
+    readonly type: string;
+    readonly payload?: Event;
+}
+export interface AggregateService<A extends Aggregate.Any> {
+    readonly aggregate: A;
+    /** One typed function per command. */
+    readonly commands: {
+        readonly [K in Aggregate.CommandName<A>]: (aggregateId: string, payload: Aggregate.Payload<A, K>) => Effect.Effect<CommandResult<Aggregate.Event<A>>, Aggregate.CommandError<A, K> | CommandFailure>;
+    };
+    /** Runs a `{ aggregateId, type, payload }` envelope received as JSON from outside the process. */
+    readonly dispatch: (input: unknown) => Effect.Effect<CommandResult<Aggregate.Event<A>>, Aggregate.CommandError<A> | CommandFailure | UnknownCommand>;
+    /** Materializes the state on the fly, optionally as it was before `finishTime`. */
+    readonly readModel: (aggregateId: string, options?: {
+        readonly finishTime?: DateTime.Utc | undefined;
+    }) => Effect.Effect<Aggregate.State<A>, ReadError>;
+    /** Lists the events of one aggregate, with their decoded payload when `payload` is set. */
+    readonly history: (aggregateId: string, options?: {
+        readonly payload?: boolean | undefined;
+        readonly startTime?: DateTime.Utc | undefined;
+        readonly finishTime?: DateTime.Utc | undefined;
+    }) => Effect.Effect<ReadonlyArray<HistoryEntry<Aggregate.Event<A>>>, ReadError>;
+}
+/** Decodes a stored event with the schema of the aggregate it belongs to. */
+export declare const makeEventDecoder: <A extends Aggregate.Any>(aggregate: A) => (stored: StoredEvent) => Effect.Effect<Aggregate.Event<A>, EventDecodeError>;
+/** Encodes events into the JSON form the store keeps. */
+export declare const makeEventEncoder: <A extends Aggregate.Any>(aggregate: A) => (event: Aggregate.Event<A>) => Effect.Effect<{
+    type: any;
+    payload: Schema.Json;
+}, never, never>;
+export declare const make: <A extends Aggregate.Any>(aggregate: A, options?: {
+    /** How many times a command is re-decided after losing a race. Defaults to 5. */
+    readonly maxRetries?: number;
+    /** How many aggregates keep their state in memory between commands. Defaults to 10,000. */
+    readonly stateCacheSize?: number;
+} | undefined) => Effect.Effect<AggregateService<A>, never, EventStore | Aggregate.Context<A>>;
+export {};
+//# sourceMappingURL=AggregateService.d.ts.map

package/dist/AggregateService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AggregateService.d.ts","sourceRoot":"","sources":["../src/AggregateService.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAgB,KAAK,QAAQ,EAAE,MAAM,EAAY,MAAM,EAAqB,MAAM,QAAQ,CAAA;AACjG,OAAO,KAAK,SAAS,MAAM,gBAAgB,CAAA;AAC3C,OAAO,EACL,mBAAmB,EAEnB,UAAU,EACV,KAAK,eAAe,EACpB,KAAK,WAAW,EACjB,MAAM,iBAAiB,CAAA;;;;;AAExB,qBAAa,cAAe,SAAQ,mBAGlC;CAAG;;;;;;AAEL,qBAAa,cAAe,SAAQ,mBAIlC;CAAG;;;;;;;;AAEL,2FAA2F;AAC3F,qBAAa,gBAAiB,SAAQ,qBAMpC;CAAG;AAEL,MAAM,MAAM,SAAS,GAAG,eAAe,GAAG,gBAAgB,CAAA;AAE1D,6EAA6E;AAC7E,MAAM,MAAM,cAAc,GAAG,mBAAmB,GAAG,cAAc,GAAG,SAAS,CAAA;AAE7E,MAAM,WAAW,aAAa,CAAC,KAAK;IAClC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,4CAA4C;IAC5C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,8EAA8E;IAC9E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,KAAK,CAAC,CAAA;CACtC;AAED,MAAM,WAAW,YAAY,CAAC,KAAK;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,GAAG,CAAA;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,CAAC,EAAE,KAAK,CAAA;CACzB;AAED,MAAM,WAAW,gBAAgB,CAAC,CAAC,SAAS,SAAS,CAAC,GAAG;IACvD,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAA;IACrB,sCAAsC;IACtC,QAAQ,CAAC,QAAQ,EAAE;QACjB,QAAQ,EAAE,CAAC,IAAI,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC,GAAG,CACxC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,SAAS,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,KAC7B,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,cAAc,CAAC;KACrG,CAAA;IACD,kGAAkG;IAClG,QAAQ,CAAC,QAAQ,EAAE,CACjB,KAAK,EAAE,OAAO,KACX,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC,YAAY,CAAC,CAAC,CAAC,GAAG,cAAc,GAAG,cAAc,CAAC,CAAA;IAClH,mFAAmF;IACnF,QAAQ,CAAC,SAAS,EAAE,CAClB,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,GAAG,GAAG,SAAS,CAAA;KAAE,KACzD,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC,CAAA;IACjD,2FAA2F;IAC3F,QAAQ,CAAC,OAAO,EAAE,CAChB,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE;QACR,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;QACtC,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,CAAC,GAAG,GAAG,SAAS,CAAA;QAC7C,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,GAAG,GAAG,SAAS,CAAA;KAC/C,KACE,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,YAAY,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC,CAAA;CAC/E;AAQD,6EAA6E;AAC7E,eAAO,MAAM,gBAAgB,GAAI,CAAC,SAAS,SAAS,CAAC,GAAG,aAAa,CAAC,cAEpD,WAAW,KAAG,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,gBAAgB,CAYjF,CAAA;AAED,yDAAyD;AACzD,eAAO,MAAM,gBAAgB,GAAI,CAAC,SAAS,SAAS,CAAC,GAAG,aAAa,CAAC,aAErD,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;;aAIoC,MAAM,CAAC,IAAI;gBAEjF,CAAA;AAoED,eAAO,MAAM,IAAI,GAA+B,CAAC,SAAS,SAAS,CAAC,GAAG;IAGnE,iFAAiF;0BAC3D,MAAM;IAC5B,2FAA2F;8BACjE,MAAM;8FAsJlC,CAAA"}