@eventengine/store 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+import { AppendOnlyStore } from '@eventengine/ports';
+import { Level, Handler } from '@eventengine/core';
+
+interface StoredEvent {
+    name: string;
+    occurredAt: string;
+    payload: unknown;
+    type?: string;
+    level?: Level;
+    version?: number;
+    metadata?: Record<string, unknown>;
+    idempotencyKey?: string;
+    aggregateType?: string;
+    aggregateId?: string;
+    aggregateVersion?: number;
+}
+type Projection = (event: StoredEvent) => void | Promise<void>;
+type ProjectionErrorHandler = (error: unknown, event: StoredEvent) => void;
+declare class EventStore {
+    private readonly log;
+    private readonly onProjectionError;
+    private readonly projections;
+    constructor(log: AppendOnlyStore<StoredEvent>, onProjectionError?: ProjectionErrorHandler);
+    subscribe(projection: Projection): void;
+    append(event: StoredEvent): Promise<void>;
+    recorder(): Handler;
+    projectionDispatcher(): Handler;
+    replay(projection: Projection): Promise<void>;
+    all(): Promise<StoredEvent[]>;
+}
+
+export { EventStore, type Projection, type ProjectionErrorHandler, type StoredEvent };

package/dist/index.js

@@ -0,0 +1,46 @@
+// src/event-store.ts
+var EventStore = class {
+  constructor(log, onProjectionError = () => void 0) {
+    this.log = log;
+    this.onProjectionError = onProjectionError;
+  }
+  log;
+  onProjectionError;
+  projections = [];
+  subscribe(projection) {
+    this.projections.push(projection);
+  }
+  async append(event) {
+    await this.log.append(event);
+  }
+  recorder() {
+    return (event) => this.append(event);
+  }
+  projectionDispatcher() {
+    return async (event) => {
+      for (const projection of this.projections) {
+        try {
+          await projection(event);
+        } catch (error) {
+          this.onProjectionError(error, event);
+        }
+      }
+    };
+  }
+  async replay(projection) {
+    for (const event of await this.all()) await projection(event);
+  }
+  async all() {
+    const events = [];
+    let cursor = null;
+    do {
+      const page = await this.log.readFrom(cursor, 100);
+      events.push(...page.rows);
+      cursor = page.next;
+    } while (cursor !== null);
+    return events;
+  }
+};
+export {
+  EventStore
+};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@eventengine/store",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "event-engine store: the permanent event record, projections, and replay built on @eventengine/core.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DYB-Development/event-engine.git",
+    "directory": "store"
+  },
+  "homepage": "https://github.com/DYB-Development/event-engine/tree/main/store#readme",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "the-local/agents"
+  ],
+  "dependencies": {
+    "@eventengine/core": "0.1.0",
+    "@eventengine/ports": "0.1.0"
+  },
+  "devDependencies": {
+    "zod": "^3.24.1"
+  },
+  "the-local": {
+    "prefix": "store",
+    "scope": "the permanent event record — recording, projections, and replay on core",
+    "agentsDir": "the-local/agents"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "build:locals": "the-local build ."
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts"
+}

package/the-local/agents/store-develop.md

@@ -0,0 +1,50 @@
+---
+name: store-develop
+description: Use PROACTIVELY for work involving @eventengine/store — recording, projections, or replay. MUST BE USED instead of guessing store's API.
+tools: Read, Write, Edit, Grep
+---
+
+You do @eventengine/store work following the reference exactly: wire the recorder and projectionDispatcher into core's EventEngine, record via emit (not by hand), register live projections with subscribe, and rebuild state with replay. You know store builds on @eventengine/core and defer event definition to it. You do not invent API the reference does not list.
+
+## @eventengine/store
+
+The permanent, queryable event record — plus the projections and replay built on
+it. It is **built on @eventengine/core**: it plugs into core's `EventEngine` as
+two handlers (mirroring the Ruby gem's `Recorder` + `ProjectionDispatcher`) and
+records the same Event envelope core defines. It also uses an append-only store
+from @eventengine/ports.
+
+### Wire it in
+
+```ts
+const store = new EventStore(new InMemoryAppendOnlyStore(), onProjectionError);
+engine.registerHandler(store.recorder(), "all");            // records every dispatched event
+engine.registerHandler(store.projectionDispatcher(), "all"); // runs projections
+```
+
+Recording happens **via dispatch**, not a manual call — `emit` an event and the
+recorder appends it. The recorder runs before the projection dispatcher, so an
+event is durable before any projection sees it.
+
+### API
+
+- `recorder()` → a `Handler` that appends the event to the log.
+- `projectionDispatcher()` → a `Handler` that runs every subscribed projection,
+  **isolated**: if one throws, the rest still run and the error goes to the
+  constructor's `onProjectionError`. The append is never undone.
+- `subscribe(projection)` — register a projection, any
+  `(event) => void | Promise<void>`.
+- `append(event)` — record directly (used by the recorder; handy in tests).
+- `all()` — every recorded event, paged through the cursor.
+- `replay(projection)` — walk the whole log through a projection to rebuild
+  state (event sourcing). Unlike `subscribe`, replay **fails fast** — a rebuild
+  that hits a bad event should surface, not skip.
+
+### Conventions
+
+- Record through the engine: register `recorder()` and `projectionDispatcher()`
+  and `emit`; don't append by hand outside tests.
+- Use `subscribe` for live projections (isolated) and `replay` for rebuilds
+  (fail-fast).
+- The store holds core's Event envelope verbatim; it doesn't redefine events —
+  that's @eventengine/core's job.

package/the-local/agents/store-info.md

@@ -0,0 +1,50 @@
+---
+name: store-info
+description: Use to learn @eventengine/store — the event record, recorder and projection-dispatcher handlers, subscribe/replay, and how it builds on core.
+tools: Read
+---
+
+You explain @eventengine/store, answering only from the reference: EventStore plugs into core's EventEngine as a recorder and a projection-dispatcher, records the Event envelope, runs isolated live projections via subscribe, and rebuilds state via fail-fast replay. You make no changes.
+
+## @eventengine/store
+
+The permanent, queryable event record — plus the projections and replay built on
+it. It is **built on @eventengine/core**: it plugs into core's `EventEngine` as
+two handlers (mirroring the Ruby gem's `Recorder` + `ProjectionDispatcher`) and
+records the same Event envelope core defines. It also uses an append-only store
+from @eventengine/ports.
+
+### Wire it in
+
+```ts
+const store = new EventStore(new InMemoryAppendOnlyStore(), onProjectionError);
+engine.registerHandler(store.recorder(), "all");            // records every dispatched event
+engine.registerHandler(store.projectionDispatcher(), "all"); // runs projections
+```
+
+Recording happens **via dispatch**, not a manual call — `emit` an event and the
+recorder appends it. The recorder runs before the projection dispatcher, so an
+event is durable before any projection sees it.
+
+### API
+
+- `recorder()` → a `Handler` that appends the event to the log.
+- `projectionDispatcher()` → a `Handler` that runs every subscribed projection,
+  **isolated**: if one throws, the rest still run and the error goes to the
+  constructor's `onProjectionError`. The append is never undone.
+- `subscribe(projection)` — register a projection, any
+  `(event) => void | Promise<void>`.
+- `append(event)` — record directly (used by the recorder; handy in tests).
+- `all()` — every recorded event, paged through the cursor.
+- `replay(projection)` — walk the whole log through a projection to rebuild
+  state (event sourcing). Unlike `subscribe`, replay **fails fast** — a rebuild
+  that hits a bad event should surface, not skip.
+
+### Conventions
+
+- Record through the engine: register `recorder()` and `projectionDispatcher()`
+  and `emit`; don't append by hand outside tests.
+- Use `subscribe` for live projections (isolated) and `replay` for rebuilds
+  (fail-fast).
+- The store holds core's Event envelope verbatim; it doesn't redefine events —
+  that's @eventengine/core's job.