@auto-engineer/message-store 1.148.0 → 1.149.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @auto-engineer/message-store@1.148.0 build /home/runner/work/auto-engineer/auto-engineer/packages/message-store
+> @auto-engineer/message-store@1.149.0 build /home/runner/work/auto-engineer/auto-engineer/packages/message-store
 > tsc && tsx ../../scripts/fix-esm-imports.ts
 
 Fixed ESM imports in dist/

package/.turbo/turbo-test.log

@@ -1,5 +1,5 @@
 
-> @auto-engineer/message-store@1.147.0 test /home/runner/work/auto-engineer/auto-engineer/packages/message-store
+> @auto-engineer/message-store@1.148.0 test /home/runner/work/auto-engineer/auto-engineer/packages/message-store
 > vitest run --reporter=dot
 
 
@@ -7,7 +7,7 @@
 
 
 No test files found, exiting with code 0
-
 include: **/*.specs.{js,ts,tsx}
+
 exclude:  **/.tmp/**, **/node_modules/**, **/dist/**, **/examples/**, **/create-auto-app/templates/**, **/*-starter/**, **/vite.config.ts
 

package/.turbo/turbo-type-check.log

@@ -1,4 +1,4 @@
 
-> @auto-engineer/message-store@1.147.0 type-check /home/runner/work/auto-engineer/auto-engineer/packages/message-store
+> @auto-engineer/message-store@1.148.0 type-check /home/runner/work/auto-engineer/auto-engineer/packages/message-store
 > tsc --noEmit
 

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @auto-engineer/message-store
 
+## 1.149.0
+
+### Minor Changes
+
+- [`e1eebbd`](https://github.com/BeOnAuto/auto-engineer/commit/e1eebbdf4f209780e790094d2e6887c4fa809f98) Thanks [@github-actions[bot]](https://github.com/github-actions%5Bbot%5D)! - - **server-generator-apollo-emmett**: add Given state ref hints to state.ts.ejs
+  - **server-generator-apollo-emmett**: context-aware nonCommandField instructions
+  - **server-generator-apollo-emmett**: add state context instruction
+  - **server-generator-apollo-emmett**: extract shared template helpers
+  - **server-generator-apollo-emmett**: filter state refs from hasGivenEvents in decide.ts.ejs
+
+### Patch Changes
+
+- [`d38c81e`](https://github.com/BeOnAuto/auto-engineer/commit/d38c81e7bb442a39626564cf4f6d8d55b60d0a38) Thanks [@SamHatoum](https://github.com/SamHatoum)! -
+
+- Updated dependencies [[`d38c81e`](https://github.com/BeOnAuto/auto-engineer/commit/d38c81e7bb442a39626564cf4f6d8d55b60d0a38), [`e1eebbd`](https://github.com/BeOnAuto/auto-engineer/commit/e1eebbdf4f209780e790094d2e6887c4fa809f98)]:
+  - @auto-engineer/message-bus@1.149.0
+
 ## 1.148.0
 
 ### Minor Changes

package/README.md

@@ -1,16 +1,17 @@
-# @auto-engineer/message-store
-
-Message store for persisting commands and events with stream-based storage and session tracking.
-
----
+# @auto-engineer/message-store — Stream-based persistence for commands and events
 
 ## Purpose
 
-Without `@auto-engineer/message-store`, you would have to implement your own stream-based message persistence, handle revision tracking, manage sessions, and implement filtering across message types.
+Without `@auto-engineer/message-store`, you would have to build your own stream-oriented message persistence with revision tracking, session management, filtering, and optimistic concurrency control.
 
-This package provides a persistence layer for CQRS/Event Sourcing architectures. It supports stream-based storage with revision tracking, session management, flexible filtering, optimistic concurrency control, and global position tracking.
+## Key Concepts
 
----
+- **Streams** — Messages are grouped by `streamId`. Each stream tracks its own revision number, incremented on every append.
+- **Global position** — Every message gets a monotonically increasing `position` across all streams, giving a total ordering of all writes.
+- **Sessions** — A session groups related messages together. Creating a session returns a `sessionId` that is stamped onto every message saved while the session is active.
+- **Optimistic concurrency** — Pass an `expectedRevision` when saving. If the stream's current revision does not match, the write is rejected.
+- **Message type inference** — The store infers whether a message is a `command` or `event` from an explicit parameter, the stream name, or the presence of a `requestId` field.
+- **Pluggable backends** — The `IMessageStore` interface allows alternate implementations. The built-in `MemoryMessageStore` stores everything in-process.
 
 ## Installation
 
@@ -25,40 +26,34 @@ import { MemoryMessageStore } from '@auto-engineer/message-store';
 
 const store = new MemoryMessageStore();
 
+// Save a command
 await store.saveMessage('user-commands', {
   type: 'CreateUser',
   data: { name: 'Alice', email: 'alice@example.com' },
   requestId: 'req-123',
 });
 
+// Read it back
 const messages = await store.getMessages('user-commands');
-console.log(messages);
-// → [{ streamId: 'user-commands', message: {...}, revision: 0n, position: 1n, ... }]
+// [{ streamId: 'user-commands', message: {...}, revision: 0n, position: 1n, ... }]
 ```
 
----
-
 ## How-to Guides
 
-### Save Messages to a Stream
+### Save multiple messages in one call
 
 ```typescript
-import { MemoryMessageStore } from '@auto-engineer/message-store';
-
-const store = new MemoryMessageStore();
-
-await store.saveMessage('orders-123', {
-  type: 'OrderPlaced',
-  data: { orderId: 'ord-001', total: 99.99 },
-});
+await store.saveMessages('order-events', [
+  { type: 'OrderPlaced', data: { orderId: 'ord-1', total: 42 } },
+  { type: 'OrderConfirmed', data: { orderId: 'ord-1' } },
+]);
 ```
 
-### Use Sessions
+### Use sessions to group related activity
 
 ```typescript
-const store = new MemoryMessageStore();
-
 const sessionId = await store.createSession();
+
 await store.saveMessage('commands', { type: 'StartProcess', data: {} });
 await store.saveMessage('events', { type: 'ProcessStarted', data: {} });
 
@@ -66,36 +61,42 @@ const sessionMessages = await store.getSessionMessages(sessionId);
 await store.endSession(sessionId);
 ```
 
-### Filter Messages
+### Filter messages
 
 ```typescript
+// Commands from the last hour with specific names
 const recentCommands = await store.getAllCommands({
-  fromTimestamp: new Date(Date.now() - 3600000),
+  fromTimestamp: new Date(Date.now() - 3_600_000),
   messageNames: ['CreateUser', 'UpdateUser'],
 });
 
-const correlatedMessages = await store.getAllMessages({
+// All messages sharing a correlation ID
+const correlated = await store.getAllMessages({
   correlationId: 'corr-456',
 });
+
+// Filter on message data fields
+const matched = await store.getAllMessages({
+  jsonFilter: { orderId: 'ord-1' },
+});
 ```
 
-### Use Optimistic Concurrency
+### Enforce optimistic concurrency
 
 ```typescript
-await store.saveMessage('orders-123', command1); // revision becomes 0
+await store.saveMessage('orders-123', command1); // revision becomes 0n
 
 try {
+  // This expects the stream to be empty (revision -1n), but it is at 0n
   await store.saveMessage('orders-123', command2, BigInt(-1));
 } catch (err) {
   // "Expected revision -1 but stream is at revision 0"
 }
 ```
 
----
-
 ## API Reference
 
-### Package Exports
+### Exports
 
 ```typescript
 import {
@@ -103,80 +104,119 @@ import {
   type IMessageStore,
   type ILocalMessageStore,
   type Message,
+  type MessageType,
   type PositionalMessage,
   type MessageFilter,
   type StreamInfo,
   type SessionInfo,
+  type MessageStoreStats,
 } from '@auto-engineer/message-store';
 ```
 
-### IMessageStore Interface
+### `IMessageStore`
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `saveMessage` | `(streamId: string, message: Message, expectedRevision?: bigint, messageType?: MessageType) => Promise<void>` | Save a single message to a stream |
+| `saveMessages` | `(streamId: string, messages: Message[], expectedRevision?: bigint, messageType?: MessageType) => Promise<void>` | Save multiple messages to a stream |
+| `getMessages` | `(streamId: string, fromRevision?: bigint, count?: number) => Promise<PositionalMessage[]>` | Read messages from a stream |
+| `getAllMessages` | `(filter?: MessageFilter, count?: number) => Promise<PositionalMessage[]>` | Read all messages across streams |
+| `getAllCommands` | `(filter?, count?) => Promise<PositionalMessage[]>` | Shorthand for `getAllMessages` with `messageType: 'command'` |
+| `getAllEvents` | `(filter?, count?) => Promise<PositionalMessage[]>` | Shorthand for `getAllMessages` with `messageType: 'event'` |
+| `getStreamInfo` | `(streamId: string) => Promise<StreamInfo \| null>` | Get metadata about a stream |
+| `getStreams` | `() => Promise<string[]>` | List all stream IDs |
+| `getSessions` | `() => Promise<SessionInfo[]>` | List all sessions |
+| `getSessionInfo` | `(sessionId: string) => Promise<SessionInfo \| null>` | Get metadata about a session |
+| `getSessionMessages` | `(sessionId: string, filter?, count?) => Promise<PositionalMessage[]>` | Get messages for a session |
+| `getStats` | `() => Promise<MessageStoreStats>` | Get aggregate statistics |
+| `dispose` | `() => Promise<void>` | Release resources |
+
+### `ILocalMessageStore` (extends `IMessageStore`)
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `reset` | `() => Promise<void>` | Clear all stored messages, sessions, and state |
+| `createSession` | `() => Promise<string>` | Start a new session, returns the session ID |
+| `endSession` | `(sessionId: string) => Promise<void>` | Mark a session as ended |
+
+### Types
 
-| Method | Description |
-|--------|-------------|
-| `saveMessage(streamId, message, expectedRevision?)` | Save a single message |
-| `saveMessages(streamId, messages, expectedRevision?)` | Save multiple messages |
-| `getMessages(streamId, fromRevision?, count?)` | Get messages from stream |
-| `getAllMessages(filter?, count?)` | Get all messages with filtering |
-| `getAllCommands(filter?, count?)` | Get all commands |
-| `getAllEvents(filter?, count?)` | Get all events |
-| `getStreamInfo(streamId)` | Get stream metadata |
-| `getStreams()` | Get all stream IDs |
-| `getSessions()` | Get all session info |
-| `getStats()` | Get storage statistics |
+```typescript
+type Message = Command | Event; // from @auto-engineer/message-bus
 
-### PositionalMessage
+type MessageType = 'command' | 'event';
 
-```typescript
 interface PositionalMessage {
   streamId: string;
   message: Message;
-  messageType: 'command' | 'event';
-  revision: bigint;
-  position: bigint;
+  messageType: MessageType;
+  revision: bigint;   // position within the stream
+  position: bigint;   // global position across all streams
   timestamp: Date;
   sessionId: string;
 }
-```
 
-### MessageFilter
-
-```typescript
 interface MessageFilter {
-  messageType?: 'command' | 'event';
+  messageType?: MessageType;
   messageNames?: string[];
   streamId?: string;
   sessionId?: string;
   correlationId?: string;
+  requestId?: string;
   fromPosition?: bigint;
   toPosition?: bigint;
   fromTimestamp?: Date;
   toTimestamp?: Date;
+  jsonFilter?: Record<string, unknown>;
+}
+
+interface StreamInfo {
+  streamId: string;
+  revision: bigint;
+  messageCount: number;
+  firstPosition: bigint;
+  lastPosition: bigint;
+  createdAt: Date;
+  lastUpdated: Date;
+}
+
+interface SessionInfo {
+  sessionId: string;
+  startedAt: Date;
+  messageCount: number;
+  commandCount: number;
+  eventCount: number;
+  lastActivity: Date;
 }
-```
 
----
+interface MessageStoreStats {
+  totalMessages: number;
+  totalCommands: number;
+  totalEvents: number;
+  totalStreams: number;
+  totalSessions: number;
+  memoryUsage?: number;
+  oldestMessage?: Date;
+  newestMessage?: Date;
+}
+```
 
 ## Architecture
 
 ```
 src/
-├── index.ts
-├── types.ts
-└── MemoryMessageStore.ts
+├── index.ts                          # Re-exports all public API
+├── interfaces/
+│   ├── IMessageStore.ts              # IMessageStore and ILocalMessageStore interfaces
+│   └── types.ts                      # Message, PositionalMessage, filter and info types
+└── memory/
+    └── MemoryMessageStore.ts         # In-memory implementation
 ```
 
-### Key Concepts
-
-- **Stream-based storage**: Messages organized by streamId
-- **Global positioning**: Monotonically increasing position across streams
-- **Session tracking**: Group related messages together
-- **Optimistic concurrency**: expectedRevision parameter
-
 ### Dependencies
 
-| Package | Usage |
-|---------|-------|
-| `@auto-engineer/message-bus` | Command and Event types |
-| `debug` | Debug logging |
-| `nanoid` | Session ID generation |
+| Package | Role |
+|---------|------|
+| `@auto-engineer/message-bus` | Provides `Command` and `Event` types that compose `Message` |
+| `debug` | Namespaced debug logging (`auto:message-store:memory`) |
+| `nanoid` | Generates unique session IDs |

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@auto-engineer/message-store",
   "type": "module",
-  "version": "1.148.0",
+  "version": "1.149.0",
   "description": "Message store for commands and events with pluggable backends",
   "main": "./dist/src/index.js",
   "types": "./dist/src/index.d.ts",
   "dependencies": {
     "debug": "^4.3.4",
     "nanoid": "^5.0.0",
-    "@auto-engineer/message-bus": "1.148.0"
+    "@auto-engineer/message-bus": "1.149.0"
   },
   "devDependencies": {
     "typescript": "^5.3.0"