PocketBase Typed SDK

• PocketBase Typed SDK
  • Overview
  • Demo
  • Installation
  • Usage
    • Defining schema
      • Schema interface
    • Instantiating the SDK
    • Building query
  • Helper functions for filter and sort
    • Filter
      • and
      • or
      • eq/ne
      • gt/gte/lt/lte
      • like/notLike
      • anyEq/anyNe
      • anyGt/anyGte/anyLt/anyLte
      • anyLike/anyNotLike
      • between/notBetween
      • inArray/notInArray
    • Sort
    • Maximum expand depth
  • Caveats:
    • Back-relations
    • Dealing with tables with exactly the same properties
    • Batch requests

Overview

pocketbase-ts is a wrapper around the official PocketBase JavaScript SDK that allows you to write options like this:

const postsWithAuthorAndComments = await pb.collection('posts').getFullList({
    fields: ['id', 'title'],
    expand: [
        {
            key: 'author',
            fields: ['id', 'name'],
        },
        {
            key: 'comments_via_post',
            fields: ['id', 'message'],
        },
    ],
})

instead of:

const postsWithAuthorAndComments = await pb.collection('posts').getFullList({
    expand: 'author,comments_via_post',
    fields: 'id,title,expand.author.id,expand.author.name,expand.comments_via_post.id,expand.comments_via_post.message',
})

and types the response as:

type PostsWithAuthorAndComments = Pick<Post, 'id' | 'title'> & {
    expand: {
        author: Pick<User, 'id' | 'name'>
        comments_via_post?: Pick<Comment, 'id' | 'message'>[]
    }
}

It comes with autocomplete for collection names, field names, relation names, etc.

Demo

You can try it out in TS Playground

Installation

[!IMPORTANT] This package doesn't strictly follow SemVer and treats 1.x.x like 0.x.x as the name pocketbase-ts apparently belonged to another package previously and npm didn't let me publish 0.x.x.

npm install pocketbase-ts

pnpm add pocketbase-ts

bun add pocketbase-ts

Usage

Except for the features described below (i.e., the query options), everything from the official SDK is left as-is.

Defining schema

[!TIP] I recommend using this hook to generate the schema.
It will watch for any changes made to the collections and update the schema file accordingly, keeping everything in sync.

Schema interface

interface SchemaDeclaration {
    [collectionName: string]: {
        type: Record<PropertyKey, any> // collection type
        relations?: {
            [fieldName: string]: Record<PropertyKey, any> // relation type
        }
    }
}

Below is an example of how you would define the schema for this in the PocketBase docs.

interface PocketBaseCollection {
    id: string
    created: string
    updated: string
}

interface User extends PocketBaseCollection {
    name: string
}

interface Post extends PocketBaseCollection {
    // relation fields are defined as strings because they are IDs of the related items
    author: string
    title: string
    tags: Array<string>
}

interface Tag extends PocketBaseCollection {
    name: string
}

interface Comment extends PocketBaseCollection {
    post: string
    user: string
    message: string
}

// you need to use "type" instead of "interface" here
type Schema = {
    // collection name as key
    users: {
        type: User
    }
    posts: {
        type: Post
        relations: {
            // field name as key
            author: User
            // add "?" modifier to annotate optional relation fields
            tags?: Array<Tag>
        }
    }
    tags: {
        type: Tag
    }
    comments: {
        type: Comment
        relations: {
            post: Post
            user: User
        }
    }
}

Back-relations will automatically be inferred from the schema, so in most cases, you don't need to define them yourself.
However, in some cases, you may need to define them explicitly. See Caveats for more information.

Instantiating the SDK

import { PocketBaseTS } from 'pocketbase-ts'

const pb = new PocketBaseTS<Schema>('http://127.0.0.1:8090')

Building query

Use it just like you would with the official SDK, but with a more readable option syntax:

const result = await pb.collection('posts').getOne({
    // you can specify fields to be returned in the response
    fields: ['id', 'title', 'tags'],

    expand: [
        {
            // returns all fields if not specified
            key: 'author',
        },
        {
            key: 'comments_via_post',

            // you can use `:excerpt` modifier on string fields
            fields: ['message:excerpt(20)'],

            // nesting `expand` is supported
            expand: [
                {
                    key: 'user',
                    fields: ['id', 'name'],
                },
            ],
        },
    ],
})

The result is automatically typed as:

type Result = Pick<Post, 'id' | 'title' | 'tags'> & {
    expand: {
        author: User
        comments_via_post?: (Pick<Comment, 'message'> & {
            expand: {
                user: Pick<User, 'id' | 'name'>
            }
        })[]
    }
}

Helper functions for filter and sort

While you can still write filter and sort as plain strings, pocketbase-ts provides several helper functions that allow you to build them in a type-safe manner.

Filter

For filters, you can use Drizzle-like functions.

const result = await pb.collection('posts').getFullList({
    filter: ({ and, eq, gte }) => {
        return and(eq('author.verified', true), gte('likes', 10))
    },
})

Except for and and or, all helper functions take a field name as the first argument and a value or another field name to compare as the second/third argument.

[!IMPORTANT] Since the schema only exists at the type level, these helpers cannot distinguish between a field name and a generic string at runtime.
So if you want to pass a generic string as the value, you need to wrap it in either single or double quotes.

and

and(eq('title', '"foo"'), gt('likes', 30)) // => (title="foo"&&likes>30)

or

or(eq('title', '"foo"'), eq('title', '"bar"')) // => (title="foo"||title="bar")

eq/ne

eq('likes', 5) // => likes=5
eq('verified', true) // => verified=true
eq('title', '"foo"') // => title="foo"
eq('tags:length', 3) // => tags:length=3

gt/gte/lt/lte

gt('likes', 10) // => likes>10
gt('tags:length', 3) // => tags:length>3
gt('year', '@year') // => year>@year

gt('date', '"2000-01-01"') // => date>"2000-01-01"
gt('datetime', '@now') // => datetime>@now

like/notLike

like('title', '"foo"') // => title~"foo"

anyEq/anyNe

anyEq('tags.name', '"foo"') // => tags.name?="foo"
anyEq('posts_via_author.published', true) // => posts_via_author.published?=true
anyEq('@collection.courseRegistrations.user', 'id') // => @collection.courseRegistrations.user?=id

anyGt/anyGte/anyLt/anyLte

anyGt('posts_via_author.likes', 10) // => posts_via_author.likes>10
anyGt('posts_via_author.date', '"2000-01-01"') // => posts_via_author.date>"2000-01-01"

anyLike/anyNotLike

anyLike('tags.name', '"foo"') // => tags.name?~"foo"
anyLike('posts_via_author.title', '"foo"') // => posts_via_author.title?~"foo"

between/notBetween

between('likes', 10, 100) // => (likes>=10&&likes<=100)

notBetween('date', '"2000-01-01"', '"2001-01-01"') // => (date<"2000-01-01"||date>"2001-01-01")

inArray/notInArray

inArray('likes', [1, 3, 5]) // => (likes=1||likes=3||likes=5)

notInArray('title', ['"foo"', '"bar"', '"baz"']) // => (title!="foo"&&title!="bar"&&title!="baz")

At the moment, these helper functions do not perform any type narrowing.
(e.g. eq('tags:length', 3) won't make tags in the response type [string, string, string]. It'll still be string[].)

Sort

For sort, you can use the sortBy function.

const result = await pb.collection('posts').getFullList({
    sort: ({ sortBy }) => {
        return sortBy('author.name', 'title', '-likes') // => 'author.name,title,-likes'
    },
})

Maximum expand depth

While PocketBase supports expanding relations up to 6 levels deep, the number of fields increases exponentially with each level.
The performance hit was very noticeable when I tried to set it to 6 even with the simple schema in the example above.

As such, I've set the default maximum depth for these helpers to 1.

However, should you wish to expand further, you can adjust the maximum depth by passing it as the second type argument when instantiating the SDK.

const pb = new PocketBaseTS<Schema, 6>()

Caveats:

Back-relations

By default, all back-relations are treated as nullable (e.g. Post may not have any Comment), and to-many (e.g. comments_via_post will be of type Comment[]).
The former can be dealt with by simply adding the non-null assertion operator !, but the latter is a different story.

If you have a UNIQUE index constraint on the relation field, the item in expand will be of type T instead of T[].

In such cases, you can override the default behaviour by explicitly defining back-relations yourself in the schema.

type Schema = {
    ...
    users: {
        type: User
        relations: {
            ...
-            userDetail_via_user?: UserDetail[] // default (implicit/inferred)
+            userDetail_via_user: UserDetail // made non-nullable by removing the `?`
        }
    }
    ...
}

Dealing with tables with exactly the same properties

In the example above, User and Tag have the exact same shape, and there is no way for TypeScript to differentiate between the two.
To make it clear to TypeScript that they are different, you can use the UniqueCollection utility type provided by this package.

import type { UniqueCollection } from 'pocketbase-ts'

// pass in the collection name as the second type argument to ensure uniqueness
type User = UniqueCollection<{ name: string } & PocketBaseCollection, 'users'>

Without this, TypeScript will confuse back-relations pointing to User and Tag and suggest that users can be expanded with posts_via_tags, etc.

Batch requests

The response of batch requests (introduced in the official SDK v0.22.0) is not typed, and likely never will be.
There are many cases where it's impossible to know the shape of the request until runtime.

For example:

const batch = pb.createBatch()

for (const user of users) {
    if (condition) {
        batch.collection('users').update(user.id, { name: '...' })
    } else {
        batch.collection('users').delete(user.id)
    }
}

const response = batch.send()