use()

Used for registering a hook - a function that is called whenever BlinkDB executes a certain action like inserting, updating or removing entities (See Actions).

Typical usage of use() looks like this:

use(userTable, async (ctx) => {
  // Call the next registered hook (or the implementation)
  const result = await ctx.next(...ctx.params);
  // Return results
  return result;
});

Parameter	Description
obj	Either a table created by createTable() or an entire database created by createDB(). See Registering a hook.
hook	A callback that will be executed whenever BlinkDB executes an action. See Actions.

Registering a hook

A hook can be registered on a table, and the corresponding callback will trigger whenever BlinkDB executes actions in that given table:

use(userTable, (ctx) => {
  ...
});

Alternatively, if you want the callback to run on actions on any table created with a database, you can register hooks on the database directly:

use(db, (ctx) => {
  ...
});

Call Order

Registered hooks are called in the following order:

1. All logic before await ctx.next() of hooks registered on the database.
2. All logic before await ctx.next() of hooks registered on the table.
3. All logic after await ctx.next() of hooks registered on the table.
4. All logic after await ctx.next() of hooks registered on the database.

Additionally, hooks themselves are called in the reverse order of when they were added. To clarify:

// Register a hook on the entire database
use(db, async (ctx) => {
  console.log("1");
  const result = await ctx.next(...ctx.params);
  console.log("6");
  return result;
});

// Register a hook on the userTable
use(userTable, async (ctx) => {
  console.log("2");
  const result = await ctx.next(...ctx.params);
  console.log("5");
  return result;
});

// Register a second hook on the userTable
// - this will be called after the second hook
use(userTable, async (ctx) => {
  console.log("3");
  const result = await ctx.next(...ctx.params);
  console.log("4");
  return result;
});

// Executing a action will then cause BlinkDB to call the hooks.
// The following call to `insert` will log:
// - 1
// - 2
// - 3
// - 4
// - 5
// - 6
await insert(userTable, someUser);

Actions

Most actions taken by BlinkDB will call middleware, and can therefore be modified, transformed, or canceled. All BlinkDB methods will, when called, execute all middleware with their name:

export type HookAction =
  | "clear"
  | "count"
  | "first"
  | "insert"
  | "insertMany"
  | "many"
  | "one"
  | "remove"
  | "removeMany"
  | "removeWhere"
  | "update"
  | "updateMany"
  | "updateWhere";

The name of the method currently executing a hook can be retrieved with ctx.action, and checked with isAction().

use(userTable, async (ctx) => {
  console.log(ctx.action);
  const result = await ctx.next(...ctx.params);
  return result;
});

// Will log `"insertMany"`.
await insertMany(userTable, []);

isAction()

This function can be used to check whether a hook has been executed by a given action.

use(userTable, async (ctx) => {
  if(isAction(ctx, "count")) {
    console.log("User has executed count()!");
  }
  const result = await ctx.next(...ctx.params);
  return result;
});

It provides the same functionality as a ctx.action === "count" check, but additionally typecasts ctx:

use(userTable, async (ctx) => {
  if(isAction(ctx, "count")) {
    // `result` is now typed as `number`!
    const result = await ctx.next(...ctx.params);
  }
  // Out here, `result` can be anything - a number, one entity, a list of entities...
  const result = await ctx.next(...ctx.params);
  return result;
});