Pocketbase Query

Overview

@emresandikci/pocketbase-query is a TypeScript-based query builder designed to generate complex filter queries for PocketBase. It allows for easy construction of queries using various operators while maintaining a fluent and chainable API.

Installation

This library can be used in any TypeScript/JavaScript project. Simply import it as needed:

npm i @emresandikci/pocketbase-query

import PocketbaseQuery from '@emresandikci/pocketbase-query';

Usage

Creating an Instance

The PocketbaseQuery class follows the singleton pattern. You should use getInstance() to get a query builder instance:

const query = PocketbaseQuery.getInstance<MyType>();

Example

import PocketbaseQuery from '@emresandikci/pocketbase-query';

const query = PocketbaseQuery.getInstance<{ status: string; comments: number }>();

const customFilters = query
  .equal('status', 'active')
  .and()
  .greaterThan('comments', 50)
  .build();

console.log(customFilters); // Outputs: status='active' && comments>50

await pb.collection('posts').getFullList({
	filter: customFilters,
	expand: [{ key: 'comments_via_post' }],
})

API Methods

Operators Enum

OperatorEnum defines a set of operators for use in queries:

enum OperatorEnum {
  Equal = "=",
  NotEqual = "!=",
  GreaterThan = ">",
  GreaterThanOrEqual = ">=",
  LessThan = "<",
  LessThanOrEqual = "<=",
  Like = "~",
  NotLike = "!~",
  AnyEqual = "?=",
  AnyNotEqual = "?!=",
  AnyGreaterThan = "?>",
  AnyGreaterThanOrEqual = "?>=",
  AnyLessThan = "?<",
  AnyLessThanOrEqual = "?<=",
  AnyLike = "?~",
  AnyNotLike = "?!~",
}

Query Builder Methods

equal(field: keyof T, value: string | boolean)

Adds an equality condition to the query.

query.equal("status", "active");

notEqual(field: keyof T, value: string)

Adds a not-equal condition to the query.

query.notEqual("category", "archived");

greaterThan(field: keyof T, value: string)

Adds a greater-than condition.

query.greaterThan("age", "18");

lessThan(field: keyof T, value: string)

Adds a less-than condition.

query.lessThan("price", "100");

like(field: keyof T, value: string)

Adds a LIKE condition (partial match).

query.like("name", "John");

notLike(field: keyof T, value: string)

Adds a NOT LIKE condition.

query.notLike("description", "discount");

anyEqual(field: keyof T, value: string)

Adds an equality condition for array fields.

query.anyEqual("tags", "sale");

in(field: keyof T, values: any[])

Adds an OR condition for multiple values.

query.in("category", ["electronics", "furniture"]);

customFilter(filter: string)

Adds a custom filter string to the query.

query.customFilter("status='active' && price>100");

Logical Operators

and()

Joins multiple conditions with &&.

query.equal("status", "active").and().greaterThan("price", "50");

or()

Joins multiple conditions with ||.

query.equal("status", "active").or().equal("status", "pending");

openBracket() and closeBracket()

Groups conditions using parentheses.

query.openBracket().equal("status", "active").or().equal("status", "pending").closeBracket().and().greaterThan("price", "50");

Query Execution

getQuery()

Returns the current query string.

const queryString = query.getQuery();

build()

Finalizes and returns the query string while clearing the internal state.

const finalQuery = query.build();

Notes

• The PocketbaseQuery class uses a singleton pattern, meaning a single instance is reused across calls.
• The .build() method resets the query, so ensure you store the generated string if you need it.
• The in() method applies OR between multiple values.

License

MIT License