Emmett

https://event-driven-io.github.io/emmett/
Admin
Emmett simplifies event sourcing development for event-driven applications by reducing boilerplate,...
Tokens:86,030
Snippets:928
Trust Score:8.3
Update:1 month ago
Show doc for...
Tokens:
Raw
### Configure package.json

Source: https://event-driven-io.github.io/emmett/quick-intro.html

Example configuration for package.json including the start script and dependencies.

```json
{
  "name": "emmett-quick-intro",
  "version": "1.0.0",
  "type": "module",
  "description": "",
  "scripts": {
    "start": "tsx ./index.ts"
  },
  "author": "",
  "license": "ISC",
  "devDependencies": {
    "@types/node": "^25.0.10",
    "tsx": "^4.19.3",
    "typescript": "^5.8.2"
  },
  "dependencies": {
    "@event-driven-io/emmett": "^0.43.0-beta.40"
  }
}
```

--------------------------------

### Run Express + PostgreSQL Sample

Source: https://event-driven-io.github.io/emmett/samples

Commands to clone the repository, start the database container, and install dependencies for the Express and PostgreSQL sample.

```bash
# Clone the repository
git clone https://github.com/event-driven-io/emmett.git
cd emmett/samples/webApi/expressjs-with-postgresql

# Start PostgreSQL
docker-compose up -d

# Install dependencies
npm install
```

--------------------------------

### Setup API with EventStoreDB

Source: https://event-driven-io.github.io/emmett/resources/packages.html

Install core, EventStoreDB, and Fastify packages along with testcontainers.

```bash
npm install @event-driven-io/emmett \
            @event-driven-io/emmett-esdb \
            @event-driven-io/emmett-fastify

npm install -D @event-driven-io/emmett-testcontainers
```

--------------------------------

### Setup API with PostgreSQL

Source: https://event-driven-io.github.io/emmett/resources/packages.html

Install core, PostgreSQL, and Express.js packages along with testcontainers.

```bash
npm install @event-driven-io/emmett \
            @event-driven-io/emmett-postgresql \
            @event-driven-io/emmett-expressjs

npm install -D @event-driven-io/emmett-testcontainers
```

--------------------------------

### Setup API with MongoDB

Source: https://event-driven-io.github.io/emmett/resources/packages.html

Install core, MongoDB, and Express.js packages along with testcontainers.

```bash
npm install @event-driven-io/emmett \
            @event-driven-io/emmett-mongodb \
            @event-driven-io/emmett-expressjs

npm install -D @event-driven-io/emmett-testcontainers
```

--------------------------------

### Consumer Usage Example

Source: https://event-driven-io.github.io/emmett/api-reference/eventstore.html

Demonstrates how to initialize and start a consumer for processing events.

```typescript
const consumer = eventStore.consumer<ShoppingCartEvent>();

consumer.projector({ processorId: 'cart-summary', projection });

await consumer.start();
```

--------------------------------

### Install peer dependencies

Source: https://event-driven-io.github.io/emmett/event-stores/esdb.html

Install the necessary peer dependencies for the adapter.

```bash
npm install @event-driven-io/emmett @eventstore/db-client
```

--------------------------------

### Install Pongo

Source: https://event-driven-io.github.io/emmett/resources/packages.html

Install Pongo for PostgreSQL as a Document Database with MongoDB-like API.

```bash
npm install @event-driven-io/pongo
```

--------------------------------

### Run application

Source: https://event-driven-io.github.io/emmett/quick-intro.html

Execute the application using the configured start script.

```sh
npm run start
```

--------------------------------

### Install Fastify Integration

Source: https://event-driven-io.github.io/emmett/resources/packages.html

Install the Fastify integration package with plugin architecture support.

```bash
npm install @event-driven-io/emmett-fastify
```

--------------------------------

### Initialize and start Podman machine on macOS

Source: https://event-driven-io.github.io/emmett/resources/faq.html

Commands to initialize, start, and configure the DOCKER_HOST for Podman machine.

```bash
podman machine init
podman machine start
export DOCKER_HOST="unix://$HOME/.local/share/containers/podman/machine/podman.sock"
```

--------------------------------

### Install Hono Integration

Source: https://event-driven-io.github.io/emmett/resources/packages.html

Install the Hono integration package with Fetch-native response helpers.

```bash
npm install @event-driven-io/emmett-honojs
```

--------------------------------

### Run Express EventStoreDB Sample

Source: https://event-driven-io.github.io/emmett/samples

Commands to initialize and start the Express with EventStoreDB sample.

```bash
cd emmett/samples/webApi/expressjs-with-esdb

# Start EventStoreDB
docker-compose up -d

# Install and run
npm install
npm run start
```

--------------------------------

### Run Express MongoDB Sample

Source: https://event-driven-io.github.io/emmett/samples

Commands to initialize and start the Express with MongoDB sample.

```bash
cd emmett/samples/webApi/expressjs-with-mongodb

# Start MongoDB
docker-compose up -d

# Install and run
npm install
npm run start
```

--------------------------------

### Run Application and Tests

Source: https://event-driven-io.github.io/emmett/samples

Standard commands for starting the application and executing the test suite.

```bash
npm run start
```

```bash
# Run all tests
npm run test

# Or use the HTTP file for manual testing
# Open .http file in VS Code with REST Client extension
```

--------------------------------

### Install Emmett EventStoreDB adapter

Source: https://event-driven-io.github.io/emmett/event-stores/esdb.html

Install the required package for EventStoreDB integration.

```bash
npm install @event-driven-io/emmett-esdb
```

--------------------------------

### Install Emmett Shims

Source: https://event-driven-io.github.io/emmett/resources/packages.html

Install polyfills for environments lacking native support.

```bash
npm install @event-driven-io/emmett-shims
```

--------------------------------

### startAPI(application, options?)

Source: https://event-driven-io.github.io/emmett/frameworks/honojs.html

Starts the Hono application using the @hono/node-server.

```APIDOC
## startAPI(application, options?)

### Description
Starts the Hono application through @hono/node-server. If options are omitted, the server defaults to port 3000.

### Parameters
- **application** (Hono) - Required - The Hono application to start.
- **options** (ApplicationOptions) - Optional - Configuration options for the API server.
```

--------------------------------

### Install Express.js Integration

Source: https://event-driven-io.github.io/emmett/resources/packages.html

Install the Express.js integration package including testing utilities.

```bash
npm install @event-driven-io/emmett-expressjs
```

--------------------------------

### Install Core Emmett Package

Source: https://event-driven-io.github.io/emmett/resources/packages.html

Install the foundation of the Emmett ecosystem, required for all projects.

```bash
npm install @event-driven-io/emmett
```

--------------------------------

### Run Hono PostgreSQL Sample

Source: https://event-driven-io.github.io/emmett/samples

Commands to initialize and start the Hono with PostgreSQL sample using Docker Compose.

```bash
cd emmett/samples/webApi/honojs-with-postgresql

docker compose up -d
npm install
npm run start
```

--------------------------------

### Define example commands

Source: https://event-driven-io.github.io/emmett/quick-intro.html

Sample command objects for adding and removing items.

```typescript
const addPizza: AddItem = {
  type: 'AddItem',
  data: {
    name: 'Pizza',
  },
};

const addIceCream: AddItem = {
  type: 'AddItem',
  data: {
    name: 'Ice Cream',
  },
};

const removePizza: RemoveItem = {
  type: 'RemoveItem',
  data: {
    name: 'Pizza',
  },
};

const removeIceCream: RemoveItem = {
  type: 'RemoveItem',
  data: {
    name: 'Ice Cream',
  },
};
```

--------------------------------

### Install TypeScript dependencies

Source: https://event-driven-io.github.io/emmett/quick-intro.html

Install TypeScript and tsx as development dependencies.

```sh
npm install typescript @types/node tsx --save-dev
```

--------------------------------

### Isolated Test Database Setup for Event Store

Source: https://event-driven-io.github.io/emmett/event-stores/sqlite.html

Set up an isolated, in-memory SQLite database for each test using `getSQLiteEventStore(':memory:')`. This ensures tests do not interfere with each other and start with a clean state.

```typescript
import { v4 as uuid } from 'uuid';

describe('Shopping Cart', () => {
  let eventStore: SQLiteEventStore;

  beforeEach(() => {
    // Each test gets fresh in-memory database
    eventStore = getSQLiteEventStore(':memory:');
  });

  it('adds products', async () => {
    await eventStore.appendToStream('cart-1', [
      {
        type: 'ProductItemAdded',
        data: { productId: 'p1', quantity: 1, price: 10 },
      },
    ]);

    const { events } = await eventStore.readStream('cart-1');
    expect(events).toHaveLength(1);
  });
});
```

--------------------------------

### Install TestContainers Utility

Source: https://event-driven-io.github.io/emmett/resources/packages.html

Install the TestContainers integration for E2E testing as a development dependency.

```bash
npm install -D @event-driven-io/emmett-testcontainers
```

--------------------------------

### Install Peer Dependencies

Source: https://event-driven-io.github.io/emmett/event-stores/postgresql.html

Install the necessary peer dependencies for Emmett and Pongo.

```bash
npm install @event-driven-io/emmett @event-driven-io/pongo
```

--------------------------------

### Install Peer Dependencies

Source: https://event-driven-io.github.io/emmett/event-stores/mongodb.html

Install the necessary peer dependencies for the MongoDB event store.

```bash
npm install @event-driven-io/emmett mongodb
```

--------------------------------

### Quick Setup: EventStoreDB Event Store

Source: https://event-driven-io.github.io/emmett/event-stores

Initializes the EventStoreDB event store using the EventStoreDBClient. Requires the EventStoreDB server to be running and accessible.

```typescript
import { getEventStoreDBEventStore } from '@event-driven-io/emmett-esdb';
import { EventStoreDBClient } from '@eventstore/db-client';

const client = EventStoreDBClient.connectionString(
  'esdb://localhost:2113?tls=false',
);
const eventStore = getEventStoreDBEventStore(client);
```

--------------------------------

### Installing PostgreSQL TestContainers

Source: https://event-driven-io.github.io/emmett/getting-started.html

Install the PostgreSQL test container package using various package managers.

```shell
$ npm add @testcontainers/postgresql
```

```shell
$ pnpm add @testcontainers/postgresql
```

```shell
$ yarn add @testcontainers/postgresql
```

```shell
$ bun add @testcontainers/postgresql
```

--------------------------------

### Install Emmett Fastify Package

Source: https://event-driven-io.github.io/emmett/frameworks/fastify.html

Install the main package for Emmett's Fastify integration.

```bash
npm install @event-driven-io/emmett-fastify
```

--------------------------------

### Initialize EventStoreDB Event Store

Source: https://event-driven-io.github.io/emmett/api-reference/eventstore.html

Setup for the EventStoreDB implementation.

```typescript
import { getEventStoreDBEventStore } from '@event-driven-io/emmett-esdb';

const eventStore = getEventStoreDBEventStore(client);
```

--------------------------------

### Configure event store options for various backends

Source: https://event-driven-io.github.io/emmett/resources/faq.html

Examples for initializing PostgreSQL, EventStoreDB, MongoDB, and SQLite event stores with projections.

```typescript
// PostgreSQL
const pgStore = getPostgreSQLEventStore(connectionString, {
  schema: 'events',
  projections: [myProjection],
});

// EventStoreDB
const esdbStore = getEventStoreDBEventStore(client, {
  projections: [myProjection],
});

// MongoDB
const mongoStore = getMongoDBEventStore({
  client: mongoClient,
  database: 'myapp',
  projections: [myProjection],
});

// SQLite
const sqliteStore = getSQLiteEventStore({
  fileName: './events.db', // or ':memory:' for in-memory
  projections: [myProjection],
});
```

--------------------------------

### Initialize PostgreSQL Event Store

Source: https://event-driven-io.github.io/emmett/api-reference/eventstore.html

Setup for the PostgreSQL event store implementation.

```typescript
import { getPostgreSQLEventStore } from '@event-driven-io/emmett-postgresql';

const eventStore = getPostgreSQLEventStore(connectionString);
```

--------------------------------

### Complete Emmett Fastify Example with PostgreSQL

Source: https://event-driven-io.github.io/emmett/frameworks/fastify.html

A full example demonstrating Emmett's Fastify integration with PostgreSQL for event storage, including defining a decider, creating an event store, and setting up API routes.

```typescript
import { startAPI, getFastifyApp } from '@event-driven-io/emmett-fastify';
import { getPostgreSQLEventStore } from '@event-driven-io/emmett-postgresql';
import { CommandHandler } from '@event-driven-io/emmett';

// Define your decider
const shoppingCartDecider = {
  decide,
  evolve,
  initialState,
  mapToStreamId: (id: string) => `shopping_cart-${id}`,
};

// Create event store
const eventStore = getPostgreSQLEventStore(process.env.DATABASE_URL!);

// Define API
const shoppingCartApi =
  (eventStore: EventStore) => async (fastify: FastifyInstance) => {
    const handle = CommandHandler(shoppingCartDecider, eventStore);

    fastify.post<{ 
      Params: { cartId: string };
      Body: { productId: string; quantity: number };
    }>('/carts/:cartId/items', async (request, reply) => {
      const { cartId } = request.params;
      const { productId, quantity } = request.body;

      const price = await getPriceFromCatalog(productId);

      const result = await handle(cartId, {
        type: 'AddProductItem',
        data: { productId, quantity, price },
      });

      return reply
        .header('ETag', `"${result.nextExpectedStreamVersion}" `)
        .status(200)
        .send({ added: true });
    });
  };

// Start server
const app = getFastifyApp({
  apis: [shoppingCartApi(eventStore)],
});

await startAPI(app, { port: 3000 });
```

--------------------------------

### Install In-Memory Event Store

Source: https://event-driven-io.github.io/emmett/event-stores

The in-memory event store is included in the core package and does not require a separate installation. It's suitable for testing purposes.

```bash
# Included in core package
npm install @event-driven-io/emmett
```

--------------------------------

### Install PostgreSQL Event Store

Source: https://event-driven-io.github.io/emmett/event-stores

Installs the PostgreSQL event store package using npm. This is suitable for production applications requiring full ACID compliance.

```bash
npm install @event-driven-io/emmett-postgresql
```

--------------------------------

### Quick Setup: PostgreSQL Event Store

Source: https://event-driven-io.github.io/emmett/event-stores

Initializes the PostgreSQL event store using a connection string. Ensure your PostgreSQL server is running and accessible.

```typescript
import { getPostgreSQLEventStore } from '@event-driven-io/emmett-postgresql';

const eventStore = getPostgreSQLEventStore(
  'postgresql://user:password@localhost:5432/mydb',
);
```

--------------------------------

### Quick Setup: MongoDB Event Store

Source: https://event-driven-io.github.io/emmett/event-stores

Initializes the MongoDB event store with connection details and a database name. The MongoDB server must be running.

```typescript
import { getMongoDBEventStore } from '@event-driven-io/emmett-mongodb';

const eventStore = getMongoDBEventStore({
  connectionString: 'mongodb://localhost:27017',
  database: 'events',
});
```

--------------------------------

### Initialize Express.js application with Emmett

Source: https://event-driven-io.github.io/emmett/getting-started.html

Example of bootstrapping an Express application using Emmett's getApplication and startAPI helpers.

```ts
import { getInMemoryEventStore } from '@event-driven-io/emmett';
import { getApplication, startAPI } from '@event-driven-io/emmett-expressjs';
import type { Application } from 'express';
import type { Server } from 'http';

const eventStore = getInMemoryEventStore();

const shoppingCarts = shoppingCartApi(
  eventStore,
  getUnitPrice,
  () => new Date(),
);

const application: Application = getApplication({
  apis: [shoppingCarts],
});

const server: Server = startAPI(application);
```

--------------------------------

### Setup with Existing MongoClient

Source: https://event-driven-io.github.io/emmett/event-stores/mongodb.html

Initialize the MongoDB event store using an existing MongoClient instance.

```typescript
import { MongoClient } from 'mongodb';
import { getMongoDBEventStore } from '@event-driven-io/emmett-mongodb';

const client = new MongoClient('mongodb://localhost:27017');
await client.connect();

const eventStore = getMongoDBEventStore({
  client,
  database: 'events',
});
```

--------------------------------

### Install Emmett packages

Source: https://event-driven-io.github.io/emmett/resources/faq.html

Install the core Emmett package along with specific event store adapters, web framework integrations, or testing utilities.

```bash
# Core package (required)
npm install @event-driven-io/emmett

# Choose your event store
npm install @event-driven-io/emmett-postgresql  # PostgreSQL
npm install @event-driven-io/emmett-esdb        # EventStoreDB
npm install @event-driven-io/emmett-mongodb     # MongoDB
npm install @event-driven-io/emmett-sqlite      # SQLite

# Optional: Web framework integration
npm install @event-driven-io/emmett-expressjs   # Express.js
npm install @event-driven-io/emmett-fastify     # Fastify

# Optional: Testing utilities
npm install @event-driven-io/emmett-testcontainers
```

--------------------------------

### Install EventStoreDB Event Store

Source: https://event-driven-io.github.io/emmett/event-stores

Installs the EventStoreDB event store package using npm. This is ideal for native event sourcing scenarios and offers cluster scaling.

```bash
npm install @event-driven-io/emmett-esdb
```

--------------------------------

### Install Peer Dependencies

Source: https://event-driven-io.github.io/emmett/event-stores/sqlite.html

Install necessary peer dependencies for the SQLite event store, including Emmett and better-sqlite3.

```bash
npm install @event-driven-io/emmett better-sqlite3
npm install -D @types/better-sqlite3
```

--------------------------------

### Clone and Install Emmett Dependencies

Source: https://event-driven-io.github.io/emmett/resources/contributing.html

Clone the Emmett repository and install project dependencies using npm.

```bash
git clone https://github.com/event-driven-io/emmett.git
cd emmett

npm install

npm run build

npm run test
```

--------------------------------

### Quick Setup: In-Memory Event Store

Source: https://event-driven-io.github.io/emmett/event-stores

Initializes the in-memory event store. This is a simple, non-persistent store suitable for testing and development.

```typescript
import { getInMemoryEventStore } from '@event-driven-io/emmett';

const eventStore = getInMemoryEventStore();
```

--------------------------------

### Run Emmett Documentation Locally

Source: https://event-driven-io.github.io/emmett/resources/contributing.html

Commands to install dependencies and run the documentation development server locally.

```bash
cd src/docs
npm install
npm run dev
```

--------------------------------

### Enable Podman socket on Linux

Source: https://event-driven-io.github.io/emmett/resources/faq.html

Command to enable and start the Podman socket for user-level access.

```bash
systemctl --user enable --now podman.socket
```

--------------------------------

### Install SQLite Event Store

Source: https://event-driven-io.github.io/emmett/event-stores

Installs the SQLite event store package using npm. This is recommended for development and embedded applications, providing full ACID compliance on a single node.

```bash
npm install @event-driven-io/emmett-sqlite
```

--------------------------------

### Start a new Express API

Source: https://event-driven-io.github.io/emmett/frameworks/expressjs.html

Use getApplication to initialize a new Express application with default middleware and route registration.

```typescript
const application = getApplication({
  apis: [
    (router) => {
      router.post('/echo', (request, response) => {
        const body: unknown = request.body;
        response.status(200).json({ body });
      });
    },
  ],
});
```

--------------------------------

### Install Emmett PostgreSQL Package

Source: https://event-driven-io.github.io/emmett/getting-started.html

Commands to install the PostgreSQL adapter for Emmett using various package managers.

```sh
$ npm add @event-driven-io/emmett-postgresql
```

```sh
$ pnpm add @event-driven-io/emmett-postgresql
```

```sh
$ yarn add @event-driven-io/emmett-postgresql
```

```sh
$ bun add @event-driven-io/emmett-postgresql
```

--------------------------------

### Install MongoDB Event Store

Source: https://event-driven-io.github.io/emmett/event-stores

Installs the MongoDB event store package using npm. This option is best for document-centric applications and scales horizontally.

```bash
npm install @event-driven-io/emmett-mongodb
```

--------------------------------

### Initialize and Start an Async Consumer

Source: https://event-driven-io.github.io/emmett/event-stores/postgresql.html

Create a consumer from the event store to register projectors or reactors and wait for processing to catch up.

```ts
const consumer = eventStore.consumer<ShoppingCartEvent>();

consumer.projector({
  processorId: 'shopping-carts-summary',
  projection: shoppingCartsSummaryProjection,
});

const running = consumer.start();
await consumer.whenCaughtUp();
```

--------------------------------

### Manual API Testing with HTTP Files

Source: https://event-driven-io.github.io/emmett/samples

Example requests for testing the shopping cart API endpoints.

```http
### Add product item
POST http://localhost:3000/clients/client-1/shopping-carts/cart-1/product-items
Content-Type: application/json

{
  "productId": "shoes-123",
  "quantity": 2
}

### Get shopping cart
GET http://localhost:3000/clients/client-1/shopping-carts/cart-1

### Confirm shopping cart
POST http://localhost:3000/clients/client-1/shopping-carts/cart-1/confirm
```

--------------------------------

### Build and Run Emmett Application with Docker Compose

Source: https://event-driven-io.github.io/emmett/samples

Use these commands to build the application container and start the service using the specified profile.

```bash
docker-compose --profile app build
```

```bash
docker-compose --profile app up
```

--------------------------------

### Basic Fastify API Setup with Emmett

Source: https://event-driven-io.github.io/emmett/frameworks/fastify.html

Set up a basic Fastify application using Emmett, integrating a shopping cart API with an in-memory event store.

```typescript
import { startAPI, getFastifyApp } from '@event-driven-io/emmett-fastify';
import { getInMemoryEventStore } from '@event-driven-io/emmett';

const eventStore = getInMemoryEventStore();

const app = getFastifyApp({
  apis: [shoppingCartApi(eventStore)],
});

await startAPI(app, { port: 3000 });
```

--------------------------------

### Generic Response Handling

Source: https://event-driven-io.github.io/emmett/getting-started.html

A basic example of returning a response using the setResponse helper.

```typescript
    return setResponse(response);
  };
```
```

--------------------------------

### Create project directory

Source: https://event-driven-io.github.io/emmett/quick-intro.html

Initialize the project folder and navigate into it.

```sh
mkdir emmett-quick-intro
cd emmett-quick-intro
```

--------------------------------

### Define Initial State

Source: https://event-driven-io.github.io/emmett/getting-started.html

Provides the starting structure for the shopping cart entity.

```typescript
export const initialState = (): ShoppingCart => {
  return {
    status: 'Empty',
  };
};
```

--------------------------------

### Install Emmett Express.js package

Source: https://event-driven-io.github.io/emmett/getting-started.html

Commands to add the @event-driven-io/emmett-expressjs package using various package managers.

```sh
$ npm add @event-driven-io/emmett-expressjs
```

```sh
$ pnpm add @event-driven-io/emmett-expressjs
```

```sh
$ yarn add @event-driven-io/emmett-expressjs
```

```sh
$ bun add @event-driven-io/emmett-expressjs
```

--------------------------------

### Start PostgreSQL container for E2E testing

Source: https://event-driven-io.github.io/emmett/guides/testing.html

Configures a PostgreSQL container using TestContainers to run end-to-end tests against a real database instance.

```typescript
import {
  getPostgreSQLEventStore,
  type PostgresEventStore,
} from '@event-driven-io/emmett-postgresql';
import type { StartedPostgreSqlContainer } from '@testcontainers/postgresql';
import { PostgreSqlContainer } from '@testcontainers/postgresql';

void describe('ShoppingCart E2E', () => {
  let postgreSQLContainer: StartedPostgreSqlContainer;
  let eventStore: PostgresEventStore;

  // Set up a container and event store before all tests
  beforeAll(async () => {
    postgreSQLContainer = await new PostgreSqlContainer(
      'postgres:18.1',
    ).start();
    eventStore = getPostgreSQLEventStore(
      postgreSQLContainer.getConnectionUri(),
    );
  });

  // Close PostgreSQL connection and stop container once we finished testing
  afterAll(async () => {
    await eventStore.close();
    return postgreSQLContainer.stop();
  });
  // (...) Tests will go here
});
```

--------------------------------

### Open Shopping Cart Endpoint

Source: https://event-driven-io.github.io/emmett/getting-started.html

An advanced endpoint example showing how to handle the OpenShoppingCart command with explicit stream version expectations.

```typescript
router.post(
  '/clients/:clientId/shopping-carts/',
  on(async (request: Request) => {
    const clientId = assertNotEmptyString(request.params.clientId);
    const shoppingCartId = clientId;

    const result = await handle(
      eventStore,
      shoppingCartId,
      {
        type: 'OpenShoppingCart',
        data: { clientId, shoppingCartId, now: new Date() },
      },
      { expectedStreamVersion: STREAM_DOES_NOT_EXIST },
    );

    return Created({
      createdId: shoppingCartId,
      eTag: toWeakETag(result.nextExpectedStreamVersion),
    });
  }),
);
```

--------------------------------

### Configure PostgreSQL Event Store

Source: https://event-driven-io.github.io/emmett/getting-started.html

Update the application setup to use PostgreSQL instead of the in-memory store by providing a connection string.

```typescript
import { getPostgreSQLEventStore } from '@event-driven-io/emmett-postgresql';

const connectionString =
  process.env.POSTGRESQL_CONNECTION_STRING ??
  'postgresql://localhost:5432/postgres';

const eventStore = getPostgreSQLEventStore(connectionString);

const shoppingCarts = shoppingCartApi(
  eventStore,
  getUnitPrice,
  () => new Date(),
);
```

--------------------------------

### Inject Pongo into application

Source: https://event-driven-io.github.io/emmett/getting-started.html

Configure the Pongo client and inject it into the application setup alongside the event store.

```typescript
import { pongoClient } from '@event-driven-io/pongo';

const connectionString =
  process.env.POSTGRESQL_CONNECTION_STRING ??
  'postgresql://localhost:5432/postgres';

const pongo = pongoClient(connectionString);

const eventStore = getPostgreSQLEventStore(connectionString, {
  projections: projections.inline([
    shoppingCartSummaryProjection,
    clientShoppingSummaryProjection,
  ]),
});

const application = getApplication({
  apis: [
    shoppingCartApi(
      eventStore,
      pongo, // 👈
      getUnitPrice,
    ),
  ],
});
```

--------------------------------

### Complete ShoppingCart Test Suite

Source: https://event-driven-io.github.io/emmett/getting-started.html

A full example of a test suite for the ShoppingCart module using Emmett's testing utilities.

```typescript
import { getInMemoryEventStore } from '@event-driven-io/emmett';
import {
  ApiSpecification,
  existingStream,
  expectError,
  expectNewEvents,
  expectResponse,
  getApplication,
} from '@event-driven-io/emmett-expressjs';
import { randomUUID } from 'node:crypto';

void describe('ShoppingCart', () => {
  let clientId: string;
  let shoppingCartId: string;

  beforeEach(() => {
    clientId = randomUUID();
    shoppingCartId = `shopping_cart:${clientId}:current`;
  });

  void describe('When empty', () => {
    void it('should add product item', () => {
      return given()
        .when((request) =>
          request
            .post(`/clients/${clientId}/shopping-carts/current/product-items`)
            .send(productItem),
        )
        .then([
          expectNewEvents(shoppingCartId, [
            {
              type: 'ProductItemAddedToShoppingCart',
              data: {
                shoppingCartId,
                productItem,
                addedAt: now,
              },
            },
          ]),
        ]);
    });
  });
```

--------------------------------

### Initialize project

Source: https://event-driven-io.github.io/emmett/quick-intro.html

Initialize a new package.json file using various package managers.

```sh
npm init
```

```sh
pnpm init
```

```sh
yarn init
```

```sh
bun init
```

--------------------------------

### Complete E2E Test Suite

Source: https://event-driven-io.github.io/emmett/getting-started.html

Full example of an E2E test suite using PostgreSQL containers and Emmett ExpressJS integration.

```typescript
import {
  ApiE2ESpecification,
  expectResponse,
  getApplication,
  type TestRequest,
} from '@event-driven-io/emmett-expressjs';
import {
  getPostgreSQLEventStore,
  type PostgresEventStore,
} from '@event-driven-io/emmett-postgresql';
import {
  PostgreSqlContainer,
  type StartedPostgreSqlContainer,
} from '@testcontainers/postgresql';
import { randomUUID } from 'node:crypto';

void describe('ShoppingCart E2E', () => {
  const unitPrice = 100;
  let clientId: string;
  let shoppingCartId: string;
  let postgreSQLContainer: StartedPostgreSqlContainer;
  let eventStore: PostgresEventStore;
  let given: ApiE2ESpecification;

  beforeAll(async () => {
    postgreSQLContainer = await new PostgreSqlContainer(
      'postgres:18.1',
    ).start();
    eventStore = getPostgreSQLEventStore(
      postgreSQLContainer.getConnectionUri(),
    );

    given = ApiE2ESpecification.for({
      getEventStore: () => eventStore,
      getApplication: (eventStore) =>
        getApplication({
          apis: [
            shoppingCartApi(
              eventStore,
              () => Promise.resolve(unitPrice),
              () => now,
            ),
          ],
        }),
    });
  });

  beforeEach(() => {
    clientId = randomUUID();
    shoppingCartId = `shopping_cart:${clientId}:current`;
  });

  afterAll(async () => {
    await eventStore.close();
    return postgreSQLContainer.stop();
  });

  void describe('When opened with product item', () => {
    const openedShoppingCartWithProduct: TestRequest = (request) =>
      request
        .post(`/clients/${clientId}/shopping-carts/current/product-items`)
        .send(productItem);

    void it('should confirm', () =>
      given(openedShoppingCartWithProduct)
        .when((request) =>
          request.post(`/clients/${clientId}/shopping-carts/current/confirm`),
        )
        .then([expectResponse(204)]));

    void it('returns details', () =>
      given(openedShoppingCartWithProduct)
        .when((request) =>
          request.get(`/clients/${clientId}/shopping-carts/current`).send(),
        )
        .then([
          expectResponse(200, {
            body: {
              clientId,
              id: shoppingCartId,
              productItems: [
                {
                  quantity: productItem.quantity,
                  productId: productItem.productId,
                },
              ],
              status: ShoppingCartStatus.Opened,
            },
          }),
        ]));
  });

  const now = new Date();

  const getRandomProduct = (): PricedProductItem => {
    return {
      productId: randomUUID(),
      unitPrice: unitPrice,
      quantity: Math.random() * 10,
    };
  };

  const productItem = getRandomProduct();
});
```

--------------------------------

### Test shopping cart with helper functions

Source: https://event-driven-io.github.io/emmett/getting-started.html

Uses eventsInStream and newEventsInStream helpers to simplify test setup for existing and new events.

```typescript
import {
  eventsInStream,
  newEventsInStream,
} from '@event-driven-io/emmett-postgresql';

void describe('Shopping carts summary', () => {
  // (...) test setup

  void it('applies discount for existing shopping cart with product', () => {
    const couponId = uuid();

    return given(
      eventsInStream(shoppingCartId, [
        {
          type: 'ProductItemAddedToShoppingCart',
          data: {
            productItem: { unitPrice: 100, productId: 'shoes', quantity: 100 },
          },
        },
      ]),
    )
      .when(
        newEventsInStream(shoppingCartId, [
          {
            type: 'DiscountApplied',
            data: { percent: 10, couponId },
          },
        ]),
      )
      .then(
        expectPongoDocuments
          .fromCollection<ShoppingCartShortInfo>(
            shoppingCartShortInfoCollectionName,
          )
          .withId(shoppingCartId)
          .toBeEqual({
            productItemsCount: 100,
            totalAmount: 9000,
          }),
      );
  });
});
```

--------------------------------

### Query a Read Model in HonoJS

Source: https://event-driven-io.github.io/emmett/frameworks/honojs.html

Example of setting up a HonoJS route to query a read model and return a response using built-in helpers.

```typescript
const shoppingCartDetailsApi: WebApiSetup = (router) => {
  router.get('/shopping-carts/:shoppingCartId', (context: Context) => {
    const shoppingCartId = assertNotEmptyString(
      context.req.param('shoppingCartId'),
    );
    const result = shoppingCartDetails.get(shoppingCartId);

    return result === undefined
      ? NotFound({
          context,
          problemDetails: `Shopping cart ${shoppingCartId} was not found`,
        })
      : OK({ context, body: result });
  });
};
```

--------------------------------

### Create entry point

Source: https://event-driven-io.github.io/emmett/quick-intro.html

Create an empty index.ts file.

```sh
touch index.ts
```

--------------------------------

### Execute ApiE2ESpecification Test

Source: https://event-driven-io.github.io/emmett/frameworks/expressjs.html

Performs a black-box test by executing multiple setup requests followed by a test request and final response assertion.

```typescript
void it('prepares state through HTTP requests', () => {
  const clientId = 'client-123';
  const shoppingCartId = clientId;
  const productItem = { productId: 'product-123', quantity: 2 };

  return apiE2ESpecification(
    (request) => request.post(`/clients/${clientId}/shopping-carts/`).send(),
    (request) =>
      request
        .post(
          `/clients/${clientId}/shopping-carts/${shoppingCartId}/product-items`,
        )
        .set(HeaderNames.IF_MATCH, toWeakETag(1))
        .send(productItem),
  )
    .when((request) =>
      request
        .post(`/clients/${clientId}/shopping-carts/${shoppingCartId}/confirm`)
        .set(HeaderNames.IF_MATCH, toWeakETag(2)),
    )
    .then([expectResponse(204, { headers: { etag: toWeakETag(3) } })]);
});
```

--------------------------------

### Aggregate and Append Events

Source: https://event-driven-io.github.io/emmett/getting-started.html

Demonstrates the manual process of aggregating a stream to get the current state and appending new events using the event store.

```typescript
const { state, expectedStreamVersion } = await eventStore.aggregateStream(
  streamName,
  {
    evolve,
    initialState,
  },
);

const events = handle(command, state);

await eventStore.appendToStream(streamName, result, { expectedStreamVersion });
```

--------------------------------

### Install Emmett Peer Dependencies

Source: https://event-driven-io.github.io/emmett/frameworks/fastify.html

Install the core Emmett package and Fastify as peer dependencies.

```bash
npm install @event-driven-io/emmett fastify
```

--------------------------------

### Quick Setup for SQLite Event Store

Source: https://event-driven-io.github.io/emmett/guides/choosing-event-store.html

Initialize the SQLite event store. Use a file path for persistent storage or ':memory:' for an in-memory store, suitable for testing.

```typescript
import { getSQLiteEventStore } from '@event-driven-io/emmett-sqlite';

// File-based
const eventStore = getSQLiteEventStore('./events.db');

// In-memory
const eventStore = getSQLiteEventStore(':memory:');
```

--------------------------------

### Install Emmett with Express.js v5

Source: https://event-driven-io.github.io/emmett/resources/faq.html

Install the Emmett Express integration alongside Express 5 and its corresponding type definitions.

```bash
npm install @event-driven-io/emmett-expressjs express@5
npm install --save-dev @types/express@5
```

--------------------------------

### Quick Setup: SQLite Event Store

Source: https://event-driven-io.github.io/emmett/event-stores

Initializes the SQLite event store, specifying the database file path. An in-memory option is also available using ':memory:'.

```typescript
import { getSQLiteEventStore } from '@event-driven-io/emmett-sqlite';

const eventStore = getSQLiteEventStore('./events.db');
// or in-memory: getSQLiteEventStore(':memory:')
```
Tokens:
Raw