@ikatec/digisac-api-sdk 4.0.0 → 4.2.0

package/src/core/BaseCrudApi.test.ts

@@ -1,11 +1,12 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 import { BaseCrudApi } from './BaseCrudApi'
 import type { ApiClient } from './ApiClient'
+import type { QueryFormat } from './queryString'
 import type { Paginated } from './types'
 
 // ── Test types ───────────────────────────────────────────────────────
 
-type Item = { id: string; name: string }
+type Item = { id: string; name: string; deletedAt?: string | null }
 type CreateItem = { name: string }
 type UpdateItem = { name?: string }
 type ItemWithTags = Item & {
@@ -15,8 +16,9 @@ type ItemWithTags = Item & {
 
 // ── Mock client factory ──────────────────────────────────────────────
 
-function createMockClient(): ApiClient {
+function createMockClient(queryFormat?: QueryFormat): ApiClient {
   return {
+    ...(queryFormat && { queryFormat }),
     setAccessToken: vi.fn().mockReturnThis(),
     request: vi.fn(),
     get: vi.fn(),
@@ -32,6 +34,18 @@ function calledUrl(client: ApiClient, call = 0): string {
   return decodeURIComponent(vi.mocked(client.get).mock.calls.at(call)?.at(0) as string)
 }
 
+/** The path of the nth `client.get` call, without the query string. */
+function calledPath(client: ApiClient, call = 0): string {
+  return (vi.mocked(client.get).mock.calls.at(call)?.at(0) as string).split('?')[0] as string
+}
+
+/** The query sent by the nth `client.get` call, decoded from `?query=<JSON>`. */
+function calledQuery(client: ApiClient, call = 0): unknown {
+  const url = vi.mocked(client.get).mock.calls.at(call)?.at(0) as string
+  const json = new URLSearchParams(url.split('?')[1] ?? '').get('query')
+  return json === null ? undefined : JSON.parse(json)
+}
+
 // ── Tests ────────────────────────────────────────────────────────────
 
 describe('BaseCrudApi', () => {
@@ -97,8 +111,8 @@ describe('BaseCrudApi', () => {
       await updateById('1', { name: 'x' })
       await deleteById('1')
 
-      expect(calledUrl(client, 0)).toBe('/items?paginate=false')
-      expect(calledUrl(client, 1)).toBe('/items?limit=1&paginate=false')
+      expect(calledQuery(client, 0)).toEqual({ paginate: false })
+      expect(calledQuery(client, 1)).toEqual({ limit: 1, paginate: false })
       expect(calledUrl(client, 2)).toBe('/items/1')
       expect(client.post).toHaveBeenCalledWith('/items', { name: 'x' }, undefined)
       expect(client.put).toHaveBeenCalledWith('/items/1', { name: 'x' }, undefined)
@@ -131,20 +145,15 @@ describe('BaseCrudApi', () => {
       vi.mocked(client.get).mockResolvedValue({ data: [], total: 0 })
 
       await api.getMany({ page: 2, perPage: 25 })
-      const calledUrl = vi.mocked(client.get).mock.calls.at(0)?.at(0) as string
-      expect(calledUrl).toContain('/items?')
-      expect(calledUrl).toContain('page=2')
-      expect(calledUrl).toContain('perPage=25')
+      expect(calledPath(client)).toBe('/items')
+      expect(calledQuery(client)).toEqual({ page: 2, perPage: 25 })
     })
 
     it('serializes where clause into query string', async () => {
       vi.mocked(client.get).mockResolvedValue({ data: [], total: 0 })
 
       await api.getMany({ where: { name: 'test' } })
-      const calledUrl = vi.mocked(client.get).mock.calls.at(0)?.at(0) as string
-      expect(calledUrl).toContain('where')
-      expect(calledUrl).toContain('name')
-      expect(calledUrl).toContain('test')
+      expect(calledQuery(client)).toEqual({ where: { name: 'test' } })
     })
 
     it('forwards custom headers', async () => {
@@ -160,7 +169,7 @@ describe('BaseCrudApi', () => {
       vi.mocked(client.get).mockResolvedValue(items)
 
       const result = await api.getMany({ paginate: false })
-      expect(calledUrl(client)).toBe('/items?paginate=false')
+      expect(calledQuery(client)).toEqual({ paginate: false })
       expect(result).toEqual(items)
     })
 
@@ -173,7 +182,7 @@ describe('BaseCrudApi', () => {
         page: number
       }
       await api.getMany(query)
-      expect(calledUrl(client)).toBe('/items?page=2')
+      expect(calledQuery(client)).toEqual({ page: 2, where: {} })
     })
 
     it('forwards headers with query', async () => {
@@ -193,10 +202,8 @@ describe('BaseCrudApi', () => {
       vi.mocked(client.get).mockResolvedValue([item])
 
       const result = await api.getOne()
-      const calledUrl = vi.mocked(client.get).mock.calls.at(0)?.at(0) as string
-      expect(calledUrl).toContain('/items?')
-      expect(calledUrl).toContain('limit=1')
-      expect(calledUrl).toContain('paginate=false')
+      expect(calledPath(client)).toBe('/items')
+      expect(calledQuery(client)).toEqual({ limit: 1, paginate: false })
       expect(result).toEqual(item)
     })
 
@@ -209,9 +216,12 @@ describe('BaseCrudApi', () => {
         limit: 50,
         paginate: true,
       })
-      expect(calledUrl(client)).toBe(
-        '/items?where[name]=x&order[0][0]=name&order[0][1]=DESC&limit=1&paginate=false',
-      )
+      expect(calledQuery(client)).toEqual({
+        where: { name: 'x' },
+        order: [['name', 'DESC']],
+        limit: 1,
+        paginate: false,
+      })
     })
 
     it('returns only the first item when the API returns more than one', async () => {
@@ -223,6 +233,12 @@ describe('BaseCrudApi', () => {
       expect(await api.getOne()).toEqual({ id: '1', name: 'a' })
     })
 
+    it('returns null when the API returns an empty body', async () => {
+      vi.mocked(client.get).mockResolvedValue(undefined)
+
+      expect(await api.getOne()).toBeNull()
+    })
+
     it('returns null when no records match', async () => {
       vi.mocked(client.get).mockResolvedValue([])
 
@@ -255,7 +271,8 @@ describe('BaseCrudApi', () => {
       vi.mocked(client.get).mockResolvedValue({ id: 'abc', name: 'Test' })
 
       await api.getById('abc', { attributes: ['id', 'name'] })
-      expect(calledUrl(client)).toBe('/items/abc?attributes[0]=id&attributes[1]=name')
+      expect(calledPath(client)).toBe('/items/abc')
+      expect(calledQuery(client)).toEqual({ attributes: ['id', 'name'] })
     })
 
     it('forwards query and headers together', async () => {
@@ -263,7 +280,10 @@ describe('BaseCrudApi', () => {
       const headers = { 'X-Tenant': '123' }
 
       await api.getById('1', { attributes: ['id'] }, headers)
-      expect(client.get).toHaveBeenCalledWith('/items/1?attributes%5B0%5D=id', headers)
+      expect(client.get).toHaveBeenCalledWith(
+        `/items/1?query=${encodeURIComponent('{"attributes":["id"]}')}`,
+        headers,
+      )
     })
 
     it('forwards custom headers', async () => {
@@ -378,82 +398,133 @@ describe('BaseCrudApi', () => {
     })
   })
 
-  // ── Query serialization edge cases ───────────────────────────────
+  // ── Query serialization: 'json' (default) ───────────────────────
 
-  describe('query serialization', () => {
-    it('handles complex where with operators', async () => {
+  describe("query serialization (queryFormat: 'json', the default)", () => {
+    it('sends the query as ?query=<JSON>', async () => {
       vi.mocked(client.get).mockResolvedValue({ data: [], total: 0 })
 
-      await api.getMany({ where: { name: { $like: '%test%' } } })
-      const calledUrl = vi.mocked(client.get).mock.calls.at(0)?.at(0) as string
-      expect(calledUrl).toMatch(/^\/items\?/)
-      expect(calledUrl).toContain('%25test%25')
+      await api.getMany({ where: { name: 'x' }, page: 2 })
+      expect(client.get).toHaveBeenCalledWith(
+        `/items?query=${encodeURIComponent('{"where":{"name":"x"},"page":2}')}`,
+        undefined,
+      )
     })
 
-    it('handles order parameter', async () => {
+    it('keeps null, booleans and numbers typed', async () => {
       vi.mocked(client.get).mockResolvedValue({ data: [], total: 0 })
+      const query = {
+        where: { deletedAt: null, id: { $ne: 'x' }, name: { $ne: 'y' } },
+        paranoid: false,
+        distinct: true,
+        limit: 10,
+      }
 
-      await api.getMany({ order: [['name', 'ASC']] })
-      const calledUrl = vi.mocked(client.get).mock.calls.at(0)?.at(0) as string
-      expect(calledUrl).toContain('order')
-      expect(calledUrl).toContain('name')
-      expect(calledUrl).toContain('ASC')
+      await api.getMany(query)
+      expect(calledQuery(client)).toEqual(query)
     })
 
-    it('serializes nested include with where and include', async () => {
+    it('keeps deeply nested includes intact', async () => {
       vi.mocked(client.get).mockResolvedValue({ data: [], total: 0 })
       const tagsApi = new BaseCrudApi<ItemWithTags, CreateItem>(client, '/items')
+      const query = {
+        include: [
+          'owner' as const,
+          { model: 'tags' as const, where: { label: { $in: ['a', 'b'] } }, required: true },
+        ],
+      }
+
+      await tagsApi.getMany(query)
+      expect(calledQuery(client)).toEqual(query)
+    })
+
+    it('encodes special characters', async () => {
+      vi.mocked(client.get).mockResolvedValue({ data: [], total: 0 })
+
+      await api.getMany({ where: { name: { $like: '%a&b=c?#%' } } })
+      expect(calledQuery(client)).toEqual({ where: { name: { $like: '%a&b=c?#%' } } })
+    })
+
+    it('sends no query string for an empty query object', async () => {
+      vi.mocked(client.get).mockResolvedValue({ data: [], total: 0 })
+
+      await api.getMany({})
+      expect(client.get).toHaveBeenCalledWith('/items', undefined)
+    })
+  })
+
+  // ── Query serialization: 'qs' ────────────────────────────────────
+
+  describe("query serialization (queryFormat: 'qs')", () => {
+    let qsClient: ApiClient
+    let qsApi: BaseCrudApi<ItemWithTags, CreateItem, UpdateItem>
+
+    beforeEach(() => {
+      qsClient = createMockClient('qs')
+      qsApi = new BaseCrudApi<ItemWithTags, CreateItem, UpdateItem>(qsClient, '/items')
+      vi.mocked(qsClient.get).mockResolvedValue({ data: [], total: 0 })
+    })
+
+    it('serializes where with operators', async () => {
+      await qsApi.getMany({ where: { name: { $like: '%test%' } } })
+      expect(vi.mocked(qsClient.get).mock.calls.at(0)?.at(0)).toBe(
+        '/items?where%5Bname%5D%5B%24like%5D=%25test%25',
+      )
+    })
 
-      await tagsApi.getMany({
+    it('serializes nested include with where and include', async () => {
+      await qsApi.getMany({
         include: ['owner', { model: 'tags', where: { label: 'vip' }, required: true }],
       })
-      expect(calledUrl(client)).toBe(
+      expect(calledUrl(qsClient)).toBe(
         '/items?include[0]=owner&include[1][model]=tags&include[1][where][label]=vip&include[1][required]=true',
       )
     })
 
     it('serializes $in arrays with indices', async () => {
-      vi.mocked(client.get).mockResolvedValue({ data: [], total: 0 })
-
-      await api.getMany({ where: { id: { $in: ['a', 'b'] } } })
-      expect(calledUrl(client)).toBe('/items?where[id][$in][0]=a&where[id][$in][1]=b')
+      await qsApi.getMany({ where: { id: { $in: ['a', 'b'] } } })
+      expect(calledUrl(qsClient)).toBe('/items?where[id][$in][0]=a&where[id][$in][1]=b')
     })
 
     it('serializes $or/$and combinators', async () => {
-      vi.mocked(client.get).mockResolvedValue({ data: [], total: 0 })
-
-      await api.getMany({ where: { $or: [{ name: 'a' }, { name: 'b' }] } })
-      expect(calledUrl(client)).toBe('/items?where[$or][0][name]=a&where[$or][1][name]=b')
+      await qsApi.getMany({ where: { $or: [{ name: 'a' }, { name: 'b' }] } })
+      expect(calledUrl(qsClient)).toBe('/items?where[$or][0][name]=a&where[$or][1][name]=b')
     })
 
     it('serializes order exactly', async () => {
-      vi.mocked(client.get).mockResolvedValue({ data: [], total: 0 })
-
-      await api.getMany({
+      await qsApi.getMany({
         order: [
           ['name', 'ASC'],
           ['id', 'desc'],
         ],
       })
-      expect(calledUrl(client)).toBe(
+      expect(calledUrl(qsClient)).toBe(
         '/items?order[0][0]=name&order[0][1]=ASC&order[1][0]=id&order[1][1]=desc',
       )
     })
 
     it('serializes booleans and numbers as strings', async () => {
-      vi.mocked(client.get).mockResolvedValue({ data: [], total: 0 })
+      await qsApi.getMany({ paranoid: false, distinct: true, limit: 10, offset: 20 })
+      expect(calledUrl(qsClient)).toBe('/items?paranoid=false&distinct=true&limit=10&offset=20')
+    })
 
-      await api.getMany({ paranoid: false, distinct: true, limit: 10, offset: 20 })
-      expect(calledUrl(client)).toBe('/items?paranoid=false&distinct=true&limit=10&offset=20')
+    it('serializes null as an empty value (the backend reads it as an empty string)', async () => {
+      await qsApi.getMany({ where: { deletedAt: null } })
+      expect(calledUrl(qsClient)).toBe('/items?where[deletedAt]=')
     })
 
-    it('handles empty query object', async () => {
-      vi.mocked(client.get).mockResolvedValue({ data: [], total: 0 })
+    it('serializes getOne and getById queries', async () => {
+      vi.mocked(qsClient.get).mockResolvedValueOnce([]).mockResolvedValueOnce({ id: '1' })
 
-      await api.getMany({})
-      const calledUrl = vi.mocked(client.get).mock.calls.at(0)?.at(0) as string
-      // qs.stringify({}) produces '', so we get '/items?'
-      expect(calledUrl).toBe('/items?')
+      await qsApi.getOne({ where: { name: 'x' } })
+      await qsApi.getById('1', { attributes: ['id'] })
+      expect(calledUrl(qsClient, 0)).toBe('/items?where[name]=x&limit=1&paginate=false')
+      expect(calledUrl(qsClient, 1)).toBe('/items/1?attributes[0]=id')
+    })
+
+    it('sends no query string for an empty query object', async () => {
+      await qsApi.getMany({})
+      expect(qsClient.get).toHaveBeenCalledWith('/items', undefined)
     })
   })
 })

package/src/core/BaseCrudApi.ts

@@ -1,6 +1,5 @@
-import qs from 'qs'
-import type { ApiClient } from './ApiClient'
-import type { CrudApi, GetByIdQuery, ListQuery, Paginated } from './types'
+import { BaseReadApi } from './BaseReadApi'
+import type { CrudApi, ListQuery } from './types'
 export type {
   WhereClause,
   IncludeItem,
@@ -15,71 +14,16 @@ export type {
   CrudApi,
 } from './types'
 
+/** Generic CRUD resource: the reads of `BaseReadApi` plus `create`, `updateById` and `deleteById`. */
 export class BaseCrudApi<
   TResponse,
   TCreate,
   TUpdate = TCreate,
   TQuery extends ListQuery<TResponse> = ListQuery<TResponse>,
-> implements CrudApi<TResponse, TCreate, TUpdate, TQuery> {
-  public readonly client: ApiClient
-  public readonly basePath: string
-
-  constructor(client: ApiClient, basePath: string) {
-    this.client = client
-    this.basePath = basePath.replace(/\/$/, '')
-    this.getMany = this.getMany.bind(this)
-    this.getOne = this.getOne.bind(this)
-    this.getById = this.getById.bind(this)
-    this.create = this.create.bind(this)
-    this.updateById = this.updateById.bind(this)
-    this.deleteById = this.deleteById.bind(this)
-  }
-
-  getMany(
-    query: TQuery & { paginate: false },
-    headers?: Record<string, string>,
-  ): Promise<TResponse[]>
-  getMany(
-    query?: TQuery & { paginate?: true },
-    headers?: Record<string, string>,
-  ): Promise<Paginated<TResponse>>
-  getMany(
-    query?: TQuery,
-    headers?: Record<string, string>,
-  ): Promise<Paginated<TResponse> | TResponse[]> {
-    const queryString = query ? `?${qs.stringify(query)}` : ''
-    return this.client.get<Paginated<TResponse> | TResponse[]>(
-      `${this.basePath}${queryString}`,
-      headers,
-    )
-  }
-
-  /**
-   * Returns the first resource matching the query, or `null` when none match.
-   * Convenience over `getMany` with `limit: 1`.
-   * @permissions $resourceName.view
-   */
-  async getOne(query?: TQuery, headers?: Record<string, string>): Promise<TResponse | null> {
-    const results = await this.getMany(
-      { ...query, limit: 1, paginate: false } as TQuery & { paginate: false },
-      headers,
-    )
-    return results[0] ?? null
-  }
-
-  /**
-   * Returns a single resource by ID.
-   * @permissions $resourceName.view
-   */
-  getById(
-    id: string,
-    query?: GetByIdQuery<TResponse>,
-    headers?: Record<string, string>,
-  ): Promise<TResponse> {
-    const queryString = query ? `?${qs.stringify(query)}` : ''
-    return this.client.get<TResponse>(`${this.basePath}/${id}${queryString}`, headers)
-  }
-
+>
+  extends BaseReadApi<TResponse, TQuery>
+  implements CrudApi<TResponse, TCreate, TUpdate, TQuery>
+{
   /**
    * Creates a new resource.
    * @permissions $resourceName.create

package/src/core/BaseReadApi.ts

@@ -0,0 +1,70 @@
+import type { ApiClient } from './ApiClient'
+import { BaseApi } from './BaseApi'
+import type { GetByIdQuery, HasGetById, HasGetMany, ListQuery, Paginated } from './types'
+
+/**
+ * Generic read-only resource: `getMany`, `getOne` and `getById` under `basePath`. Base of
+ * `BaseCrudApi`, and of the resources the backend only serves for reading (e.g. permissions,
+ * auth history).
+ */
+export class BaseReadApi<TResponse, TQuery extends ListQuery<TResponse> = ListQuery<TResponse>>
+  extends BaseApi
+  implements HasGetMany<TResponse, TQuery>, HasGetById<TResponse>
+{
+  public readonly basePath: string
+
+  constructor(client: ApiClient, basePath: string) {
+    super(client)
+    this.basePath = basePath.replace(/\/$/, '')
+  }
+
+  getMany(
+    query: TQuery & { paginate: false },
+    headers?: Record<string, string>,
+  ): Promise<TResponse[]>
+  getMany(
+    query?: TQuery & { paginate?: true },
+    headers?: Record<string, string>,
+  ): Promise<Paginated<TResponse>>
+  getMany(
+    query?: TQuery,
+    headers?: Record<string, string>,
+  ): Promise<Paginated<TResponse> | TResponse[]>
+  getMany(
+    query?: TQuery,
+    headers?: Record<string, string>,
+  ): Promise<Paginated<TResponse> | TResponse[]> {
+    const queryString = this.toQueryString(query)
+    return this.client.get<Paginated<TResponse> | TResponse[]>(
+      `${this.basePath}${queryString}`,
+      headers,
+    )
+  }
+
+  /**
+   * Returns the first resource matching the query, or `null` when none match.
+   * Convenience over `getMany` with `limit: 1`.
+   * @permissions $resourceName.view
+   */
+  async getOne(query?: TQuery, headers?: Record<string, string>): Promise<TResponse | null> {
+    const results = await this.getMany(
+      { ...query, limit: 1, paginate: false } as TQuery & { paginate: false },
+      headers,
+    )
+    // An empty response body resolves to `undefined`.
+    return results?.[0] ?? null
+  }
+
+  /**
+   * Returns a single resource by ID. When it does not exist most routes answer 200 with an empty
+   * body, which resolves to `undefined`.
+   * @permissions $resourceName.view
+   */
+  getById(
+    id: string,
+    query?: GetByIdQuery<TResponse>,
+    headers?: Record<string, string>,
+  ): Promise<TResponse> {
+    return this.client.get<TResponse>(`${this.basePath}/${id}${this.toQueryString(query)}`, headers)
+  }
+}

package/src/core/bindMethods.ts

@@ -0,0 +1,26 @@
+/**
+ * Binds every method of `instance`'s class chain (up to `Object.prototype`) to `instance`, as own
+ * properties, so methods keep working when destructured (`const { getMany } = api`). The most
+ * derived implementation wins; getters, setters and `constructor` are skipped.
+ */
+export function bindMethods(instance: object): void {
+  const target = instance as Record<PropertyKey, unknown>
+  const bound = new Set<PropertyKey>()
+
+  for (
+    let prototype: object | null = Object.getPrototypeOf(instance);
+    prototype && prototype !== Object.prototype;
+    prototype = Object.getPrototypeOf(prototype)
+  ) {
+    for (const key of Reflect.ownKeys(prototype)) {
+      if (key === 'constructor' || bound.has(key)) {
+        continue
+      }
+      const { value } = Object.getOwnPropertyDescriptor(prototype, key) as PropertyDescriptor
+      if (typeof value === 'function') {
+        target[key] = value.bind(instance)
+        bound.add(key)
+      }
+    }
+  }
+}

package/src/core/index.ts

@@ -1,5 +1,7 @@
 export type { ApiClient, HttpMethod } from './ApiClient'
 export { BaseApiClient } from './BaseApiClient'
+export type { BaseApiClientOptions } from './BaseApiClient'
+export type { QueryFormat } from './queryString'
 export {
   DigisacError,
   ApiConnectionError,
@@ -17,6 +19,8 @@ export {
   parseFieldErrors,
 } from './errors'
 export type { FieldError, ErrorClassName, ApiErrorOptions } from './errors'
+export { BaseApi } from './BaseApi'
+export { BaseReadApi } from './BaseReadApi'
 export { BaseCrudApi } from './BaseCrudApi'
 export { ArchivableCrudApi } from './ArchivableCrudApi'
 export type { WhereClause, IncludeItem, ListQuery, GetByIdQuery, Paginated } from './types'

package/src/core/queryString.test.ts

@@ -0,0 +1,71 @@
+import { describe, it, expect } from 'vitest'
+import qs from 'qs'
+import { toQueryString } from './queryString'
+
+/** Decodes a `?query=<JSON>` string back into the query object. */
+const decodeJson = (queryString: string): unknown =>
+  JSON.parse(new URLSearchParams(queryString.slice(1)).get('query') as string)
+
+describe('toQueryString', () => {
+  it.each([
+    ['undefined', undefined],
+    ['null', null],
+    ['an empty object', {}],
+    ['only undefined values', { page: undefined, where: undefined }],
+  ])('returns an empty string for %s', (_label, query) => {
+    expect(toQueryString(query, 'json')).toBe('')
+    expect(toQueryString(query, 'qs')).toBe('')
+  })
+
+  it("defaults to 'json'", () => {
+    expect(toQueryString({ page: 1 })).toBe(toQueryString({ page: 1 }, 'json'))
+  })
+
+  describe("'json'", () => {
+    it('sends ?query=<JSON>', () => {
+      expect(toQueryString({ page: 2 }, 'json')).toBe(`?query=${encodeURIComponent('{"page":2}')}`)
+    })
+
+    it('round-trips null, booleans, numbers, dates and deep nesting', () => {
+      const query = {
+        where: { deletedAt: null, isArchived: false, createdAt: { $gte: new Date('2026-01-01Z') } },
+        include: [{ model: 'a', include: [{ model: 'b', where: { id: { $in: ['x', 'y'] } } }] }],
+        limit: 10,
+      }
+      expect(decodeJson(toQueryString(query, 'json'))).toEqual({
+        ...query,
+        where: { ...query.where, createdAt: { $gte: '2026-01-01T00:00:00.000Z' } },
+      })
+    })
+
+    it('drops undefined values', () => {
+      expect(decodeJson(toQueryString({ page: 1, where: { name: undefined } }, 'json'))).toEqual({
+        page: 1,
+        where: {},
+      })
+    })
+
+    it('encodes characters that are special in URLs', () => {
+      const queryString = toQueryString({ where: { name: 'a&b=c?#%+ ' } }, 'json')
+      expect(queryString.slice('?query='.length)).not.toMatch(/[&=?#+ ]/)
+      expect(decodeJson(queryString)).toEqual({ where: { name: 'a&b=c?#%+ ' } })
+    })
+  })
+
+  describe("'qs'", () => {
+    it('sends bracket notation', () => {
+      expect(decodeURIComponent(toQueryString({ where: { name: 'x' }, page: 2 }, 'qs'))).toBe(
+        '?where[name]=x&page=2',
+      )
+    })
+
+    it('matches qs.stringify', () => {
+      const query = { where: { id: { $in: ['a', 'b'] } }, order: [['name', 'ASC']] }
+      expect(toQueryString(query, 'qs')).toBe(`?${qs.stringify(query)}`)
+    })
+
+    it('drops undefined values', () => {
+      expect(toQueryString({ page: 1, perPage: undefined }, 'qs')).toBe('?page=1')
+    })
+  })
+})

package/src/core/queryString.ts

@@ -0,0 +1,30 @@
+import qs from 'qs'
+
+/**
+ * How list/get queries (`where`, `include`, `order`, ...) are put in the URL:
+ *
+ * - `'json'` — `?query=<JSON>`, merged into `req.query` by the backend `parseQuery` middleware.
+ *   Keeps `null`, booleans and numbers typed and has no nesting limit.
+ * - `'qs'` — bracket notation (`?where[name]=x&page=2`). Readable, but the backend parses it with
+ *   `qs` defaults: `null` arrives as `''`, booleans/numbers as strings, and objects nested deeper
+ *   than 5 levels (e.g. an `include` inside an `include` with a `where`) are mangled.
+ */
+export type QueryFormat = 'json' | 'qs'
+
+export const DEFAULT_QUERY_FORMAT: QueryFormat = 'json'
+
+/** Serializes a query in `format`, or returns `''` when there is nothing to send. */
+export function toQueryString(
+  query?: object | null,
+  format: QueryFormat = DEFAULT_QUERY_FORMAT,
+): string {
+  if (!query) {
+    return ''
+  }
+  if (format === 'qs') {
+    const queryString = qs.stringify(query)
+    return queryString ? `?${queryString}` : ''
+  }
+  const json = JSON.stringify(query)
+  return json === '{}' ? '' : `?query=${encodeURIComponent(json)}`
+}

package/src/core/types.ts

@@ -125,6 +125,11 @@ export interface HasGetMany<TResponse, TQuery extends ListQuery<TResponse> = Lis
     query?: TQuery & { paginate?: true },
     headers?: Record<string, string>,
   ): Promise<Paginated<TResponse>>
+  /** When `paginate` is only known at runtime (e.g. a `boolean` variable). */
+  getMany(
+    query?: TQuery,
+    headers?: Record<string, string>,
+  ): Promise<Paginated<TResponse> | TResponse[]>
 }
 
 export type GetByIdQuery<T = Record<string, unknown>> = Pick<ListQuery<T>, 'include' | 'attributes'>