@magek/mcp-server 0.0.8

package/docs/architecture/event-handler.md

@@ -0,0 +1,108 @@
+---
+title: "Event Handlers"
+group: "Architecture"
+---
+
+# Event handler
+
+An event handler is a class that reacts to events. They are commonly used to trigger side effects in case of a new event. For instance, if a new event is registered in the system, an event handler could send an email to the user.
+
+## Creating an event handler
+
+The Magek CLI will help you to create new event handlers. You just need to run the following command and the CLI will generate all the boilerplate for you:
+
+```bash
+npx magek new:event-handler HandleAvailability --event StockMoved
+```
+
+This will generate a new file called `handle-availability.ts` in the `src/event-handlers` directory. You can also create the file manually, but you will need to create the class and decorate it, so we recommend using the CLI.
+
+## Declaring an event handler
+
+In Magek, event handlers are classes decorated with the `@EventHandler` decorator. The parameter of the decorator is the event that the handler will react to. The logic to be triggered after an event is registered is defined in the `handle` method of the class. This `handle` function will receive the event that triggered the handler.
+
+```typescript title="src/event-handlers/handle-availability.ts"
+// highlight-next-line
+@EventHandler(StockMoved)
+export class HandleAvailability {
+  // highlight-start
+  public static async handle(event: StockMoved): Promise<void> {
+    // Do something here
+  }
+  // highlight-end
+}
+```
+
+## Creating an event handler
+
+Event handlers can be easily created using the Magek CLI command `npx magek new:event-handler`. There are two mandatory arguments: the event handler name, and the name of the event it will react to. For instance:
+
+```typescript
+npx magek new:event-handler HandleAvailability --event StockMoved
+```
+
+Once the creation is completed, there will be a new file in the event handlers directory `<project-root>/src/event-handlers/handle-availability.ts`.
+
+```text
+<project-root>
+├── src
+│   ├── commands
+│   ├── common
+│   ├── config
+│   ├── entities
+│   ├── events
+│   ├── event-handlers <------ put them here
+│   └── read-models
+```
+
+## Registering events from an event handler
+
+Event handlers can also register new events. This is useful when you want to trigger a new event after a certain condition is met. For example, if you want to send an email to the user when a product is out of stock.
+
+In order to register new events, Magek injects the `register` instance in the `handle` method as a second parameter. This `register` instance has a `events(...)` method that allows you to store any side effect events, you can specify as many as you need separated by commas as arguments of the function.
+
+```typescript title="src/event-handlers/handle-availability.ts"
+@EventHandler(StockMoved)
+export class HandleAvailability {
+  public static async handle(event: StockMoved, register: Register): Promise<void> {
+    if (event.quantity < 0) {
+      // highlight-next-line
+      register.events([new ProductOutOfStock(event.productID)])
+    }
+  }
+}
+```
+
+## Reading entities from event handlers
+
+There are cases where you need to read an entity to make a decision based on its current state. Different side effects can be triggered depending on the current state of the entity. Given the previous example, if a user does not want to receive emails when a product is out of stock, we should be able check the user preferences before sending the email.
+
+For that reason, Magek provides the `Magek.entity` function. This function allows you to retrieve the current state of an entity. Let's say that we want to check the status of a product before we trigger its availability update. In that case we would call the `Magek.entity` function, which will return information about the entity.
+
+```typescript title="src/event-handlers/handle-availability.ts"
+@EventHandler(StockMoved)
+export class HandleAvailability {
+  public static async handle(event: StockMoved, register: Register): Promise<void> {
+    // highlight-next-line
+    const product = await Magek.entity(Product, event.productID)
+    if (product.stock < 0) {
+      register.events([new ProductOutOfStock(event.productID)])
+    }
+  }
+}
+```
+
+## Creating a global event handler
+
+**Magek** includes a `Global event handler`. This feature allows you to react to any event that occurs within the system.
+By annotating a class with the @GlobalEventHandler decorator, the handle method within that class will be automatically called for any event that is generated
+
+```typescript
+@GlobalEventHandler
+export class GlobalHandler {
+  public static async handle(event: EventInterface | NotificationInterface, register: Register): Promise<void> {
+    if (event instanceof LogEventReceived) {
+      register.events(new LogEventReceivedTest(event.entityID(), event.value))
+    }
+  }
+```

package/docs/architecture/event.md

@@ -0,0 +1,145 @@
+---
+title: "Events"
+group: "Architecture"
+---
+
+# Event
+
+An event is a fact of something that has happened in your application. Every action that takes place on your application should be stored as an event. They are stored in a single collection, forming a set of **immutable records of facts** that contain the whole story of your application. This collection of events is commonly known as the **Event Store**.
+
+## Creating an event
+
+The Magek CLI will help you to create new events. You just need to run the following command and the CLI will generate all the boilerplate for you:
+
+```bash
+npx magek new:event StockMoved --fields productID:string origin:string destination:string quantity:number
+```
+
+This will generate a new file called `stock-moved.ts` in the `src/events` directory. You can also create the file manually, but you will need to create the class and decorate it, so we recommend using the CLI.
+
+## Declaring an event
+
+Events are the cornerstone of Magek because of its event-driven and event-sourced nature. Magek events are TypeScript classes decorated with `@Event`. An event class may look like this:
+
+```typescript title="src/events/event-name.ts"
+@Event
+export class EventName {
+  @field()
+  public readonly field1!: SomeType
+
+  @field()
+  public readonly field2!: SomeOtherType
+
+  public constructor(field1: SomeType, field2: SomeOtherType) {
+    this.field1 = field1
+    this.field2 = field2
+  }
+
+  public entityID(): UUID {
+    return /* the associated entity ID */
+  }
+}
+```
+
+The class name is the name of the event. The event name is used to identify the event in the application. It is also used to generate the GraphQL schema. The class parameter names are the names of the fields of the event and their types are the types of the fields of the event.
+
+## Events and entities
+
+Events and [Entities](./entity.md) are closely related. Each event will be aggregated (or _reduced_) into an entity. Therefore, Magek needs a way to know which entity is associated with each event. For that reason, it is required to provide an entity ID with each event. You can declare it with a class function named `entityID`. For example:
+
+```typescript title="src/events/cart-paid.ts"
+@Event
+export class CartPaid {
+  @field()
+  public readonly cartID!: UUID
+
+  @field()
+  public readonly paymentID!: UUID
+
+  public constructor(cartID: UUID, paymentID: UUID) {
+    this.cartID = cartID
+    this.paymentID = paymentID
+  }
+
+  // highlight-start
+  public entityID(): UUID {
+    // returns cartID because we want to associate it with
+    // (and reduce it within) the Cart entity
+    return this.cartID
+  }
+  // highlight-end
+}
+```
+
+> **Tip:** If your domain requires a **_Singleton_** entity, where there's only one instance of that entity in your whole application, you can return a constant value.
+
+> **Caution:** Make sure that the `entityID` method always returns the same value for the same event's instance. Otherwise, the result of the entity reduction will be unpredictable.
+
+## Registering events in the event store
+
+We have shown you how to _declare_ an event in Magek, but we haven't explained how to store them in the event store. In Magek terminology, creating an instance of an event and storing in the event store is known as `registering` it. You can do that on Magek using the `register.events(...)` function. The `register` object is provided as a parameter in the `handle` method of both [commands](./command.md#registering-events) and the [event handlers](./event-handler.md#registering-events-from-an-event-handler). For example:
+
+### Registering events from command handlers
+
+```typescript title="src/commands/move-stock.ts"
+@Command({
+  authorize: [Admin],
+})
+export class MoveStock {
+  @field()
+  readonly productID!: string
+
+  @field()
+  readonly origin!: string
+
+  @field()
+  readonly destination!: string
+
+  @field()
+  readonly quantity!: number
+
+  public static async handle(command: MoveStock, register: Register): Promise<void> {
+    if (!command.enoughStock(command.origin, command.quantity, command.productID)) {
+      // highlight-next-line
+      register.events(new ErrorEvent(`There is not enough stock for ${command.productID} at ${command.origin}`))
+    }
+  }
+}
+```
+
+### Registering events from event handlers
+
+```typescript title="src/event-handlers/stock-moved.ts"
+@EventHandler(StockMoved)
+export class HandleAvailability {
+  public static async handle(event: StockMoved, register: Register): Promise<void> {
+      // highlight-next-line
+      register.events(new ProductAvailabilityChanged(event.productID, event.quantity))
+    }
+  }
+}
+```
+
+## Events naming convention
+
+As with commands, you can name events in any way you want, depending on your application's domain. However, we recommend you to choose short sentences written in past tense because events are facts that have happened and can't be changed. Some event names would be:
+
+- ProductCreated
+- ProductUpdated
+- ProductDeleted
+- CartItemChanged
+- StockMoved
+
+As with other Magek files, events have their own directory:
+
+```text
+<project-root>
+├── src
+│   ├── commands
+│   ├── common
+│   ├── config
+│   ├── entities
+│   ├── events <------ put them here
+│   ├── index.ts
+│   └── read-models
+```

package/docs/architecture/notifications.md

@@ -0,0 +1,54 @@
+---
+title: "Notifications"
+group: "Architecture"
+---
+
+# Notifications
+
+Notifications are an important concept in event-driven architecture, and they play a crucial role in informing interested parties about certain events that take place within an application.
+
+## Declaring a notification
+
+In Magek, notifications are defined as classes decorated with the `@Notification` decorator. Here's a minimal example to illustrate this:
+
+```typescript title="src/notifications/cart-abandoned.ts"
+
+@Notification()
+export class CartAbandoned {}
+```
+
+As you can see, to define a notification you simply need to import the `@Notification` decorator from the @magek/core library and use it to decorate a class. In this case, the class `CartAbandoned` represents a notification that informs interested parties that a cart has been abandoned.
+
+## Separating by topic
+
+By default, all notifications in the application will be sent to the same topic called `defaultTopic`. To configure this, you can specify a different topic name in the `@Notification` decorator:
+
+```typescript title="src/notifications/cart-abandoned-topic.ts"
+
+@Notification({ topic: 'cart-abandoned' })
+export class CartAbandoned {}
+```
+
+In this example, the `CartAbandoned` notification will be sent to the `cart-abandoned` topic, instead of the default topic.
+
+## Separating by partition key
+
+By default, all the notifications in the application will share a partition key called `default`. This means that, by default, all the notifications in the application will be processed in order, which may not be as performant.
+
+To change this, you can use the @partitionKey decorator to specify a field that will be used as a partition key for each notification:
+
+```typescript title="src/notifications/cart-abandoned-partition-key.ts"
+
+@Notification({ topic: 'cart-abandoned' })
+export class CartAbandoned {
+  public constructor(@partitionKey readonly key: string) {}
+}
+```
+
+In this example, each `CartAbandoned` notification will have its own partition key, which is specified in the constructor as the field `key`, it can be called in any way you want. This will allow for parallel processing of notifications, making the system more performant.
+
+## Reacting to notifications
+
+Just like events, notifications can be handled by event handlers in order to trigger other processes. Event handlers are responsible for listening to events and notifications, and then performing specific actions in response to them.
+
+In conclusion, defining notifications in the Magek Framework is a simple and straightforward process that can be done using the `@Notification` and `@partitionKey` decorators.

package/docs/architecture/queries.md

@@ -0,0 +1,207 @@
+---
+title: "Queries"
+group: "Architecture"
+---
+
+#  Queries
+
+ReadModels offer read operations over reduced events. On the other hand, Queries provide a way to do custom read operations.
+
+Queries are classes decorated with the `@Query` decorator that have a `handle` method. When the handler returns a value, use the `@returns` decorator to specify the GraphQL return type.
+
+```typescript
+import {
+  beforeHookQueryID,
+  beforeHookQueryMultiply,
+  queryHandlerErrorCartId,
+  queryHandlerErrorCartMessage,
+} from '../constants'
+
+@Query({
+  authorize: 'all',
+})
+export class CartTotalQuantity {
+  @field()
+  readonly cartId!: UUID
+
+  @field()
+  @nonExposed
+  readonly multiply!: number
+
+  @returns(type => Number)
+  public static async handle(query: CartTotalQuantity, queryInfo: QueryInfo): Promise<number> {
+    const cart = await Magek.entity(Cart, query.cartId)
+    if (!cart || !cart.cartItems || cart.cartItems.length === 0) {
+      return 0
+    }
+    return cart?.cartItems
+      .map((cartItem) => cartItem.quantity)
+      .reduce((accumulator, value) => {
+        return accumulator + value
+      }, 0)
+  }
+}
+```
+
+##  Queries naming convention
+
+We recommend use the `Query` suffix in your queries name.
+
+Despite you can place your queries in any directory, we strongly recommend you to put them in `<project-root>/src/queries`.
+
+```text
+<project-root>
+├── src
+│   ├── commands
+│   ├── common
+│   ├── config
+│   ├── entities
+│   ├── read-models
+│   ├── events
+│   ├── queries      <------ put them here
+│   └── index.ts
+```
+
+##  Creating a query
+
+The preferred way to create a query is by using the generator, e.g.
+
+```shell
+npx magek new:query ItemsInCountry --fields country:string
+```
+
+The generator will create a Typescript class under the queries directory `<project-root>/src/queries/items-in-country.ts`.
+
+Queries classes can also be created by hand and there are no restrictions. The structure of the data is totally open and can be as complex as you can manage in your projection functions.
+
+## The query handler function
+
+Each query class must have a method called `handle`. This function is the command handler, and it will be called by the framework every time one instance of this query is submitted. Inside the handler you can run validations, return errors and query entities to make decisions.
+
+Handler function receive a QueryInfo object to let users interact with the execution context. It can be used for a variety of purposes, including:
+
+* Access the current signed in user, their roles and other claims included in their JWT token
+* Access the request context or alter the HTTP response headers
+
+### Validating data
+
+Magek uses the typed nature of GraphQL to ensure that types are correct before reaching the handler, so you don't have to validate types.
+
+####  Throw an error
+
+There are still business rules to be checked before proceeding with a query. For example, a given number must be between a threshold or a string must match a regular expression. In that case, it is enough just to throw an error in the handler. Magek will use the error's message as the response to make it descriptive.
+
+###  Registering events
+
+Within the query handler execution, it is not possible to register domain events. If you need to register events, then use a Command. For more details about events and the register parameter, see the [`Events`](/architecture/event) section.
+
+##  Authorizing queries
+
+You can define who is authorized to access your queries. The Magek authorization feature is covered in [the auth section](/security/authentication). So far, we have seen that you can make a query publicly accessible by authorizing `'all'` to query it, or you can set specific roles providing an array of roles in this way: `authorize: [Admin]`.
+
+##  Querying
+
+For every query, Magek automatically creates the corresponding GraphQL query. For example, given this `CartTotalQuantityQuery`:
+
+```typescript
+@Query({
+  authorize: 'all',
+})
+export class CartTotalQuantityQuery {
+  @field()
+  readonly cartId!: UUID
+
+  @returns(type => Number)
+  public static async handle(query: CartTotalQuantity, queryInfo: QueryInfo): Promise<number> {
+    const cart = await Magek.entity(Cart, query.cartId)
+    if (!cart || !cart.cartItems || cart.cartItems.length === 0) {
+      return 0
+    }
+    return cart?.cartItems
+      .map((cartItem) => cartItem.quantity)
+      .reduce((accumulator, value) => {
+        return accumulator + value
+      }, 0)
+  }
+}
+```
+
+You will get the following GraphQL query and subscriptions:
+
+```graphQL
+query CartTotalQuantityQuery($cartId: ID!): Float!
+```
+
+> **Note:** Query subscriptions are not supported yet
+
+###  Returning union types
+Magek supports returning graphql union types. For example, this `SearchMedia` query returning books and movies.
+
+```typescript
+export type MediaValue = BookReadModel | MovieReadModel
+
+class SearchResult {
+  readonly results!: MediaValue[]
+  constructor(results: MediaValue[]) {
+    this.results = results
+  }
+}
+
+@Query({
+  authorize: 'all',
+})
+export class SearchMedia {
+  @field()
+  readonly searchword!: string
+
+  @returns(type => SearchResult)
+  public static async handle(query: SearchMedia, queryInfo: QueryInfo): Promise<SearchResult> {
+    const [books, movies] = await Promise.all([
+      Magek.readModel(BookReadModel)
+        .filter({
+          title: {
+            contains: query.searchword,
+          },
+        })
+        .search(),
+      Magek.readModel(MovieReadModel)
+        .filter({
+          title: {
+            contains: query.searchword,
+          },
+        })
+        .search(),
+    ])
+    const response = [...books, ...movies]
+
+    return {
+      results: response,
+    }
+  }
+}
+```
+
+This generates the following query 
+
+```graphql
+SearchMedia ( input SearchMediaInput! ) SearchResult!
+```
+
+The GraphQL union querying functionality can then be used. An example for the query above could be the following.
+
+```graphql
+{
+  SearchMedia(input: { searchword: "Oppenheimer" }) {
+    results {
+      __typename
+      ... on BookReadModel {
+        title
+        pages
+      }
+      ... on MovieReadModel {
+        title
+      }
+    }
+  }
+}
+```