Query Object Tool Documentation

Overview

This tool is used for parsing our custom filter, pagination and sorter JSON object (referred to as "Query Object" in the following text) into a Base64URL encoded and decoded string for usage in GET requests.

Design Considerations

GET Requests vs POST Requests

While some StackOverflow answers suggest that the best way to implement a filter endpoint is using something like POST /{entity}/filter where the filter object is sent in the request body, we came to a different conclusion.

The main disadvantages of using a POST request are:

• Not Idempotent: POST requests are not idempotent and therefore not cacheable.
• URL Reusability: You cannot copy the URL, paste it somewhere else, and get the same results.

An important consideration when using GET requests, however, is the size limitation of a URL. When using a Base64URL encoded string in the URL, it can become quite large and potentially exceed the default size limits for Express, Node.js, or the browser being used.

URL Length Limitations

| Software | Max URL Length | Additional Information | | -------- | -------------- | ------------------------------------------------------------------------------------------- | | Browser | 2083 | Chromium is the lowest by far; all others can handle upwards of 10,000 characters for URLs. | | Node.js | ~80,000 | Node.js HTTP GET URL length limitation. | | Express | - | Seems to have no explicit limitations other than Node.js. | | Axios | - | Seems to have no limitations by itself. |

Non-ASCII characters may decrease the maximum length that can be used.

Custom Base64 Encode/Decode Methods

Custom Base64 encode/decode methods are needed to make Base64 URL safe for both browser and Node.js usage. While Node.js has a method (Buffer.from(…….).toString('base64url')), no such methods are available in the browser.

Difference Between Base64 and Base64URL

The main differences are:

• Characters: Characters 62 and 63 (+, /) are not URL safe. In Base64URL, these are replaced with - and _.
• Trailing Equals: The trailing = is removed in Base64URL.

Tool Capabilities

This tool is able to:

1. Validate and convert a Query Object into a string.
2. Validate and convert such custom strings back into a Query Object.
3. Convert a Query Object into an object usable by Prisma ORM

Query Object Definition

{
  "filters": undefined | {
    "property": string[]
  },
  "pagination": undefined | {
    "current": number, // min => 1, max => Ceil(totalEntries / pageSize)
    "pageSize": number // min 1, max 100
  },
  "sorter": undefined | {
    "field": string,
    "order": int // 0 = ascend, 1 = descend, undefined
  }
}

Example Usage

Creating a Query Object

const queryObject = {
  filters: {
    name: '[foo]',
  },
  sorter: {
    field: 'name',
    order: 'asc',
  },
  pagination: {
    skip: 0,
    take: 10,
  },
};

Converting Query Object into string

import AntdQueryUtility from '@adviz/antd-query-utilty';

const queryString = AntdQueryUtility.ToQueryString(queryObject);

Converting string back into Query Object

Be sure to not just call with req.url rather with req.query.queryString.

import AntdQueryUtility from '@adviz/antd-query-utilty';

const queryObject = AntdQueryUtility.ToQueryObject(queryString);

Converting a Query Object to a Prisma Query

import AntdQueryUtility from '@adviz/antd-query-utilty';

const prismaQuery = AntdQueryUtility.ToPrismaQueryFromQueryObject(queryObject);

Converting a Query String to a Prisma Query directly

import AntdQueryUtility from '@adviz/antd-query-utilty';

const prismaQuery = AntdQueryUtility.ToPrismaQueryFromQueryString(queryObject);

// with single relation to another entity
const prismaQuery = AntdQueryUtility.ToPrismaQueryFromQueryString(
  queryObject,
  true, // validation = true
  ['address'] // singe relation keys
);

// n:m relation to another entity
const prismaQuery = AntdQueryUtility.ToPrismaQueryFromQueryString(
  queryObject,
  true, // validation = true
  undefined,
  ['friends'] // multi relation keys
);

Special Where Keys

Some keys have to transformed differently than others, but it is not possible to differentiate them just from filter values. For this problem we have implemented the enum PrismaWhereKeyTypes

enum PrismaWhereKeyTypes {
  Enum = 'enum',
  EnumArray = 'enum[]',
  StringArray = 'string[]',
  ExactString = 'string',
  LikeString = 'likeString',
}

Every Array Type is filtered by an || link, && is currently not supported.

Usage

import AntdQueryUtility from '@adviz/antd-query-utilty';

const prismaQuery = AntdQueryUtility.ToPrismaQueryFromQueryString(queryObject);

const prismaQuery = AntdQueryUtility.ToPrismaQueryFromQueryString(
  queryObject,
  true, // validation = true
  undefined, // no single relation keys
  undefined, // no mulit relation keys
  {
    tags: PrismaWhereKeyTypes.StringArray,
  }
);

Cleanup Query Object

Antd for example popuplates the object with some key: undefined values that need to be cleaned up.

import AntdQueryUtility from '@adviz/antd-query-utilty';

const queryString = AntdQueryUtility.ToQueryString(queryObject, true); // true => withCleanup

OR

import AntdQueryUtility from '@adviz/antd-query-utilty';

const cleanedUpQueryObject = AntdQueryUtility.CleanUpObject(queryObject);
const queryString = AntdQueryUtility.ToQueryString(cleanedUpQueryObject);