Writing a driver

Four steps. The compiler enforces the last one, because DRIVERS is a closed Record<DriverEnum, DriverDefinition> — add an enum member without registering it and the build fails.

1. Add the enum member

src/enums/driver.enum.ts

export enum DriverEnum {
  // …
  MY_BACKEND = 'my-backend',
}

2. Write the request strategy

Extend AbstractRequestStrategy and override one hook. buildUri() handles resource assertion and joining; parts() returns the query-string segments.

src/strategies/my-backend-request.strategy.ts

import { AbstractRequestStrategy } from '@qubeejs/core';

export class MyBackendRequestStrategy extends AbstractRequestStrategy {
  public readonly capabilities: StrategyCapabilities = {
    embedded: false,
    fields: false,
    filters: true,
    includes: false,
    operatorFilters: false,
    search: false,
    select: true,
    sort: true,
  };

  protected parts(state: QueryBuilderState, options: QueryBuilderOptions): string[] {
    const out: string[] = [];

    Object.entries(state.filters).forEach(([field, values]) => {
      out.push(`${field}=${values.join(',')}`);
    });

    out.push(`${options.page}=${state.page}`, `${options.limit}=${state.limit}`);

    return out;
  }
}

Declare capabilities honestly. It is what makes the builder throw a useful error instead of emitting something the server ignores.

3. Write the response strategy

If the envelope is flat, extend AbstractFlatResponseStrategy and you are done — the base reads every field by name from ResponseOptions:

export class MyBackendResponseStrategy extends AbstractFlatResponseStrategy {}

If it is nested, extend AbstractDotPathResponseStrategy, which resolves dotted paths like meta.pagination.total. If it is neither, implement IResponseStrategy directly.

4. Register it

src/drivers/my-backend.driver.ts

export const MY_BACKEND_DRIVER: DriverDefinition = {
  createRequestStrategy: () => new MyBackendRequestStrategy(),
  createResponseStrategy: () => new MyBackendResponseStrategy(),
  createResponseOptions: (config) => new ResponseOptions(config),
};

Then one line in DRIVERS, and a named export from src/index.ts.

Bee aware

test/drivers.spec.ts fails if a *.driver.ts file exists that nothing imports — the one hazard the per-file layout introduces. Both strategies need specs; every existing driver has them.

Serialising nested structures

Use the bundled stringify() rather than URLSearchParams, which percent-encodes brackets with no opt-out:

import { stringify } from '@qubeejs/core';

stringify({ filters: { status: { $eq: 'published' } } });
// filters[status][$eq]=published