Prisma Query Parser

A zero-dependency, lightweight utility that automatically parses URL query parameters (like ?page=1&limit=10&sort=-createdAt) into Prisma ORM query arguments (skip, take, where, orderBy, select, include).

Features

• 🚀 Zero Dependencies: Pure TypeScript, no external bloat.
• 🔄 Pagination: Automatically handles page and limit.
• 📊 Sorting: Support for multiple fields and descending/ascending order.
• 🎯 Field Selection: Pick exactly which fields to return, including nested relations using dot notation (e.g., owner.name).
• 🔗 Relations: Fetch related models easily via include.
• 🔍 Advanced Filtering: Support for Prisma's advanced operators (gte, lte, contains, in, notIn).

Installation

npm install prisma-query-parser

or

yarn add prisma-query-parser

Quick Start (Express.js Example)

Just pass your req.query directly into the PrismaQueryBuilder.

import { Request, Response } from 'express';
import { PrismaQueryBuilder } from 'prisma-query-parser';
import { prisma } from './your-prisma-client';

export const getUsers = async (req: Request, res: Response) => {
  // 1. Initialize the builder with req.query
  const builder = new PrismaQueryBuilder(req.query);
  
  // 2. Build the Prisma query options
  const queryOptions = builder.build();

  // 3. Execute the Prisma query
  const users = await prisma.user.findMany(queryOptions);
  const total = await prisma.user.count({ where: queryOptions.where });

  // 4. Send response with optional pagination metadata
  res.json({
    data: users,
    meta: builder.getMeta(total, users.length)
  });
};

How to use Query Parameters

1. Pagination (page & limit)

GET /users?page=2&limit=5

2. Sorting (sort)

Prefix with - for descending order. Separate multiple fields by commas.

GET /users?sort=-createdAt,name

3. Field Selection (fields)

Limit the returned columns. Supports nested fields via dot notation!

GET /users?fields=id,name,email,profile.bio

4. Include Relations (include)

Fetch related tables.

GET /users?include=posts,profile

💡 Pro Tip: If you only need specific fields from a relation, use fields with dot notation (e.g., fields=profile.bio). You DO NOT need to pass include=profile. The builder automatically resolves the join, keeping your response payload clean and minimal!

5. Filtering (Exact Match)

Filter by exact values.

GET /users?role=ADMIN&city=Bandung

6. Advanced Filtering (Prisma Operators)

Use brackets to utilize Prisma's native comparison operators.

# Text search
GET /users?name[contains]=John

# Number comparisons
GET /products?price[gte]=1000&price[lte]=5000

# IN Array
GET /users?role[in]=ADMIN,MODERATOR

Type Conversion Configuration

Because query strings are always text, you might need to convert some fields into numbers or booleans before Prisma reads them.

You can pass a configuration object into the build() method:

const queryOptions = builder.build({
  numberFields: ['price', 'stock', 'rating'],
  booleanFields: ['isActive', 'isPublished']
});

License

MIT License