Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/kruschid/refine-pocketbase
https://github.com/kruschid/refine-pocketbase
Last synced: 6 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/kruschid/refine-pocketbase
- Owner: kruschid
- License: mit
- Created: 2024-01-21T17:16:23.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-01-19T17:52:45.000Z (8 days ago)
- Last Synced: 2025-01-19T18:36:15.575Z (8 days ago)
- Language: TypeScript
- Size: 625 KB
- Stars: 65
- Watchers: 2
- Forks: 7
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-refine - refine-pocketbase
README
# refine-pocketbase
[](https://github.com/kruschid/refine-pocketbase/blob/master/LICENSE)
[](https://github.com/kruschid/refine-pocketbase/graphs/contributors)
[](https://www.npmjs.com/package/refine-pocketbase)
[](https://discord.gg/BCGmvSSJBk)
[PocketBase](https://pocketbase.io/) providers for [Refine](https://refine.dev/).
## Installation
``` sh
npm install refine-pocketbase
```
## Data Provider
### Basic Usage
``` tsx
import PocketBase from "pocketbase";
import { authProvider, dataProvider, liveProvider } from "refine-pocketbase";
const pb = new PocketBase(POCKETBASE_URL);
...
```
### 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.
``` ts
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`, ``, ``, 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.
``` ts
{
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.
``` ts
{
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:
``` ts
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.
``` ts
import { authProvider, AuthOptions } from "refine-pocketbase";
const authOptions: AuthOptions = {
loginRedirectTo: "/dashboard",
};
...
```
### 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:
``` ts
const authOptions: AuthOptions = {
collection: "superusers",
};
```
## Features
- [x] auth provider
- [x] register
- [x] login with password
- [x] login with provider
- [x] forgot password
- [x] update password
- [x] data provider
- [x] filters
- [x] sorters
- [x] pagination
- [x] expand
- [x] filter
- [x] live provider
- [x] subscribe
- [x] unsubscribe
- [ ] audit log provider
## Tasks: PRs Welcome!
- [ ] `auditLogProvider` implementation
- [ ] happy path test specs
- [x] `authProvider`
- [x] `dataProvider` (except for `deleteOne`)
- [x] `liveProvider`
- [ ] `auditLogProvider`
- [ ] test specs for `authProvider` error conditions
- [x] `register`
- [x] `forgotPassword`
- [x] `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
- [x] Setup Github Actions
- [x] test environment
- [x] build & publish
## How to Contribute
- leave a star ⭐
- report a bug 🐞
- open a pull request 🏗️
- help others ❤️
- [buy me a coffee ☕](https://www.buymeacoffee.com/kruschid)
