@magek/mcp-server 0.0.8

package/docs/advanced/data-migrations.md

@@ -0,0 +1,181 @@
+---
+title: "Data Migrations"
+group: "Advanced"
+---
+
+# Migrations
+
+Migrations are a mechanism for updating or transforming the schemas of events and entities as your system evolves. This allows you to make changes to your data model without losing or corrupting existing data. There are two types of migration tools available in Magek: schema migrations and data migrations.
+
+* **Schema migrations** are used to incrementally upgrade an event or entity from a past version to the next. They are applied lazily, meaning that they are performed on-the-fly whenever an event or entity is loaded. This allows you to make changes to your data model without having to manually update all existing artifacts, and makes it possible to apply changes without running lengthy migration processes.
+
+* **Data migrations**, on the other hand, behave as background processes that can actively change the existing values in the database for existing entities and read models. They are particularly useful for data migrations that cannot be performed automatically with schema migrations, or for updating existing read models after a schema change.
+
+Together, schema and data migrations provide a flexible and powerful toolset for managing the evolution of your data model over time.
+
+## Schema migrations
+
+Magek handles classes annotated with `@SchemaMigration` as **schema migrations**. The migration functions defined inside will update an existing artifact (either an event or an entity) from a previous version to a newer one whenever that artifact is visited. Schema migrations are applied to events and entities lazily, meaning that they are only applied when the event or entity is loaded. This ensures that the migration process is non-disruptive and does not affect the performance of your system. Schema migrations are also performed on-the-fly and the results are not written back to the database, as events are not revisited once the next snapshot is written in the database.
+
+For example, to upgrade a `Product` entity from version 1 to version 2, you can write the following migration class:
+
+```typescript
+@SchemaMigration(Product)
+export class ProductMigration {
+  @toVersion(2, { fromSchema: ProductV1, toSchema: ProductV2 })
+  public async changeNameFieldToDisplayName(old: ProductV1): Promise<ProductV2> {
+    return new ProductV2(
+      old.id,
+      old.sku,
+      old.name,
+      old.description,
+      old.price,
+      old.pictures,
+      old.deleted
+    )
+  }
+}
+```
+
+Notice that we've used the `@toVersion` decorator in the above example. This decorator not only tells Magek what schema upgrade this migration performs, it also informs it about the existence of a version, which is always an integer number. Magek will always use the latest version known to tag newly created artifacts, defaulting to 1 when no migrations are defined. This ensures that the schema of newly created events and entities is up-to-date and that they can be migrated as needed in the future.
+
+The `@toVersion` decorator takes two parameters in addition to the version: `fromSchema` and `toSchema`. The fromSchema parameter is set to `ProductV1`, while the `toSchema` parameter is set to `ProductV2`. This tells Magek that the migration is updating the `Product` object from version 1 (as defined by the `ProductV1` schema) to version 2 (as defined by the `ProductV2` schema).
+
+As Magek can easily read the structure of your classes, the schemas are described as plain classes that you can maintain as part of your code. The `ProductV1` class represents the schema of the previous version of the `Product` object with the properties and structure of the `Product` object as it was defined in version 1. The `ProductV2` class is an alias for the latest version of the Product object. You can use the `Product` class here, there's no difference, but it's a good practice to create an alias for clarity.
+
+It's a good practice to define the schema classes (`ProductV1` and `ProductV2`) as non-exported classes in the same migration file. This allows you to see the changes made between versions and helps to understand how the migration works:
+
+```typescript
+class ProductV1 {
+  public constructor(
+    public id: UUID,
+    readonly sku: string,
+    readonly name: string,
+    readonly description: string,
+    readonly price: Money,
+    readonly pictures: Array<Picture>,
+    public deleted: boolean = false
+  ) {}
+}
+
+class ProductV2 extends Product {}
+```
+
+When you want to upgrade your artifacts from V2 to V3, you can add a new function decorated with `@toVersion` to the same migrations class. You're free to structure the code the way you want, but we recommend keeping all migrations for the same artifact in the same migration class. For instance:
+
+```typescript
+@SchemaMigration(Product)
+export class ProductMigration {
+  @toVersion(2, { fromSchema: ProductV1, toSchema: ProductV2 })
+  public async changeNameFieldToDisplayName(old: ProductV1): Promise<ProductV2> {
+    return new ProductV2(
+      old.id,
+      old.sku,
+      old.name, // It's now called `displayName`
+      old.description,
+      old.price,
+      old.pictures,
+      old.deleted
+    )
+  }
+
+  @toVersion(3, { fromSchema: ProductV2, toSchema: ProductV3 })
+  public async addNewField(old: ProductV2): Promise<ProductV3> {
+    return new ProductV3(
+      old.id,
+      old.sku,
+      old.displayName,
+      old.description,
+      old.price,
+      old.pictures,
+      old.deleted,
+      42 // We set a default value to initialize this field
+    )
+  }
+}
+```
+
+In this example, the `changeNameFieldToDisplayName` function updates the `Product` entity from version 1 to version 2 by renaming the `name` field to `displayName`. Then, `addNewField` function updates the `Product` entity from version 2 to version 3 by adding a new field called `newField` to the entity's schema. Notice that at this point, your database could have snapshots set as v1, v2, or v3, so while it might be tempting to redefine the original migration to keep a single 1-to-3 migration, it's usually a good idea to keep the intermediate steps. This way Magek will be able to handle any scenario.
+
+## Data migrations
+
+Data migrations can be seen as background processes that can actively update the values of existing entities and read models in the database. They can be useful to perform data migrations that cannot be handled with schema migrations, for example when you need to update the values exposed by the GraphQL API, or to initialize new read models that are projections of previously existing entities.
+
+To create a data migration in Magek, you can use the `@DataMigration` decorator on a class that implements a `start` method. The `@DataMigration` decorator takes an object with a single parameter, `order`, which specifies the order in which the data migration should be run relative to other data migrations.
+
+Data migrations are not run automatically, you need to invoke the `MagekDataMigrations.run()` method from an event handler or a command. This will emit a `MagekDataMigrationStarted` event, which will make Magek check for any pending migrations and run them in the specified order. A common pattern to be able to run migrations on demand is to add a special command, with access limited to an administrator role which calls this function.
+
+It's advisable to design these functions in a way that allows re-running them in case of failures. In order to tell Magek that your migration has been applied successfully, at the end of each `DataMigration.start` method, you must emit a `MagekDataMigrationFinished` event manually.
+
+Inside your `@DataMigration` classes, you can use the `MagekDataMigrations.migrateEntity` method to update the data for a specific entity. This method takes the old entity name, the old entity ID, and the new entity data as arguments. It will also generate an internal `MagekEntityMigrated` event before performing the migration.
+
+Here is an example of how you might use the `@DataMigration` decorator and the `Magek.migrateEntity` method to update the quantity of the first item in a cart:
+
+```typescript
+@DataMigration({
+  order: 2,
+})
+export class CartIdDataMigrateV2 {
+  public constructor() {}
+
+  public static async start(register: Register): Promise<void> {
+    const entitiesIdsResult = await Magek.entitiesIDs('Cart', 500, undefined)
+    const paginatedEntityIdResults = entitiesIdsResult.items
+
+    const carts = await Promise.all(
+      paginatedEntityIdResults.map(async (entity) => await Magek.entity(Cart, entity.entityID))
+    )
+    return await Promise.all(
+        carts.map(async (cart) => {
+          cart.cartItems[0].quantity = 100
+          const newCart = new Cart(cart.id, cart.cartItems, cart.shippingAddress, cart.checks)
+          await MagekDataMigrations.migrateEntity('Cart', validCart.id, newCart)
+          return validCart.id
+      })
+    )
+
+    register.events(new MagekDataMigrationFinished('CartIdDataMigrateV2'))
+  }
+}
+```
+
+# Migrate from Previous Magek Versions
+
+* To migrate to new versions of Magek, check that you have the latest development dependencies required:
+
+```json
+"devDependencies": {
+    "rimraf": "^5.0.0",
+    "@typescript-eslint/eslint-plugin": "4.22.1",
+    "@typescript-eslint/parser": "4.22.1",
+    "eslint": "7.26.0",
+    "eslint-config-prettier": "8.3.0",
+    "eslint-plugin-prettier": "3.4.0",
+    "mocha": "10.2.0",
+    "@types/mocha": "10.0.1",
+    "nyc": "15.1.0",
+    "prettier":  "2.3.0",
+    "typescript": "4.5.4",
+    "ts-node": "9.1.1",
+    "@types/node": "15.0.2",
+    "ts-patch": "3.1.2",
+    "@magek/metadata": "0.30.2"
+  },
+```
+
+## Migrate to Magek version 1.19.0
+
+Magek version 1.19.0 requires updating your index.ts file to export the `health` method. If you have an index.ts file created from a previous Magek version, update it accordingly. Example:
+
+```typescript
+export {
+  Magek,
+  eventDispatcher,
+  graphQLDispatcher,
+  health,
+  notifySubscribers,
+  triggerScheduledCommands,
+} from '@magek/core'
+
+Magek.start(__dirname)
+```

package/docs/advanced/environment-configuration.md

@@ -0,0 +1,74 @@
+---
+title: "Environment Configuration"
+group: "Advanced"
+---
+
+# Environments
+
+You can create multiple environments calling the `Magek.configure` function several times using different environment names as the first argument. You can create one file for each environment, but it is not required. In this example we set all environments in a single file:
+
+```typescript
+// Here we use a single file called src/config.ts, but you can use separate files for each environment too.
+
+Magek.configure('stage', (config: MagekConfig): void => {
+  config.appName = 'fruit-store-stage'
+  config.runtime = ServerRuntime
+  config.eventStoreAdapter = eventStore
+  config.readModelStoreAdapter = readModelStore
+  config.sessionStoreAdapter = sessionStore
+})
+
+Magek.configure('prod', (config: MagekConfig): void => {
+  config.appName = 'fruit-store-prod'
+  config.runtime = ServerRuntime
+  config.eventStoreAdapter = eventStore
+  config.readModelStoreAdapter = readModelStore
+  config.sessionStoreAdapter = sessionStore
+})
+```
+
+## Pluggable Adapters
+
+Magek uses a pluggable architecture for data storage, allowing you to choose the most appropriate storage solution for your needs. The framework provides several adapter types:
+
+### Event Store Adapters
+Event store adapters handle the storage and retrieval of events in your event-sourced system:
+
+- `@magek/adapter-event-store-nedb` - A lightweight, file-based adapter perfect for development and testing
+
+### Read Model Store Adapters  
+Read model store adapters manage the storage of read models (projections of your domain state):
+
+- `@magek/adapter-read-model-store-nedb` - A lightweight, file-based adapter perfect for development and testing
+
+### Session Store Adapters
+Session store adapters handle WebSocket connections and subscription management:
+
+- `@magek/adapter-session-store-nedb` - A lightweight, file-based adapter perfect for development and testing
+
+This modular approach allows you to:
+- Start development quickly with simple file-based stores
+- Switch to production-grade databases without changing your application code
+- Create custom adapters for specific requirements
+- Test your application with different storage backends
+
+To use adapters, simply import them and assign them to the corresponding configuration properties (`config.eventStoreAdapter`, `config.readModelStoreAdapter`, `config.sessionStoreAdapter`) in your environment configuration.
+
+## Environment Files
+
+It is also possible to place an environment configuration in a separated file. Let's say that a developer called "John" created its own configuration file `src/config/john.ts`. The content would be the following:
+
+```typescript
+
+Magek.configure('john', (config: MagekConfig): void => {
+  config.appName = 'john-fruit-store'
+  config.runtime = ServerRuntime
+  config.eventStoreAdapter = eventStore
+  config.readModelStoreAdapter = readModelStore
+  config.sessionStoreAdapter = sessionStore
+})
+```
+
+This way, you can have different configurations depending on your needs.
+
+Magek environments are extremely flexible. As shown in the first example, your 'fruit-store' app can have three team-wide environments: 'dev', 'stage', and 'prod', each of them with different app names or configurations. Developers, like "John" in the second example, can create their own private environments in separate config files to test their changes before committing them.

package/docs/advanced/framework-packages.md

@@ -0,0 +1,17 @@
+---
+title: "Framework Packages"
+group: "Advanced"
+---
+
+# Framework packages
+The framework is already splitted into different packages:
+
+## Framework Core
+
+The `framework-core` package includes the most important components of the framework abstraction. It can be seen as skeleton or the main architecture of the framework.
+
+The package defines the specification of how should a Magek application work without taking into account the specific providers that could be used. Every Magek provider package is based on the components that the framework core needs in order to work on the platform.
+
+## Common
+
+The `common` package includes the types that define the domain of the Magek framework. It defines domain concepts like an `Event`, a `Command` or a `Role`.

package/docs/advanced/health/sensor-health.md

@@ -0,0 +1,389 @@
+---
+title: "Sensor Health"
+group: "Advanced"
+---
+
+## Health
+
+The Health functionality allows users to easily monitor the health status of their applications. With this functionality, users can make GET requests to a specific endpoint and retrieve detailed information about the health and status of their application components.
+
+### Enabling Health Functionality
+
+To enable the Health functionality in your Magek application, follow these steps:
+
+1. Install or update to the latest version of the Magek framework, ensuring compatibility with the Health functionality.
+2. Enable the Magek Health endpoints in your application's configuration file. Example configuration in config.ts:
+
+```typescript
+
+Magek.configure('local', (config: MagekConfig): void => {
+  config.appName = 'my-store'
+  config.runtime = ServerRuntime
+  Object.values(config.sensorConfiguration.health.magek).forEach((indicator) => {
+    indicator.enabled = true
+  })
+})
+```
+
+Or enable only the components you want:
+
+```typescript
+Magek.configure('local', (config: MagekConfig): void => {
+  config.appName = 'my-store'
+  config.runtime = ServerRuntime
+  const sensors = config.sensorConfiguration.health.magek
+  sensors[HEALTH_INDICATORS_IDS.DATABASE].enabled = true
+})
+```
+
+3. Optionally, implement health checks for your application components. Each component should provide a health method that performs the appropriate checks and returns a response indicating the health status. Example:
+
+```typescript
+import {
+  MagekConfig,
+  HealthIndicatorResult,
+  HealthIndicatorMetadata,
+  HealthStatus,
+} from '@magek/common'
+
+@HealthSensor({
+  id: 'application',
+  name: 'my-application',
+  enabled: true,
+  details: true,
+  showChildren: true,
+})
+export class ApplicationHealthIndicator {
+  public async health(
+    config: MagekConfig,
+    healthIndicatorMetadata: HealthIndicatorMetadata
+  ): Promise<HealthIndicatorResult> {
+    return {
+      status: HealthStatus.UP,
+    } as HealthIndicatorResult
+  }
+}
+```
+
+4. A health check typically involves verifying the connectivity and status of the component, running any necessary tests, and returning an appropriate status code.
+5. Start or restart your Magek application. The Health functionality will be available at the <https://your-application-url/sensor/health/> endpoint URL.
+
+### Health Endpoint
+
+The Health functionality provides a dedicated endpoint where users can make GET requests to retrieve the health status of their application. The endpoint URL is: <https://your-application-url/sensor/health/>
+
+This endpoint will return all the enabled Magek and application components health status. To get specific component health status, add the component status to the url. For example, to get the events status use: <https://your-application-url/sensor/health/magek/database/events>
+
+#### Available endpoints
+
+Magek provides the following endpoints to retrieve the enabled components:
+
+- <https://your-application-url/sensor/health/>: All the components status
+- <https://your-application-url/sensor/health/magek>: Magek status
+- <https://your-application-url/sensor/health/magek/database>: Database status
+- <https://your-application-url/sensor/health/magek/database/events>: Events status
+- <https://your-application-url/sensor/health/magek/database/readmodels>: ReadModels status
+- <https://your-application-url/sensor/health/magek/function>: Functions status
+- <https://your-application-url/sensor/health/your-component-id>: User defined status
+- <https://your-application-url/sensor/health/your-component-id/your-component-child-id>: User child component status
+
+Depending on the `showChildren` configuration, child components will be included or not.
+
+### Health Status Response
+
+Each component response will contain the following information:
+
+- status: The component or subsystem status
+- name: component description
+- id: string. unique component identifier. You can request a component status using the id in the url
+- details: optional object. If `details` is enabled, specific details about this component.
+- components: optional object. If `showChildren` is enabled, child components health status.  
+
+Example:
+
+```json
+[
+  {
+    "status": "UP",
+    "details": {
+      "urls": [
+        "dbs/my-store-app"
+      ]
+    },
+    "name": "Magek Database",
+    "id": "magek/database",
+    "components": [
+      {
+        "status": "UP",
+        "details": {
+          "url": "dbs/my-store-app/colls/my-store-app-events-store",
+          "count": 6
+        },
+        "name": "Magek Database Events",
+        "id": "magek/database/events"
+      },
+      {
+        "status": "UP",
+        "details": [
+          {
+            "url": "dbs/my-store-app/colls/my-store-app-ProductReadModel",
+            "count": 1
+          }
+        ],
+        "name": "Magek Database ReadModels",
+        "id": "magek/database/readmodels"
+      }
+    ]
+  }
+]
+```
+
+### HTTP Status Codes
+
+The health endpoint returns different HTTP status codes based on the overall health of the application:
+
+- 200 OK: All components are healthy (UP)
+- 503 Service Unavailable: One or more components are unhealthy (DOWN or PARTIALLY_UP)
+
+### Get specific component health information
+
+Use the `id` field to get specific component health information. Magek provides the following ids:
+
+- magek
+- magek/function
+- magek/database
+- magek/database/events
+- magek/database/readmodels
+
+You can provide new components:
+
+```typescript
+@HealthSensor({
+  id: 'application',
+})
+```
+
+```typescript
+@HealthSensor({
+  id: 'application/child',
+})
+```
+
+Add your own components to Magek:
+
+```typescript
+@HealthSensor({
+  id: `${HEALTH_INDICATORS_IDS.DATABASE}/extra`,
+})
+```
+
+Or override Magek existing components with your own implementation:
+
+```typescript
+@HealthSensor({
+  id: HEALTH_INDICATORS_IDS.DATABASE,
+})
+```
+
+### Health configuration
+
+Health components are fully configurable, allowing you to display the information you want at any moment.
+
+Configuration options:
+- enabled: If false, this indicator and the components of this indicator will be skipped
+- details: If false, the indicator will not include the details
+- showChildren: If false, this indicator will not include child components in the tree.
+  - Child components will be shown through child urls
+- authorize: Authorize configuration. [See security documentation](https://docs.magek.ai/security/security)
+
+#### Magek components default configuration
+
+Magek sets the following default configuration for its own components:
+
+- enabled: false
+- details: true
+- showChildren: true
+
+Change this configuration using the `config.sensorConfiguration` object. This object provides:
+
+- config.sensorConfiguration.health.globalAuthorizer: Allow to define authorization configuration
+- config.sensorConfiguration.health.magek: Allow to override default Magek components configuration
+  - config.sensorConfiguration.health.magek[COMPONENT_ID].enabled
+  - config.sensorConfiguration.health.magek[COMPONENT_ID].details
+  - config.sensorConfiguration.health.magek[COMPONENT_ID].showChildren
+
+#### User components configuration
+
+Use `@HealthSensor` parameters to configure user components. Example:
+
+```typescript
+@HealthSensor({
+  id: 'user',
+  name: 'my-application',
+  enabled: true,
+  details: true,
+  showChildren: true,
+})
+```
+
+### Create your own health endpoint
+
+Create your own health endpoint with a class annotated with `@HealthSensor` decorator. This class
+should define a `health` method that returns a **HealthIndicatorResult**. Example:
+
+```typescript
+import {
+  MagekConfig,
+  HealthIndicatorResult,
+  HealthIndicatorMetadata,
+  HealthStatus,
+} from '@magek/common'
+
+@HealthSensor({
+  id: 'application',
+  name: 'my-application',
+  enabled: true,
+  details: true,
+  showChildren: true,
+})
+export class ApplicationHealthIndicator {
+  public async health(
+    config: MagekConfig,
+    healthIndicatorMetadata: HealthIndicatorMetadata
+  ): Promise<HealthIndicatorResult> {
+    return {
+      status: HealthStatus.UP,
+    } as HealthIndicatorResult
+  }
+}
+```
+
+### Magek health endpoints
+
+#### magek
+
+- status: UP if and only if graphql function is UP and events are UP
+- details:
+  - magekVersion: Magek version number
+
+#### magek/function
+
+- status: UP if and only if graphql function is UP
+- details:
+  - graphQL_url: GraphQL function url
+  - cpus: Information about each logical CPU core.
+    - cpu:
+      - model: Cpu model. Example: AMD EPYC 7763 64-Core Processor
+      - speed: cpu speed in MHz
+      - times: The number of milliseconds the CPU/core spent in (see iostat)
+        - user:  CPU utilization that occurred while executing at the user level (application)
+        - nice: CPU utilization that occurred while executing at the user level with nice priority.
+        - sys: CPU utilization that occurred while executing at the system level (kernel).
+        - idle: CPU or CPUs were idle and the system did not have an outstanding disk I/O request.
+        - irq: CPU load system
+    - timesPercentages: For each times value, the percentage over the total times
+  - memory:
+    - totalBytes: the total amount of system memory in bytes as an integer.
+    - freeBytes: the amount of free system memory in bytes as an integer.
+
+#### magek/database
+
+- status: UP if and only if events are UP and Read Models are UP
+- details:
+  - urls: Database urls
+
+#### magek/database/events
+
+- status: UP if and only if events are UP
+- details:
+  - file: event database file
+  - count: number of rows
+
+#### magek/database/readmodels
+
+- status: UP if and only if Read Models are UP
+- details:
+  - file: Read Models database file
+  - count: number of total rows
+
+> **Note:**
+> Details will be included only if `details` is enabled
+
+### Health status
+
+Available status are
+
+- UP: The component or subsystem is working as expected
+- PARTIALLY_UP: The component is partially working or has reduced functionality
+- DOWN: The component is not working
+- OUT_OF_SERVICE: The component is out of service temporarily
+- UNKNOWN: The component state is unknown
+
+If a component throw an exception the status will be DOWN
+
+### Securing health endpoints
+
+To configure the health endpoints authorization use `config.sensorConfiguration.health.globalAuthorizer`.
+
+Example:
+
+```typescript
+config.sensorConfiguration.health.globalAuthorizer = {
+      authorize: 'all',
+}
+```
+
+If the authorization process fails, the health endpoint will return a 401 error code
+
+### Example
+
+If all components are enable and showChildren is set to true:
+
+- A Request to <https://your-application-url/sensor/health/> will return:
+
+```text
+├── magek
+│  ├── database
+│    ├── events
+│    └── readmodels
+└  └── function
+```
+
+If the database component is disabled, the same url will return:
+
+```text
+├── magek
+└  └── function
+```
+
+If the request url is <https://your-application-url/sensor/health/database>, the component will not be returned
+
+```text
+[Empty]
+```
+
+And the child components will be disabled too using direct url <https://your-application-url/sensor/health/database/events>
+
+```text
+[Empty]
+```
+
+If database is enabled and showChildren is set to false and using <https://your-application-url/sensor/health/>
+
+```text
+├── magek
+│  ├── database
+│  └── function
+```
+
+using <https://your-application-url/sensor/health/database>, children will not be visible
+
+```text
+└── database
+```
+
+but you can access to them using the component url <https://your-application-url/sensor/health/database/events>
+
+```text
+└── events
+```