effect-cqrs 0.0.0-stage → 0.2.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,327 @@
-# 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.
+
+When an event's schema changes, the stored events keep their old shape. The aggregate
+declares the older shapes and how each becomes the next, and they are upcast as they
+are read:
+
+```ts
+const Todo = Aggregate.make<TodoState>()({
+  // ...
+  versions: {
+    TodoCreated: EventVersions.from(TodoCreatedV1).next(TodoEvent.cases.TodoCreated, (v1) => ({ ...v1, dueDate: null }))
+  }
+})
+```
+
+## 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. With
+`snapshots: { every, schema, version }` it also saves states through a `KeyValueStore`
+from `effect/persistence`, so a restart replays only what came after the last one.
+
+Every event records a `correlationId` and a `causationId`. A command a view model runs
+gets the handled event as its cause, so a chain of reactions can be traced back to the
+request that started it. `Causation.withCausation` sets the ids from outside.
+
+Commands can also carry metadata, a JSON object for what the domain doesn't decide on,
+such as the software version or the user who sent them. It is recorded on every event they
+write. `Metadata.layer({ appVersion })` sets it for the whole application and
+`Metadata.withMetadata` adds to it per request.
+
+## 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.
+- `givenEvents` also takes events in an older schema version, built with
+  `Aggregate.historical(Todo, "TodoCreated", 1, { ... })`, to test upcasting.
+- `checkInvariants({ invariant })` runs random command sequences generated from the
+  payload schemas and reports the shortest one that breaks the predicate.
+
+`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`.
+- **Snapshots are opt-in.** Without `snapshots`, recent state is only kept in memory, so
+  after a restart each stream is replayed the first time it is used. A changed state
+  needs a new snapshot `version` by hand.
+- **Event upcasts are pure.** Older event shapes declared with `EventVersions` are
+  upcast on read, but an upcast can't read a service or fail with its own error.

package/dist/Aggregate.d.ts

@@ -0,0 +1,127 @@
+/**
+ * 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, type Effect, Schema } from "effect";
+import * as EventVersions from "./EventVersions.ts";
+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;
+    /** Shared by everything that follows from one original request, see `Causation`. */
+    readonly correlationId: string | null;
+    /** What directly caused the command that recorded the event. */
+    readonly causationId: string | null;
+    /** What the command carried beside its payload, such as the software version, see `Metadata`. */
+    readonly metadata: Schema.JsonObject;
+}
+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>;
+}
+/**
+ * The older shapes of some events, keyed by tag. Each history has to end in the
+ * event's current shape.
+ */
+export type Versions<Event extends Tagged> = {
+    readonly [Tag in Event["_tag"]]?: EventVersions.Any<Extract<Event, {
+        readonly _tag: Tag;
+    }>>;
+};
+export interface Aggregate<Name extends string, State, Events extends EventSchema<any>, Commands extends Record<string, AnyCommand>, V extends Versions<Events["Type"]> = {}> {
+    readonly name: Name;
+    readonly events: Events;
+    readonly initial: State;
+    readonly projection: Projection<State, Events["Type"]>;
+    readonly commands: Commands;
+    readonly versions: V;
+    /** 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>>, V>;
+}
+export type Any = Aggregate<string, any, EventSchema<any>, Record<string, AnyCommand>, any>;
+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>, const V extends Versions<Events["Type"]> = {}>(options: {
+    readonly name: Name;
+    readonly events: Events;
+    readonly initial: State;
+    readonly projection: Projection<State, Events["Type"]>;
+    /** Older shapes of events already in the store, see `EventVersions`. */
+    readonly versions?: V | undefined;
+}) => Aggregate<Name, State, Events, {}, V>;
+/** 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>;
+/** The schema version new events with this tag are written with. */
+export declare const schemaVersion: (aggregate: Any, tag: string) => number;
+/**
+ * An event as it was stored in the past, in an older version of its schema.
+ * Construct one directly to replay JSON taken from a database.
+ */
+export declare class Historical {
+    readonly type: string;
+    readonly schemaVersion: number;
+    readonly payload: Schema.Json;
+    constructor(options: {
+        readonly type: string;
+        readonly schemaVersion: number;
+        readonly payload: Schema.Json;
+    });
+}
+/**
+ * Encodes an event in an older version of its schema, as code from that time
+ * would have stored it. The value is checked against that version, so a test
+ * can't seed a shape that never existed.
+ */
+export declare const historical: <A extends Any, const Tag extends keyof A["versions"] & string, const Version extends number>(aggregate: A, tag: Tag, version: Version, value: EventVersions.SchemaAt<NonNullable<A["versions"][Tag]>, Version>["Type"]) => Historical;
+//# 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,59 @@
+/**
+ * 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 { Predicate, Schema } from "effect";
+import * as EventVersions from "./EventVersions.js";
+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, versions: options.versions ?? {}, commands: {} });
+/** Folds one event into the state. */
+export const evolve = (aggregate, state, event, meta) => aggregate.projection[event._tag](state, event, meta);
+/** The schema version new events with this tag are written with. */
+export const schemaVersion = (aggregate, tag) => EventVersions.current(aggregate.versions[tag]);
+/**
+ * An event as it was stored in the past, in an older version of its schema.
+ * Construct one directly to replay JSON taken from a database.
+ */
+export class Historical {
+    type;
+    schemaVersion;
+    payload;
+    constructor(options) {
+        this.type = options.type;
+        this.schemaVersion = options.schemaVersion;
+        this.payload = options.payload;
+    }
+}
+/**
+ * Encodes an event in an older version of its schema, as code from that time
+ * would have stored it. The value is checked against that version, so a test
+ * can't seed a shape that never existed.
+ */
+export const historical = (aggregate, tag, version, value) => {
+    const versions = aggregate.versions[tag];
+    const schema = versions?.schemas[version - 1];
+    if (schema === undefined) {
+        throw new Error(`${aggregate.name} has no version ${version} of ${tag}`);
+    }
+    const payload = Schema.encodeSync(Schema.toCodecJson(schema))(value);
+    return new Historical({
+        type: tag,
+        schemaVersion: version,
+        // Events were always stored with their tag, whatever the schema of the time said.
+        payload: Predicate.isObject(payload) ? { ...payload, _tag: tag } : payload
+    });
+};
+//# sourceMappingURL=Aggregate.js.map

package/dist/Aggregate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Aggregate.js","sourceRoot":"","sources":["../src/Aggregate.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAA8B,SAAS,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AACtE,OAAO,KAAK,aAAa,MAAM,oBAAoB,CAAA;AA2GnD,MAAM,KAAK,GAAG,CAOZ,UAGC,EAC4C,EAAE,CAAC,CAAC;IACjD,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,CAA4G,OAO3G,EAAyC,EAAE,CAC1C,KAAK,CAAC,EAAE,GAAG,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAK,EAAQ,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,CAAA;AAE9E,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;AAEH,oEAAoE;AACpE,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,SAAc,EAAE,GAAW,EAAU,EAAE,CACnE,aAAa,CAAC,OAAO,CAAE,SAAS,CAAC,QAA0D,CAAC,GAAG,CAAC,CAAC,CAAA;AAEnG;;;GAGG;AACH,MAAM,OAAO,UAAU;IACZ,IAAI,CAAQ;IACZ,aAAa,CAAQ;IACrB,OAAO,CAAa;IAC7B,YAAY,OAAiG;QAC3G,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAA;QACxB,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC,aAAa,CAAA;QAC1C,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAA;IAChC,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAKxB,SAAY,EACZ,GAAQ,EACR,OAAgB,EAChB,KAA+E,EACnE,EAAE;IACd,MAAM,QAAQ,GAAI,SAAS,CAAC,QAA0D,CAAC,GAAG,CAAC,CAAA;IAC3F,MAAM,MAAM,GAAG,QAAQ,EAAE,OAAO,CAAC,OAAO,GAAG,CAAC,CAAC,CAAA;IAC7C,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,GAAG,SAAS,CAAC,IAAI,mBAAmB,OAAO,OAAO,GAAG,EAAE,CAAC,CAAA;IAC1E,CAAC;IACD,MAAM,OAAO,GAAG,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAgB,CAAA;IACnF,OAAO,IAAI,UAAU,CAAC;QACpB,IAAI,EAAE,GAAG;QACT,aAAa,EAAE,OAAO;QACtB,kFAAkF;QAClF,OAAO,EAAE,SAAS,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,GAAI,OAAkB,EAAE,IAAI,EAAE,GAAG,EAAiB,CAAC,CAAC,CAAC,OAAO;KACtG,CAAC,CAAA;AACJ,CAAC,CAAA"}