Frontend Usage & crudQuery

Overview

info

Although all examples and schematics in this documentation demonstrate passing crudQuery as a JSON.stringified string in your query parameters, that is not mandatorily the only way to do it.

You can chose to adjust your controllers and retrieve the crudQuery object from POST bodies or any other method you prefer.

If you choose to do so, remember to also adapt any built in or custom policies that were previously relying on request.query.

Every public method of PrismaCrudService used in your CRUD endpoints accept a parameter crudQuery.

crudQuery must be an object (or JSON string) with the following shape:

export type CrudQuery = {    where?: any;    joins?: string[];    select?: { only?: string[]; except?: string[] };    orderBy?: any[];    page?: number;    pageSize?: number;};

TLDR Usage

// "/users" endpointconst crudQuery = {    where: {        posts: {            some: {                comments: { some: { content: { contains: 'Hello' } } },            },        },    },    joins: ['profile', 'posts.comments'],    select: { only: ['id', 'profile.fullName', 'posts.title', 'posts.comments.content'] },    orderBy: [{ age: 'asc' }],    page: 2,    pageSize: 100,};
fetch('http://localhost:3000?' + new URLSearchParams({ crudQuery: JSON.stringify(crudQuery) }));

CrudQuery Properties

CrudQuery.where

Type: any
Mandatory: No
Description:

This must be valid prisma .where for your specific model.

Querying nested joins is supported, as long as the joined relations are present in your service's allowedJoins.

Example:

/*To fetch all users who have posts where someone made a comment containing the word'Hello', send the following crudQuery query parameter to the "/users" endpoint.*/const crudQuery = {    // ...    where: {        posts: {            some: {                comments: { some: { content: { contains: 'Hello' } } },            },        },    },};

For more information on the .where object, see the prisma API reference.

---

CrudQuery.joins

Type: string[]
Mandatory: No
Description:

The joined relations you wish the response to include. Supports dot notation.

Setting this value will override the server's defaultJoins option.

Note: endpoint will throw 403 if the provided join is not present in allowedJoins

Example:

/*Send the following crudQuery to the "/users" endpoint to get the user with:  1. his profile  2. all his posts  3. all his posts' comments*/const crudQuery = {    // ...    joins: ['profile', 'posts.comments'],};

---

CrudQuery.select

Type: { only?: string[]; except?: string[] }
Mandatory: No
Description:

The properties which you wish to incude in the responses.

tip

Both .only and .except support a special dot notation that goes through arrays without needing to specify the array's indexes.

Example:
✅ { only: ['user.posts.title'] }
❌ { only: ['user.posts.0.title', 'user.posts.1.title', 'user.posts.2.title', ...] }

This syntax is different than the forbiddenPaths syntax, since there we can use RegExps for targetting the array indexes.

Use .except when you want to provide an array of properties that you wish to omit.

Use .only when you want to provide an array of properties that you wish to include in the response, excluding everything else.

Note: These properties are omitted from the HTTP responses, however they still get fetched from the database!!

Example:

/*Send the following crudQuery to the "/users" endpoint to get only their username and post titles:*/const crudQuery = {    // ...    select: { only: ['username', 'posts.title'] },};
// response: { username: 'john', posts: [{ title: 'My Title 1' }, { title: 'My Title 2' }] };

---

CrudQuery.orderBy

Type: Array<{ [string]: 'asc' | 'desc' }>
Mandatory: No
Description:

This must be a valid prisma .orderBy array. See prisma orderBy reference for more.

Example:

const crudQuery = {    // ...    orderBy: [{ age: 'asc' }],};

---

CrudQuery.page

Type: number
Mandatory: No
Description:

The page property is used to control the pagination in the prismaCrudService.findMany responses.

Page value must be 1 or greater.

Example:

const crudQuery = {    // ...    page: 2,};

---

CrudQuery.pageSize

Type: number
Mandatory: No
Description:

The pageSize property is used to control the pagination in the prismaCrudService.findMany responses. It be 1 or greater and will get overriden if passed a larger value than configured in the service.

Example:

const crudQuery = {    // ...    pageSize: 100,};

---