tibi-svelte-starter/api/hooks/AGENTS.md

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():

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.