Walkthrough: using Typescript and imports for pb_hooks

[benallfree]

I spent the day trying some different solutions to using pb_hooks in https://pockethost.io. We have some server-side functions that in theory could be moved to hooks, but I found it difficult to manage package dependencies and I really wanted full Typescript support too.

Here's what I came up with. Let me know what you guys think!

Folder structure

Create ./src/hooks/*.pb.ts files. These are your entry points. I recommend making many of them and keeping them focused on specific tasks. While you could make one onRecordAfterUpdateRequest to hold the ocean, it's better to use many purpose-built onRecordAfterUpdateRequest handlers. So make one per .pb.ts file.

pb_hooks/
src/
   hooks/
      some-purposeful-name.pb.ts

Example:

// src/hooks/some-sensible-name.pb.ts

/// <reference path="/path/to/pb_data/types.d.ts" />

onRecordAfterUpdateRequest((e) => {
  console.log(JSON.stringify(e.record)))
}, 'users')

Build step

yarn add -D chokidar tsup

In package.json:

  "scripts": {
    "build:hooks": "tsup ./src/hooks/*.ts -d ./pb_hooks",
    "dev:hooks": "chokidar './src/hooks/**' -c 'yarn build:hooks' --initial",
  }

During development, run yarn dev:hooks to watch for changes to src/hooks and compile them into pb_hooks.

Running PocketBase with your generated hooks

pocketbase --hooksDir=/path/to/pb_hooks

Including libraries, modules, etc.

Add ./src/hooks/lib.ts. This file will serve as the 'kitchen sink' library entry point. You can include all your goodies in it just like you always do. Keep in mind, you'll need to require() this in your hook files, so be aware of how large this library grows. It will build as ./pb_hooks/lib.js which is not autoloaded by PocketBase.

Some Typescript kung fu makes this work by creating a type that is the entire interface to your library:

type Lib = typeof import('./lib')

Using that, you can then require your library and cast it to the Lib type. This works in VSCode, too, even though there is no .js file!

const lib = require(`${__hooks}/lib.js`) as Lib

Putting it all together:

// ./src/hooks/lib.ts example

export const hello = ()=>console.log(`hello from library!`)

To use it in a hook, do this:

// src/hooks/some-sensible-name.pb.ts

type Lib = typeof import('./lib')

onRecordAfterUpdateRequest((e) => {
  const lib = require(`${__hooks}/lib.js`) as Lib
  const { hello } = lib
  hello()
}, 'users')

Special note about assertion functions

If you use Typescript assertion functions, you need to know that they require an explicit type annotation.

Suppose you have

// assert.ts

export function assert<T>(
  v: T | undefined | void | null,
  msg?: string,
): asserts v is T {
  if (!v) {
    throw new Error(msg || `Assertion failure`)
  }
}

In lib.ts, you'll want to do

import { assert } from './assert'
export type Assert = typeof assert
export { assert }

And in your hook files (*.pb.ts), it'll look like this

import { Assert } from './lib'

type Lib = typeof import('./lib')

onRecordAfterUpdateRequest((e) => {
  const lib = require(`${__hooks}/lib.js`) as Lib
  const assert: Assert = lib.assert
  assert(record, `Expected record here`)
}, 'users')