Getting Started

ng-qubee is a query builder for Angular. It composes API request URIs (filters, sorts, pagination, column selection) and parses paginated responses, with a pluggable driver system that targets five backends today and is built to grow.

• Easily retrieve URIs from a service
• Pagination ready, with auto-sync from response to query state
• Reactive — URIs emit through an RxJS Observable
• Test-driven, ~460 specs covering every driver path
• Multi-driver: JSON:API, Laravel (pagination-only), Spatie Query Builder, NestJS (nestjs-paginate), PostgREST / Supabase

Requirements

Dependency	Range
Angular	>=16.0.0 <22.0.0
RxJS	`^6.5.0

Angular 16+ is required because the library uses Angular Signals for state management.

Installation

npm install ng-qubee

Configure a driver

ng-qubee requires you to pick a driver at bootstrap. There's no default — every driver speaks a different wire format and the library wants you to be explicit.

main.ts

import { bootstrapApplication } from '@angular/platform-browser';
import { DriverEnum, provideNgQubee } from 'ng-qubee';
import { AppComponent } from './app/app.component';

bootstrapApplication(AppComponent, {
  providers: [
    provideNgQubee({ driver: DriverEnum.SPATIE })
  ]
});

Module-style equivalent:

app.module.ts

import { NgModule } from '@angular/core';
import { DriverEnum, NgQubeeModule } from 'ng-qubee';

@NgModule({
  imports: [
    NgQubeeModule.forRoot({ driver: DriverEnum.SPATIE })
  ]
})
export class AppModule {}

Build your first request

Inject the service, set a resource, add filters / sorts / pagination, and subscribe to the URI stream:

import { Component } from '@angular/core';
import { NgQubeeService, SortEnum } from 'ng-qubee';

@Component({ /* ... */ })
export class UsersComponent {
  constructor(private _qb: NgQubeeService) {
    this._qb.setResource('users')
            .addFilter('status', 'active')
            .addSort('created_at', SortEnum.DESC)
            .setLimit(25);

    this._qb.generateUri().subscribe(uri => {
      // Spatie driver: /users?filter[status]=active&limit=25&page=1&sort=-created_at
      console.log(uri);
    });
  }
}

The exact URI shape depends on the driver. See the Drivers section for the format produced by each.

Pick a driver

Five drivers ship out of the box:

Driver	Best for
JSON:API	Any JSON:API-compliant backend (Rails, Django, .NET, Java, Elixir)
Laravel	Plain Laravel pagination (limit + page only — no filters/sorts)
Spatie	Spatie Query Builder for Laravel
NestJS	nestjs-paginate
PostgREST	PostgREST and Supabase

Next steps

• Query Builder API — every fluent method on NgQubeeService
• Pagination — navigation helpers, auto-sync, response parsing
• Per-component instances — isolate state per feature component