moost 0.5.32 → 0.6.0

package/skills/moost/decorators.md

@@ -0,0 +1,185 @@
+# Decorators & Metadata — moost
+
+> The decorator system, metadata storage via `@prostojs/mate`, handler registration, and how to create custom decorators.
+
+## Concepts
+
+Moost's decorator system is built on `@prostojs/mate`, a metadata management library. All decorators write to a shared metadata workspace (`'moost'`) via `getMoostMate()`. This metadata is then read during `app.init()` to bind handlers, resolve dependencies, and configure interceptors.
+
+**Key types of decorators:**
+- **Class decorators** — `@Controller()`, `@Injectable()`, `@ImportController()`
+- **Method decorators** — `@Get()`, `@Cli()`, `@Intercept()`, handler registrations
+- **Parameter decorators** — `@Param()`, `@Resolve()`, `@Inject()`, `@Body()`
+- **Property decorators** — `@Inject()`, `@Provide()`, hooks
+
+Metadata is stored per-class and per-method using TypeScript's legacy experimental decorators (`experimentalDecorators: true`, `emitDecoratorMetadata: true`).
+
+## API Reference
+
+### `getMoostMate()`
+
+Returns the singleton `Mate` instance for the `'moost'` metadata workspace.
+
+```ts
+import { getMoostMate } from 'moost'
+
+const mate = getMoostMate()
+
+// Read class metadata
+const classMeta = mate.read(MyController)
+
+// Read method metadata
+const methodMeta = mate.read(MyController.prototype, 'myMethod')
+
+// Write custom metadata via decorator
+mate.decorate('myKey', myValue)           // Overwrites
+mate.decorate('myArray', item, true)      // Appends to array
+```
+
+### `TMoostMetadata` (interface)
+
+The shape of metadata stored per class/method:
+
+```ts
+interface TMoostMetadata<H = {}> {
+  controller?: { prefix?: string }
+  importController?: Array<{ prefix?; typeResolver?; provide? }>
+  injectable?: true | 'FOR_EVENT' | 'SINGLETON'
+  interceptor?: { priority: TInterceptorPriority }
+  interceptors?: TInterceptorData[]
+  handlers?: TMoostHandler<H>[]           // Set by adapter decorators
+  pipes?: TPipeData[]
+  provide?: TProvideRegistry
+  replace?: TReplaceRegistry
+  params: Array<TMateParamMeta & TMoostParamsMetadata>
+  returnType?: Function
+  loggerTopic?: string
+  id?: string                             // Handler ID for path builders
+  // ... and more
+}
+```
+
+### `TMoostHandler<H>` (type)
+
+```ts
+type TMoostHandler<H> = {
+  type: string      // Adapter type identifier ('HTTP', 'WS_MESSAGE', 'CRON', etc.)
+  path?: string     // Route/command path
+} & H               // Custom handler metadata fields
+```
+
+### `@Controller(prefix?: string)`
+
+Marks a class as a controller. The prefix is prepended to all handler paths.
+
+```ts
+@Controller('api/v1')
+class ApiController { }
+```
+
+### `@Injectable(scope?: 'SINGLETON' | 'FOR_EVENT')`
+
+Marks a class for DI registration with a lifecycle scope.
+
+```ts
+@Injectable('SINGLETON')   // One instance for the app lifetime
+class DbService { }
+
+@Injectable('FOR_EVENT')   // New instance per event (request, command, etc.)
+class RequestScoped { }
+```
+
+### `@Description(text: string)`
+
+Adds a description to a class or method (used by swagger, CLI help).
+
+```ts
+@Description('User management endpoints')
+@Controller('users')
+class UserController {
+  @Description('Get user by ID')
+  @Get(':id')
+  getUser() { }
+}
+```
+
+## Common Patterns
+
+### Pattern: Creating a Handler Decorator
+
+All adapter-specific decorators follow the same pattern:
+
+```ts
+import type { TEmpty, TMoostMetadata } from 'moost'
+import { getMoostMate } from 'moost'
+
+function MyDecorator(path?: string): MethodDecorator {
+  return getMoostMate<TEmpty, TMoostMetadata<{ /* extra fields */ }>>().decorate(
+    'handlers',        // Always 'handlers' for handler registration
+    {
+      path,
+      type: 'MY_TYPE', // Unique string your adapter filters by
+      // ...extra fields
+    },
+    true,              // Array mode — accumulates multiple decorators
+  )
+}
+```
+
+### Pattern: Reading Metadata in an Adapter
+
+```ts
+bindHandler<T extends object>(opts: TMoostAdapterOptions<TMyMeta, T>) {
+  const mate = getMoostMate()
+
+  for (const handler of opts.handlers) {
+    if (handler.type !== 'MY_TYPE') continue
+
+    // Read additional method-level metadata
+    const methodMeta = mate.read(opts.fakeInstance, opts.method as string)
+
+    // Read class-level metadata
+    const classMeta = mate.read(opts.fakeInstance)
+
+    // Access custom metadata set by your decorators
+    const myCustomData = methodMeta?.myCustomField
+  }
+}
+```
+
+### Pattern: Dual Parameter/Property Decorator
+
+Some decorators work on both parameters and class properties:
+
+```ts
+function MyValue(): ParameterDecorator & PropertyDecorator {
+  return Resolve(() => computeValue(), 'my-value')
+}
+
+// As parameter:
+@Get('test')
+handler(@MyValue() val: string) { }
+
+// As property:
+@Controller()
+class MyCtrl {
+  @MyValue()
+  val!: string
+
+  @Get('test')
+  handler() { return this.val }
+}
+```
+
+## Best Practices
+
+- Use `getMoostMate()` (not `new Mate()`) — all Moost metadata must share the same workspace
+- Handler decorators must use array mode (`true` as third arg to `decorate`) so multiple decorators can coexist
+- Use distinctive `type` strings to avoid collisions between adapters
+- Keep metadata types lean — store only what `bindHandler` needs
+
+## Gotchas
+
+- `getMoostMate().read(instance, method)` requires the **prototype** instance, not a constructed one — use `opts.fakeInstance` in adapters
+- Metadata is inherited from parent classes by default for class-level metadata (when `inherit: true` is set)
+- TypeScript's `emitDecoratorMetadata` must be enabled for type reflection to work (`design:type`, `design:paramtypes`, `design:returntype`)

package/skills/moost/di.md

@@ -0,0 +1,161 @@
+# Dependency Injection — moost
+
+> DI container powered by `@prostojs/infact`, scoping strategies, provider registration, and injection patterns.
+
+## Concepts
+
+Moost's DI is built on `@prostojs/infact`. It supports two scopes:
+
+- **SINGLETON** — One instance per application. Created during `init()` or on first access.
+- **FOR_EVENT** — One instance per event (HTTP request, CLI command, etc.). Cleaned up when the event scope is unregistered.
+
+DI resolution happens automatically during the handler lifecycle — controller instances, interceptors, and injected dependencies are all resolved through the same container.
+
+### Scope Lifecycle
+
+```
+app.init()
+  → SINGLETON instances created (once)
+
+Event arrives:
+  → DI scope registered (useScopeId + registerEventScope)
+  → FOR_EVENT instances created on demand
+  → Handler executes
+  → DI scope unregistered → FOR_EVENT instances released
+```
+
+## API Reference
+
+### `@Injectable(scope?: 'SINGLETON' | 'FOR_EVENT' | true)`
+
+Marks a class as DI-managed. `true` is an alias for `'SINGLETON'`.
+
+```ts
+@Injectable('SINGLETON')
+class DatabaseService {
+  constructor() { /* connects once */ }
+}
+
+@Injectable('FOR_EVENT')
+class RequestContext {
+  // Fresh instance per request/event
+}
+```
+
+### `@Inject(token: string | symbol | Class)`
+
+Explicit injection by token. Use when automatic type-based resolution isn't sufficient.
+
+```ts
+@Injectable()
+class MyService {
+  constructor(@Inject('CONFIG') private config: AppConfig) {}
+}
+```
+
+### `@Provide(token?, value?)`
+
+Registers a value or factory in the DI container from a controller/class.
+
+```ts
+@Controller()
+class AppController {
+  @Provide('APP_VERSION')
+  version = '1.0.0'
+}
+```
+
+### `@Circular(() => Type)`
+
+Handles circular dependency references by deferring resolution.
+
+```ts
+@Injectable()
+class ServiceA {
+  constructor(@Circular(() => ServiceB) private b: ServiceB) {}
+}
+```
+
+### `createProvideRegistry(...entries)`
+
+Creates a provider registry for adapter `getProvideRegistry()`.
+
+```ts
+import { createProvideRegistry } from 'moost'
+
+const registry = createProvideRegistry(
+  [MyClass, () => myInstance],
+  ['string-token', () => someValue],
+)
+```
+
+### `createReplaceRegistry(...entries)`
+
+Creates a replacement registry for overriding existing providers (useful for testing).
+
+```ts
+import { createReplaceRegistry } from 'moost'
+
+const replacements = createReplaceRegistry(
+  [RealService, () => new MockService()],
+)
+```
+
+### `getMoostInfact()`
+
+Returns the singleton `Infact` DI container instance. Mainly used internally by adapters.
+
+```ts
+import { getMoostInfact } from 'moost'
+
+const infact = getMoostInfact()
+infact.registerScope(scopeId)
+infact.unregisterScope(scopeId)
+```
+
+## Common Patterns
+
+### Pattern: Adapter DI Providers
+
+Adapters expose their services to controllers via `getProvideRegistry()`:
+
+```ts
+class MoostHttp implements TMoostAdapter<THttpHandlerMeta> {
+  getProvideRegistry() {
+    return createProvideRegistry(
+      [WooksHttp, () => this.getHttpApp()],
+      [HttpServer, () => this.getHttpApp().getServer()],
+    )
+  }
+}
+```
+
+### Pattern: Scope Cleanup for Long-lived Events
+
+For events that outlive a handler call, adapters manually manage scope lifecycle:
+
+```ts
+const fn = defineMoostEventHandler({
+  manualUnscope: true,
+  hooks: {
+    init: ({ unscope }) => {
+      // Defer cleanup to when the event truly ends
+      onEventEnd(() => unscope())
+    },
+  },
+})
+```
+
+## Best Practices
+
+- Default to `SINGLETON` scope unless instances need per-event state
+- Use `FOR_EVENT` for anything that holds request-specific data (user context, auth state)
+- Adapters should provide both class tokens and string tokens in `getProvideRegistry()`
+- Avoid manual `getMoostInfact()` calls in application code — use decorators instead
+
+## Gotchas
+
+- `SINGLETON` instances are created during `app.init()` inside a synthetic event context — composables may not behave as expected in constructors
+- `FOR_EVENT` instances are only available during event processing — injecting them outside an event context will fail
+- Circular dependencies require `@Circular(() => Type)` — without it, the container throws at resolution time
+- Scope IDs are monotonic integers (not UUIDs) for performance — don't rely on their format

package/skills/moost/interceptors.md

@@ -0,0 +1,199 @@
+# Interceptors — moost
+
+> Interceptor lifecycle, priority levels, `@Intercept` decorator, `InterceptorHandler` internals, and creating custom interceptors.
+
+## Concepts
+
+Interceptors wrap handler execution in an onion-like pattern. They can:
+- **Short-circuit** — Return a response before the handler runs
+- **Modify responses** — Transform the handler's return value
+- **Handle errors** — Catch and replace errors
+- **Add side effects** — Logging, tracing, auth checks
+
+### Priority Levels
+
+Interceptors run in priority order (lowest first):
+
+| Priority | Constant | Typical Use |
+|----------|----------|-------------|
+| 0 | `BEFORE_ALL` | Logging, tracing setup |
+| 10 | `BEFORE_GUARD` | Pre-auth setup |
+| 20 | `GUARD` | Authentication/authorization checks |
+| 30 | `AFTER_GUARD` | Post-auth enrichment |
+| 40 | `INTERCEPTOR` | General-purpose (default) |
+| 50 | `CATCH_ERROR` | Error handling |
+| 60 | `AFTER_ALL` | Response transformation, cleanup |
+
+### Lifecycle Phases
+
+```
+before phase (all interceptors, in priority order)
+  └─ Each can return a value to short-circuit
+handler execution
+after phase (in LIFO/reverse order)
+  └─ Each receives the response, can modify it
+onError phase (if handler threw)
+  └─ Each receives the error, can replace it
+```
+
+The after/error phases use **LIFO order** (last registered runs first) — creating a wrap-around pattern where the outermost interceptor has first and last access.
+
+## API Reference
+
+### `@Intercept(handler, priority?)`
+
+Registers an interceptor on a class or method. The handler can be a class or a functional interceptor definition.
+
+```ts
+import { Intercept, TInterceptorPriority } from 'moost'
+
+@Intercept(MyGuard, TInterceptorPriority.GUARD)
+@Controller()
+class ProtectedController { }
+
+@Intercept(loggingInterceptor)
+@Get('data')
+getData() { }
+```
+
+### Functional Interceptor (TInterceptorDef)
+
+```ts
+import type { TInterceptorDef } from 'moost'
+
+const myInterceptor: TInterceptorDef = {
+  // Called before handler — return value to short-circuit
+  before(reply: (response: unknown) => void) {
+    // Optional: reply(value) to skip handler
+  },
+
+  // Called after handler (or after before's reply)
+  after(response: unknown, reply: (response: unknown) => void) {
+    // Optional: modify response via reply(newValue)
+  },
+
+  // Called if handler threw
+  onError(error: unknown, reply: (response: unknown) => void) {
+    // Optional: recover from error via reply(fallbackValue)
+  },
+}
+```
+
+### Class-Based Interceptor
+
+```ts
+import { Injectable, Before, After, OnError } from 'moost'
+
+@Injectable()
+class LoggingInterceptor {
+  @Before()
+  before() {
+    console.log('Before handler')
+    // Return undefined to continue, or return a value to short-circuit
+  }
+
+  @After()
+  after(response: unknown) {
+    console.log('After handler:', response)
+    // Return undefined to keep original, or return new value
+  }
+
+  @OnError()
+  onError(error: unknown) {
+    console.error('Handler error:', error)
+  }
+}
+```
+
+### `InterceptorHandler` (class)
+
+Used internally by `defineMoostEventHandler`. You don't create these directly — they're provided via `opts.getIterceptorHandler()`.
+
+Key properties:
+- `count` — Total number of interceptors (0 means skip interceptor phase)
+- `countAfter` — Number of after-phase handlers
+- `countOnError` — Number of error-phase handlers
+
+Key methods:
+- `before()` — Runs all before interceptors. Returns early response or `undefined`
+- `fireAfter(response)` — Runs after/error handlers in LIFO order. Returns final response
+
+## Common Patterns
+
+### Pattern: Auth Guard
+
+```ts
+const authGuard: TInterceptorDef = {
+  before(reply) {
+    const token = useHeaders().get('authorization')
+    if (!token) {
+      reply(new HttpError(401, 'Unauthorized'))
+    }
+  },
+}
+
+@Intercept(authGuard, TInterceptorPriority.GUARD)
+@Controller('protected')
+class ProtectedController { }
+```
+
+### Pattern: Response Wrapper
+
+```ts
+const wrapResponse: TInterceptorDef = {
+  after(response, reply) {
+    reply({ data: response, timestamp: Date.now() })
+  },
+}
+```
+
+### Pattern: Global Error Handler
+
+```ts
+app.interceptor({
+  handler: {
+    onError(error, reply) {
+      if (error instanceof HttpError) {
+        reply({ error: error.message, status: error.statusCode })
+      }
+    },
+  },
+  priority: TInterceptorPriority.CATCH_ERROR,
+})
+```
+
+## Integration
+
+### With Adapters
+
+Adapters receive `getIterceptorHandler` in `bindHandler()` options. Pass it through to `defineMoostEventHandler()` — interceptors are handled automatically.
+
+For not-found handlers, use `moost.getGlobalInterceptorHandler()` to run global interceptors (CORS, logging) even on unmatched routes.
+
+### With Context Types
+
+Interceptors can check `contextType` to apply only to specific event types:
+
+```ts
+const httpOnly: TInterceptorDef = {
+  before() {
+    // This interceptor is registered globally but only meaningful for HTTP
+    // Check event type if needed
+  },
+}
+```
+
+## Best Practices
+
+- Use `GUARD` priority for auth checks — they run before general interceptors
+- Use `AFTER_ALL` for response transformations — they run after everything else
+- Use `CATCH_ERROR` for error recovery — keeps error handling separate from business logic
+- Prefer functional interceptors for simple logic, class-based for complex logic requiring DI
+- Return `undefined` from `before()` to continue to the handler; return a value to short-circuit
+
+## Gotchas
+
+- After-phase interceptors run in **LIFO** order (reverse of registration) — the last registered interceptor's `after()` runs first
+- If `before()` returns a value, the handler is **skipped** but after-phase interceptors still run
+- Error interceptors receive the error as the `response` parameter, not as a thrown exception
+- `InterceptorHandler.count === 0` means no interceptors — the entire interceptor phase is skipped for performance