meocord 4.1.0-beta.3 → 4.1.0-beta.4

package/CHANGELOG.md

@@ -1,5 +1,61 @@
 # meocord
 
+## 4.1.0-beta.4
+
+### Minor Changes
+
+- [#137](https://github.com/meocord/meocord/pull/137) [`c778561`](https://github.com/meocord/meocord/commit/c778561f583a1246570881c56348c3b850bc8330) Thanks [@l7aromeo](https://github.com/l7aromeo)! - `@Cooldown` takes `by`, a function of the call that counts calls apart by a value, such as the account a button acts on: `@Cooldown({ seconds: 3600, by: (_context, { uid }: { uid: string }) => uid })` lets a user check each of their accounts in once an hour, where before the first check-in blocked the rest. `by` receives the handler's params as the handler does, after validation and pipes, and the handler's params are checked against the ones `by` declares at compile time. With `per: 'global'`, the limit is per resource across every user. Returning `undefined` counts as before; an error `by` throws goes to the exception filters, and nothing is counted. `inspectHandler(...).cooldowns` now reports `by` alongside `bypass`.
+
+- [#143](https://github.com/meocord/meocord/pull/143) [`add425d`](https://github.com/meocord/meocord/commit/add425d6d37171828d23fb8d6e07532eec349d7f) Thanks [@l7aromeo](https://github.com/l7aromeo)! - `testCooldownStore` in `meocord/testing` checks a `CooldownStore` you write yourself, over Postgres, SQLite, MongoDB or anything else, against the behaviour `MemoryCooldownStore` defines. It registers its cases with your test framework's `describe`, `it` and `expect`, so it runs under Vitest or Jest:
+
+  ```typescript
+  import { testCooldownStore } from 'meocord/testing'
+
+  testCooldownStore('PostgresCooldownStore', () => new PostgresCooldownStore(sql), { describe, it, expect })
+  ```
+
+  It covers calls within a window, a sliding window, `retryAfterMs` counted from the oldest call still in the window, each key counted on its own, calls in the same millisecond kept distinct, and several concurrent calls at the limit where exactly one passes. It uses real time with short windows and takes a few seconds. The README's [Store recipes](https://github.com/meocord/meocord/blob/main/README.md#store-recipes) show stores for Postgres, SQLite and MongoDB.
+
+- [#140](https://github.com/meocord/meocord/pull/140) [`28f0f0a`](https://github.com/meocord/meocord/commit/28f0f0ae8bd660f3dccc332d87f657b1a069c49b) Thanks [@l7aromeo](https://github.com/l7aromeo)! - `ExecutionContext.getHandlerParams<P>()` returns the handler's params, its second argument, to any stage: a command's options, a component's customId params, a modal's fields or a message pattern's params. A guard sees them raw, an interceptor raw before `next.handle()` and validated and piped after it, and a filter as they were when the error was thrown. It returns a patterned `@MessageHandler`'s params too, and is `undefined` for message listeners, reaction and event handlers, and a call no handler was reached for. It is separate from `getParams()`, which stays the running stage's own `{ provide, params }`. `createExecutionContext` takes `handlerParams` for unit tests. `getArgs()` now returns the arguments as they stand too, so after validation and pipes its second argument is the validated and piped params, the same value `getHandlerParams()` returns; in 4.1.0-beta.1 to beta.3 it kept returning the raw arguments.
+
+- [#148](https://github.com/meocord/meocord/pull/148) [`abf9fd8`](https://github.com/meocord/meocord/commit/abf9fd8ba1769ac1cdd2f0c9b1dd1df6de81ff5e) Thanks [@l7aromeo](https://github.com/l7aromeo)! - `@MessageHandler` takes patterns with params, using the `{name}` syntax of customId routes: `@MessageHandler('roll {sides} {note...?}')` gives the handler `{ sides, note }` as its second argument. `{name}` is one word, and words in quotes count as one; `{name...}` takes the rest of the message as typed; `{name?}` and `{name...?}` are optional; the last three come only at the end. `@Validate`, pipes, `@Cooldown({ by })` and `ExecutionContext.getHandlerParams()` see a patterned message handler's params as they do a component's. `@MeoCord({ messages: { prefix, mention, caseSensitive } })` sets the prefix, a string, a list or a function of the message, accepts a mention of the bot when `mention` is on, and matches the prefix and literal words in any case unless `caseSensitive` is set; a handler overrides them with `@MessageHandler('ping', { prefix: false | '?' | ['?', '??'], caseSensitive })`. Only the most specific matching pattern runs, across every controller: more literal words first, then a fixed number of words before a rest, then fewer params. `@MessageHandler()` without a pattern still runs for every message. A pattern that cannot be read, and two that match the same messages, stop the bot at startup. In `meocord/testing`, `resolveRoute(App, { content })` resolves a message, `invoke(Controller, 'method', message)` passes the params the pattern captures, `inspectHandler(...).pattern` reports the pattern, and `createMockMessage()` comes from a user rather than a bot.
+
+  A 4.0 keyword now matches in any case and word by word, only the most specific of two matching patterns runs, two handlers with the same keyword stop the bot at startup, and a configured prefix applies to existing keywords unless they set `prefix: false`. See [Message keywords match in any case, and only one runs](https://github.com/meocord/meocord/blob/main/docs/MIGRATING.md#message-keywords-match-in-any-case-and-only-one-runs).
+
+- [#147](https://github.com/meocord/meocord/pull/147) [`5a2813f`](https://github.com/meocord/meocord/commit/5a2813f72b9d8afc9e0797ee266929b98433ad5c) Thanks [@l7aromeo](https://github.com/l7aromeo)! - Observers see every call MeoCord dispatches once it has settled, for metrics and audit logs. Mark a class `@Observer()`, implement `DispatchObserver`'s `onSettled(context, result)`, and list it in `@MeoCord({ observers })`. It is told about commands, components, modals, autocomplete, message, reaction and event handlers, and interactions no handler matches. The `DispatchResult` carries an `outcome` (`'ran'`, `'denied'`, `'cooldown'`, `'invalid'`, `'error'` or `'not-found'`), `startedAt` in epoch milliseconds, a `durationMs` covering the whole call through the filters and the fallback, the guard that denied it as `deniedBy`, where an interaction's answer stood as `response` (`'replied'`, `'deferred'` or `'unanswered'`), the `error`, and whether a filter or the fallback `handled` it. An optional `onStart(context)` sees the call begin, before the guards, with the same context object `onSettled` later receives, so a `WeakMap` pairs them into a span. Observers run in the order listed, and the call never waits for them: one that is slow never delays a handler, and one that throws is logged while the rest still run. `@Observer({ types })` limits one to some kinds of call. They are services, so they inject dependencies and their `onReady` and `onShutdown` hooks run in dependency order. A message no handler matches is not reported. In `meocord/testing`, `invoke` and `emit` wait for the module's observers, the testing module takes `observers`, and `inspectHandler(...).observers` lists an app's. `npx meocord g ob <name>` generates one with its spec.
+
+- [#144](https://github.com/meocord/meocord/pull/144) [`6798abd`](https://github.com/meocord/meocord/commit/6798abd830f3f4b62b073413ca663d48b062f4b7) Thanks [@l7aromeo](https://github.com/l7aromeo)! - `RedisCooldownStore` in `meocord/common` keeps `@Cooldown` counts on Redis, so they survive a restart and are shared by every shard and process that uses the same server, which keeps `'user'` and `'global'` cooldowns exact under process sharding. MeoCord adds no Redis dependency: give `RedisCooldownStore.using` a function that runs a script with your client, and pass what it returns to `@MeoCord({ cooldownStore })`:
+
+  ```typescript
+  import { RedisCooldownStore } from 'meocord/common'
+
+  // node-redis
+  cooldownStore: RedisCooldownStore.using((script, keys, args) => redis.eval(script, { keys, arguments: args }))
+  // ioredis
+  cooldownStore: RedisCooldownStore.using((script, keys, args) => redis.eval(script, keys.length, ...keys, ...args))
+  ```
+
+  One Lua script checks and records each call as one step, timed by the server's `TIME`, with calls in the same millisecond kept apart and every key set to expire. Keys start with `meocord:cooldown:`, or `{ prefix }`; pass `{ evalsha }` to send the script by its SHA1, in full only when the server answers `NOSCRIPT`. It runs on Redis 5 and later, Valkey, KeyDB, Dragonfly and Upstash; Garnet runs Lua only in part, so check it with `testCooldownStore` first. See [Where calls are counted](https://github.com/meocord/meocord/blob/main/README.md#where-calls-are-counted).
+
+- [#145](https://github.com/meocord/meocord/pull/145) [`8f8690c`](https://github.com/meocord/meocord/commit/8f8690c84bc4e6b2676e86842b0ae3e51129c620) Thanks [@l7aromeo](https://github.com/l7aromeo)! - `ShardedCooldownStore` in `meocord/common` makes `'user'` and `'global'` cooldowns exact under process sharding without a database. Each shard asks the shard manager, which counts every shard's calls in its memory over the IPC the shards already use:
+
+  ```typescript
+  import { ShardedCooldownStore } from 'meocord/common'
+
+  @MeoCord({ controllers: [...], clientOptions: {...}, cooldownStore: ShardedCooldownStore })
+  export default class App {}
+  ```
+
+  Counts are kept while the manager runs, so a shard that restarts keeps them, but they start again when the whole bot restarts. For counts that outlive a restart, or a bot on several hosts, use `RedisCooldownStore`. If the manager does not answer within a second, a shard counts the call itself and warns once. The startup warning about per-shard cooldowns stays silent with this store, and now names both shared stores. See [Where calls are counted](https://github.com/meocord/meocord/blob/main/README.md#where-calls-are-counted).
+
+### Patch Changes
+
+- [#142](https://github.com/meocord/meocord/pull/142) [`400f903`](https://github.com/meocord/meocord/commit/400f903510961d7b181352586f2c693f5039eabc) Thanks [@l7aromeo](https://github.com/l7aromeo)! - A `bundleDependencies` build starts under Bun, and under any devtool.
+
+  - **Bun.** A bundled ES module that probes for CommonJS, as lodash-es does with `typeof exports`, left `module` and `exports` in the bundle's top scope. Bun then read the whole bundle as CommonJS and stopped at startup with `Cannot use import statement with CommonJS-only features`, while Node ran it. Those probes now see `undefined`, as they do in any ES module, so `bun dist/main.js` starts. CommonJS dependencies keep their own `module` and `exports`. Rebuild to pick this up; nothing else changes.
+  - **Eval devtools.** An `eval-*` devtool, set through `output.sourceMap` or `tools.rspack` in the `rsbuild` hook, is built as its non-eval equivalent (`eval-source-map` as `source-map`, plain `eval` as no source map), with a warning at build time. A module evaluated from a string cannot read `import.meta`, so with `bundleDependencies` such a bundle stopped at startup with `SyntaxError: import.meta is only valid inside modules`. To silence the warning, set `output.sourceMap.js` to the non-eval devtool yourself.
+  - Development builds emit `cheap-module-source-map` rather than `eval-source-map`. See [Smaller changes](https://github.com/meocord/meocord/blob/main/docs/MIGRATING.md#smaller-changes) in the upgrade guide.
+
 ## 4.1.0-beta.3
 
 ### Patch Changes

package/README.md

@@ -35,6 +35,9 @@
 - [Command Parameters](#command-parameters)
 - [Subcommands](#subcommands)
 - [Autocomplete](#autocomplete)
+- [Message commands](#message-commands)
+  - [Prefixes](#prefixes)
+  - [Which handler runs](#which-handler-runs)
 - [Interaction responses](#interaction-responses)
   - [Where the interaction happened](#where-the-interaction-happened)
   - [Presenters](#presenters)
@@ -47,7 +50,10 @@
 - [Exception filters](#exception-filters)
 - [Validation and Pipes](#validation-and-pipes)
 - [Cooldowns](#cooldowns)
+- [Observers](#observers)
   - [Where calls are counted](#where-calls-are-counted)
+  - [Checking a store](#checking-a-store)
+  - [Store recipes](#store-recipes)
 - [Custom Decorators](#custom-decorators)
 - [Gateway Events](#gateway-events)
 - [Handler Discovery](#handler-discovery)
@@ -75,6 +81,7 @@
 - **A request pipeline** — [Guards](#guards) decide whether a handler runs, [interceptors](#interceptors) wrap it, [validation and pipes](#validation-and-pipes) check and transform its input, [cooldowns](#cooldowns) limit how often it runs, and [exception filters](#exception-filters) decide what the user is told when something throws. Each applies to a method, a controller, or the whole bot.
 - **Interaction responses** — `respond(interaction)` answers every interaction type correctly from any state, deferred or replied, wherever a user-installed app is used; a presenter styles MeoCord's own answers.
 - **Cooldowns** — `@Cooldown` limits how often a handler runs, per user, server, channel or for everyone, with a pluggable store to share the count across shards.
+- **Observers** — `@Observer` classes hear about every dispatched call once it has settled, with its outcome and duration, for metrics and audit logs, without ever delaying one.
 - **Gateway events** — `@On` and `@Once` handle any discord.js client event on a controller or service, with typed arguments and the same pipeline. `HandlerRegistry` lists every handler for a `/help` command or generated docs.
 - **Lifecycle hooks** — `onReady` and `onShutdown` on any controller or service, in dependency order, for schedulers, cache warm-up and clean shutdown.
 - **Localisation** — One typed catalog per locale for command names, descriptions and replies, checked at compile time.
@@ -495,6 +502,7 @@ npx meocord start --build --prod  # production build + start
 | `interceptor` | `i`   | an interceptor and its spec         |
 | `filter`      | `f`   | an exception filter and its spec    |
 | `pipe`        | `pi`  | a pipe and its spec                 |
+| `observer`    | `ob`  | a dispatch observer and its spec    |
 
 #### Controllers
 
@@ -735,6 +743,89 @@ If no handler claims an option, MeoCord answers with an empty list and logs whic
 
 ---
 
+## Message commands
+
+`@MessageHandler` handles messages: every message, or those matching a pattern. A pattern uses the same `{name}` params as a component's customId, matched word by word:
+
+```typescript
+import { type Message } from 'discord.js'
+import { Controller, MessageHandler } from 'meocord/decorator'
+
+@Controller()
+export class DiceController {
+  // !roll 20 for initiative  ->  { sides: '20', note: 'for initiative' }
+  @MessageHandler('roll {sides} {note...?}')
+  async roll(message: Message, { sides, note }: { sides: string; note?: string }) {
+    const result = 1 + Math.floor(Math.random() * Number(sides))
+    await message.reply(note ? `${result} (${note})` : String(result))
+  }
+
+  // Runs for every message a user sends, after any pattern it matched
+  @MessageHandler()
+  async log(message: Message) {
+    console.log(message.content)
+  }
+}
+```
+
+| In a pattern | Matches                                                                                             |
+| ------------ | --------------------------------------------------------------------------------------------------- |
+| `roll`       | The word `roll`, in any case unless `caseSensitive` is set                                          |
+| `{name}`     | One word. Words in quotes, `"like this"` or `“like this”`, count as one, and the quotes are removed |
+| `{name...}`  | The rest of the message, as typed. Only last                                                        |
+| `{name?}`    | One word, or nothing. Only last; `{name...?}` is the optional rest                                  |
+
+A pattern without params, such as `'hello'`, matches exactly that message. The params arrive as the handler's second argument, so [`@Validate`](#validation-and-pipes), pipes and [`@Cooldown({ by })`](#counting-per-resource) work on them as they do on a component's, and stages read them with `getHandlerParams()`:
+
+```typescript
+@MessageHandler('roll {sides}')
+@Validate(z.object({ sides: z.coerce.number().int().min(2).max(100) }))
+async roll(message: Message, { sides }: { sides: number }) {}
+```
+
+A pattern that cannot be read — `{rest...}` before another word, a name used twice — and two handlers whose patterns match exactly the same messages stop the bot at startup, naming the handlers.
+
+### Prefixes
+
+Set the prefix once, for the whole app, in `@MeoCord({ messages })`:
+
+```typescript
+@MeoCord({
+  controllers: [DiceController],
+  clientOptions: {
+    intents: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildMessages, GatewayIntentBits.MessageContent],
+  },
+  messages: { prefix: '!', mention: true },
+})
+class App {}
+```
+
+- `prefix` is a string, a list such as `['!', '?']`, or a function of the message returning either, which may be async — a server's own prefix, say. Without one, a pattern matches the message as it is. The longest prefix that fits is used, and a space after it is allowed: `! roll 20` works too.
+- `mention: true` also accepts a mention of the bot, `@Bot roll 20`, in place of the prefix.
+- `caseSensitive: true` matches the prefix and a pattern's literal words in the case written. It is off by default. Param values always keep the case they were typed in.
+
+A handler can set its own `prefix` and `caseSensitive`. Its prefix replaces the app's; a mention still counts. `prefix: false` matches the message as it is:
+
+```typescript
+@MessageHandler('ping', { prefix: ['?', '??'] })   // ?ping, ??ping, @Bot ping
+@MessageHandler('good morning', { prefix: false }) // good morning, as typed
+```
+
+### Which handler runs
+
+Only one patterned handler runs for a message, the most specific that matches, across every controller:
+
+1. More literal words win: `roll 20` beats `roll {sides}`, which beats `{anything...}`.
+2. Then a fixed number of words beats a rest: `roll {a} {b}` beats `roll {rest...}`.
+3. Then a pattern without an optional param beats one with it, and fewer params beat more.
+4. Patterns still equal go to the one whose first differing word is literal: `roll {x}` beats `{verb} 6`.
+
+The table is built once at startup, so declaration order and file layout never decide it. Then every `@MessageHandler()` listener runs. Messages from bots, and empty messages, reach no handler. A prefix function that throws goes to the global [exception filters](#exception-filters), then the fallback, and the listeners still run.
+
+To check routing in a test, `resolveRoute(App, { content: '!roll 20' })` returns the handler a message reaches, and `invoke(DiceController, 'roll', createMockMessage({ content: '!roll 20' }))` runs it with the params its pattern captures — see [Testing](#testing).
+
+---
+
 ## Interaction responses
 
 `respond(interaction)` from `meocord/common` is the one place an interaction is answered. It remembers where the answer stands and picks the right Discord call each time, so a handler says what to send, not how:
@@ -847,7 +938,9 @@ Every handler — a command, a component, an autocomplete, a message, a reaction
 
 **Exception filters** surround all of it: an error from any stage or the handler reaches them, and one no filter handles goes to the built-in fallback. The handler, its interceptors and filters, and the fallback all answer through [`respond()`](#interaction-responses), so each sees where the others left the answer.
 
-Validation and pipes apply to command, component and modal handlers, whose options, customId params and fields they check. Cooldowns apply to those and to message handlers. An autocomplete handler, which must answer within three seconds, runs its guards and filters but no interceptors. `@Defer` applies to command, component and modal handlers only.
+**[Observers](#observers)** frame all of it: an observer's `onStart` is called as the call begins, before `@Defer` and the guards, and its `onSettled` once the call has settled and been answered, whatever the outcome, with how it ended and how long it took. The call waits for neither. They also hear about an interaction no handler matches.
+
+Validation and pipes apply to command, component and modal handlers, and to message handlers with a pattern, whose options, customId params, fields and pattern params they check. Cooldowns apply to those and to every message handler. An autocomplete handler, which must answer within three seconds, runs its guards and filters but no interceptors. `@Defer` applies to command, component and modal handlers only.
 
 Guards, interceptors and filters apply at three levels, which run in this order: globally, from `@MeoCord({ guards, interceptors, filters })`; on a controller, for every handler it declares or inherits; and on a method. Cooldowns apply on a controller or a method. A stage also sees what it is running for through `ExecutionContext`, whose `getType()` is `'interaction'`, `'autocomplete'`, `'message'`, `'reaction'` or `'event'`; a guard or interceptor declared with `types` runs only for those, and a subclass inherits them unless it declares its own. A `types` list that can match nothing — empty, or `['autocomplete']` on an interceptor, since interceptors skip autocomplete — throws when the class is decorated.
 
@@ -988,6 +1081,14 @@ async ban(interaction: ChatInputCommandInteraction) { ... }
 
 Use params for configuring one guard (`{ provide, params }`, [above](#passing-options-to-a-guard)), and `createMetadata` for facts about a handler that any guard can read. `ExecutionContext` is injected only into guards: each call gets its own, so a controller or service, which is shared across calls, cannot inject it. The context also gives the handler's arguments (`getArgs()`, `getInteraction()`, `getMessage()`, `getReaction()`), what it is handling (`getType()`), the controller and method (`getController()`, `getHandlerName()`), and the guard's own params (`getParams()`). Values declared with `SetMetadata` are read with their key: `this.context.get<string[]>('roles')`.
 
+`getHandlerParams<P>()` is the handler's params, its second argument: a command's options, a component's customId params or a modal's fields. It is not `getParams()`, which is the running stage's own `{ provide, params }` configuration. The value is read as it stands when a stage asks:
+
+- A guard sees the params raw.
+- An interceptor sees them raw before `next.handle()`, and validated and piped after it, as the handler received them.
+- A filter sees them as they were when the error was thrown.
+
+`getArgs()` follows the same stages, so its second argument is always the value `getHandlerParams()` returns. It is `undefined` for message, reaction and event handlers, which take no params, and for a call no handler was reached for. In a unit test, `createExecutionContext(Controller, 'method', { handlerParams })` sets it.
+
 In a unit test, build the context with `createExecutionContext` from `meocord/testing`:
 
 ```typescript
@@ -1043,7 +1144,7 @@ export class ProfileController { ... }
 
 Apply them like guards: on a method, on a controller, or to every handler with `@MeoCord({ interceptors })`. Global interceptors are outermost, then the controller's, then the method's; within one decorator, the first listed is outermost. A class-level `@UseInterceptor` also covers the handlers a controller inherits.
 
-One instance of an interceptor serves every call, so it can hold a cache or counters; keep per-call state in local variables. For per-use options, pass `{ provide, params }` and read them with `context.getParams()` — they are never assigned onto the shared instance. For the same reason an interceptor cannot inject `ExecutionContext`; the bot refuses to start if one does.
+One instance of an interceptor serves every call, so it can hold a cache or counters; keep per-call state in local variables. For per-use options, pass `{ provide, params }` and read them with `context.getParams()` — they are never assigned onto the shared instance. The call's own input is `context.getHandlerParams()`, validated and piped once `next.handle()` has run. For the same reason an interceptor cannot inject `ExecutionContext`; the bot refuses to start if one does.
 
 Interceptors run when a handler is dispatched, or run with [`invoke`](#running-a-handler-with-invoke) in a test. A controller method called directly runs its guards but no interceptors. Autocomplete handlers run none.
 
@@ -1126,11 +1227,11 @@ import { Command, Validate } from 'meocord/decorator'
 async remind(interaction: ChatInputCommandInteraction, { minutes, note }: { minutes: number; note: string }) {}
 ```
 
-The input is one object: a chat command's options, or a component's customId params together with a modal's fields — what the handler's second argument holds anyway. The handler receives the schema's output, so defaults and coercions apply, and its second parameter is type-checked against it: `{ minutes: string }` above fails to compile.
+The input is one object: a chat command's options, a component's customId params together with a modal's fields, or a [message pattern's](#message-commands) params — what the handler's second argument holds anyway. The handler receives the schema's output, so defaults and coercions apply, and its second parameter is type-checked against it: `{ minutes: string }` above fails to compile.
 
 Invalid input stops the call with a `ValidationError` (from `meocord/common`) whose `issues` list each problem and where it is. The user gets a private reply with them. Schema libraries write their messages in English; an exception filter that maps issues to your own words is the place to localise them.
 
-Validation runs after guards and inside interceptors, so a timing or logging interceptor sees a failure as the handler's error. It applies to command, component and modal handlers only; the bot refuses to start with `@Validate` or `@UsePipe` on a message, reaction, autocomplete or event handler. A handler takes one `@Validate`; a second throws, so combine the schemas into one.
+Validation runs after guards and inside interceptors, so a timing or logging interceptor sees a failure as the handler's error. It applies to command, component and modal handlers, and to message handlers with a pattern; the bot refuses to start with `@Validate` or `@UsePipe` on a message handler without one, or on a reaction, autocomplete or event handler. A handler takes one `@Validate`; a second throws, so combine the schemas into one.
 
 ### Pipes
 
@@ -1181,12 +1282,13 @@ async daily(interaction: ChatInputCommandInteraction) {}
 
 Stacked cooldowns are counted in the order they read, a controller's first, and a call blocked by one has already spent those above it. Put the short one first, as here: a call made 1 second after the last is refused by the 3-second cooldown before it reaches the per-minute one. Written the other way round, each such call would spend one of the 5 before being refused.
 
-| Option    | Default  | Description                                                                                                                             |
-| --------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| `seconds` | —        | The window's length.                                                                                                                    |
-| `uses`    | `1`      | Calls allowed within the window.                                                                                                        |
-| `per`     | `'user'` | Whose calls count together: `'user'`, `'guild'`, `'channel'` or `'global'`. Outside a server, `'guild'` and `'channel'` count per user. |
-| `bypass`  | —        | `(context) => boolean`: exempts a call without counting it, such as one from an owner.                                                  |
+| Option    | Default  | Description                                                                                                                               |
+| --------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `seconds` | —        | The window's length.                                                                                                                      |
+| `uses`    | `1`      | Calls allowed within the window.                                                                                                          |
+| `per`     | `'user'` | Whose calls count together: `'user'`, `'guild'`, `'channel'` or `'global'`. Outside a server, `'guild'` and `'channel'` count per user.   |
+| `bypass`  | —        | `(context) => boolean`: exempts a call without counting it, such as one from an owner.                                                    |
+| `by`      | —        | `(context, params) => string \| number \| undefined`: counts calls apart by a value of the call, within the scope `per` names. See below. |
 
 A blocked call throws `CooldownError` (from `meocord/common`, with `retryAfterMs` and `per`), which the built-in fallback answers only to the caller: "Slow down: try again in 12s." `cooldownMessage(retryAfterMs)` builds that text; an [exception filter](#exception-filters) catching `CooldownError` can say it another way, or in the user's language.
 
@@ -1196,33 +1298,254 @@ Cooldowns are counted under the controller's class name, so the bot refuses to s
 
 For a reusable exemption, compose it: `const Limited = (seconds: number) => applyDecorators(Cooldown({ seconds, bypass: isOwner }))`.
 
+### Counting per resource
+
+`per` decides whose calls count together; `by` splits that count by a value of the call, such as the account a button acts on. A user with three game accounts can then check each of them in once an hour:
+
+```typescript
+@Command('check-in/{ownerId}/{uid}', CommandType.BUTTON)
+@UseGuard(OwnerGuard)
+@Cooldown({ seconds: 3600, by: (_context, { uid }: { uid: string }) => uid })
+async checkIn(interaction: ButtonInteraction, { uid }: { ownerId: string; uid: string }) {}
+```
+
+- `by` receives the call's `ExecutionContext` and the handler's params as the handler receives them: a component's customId params, a command's options, a modal's fields, after `@Validate` and pipes. For a piped object, return a stable id from it, such as `({ account }) => account.uid`.
+- Declare the params `by` reads, or pass them as the type argument, `@Cooldown<{ uid: string }>({ … })`, and a key the handler does not receive, or receives as another type, fails to compile. Undeclared, they are `Record<string, unknown>`.
+- With `per: 'global'`, the limit is per resource across every user.
+- Returning `undefined` counts the call as though there were no `by`. An error `by` throws goes to the [exception filters](#exception-filters), and no cooldown on the handler counts the call.
+- The value is added to the key the store counts under, `Controller.method#index:per:<scope>:by:<value>`, encoded so a value holding `:` cannot count under another's key. `inspectHandler(...).cooldowns` reports `by: true` for a cooldown that has one.
+
 ### Where calls are counted
 
-By default in this process's memory: one count per bot, which drops keys whose calls have all expired. With [process sharding](#sharding), each shard counts on its own, so `'user'` and `'global'` cooldowns allow more than they say — the bot warns at startup. `'guild'` and `'channel'` stay exact, since a server lives on one shard.
+By default in this process's memory: one count per bot, which drops keys whose calls have all expired. With [process sharding](#sharding), each shard counts on its own, so `'user'` and `'global'` cooldowns allow more than they say — the bot warns at startup, unless it binds a shared store. `'guild'` and `'channel'` stay exact, since a server lives on one shard.
+
+| Store                               | Counts                                            | Survives a restart               | Across hosts         |
+| ----------------------------------- | ------------------------------------------------- | -------------------------------- | -------------------- |
+| `MemoryCooldownStore` (the default) | In this process; per shard with process sharding  | No                               | No                   |
+| `ShardedCooldownStore`              | In the shard manager, for every shard on the host | A shard's restart, not the bot's | No                   |
+| `RedisCooldownStore`                | On the Redis server                               | Yes                              | Yes                  |
+| Your own `CooldownStore`            | Where it keeps them                               | As its database does             | As its database does |
+
+To keep counts across restarts, or share them between shards and processes, bind a shared store with `@MeoCord({ cooldownStore })`.
 
-To share one count, extend `CooldownStore` and pass it to `@MeoCord({ cooldownStore })`. It is resolved like a service, so it can inject its client, and its `consume` must check and record a call in one step, so two calls at the limit cannot both pass:
+**Process sharding on one host.** `ShardedCooldownStore` from `meocord/common` needs no database: each shard asks the shard manager, which counts every shard's calls in its memory over the IPC the shards already use, so `'user'` and `'global'` cooldowns are exact across them.
 
 ```typescript
-import { CooldownStore, type CooldownLimit, type CooldownVerdict } from 'meocord/common'
-import { RedisService } from '@src/services/redis.service.js'
+import { ShardedCooldownStore } from 'meocord/common'
 
-@Service()
-export class RedisCooldownStore extends CooldownStore {
-  constructor(private readonly redis: RedisService) {
-    super()
-  }
+@MeoCord({ controllers: [...], clientOptions: {...}, cooldownStore: ShardedCooldownStore })
+export default class App {}
+```
 
-  consume(key: string, { uses, windowMs }: CooldownLimit): Promise<CooldownVerdict> {
-    return this.redis.slidingWindow(key, uses, windowMs) // a sorted set trimmed and counted in one Lua script
-  }
-}
+The manager's counts are kept while it runs: a shard that restarts keeps them, but they start again when the whole bot restarts, as the default store's do. If the manager does not answer within a second, a shard counts the call itself and logs a warning, once. Without process sharding it counts in the one process, which is exact there too.
 
-@MeoCord({ controllers: [...], clientOptions: {...}, cooldownStore: RedisCooldownStore })
+**Redis, and servers that speak its protocol.** `RedisCooldownStore` from `meocord/common` counts each key in a sorted set, trimmed, counted and added to by one Lua script, timed by the server's `TIME` so every process counts by one clock, with every key set to expire. MeoCord depends on no Redis client: give `RedisCooldownStore.using` a function that runs a script with the one you have.
+
+```typescript
+import { RedisCooldownStore } from 'meocord/common'
+import { createClient } from 'redis'
+
+const redis = await createClient({ url: process.env.REDIS_URL }).connect()
+
+@MeoCord({
+  controllers: [...],
+  clientOptions: {...},
+  cooldownStore: RedisCooldownStore.using((script, keys, args) => redis.eval(script, { keys, arguments: args })),
+})
 export default class App {}
 ```
 
+With ioredis, run it as `(script, keys, args) => redis.eval(script, keys.length, ...keys, ...args)`. Keys start with `meocord:cooldown:`; pass `{ prefix }` for your own. Pass `{ evalsha }`, such as `(sha, keys, args) => redis.evalSha(sha, { keys, arguments: args })`, to send the script by its SHA1, and in full only when the server answers `NOSCRIPT`.
+
+The same script runs on Redis 5 and later, Valkey, KeyDB, Dragonfly and Upstash, which runs `EVAL`. Garnet runs Lua only in part: check it with [`testCooldownStore`](#checking-a-store) before relying on it.
+
+**Any other database.** Extend `CooldownStore`. It is resolved like a service, so it can inject its client, and its `consume` must check and record a call in one step, so two calls at the limit cannot both pass. See [Store recipes](#store-recipes) for Postgres, SQLite and MongoDB, and check yours with [`testCooldownStore`](#checking-a-store).
+
 In tests, each `MeoCordTestingModule` counts in a fresh in-memory store; provide `{ provide: CooldownStore, useValue }` to use another. `inspectHandler(Controller, 'method').cooldowns` lists a handler's cooldowns with their defaults.
 
+### Checking a store
+
+A shared store is easy to get subtly wrong. `testCooldownStore` from `meocord/testing` runs the behaviour `MemoryCooldownStore` defines against yours, under Vitest, Jest or any runner with `describe`, `it` and `expect`:
+
+```typescript
+import { testCooldownStore } from 'meocord/testing'
+import { PostgresCooldownStore } from '@src/stores/postgres-cooldown.store.js'
+
+testCooldownStore('PostgresCooldownStore', () => new PostgresCooldownStore(sql), { describe, it, expect })
+```
+
+It checks calls within a window, that the window slides rather than resetting in buckets, that `retryAfterMs` counts from the oldest call still in the window — so "try again in 12s" means the same whatever the store — that each key counts on its own, that calls in the same millisecond stay distinct, and that of several concurrent calls at the limit exactly one passes. It uses real time with short windows, so it takes a few seconds, and each case counts under keys of its own, so it can run against a database that outlives the test. What it cannot see is whether every key expires: a store should give each one an expiry, or clear keys whose calls have all left their window.
+
+### Store recipes
+
+Stores for other databases, each checked with `testCooldownStore`. A store is resolved like a service, so inject your client, and keep the check and the record in one step: a transaction holding a lock on the key, or a single atomic update.
+
+**Postgres** ([postgres.js](https://github.com/porsager/postgres)): a row per call, counted in a transaction that holds an advisory lock on the key, with the database's clock throughout.
+
+```sql
+CREATE TABLE cooldown_calls (key text NOT NULL, at timestamptz NOT NULL DEFAULT clock_timestamp(), id bigserial PRIMARY KEY);
+CREATE INDEX ON cooldown_calls (key, at);
+```
+
+```typescript
+consume(key: string, { uses, windowMs }: CooldownLimit): Promise<CooldownVerdict> {
+  return this.sql.begin(async sql => {
+    await sql`SELECT pg_advisory_xact_lock(hashtextextended(${key}, 0))`
+    const window = sql`${windowMs} * interval '1 millisecond'`
+    await sql`DELETE FROM cooldown_calls WHERE key = ${key} AND at <= clock_timestamp() - ${window}`
+    const [{ count, retry }] = await sql`
+      SELECT count(*)::int AS count,
+             ceil(extract(epoch FROM min(at) + ${window} - clock_timestamp()) * 1000)::int AS retry
+      FROM cooldown_calls WHERE key = ${key}`
+    if (count >= uses) return { allowed: false, retryAfterMs: retry }
+    await sql`INSERT INTO cooldown_calls (key) VALUES (${key})`
+    return { allowed: true, retryAfterMs: 0 }
+  })
+}
+```
+
+A key's rows go when it is next used; clear the rest from time to time with `DELETE FROM cooldown_calls WHERE at < now() - interval '1 day'`, or whatever your longest window is.
+
+**SQLite** ([better-sqlite3](https://github.com/WiseLibs/better-sqlite3)): the same rows in an `IMMEDIATE` transaction, which takes the write lock before reading, so two processes on one database file cannot both take the last use. SQLite shares one host, so `Date.now()` is one clock.
+
+```typescript
+consume(key: string, { uses, windowMs }: CooldownLimit): Promise<CooldownVerdict> {
+  const now = Date.now()
+  const consumeOne = this.db.transaction((): CooldownVerdict => {
+    this.db.prepare('DELETE FROM cooldown_calls WHERE key = ? AND at <= ?').run(key, now - windowMs)
+    const { count, oldest } = this.db
+      .prepare('SELECT count(*) AS count, min(at) AS oldest FROM cooldown_calls WHERE key = ?')
+      .get(key) as { count: number; oldest: number | null }
+    if (count >= uses) return { allowed: false, retryAfterMs: oldest! + windowMs - now }
+    this.db.prepare('INSERT INTO cooldown_calls (key, at) VALUES (?, ?)').run(key, now)
+    return { allowed: true, retryAfterMs: 0 }
+  })
+  return Promise.resolve(consumeOne.immediate())
+}
+```
+
+with `CREATE TABLE cooldown_calls (id INTEGER PRIMARY KEY, key TEXT NOT NULL, at INTEGER NOT NULL)` and an index on `(key, at)`.
+
+**MongoDB**: one document per key, trimmed, counted and appended to by a single `findOneAndUpdate` with an update pipeline, so the check and the record are one atomic write, timed by the server's `$$NOW`. A TTL index on `expiresAt` removes a key once its window has passed.
+
+```typescript
+async consume(key: string, { uses, windowMs }: CooldownLimit): Promise<CooldownVerdict> {
+  const id = randomUUID() // tells this call apart from one in the same millisecond
+  const kept = { $filter: { input: { $ifNull: ['$calls', []] }, cond: { $gt: ['$$this.at', { $subtract: ['$$NOW', windowMs] }] } } }
+  const doc = await this.cooldowns.findOneAndUpdate(
+    { _id: key },
+    [
+      { $set: { calls: kept } },
+      {
+        $set: {
+          calls: { $cond: [{ $lt: [{ $size: '$calls' }, uses] }, { $concatArrays: ['$calls', [{ at: '$$NOW', id }]] }, '$calls'] },
+          expiresAt: { $add: ['$$NOW', windowMs] },
+          now: '$$NOW',
+        },
+      },
+    ],
+    { upsert: true, returnDocument: 'after' },
+  )
+  if (doc!.calls.some((call: { id: string }) => call.id === id)) return { allowed: true, retryAfterMs: 0 }
+  return { allowed: false, retryAfterMs: doc!.calls[0].at.getTime() + windowMs - doc!.now.getTime() }
+}
+```
+
+with `db.cooldowns.createIndex({ expiresAt: 1 }, { expireAfterSeconds: 0 })`.
+
+---
+
+## Observers
+
+An observer is told about every call MeoCord dispatches, once it has settled: commands, components, modals, autocomplete, message, reaction and event handlers, and interactions no handler matches. It is where metrics and audit logs go, since no other stage sees every outcome. Guards run before anything is decided, interceptors never see a call a guard denied or autocomplete, and filters see only errors.
+
+```typescript
+import { Observer } from 'meocord/decorator'
+import { type ExecutionContext } from 'meocord/common'
+import { type DispatchObserver, type DispatchResult } from 'meocord/interface'
+
+@Observer()
+export class MetricsObserver implements DispatchObserver {
+  constructor(private readonly metrics: MetricsService) {}
+
+  onSettled(context: ExecutionContext, { outcome, durationMs }: DispatchResult) {
+    this.metrics.record(context.getType(), context.getHandlerName() ?? 'unrouted', outcome, durationMs)
+  }
+}
+
+@MeoCord({ controllers: [ShopController], observers: [MetricsObserver], clientOptions: { intents: [] } })
+class App {}
+```
+
+`DispatchResult` holds:
+
+| Field        | What it is                                                                                                                |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------- |
+| `outcome`    | `'ran'`, `'denied'`, `'cooldown'`, `'invalid'`, `'error'` or `'not-found'`; see below.                                    |
+| `startedAt`  | When dispatch received the call, in milliseconds since the Unix epoch.                                                    |
+| `durationMs` | From dispatch until the filters and the fallback had answered, from `performance.now()`.                                  |
+| `deniedBy`   | The guard class that denied the call, whether it returned `false` or threw `GuardDeniedError`.                            |
+| `response`   | For an interaction, where its answer stood: `'replied'`, `'deferred'` (deferred and never followed up) or `'unanswered'`. |
+| `error`      | The error the call ended with, when it ended with one.                                                                    |
+| `handled`    | Whether an exception filter or the built-in fallback answered the error; `false` without one.                             |
+
+| Outcome       | When                                                                                                                                   |
+| ------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `'ran'`       | The call settled without an error. An interceptor that answers without calling `next.handle()`, from a cache for instance, counts too. |
+| `'denied'`    | A guard returned `false` (no `error`) or threw `GuardDeniedError`.                                                                     |
+| `'cooldown'`  | A `@Cooldown` refused it with `CooldownError`.                                                                                         |
+| `'invalid'`   | `@Validate` refused its input with `ValidationError`.                                                                                  |
+| `'error'`     | Anything else was thrown, by the handler, a pipe, an interceptor or a guard.                                                           |
+| `'not-found'` | No handler matches the interaction: `CommandNotFoundError`, or an autocomplete no `@Autocomplete` claims (no `error`).                 |
+
+`response` catches a handler that left an interaction hanging: `'deferred'` means the user still sees "thinking…".
+
+What is reported: every interaction, the ones no handler matches included; every message and reaction a handler runs for; and every event handler call. A message no handler matches is not reported: messages are not commands, and most of a server's traffic would reach the observers for nothing.
+
+- **Read-only.** An observer runs outside the call, and the call waits for none of its methods, so a slow observer never delays a handler. One that throws is logged through `Logger`, and the others still run.
+- **In order.** Observers are told one after another, in the order `observers` lists them.
+- **By type.** `@Observer({ types: ['interaction'] })` is told only about those calls, as `ExecutionContext.getType()` reports them. An empty list throws, and a subclass inherits the types unless it declares its own.
+- **A service.** One instance is resolved from the container, so an observer injects services, and its `onReady` and `onShutdown` hooks run in dependency order with the rest; an exporter flushes what it buffered in `onShutdown`, before the services it uses shut down. It cannot inject `ExecutionContext`; each call's context is passed in, and has no controller or handler for an interaction no handler matched.
+- **Testing.** `invoke` and `emit` wait for the module's observers before they resolve, so a test sees what they were told. The testing module takes an `app`'s observers, and `observers` of its own. `inspectHandler(Controller, 'method', { app }).observers` lists the app's.
+
+Generate one with `npx meocord g ob <name>`.
+
+### Tracing a call
+
+`onStart` receives the call as it begins, and `onSettled` for the same call receives the same context object, so a `WeakMap` pairs them: that gives a span for every call, a denied one or one no handler matched included. An observer sees the call from outside, though: a span for work inside the handler, such as a database query nested under the command, comes from an interceptor, which runs within the call. With OpenTelemetry, use both:
+
+```typescript
+// The call's own span, from the moment it arrives, whatever the outcome
+@Observer()
+export class CallSpanObserver implements DispatchObserver {
+  private readonly spans = new WeakMap<ExecutionContext, Span>()
+
+  onStart(context: ExecutionContext) {
+    this.spans.set(context, tracer.startSpan(`${context.getType()} ${context.getHandlerName()}`))
+  }
+
+  onSettled(context: ExecutionContext, { outcome }: DispatchResult) {
+    const span = this.spans.get(context)
+    span?.setAttribute('meocord.outcome', outcome)
+    span?.end()
+  }
+}
+
+// The handler's span, active while it runs, so the spans it starts nest under it
+@Interceptor()
+export class HandlerSpanInterceptor implements InterceptorInterface {
+  async intercept(context: ExecutionContext, next: CallHandler) {
+    return tracer.startActiveSpan(`handler ${context.getHandlerName()}`, async span => {
+      try {
+        return await next.handle()
+      } finally {
+        span.end()
+      }
+    })
+  }
+}
+```
+
 ---
 
 ## Custom Decorators
@@ -1324,7 +1647,7 @@ export class HelpService {
 | `component`    | The customId pattern, such as `profile/{uid}`  | `commandType`                                                 |
 | `modal`        | The customId pattern                           | `commandType`                                                 |
 | `autocomplete` | The command path, then the option it completes |                                                               |
-| `message`      | The keyword, or `undefined` for every message  |                                                               |
+| `message`      | The pattern, or `undefined` for every message  |                                                               |
 | `reaction`     | The emoji, or `undefined` for every reaction   |                                                               |
 | `event`        | The client event                               | `once`                                                        |
 
@@ -1537,7 +1860,7 @@ const controller = module.get(GreetingSlashController)
 
 ### Running a handler with `invoke`
 
-`module.invoke(Controller, 'method', ...args)` runs a handler through the [pipeline](#how-a-handler-runs) dispatch runs: `@Defer`, its guards, class guards first and each once, then its interceptors around validation, pipes, cooldowns and the handler, all inside its exception filters. Guards resolve from the module, so `overrideGuard` stubs and injected `ExecutionContext` work as they do in the bot. Pass the arguments dispatch would: the interaction, message or reaction, then the handler's params. An interaction must be one dispatch could route to the handler: a customId its pattern matches, or the command or subcommand path it handles. One that could not, such as `'something/else'` for `'profile/{id}'`, rejects with a message naming both, so a typo in a test does not pass silently. A mock built without a customId or command name is not checked.
+`module.invoke(Controller, 'method', ...args)` runs a handler through the [pipeline](#how-a-handler-runs) dispatch runs: `@Defer`, its guards, class guards first and each once, then its interceptors around validation, pipes, cooldowns and the handler, all inside its exception filters. Guards resolve from the module, so `overrideGuard` stubs and injected `ExecutionContext` work as they do in the bot. Pass the arguments dispatch would: the interaction, message or reaction, then the handler's params. An interaction must be one dispatch could route to the handler: a customId its pattern matches, or the command or subcommand path it handles. One that could not, such as `'something/else'` for `'profile/{id}'`, rejects with a message naming both, so a typo in a test does not pass silently. A mock built without a customId or command name is not checked. A message passed alone to a [patterned `@MessageHandler`](#message-commands) is checked the same way, and the handler gets the params its pattern captures, after the prefix of the module's `app`: `invoke(DiceController, 'roll', createMockMessage({ content: '!roll 20' }))`.
 
 ```typescript
 import { ButtonInteraction } from 'discord.js'
@@ -1568,7 +1891,7 @@ Pass the interaction alone and `invoke` builds the params as dispatch does: a co
 
 To send a client event to the module's `@On` and `@Once` handlers, use [`emit`](#gateway-events).
 
-To check what a handler is set up with, without running it, use `inspectHandler`. It lists the guards, interceptors, filters and cooldowns dispatch applies, in order, and reads the handler's metadata as `ExecutionContext` does:
+To check what a handler is set up with, without running it, use `inspectHandler`. It lists the guards, interceptors, filters and cooldowns dispatch applies, in order, gives a message handler's `pattern`, and reads the handler's metadata as `ExecutionContext` does:
 
 ```typescript
 import { inspectHandler } from 'meocord/testing'
@@ -1777,7 +2100,7 @@ edited.delete // → a mock fn
 expect(msg.delete).toHaveBeenCalledTimes(1)
 ```
 
-Without arguments the message is empty. Give it an `id`, `content`, `components`, `embeds` and `flags` to test code that reads them, such as a button on a message whose controls `@Defer` locks. Components and embeds may be API JSON, builders or discord.js instances, and `flags` a number, flag names or a `MessageFlagsBitField`:
+Without arguments the message is empty, and its author is a user rather than a bot, so dispatch and `invoke` handle it. Give it an `id`, `content`, `components`, `embeds` and `flags` to test code that reads them, such as a button on a message whose controls `@Defer` locks. Components and embeds may be API JSON, builders or discord.js instances, and `flags` a number, flag names or a `MessageFlagsBitField`:
 
 ```typescript
 const message = createMockMessage({
@@ -1799,8 +2122,8 @@ API JSON and builders are kept as their JSON behind `toJSON()`, which is what `r
 <details>
 <summary><b><code>resolveRoute</code> / <code>findRouteConflicts</code></b></summary>
 
-Tests which handler a component's customId reaches — the same answer dispatch gives, across every
-controller your app registers, most specific pattern first. They read decorator metadata only, so
+Tests which handler a component's customId or a message's content reaches — the same answer dispatch
+gives, across every controller your app registers, most specific pattern first. They read decorator metadata only, so
 they need no Discord client, config or container. They check routing alone: guards are not run, and
 whether a controller's dependencies are bound is for `MeoCordTestingModule` to test.
 
@@ -1818,6 +2141,11 @@ it('routes the profile button to its handler', () => {
   expect(route?.params).toEqual({ ownerId: '111', uid: '8000' })
 })
 
+// A message, after the prefix @MeoCord({ messages }) configures
+it('routes !roll to the dice handler', () => {
+  expect(resolveRoute(App, { content: '!roll 20 for luck' })?.params).toEqual({ sides: '20', note: 'for luck' })
+})
+
 // Patterns that can match the same customId, as a failing test rather than a startup warning.
 it('has no overlapping component patterns', () => {
   expect(findRouteConflicts(App)).toEqual([])
@@ -1825,7 +2153,10 @@ it('has no overlapping component patterns', () => {
 ```
 
 `resolveRoute` returns the `controller`, the `handler` method and its name as `method`, and the
-`params` the pattern captured — or `undefined` when no route handles the customId.
+`params` the pattern captured — or `undefined` when no route handles the customId or message. A
+message never resolves to a `@MessageHandler()` listener, which runs for every message. For an app
+that reads prefixes from a function, pass the one the message has, `{ content, prefix: '?' }`, and
+pass `botId` for a message that mentions the bot.
 
 </details>