@typesql/postgres 0.2.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/CHANGELOG.md +9 -0
  2. package/README.md +13 -52
  3. package/package.json +2 -2
package/CHANGELOG.md CHANGED
@@ -1,5 +1,14 @@
1
1
  # @typesql/postgres
2
2
 
3
+ ## 0.2.1
4
+
5
+ ### Patch Changes
6
+
7
+ - The README is shorter: install, one example and links to the docs site, which now has the details it used to repeat.
8
+
9
+ - Updated dependencies:
10
+ - @typesql/core@0.6.0
11
+
3
12
  ## 0.2.0
4
13
 
5
14
  ### Minor Changes
package/README.md CHANGED
@@ -1,16 +1,13 @@
1
1
  # @typesql/postgres
2
2
 
3
- [postgres.js](https://github.com/porsager/postgres) (`postgres` 3.x) adapter for
4
- [`@typesql/core`](https://www.npmjs.com/package/@typesql/core): a `createSql` bound to the type
5
- map of postgres.js' default parsers, whose queries run on your `sql` instance and return rows
6
- typed from the SQL.
3
+ Run [TypeSQL](https://www.npmjs.com/package/@typesql/core) queries on [postgres.js](https://github.com/porsager/postgres) (`postgres` 3.x), with rows typed the way postgres.js returns them.
4
+
5
+ ## Install
7
6
 
8
7
  ```sh
9
- pnpm add @typesql/core @typesql/postgres postgres
8
+ npm install @typesql/core @typesql/postgres postgres
10
9
  ```
11
10
 
12
- [Open an example in the TypeScript Playground](https://www.typescriptlang.org/play/#code/PTAEBUE8AcFMGUCKAZUB3AlgFwBamgPYDOWA5gE6xEB0AVkaABQACWMVAjgDbCEkVUAlNVCIArrHIYqocmIB26bHiLdqCogEMAZrEZZYADywAaUADdNXCUUFnN8gCayCaIgCgQoTZVBs4zgBGkOg4mlj4xGSUNPT4PkRUAFygGPJYABypDJqgJFLypGYE5N6ggRikaRGYuKAAQpUAkunx5ERppKAE8tTu7hgAtoTkEf6woADeoADCBFxmAOKw8pLhsI5mAHJiXFyagVwTAL6g2uQEg6AARKzsqjwAxiWw1wDcA8MlEdOPlOvwbigU7nS43O5wB68KICIjvT4jMbsKagQFcYFnC5Xa58aJUeEDdKSbSaR4TAAi9Sm7gAkGJEu0UpNaTSMI4UstVuR1o4ADzXaoAFmuAD4PjSabBBpoMFwUnMuPyDMZReKaY4MERoPtIAB9eSaQawFI7PYHI5KoxYVUsv6wHm68IclZrAx865YIZULCG6BYABeNppx3FuKITJZbOdXJ5-OqGSDNM0YlwJV1Udm8zj6WFYpZnqwR3lWY9VsTPtI4czitLxgA2gBdIMh9zHfqOWCPfa+Z7yEigRyBFJot6gLy42GMHEwmJJEBcAiPKw4KLATTQaDXQTuXv9h6gAC8oDtAO4vMpIsYg8EHx3PX7YcP3jQMoiD0YtIABvAAKLIH8zOAqSbH42BHGYFYMAAYgASgA8gAspEJAMAA6gAEj+ME-qAAAkACMT4AIJbAAmkwkGCJ+Ji0tcDzXDRwhGJ2KZ6DenhgKAXEAHoAPz9F4cGKLkvarI8no9EodSfuMVbTBUVTpCkE4xNQjSkC0ETHNRqTpFkDjOM8ChYIwABUgjHpcEyBKSADW3gMAp1R9B2XY+BMu4RIO6nDme8mVNUKROa0xx5p55SVE+J4GGi571Je3mVGY-mKVgKRYHIJzseFRnpAwR6aC+2ARaQH40t+f4AUByapuQ6YgblJnmaARHwKAiiwYhyFYAwizwQAqgACg05E1SudVstR7hMYYLEGIw7FeFxoB8QJYAPNQGUOFo4kYJJmp5GogSwIpo5YIYm3cn2pISYoB25Fo5iwIQznuIVr6HVwl3bTde3yIwmhEJA8iPBRhgWQeIrUkmRVjIYZXlUN5JEeAOGPr+QEFkcT5iBukj6GBsAWRhWE4WNaZsk+BFTRKADsNE0jNc1seK4WKAVsN+PDLKfuSlWo6AnVIY+JPYcePgagaXDYJA+iaJWEOgAADDTTOPKxczGQt4pLTx-HHOx7jvhV-6AcBgvwcLURoZhYuQaAzBQ9TZh0dwW6jl4kgXOQ6Xywwjt+JotkyLkypYI27hAA) <!-- playground:postgres --> to hover the types and edit the SQL, with nothing to install.
13
-
14
11
  ## Usage
15
12
 
16
13
  ```ts
@@ -18,61 +15,25 @@ import postgres from "postgres";
18
15
  import { createSql } from "@typesql/postgres";
19
16
  import type { DB } from "./schema";
20
17
 
21
- const db = postgres(process.env.DATABASE_URL!);
22
- const sql = createSql<DB>(db); // PostgresJsTypeMap
18
+ const sql = createSql<DB>(postgres(process.env.DATABASE_URL!));
23
19
 
24
20
  const posts = await sql("SELECT id, title FROM posts WHERE author_id = $1", 1).execute();
25
- // { id: string; title: string }[] int8 is a string by default
21
+ // { id: string; title: string }[] (int8 is a string by default)
26
22
 
27
23
  await sql.transaction(async (tx) => {
28
24
  await tx("UPDATE posts SET title = upper(title) WHERE author_id = $1", 1).execute();
29
25
  });
30
26
  ```
31
27
 
32
- With bigint parsing enabled on the connection, pass `{ bigint: true }`:
28
+ If your connection parses `int8` to `bigint` (`types: { bigint: postgres.BigInt }`), pass `{ bigint: true }` as the second argument of `createSql`.
33
29
 
34
- ```ts
35
- const dbBig = postgres(process.env.DATABASE_URL!, { types: { bigint: postgres.BigInt } });
36
- const big = createSql<DB>(dbBig, { bigint: true }); // PostgresJsBigIntTypeMap
37
-
38
- const counts = await big("SELECT author_id, count(*) AS n FROM posts GROUP BY author_id").execute();
39
- // { author_id: number; n: bigint }[]
40
- ```
41
-
42
- ## API
43
-
44
- | Export | |
45
- |---|---|
46
- | `createSql<DB>(db, options?)` | core's `createSql<DB, PostgresJsTypeMap>()` with the queries running on `db`; `{ rowKeys: "camelCase" }` camelCases the row keys, `{ bigint: true }` uses `PostgresJsBigIntTypeMap`, for `types: { bigint: postgres.BigInt }` |
47
- | `q.execute()`, `q.executeTakeFirst()`, `q.executeTakeFirstOrThrow()`, `q.executeCount()` | `Promise<Row[]>` (a plain array, result metadata stripped), `Promise<Row \| undefined>`, `Promise<Row>` (`NoResultError` on 0 rows), `Promise<number>` (`.count`, 0 for DDL) |
48
- | `sql.transaction(fn)` | `db.begin(fn)` with `tx` bound to the transaction; `tx.transaction(fn)` is `savepoint(fn)` |
49
- | `executor(db)` | an `Executor` for `q.execute(executor)` and core's `createSql(executor)` (reports `.count`) |
50
- | `migrate(db, m)` | runs `m.statements` (e.g. from core's `migrations()`) in one transaction |
51
- | `PostgresJsSql<DB, Keys, TM>` | the type `createSql` returns (`TM` is `PostgresJsBigIntTypeMap` with `{ bigint: true }`) |
52
- | `PostgresJsTypeMap`, `PostgresJsBigIntTypeMap`, `PostgresJsParamTypeMap` | the type maps (rows), and what parameters also accept |
53
- | `PostgresJsQueryable`, `PostgresJsTransactable`, `PostgresJsRows`, `MigrationSource` | parameter types |
54
-
55
- Queries run with `db.unsafe(text, values)`, so the text reaches the server unchanged and values
56
- are bind parameters. `db` is the `Sql` instance, a `TransactionSql` or a `ReservedSql`.
57
-
58
- ## Type maps
30
+ [Open an example in the TypeScript Playground](https://www.typescriptlang.org/play/#code/PTAEBUE8AcFMGUCKAZUB3AlgFwBamgPYDOWA5gE6xEB0AVkaABQACWMVAjgDbCEkVUAlNVCIArrHIYqocmIB26bHiLdqCogEMAZrEZZYADywAaUADdNXCUUFnN8gCayCaIgCgQoTZVBs4zgBGkOg4mlj4xGSUNPT4PkRUAFygGPJYABypDJqgJFLypGYE5N6ggRikaRGYuKAAQpUAkunx5ERppKAE8tTu7hgAtoTkEf6woADeoADCBFxmAOKw8pLhsI5mAHJiXFyagVwTAL6g2uQEg6AARKzsqjwAxiWw1wDcA8MlEdOPlOvwbigU7nS43O5wB68KICIjvT4jMbsKagQFcYFnC5Xa58aJUeEDdKSbSaR4TAAi9Sm7gAkGJEu0UpNaTSMI4UstVuR1o4ADzXaoAFmuAD4PjSabBBpoMFwUnMuPyDMZReKaY4MERoPtIAB9eSaQawFI7PYHI5KoxYVUsv6wHm68IclZrAx865YIZULCG6BYABeNppx3FuKITJZbOdXJ5-OqGSDNM0YlwJV1Udm8zj6WFYpZnqwR3lWY9VsTPtI4czitLxgA2gBdIMh9zHfqOWCPfa+Z7yEigRyBFJot6gLy42GMHEwmJJEBcAiPKw4KLATTQaDXQTuXv9h6gAC8oDtAO4vMpIsYg8EHx3PX7YcP3jQMoiD0YtIABvAAKLIH8zOAqSbH42BHGYFYMAAYgASgA8gAspEJAMAA6gAEj+ME-qAAAkACMT4AIJbAAmkwkGCJ+Ji0tcDzXDRwhGJ2KZ6DenhgKAXEAHoAPz9F4cGKLkvarI8no9EodSfuMVbTBUVTpCkE4xNQjSkC0ETHNRqTpFkDjOM8ChYIwABUgjHpcEyBKSADW3gMAp1R9B2XY+BMu4RIO6nDme8mVNUKROa0xx5p55SVE+J4GGi571Je3mVGY-mKVgKRYHIJzseFRnpAwR6aC+2ARaQH40t+f4AUByapuQ6YgblJnmaARHwKAiiwYhyFYAwizwQAqgACg05E1SudVstR7hMYYLEGIw7FeFxoB8QJYAPNQGUOFo4kYJJmp5GogSwIpo5YIYm3cn2pISYoB25Fo5iwIQznuIVr6HVwl3bTde3yIwmhEJA8iPBRhgWQeIrUkmRVjIYZXlUN5JEeAOGPr+QEFkcT5iBukj6GBsAWRhWE4WNaZsk+BFTRKADsNE0jNc1seK4WKAVsN+PDLKfuSlWo6AnVIY+JPYcePgagaXDYJA+iaJWEOgAADDTTOPKxczGQt4pLTx-HHOx7jvhV-6AcBgvwcLURoZhYuQaAzBQ9TZh0dwW6jl4kgXOQ6Xywwjt+JotkyLkypYI27hAA) <!-- playground:postgres --> to hover the types and edit the SQL, with nothing to install.
59
31
 
60
- postgres.js parses only a few types by default; everything else is the text Postgres sent:
32
+ ## Documentation
61
33
 
62
- | Postgres | `PostgresJsTypeMap` | `PostgresJsBigIntTypeMap` |
63
- |---|---|---|
64
- | `int2`, `int4`, `oid`, `float4`, `float8` | `number` | `number` |
65
- | `int8` (also `count(*)`) | `string` | `bigint` |
66
- | `bool` | `boolean` | `boolean` |
67
- | `date`, `timestamp`, `timestamptz` | `Date` | `Date` |
68
- | `json`, `jsonb` | `unknown` | `unknown` |
69
- | `bytea` | `Buffer` | `Buffer` |
70
- | `numeric`, `interval`, `point`, text-like and other types | `string` | `string` |
34
+ - [postgres.js adapter](https://typesql.karsli.net/adapters/postgres): running queries, transactions and migrations
35
+ - [Type mapping](https://typesql.karsli.net/reference/type-mapping#postgres-js): the TypeScript type of every Postgres type
71
36
 
72
- Arrays map element-wise. Details in the
73
- [postgres.js adapter page](https://github.com/ismailkarsli/typesql/blob/main/packages/docs/adapters/postgres.md).
37
+ ## License
74
38
 
75
- Parameters accept the row type and what postgres.js serializes for the type
76
- (`PostgresJsParamTypeMap`): `number | bigint | string` for `int8`, `numeric` and `money`,
77
- `Date | string | number` (epoch ms) for dates and timestamps, `string` for `interval`,
78
- `Uint8Array` for `bytea`.
39
+ [MIT](LICENSE)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@typesql/postgres",
3
- "version": "0.2.0",
3
+ "version": "0.2.1",
4
4
  "description": "postgres.js adapter for TypeSQL.",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -28,7 +28,7 @@
28
28
  "access": "public"
29
29
  },
30
30
  "dependencies": {
31
- "@typesql/core": "0.5.0"
31
+ "@typesql/core": "0.6.0"
32
32
  },
33
33
  "peerDependencies": {
34
34
  "postgres": ">=3"