Refine-pocketbase NPM

refine-pocketbase

Installation

npm install refine-pocketbase

Data Provider

Basic Usage

import PocketBase from "pocketbase";
import { authProvider, dataProvider, liveProvider } from "refine-pocketbase";

const pb = new PocketBase(POCKETBASE_URL);

<Refine
  authProvider={authProvider(pb)}
  dataProvider={dataProvider(pb)}
  liveProvider={liveProvider(pb)}
  ...
>
  ...
</Refine>

The Meta Properties `fields` and `expand`

The code below uses useList to fetch a list of users. The resulting list contains user records with the id, name, avatar and the name of the organisation a user is assigned to. The meta properties fields and expand are used to customize the server response to the requirements of the user interface.

const users = useList({
  resource: "users",
  meta: {
    fields: ["id", "name", "avatar", "expand.org.name"],
    expand: ["org"],
  }
});

Here fields is an array of strings limiting the fields to return in the server's response. expand is an array with names of the related records that will be included in the response. Pocketbase supports up to 6-level depth nested relations expansion. See https://pocketbase.io/docs/api-records for more examples.

A couple of other refine hooks and components like useOne, useTable, <Show/>, <List/>, etc. will support the meta props fields and expand if used with the refine-pocketbase data provider.

Filtering with `in` and `nin`

The in or nin filters expect an array as value as show in the code fragment below.

{
  field: "a",
  operator: "in",
  value: [1, 2, 3],
}

This expression will be transformed to a pocketbase filter expression (a = 1 || a = 2 || a = 3).

A similar expression using nin filter will be transformed to b != 1 && b != 2 && b != 3.

Setting an empty array [] as a filter value will cause the in or nin filter to be excluded from the resulting filter expression.

Filtering with `between` and `nbetween`

The between or nbetween filters expect a tuple [min, max] as value as show in the code fragment below.

{
  field: "a",
  operator: "between",
  value: [1, 2],
}

This expression will be transformed to a pocketbase filter expression (a >= 1 && a <= 2).

The same expression but with nin as the operator will be transformed to (a < 1 || a > 2).

Partial tuples in form of [min, undefined/null] or [undefined/null, max] are possible as well and would omit either one side of the join operator.

An empty tuple [] will cause the filter to be excluded from the resulting filter.

Custom Endpoints with `useCustom` Hook

The useCustom hook allows you to make custom API calls to your PocketBase backend. This is particularly useful when you need to interact with custom PocketBase endpoints.

Here's an example of how to use the useCustom hook:

const apiUrl = useApiUrl();

const { data, isLoading } = useCustom({
    url: `${apiUrl}/api/custom-endpoint`,
    method: "get",
  });

Auth Provider

A number of configuration properties are supported by the auth provider, primarily for controlling redirection following specific auth events. Please take a look at the self-explanatory names in the AuthOptions typescript interface to find the available options.

import { authProvider, AuthOptions } from "refine-pocketbase";

const authOptions: AuthOptions = {
  loginRedirectTo: "/dashboard",
};

<Refine
  authProvider={authProvider(pb, authOptions)}
  ...
>
  ...
</Refine>

Auth Collection

users is the default auth collection in Pocketbase. Several auth collections can be supported in a single Pocketbase instance. You can use a different collection with the authProvider by using the collection property:

const authOptions: AuthOptions = {
  collection: "superusers",
};

OAuth2 Configuration

The PocketBase OAuth2Config can be set either via the mutationVariables prop in AuthPage,

<AuthPage
  type="login"
  mutationVariables={{
    scopes: ["user-read-private", "user-top-read"],
  }}
  providers={[{
    name: "spotify",
    label: "Login with Spotify",
    icon: <SpotifyIcon />,
  }]}
/>

or imperatively via useLogin:

import { LoginWithProvider } from "refine-pocketbase";

const { mutate: login } = useLogin<LoginWithProvider>();

login({
  scopes: ["user-read-private", "user-top-read"],
  providerName: "spotify",
});

For improved type safety, refine-pocketbase exports the LoginWithProvider type. With this, TypeScript can warn you if a property name or value type is incorrect and provide you with autocompletion for a better developer experience.

Password-Based Auth Options

For password-based authentication, you can pass an optional options property that meets PocketBase's RecordOptions interface.

import { LoginWithPassword } from "refine-pocketbase";

const { mutate: login } = useLogin<LoginWithPassword>();

login({
  email: "user@example.com",
  password: "********",
  options: {
    expand: "orgs,permissions",
    headers: { key: "value" },
    ... // more RecordOptions props
  },
});

// similar scenario but using AuthPage:
<AuthPage
  type="login"
  mutationVariables={{
    email: "user@example.com",
    password: "********",
    options: {
      expand: "orgs,permissions",
      headers: { key: "value" },
      ... // more RecordOptions props
    },
  }}
/>

Features

auth provider
- register
- login with password
- login with provider
- forgot password
- update password
data provider
- filters
- sorters
- pagination
- expand
- filter
live provider
- subscribe
- unsubscribe
audit log provider

Tasks: PRs Welcome!

auditLogProvider implementation
happy path test specs
- authProvider
- dataProvider (except for deleteOne)
- liveProvider
- auditLogProvider
test specs for authProvider error conditions
- register
- forgotPassword
- updatePassword
- login
test specs for dataProvider error conditions
- getList
- create
- update
- getOne
- deleteOne
test specs for deleteOne
test specs with expand
- getList
- getOne
test specs with fields
- getList
- getOne
test specs for auditLogProvider errors
remove all requestKeys to prioritize sdk autoCancellation preference
Setup Github Actions
- test environment
- build & publish