Skip to content

Commit

Permalink
Prettier: fixed configuration and ran agains the current state of the…
Browse files Browse the repository at this point in the history
… repo (adelsz#184)

* Fixed prettier rule

* Ran lint --fix

* Ran prettier

* Removed arrowParens pretteir option

* Added example package and ANTLR-generated files to be ignored by prettier and linter
  • Loading branch information
golergka authored Sep 21, 2020
1 parent 1da1dc1 commit e141244
Show file tree
Hide file tree
Showing 28 changed files with 682 additions and 643 deletions.
2 changes: 2 additions & 0 deletions .prettierignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
packages/example
packages/query/src/loader/*/parser/
3 changes: 1 addition & 2 deletions .prettierrc.yaml
Original file line number Diff line number Diff line change
@@ -1,3 +1,2 @@
trailingComma: "all"
trailingComma: 'all'
singleQuote: true
allowParens: avoid
9 changes: 5 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,14 +11,14 @@ No need to map or translate your DB schema to TypeScript, PgTyped automatically
---

## Features:

1. Automatically generates TS types for parameters/results of SQL queries of any complexity.
2. Supports extracting and typing queries from both SQL and TS files.
3. Generate query types as you write them, using watch mode.
4. Useful parameter interpolation helpers for arrays and objects.
5. No need to define your DB schema in TypeScript, your running DB is the live source of type data.
6. Prevents SQL injections by not doing explicit parameter substitution. Instead, queries and parameters are sent separately to the DB driver, allowing parameter substitution to be safely done by the PostgreSQL server.


### Documentation

Visit our new documentation page at [https://pgtyped.now.sh/](https://pgtyped.now.sh/)
Expand All @@ -29,11 +29,12 @@ Visit our new documentation page at [https://pgtyped.now.sh/](https://pgtyped.no
2. Create a PgTyped `config.json` file.
3. Run `npx pgtyped -w -c config.json` to start PgTyped in watch mode.

Refer to the [example app](./packages/example/README.md) for a preconfigured example.
Refer to the [example app](./packages/example/README.md) for a preconfigured example.

### Example

Lets save some queries in `books.sql`:

```sql
/* @name FindBookById */
SELECT * FROM books WHERE id = :bookId;
Expand Down Expand Up @@ -103,8 +104,8 @@ main();
1. [Configuring Pgtyped](https://pgtyped.now.sh/docs/cli)
2. [Writing queries in SQL files](https://pgtyped.now.sh/docs/sql-file-intro)
3. [Advanced queries and parameter expansions in SQL files](https://pgtyped.now.sh/docs/sql-file)
3. [Writing queries in TS files](https://pgtyped.now.sh/docs/ts-file-intro)
3. [Advanced queries and parameter expansions in TS files](https://pgtyped.now.sh/docs/ts-file)
4. [Writing queries in TS files](https://pgtyped.now.sh/docs/ts-file-intro)
5. [Advanced queries and parameter expansions in TS files](https://pgtyped.now.sh/docs/ts-file)

### Project state:

Expand Down
21 changes: 12 additions & 9 deletions docs-new/docs/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,26 +6,28 @@ sidebar_label: CLI config

`pgtyped` CLI can be launched in build or watch mode.
Watch mode is most useful for a local development workflow,
while build mode can be used for generating types when running CI.
while build mode can be used for generating types when running CI.

### Flags

The CLI supports two flags:
* `-c config_file_path.json` to pass the config file path.
* `-w` to start in watch mode.

- `-c config_file_path.json` to pass the config file path.
- `-w` to start in watch mode.

```shell script title="Example:"
npx pgtyped -w -c config.json
```

### Environment variables

PgTyped supports common PostgreSQL environment variables:
* `PGHOST`
* `PGUSER`
* `PGPASSWORD`
* `PGDATABASE`
* `PGPORT`
PgTyped supports common PostgreSQL environment variables:

- `PGHOST`
- `PGUSER`
- `PGPASSWORD`
- `PGDATABASE`
- `PGPORT`

These variables will override values provided in `config.json`.

Expand Down Expand Up @@ -65,6 +67,7 @@ By default, PgTyped saves generated files in the same folder as the source files
This behavior can be customized using the `emitTemplate` config parameter.
In that template, four parameters are available for interpolation: `root`, `dir`, `base`, `name` and `ext`.
For example, when parsing source/query file `/home/user/dir/file.sql`, these parameters are assigned the following values:

```
┌─────────────────────┬────────────┐
│ dir │ base │
Expand Down
2 changes: 1 addition & 1 deletion docs-new/docs/dynamic-queries.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ SELECT * FROM users
ORDER BY (CASE WHEN :asc = true THEN :sort_column END) ASC, :sort_column DESC;
```

### Advanced dynamic queries
### Advanced dynamic queries

More complicated dynamic queries can be built similarly to the above two.
Note that highly dynamic SQL queries can lead to worse DB execution times, so sometimes it is worth to split a complex query into multiple independent ones.
2 changes: 1 addition & 1 deletion docs-new/docs/features.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
id: features
title: Features
title: Features
sidebar_label: Features
---

Expand Down
5 changes: 2 additions & 3 deletions docs-new/docs/getting-started.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
id: getting-started
title: Getting Started
title: Getting Started
sidebar_label: Getting Started
---

Expand All @@ -13,6 +13,7 @@ sidebar_label: Getting Started
### Configuration

PgTyped requires a `config.json` file to run, a basic config file looks like this:

```json title="config.json"
{
"transforms": [
Expand All @@ -39,5 +40,3 @@ Refer to the [CLI page](cli) for more info on the config file, available CLI fla
:::note
If you are having trouble configuring PgTyped, you can refer to the [example app](https://github.com/adelsz/pgtyped/tree/master/packages/example) for a preconfigured example.
:::


10 changes: 5 additions & 5 deletions docs-new/docs/intro.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
---
id: intro
title: Overview
title: Overview
sidebar_label: Overview
---

PgTyped makes it possible to use raw SQL in TypeScript with guaranteed type-safety.
No need to map or translate your DB schema to TypeScript, PgTyped automatically generates types and interfaces for your SQL queries by using your running Postgres database as the source of type information.


## Project goals
* **Smooth dev experience** - Provide a smooth and reliable development experience for engineers that want to use raw SQL queries.
* **Static typing** - SQL queries are validated and fully usable by the typechecker.
* **No magic** - PgTyped is not a query builder or an ORM.

- **Smooth dev experience** - Provide a smooth and reliable development experience for engineers that want to use raw SQL queries.
- **Static typing** - SQL queries are validated and fully usable by the typechecker.
- **No magic** - PgTyped is not a query builder or an ORM.
5 changes: 3 additions & 2 deletions docs-new/docs/sql-file-intro.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,13 @@
---
id: sql-file-intro
title: Queries in SQL files
title: Queries in SQL files
sidebar_label: Queries in SQL files
---

Having installed and configured PgTyped it is now time to write some queries.
Having installed and configured PgTyped it is now time to write some queries.

Lets create our first query in `books/queries.sql`:

```sql title="books/queries.sql"
/* @name FindBookById */
SELECT * FROM books WHERE id = :bookId;
Expand Down
35 changes: 26 additions & 9 deletions docs-new/docs/sql-file.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
---
id: sql-file
title: Annotated SQL files
title: Annotated SQL files
sidebar_label: Annotated SQL files
---

PgTyped supports parsing queries from SQL files, allowing developers to write DB queries in their favourite database IDE.
To help PgTyped generate executable queries from these SQL files, they need to be annotated with special comments.
To help PgTyped generate executable queries from these SQL files, they need to be annotated with special comments.

```sql title="example.sql"
/* @name getAllComments */
Expand All @@ -21,6 +21,7 @@ SELECT FROM users WHERE age in :ages;
## Annotation format

PgTyped has a number of requirements for SQL file contents:

1. Each query must be preceded with an annotation (comment).
2. An annotation must specify the query name using the `@name` tag.
3. Each query must be a single SQL statement that ends with a semicolon.
Expand All @@ -46,6 +47,7 @@ VALUES :comments;
Here `comments -> ((userId, commentBody)...)` is a parameter expansion that instructs pgtyped to expand `comments` into an array of objects with each object having a `userId` and `commentBody` field.

A query can also contain multiple expansions if needed:

```sql
/*
@name selectSomeUsers
Expand All @@ -59,79 +61,94 @@ At the moment, PgTyped supports three expansion types:

### Array spread

The array spread expansion allows to pass an array of scalars as parameter.
The array spread expansion allows to pass an array of scalars as parameter.

#### Syntax:

```
@param paramName -> (...)
```

#### Example:

```sql title="Query definition:"
/*
@name selectSomeUsers
@param ages -> (...)
*/
SELECT FROM users WHERE age in :ages;
```

```ts title="Execution:"
const parameters = { ages: [25, 30, 35] };
selectSomeUsers.run(parameters, connection);
```

```sql title="Resulting query:"
-- Parameters: [25, 30, 35]
SELECT FROM users WHERE age in ($1, $2, $3);
```

### Object pick

The object pick expansion allows to pass an object as a parameter.
The object pick expansion allows to pass an object as a parameter.

#### Syntax:

```
@param paramName -> (name, age)
```

#### Example:

```sql title="Query definition:"
/*
@name insertUsers
@param user -> (name, age)
*/
INSERT INTO users (name, age) VALUES :user RETURNING id;
```

```ts title="Execution:"
const parameters = { user: {name: 'Rob', age: 56} };
const parameters = { user: { name: 'Rob', age: 56 } };
insertUsers.run(parameters, connection);
```

```sql title="Resulting query:"
-- Bindings: ['Rob', 56]
INSERT INTO users (name, age) VALUES ($1, $2) RETURNING id;
```

### Array spread and pick

The array spread-and-pick expansion allows to pass an array of objects as a parameter.
The array spread-and-pick expansion allows to pass an array of objects as a parameter.

#### Syntax:

```
@param paramName -> ((name, age)...)
```

#### Example:

```sql title="Query definition:"
/*
@name insertUsers
@param users -> ((name, age)...)
*/
INSERT INTO users (name, age) VALUES :users RETURNING id;`;
```

```ts title="Execution:"
const parameters = {
users: [
{name: 'Rob', age: 56},
{name: 'Tom', age: 45},
]
{ name: 'Rob', age: 56 },
{ name: 'Tom', age: 45 },
],
};
insertUsers.run(parameters, connection);
```

```sql title="Resulting query:"
-- Bindings: ['Rob', 56, 'Tom', 45]
INSERT INTO users (name, age) VALUES ($1, $2), ($3, $4) RETURNING id;
Expand Down
35 changes: 21 additions & 14 deletions docs-new/docs/ts-file-intro.md
Original file line number Diff line number Diff line change
@@ -1,21 +1,24 @@
---
id: ts-file-intro
title: SQL-in-TS
sidebar_label: Queries in TS files
sidebar_label: Queries in TS files
---

It sometimes makes sense to inline your queries instead of collecting them in separate SQL files.
PgTyped supports inlined queries using the `sql` template literal.
To see how that works lets write some queries in `users/queries.ts`:

```ts title="users/queries.ts"
import { sql } from "@pgtyped/query";
import { ISelectUserIdsQuery } from "./queries.types.ts";
import { sql } from '@pgtyped/query';
import { ISelectUserIdsQuery } from './queries.types.ts';

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

PgTyped parses your TS files, scanning them for `sql` queries and generating corresponding TS interfaces in `users/queries.types.ts`:

```ts title="users/queries.types.ts"
/** Types generated for queries found in "users/queries.ts" */

Expand All @@ -38,20 +41,24 @@ export interface ISelectUserIdsResult {
```

We can now pass the `ISelectUserIdsQuery` as a generic parameter to our query in `users/queries.ts`:

```ts title="users/queries.ts"
import { sql } from "@pgtyped/query";
import { ISelectUserIdsQuery } from "./queries.types.ts";
import { sql } from '@pgtyped/query';
import { ISelectUserIdsQuery } from './queries.types.ts';

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

const users = await selectUserIds.run({
id: "some-user-id",
const users = await selectUserIds.run(
{
id: 'some-user-id',
age: 34,
}, connection);
},
connection,
);

console.log(users[0]);
console.log(users[0]);
```

For more information on writing queries in TS files checkout the [SQL-in-TS](ts-file) guide.

Loading

0 comments on commit e141244

Please sign in to comment.