Skip to content
This page View Markdown Open in ChatGPT Open in Claude

Post hooks

A post hook is a TypeScript function of yours which runs after an API, with its result in g.res.output. It can reshape the answer, add to it, replace it, send something somewhere, or refuse to answer at all. It lives at the same levels as a pre hook : instance, database, table, API, custom, system and third party API, with optional groups.

Hooks around an API : pre hooks from the instance down to the API, the API, then post hooks from the API up to the instance request Caller with tokens pre hooks · top to bottom Instance every table of it Database every table of it Table every API of it This API get all only… The API database · cache post hooks · bottom to top This API g.res.output Table Database Instance Reply to the caller a pre hook which returns a value, or throws, answers here : nothing after it runs Also hooked Custom APIs System APIs Third party APIs A hook with groups runs only for API users of those groups Cached answers run no hook Calls from your own code (g.sys.db…) skip the hooks unless you pass skipHookRunning: false.

Order

Post hooks run from the narrowest level to the widest : the hooks of the API, then of the table, then of the database, then of the instance, each list top to bottom. The last one to run sees what every other one did.

The code

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
import * as T from 'types';
import * as db from 'db-interfaces';

async function main(g: T.IAMGlobal) {
    if (!g.req.isApiRequestFromUser) return;

    // g.res.output : the answer of the API (data), changeable
    // g.res.statusCode, g.res.warnings, g.res.errors
    // g.req : the request as the API saw it, after the pre hooks
    // g.shared : what the pre hooks left for you
}
module.exports = main;
The hook Effect
returns nothing The next post hook runs, then the answer is sent.
changes g.res.output The answer is what is in g.res.output at the end.
returns a value That value becomes the answer and the remaining post hooks do not run.
throws The request answers with the error, whatever the API did. The database change of the API is not rolled back by that.
  • Hooks run in the sandbox (or on the native process with runOnNativeProcess), within the sandbox timeout of the call.
  • No hook runs when the answer comes from the cache. Calls from your own code skip hooks unless skipHookRunning: false.

Reshape the answer

Hide a field and add a computed one
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
async function main(g: T.IAMGlobal) {
    if (!g.req.isApiRequestFromUser) return;
    const rows = Array.isArray(g.res.output) ? g.res.output : [ g.res.output ];
    for (const row of rows) {
        if (!row) continue;
        delete row.internal_notes;
        row.total_with_tax = Math.round(row.total * 1.18);
    }
}
module.exports = main;

Do something after a write

Audit row and an event after a save
1
2
3
4
5
6
7
8
9
async function main(g: T.IAMGlobal) {
    if (!g.req.isApiRequestFromUser) return;
    await g.sys.db.saveSingleOrMultiple({
        instance: 'mongodb', database: 'shop', collection: 'audit_logs',
        saveData: { api: g.req.reqInfo.apiInfo.id, by: g.req.auth.authAMDB?.email, at: new Date(), took: Date.now() - g.shared.startedAt },
    });
    await g.sys.system.emitEvent('order-placed', g.res.output);
}
module.exports = main;
  • For a notification to WebSocket clients, nothing to write : subscribers of the table are notified after every successful call. Emit a custom WebSocket event with g.sys.system.emitEventWS when the notification needs another shape.
  • For an event after an API hit without code, attach the event to the API on the Events page (automatic trigger).

Streams

On get all by stream and query by stream the rows are already on their way when the post hooks run : g.res.output only holds the last chunk, and a value returned or thrown can not change what was sent. Reshape a stream in a custom API around g.sys.db.getAllByStream instead.

Good to know

  • WebSocket notifications and automatic events run after the post hooks, on the final answer. A post hook which throws still lets the notification go out ; a pre hook which throws does not.
  • Post hooks have versions and a Test button on the API testing page, like pre hooks, and deploy with Git.
← Pre hooks Events