Official JavaScript SDK (browser and node) for interacting with the PocketBase API.
<script src="/path/to/dist/pocketbase.umd.js"></script>
OR if you are using ES modules:
<script type="module">
import PocketBase from '/path/to/dist/pocketbase.es.mjs'
...
</script>
npm install pocketbase --save
// Using ES modules (default)
import PocketBase from 'pocketbase'
// OR if you are using CommonJS modules
const PocketBase = require('pocketbase/cjs')
๐ง For Node < 17 you'll need to load a
fetch()
polyfill. I recommend lquixada/cross-fetch:// npm install cross-fetch --save require('cross-fetch/polyfill');
๐ง Node doesn't have native
EvenSource
implementation, so in order to use the realtime service (aka.client.Realtime.subscribe()
) you'll need to load aEventSource
polyfill. I recommend EventSource/eventsource:// npm install eventsource --save global.EventSource = require('eventsource');
import PocketBase from 'pocketbase';
const client = new PocketBase('http://localhost:8090');
...
// list and filter "demo" collection records
const result = await client.Records.getList("demo", 1, 20, {
filter: "status = true && totalComments > 0"
});
// authenticate as regular user
const userData = await client.Users.authViaEmail("[email protected]", "123456");
// or as admin
const adminData = await client.Admins.authViaEmail("[email protected]", "123456");
// and much more...
More detailed API docs and copy-paste examples could be found in the API documentation for each service.
Each request error response is wrapped and normalized in a ClientResponseError
object with the following fields:
ClientResponseError {
url: string, // requested url
status: number, // response status code
data: { ... }, // the api json error response
isAbort: boolean, // is abort/cancellation error
originalError: Error|null, // the original non-normalized error
}
The SDK client auto cancel duplicated pending requests.
For example, if you have the following 3 duplicated calls, only the last one will be executed, while the first 2 will be cancelled with ClientResponseError
error:
client.Records.getList("demo", 1, 20) // cancelled
client.Records.getList("demo", 1, 20) // cancelled
client.Records.getList("demo", 1, 20) // executed
To change this behavior, you could make use of 2 special query parameters:
$autoCancel
- set it tofalse
to disable auto cancellation for this request$cancelKey
- set it to a string that will be used as request identifier and based on which pending duplicated requests will be matched (default toHTTP_METHOD + url
, eg. "get /api/users?page=1")
Example:
client.Records.getList("demo", 1, 20); // cancelled
client.Records.getList("demo", 1, 20); // executed
client.Records.getList("demo", 1, 20, { "$autoCancel": false }); // executed
client.Records.getList("demo", 1, 20, { "$autoCancel": false }) // executed
client.Records.getList("demo", 1, 20, { "$cancelKey": "test" }) // cancelled
client.Records.getList("demo", 1, 20, { "$cancelKey": "test" }) // executed
To manually cancel pending requests, you could use client.cancelAllRequests()
or client.cancelRequest(cancelKey)
.
The SDK keeps track of the authenticated token and auth model for you via the client.AuthStore
instance.
It has the following public fields that you can use:
AuthStore {
token: string, // the authenticated token
model: User|Admin, // the authenticated User or Admin model
isValid: boolean, // checks if the store has existing and unexpired token
clear(), // "logout" the authenticated User or Admin
save(token, model), // update the store with the new auth data
}
By default the SDK initialize a LocalAuthStore
, which uses the browser's LocalStorage
if available, otherwise - will fallback to runtime/memory store (aka. on page refresh or service restart you'll have to authenticate again).
To "logout" an authenticated user or admin, you can just call client.AuthStore.clear()
.
const client = new PocketBase(
baseUrl = '/',
lang = 'en-US',
authStore = LocalAuthStore
);
Each instance method returns the
PocketBase
instance allowing chaining.
Method | Description |
---|---|
client.send(path, reqConfig = {}) |
Sends an api http request. |
client.cancelAllRequests() |
Cancels all pending requests. |
client.cancelRequest(cancelKey) |
Cancels single request by its cancellation token key. |
client.buildUrl(path, reqConfig = {}) |
Builds a full client url by safely concatenating the provided path. |
Each service call returns a
Promise
object with the API response.
Resource | Description |
---|---|
Admins | |
๐client.Admins.authViaEmail(email, password, bodyParams = {}, queryParams = {}) |
Authenticate an admin account by its email and password and returns a new admin token and admin data. |
๐client.Admins.refresh(bodyParams = {}, queryParams = {}) |
Refreshes the current admin authenticated instance and returns a new admin token and admin data. |
๐client.Admins.requestPasswordReset(email, bodyParams = {}, queryParams = {}) |
Sends admin password reset request. |
๐client.Admins.confirmPasswordReset(passwordResetToken, password, passwordConfirm, bodyParams = {}, queryParams = {}) |
Confirms admin password reset request. |
๐client.Admins.getList(page = 1, perPage = 30, queryParams = {}) |
Returns paginated admins list. |
๐client.Admins.getFullList(batchSize = 100, queryParams = {}) |
Returns a list with all admins batch fetched at once. |
๐client.Admins.getOne(id, queryParams = {}) |
Returns single admin by its id. |
๐client.Admins.create(bodyParams = {}, queryParams = {}) |
Creates a new admin. |
๐client.Admins.update(id, bodyParams = {}, queryParams = {}) |
Updates an existing admin by its id. |
๐client.Admins.delete(id, bodyParams = {}, queryParams = {}) |
Deletes an existing admin by its id. |
Users | |
๐client.Users.listAuthMethods(queryParams = {}) |
Returns all available application auth methods. |
๐client.Users.authViaEmail(email, password, bodyParams = {}, queryParams = {}) |
Authenticate a user account by its email and password and returns a new user token and user data. |
๐client.Users.authViaOAuth2(clientName, code, codeVerifier, redirectUrl, bodyParams = {}, queryParams = {}) |
Authenticate a user via OAuth2 client provider. |
๐client.Users.refresh(bodyParams = {}, queryParams = {}) |
Refreshes the current user authenticated instance and returns a new user token and user data. |
๐client.Users.requestPasswordReset(email, bodyParams = {}, queryParams = {}) |
Sends user password reset request. |
๐client.Users.confirmPasswordReset(passwordResetToken, password, passwordConfirm, bodyParams = {}, queryParams = {}) |
Confirms user password reset request. |
๐client.Users.requestVerification(email, bodyParams = {}, queryParams = {}) |
Sends user verification email request. |
๐client.Users.confirmVerification(verificationToken, bodyParams = {}, queryParams = {}) |
Confirms user email verification request. |
๐client.Users.requestEmailChange(newEmail, bodyParams = {}, queryParams = {}) |
Sends an email change request to the authenticated user. |
๐client.Users.confirmEmailChange(emailChangeToken, password, bodyParams = {}, queryParams = {}) |
Confirms user new email address. |
๐client.Users.getList(page = 1, perPage = 30, queryParams = {}) |
Returns paginated users list. |
๐client.Users.getFullList(batchSize = 100, queryParams = {}) |
Returns a list with all users batch fetched at once. |
๐client.Users.getOne(id, queryParams = {}) |
Returns single user by its id. |
๐client.Users.create(bodyParams = {}, queryParams = {}) |
Creates a new user. |
๐client.Users.update(id, bodyParams = {}, queryParams = {}) |
Updates an existing user by its id. |
๐client.Users.delete(id, bodyParams = {}, queryParams = {}) |
Deletes an existing user by its id. |
Realtime (for node environments you'll have to install an EventSource polyfill beforehand, eg. https://github.com/EventSource/eventsource) |
|
๐client.Realtime.subscribe(subscription, callback) |
Inits the sse connection (if not already) and register the subscription. |
๐client.Realtime.unsubscribe(subscription = "") |
Unsubscribe from a subscription (if empty - unsubscibe from all registered subscriptions). |
Collections | |
๐client.Collections.getList(page = 1, perPage = 30, queryParams = {}) |
Returns paginated collections list. |
๐client.Collections.getFullList(batchSize = 100, queryParams = {}) |
Returns a list with all collections batch fetched at once. |
๐client.Collections.getOne(id, queryParams = {}) |
Returns single collection by its id. |
๐client.Collections.create(bodyParams = {}, queryParams = {}) |
Creates a new collection. |
๐client.Collections.update(id, bodyParams = {}, queryParams = {}) |
Updates an existing collection by its id. |
๐client.Collections.delete(id, bodyParams = {}, queryParams = {}) |
Deletes an existing collection by its id. |
Records | |
๐client.Records.getList(collectionIdOrName, page = 1, perPage = 30, queryParams = {}) |
Returns paginated records list. |
๐client.Records.getFullList(collectionIdOrName, batchSize = 100, queryParams = {}) |
Returns a list with all records batch fetched at once. |
๐client.Records.getOne(collectionIdOrName, id, queryParams = {}) |
Returns single record by its id. |
๐client.Records.create(collectionIdOrName, bodyParams = {}, queryParams = {}) |
Creates a new record. |
๐client.Records.update(collectionIdOrName, id, bodyParams = {}, queryParams = {}) |
Updates an existing record by its id. |
๐client.Records.delete(collectionIdOrName, id, bodyParams = {}, queryParams = {}) |
Deletes an existing record by its id. |
Logs | |
๐client.Logs.getRequestsList(page = 1, perPage = 30, queryParams = {}) |
Returns paginated request logs list. |
๐client.Logs.getRequest(id, queryParams = {}) |
Returns a single request log by its id. |
๐client.Logs.getRequestsStats(queryParams = {}) |
Returns request logs statistics. |
Settings | |
๐client.Settings.getAll(queryParams = {}) |
Fetch all available app settings. |
๐client.Settings.update(bodyParams = {}, queryParams = {}) |
Bulk updates app settings. |
# run unit tests
npm test
# build and minify for production
npm run build