72 lines
2.6 KiB
Markdown
72 lines
2.6 KiB
Markdown
---
|
|
name: tibi-hook-authoring
|
|
description: Write and debug server-side hooks for tibi-server (goja Go JS runtime). Covers IIFE structure, HookResponse/HookException types, context.filter Go-object quirk, single-item vs list retrieval, and MongoDB filter patterns. Use when creating or modifying files in api/hooks/.
|
|
---
|
|
|
|
# tibi-hook-authoring
|
|
|
|
## Hook file structure
|
|
|
|
Wrap every hook in an IIFE:
|
|
|
|
```js
|
|
;(function () {
|
|
/** @type {HookResponse} */
|
|
const response = { status: 200 }
|
|
|
|
// ... hook logic ...
|
|
|
|
return response
|
|
})()
|
|
```
|
|
|
|
Always return a `HookResponse` or throw a `HookException`.
|
|
|
|
## Type safety
|
|
|
|
- Use inline JSDoc type casting: `/** @type {TypeName} */ (value)`.
|
|
- Reference typed collection entries from `types/global.d.ts`.
|
|
- Avoid `@ts-ignore`; use proper casting instead.
|
|
- Use `const` and `let` instead of `var` — the goja runtime supports them.
|
|
|
|
## context.filter — Go object quirk
|
|
|
|
`context.filter` is a Go object, not a regular JS 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 produces an empty filter inside `$and`, which crashes the Go server.
|
|
|
|
## Single-item vs. list retrieval
|
|
|
|
For `GET /:collection/:id`, the Go server sets `_id` automatically from the URL parameter.
|
|
|
|
GET read hooks should **not** set their own `_id` filter for `req.param("id")`. Only add authorization filters (e.g. `{ userId: userId }`).
|
|
|
|
## HookResponse fields (GET hooks)
|
|
|
|
| Field | Purpose |
|
|
| ------------- | ------------------------------------------------------------------- |
|
|
| `filter` | MongoDB filter (list retrieval, or restrict single-item) |
|
|
| `selector` | MongoDB projection (`{ field: 0 }` exclude, `{ field: 1 }` include) |
|
|
| `offset` | Pagination offset |
|
|
| `limit` | Pagination limit |
|
|
| `sort` | Sort specification |
|
|
| `pipelineMod` | Function to manipulate the aggregation pipeline |
|
|
|
|
## context.data for write hooks
|
|
|
|
- `context.data` can be an array for bulk operations — always guard with `!Array.isArray(context.data)`.
|
|
- For POST hooks, `context.data.id` may contain the new entry ID.
|
|
- For PUT/PATCH, `req.param("id")` gives the entry ID.
|