48 lines
2.0 KiB
Markdown
48 lines
2.0 KiB
Markdown
# API Hooks (tibi-server)
|
|
|
|
Hook files run inside the tibi-server Go runtime (goja).
|
|
|
|
## Conventions
|
|
|
|
- Wrap hook files in an IIFE: `;(function () { ... })()`.
|
|
- Always return a HookResponse type or throw a HookException type.
|
|
- Use inline type casting with `/** @type {TypeName} */ (value)` and typed collection entries from `types/global.d.ts`.
|
|
- Avoid `@ts-ignore`; use proper casting instead.
|
|
- Use `const` and `let` instead of `var`. The tibi-server runtime supports modern JS declarations.
|
|
|
|
## context.filter — Go object quirk
|
|
|
|
`context.filter` is not a regular JS object but a Go object. Even when empty, it is **truthy**.
|
|
Always check with `Object.keys()`:
|
|
|
|
```js
|
|
const requestedFilter =
|
|
context.filter &&
|
|
typeof context.filter === "object" &&
|
|
!Array.isArray(context.filter) &&
|
|
Object.keys(context.filter).length > 0
|
|
? context.filter
|
|
: null
|
|
```
|
|
|
|
**Never** use `context.filter || null` — it is always truthy and results in an empty filter object inside `$and`, which crashes the Go server.
|
|
|
|
## Single-item vs. list retrieval
|
|
|
|
For single-item retrieval (`GET /:collection/:id`), the Go server sets `_id` automatically from the URL parameter.
|
|
GET read hooks should therefore **not set their own `_id` filter** for `req.param("id")`;
|
|
instead, only add authorization filters (e.g. `{ userId: userId }`).
|
|
|
|
## HookResponse fields for GET hooks
|
|
|
|
- `filter` — MongoDB filter (list retrieval only, or to restrict single-item retrieval)
|
|
- `selector` — MongoDB projection (`{ fieldName: 0 }` to exclude, `{ fieldName: 1 }` to include)
|
|
- `offset`, `limit`, `sort` — pagination/sorting
|
|
- `pipelineMod` — function to manipulate the aggregation pipeline
|
|
|
|
## Related tests
|
|
|
|
- When creating or modifying collections/hooks: extend or create corresponding API tests in `tests/api/`.
|
|
- After hook changes, run only affected API tests: `npx playwright test tests/api/filename.spec.ts`.
|
|
- When tests fail, clarify whether the hook or the test needs adjustment — coordinate with the user.
|