Skip to content
PgTyped - Typesafe SQL in TypeScript
TypeScript JavaScript
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github/workflows Export type-aware sql tag Sep 28, 2019
packages v0.1.2 Sep 29, 2019
.gitignore Commit all Jun 13, 2019
LICENSE Create LICENSE Sep 28, 2019
README.md Add parameter substitution details to README Sep 29, 2019
demo.gif Add demo.gif recording Sep 29, 2019
lerna.json v0.1.2 Sep 29, 2019
package-lock.json Rename to pgtyped Sep 28, 2019
package.json Cleanup Sep 28, 2019
tsconfig.json Commit all Jun 13, 2019
tslint.json Add linter and lint codebase Sep 27, 2019

README.md

PgTyped

Actions Status

SQL query type generator.
Finally you can use raw SQL with guaranteed type-safety.
Works with PostgreSQL and TypeScript.

Features:

  1. Automatically generates types for parameters/results of SQL queries of any complexity.
  2. Generate query types as you write them using watch mode.
  3. Useful parameter interpolation helpers for arrays and objects.
  4. No need to define your DB schema in TypeScript, your running DB is the live source of type data.
  5. Prevents SQL injections by not doing explicit parameter substitution. Instead it passes each query together with its parameter bindings to the DB driver, allowing parameter substitution to be done by the PostgreSQL server.

Example:

Query code:

import sql from "@pgtyped/query";

export const selectUserIds = sql<
  ISelectUserIdsResult, ISelectUserIdsParams
  >`select id from users where id = $id and age = $age`;
`;

Generated TypeScript interfaces:

/** 'selectUserIds' parameters type */
export interface ISelectUserIdsParams {
  id: string | null;
  age: number | null;
}

/** 'selectUserIds' return type */
export interface ISelectUserIdsResult {
  id: string;
}

To run the selectUserIds query:

  const users = await selectAllUsers.run({
    id: "some-user-id",
  }, connection);

  console.log(users[0]);

Demo:

Getting started:

  1. npm install @pgtyped/cli @pgtyped/query typescript
  2. Create a config file for the type generator
  3. Put your queries in separate files (ex. queries.ts) and use the sql tag when defining them.
  4. Run npx pgtyped to generate query type files.

You can also refer to the example app, to see pgtyped in action.
Additional details are available in READMEs for the @pgtyped/cli and @pgtyped/query packages.

Using PgTyped:

pgtyped command scans your srcDir for query files,

Interpolation helpers:

Helper Syntax Parameter Type
Named parameters $paramName paramName: ParamType
Single value list $paramName(name, author) paramName: { name: NameType, author: AuthorType }
Multiple value list $$paramName paramName: Array<ParamType>
Multiple value list $$paramName(name, author) paramName: Array<{ name: NameType, author: AuthorType }>

Example insertUsers:

INSERT INTO users (name, age)
VALUES $$users(name, age) RETURNING id

can be executed as follows:

const usersToInsert = [
  { name: 'Bob', age: 12 },
  { name: 'Tom', age: 16 },
];
const result = await insertUsers(usersToInsert, connection);

Project state:

This project is still in an experimental stage so its APIs are expected to change a lot in the short term. Any help in the form of issue reports, feature requests or PRs is very appreciated.

License

MIT

Copyright (c) 2019-present, Adel Salakh

You can’t perform that action at this time.