---
title: How the Hook System Works
description: How hooks are discovered, resolved and executed — and why discovery is export-based rather than path-based.
---
import { FileTree, Aside } from '@astrojs/starlight/components';
You do not need this page to use hooks. It is here for when you want to know why
the design is the way it is.
## The problem it solves
Request samples are a projection of your API description, rebuilt on every run.
Nothing about a request is stored, so nothing about a request can go stale.
Hooks are different: they are yours, they are the investment, and they have to
survive the description changing underneath them. That makes one question
central — **what is a hook's identity?**
In the first version of the sampler, a hook's identity was its **location**: a
file at `…/launches/[id]/@GET/auth.authorize.ts` applied to whatever sat below
that directory. That is discoverable and requires no naming, and it has one fatal
property: rename a path in the API description and the hook is orphaned at a dead
directory, silently doing nothing. The tree could not tell you, because as far as
the filesystem was concerned nothing had happened.
So a hook's identity is now a **Selector** — the fully-qualified address of a
Transaction — written in the code. A Selector that stops existing is a value that
stops existing, and that is something a compiler and a loader can both see.
A Selector is also the only way Thymian ever writes a Transaction down. Check
lines, test-case names, rule headings, report locations and error messages all
print it verbatim, so any transaction you read in the terminal can be pasted
straight into a hook as its target:
```console
✖ POST /launches/{id}/crew-members (application/json) -> 409
```
```ts
beforeEach(
'POST /launches/{id}/crew-members (application/json) -> 409',
(request) => {
// …
},
);
```
## Discovery
- .thymian/sampler/hooks/
- auth.ts
- launches/
- seed.ts
The loader walks `hooks/` recursively and, for each file:
1. **Keeps** `.ts`, `.mts`, `.cts`, `.js`, `.mjs`, `.cjs`. Skips declaration
files and dot-directories, so an editor's cache inside the tree is not
scanned.
2. **Imports it** through [`jiti`](https://github.com/unjs/jiti), which
transpiles TypeScript on the fly. The bare specifier `@thymian/hooks` is
aliased to a module inside the plugin, which is why a hook runs with nothing
generated and nothing installed beside it.
3. **Collects every export** — named or default — that is a registration, or an
array of them.
A registration is a value, produced by calling `beforeEach`, `afterEach`,
`defineSample`, `authorize`, `beforeAll` or `afterAll`. Nothing is invoked to
find out whether an export is a hook: the check is structural, so a function you
export for your own reasons is never called by accident.
The directory layout carries no meaning. Moving a hook file is a non-event.
### Why registrations are returned values
The obvious alternative is an ambient registry — `beforeEach(…)` pushing into a
module-level list the plugin then reads. It cannot work here. jiti evaluates the
aliased runtime in its own module registry, so the plugin and the hook file hold
_different instances_ of that module: the list the plugin reads is never the list
the hook wrote to. Returning the registration sidesteps the realm boundary
entirely, and export-based discovery is what makes the returned value reachable.
## Order
Two hooks of the same kind on one Transaction both run, in **registration
order**: file order on the outside — hooks-directory-relative, sorted, so it does
not depend on the filesystem — and source order inside each file.
Source order matters because an ES module namespace exposes its keys _sorted_, so
export order is not registration order. Each registration is stamped with a
counter as it is created, and the loader assigns one scan-wide sequence number
once the file order is settled.
## Resolution
Once the description is loaded, the sampler builds a **transaction catalog**: a
bijection between every Transaction and its Selector, sorted by Selector. Then
each registration's target is resolved against it:
| Target | Resolved by |
| ------------------- | --------------------------------------- |
| a Selector | a map lookup |
| a list of Selectors | a lookup each |
| a filter | evaluating it against every Transaction |
Four things make a hook unresolvable, and each gets its own diagnostic naming the
file and the export: a Selector that names nothing, a value that is not a legal
filter value, a path or glob that names nothing, and a filter whose legal values
intersect nothing.
An unresolved hook **fails the run** — before the first request is sent, so
nothing has happened yet. It fails when the _run_ starts rather than when the
description is published, because `thymian sampler validate` has to survive
publishing in order to report every unresolved hook at once instead of dying on
the first.
A hook is never re-bound to a nearby Transaction. That would be the silent
staleness the whole design exists to remove.
## Execution
```
core.request.sample: generate the request → defineSample
http-testing.beforeRequest: [first request ever → beforeAll] → beforeEach …
http-testing.authorize: if the run option and request.authorize agree → authorize
→ the request is sent →
http-testing.afterResponse: afterEach …
core.close: [if a request was sent] afterAll + cleanups, reversed
```
Each of those is an action on Thymian's event bus, so the sampler plugs into the
same seams any plugin can. There is no sampler-specific machinery in the core.
### Mutate in place
Every hook returns nothing. A hook receives the request or response object and
changes it; the return value is discarded.
That is not a style preference. If a return value were honoured, the most
ordinary shorthand there is —
```typescript
beforeEach(sel, (request) => (request.headers['x-trace'] = 'yes'));
```
— evaluates to the string `'yes'`, and the whole request would be replaced by it.
### `beforeAll` and the latch
"Once before the run" has no meaning until something decides when the run starts,
and the sampler's first sight of a run is its first request. So a latch is armed
by the first `beforeRequest`, ahead of that Transaction's own `beforeEach` hooks.
The same latch gates teardown, which is why `thymian sampler show` and
`thymian sampler init` never run somebody's `afterAll`.
The latch is armed _before_ the `beforeAll` callbacks run, so a `beforeAll` that
threw still gets its teardown, and a second request cannot re-run setup that half
succeeded.
### Teardown
The cleanups `beforeAll` returned and the `afterAll` hooks are **one list**, run
in reverse order of registration. So an `afterAll` registered between two
`beforeAll` hooks runs between their cleanups — grouping the two kinds apart
would put it at one end or the other, which is not what "reverse order" means.
Teardown is best-effort: `core.close` happens after the report is written, so a
failure there cannot be acted on. An error is logged as a warning and the rest of
the teardown still runs, because one leaking fixture must not strand the others.
## Cross-endpoint requests
`utils.request` is keyed by Selector and resolved through the same catalog, so
the strings the committed types carry and the strings resolved at run time are
the same strings by construction — there is no second key language to keep in
step.
By default a nested request runs the target's own pipeline, so seeding behaves
like the real run. The active Selector chain travels with the hook context, and
re-entering a Selector already on it fails loudly with the chain printed. The
chain travels in the _context_ rather than living in the runner so that it
describes this call's ancestry rather than whatever the runner did last.
## Further reading
- [Hooks API Reference](/references/plugins/sampler/hooks-api/)
- [How to write a Hook](/guides/hooks/write-hooks/)
- [Migrating from the samples tree](/guides/sampler/migrating-from-the-samples-tree/)