@magek/mcp-server 0.0.8

package/docs/advanced/instrumentation.md

@@ -0,0 +1,135 @@
+---
+title: "Instrumentation"
+group: "Advanced"
+---
+
+# Magek instrumentation
+
+## Trace Decorator
+The Trace Decorator is a **Magek** functionality that facilitates the reception of notifications whenever significant events occur in Magek's core, such as event dispatching or migration execution.
+
+### Usage
+To configure a custom tracer, you need to define an object with two methods: onStart and onEnd. The onStart method is called before the traced method is invoked, and the onEnd method is called after the method completes. Both methods receive a TraceInfo object, which contains information about the traced method and its arguments.
+
+Here's an example of a custom tracer that logs trace events to the console:
+
+```typescript
+import {
+  TraceParameters,
+  MagekConfig,
+  TraceActionTypes,
+} from '@magek/common'
+
+class MyTracer {
+  static async onStart(config: MagekConfig, actionType: string, traceParameters: TraceParameters): Promise<void> {
+    console.log(`Start ${actionType}: ${traceParameters.className}.${traceParameters.methodName}`)
+  }
+
+  static async onEnd(config: MagekConfig, actionType: string, traceParameters: TraceParameters): Promise<void> {
+    console.log(`End ${actionType}: ${traceParameters.className}.${traceParameters.methodName}`)
+  }
+}
+```
+
+You can then configure the tracer in your Magek application's configuration:
+
+```typescript
+
+const config: MagekConfig = {
+// ...other configuration options...
+  trace: {
+    enableTraceNotification: true,
+    onStart: MyTracer.onStart,
+    onEnd: MyTracer.onStart,
+  }
+}
+```
+
+In the configuration above, we've enabled trace notifications and specified our onStart and onEnd as the methods to use. Verbose disable will reduce the amount of information generated excluding the internal parameter in the trace parameters. 
+
+Setting `enableTraceNotification: true` would enable the trace for all actions. You can either disable them by setting it to `false` or selectively enable only specific actions using an array of TraceActionTypes.
+
+```typescript
+
+const config: MagekConfig = {
+// ...other configuration options...
+  trace: {
+    enableTraceNotification: [TraceActionTypes.DISPATCH_EVENT, TraceActionTypes.MIGRATION_RUN, 'OTHER'],
+    includeInternal: false,
+    onStart: MyTracer.onStart,
+    onEnd: MyTracer.onStart,
+  }
+}
+```
+
+In this example, only DISPATCH_EVENT, MIGRATION_RUN and 'OTHER' actions will trigger trace notifications.
+
+### TraceActionTypes
+
+The TraceActionTypes enum defines all the traceable actions in Magek's core:
+
+```typescript
+export enum TraceActionTypes {
+  CUSTOM,
+  EVENT_HANDLERS_PROCESS,
+  HANDLE_EVENT,
+  DISPATCH_ENTITY_TO_EVENT_HANDLERS,
+  DISPATCH_EVENTS,
+  FETCH_ENTITY_SNAPSHOT,
+  STORE_SNAPSHOT,
+  LOAD_LATEST_SNAPSHOT,
+  LOAD_EVENT_STREAM_SINCE,
+  ENTITY_REDUCER,
+  READ_MODEL_FIND_BY_ID,
+  GRAPHQL_READ_MODEL_SEARCH,
+  READ_MODEL_SEARCH,
+  COMMAND_HANDLER,
+  MIGRATION_RUN,
+  GRAPHQL_DISPATCH,
+  GRAPHQL_RUN_OPERATION,
+  SCHEDULED_COMMAND_HANDLER,
+  DISPATCH_SUBSCRIBER_NOTIFIER,
+  READ_MODEL_SCHEMA_MIGRATOR_RUN,
+  SCHEMA_MIGRATOR_MIGRATE,
+}
+```
+
+### TraceInfo
+The TraceInfo interface defines the data that is passed to the tracer's onBefore and onAfter methods:
+
+```typescript
+export interface TraceInfo {
+  className: string
+  methodName: string
+  args: Array<unknown>
+  traceId: UUID
+  elapsedInvocationMillis?: number
+  internal: {
+    target: unknown
+    descriptor: PropertyDescriptor
+  }
+  description?: string
+}
+```
+
+`className` and `methodName` identify the function that is being traced.
+
+### Adding the Trace Decorator to Your own async methods
+In addition to using the Trace Decorator to receive notifications when events occur in Magek's core, you can also use it to trace your own methods. To add the Trace Decorator to your own methods, simply add @Trace() before your method declaration.
+
+Here's an example of how to use the Trace Decorator on a custom method:
+
+```typescript
+
+export class MyCustomClass {
+  @Trace('OTHER')
+  public async myCustomMethod(config: MagekConfig, logger: Logger): Promise<void> {
+    logger.debug('This is my custom method')
+    // Do some custom logic here...
+  }
+}
+```
+
+In the example above, we added the @Trace('OTHER') decorator to the myCustomMethod method. This will cause the method to emit trace events when it's invoked, allowing you to trace the flow of your application and detect performance bottlenecks or errors.
+
+Note that when you add the Trace Decorator to your own methods, you'll need to configure your Magek instance to use a tracer that implements the necessary methods to handle these events.

package/docs/advanced/register.md

@@ -0,0 +1,119 @@
+---
+title: "Register"
+group: "Advanced"
+---
+
+# Advanced uses of the Register object
+
+The Register object is a built-in object that is automatically injected by the framework into all command or event handlers to let users interact with the execution context. It can be used for a variety of purposes, including:
+
+* Registering events to be emitted at the end of the command or event handler
+* Manually flush the events to be persisted synchronously to the event store
+* Access the current signed in user, their roles and other claims included in their JWT token
+* In a command: Access the request context or alter the HTTP response headers
+
+## Registering events
+
+When handling a command or event, you can use the Register object to register one or more events that will be emitted when the command or event handler is completed. Events are registered using the `register.events()` method, which takes one or more events as arguments. For example:
+
+```typescript
+public async handle(register: Register): Promise<void> {
+  // Do some work...
+  register.events(new OrderConfirmed(this.orderID))
+  // Do more work...
+}
+```
+
+In this example, we're registering an OrderConfirmed event to be persisted to the event store when the handler finishes. You can also register multiple events by passing them as separate arguments to the register.events() method:
+
+```typescript
+public async handle(register: Register): Promise<void> {
+  // Do some work...
+  register.events(
+    new OrderConfirmed(this.orderID),
+    new OrderShipped(this.orderID)
+  )
+  // Do more work...
+}
+```
+
+It's worth noting that events registered with `register.events()` aren't immediately persisted to the event store. Instead, they're stored in memory until the command or event handler finishes executing. To force the events to be persisted immediately, you can call the `register.flush()` method that is described in the next section.
+
+## Manually flush the events
+
+As mentioned in the previous section, events registered with `register.events()` aren't immediately persisted to the event store. Instead, they're stored in memory until the command or event handler finishes its execution, but this doesn't work in all situations, sometimes it's useful to store partial updates of a longer process, and some scenarios could accept partial successes. To force the events to be persisted and wait for the database to confirm the write, you can use the `register.flush()` method.
+
+The `register.flush()` method takes no arguments and returns a promise that resolves when the events have been successfully persisted to the event store. For example:
+
+```typescript
+public async handle(register: Register): Promise<void> {
+  // Do some work...
+  register.events(new OrderConfirmed(this.orderID))
+  await register.flush()
+  const mailID = await sendConfirmationEmail(this.orderID)
+  register.events(new MailSent(this.orderID, mailID))
+  // Do more work...
+}
+```
+
+In this example, we're calling `register.flush()` after registering an `OrderConfirmed` event to ensure that it's persisted to the event store before continuing with the rest of the handler logic. In this way, even if an error happens while sending the confirmation email, the order will be persisted.
+
+## Access the current signed in user
+
+When handling a command or event, you can use the injected `Register` object to access the currently signed-in user as well as any metadata included in their JWT token like their roles or other claims (the specific claims will depend on the specific auth provider used). To do this, you can use the `currentUser` property. This property is an instance of the `UserEnvelope` class, which has the following properties:
+
+```typescript
+export interface UserEnvelope {
+  id?: string // An optional identifier of the user
+  username: string // The unique username of the current user
+  roles: Array<string> // The list of role names assigned to this user
+  claims: Record<string, unknown> // An object containing the claims included in the body of the JWT token
+  header?: Record<string, unknown> // An object containing the headers of the JWT token for further verification
+}
+```
+
+For example, to access the username of the currently signed-in user, you can use the `currentUser.username` property:
+
+```typescript
+public async handle(register: Register): Promise<void> {
+  console.log(`The currently signed-in user is ${register.currentUser?.username}`)
+}
+
+// Output: The currently signed-in user is john.doe
+```
+
+## Command-specific features
+
+The command handlers are executed as part of a GraphQL mutation request, so they have access to a few additional features that are specific to commands that can be used to access the request context or alter the HTTP response headers.
+
+### Access the request context
+
+The request context is injected in the command handler as part of the register command and you can access it using the `context` property. This property is an instance of the `ContextEnvelope` interface, which has the following properties:
+
+```typescript
+export interface ContextEnvelope {
+  /** Decoded request header and body */
+  request: {
+    headers: unknown
+    body: unknown
+  }
+  /** Runtime-dependent raw request context object */
+  rawContext: unknown
+}
+```
+
+The `request` property exposes a normalized version of the request headers and body that can be used regardless the provider. We recommend using this property instead of the `rawContext` property, as it will be more portable across providers.
+
+The `rawContext` property exposes the full raw request context as it comes in the original request.
+
+### Alter the HTTP response headers
+
+Finally, you can use the `responseHeaders` property to alter the HTTP response headers that will be sent back to the client. This property is a plain Typescript object which is initialized with the default headers. You can add, remove or modify any of the headers by using the standard object methods:
+
+```typescript
+public async handle(register: Register): Promise<void> {
+  register.responseHeaders['X-My-Header'] = 'My custom header'
+  register.responseHeaders['X-My-Other-Header'] = 'My other custom header'
+  delete register.responseHeaders['X-My-Other-Header']
+}
+```

package/docs/advanced/sensor.md

@@ -0,0 +1,10 @@
+---
+title: "Sensors"
+group: "Advanced"
+---
+
+# Sensor
+
+## Related Topics
+
+- [Sensor Health](health/sensor-health.md) - Health monitoring and indicators

package/docs/advanced/testing.md

@@ -0,0 +1,96 @@
+---
+title: "Testing"
+group: "Advanced"
+---
+
+# Testing
+
+Magek applications are fully tested by default. This means that you can be sure that your application will work as expected. However, you can also write your own tests to check that your application behaves as you expect. In this section, we will leave some recommendations on how to test your Magek application.
+
+## Testing Magek applications
+
+To properly test a Magek application, you should create a `test` folder at the same level as the `src` one. Apart from that, tests' names should have the `<my_test>.test.ts` format.
+
+When a Magek application is generated, you will have a script in a `package.json` like this:
+
+```typescript
+"scripts": {
+  "test": "nyc --extension .ts mocha --forbid-only \"test/**/*.test.ts\""
+}
+```
+
+The only thing that you should add to this line are the `AWS_SDK_LOAD_CONFIG=true` and `MAGEK_ENV=test` environment variables, so the script will look like this:
+
+```typescript
+"scripts": {
+  "test": "AWS_SDK_LOAD_CONFIG=true MAGEK_ENV=test nyc --extension .ts mocha --forbid-only \"test/**/*.test.ts\""
+}
+```
+
+### Testing with `sinon-chai`
+
+The `MagekConfig` can be accessed through the `Magek.config` on any part of a Magek application. To properly mock it for your objective, we really recommend to use sinon `replace` method, after configuring your `Magek.config` as desired.
+
+In the example below, we add 2 "empty" read-models, since we are iterating `Magek.config.readModels` from a command handler:
+
+```typescript
+// Test
+
+const config = new MagekConfig('test')
+config.appName = 'testing-time'
+config.runtime = {} as Runtime
+config.readModels['WoW'] = {} as ReadModelMetadata
+config.readModels['Amazing'] = {} as ReadModelMetadata
+replace(Magek, 'config', config)
+
+const spyMyCall = spy(MyCommand, 'myCall')
+const command = new MyCommand('1', true)
+const register = new Register('request-id-1')
+const registerSpy = spy(register, 'events')
+await MyCommand.handle(command, register)
+
+expect(spyMyCall).to.have.been.calledOnceWithExactly('WoW')
+expect(spyMyCall).to.have.been.calledOnceWithExactly('Amazing')
+expect(registerSpy).to.have.been.calledOnceWithExactly(new MyEvent('1', 'WoW'))
+expect(registerSpy).to.have.been.calledOnceWithExactly(new MyEvent('1', 'Amazing'))
+```
+
+```typescript
+// Example code
+public static async handle(command: MyCommand, register: Register): Promise<void> {
+  const readModels = Magek.config.readModels
+  for (const readModelName in readModels) {
+    myCall(readModelName)
+    register.events(new MyEvent(command.ID, readModelName))
+  }
+}
+```
+
+### Recommended files
+
+These are some files that might help you speed up your testing with Magek.
+
+```typescript
+// <root_dir>/test/expect.ts
+
+chai.use(require('sinon-chai'))
+chai.use(require('chai-as-promised'))
+
+export const expect = chai.expect
+```
+
+This `expect` method will help you with some more additional methods like `expect(<my_stub>).to.have.been.calledOnceWithExactly(<my_params..>)`
+
+```yaml
+# <root_dir>/.mocharc.yml
+diff: true
+require: 'ts-node/register'
+extension:
+  - ts
+package: './package.json'
+recursive: true
+reporter: 'spec'
+timeout: 5000
+full-trace: true
+bail: true
+```

package/docs/advanced/touch-entities.md

@@ -0,0 +1,45 @@
+---
+title: "Touch Entities"
+group: "Advanced"
+---
+
+# TouchEntities
+
+Magek provides a way to refresh the value of an entity and update the corresponding ReadModels that depend on it.
+This functionality is useful when a new projection is added to a ReadModel and you want to apply it retroactively to the events that have already occurred.
+It is also helpful when there was an error when calculating a ReadModel or when the snapshot of an entity was not generated.
+
+To migrate an existing entity to a new version, you need to call `MagekTouchEntityHandler.touchEntity` to touch entities.
+For example, this command will touch all the entities of the class Cart.:
+
+```typescript
+
+@Command({
+  authorize: 'all',
+})
+export class TouchCommand {
+  public constructor() {}
+
+  public static async handle(_command: TouchCommand, _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))
+    )
+    if (!carts || carts.length === 0) {
+      return
+    }
+    await Promise.all(
+      carts.map(async (cart) => {
+        const validCart = cart!
+        await MagekTouchEntityHandler.touchEntity('Cart', validCart.id)
+        console.log('Touched', validCart)
+        return validCart.id
+      })
+    )
+  }
+}
+```
+
+Please note that touching entities is an advanced feature that should be used with caution and only when necessary.
+It may affect your application performance and consistency if not used properly.