@asaidimu/query-pocketbase

A PocketBase executor for @asaidimu/query, providing a flexible and type-safe way to build and execute complex queries against PocketBase collections.

Features

• 🎯 Type-safe: Full TypeScript support with generic types for your data models
• 🔄 Query Builder Integration: Seamless integration with @asaidimu/query's QueryBuilder
• 🚀 Advanced Querying: Support for complex filters, sorting, pagination, and more
• 📊 Data Processing: Built-in support for aggregations, window functions, and computed fields
• 🔍 Smart Caching: Automatic caching of subquery results for better performance
• 🛠️ Extended Functions: Simulated support for additional functions not natively available in PocketBase

Installation

# Using npm
npm install @asaidimu/query @asaidimu/query-pocketbase pocketbase

# Using yarn
yarn add @asaidimu/query @asaidimu/query-pocketbase pocketbase

# Using pnpm
pnpm add @asaidimu/query @asaidimu/query-pocketbase pocketbase

Quick Start

import PocketBase from 'pocketbase';
import { QueryBuilder } from '@asaidimu/query';
import { PocketBaseQueryExecutor } from '@asaidimu/query-pocketbase';

// Define your data model
interface User {
  id: string;
  name: string;
  email: string;
  age: number;
  status: 'active' | 'inactive';
}

// Initialize PocketBase client and executor
const pb = new PocketBase('http://127.0.0.1:8090');
const executor = new PocketBaseQueryExecutor<User>(pb, 'users');

// Build and execute a query
async function getActiveAdultUsers() {
  const query = new QueryBuilder<User>()
    .where({
      operator: 'and',
      conditions: [
        { field: 'age', operator: 'gte', value: 18 },
        { field: 'status', operator: 'eq', value: 'active' }
      ]
    })
    .orderBy('name', 'asc')
    .offset(0, 10)
    .include(['id', 'name', 'email'])
    .build();

  const result = await executor.execute(query);
  return result;
}

Supported Operations

Filtering

// Simple filter
.where({ field: 'age', operator: 'gte', value: 18 })

// Complex conditions
.where({
  operator: 'and',
  conditions: [
    { field: 'age', operator: 'gte', value: 18 },
    {
      operator: 'or',
      conditions: [
        { field: 'status', operator: 'eq', value: 'active' },
        { field: 'role', operator: 'eq', value: 'admin' }
      ]
    }
  ]
})

Sorting

.orderBy('name', 'asc')

Pagination

// Offset-based
.offset(0, 10)

// Cursor-based
.cursor('last_id', 10, 'forward')

Projections

// Include specific fields
.include(['id', 'name', 'email'])

// Exclude fields
.exclude(['password', 'secretKey'])

// Computed fields
.computed({
  function: 'CONCAT',
  arguments: [
    { type: 'field', field: 'firstName' },
    ' ',
    { type: 'field', field: 'lastName' }
  ]
}, 'fullName')

Aggregations

.aggregate(['department'], [
  { operation: 'sum', field: 'salary', alias: 'totalSalary' },
  { operation: 'avg', field: 'age', alias: 'averageAge' }
])

Supported Functions

• String Operations:

  • CONCAT: Concatenate multiple strings
  • UPPER: Convert to uppercase
  • LOWER: Convert to lowercase
  • LENGTH: Get string length

• Numeric Operations:

  • ROUND: Round to nearest integer

• Date Operations:

  • NOW: Current timestamp
  • DATE_FORMAT: Format date strings

• Utility Functions:

  • COALESCE: Return first non-null value

PocketBase-Specific Considerations

Limitations

1. Subqueries: Not natively supported by PocketBase. The executor simulates them using multiple queries.
2. Complex Joins: Limited by PocketBase's capabilities. Implemented as separate queries.
3. Window Functions: Simulated in memory as PocketBase doesn't support them natively.

Performance Tips

1. Use Indexes: Ensure fields used in filters and sorts are indexed in PocketBase.
2. Limit Results: Always use pagination to limit result sets.
3. Optimize Projections: Only request needed fields to reduce data transfer.

Error Handling

The executor provides detailed error messages for common issues:

try {
  const result = await executor.execute(query);
} catch (error) {
  if (error.message.includes('Query execution failed')) {
    // Handle query execution errors
  }
}

TypeScript Support

The executor is fully typed and provides type inference:

interface MyModel {
  id: string;
  name: string;
  // ... other fields
}

const executor = new PocketBaseQueryExecutor<MyModel>(pb, 'collection');
// Now all queries will be type-checked against MyModel

Contributing

Contributions are welcome! Please read our Contributing Guide for details on our code of conduct and the process for submitting pull requests.

License

MIT License - see the LICENSE file for details.