@magek/mcp-server 0.0.8

package/docs/architecture/command.md

@@ -0,0 +1,367 @@
+---
+title: "Commands"
+group: "Architecture"
+---
+
+# Command
+
+Commands are any action a user performs on your application. For example, `RemoveItemFromCart`, `RatePhoto` or `AddCommentToPost`. They express the intention of an user, and they are the main interaction mechanism of your application. They are a similar to the concept of a **request on a REST API**. Command issuers can also send data on a command as parameters.
+
+## Creating a command
+
+The Magek CLI will help you to create new commands. You just need to run the following command and the CLI will generate all the boilerplate for you:
+
+```bash
+npx magek new:command CreateProduct --fields sku:SKU displayName:string description:string price:Money
+```
+
+This will generate a new file called `create-product` in the `src/commands` 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 a command
+
+In Magek you define them as TypeScript classes decorated with the `@Command` decorator. The `Command` parameters will be declared as properties of the class.
+
+```typescript title="src/commands/command-name.ts"
+@Command({
+  authorize: 'all',
+})
+export class CommandName {
+  @field()
+  readonly fieldA!: SomeType
+
+  @field()
+  readonly fieldB!: SomeOtherType
+}
+```
+
+These commands are handled by `Command Handlers`, the same way a **REST Controller** do with a request. To create a `Command handler` of a specific Command, you must declare a `handle` class function inside the corresponding command you want to handle. For example:
+
+```typescript title="src/commands/command-name.ts"
+@Command({
+  authorize: 'all',
+})
+export class CommandName {
+  @field()
+  readonly fieldA!: SomeType
+
+  @field()
+  readonly fieldB!: SomeOtherType
+
+  // highlight-start
+  public static async handle(command: CommandName, register: Register): Promise<void> {
+    // Validate inputs
+    // Run domain logic
+    // register.events([event1,...])
+  }
+  // highlight-end
+}
+```
+
+Magek will then generate the GraphQL mutation for the corresponding command, and the infrastructure to handle them. You only have to define the class and the handler function. Commands are part of the public API, so you can define authorization policies for them, you can read more about this on [the authorization section](/security/authorization).
+
+> **Tip:** We recommend using command handlers to validate input data before registering events into the event store because they are immutable once there.
+
+## The command handler function
+
+Each command 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 command is submitted. Inside the handler you can run validations, return errors, query entities to make decisions, and register relevant domain events.
+
+### Registering events
+
+Within the command handler execution, it is possible to register domain events. The command handler function receives the `register` argument, so within the handler, it is possible to call `register.events(...)` with a list of events.
+
+```typescript title="src/commands/create-product.ts"
+@Command({
+  authorize: 'all',
+})
+export class CreateProduct {
+  @field()
+  readonly sku!: string
+
+  @field()
+  readonly price!: number
+
+  public static async handle(command: CreateProduct, register: Register): Promise<void> {
+    // highlight-next-line
+    register.event(new ProductCreated(/*...*/))
+  }
+}
+```
+
+For more details about events and the register parameter, see the [`Events`](/architecture/event) section.
+
+### Returning a value
+
+The command handler function can return a value. This value will be the response of the GraphQL mutation. By default, the command handler function expects you to return a `void` as a return type. Since GrahpQL does not have a `void` type, the command handler function returns `true` when called through the GraphQL. This is because the GraphQL specification requires a response, and `true` is the most appropriate value to represent a successful execution with no return value.
+
+If you want to return a value, you need to:
+1. Change the return type of the handler function
+2. Use the `@returns` decorator to specify the GraphQL return type
+
+The `@returns` decorator tells Magek what type to use in the generated GraphQL schema. Without it, Magek defaults to `Boolean` for the mutation return type.
+
+For example, if you want to return a `string`:
+
+```typescript title="src/commands/create-product.ts"
+@Command({
+  authorize: 'all',
+})
+export class CreateProduct {
+  @field()
+  readonly sku!: string
+
+  @field()
+  readonly price!: number
+
+  // highlight-next-line
+  @returns(type => String)
+  public static async handle(command: CreateProduct, register: Register): Promise<string> {
+    register.event(new ProductCreated(/*...*/))
+    // highlight-next-line
+    return 'Product created!'
+  }
+}
+```
+
+#### The @returns decorator
+
+The `@returns` decorator is required when your command handler returns a value other than `void`. It uses the same type function pattern as `@field()`:
+
+```typescript
+// Return a primitive type
+@returns(type => String)
+public static async handle(...): Promise<string> { ... }
+
+// Return a UUID (maps to GraphQL ID)
+@returns(type => UUID)
+public static async handle(...): Promise<UUID> { ... }
+
+// Return a number
+@returns(type => Number)
+public static async handle(...): Promise<number> { ... }
+
+// Return an array
+@returns(type => [CartItem])
+public static async handle(...): Promise<CartItem[]> { ... }
+```
+
+> **Note:** The type specified in `@returns` is the GraphQL return type, not the TypeScript type. TypeScript erases type information at compile time, so Magek cannot infer the return type automatically.
+
+### Validating data
+
+> **Tip:** 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
+
+A command will fail if there is an uncaught error during its handling. When a command fails, Magek will return a detailed error response with the message of the thrown error. This is useful for debugging, but it is also a security feature. Magek will never return an error stack trace to the client, so you don't have to worry about exposing internal implementation details.
+
+One case where you might want to throw an error is when the command is invalid because it breaks a business rule. For example, if the command contains a negative price. In that case, you can throw an error in the handler. Magek will use the error's message as the response to make it descriptive. For example, given this command:
+
+```typescript title="src/commands/create-product.ts"
+@Command({
+  authorize: 'all',
+})
+export class CreateProduct {
+  @field()
+  readonly sku!: string
+
+  @field()
+  readonly price!: number
+
+  public static async handle(command: CreateProduct, register: Register): Promise<void> {
+    const priceLimit = 10
+    if (command.price >= priceLimit) {
+      // highlight-next-line
+      throw new Error(`price must be below ${priceLimit}, and it was ${command.price}`)
+    }
+  }
+}
+```
+
+You'll get something like this response:
+
+```json
+{
+  "errors": [
+    {
+      "message": "price must be below 10, and it was 19.99",
+      "path": ["CreateProduct"]
+    }
+  ]
+}
+```
+
+#### Register error events
+
+There could be situations in which you want to register an event representing an error. For example, when moving items with insufficient stock from one location to another:
+
+```typescript title="src/commands/move-stock.ts"
+@Command({
+  authorize: 'all',
+})
+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.productID, command.origin, command.quantity)) {
+      // highlight-next-line
+      register.events(new ErrorEvent(`There is not enough stock for ${command.productID} at ${command.origin}`))
+    } else {
+      register.events(new StockMoved(/*...*/))
+    }
+  }
+
+  private enoughStock(productID: string, origin: string, quantity: number): boolean {
+    /* ... */
+  }
+}
+```
+
+In this case, the command operation can still be completed. An event handler will take care of that `ErrorEvent and proceed accordingly.
+
+### Reading entities
+
+Event handlers are a good place to make decisions and, to make better decisions, you need information. The `Magek.entity` function allows you to inspect the application state. This function receives two arguments, the `Entity`'s name to fetch and the `entityID`. Here is an example of fetching an entity called `Stock`:
+
+```typescript title="src/commands/move-stock.ts"
+@Command({
+  authorize: 'all',
+})
+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> {
+    // highlight-next-line
+    const stock = await Magek.entity(Stock, command.productID)
+    if (!command.enoughStock(command.origin, command.quantity, stock)) {
+      register.events(new ErrorEvent(`There is not enough stock for ${command.productID} at ${command.origin}`))
+    }
+  }
+
+  private enoughStock(origin: string, quantity: number, stock?: Stock): boolean {
+    const count = stock?.countByLocation[origin]
+    return !!count && count >= quantity
+  }
+}
+```
+
+## Authorizing a command
+
+Commands are part of the public API of a Magek application, so you can define who is authorized to submit them. All commands are protected by default, which means that no one can submit them. In order to allow users to submit a command, you must explicitly authorize them. You can use the `authorize` field of the `@Command` decorator to specify the authorization rule.
+
+```typescript title="src/commands/create-product.ts"
+@Command({
+  // highlight-next-line
+  authorize: 'all',
+})
+export class CreateProduct {
+  @field()
+  readonly sku!: Sku
+
+  @field()
+  readonly displayName!: string
+
+  @field()
+  readonly description!: string
+
+  @field()
+  readonly price!: number
+
+  public static async handle(command: CreateProduct, register: Register): Promise<void> {
+    register.events(/* YOUR EVENT HERE */)
+  }
+}
+```
+
+You can read more about this on the [Authorization section](/security/authorization).
+
+## Submitting a command
+
+Magek commands are accessible to the outside world as GraphQL mutations. GrahpQL fits very well with Magek's CQRS approach because it has two kinds of operations: Mutations and Queries. Mutations are actions that modify the server-side data, just like commands.
+
+Magek automatically creates one mutation per command. The framework infers the mutation input type from the command fields. Given this `CreateProduct` command:
+
+```typescript
+@Command({
+  authorize: 'all',
+})
+export class CreateProduct {
+  @field()
+  readonly sku!: Sku
+
+  @field()
+  readonly displayName!: string
+
+  @field()
+  readonly description!: string
+
+  @field()
+  readonly price!: number
+
+  public static async handle(command: CreateProduct, register: Register): Promise<void> {
+    register.events(/* YOUR EVENT HERE */)
+  }
+}
+```
+
+Magek generates the following GraphQL mutation:
+
+```graphql
+mutation CreateProduct($input: CreateProductInput!): Boolean
+```
+
+where the schema for `CreateProductInput` is
+
+```text
+{
+  sku: String
+  displayName: String
+  description: String
+  price: Float
+}
+```
+
+## Commands naming convention
+
+Semantics are very important in Magek as it will play an essential role in designing a coherent system. Your application should reflect your domain concepts, and commands are not an exception. Although you can name commands in any way you want, we strongly recommend you to **name them starting with verbs in imperative plus the object being affected**. If we were designing an e-commerce application, some commands would be:
+
+- CreateProduct
+- DeleteProduct
+- UpdateProduct
+- ChangeCartItems
+- ConfirmPayment
+- MoveStock
+- UpdateCartShippingAddress
+
+Despite you can place commands, and other Magek files, in any directory, we strongly recommend you to put them in `<project-root>/src/commands`. Having all the commands in one place will help you to understand your application's capabilities at a glance.
+
+```text
+<project-root>
+├── src
+│   ├── commands <------ put them here
+│   ├── common
+│   ├── config
+│   ├── entities
+│   ├── events
+│   ├── index.ts
+│   └── read-models
+```

package/docs/architecture/entity.md

@@ -0,0 +1,214 @@
+---
+title: "Entities"
+group: "Architecture"
+---
+
+# Entity
+
+If events are the _source of truth_ of your application, entities are the _current state_ of your application. For example, if you have an application that allows users to create bank accounts, the events would be something like `AccountCreated`, `MoneyDeposited`, `MoneyWithdrawn`, etc. But the entities would be the `BankAccount` themselves, with the current balance, owner, etc.
+
+Entities are created by _reducing_ the whole event stream. Magek generates entities on the fly, so you don't have to worry about their creation. However, you must define them in order to instruct Magek how to generate them.
+
+> **Info:** Under the hood, Magek stores snapshots of the entities in order to reduce the load on the event store. That way, Magek doesn't have to reduce the whole event stream whenever the current state of an entity is needed.
+
+## Creating entities
+
+The Magek CLI will help you to create new entities. You just need to run the following command and the CLI will generate all the boilerplate for you:
+
+```bash
+npx magek new:entity Product --fields displayName:string description:string price:Money
+```
+
+This will generate a new file called `product.ts` in the `src/entities` 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 entity
+
+To declare an entity in Magek, you must define a class decorated with the `@Entity` decorator. Inside of the class, you must define a constructor with all the fields you want to have in your entity.
+
+```typescript title="src/entities/entity-name.ts"
+@Entity
+export class EntityName {
+  @field(type => UUID)
+  public id!: UUID
+
+  @field()
+  readonly fieldA!: SomeType
+
+  @field()
+  readonly fieldB!: SomeOtherType
+}
+```
+
+## The reduce function
+
+In order to tell Magek how to reduce the events, you must define a static method decorated with the `@reduces` decorator. This method will be called by the framework every time an event of the specified type is emitted. The reducer method must return a new entity instance with the current state of the entity.
+
+```typescript title="src/entities/entity-name.ts"
+@Entity
+export class EntityName {
+  @field(type => UUID)
+  public id!: UUID
+
+  @field()
+  readonly fieldA!: SomeType
+
+  @field()
+  readonly fieldB!: SomeOtherType
+
+  // highlight-start
+  @reduces(SomeEvent)
+  public static reduceSomeEvent(event: SomeEvent, currentEntityState?: EntityName): EntityName {
+    return evolve(currentEntityState, {
+      id: event.entityID(),
+      fieldA: event.fieldA,
+      fieldB: event.fieldB,
+    })
+  }
+  // highlight-end
+}
+```
+
+The reducer method receives two parameters:
+
+- `event` - The event object that triggered the reducer
+- `currentEntity?` - The current state of the entity instance that the event belongs to if it exists. **This parameter is optional** and will be `undefined` if the entity doesn't exist yet (For example, when you process a `ProductCreated` event that will generate the first version of a `Product` entity).
+
+> **Tip:** The `evolve()` helper function creates a new immutable copy of the entity with the specified field updates. It safely handles the case where `currentEntityState` is `undefined` (for newly created entities) and ensures immutability by returning a fresh object rather than mutating the existing one.
+
+### Reducing multiple events
+
+You can define as many reducer methods as you want, each one for a different event type. For example, if you have a `Cart` entity, you could define a reducer for `ProductAdded` events and another one for `ProductRemoved` events.
+
+```typescript title="src/entities/cart.ts"
+@Entity
+export class Cart {
+  @field(type => UUID)
+  public id!: UUID
+
+  @field()
+  readonly items!: Array<CartItem>
+
+  @reduces(ProductAdded)
+  public static reduceProductAdded(event: ProductAdded, currentCart?: Cart): Cart {
+    const newItems = addToCart(event.item, currentCart)
+    return evolve(currentCart, { id: event.entityID(), items: newItems })
+  }
+
+  @reduces(ProductRemoved)
+  public static reduceProductRemoved(event: ProductRemoved, currentCart?: Cart): Cart {
+    const newItems = removeFromCart(event.item, currentCart)
+    return evolve(currentCart, { items: newItems })
+  }
+}
+```
+
+> **Tip:** It's highly recommended to **keep your reducer functions pure**, which means that you should be able to produce the new entity version by just looking at the event and the current entity state. You should avoid calling third party services, reading or writing to a database, or changing any external state.
+
+### Skipping Events with ReducerAction.Skip
+
+Sometimes a reducer may need to skip an event instead of updating the entity state. This can happen when:
+- Receiving an update event for an entity that doesn't exist
+- Processing an event that is no longer relevant
+- Handling events that should be ignored under certain conditions
+
+To skip an event, return `ReducerAction.Skip` from your reducer. This tells Magek to keep the current entity state unchanged:
+
+```typescript title="src/entities/product.ts"
+import { ReducerAction, ReducerResult } from '@magek/common'
+
+@Entity
+export class Product {
+  @field(type => UUID)
+  public id!: UUID
+
+  @field()
+  readonly name!: string
+
+  @field()
+  readonly price!: number
+
+  @reduces(ProductUpdated)
+  public static reduceProductUpdated(
+    event: ProductUpdated,
+    currentProduct?: Product
+  ): ReducerResult<Product> {
+    if (!currentProduct) {
+      // Can't update a non-existent product - skip this event
+      return ReducerAction.Skip
+    }
+    return new Product(currentProduct.id, event.newName, event.newPrice)
+  }
+}
+```
+
+When a reducer returns `ReducerAction.Skip`, the framework will:
+- Keep the previous entity snapshot unchanged
+- Continue processing subsequent events in the event stream
+- Not store a new snapshot for this event
+
+> **Note:** `ReducerAction.Skip` should be used sparingly and only for events that genuinely should not affect entity state. In most cases, properly designed events and reducers won't need to skip events.
+
+There could be a lot of events being reduced concurrently among many entities, but, **for a specific entity instance, the events order is preserved**. This means that while one event is being reduced, all other events of any kind _that belong to the same entity instance_ will be waiting in a queue until the previous reducer has finished. This is how Magek guarantees that the entity state is consistent.
+
+![reducer process gif](/img/reducer.gif)
+
+### Eventual Consistency
+
+Additionally, due to the event driven and async nature of Magek, your data might not be instantly updated. Magek will consume the commands, generate events, and _eventually_ generate the entities. Most of the time this is not perceivable, but under huge loads, it could be noticed.
+
+This property is called [Eventual Consistency](https://en.wikipedia.org/wiki/Eventual_consistency), and it is a trade-off to have high availability for extreme situations, where other systems might simply fail.
+
+## Entity ID
+
+In order to identify each entity instance, you must define an `id` field on each entity. This field will be used by the framework to identify the entity instance. If the value of the `id` field matches the value returned by the [`entityID()` method](./event.md#events-and-entities) of an Event, the framework will consider that the event belongs to that entity instance.
+
+```typescript title="src/entities/entity-name.ts"
+@Entity
+export class EntityName {
+  // highlight-next-line
+  @field(type => UUID)
+  public id!: UUID
+
+  @field()
+  readonly fieldA!: SomeType
+
+  @field()
+  readonly fieldB!: SomeOtherType
+
+  @reduces(SomeEvent)
+  public static reduceSomeEvent(event: SomeEvent, currentEntityState?: EntityName): EntityName {
+    return evolve(currentEntityState, {
+      id: event.entityID(),
+      fieldA: event.fieldA,
+    })
+  }
+}
+```
+
+> **Tip:** We recommend you to use the `UUID` type for the `id` field. You can generate a new `UUID` value by calling the `UUID.generate()` method already provided by the framework.
+
+## Entities naming convention
+
+Entities are a representation of your application state in a specific moment, so name them as closely to your domain objects as possible. Typical entity names are nouns that might appear when you think about your app. In an e-commerce application, some entities would be:
+
+- Cart
+- Product
+- UserProfile
+- Order
+- Address
+- PaymentMethod
+- Stock
+
+Entities live within the entities directory of the project source: `<project-root>/src/entities`.
+
+```text
+<project-root>
+├── src
+│   ├── commands
+│   ├── common
+│   ├── config
+│   ├── entities <------ put them here
+│   ├── events
+│   ├── index.ts
+│   └── read-models
+```

package/docs/architecture/event-driven.md

@@ -0,0 +1,30 @@
+---
+title: "Event-Driven Architecture"
+group: "Architecture"
+---
+
+# Magek architecture
+
+Magek is a highly opinionated framework that provides a complete toolset to build production-ready event-driven serverless applications.
+
+Two patterns influence the Magek's event-driven architecture: Command-Query Responsibility Segregation ([CQRS](https://www.martinfowler.com/bliki/CQRS.html)) and [Event Sourcing](https://martinfowler.com/eaaDev/EventSourcing.html). They're complex techniques to implement from scratch with lower-level frameworks, but Magek makes them feel natural and very easy to use.
+
+![architecture](../magek-arch.png)
+
+As you can see in the diagram, Magek applications consist of four main building blocks: `Commands`, `Events`, `Entities`, and `Read Models`. `Commands` and `Read Models` are the public interface of the application, while `Events` and `Entities` are private implementation details. With Magek, clients submit `Commands`, query the `Read Models`, or subscribe to them for receiving real-time updates thanks to the out of the box [GraphQL API](/graphql)
+
+Magek applications are event-driven and event-sourced so, **the source of truth is the whole history of events**. When a client submits a command, Magek _wakes up_ and handles it throght `Command Handlers`. As part of the process, some `Events` may be _registered_ as needed.
+
+On the other side, the framework caches the current state by automatically _reducing_ all the registered events into `Entities`. You can also _react_ to events via `Event Handlers`, triggering side effect actions to certain events. Finally, `Entities` are not directly exposed, they are transformed or _projected_ into `ReadModels`, which are exposed to the public.
+
+In this chapter you'll walk through these concepts in detail.
+
+## Architecture Components
+
+- [Commands](./command.md) - The input interface for your application
+- [Events](./event.md) - Records of facts that represent the source of truth
+- [Event Handlers](./event-handler.md) - React to events and trigger side effects
+- [Entities](./entity.md) - Current state derived from events
+- [Read Models](./read-model.md) - Public projections of your data
+- [Notifications](./notifications.md) - Real-time updates and messaging
+- [Queries](./queries.md) - How to query your read models