Convert any SQL query into an API.
Add the package and its peer dependencies to your project
yarn add slonik-trpc slonik zod- Declarative filtering API (filter creation utils included!)
- Automatic support for
AND,NOT,ORin all the filters - Ability to add authorization filters based on user auth context.
- Automatic support for
- Select the fields you need, to avoid the overfetching problem.
- Fully type-safe, only selected fields are returned in the types. If no selects are specified, every field is returned.
- Runtime validation of input (completely safe against unsanitized inputs).
- Optional runtime validation of output (Your zod types can be executed against your result, including transforming the output fields with zod transformers).
- Virtual field declaration in typescript (fully type-safe + with async support).
- Declarative sorting capabilities, with support for custom SQL sorting expressions
- DISTINCT ON support with PostgreSQL, for all sortable columns
- Offset-based pagination.
- Cursor-based pagination.
- Reverse page support
- Plugins
TypeScript 4.5+ Slonik 33+ Zod 3+
Basic demo of a table with pagination, sorting and filtering in codesandbox.
Playground where you can see the SQL queries that the engine creates for custom loaders.
Let's say you have this SQL query for a list of posts you'd like to create an API for
SELECT "posts".id
, "users"."firstName" || ' ' || "users"."lastName" AS "author"
, "posts"."text"
, EXTRACT(DAYS FROM NOW() - posts."created_at") AS "age"
FROM users
LEFT JOIN posts
ON posts.author = users.idFirst, get the FROM clause part of the query and build a "view" with it.
import { buildView, sql } from 'slonik-trpc';
const postsView = buildView`
FROM users
LEFT JOIN posts
ON posts.author = users.id`
// Allows filtering posts.title: { _ilike: '%hello%' }
.addStringFilter('posts.title')
// Allows filter id: [1, 2, 3]
.addInArrayFilter('id', () => sql.fragment`posts.id`, 'numeric')You can add filters when building the view. The above filters allow searching posts by their title, or their id.
Then get the SELECT part of the query, and specify the return type with zod.
import { z } from 'zod';
import { sql, makeQueryLoader } from 'slonik-trpc';
const queryType = z.object({
id: z.string(),
author: z.string(),
text: z.string(),
age: z.number(),
});
const selectQuery = sql.type(queryType)`
SELECT "posts".id
, "users"."firstName" || ' ' || "users"."lastName" AS "author"
, "posts"."text"
, EXTRACT(DAYS FROM NOW() - posts."created_at") AS "age"
`
// This loader is the type-safe API
const loader = makeQueryLoader({
db: slonikConnection, // Any connection pool will do
query: {
select: selectQuery,
view: postsView,
}
});Now you can query this loader/API by selecting just the fields you need.
// This array is type-safe, only having "id", "text", and "age" fields (no author)
const posts = await loader.load({
select: ["id", "text", "age"],
where: {
OR: [{
"posts.title": "Lorem Ipsum",
}, {
"posts.id": [3, 4],
}]
},
take: 200,
});Read on for more advanced usage, including how to use sorting, filtering, cursor pagination, authorization checks, creating a tRPC API and more.
You can refer to the documentation for advanced use-cases and tutorials.
Read slonik documentation for how to get started with it, but you can also use other clients, as long as they accept SQL and return an array of objects.
Databases other than PostgreSQL aren't supported as of now, but can be made to work in limited use-cases (e.g. sqlite will work by specifying useSqlite in options).
Let's say you want to add a custom sub-query as a field to your relation. You can do this very easily.
import { sql, buildView } from 'slonik-trpc';
const query = sql.type(z.object({
id: z.string(),
name: z.string(),
email: z.string(),
authoredPosts: z.number(),
created_at: z.string()
}))`SELECT *,
-- Count all the posts of the user as a number
(SELECT COUNT(*) FROM posts WHERE posts.author = users.id) AS "authoredPosts"`;
const userView = buildView`FROM users`;Note this count sub-query will be called only when the authoredPosts selected. Otherwise the database won't execute it, ensuring optimal performance.
Use loader.getLoadArgs for getting the tRPC query input zod type.
getUsers: publicProcedure
.input(loader.getLoadArgs({
disabledFilters: {
// OR filters can be disabled on a public API
OR: true,
}
}))
.query(({ input, ctx }) => {
return loader.loadPagination({
...input,
ctx,
});
}),Now it can be called via tRPC:
const users = await client.getUsers.query({
select: ["id", "name", "email"], // Will query only these 3 columns, ignoring the rest
take: 25,
skip: 0,
});This returns a relay-like pagination result, with nodes and pageInfo keys.
You can add any filter to the API, by specifying the filter type, and the optional interpreter function that converts the filter input to a SQL fragment, in a declarative way.
Here's an example:
buildView`FROM users`
.addInArrayFilter('id')
.addStringFilter(['users.name', 'users.profession'])
.addComparisonFilter('postsCount', () => sql.fragment`users."authoredPosts"`)
.addDateFilter('createdDate', () => sql.fragment`users.created_at`)
.addJsonContainsFilter('users.settings') // jsonb column
.addBooleanFilter('isGmail', () => sql.fragment`users.email ILIKE '%gmail.com'`)AND, OR and NOT filters are added automatically, to allow more complex combinations.
const specificUsers = await filtersLoader.load({
where: {
// users created between yesterday and now
createdDate: {
_lte: new Date().toISOString(),
_gte: new Date(Date.now() - 1000 * 3600 * 24).toISOString(),
},
"users.settings": {
// This allows filtering by a nested jsonb/json column
notifications: true,
// Users whose settings have notifications turned on, and a dark theme
theme: 'dark'
},
"users.profession": {
_ilike: '%engineer%',
},
OR: [{
// Returns users with these specific ids
id: ['x', 'y'],
}, {
// or non-gmail users.
isGmail: false,
}, {
// Or with less than 20 posts (by inverting the postsCount greater than filter)
NOT: {
postsCount: {
_gte: 20,
},
}
}]
}
});The AND, OR, and NOT can be disabled when calling getLoadArgs, and it is recommended to do so for the OR filter, which is often computationally expensive and shouldn't be allowed on a public API.
loader.getLoadArgs({
disabledFilters: {
// OR filters should be disabled on a public API
OR: true,
}
})The addGenericFilter method offers more freedom, by letting you specify any valid SQL fragment in response to a value. The filter is then applied for any non-null value.
For authorization checks, use the constraints option to add hardcoded conditions to the query, based on the context.
const userLoader = makeQueryLoader({
db,
query,
filters,
constraints(ctx) {
if (ctx.role === 'ADMIN') {
// Allow admins to query anyone by returning no extra permission rules.
return null;
} else {
// Only allow querying the users in the same org as the logged in user
return sql.fragment`users.org_id=${ctx.orgId}`;
}
}
});Constraints are like hardcoded filters that are always applied.
Any kind of SQL condition will do, and you can also return an array of multiple conditions, they will be joined with AND.
You can also specify constraints when creating a view
const userView = buildView`FROM posts
LEFT JOIN users
ON posts.author = users.id`
.setConstraints((ctx) => {
return sql.fragment`users.org_id=${ctx.orgId}`;
})These conditions will be added anywhere the view is used.
If you need to check specific columns, you can virtualize them with the same name, and run any checks.
const virtualFieldsLoader = makeQueryLoader({
query,
virtualFields: {
name: {
resolve(row, ctx) {
if (!ctx.isLoggedIn) {
// Return null if user isn't logged in.
return null;
}
return row.name;
}
},
email: {
resolve(row, ctx) {
if (ctx.isAdmin) {
// Only return user emails if current user is admin.
return row.email;
}
return null;
},
},
}
});Define your sortable column aliases. You can use strings or sql fragments to identify the columns.
const sortableLoader = makeQueryLoader({
query,
sortableColumns: {
id: sql.fragment`users.id`,
name: "name",
// All 3 methods are acceptable as long as the specified column is accessible from the FROM query and non-ambiguous
createdAt: ["users", "created_at"],
},
});
const sortedByName = await db.any(await sortableLoader.getQuery({
orderBy: ["name", "ASC"],
}));
const sortedByNameAndDate = await db.any(await sortableLoader.getQuery({
orderBy: [["name", "DESC"], ["id", "ASC"]],
take: 5,
}))If you don't specify any sortableColumns your API won't be sortable with orderBy.
If you specify a negative take, the order will be reversed, this is useful for getting the last page...
const lastPage = await db.any(await sortableLoader.getQuery({
orderBy: [["name", "DESC"], ["id", "ASC"]],
take: -25,
}));You can additionally use sortableColumns in the distinctOn option.
To get only posts by distinct authors use this:
const distinctAuthors = await db.any(await sortableLoader.getQuery({
distinctOn: ["name"],
take: 5,
}))You can add a groupBy fragment to your query, to be able to use aggregates in your select.
E.g. for getting the user's posts count, you can use
const groupedLoader = makeQueryLoader({
query: {
select: sql.type(z.object({
count: z.number(),
name: z.string(),
}))`SELECT COUNT(*), users.name`,
view: buildView`FROM posts
LEFT JOIN users
ON posts.author = users.id`
.addInArrayFilter('posts.category'),
groupBy: sql.fragment`users.name`,
},
});Now you can easily filter authors by their posts, and still get the posts count.
const bigPostsCount = await sortableLoader.load({
where: {
'posts.category': ["typescript"]
},
});
// Returns counts of typescript posts for each user.If you've enabled any sorting columns, you can use cursor-based pagination with cursur. Simply specify the cursor of the item you'd like to paginate after.
const usersAfterBob = await db.any(await sortableLoader.getQuery({
orderBy: [["name", "DESC"], ["id", "ASC"]],
cursor: "eyJuYW1lIjoiQm9iIiwiaWQiOjQ1fQ==",
take: 5,
}));You'd normally retrieve this cursor from the previous result e.g. result.pageInfo.endCursor, if you specify takeCursors: true.
You can also do prisma-style cursor pagination by supplying the values yourself.
const usersAfterBob = await db.any(await sortableLoader.getQuery({
orderBy: [["name", "DESC"], ["id", "ASC"]],
searchAfter: {
name: "Bob",
id: 45,
},
take: 5,
}))This is equivalent to the above example, since eyJuYW1lIjoiQm9iIiwiaWQiOjQ1fQ== base64 decoded is {"name":"Bob","id":45}.
Virtual fields are only supported when using load/loadPagination currently.
const virtualFieldsLoader = makeQueryLoader({
query,
virtualFields: {
fullName: {
dependencies: ["first_name", "last_name"],
async resolve(row) {
// async code supported
return Promise.resolve(row.first_name + row.last_name);
},
},
}
});The virtual fields can then be selected like normal fields.
If you need to load remote data in your virtual fields, it's often more efficient to use a batch loader, rather than returning a promise in the resolve function of each row. Use load for this purpose.
virtualFields: {
posts: {
dependencies: ["id"],
// 📉 This can lead to performance issues.
resolve: async (row) => {
const posts = await fetchPostsForAuthor(row.id);
return posts;
}
}
},virtualFields: {
posts: {
dependencies: ["id"],
// 🚀 Use the load function to fetch data in batches
async load(rows) {
const allPosts = await fetchPostsForAuthors(rows.map(row => row.id));
return allPosts;
},
// ✔️ Use the resolve function to handle synchronous operations.
resolve: (row, args, posts) => {
// Only return the posts of each user.
return posts.filter(post => post.authorId = row.id)
}
}
},You can query a view directly for easier usage.
const usersView = buildView`FROM users`
.addInArrayFilter('id')
.addStringFilter(['users.name', 'users.profession'])
.addComparisonFilter('postsCount', () => sql.fragment`users."authoredPosts"`)
.addDateFilter('createdDate', () => sql.fragment`users.created_at`)
.addJsonContainsFilter('users.settings') // jsonb column
.addBooleanFilter('isGmail', () => sql.fragment`users.email ILIKE '%gmail.com'`)
.setColumns(["name", "profession", "email"])
.setColumns({
createdDate: sql.fragment`users.created_at AS "createdDate"`,
postsCount: sql.fragment`( SELECT COUNT(*) FROM posts
WHERE posts.user_id = users.id) AS "postsCount"`,
})
const data = await usersView.load({
select: ["name", "profession", "postsCount"],
where: {
id: [1, 2],
},
orderBy: sql.fragment`users.name DESC`,
})The idea is you declare all the filters and relevant columns upfront, and then you can reuse them easily.
You can use PostgreSQL functions for creating json arrays and objects in your query. Two such utils are exposed for convenience through rowToJson and rowsToArray.
import { rowToJson, rowsToArray } from 'slonik-trpc/utils';
const query = sql.type(z.object({
id: z.string(),
name: z.string(),
email: z.string(),
contactInfo: z.object({
phoneNumber: z.string(),
zip: z.string(),
address: z.string(),
}),
posts: z.array(z.object({
text: z.string(),
title: z.string(),
})),
}))`SELECT
users.id,
name,
email,
${rowToJson(sql.fragment`
SELECT "phoneNumber", "zip", "address"
WHERE contact_info.id IS NOT NULL
`, 'contactInfo')}
${rowsToArray(sql.fragment`
SELECT text, title`, sql.fragment`
FROM posts
WHERE posts.author = users.id`,
'posts'
)}
FROM users
LEFT JOIN contact_info
ON contact_info.id = users.contact_info`;If you wanna prevent conflicts of field names when joining multiple tables, it's recommended to wrap the whole query in a SELECT * FROM (subQuery) alias, which has the effect of returning only a single view, thus making conflicts impossible.
Refer to the minimal-example, or datagrid-example for more complete examples.
This is not officially supported, but you can actually provide any function to the db loader argument. Then you won't have to setup slonik client and can use another one like prisma client, as long as it's able to send SQL queries.
So with prisma you can write the following when creating the loader:
export const loader = makeQueryLoader({
query,
db: {
any: (sql) => {
return prisma.$queryRawUnsafe(sql.sql, ...sql.values);
}
},
// ...You still need to install slonik and zod though, for composing query fragments with. Since the SQL string is generated from slonik, it's completely safe from SQL injection, so it's safe to be used with prisma.$queryRawUnsafe.
It is likely you will run into issues doing this though, so using the slonik package as a client is recommended. Refer to the documentation for a minimal setup example of slonik client.
Yes, any PostgreSQL query is supported. So you can do anything that is allowed in PostgreSQL, e.g. to get postCount of users directly in a sub-query do
SELECT id
, name
, (SELECT COUNT(*) FROM posts WHERE users.id = posts.author_id) AS postCount
, email
, created_at
FROM usersIt is theoretically possible to infer the zod type from the SQL query you write. E.g. @slonik/typegen generates typescript types.
Let me know if there already are packages that convert PostgreSQL queries to zod types, we can try to make them compatible and easier to work with the query loaders.
This is a good issue to contribute on. All help is welcome!
If you mean debugging during runtime, you can do export DEBUG=slonik-trpc.
You can also run getQuery with the same parameters as load/loadPagination, and it will return the raw SQL query without executing anything.
This is useful for many reasons, e.g. if you want to analyze a slow query, you can measure the time it takes to run, and then print out the SQL for any queries that are slower than a threshold.
Note that loadPagination will run an extra query for getting the total count, if you specify takeCount: true. This is the same query as returned by getQuery, but wrapped in a SELECT COUNT query like
SELECT COUNT(*) FROM (...) subQueryMany features of ORMs, such as updating data, aren't supported at all by this package.
However, this package can be integrated with any ORM that supports executing raw queries, such as prisma.
So you can use them both at the same time, by using slonik-trpc to build a type-safe yet flexible read-only API, and use the ORM for the rest.
If you're passing a select array conditionally, typescript type inference doesn't allow getting the underlying type correctly. You'll have to use type assertions in that case, use as any if one condition has an empty array/undefined to get all the fields returned properly. Otherwise typescript will only return id/name.
const data = await loader.load({
select: someCondition ? ['id', 'name'] : [] as any
})Do not pass any conditions after the select ... from statement. If you must run custom SQL conditions in your queries, simply wrap them in a sub-query
const query = sql.type(z.object({
id: z.string(),
name: z.string(),
email: z.string(),
created_at: z.string()
}))`SELECT * FROM (
SELECT id, name, email, created_at
FROM users
WHERE users.created_at > NOW() - INTERVAL '1 month'
ORDER BY users.created_at
) x`;Due to typescript limitations it's not possible to infer the returned types automatically in the clientside with trpc. So all fields will be selected by default, even if you only select a few.
To get around this, you can use InferPayload and pass the arguments as a generic argument.
server
import type { InferPayload, InferArgs } from 'slonik-trpc';
const postsLoader = makeQueryLoader(...);
type PostLoader = typeof postsLoader;
export type {
InferPayload, InferArgs, PostLoader
}client
const getPosts = <TArgs extends InferArgs<PostLoader>>(args: TArgs) => {
return client.loadPosts.query(args) as Promise<InferPayload<PostLoader, TArgs>[]>;
}Or with hooks + loadPagination and a useful type annotation to replace the pagination nodes key easily.
import type { InferArgs, InferPayload, Post } from '../../server';
type ReplaceNodes<TResult, TPayload> = TResult extends { nodes?: ArrayLike<any>, hasNextPage?: boolean } ? Omit<TResult, "nodes"> & {
nodes: TPayload[]
} : TResult extends object ? {
[K in keyof TResult]: ReplaceNodes<TResult[K], TPayload>
} : TResult;
const getPosts = <TArgs extends InferArgs<PostLoader>>(args: TArgs) => {
const result = trpc.loadPosts.useQuery(args);
return result as ReplaceNodes<typeof result, InferPayload<PostLoader, TArgs>>;
}You don't need to do this if your selects are dynamic, in that case simply consider all fields optional.
Also this is not necessary when querying the loader directly in the serverside, in those cases fields will be automatically inferred depending on your selections.
There are more advanced patterns to support relay-like fragment selections, or cursor pagination that allows rendering each table column in a type-safe method.
Contributions, issues and feature requests are welcome!
Feel free to check issues page.
Export your postgres database URL, then run yarn test
export DATABASE_URL=postgresql://postgres:password@localhost:5432/database
yarn test- Prisma generator similar to zod-prisma that automatically creates data loaders from prisma schemas.
- Automatically syncing the zod types with sql, using something like @slonik/typegen
- Wildcards in selects, e.g.
select: ["name*"]to select all fields that start with name. - Custom loaders and/or plugins/middlewares for processing query results.
- Mutations, through an update API builder.
- Furthermore, building an entire CRUD tRPC API, by only requiring you to declare small SQL fragments and their zod types. Similar to hasura.
Integration with prisma client raw database access, and other DB clients, separating data loading from query composition.Done.