From 831d1a59e7ac05adfdff4560b7134efa58b01cf8 Mon Sep 17 00:00:00 2001 From: George MacKerron Date: Thu, 30 Nov 2023 12:00:39 +0000 Subject: [PATCH] Updated docs --- docs/index.html | 424 +++++++++++++++++++---------------------- docs/zapatos-bundle.js | 2 +- 2 files changed, 202 insertions(+), 224 deletions(-) diff --git a/docs/index.html b/docs/index.html index f4da1d9..a0f7f59 100644 --- a/docs/index.html +++ b/docs/index.html @@ -176,12 +176,12 @@

Arbitrary SQL

INSERT INTO "authors" ("isLiving", "name")
   VALUES ($1, $2)
 RETURNING *
-
[false, "Gabriel Garcia Marquez"]
+
[false, "Gabriel Garcia Marquez"]
[
   {
     "id": 1,
     "name": "Gabriel Garcia Marquez",
-    "isLiving": false
+    "isLiving": false
   }
 ]
@@ -202,17 +202,17 @@

Everyday CRUD

INSERT INTO "authors" ("isLiving", "name")
   VALUES ($1, $2), ($3, $4)
 RETURNING to_jsonb ("authors".*) AS result
-
[false, "Douglas Adams", false, "Jane Austen"]
+
[false, "Douglas Adams", false, "Jane Austen"]
[
   {
     "id": 2,
     "name": "Douglas Adams",
-    "isLiving": false
+    "isLiving": false
   },
   {
     "id": 3,
     "name": "Jane Austen",
-    "isLiving": false
+    "isLiving": false
   }
 ]
@@ -277,10 +277,10 @@

JOINs as nested JSON

"author": { "id": 1000, "name": "Philip Pullman", - "isLiving": true + "isLiving": true }, "authorId": 1000, - "createdAt": "2023-11-27T14:24:50.106213+00:00" + "createdAt": "2023-11-30T11:55:24.995182+00:00" }, { "id": 1001, @@ -298,10 +298,10 @@

JOINs as nested JSON

"author": { "id": 1000, "name": "Philip Pullman", - "isLiving": true + "isLiving": true }, "authorId": 1000, - "createdAt": "2023-11-27T14:24:50.107595+00:00" + "createdAt": "2023-11-30T11:55:24.996168+00:00" }, { "id": 1002, @@ -319,10 +319,10 @@

JOINs as nested JSON

"author": { "id": 1000, "name": "Philip Pullman", - "isLiving": true + "isLiving": true }, "authorId": 1000, - "createdAt": "2023-11-27T14:24:50.108396+00:00" + "createdAt": "2023-11-30T11:55:24.996692+00:00" }, { "id": 1003, @@ -336,10 +336,10 @@

JOINs as nested JSON

"author": { "id": 1001, "name": "Mark Haddon", - "isLiving": true + "isLiving": true }, "authorId": 1001, - "createdAt": "2023-11-27T14:24:50.113982+00:00" + "createdAt": "2023-11-30T11:55:25.000887+00:00" }, { "id": 1004, @@ -353,10 +353,10 @@

JOINs as nested JSON

"author": { "id": 1002, "name": "Louis Sachar", - "isLiving": true + "isLiving": true }, "authorId": 1002, - "createdAt": "2023-11-27T14:24:50.115319+00:00" + "createdAt": "2023-11-30T11:55:25.002593+00:00" } ] @@ -483,7 +483,7 @@

Configure it

"customTypesTransform" is a string that determines how user-defined Postgres type names are mapped to TypeScript type names. Your options are "my_type", "PgMyType" or "PgMy_type", each representing how a Postgres type named my_type will be transformed. The default (for reasons of backward-compatibility rather than superiority) is "PgMy_type". If you generate your schema programmatically, you can alternatively define your own transformation function.

  • -

    "schemas" is an object that lets you define the schemas, and the tables and views within schemas, for which types will be generated. Each key is a schema name, and each value is an object with keys "include" and "exclude". Those keys can take the value "*" (for all tables in the schema) or an array of table names. The "exclude" list takes precedence over the "include" list. Thanks to generous sponsorship by Seam, schemas are properly supported (via namespacing of types) as of version 6.

    +

    "schemas" is an object that lets you define the schemas, and the tables and views within schemas, for which types will be generated. Each key is a schema name, and each value is an object with keys "include" and "exclude". Those keys can take the value "*" (for all tables in the schema) or an array of table names. The "exclude" list takes precedence over the "include" list. Thanks to generous sponsorship by Seam, schemas are properly supported (via namespacing of types) as of version 6.

    • If not specified, the default value for "schemas" includes all tables in the public schema, i.e.:

    @@ -578,7 +578,7 @@

    Environment variables

    "connectionString": "{{DATABASE_URL}}" }

    ESLint / tslint

    -

    A general configuration suggestion: set up ESLint with the rules @typescript-eslint/await-thenable and @typescript-eslint/no-floating-promises (or the now-deprecated tslint with no-floating-promises and await-promise) to avoid various Promise-related pitfalls.

    +

    A general configuration suggestion: set up ESLint with the rules @typescript-eslint/await-thenable and @typescript-eslint/no-floating-promises (or the now-deprecated tslint with no-floating-promises and await-promise) to avoid various Promise-related pitfalls.

    Generate your schema

    Zapatos provides a command line tool. With everything configured, run it like so:

    npx zapatos
    @@ -639,32 +639,32 @@

    sql tagged template strings { "id": 1000, "name": "Philip Pullman", - "isLiving": true + "isLiving": true }, { "id": 1001, "name": "Mark Haddon", - "isLiving": true + "isLiving": true }, { "id": 1002, "name": "Louis Sachar", - "isLiving": true + "isLiving": true }, { "id": 1, "name": "Gabriel Garcia Marquez", - "isLiving": false + "isLiving": false }, { "id": 2, "name": "Douglas Adams", - "isLiving": false + "isLiving": false }, { "id": 3, "name": "Jane Austen", - "isLiving": false + "isLiving": false } ] @@ -680,10 +680,10 @@

    sql tagged template stringsSELECT random() 
    [
   {
-    "random": 0.8254187817507521
+    "random": 0.5511811017169812
   }
 ]
    -
    0.8254187817507521
    +
    0.5511811017169812

    Interpolations is never because nothing needs to be interpolated in this query, and the RunResult type says that the query will return one row comprising one numeric column, named random. The random TypeScript variable we initialize will of course be typed as a number.

    If you’re happy to have your types tied down a little less tightly, it also works to wholly omit the type variables in this particular query, falling back on their defaults:

    @@ -736,12 +736,12 @@

    cols() and vals()

    INSERT INTO "authors" ("isLiving", "name")
   VALUES ($1, $2)
 RETURNING *
    -
    [false, "Joseph Conrad"]
    +
    [false, "Joseph Conrad"]
    [
   {
     "id": 4,
     "name": "Joseph Conrad",
-    "isLiving": false
+    "isLiving": false
   }
 ]
    @@ -796,12 +796,12 @@

    cols() and vals()

    { "id": 1, "name": "Gabriel Garcia Marquez", - "isLiving": false + "isLiving": false }, { "id": 2, "name": "Douglas Adams", - "isLiving": false + "isLiving": false } ] @@ -823,7 +823,7 @@

    Whereable

    "id": 1000, "authorId": 1000, "title": "Northern Lights", - "createdAt": "2023-11-27T14:24:50.106Z" + "createdAt": "2023-11-30T11:55:24.995Z" } ] @@ -849,7 +849,7 @@

    Whereable

    "id": 1000, "authorId": 1000, "title": "Northern Lights", - "createdAt": "2023-11-27T14:24:50.106Z" + "createdAt": "2023-11-30T11:55:24.995Z" } ] @@ -875,7 +875,7 @@

    Whereable

    "id": 1000, "authorId": 1000, "title": "Northern Lights", - "createdAt": "2023-11-27T14:24:50.106Z" + "createdAt": "2023-11-30T11:55:24.995Z" } ] @@ -990,7 +990,7 @@

    runResultTransform: (qr: const dbNow = await dbNowQuery().run(pool); // dbNow is a Date: the result you can toggle below has come via JSON.stringify
    SELECT now()
    -
    "2023-11-27T14:25:01.886Z"
    +
    "2023-11-30T11:56:08.041Z"

    Note that the RunResult type variable on the sql template function (in this case, Date) must reflect the type of the transformed result, not what comes straight back from pg (which in this case is roughly { rows: [{ now: Date }] }).

    If a SQLFragment does not have run called on it directly — for example, if it is instead interpolated into another SQLFragment, or given as the value of the lateral option to the select shortcut — then the runResultTransform function is never applied.

    @@ -1016,55 +1016,55 @@

    Manual joins using Postgres "id": 1000, "authorId": 1000, "title": "Northern Lights", - "createdAt": "2023-11-27T14:24:50.106Z", + "createdAt": "2023-11-30T11:55:24.995Z", "author": { "id": 1000, "name": "Philip Pullman", - "isLiving": true + "isLiving": true } }, { "id": 1001, "authorId": 1000, "title": "The Subtle Knife", - "createdAt": "2023-11-27T14:24:50.108Z", + "createdAt": "2023-11-30T11:55:24.996Z", "author": { "id": 1000, "name": "Philip Pullman", - "isLiving": true + "isLiving": true } }, { "id": 1002, "authorId": 1000, "title": "The Amber Spyglass", - "createdAt": "2023-11-27T14:24:50.108Z", + "createdAt": "2023-11-30T11:55:24.996Z", "author": { "id": 1000, "name": "Philip Pullman", - "isLiving": true + "isLiving": true } }, { "id": 1003, "authorId": 1001, "title": "The Curious Incident of the Dog in the Night-Time", - "createdAt": "2023-11-27T14:24:50.114Z", + "createdAt": "2023-11-30T11:55:25.000Z", "author": { "id": 1001, "name": "Mark Haddon", - "isLiving": true + "isLiving": true } }, { "id": 1004, "authorId": 1002, "title": "Holes", - "createdAt": "2023-11-27T14:24:50.115Z", + "createdAt": "2023-11-30T11:55:25.002Z", "author": { "id": 1002, "name": "Louis Sachar", - "isLiving": true + "isLiving": true } } ] @@ -1090,51 +1090,51 @@

    Manual joins using Postgres { "id": 1000, "name": "Philip Pullman", - "isLiving": true, + "isLiving": true, "books": [ { "id": 1000, "title": "Northern Lights", "authorId": 1000, - "createdAt": "2023-11-27T14:24:50.106213+00:00" + "createdAt": "2023-11-30T11:55:24.995182+00:00" }, { "id": 1001, "title": "The Subtle Knife", "authorId": 1000, - "createdAt": "2023-11-27T14:24:50.107595+00:00" + "createdAt": "2023-11-30T11:55:24.996168+00:00" }, { "id": 1002, "title": "The Amber Spyglass", "authorId": 1000, - "createdAt": "2023-11-27T14:24:50.108396+00:00" + "createdAt": "2023-11-30T11:55:24.996692+00:00" } ] }, { "id": 1001, "name": "Mark Haddon", - "isLiving": true, + "isLiving": true, "books": [ { "id": 1003, "title": "The Curious Incident of the Dog in the Night-Time", "authorId": 1001, - "createdAt": "2023-11-27T14:24:50.113982+00:00" + "createdAt": "2023-11-30T11:55:25.000887+00:00" } ] }, { "id": 1002, "name": "Louis Sachar", - "isLiving": true, + "isLiving": true, "books": [ { "id": 1004, "title": "Holes", "authorId": 1002, - "createdAt": "2023-11-27T14:24:50.115319+00:00" + "createdAt": "2023-11-30T11:55:25.002593+00:00" } ] } @@ -1166,76 +1166,76 @@

    Manual joins using Postgres { "id": 1000, "name": "Philip Pullman", - "isLiving": true, + "isLiving": true, "books": [ { "id": 1000, "authorId": 1000, "title": "Northern Lights", - "createdAt": "2023-11-27T14:24:50.106213+00:00" + "createdAt": "2023-11-30T11:55:24.995182+00:00" }, { "id": 1001, "authorId": 1000, "title": "The Subtle Knife", - "createdAt": "2023-11-27T14:24:50.107595+00:00" + "createdAt": "2023-11-30T11:55:24.996168+00:00" }, { "id": 1002, "authorId": 1000, "title": "The Amber Spyglass", - "createdAt": "2023-11-27T14:24:50.108396+00:00" + "createdAt": "2023-11-30T11:55:24.996692+00:00" } ] }, { "id": 1001, "name": "Mark Haddon", - "isLiving": true, + "isLiving": true, "books": [ { "id": 1003, "authorId": 1001, "title": "The Curious Incident of the Dog in the Night-Time", - "createdAt": "2023-11-27T14:24:50.113982+00:00" + "createdAt": "2023-11-30T11:55:25.000887+00:00" } ] }, { "id": 1002, "name": "Louis Sachar", - "isLiving": true, + "isLiving": true, "books": [ { "id": 1004, "authorId": 1002, "title": "Holes", - "createdAt": "2023-11-27T14:24:50.115319+00:00" + "createdAt": "2023-11-30T11:55:25.002593+00:00" } ] }, { "id": 1, "name": "Gabriel Garcia Marquez", - "isLiving": false, + "isLiving": false, "books": [] }, { "id": 2, "name": "Douglas Adams", - "isLiving": false, + "isLiving": false, "books": [] }, { "id": 3, "name": "Jane Austen", - "isLiving": false, + "isLiving": false, "books": [] }, { "id": 4, "name": "Joseph Conrad", - "isLiving": false, + "isLiving": false, "books": [] } ] @@ -1299,11 +1299,11 @@

    insert

    INSERT INTO "authors" ("isLiving", "name")
   VALUES ($1, $2)
 RETURNING to_jsonb ("authors".*) AS result
    -
    [false, "Steven Hawking"]
    +
    [false, "Steven Hawking"]
    {
   "id": 5,
   "name": "Steven Hawking",
-  "isLiving": false
+  "isLiving": false
 }
    INSERT INTO "books" ("authorId", "createdAt", "title")
   VALUES ($1, now(), $2), ($3, now(), $4)
@@ -1314,13 +1314,13 @@ 
    insert
    
     "id": 1,
     "title": "A Brief History of Time",
     "authorId": 5,
-    "createdAt": "2023-11-27T14:25:02.990873+00:00"
+    "createdAt": "2023-11-30T11:56:09.395795+00:00"
   },
   {
     "id": 2,
     "title": "My Brief History",
     "authorId": 5,
-    "createdAt": "2023-11-27T14:25:02.990873+00:00"
+    "createdAt": "2023-11-30T11:56:09.395795+00:00"
   }
 ]
    INSERT INTO "tags" ("bookId", "tag")
@@ -1388,7 +1388,7 @@ 
    update
    
   {
     "id": 5,
     "name": "Stephen Hawking",
-    "isLiving": false
+    "isLiving": false
   }
 ]
    @@ -1415,7 +1415,7 @@

    update

    [
   {
     "email": "me@privacy.net",
-    "lastFailedLogin": "2023-11-27T14:25:04.429787+00:00",
+    "lastFailedLogin": "2023-11-30T11:56:10.736952+00:00",
     "consecutiveFailedLogins": 1
   }
 ]
    @@ -1563,7 +1563,7 @@
    INSERT ... ON CONFLICT ... DO NOT 
    {
   "code": "XYE953ZVU767",
   "$action": "INSERT",
-  "redeemedAt": "2023-11-27T14:25:05.169319+00:00"
+  "redeemedAt": "2023-11-30T11:56:11.609362+00:00"
 }
    INSERT INTO "usedVoucherCodes" ("code")
   VALUES ($1)
@@ -1697,43 +1697,43 @@ 
    select, select
     "id": 1000,
     "title": "Northern Lights",
     "authorId": 1000,
-    "createdAt": "2023-11-27T14:24:50.106213+00:00"
+    "createdAt": "2023-11-30T11:55:24.995182+00:00"
   },
   {
     "id": 1001,
     "title": "The Subtle Knife",
     "authorId": 1000,
-    "createdAt": "2023-11-27T14:24:50.107595+00:00"
+    "createdAt": "2023-11-30T11:55:24.996168+00:00"
   },
   {
     "id": 1002,
     "title": "The Amber Spyglass",
     "authorId": 1000,
-    "createdAt": "2023-11-27T14:24:50.108396+00:00"
+    "createdAt": "2023-11-30T11:55:24.996692+00:00"
   },
   {
     "id": 1003,
     "title": "The Curious Incident of the Dog in the Night-Time",
     "authorId": 1001,
-    "createdAt": "2023-11-27T14:24:50.113982+00:00"
+    "createdAt": "2023-11-30T11:55:25.000887+00:00"
   },
   {
     "id": 1,
     "title": "A Brief History of Time",
     "authorId": 5,
-    "createdAt": "2023-11-27T14:25:02.990873+00:00"
+    "createdAt": "2023-11-30T11:56:09.395795+00:00"
   },
   {
     "id": 2,
     "title": "My Brief History",
     "authorId": 5,
-    "createdAt": "2023-11-27T14:25:02.990873+00:00"
+    "createdAt": "2023-11-30T11:56:09.395795+00:00"
   },
   {
     "id": 3,
     "title": "The Universe in a Nutshell",
     "authorId": 5,
-    "createdAt": "2023-11-27T14:25:02.996624+00:00"
+    "createdAt": "2023-11-30T11:56:09.400222+00:00"
   }
 ]
    @@ -1751,19 +1751,19 @@

    select, select "id": 1000, "title": "Northern Lights", "authorId": 1000, - "createdAt": "2023-11-27T14:24:50.106213+00:00" + "createdAt": "2023-11-30T11:55:24.995182+00:00" }, { "id": 1001, "title": "The Subtle Knife", "authorId": 1000, - "createdAt": "2023-11-27T14:24:50.107595+00:00" + "createdAt": "2023-11-30T11:55:24.996168+00:00" }, { "id": 1002, "title": "The Amber Spyglass", "authorId": 1000, - "createdAt": "2023-11-27T14:24:50.108396+00:00" + "createdAt": "2023-11-30T11:55:24.996692+00:00" } ] @@ -1778,7 +1778,7 @@

    select, select 
    {
   "id": 1000,
   "name": "Philip Pullman",
-  "isLiving": true
+  "isLiving": true
 }
    import * as db from 'zapatos/db';
@@ -1817,7 +1817,7 @@ 
    select, select
     "id": 1003,
     "title": "The Curious Incident of the Dog in the Night-Time",
     "authorId": 1001,
-    "createdAt": "2023-11-27T14:24:50.113982+00:00"
+    "createdAt": "2023-11-30T11:55:25.000887+00:00"
   }
 ]
    @@ -1840,7 +1840,7 @@

    select, select "id": 1003, "title": "The Curious Incident of the Dog in the Night-Time", "authorId": 1001, - "createdAt": "2023-11-27T14:24:50.113982+00:00" + "createdAt": "2023-11-30T11:55:25.000887+00:00" } ] @@ -1862,7 +1862,7 @@

    select, select "id": 1, "title": "A Brief History of Time", "authorId": 5, - "createdAt": "2023-11-27T14:25:02.990873+00:00" + "createdAt": "2023-11-30T11:56:09.395795+00:00" } ] @@ -1930,7 +1930,7 @@

    order, limit and "id": 1, "title": "A Brief History of Time", "authorId": 5, - "createdAt": "2023-11-27T14:25:02.990873+00:00" + "createdAt": "2023-11-30T11:56:09.395795+00:00" } ] @@ -1950,7 +1950,7 @@
    order, limit and "id": 1, "title": "A Brief History of Time", "authorId": 5, - "createdAt": "2023-11-27T14:25:02.990873+00:00" + "createdAt": "2023-11-30T11:56:09.395795+00:00" }

    The { limit: 1 } option is now applied automatically. And the return type following await needs no destructuring and is now, correctly, JSONSelectable | undefined.

    @@ -2000,10 +2000,10 @@
    lateral property maps
    "author": { "id": 1000, "name": "Philip Pullman", - "isLiving": true + "isLiving": true }, "authorId": 1000, - "createdAt": "2023-11-27T14:24:50.106213+00:00" + "createdAt": "2023-11-30T11:55:24.995182+00:00" }, { "id": 1001, @@ -2021,10 +2021,10 @@
    lateral property maps
    "author": { "id": 1000, "name": "Philip Pullman", - "isLiving": true + "isLiving": true }, "authorId": 1000, - "createdAt": "2023-11-27T14:24:50.107595+00:00" + "createdAt": "2023-11-30T11:55:24.996168+00:00" }, { "id": 1002, @@ -2042,10 +2042,10 @@
    lateral property maps
    "author": { "id": 1000, "name": "Philip Pullman", - "isLiving": true + "isLiving": true }, "authorId": 1000, - "createdAt": "2023-11-27T14:24:50.108396+00:00" + "createdAt": "2023-11-30T11:55:24.996692+00:00" }, { "id": 1003, @@ -2059,10 +2059,10 @@
    lateral property maps
    "author": { "id": 1001, "name": "Mark Haddon", - "isLiving": true + "isLiving": true }, "authorId": 1001, - "createdAt": "2023-11-27T14:24:50.113982+00:00" + "createdAt": "2023-11-30T11:55:25.000887+00:00" }, { "id": 1, @@ -2076,10 +2076,10 @@
    lateral property maps
    "author": { "id": 5, "name": "Stephen Hawking", - "isLiving": false + "isLiving": false }, "authorId": 5, - "createdAt": "2023-11-27T14:25:02.990873+00:00" + "createdAt": "2023-11-30T11:56:09.395795+00:00" }, { "id": 2, @@ -2097,10 +2097,10 @@
    lateral property maps
    "author": { "id": 5, "name": "Stephen Hawking", - "isLiving": false + "isLiving": false }, "authorId": 5, - "createdAt": "2023-11-27T14:25:02.990873+00:00" + "createdAt": "2023-11-30T11:56:09.395795+00:00" }, { "id": 3, @@ -2109,10 +2109,10 @@
    lateral property maps
    "author": { "id": 5, "name": "Stephen Hawking", - "isLiving": false + "isLiving": false }, "authorId": 5, - "createdAt": "2023-11-27T14:25:02.996624+00:00" + "createdAt": "2023-11-30T11:56:09.400222+00:00" } ]     @@ -2163,7 +2163,7 @@
    lateral property maps
    ], "title": "Northern Lights", "authorId": 1000, - "createdAt": "2023-11-27T14:24:50.106213+00:00" + "createdAt": "2023-11-30T11:55:24.995182+00:00" }, { "id": 1001, @@ -2177,7 +2177,7 @@
    lateral property maps
    ], "title": "The Subtle Knife", "authorId": 1000, - "createdAt": "2023-11-27T14:24:50.107595+00:00" + "createdAt": "2023-11-30T11:55:24.996168+00:00" }, { "id": 1002, @@ -2191,10 +2191,10 @@
    lateral property maps
    ], "title": "The Amber Spyglass", "authorId": 1000, - "createdAt": "2023-11-27T14:24:50.108396+00:00" + "createdAt": "2023-11-30T11:55:24.996692+00:00" } ], - "isLiving": true + "isLiving": true }, { "id": 1001, @@ -2209,40 +2209,40 @@
    lateral property maps
    ], "title": "The Curious Incident of the Dog in the Night-Time", "authorId": 1001, - "createdAt": "2023-11-27T14:24:50.113982+00:00" + "createdAt": "2023-11-30T11:55:25.000887+00:00" } ], - "isLiving": true + "isLiving": true }, { "id": 1002, "name": "Louis Sachar", "books": [], - "isLiving": true + "isLiving": true }, { "id": 1, "name": "Gabriel Garcia Marquez", "books": [], - "isLiving": false + "isLiving": false }, { "id": 2, "name": "Douglas Adams", "books": [], - "isLiving": false + "isLiving": false }, { "id": 3, "name": "Jane Austen", "books": [], - "isLiving": false + "isLiving": false }, { "id": 4, "name": "Joseph Conrad", "books": [], - "isLiving": false + "isLiving": false }, { "id": 5, @@ -2257,7 +2257,7 @@
    lateral property maps
    ], "title": "A Brief History of Time", "authorId": 5, - "createdAt": "2023-11-27T14:25:02.990873+00:00" + "createdAt": "2023-11-30T11:56:09.395795+00:00" }, { "id": 2, @@ -2271,17 +2271,17 @@
    lateral property maps
    ], "title": "My Brief History", "authorId": 5, - "createdAt": "2023-11-27T14:25:02.990873+00:00" + "createdAt": "2023-11-30T11:56:09.395795+00:00" }, { "id": 3, "tags": [], "title": "The Universe in a Nutshell", "authorId": 5, - "createdAt": "2023-11-27T14:25:02.996624+00:00" + "createdAt": "2023-11-30T11:56:09.400222+00:00" } ], - "isLiving": false + "isLiving": false } ]     @@ -2311,7 +2311,7 @@

    lateral property maps
    {
   "id": 1,
   "name": "Anna",
-  "managerId": null
+  "managerId": null
 }
    INSERT INTO "employees" ("managerId", "name")
   VALUES ($1, $2), ($3, $4)
@@ -2367,7 +2367,7 @@ 
    lateral property maps
    
 
    [
   {
     "name": "Anna",
-    "lineManager": null,
+    "lineManager": null,
     "directReports": 2
   },
   {
@@ -2752,46 +2752,46 @@ 
    distinct
    
   FROM "books") AS "sq_books"
    
 
    [
   {
-    "id": 1003,
-    "title": "The Curious Incident of the Dog in the Night-Time",
-    "authorId": 1001,
-    "createdAt": "2023-11-27T14:24:50.113982+00:00"
-  },
-  {
-    "id": 1002,
-    "title": "The Amber Spyglass",
-    "authorId": 1000,
-    "createdAt": "2023-11-27T14:24:50.108396+00:00"
-  },
-  {
-    "id": 3,
-    "title": "The Universe in a Nutshell",
+    "id": 1,
+    "title": "A Brief History of Time",
     "authorId": 5,
-    "createdAt": "2023-11-27T14:25:02.996624+00:00"
+    "createdAt": "2023-11-30T11:56:09.395795+00:00"
   },
   {
     "id": 1001,
     "title": "The Subtle Knife",
     "authorId": 1000,
-    "createdAt": "2023-11-27T14:24:50.107595+00:00"
+    "createdAt": "2023-11-30T11:55:24.996168+00:00"
   },
   {
-    "id": 1,
-    "title": "A Brief History of Time",
-    "authorId": 5,
-    "createdAt": "2023-11-27T14:25:02.990873+00:00"
+    "id": 1003,
+    "title": "The Curious Incident of the Dog in the Night-Time",
+    "authorId": 1001,
+    "createdAt": "2023-11-30T11:55:25.000887+00:00"
   },
   {
     "id": 2,
     "title": "My Brief History",
     "authorId": 5,
-    "createdAt": "2023-11-27T14:25:02.990873+00:00"
+    "createdAt": "2023-11-30T11:56:09.395795+00:00"
+  },
+  {
+    "id": 1002,
+    "title": "The Amber Spyglass",
+    "authorId": 1000,
+    "createdAt": "2023-11-30T11:55:24.996692+00:00"
+  },
+  {
+    "id": 3,
+    "title": "The Universe in a Nutshell",
+    "authorId": 5,
+    "createdAt": "2023-11-30T11:56:09.400222+00:00"
   },
   {
     "id": 1000,
     "title": "Northern Lights",
     "authorId": 1000,
-    "createdAt": "2023-11-27T14:24:50.106213+00:00"
+    "createdAt": "2023-11-30T11:55:24.995182+00:00"
   }
 ]
    
 
    SELECT coalesce(jsonb_agg(result), '[]') AS result
@@ -2803,43 +2803,43 @@ 
    distinct
    
     "id": 1,
     "title": "A Brief History of Time",
     "authorId": 5,
-    "createdAt": "2023-11-27T14:25:02.990873+00:00"
+    "createdAt": "2023-11-30T11:56:09.395795+00:00"
   },
   {
     "id": 2,
     "title": "My Brief History",
     "authorId": 5,
-    "createdAt": "2023-11-27T14:25:02.990873+00:00"
+    "createdAt": "2023-11-30T11:56:09.395795+00:00"
   },
   {
     "id": 1000,
     "title": "Northern Lights",
     "authorId": 1000,
-    "createdAt": "2023-11-27T14:24:50.106213+00:00"
+    "createdAt": "2023-11-30T11:55:24.995182+00:00"
   },
   {
     "id": 1002,
     "title": "The Amber Spyglass",
     "authorId": 1000,
-    "createdAt": "2023-11-27T14:24:50.108396+00:00"
+    "createdAt": "2023-11-30T11:55:24.996692+00:00"
   },
   {
     "id": 1003,
     "title": "The Curious Incident of the Dog in the Night-Time",
     "authorId": 1001,
-    "createdAt": "2023-11-27T14:24:50.113982+00:00"
+    "createdAt": "2023-11-30T11:55:25.000887+00:00"
   },
   {
     "id": 1001,
     "title": "The Subtle Knife",
     "authorId": 1000,
-    "createdAt": "2023-11-27T14:24:50.107595+00:00"
+    "createdAt": "2023-11-30T11:55:24.996168+00:00"
   },
   {
     "id": 3,
     "title": "The Universe in a Nutshell",
     "authorId": 5,
-    "createdAt": "2023-11-27T14:25:02.996624+00:00"
+    "createdAt": "2023-11-30T11:56:09.400222+00:00"
   }
 ]
    
 
    SELECT coalesce(jsonb_agg(result), '[]') AS result
@@ -2851,43 +2851,43 @@ 
    distinct
    
     "id": 1,
     "title": "A Brief History of Time",
     "authorId": 5,
-    "createdAt": "2023-11-27T14:25:02.990873+00:00"
+    "createdAt": "2023-11-30T11:56:09.395795+00:00"
   },
   {
     "id": 2,
     "title": "My Brief History",
     "authorId": 5,
-    "createdAt": "2023-11-27T14:25:02.990873+00:00"
+    "createdAt": "2023-11-30T11:56:09.395795+00:00"
   },
   {
     "id": 1000,
     "title": "Northern Lights",
     "authorId": 1000,
-    "createdAt": "2023-11-27T14:24:50.106213+00:00"
+    "createdAt": "2023-11-30T11:55:24.995182+00:00"
   },
   {
     "id": 1002,
     "title": "The Amber Spyglass",
     "authorId": 1000,
-    "createdAt": "2023-11-27T14:24:50.108396+00:00"
+    "createdAt": "2023-11-30T11:55:24.996692+00:00"
   },
   {
     "id": 1003,
     "title": "The Curious Incident of the Dog in the Night-Time",
     "authorId": 1001,
-    "createdAt": "2023-11-27T14:24:50.113982+00:00"
+    "createdAt": "2023-11-30T11:55:25.000887+00:00"
   },
   {
     "id": 1001,
     "title": "The Subtle Knife",
     "authorId": 1000,
-    "createdAt": "2023-11-27T14:24:50.107595+00:00"
+    "createdAt": "2023-11-30T11:55:24.996168+00:00"
   },
   {
     "id": 3,
     "title": "The Universe in a Nutshell",
     "authorId": 5,
-    "createdAt": "2023-11-27T14:25:02.996624+00:00"
+    "createdAt": "2023-11-30T11:56:09.400222+00:00"
   }
 ]
    
 
    SELECT coalesce(jsonb_agg(result), '[]') AS result
@@ -2899,43 +2899,43 @@ 
    distinct
    
     "id": 1,
     "title": "A Brief History of Time",
     "authorId": 5,
-    "createdAt": "2023-11-27T14:25:02.990873+00:00"
+    "createdAt": "2023-11-30T11:56:09.395795+00:00"
   },
   {
     "id": 2,
     "title": "My Brief History",
     "authorId": 5,
-    "createdAt": "2023-11-27T14:25:02.990873+00:00"
+    "createdAt": "2023-11-30T11:56:09.395795+00:00"
   },
   {
     "id": 1000,
     "title": "Northern Lights",
     "authorId": 1000,
-    "createdAt": "2023-11-27T14:24:50.106213+00:00"
+    "createdAt": "2023-11-30T11:55:24.995182+00:00"
   },
   {
     "id": 1002,
     "title": "The Amber Spyglass",
     "authorId": 1000,
-    "createdAt": "2023-11-27T14:24:50.108396+00:00"
+    "createdAt": "2023-11-30T11:55:24.996692+00:00"
   },
   {
     "id": 1003,
     "title": "The Curious Incident of the Dog in the Night-Time",
     "authorId": 1001,
-    "createdAt": "2023-11-27T14:24:50.113982+00:00"
+    "createdAt": "2023-11-30T11:55:25.000887+00:00"
   },
   {
     "id": 1001,
     "title": "The Subtle Knife",
     "authorId": 1000,
-    "createdAt": "2023-11-27T14:24:50.107595+00:00"
+    "createdAt": "2023-11-30T11:55:24.996168+00:00"
   },
   {
     "id": 3,
     "title": "The Universe in a Nutshell",
     "authorId": 5,
-    "createdAt": "2023-11-27T14:25:02.996624+00:00"
+    "createdAt": "2023-11-30T11:56:09.400222+00:00"
   }
 ]
    
 
@@ -2966,42 +2966,42 @@ 
    lock
    
   {
     "id": 1000,
     "name": "Philip Pullman",
-    "isLiving": true
+    "isLiving": true
   },
   {
     "id": 1001,
     "name": "Mark Haddon",
-    "isLiving": true
+    "isLiving": true
   },
   {
     "id": 1002,
     "name": "Louis Sachar",
-    "isLiving": true
+    "isLiving": true
   },
   {
     "id": 1,
     "name": "Gabriel Garcia Marquez",
-    "isLiving": false
+    "isLiving": false
   },
   {
     "id": 2,
     "name": "Douglas Adams",
-    "isLiving": false
+    "isLiving": false
   },
   {
     "id": 3,
     "name": "Jane Austen",
-    "isLiving": false
+    "isLiving": false
   },
   {
     "id": 4,
     "name": "Joseph Conrad",
-    "isLiving": false
+    "isLiving": false
   },
   {
     "id": 5,
     "name": "Stephen Hawking",
-    "isLiving": false
+    "isLiving": false
   }
 ]
    SELECT coalesce(jsonb_agg(result), '[]') AS result
@@ -3014,42 +3014,42 @@ 
    lock
    
   {
     "id": 1000,
     "name": "Philip Pullman",
-    "isLiving": true
+    "isLiving": true
   },
   {
     "id": 1001,
     "name": "Mark Haddon",
-    "isLiving": true
+    "isLiving": true
   },
   {
     "id": 1002,
     "name": "Louis Sachar",
-    "isLiving": true
+    "isLiving": true
   },
   {
     "id": 1,
     "name": "Gabriel Garcia Marquez",
-    "isLiving": false
+    "isLiving": false
   },
   {
     "id": 2,
     "name": "Douglas Adams",
-    "isLiving": false
+    "isLiving": false
   },
   {
     "id": 3,
     "name": "Jane Austen",
-    "isLiving": false
+    "isLiving": false
   },
   {
     "id": 4,
     "name": "Joseph Conrad",
-    "isLiving": false
+    "isLiving": false
   },
   {
     "id": 5,
     "name": "Stephen Hawking",
-    "isLiving": false
+    "isLiving": false
   }
 ]
    @@ -3094,7 +3094,7 @@

    JSONSelectable

    s1: '2012-06-01T12:34:00.000Z', s2: '2012-06-01T00:00:00.000', s3: '2012-06-01', - s4: '2012-10-09T02:34:00.000Z' + s4: null }
      @@ -3156,35 +3156,7 @@

      JSONSelectable

      o: -0, isLuxonDateTime: true }, - dt3: DateTime { - ts: 626637180000, - _zone: SystemZone {}, - loc: Locale { - locale: 'en-GB', - numberingSystem: null, - outputCalendar: null, - intl: 'en-GB', - weekdaysCache: [Object], - monthsCache: [Object], - meridiemCache: null, - eraCache: {}, - specifiedLocale: null, - fastNumbersCached: null - }, - invalid: null, - weekData: null, - c: { - year: 1989, - month: 11, - day: 9, - hour: 17, - minute: 53, - second: 0, - millisecond: 0 - }, - o: -0, - isLuxonDateTime: true - }, + dt3: null, alsoTsTz: '1989-11-09T17:53:00.000+00:00' } @@ -3197,14 +3169,17 @@
      Custom JSON parsing for Set "customJSONParsingForLargeNumbers": true in the schema-generation config in zapatosconfig.json. This switches the TypeScript types for these columns in JSONSelectables from number to number | `${number}`. It also suppresses the warning.

    • -

      Be sure to call db.enableCustomJSONParsingForLargeNumbers(pg) in your code before running any queries. This switches node-postgres JSON parsing to use the json-custom-numbers package, and return as strings any values that aren’t representable as a JS number.

      +

      Be sure to call db.enableCustomJSONParsingForLargeNumbers(pg) in your code before running any queries. This switches node-postgres’s JSON parsing to use the json-custom-numbers package, and return as strings any values that aren’t representable as a JS number.

    -

    When using these string | number values in code, you will likely want to convert integers to BigInt and decimals to a third-party decimal format such as big.js at the earliest opportunity. For example:

    +

    When using these number | `${number}` values in code, you will likely want to convert integers to BigInt and decimals to a third-party decimal format such as big.js at the earliest opportunity.

    +

    Here’s an example:

    import * as db from 'zapatos/db';
 import pool from './pgPool.js';
 import pg from 'pg';
-import Big from 'big.js';
+import Big from 'big.js';  // third-party arbitrary-precision library
+
+// note: set `"customJSONParsingForLargeNumbers": true` in zapatosconfig.json
 
 db.enableCustomJSONParsingForLargeNumbers(pg);
 
@@ -3214,15 +3189,16 @@ 
    Custom JSON parsing for   { order: { by: "bigintValue", direction: "ASC" } }).run(pool);
 
 for (const { bigintValue: raw } of bigints) {  // raw is number | `${number}`
-  const number = Number(raw);  // don't do this: may get a different integer
+  const number = Number(raw);  // DON'T do this: may become a different integer
   const bigint = BigInt(raw);  // do this instead
 
   console.log('raw:', raw, '/ as Number:', number, '/ as BigInt:', bigint);
 
   // Note that numbers above `Number.MAX_SAFE_INTEGER` are still returned as
-  // numbers *if* that doesn't change them. For example, 9007199254740995 is
-  // returned as a string (because it would become 9007199254740996), but
-  // 9007199254740996 is safely returned as an ordinary number.
+  // numbers *if* that doesn't change them. For example, 9007199254740993 is
+  // returned as a string (because it would become 9007199254740992), but
+  // 9007199254740992 is safely returned as an ordinary number, even though
+  // it's `Number.MAX_SAFE_INTEGER + 1`.
 }
 
 // numerics
@@ -3231,11 +3207,13 @@ 
    Custom JSON parsing for   { order: { by: "numericValue", direction: "ASC" } }).run(pool);
 
 for (const { numericValue: raw } of numerics) {  // raw is number | `${number}`
-  const number = Number(raw);  // don't do this: may overflow or lose precision
+  const number = Number(raw);  // DON'T do this: may overflow or lose precision
   const bigdec = Big(raw);  // do this instead
 
-  console.log('raw', raw, '/ as Number', number, '/ as Big', bigdec);
-}
    + console.log('raw:', raw, '/ as Number:', number, '/ as Big:', bigdec); +} + +await pool.end();
    SELECT coalesce(jsonb_agg(result), '[]') AS result
 FROM (
   SELECT to_jsonb ("bigints".*) AS result
@@ -3274,10 +3252,10 @@ 
    Custom JSON parsing for     "numericValue": "180000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000"
   }
 ]
    -
    raw 1.2345678901234566 / as Number 1.2345678901234567 / as Big 1.2345678901234566
-raw 1.2345678901234567 / as Number 1.2345678901234567 / as Big 1.2345678901234567
-raw 1.7e+308 / as Number 1.7e+308 / as Big 1.7e+308
-raw 180000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 / as Number Infinity / as Big 1.8e+308
    +
    raw: 1.2345678901234566 / as Number: 1.2345678901234567 / as Big: 1.2345678901234566
+raw: 1.2345678901234567 / as Number: 1.2345678901234567 / as Big: 1.2345678901234567
+raw: 1.7e+308 / as Number: 1.7e+308 / as Big: 1.7e+308
+raw: 180000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 / as Number: Infinity / as Big: 1.8e+308
    Source code »

    transaction

    @@ -3442,7 +3420,7 @@

    transaction

    Transaction 1
    ROLLBACK
    Transaction 1
    -
    Transaction rollback (code 40001) on attempt 1 of 5, retrying in 86ms
    +
    Transaction rollback (code 40001) on attempt 1 of 5, retrying in 76ms
    Transaction 1
    Retrying transaction, attempt 2 of 5
    Transaction 1
    @@ -3933,7 +3911,7 @@

    6.3

    6.2

    Return type for certain embedded SQLFragments now matches the null actually returned (previously typed as undefined). Fix for and and or types. Corrected package.json key order. Exporting mapWithSeparator.

    6.0

    -

    Breaking change (if you use schemas): Thanks to generous sponsorship from Seam, Zapatos now supports schemas properly, prefixing the schema to table and enum names as necessary in the generated types. If you make use of Postgres schemas outside of the default public schema, you’ll need to add schema names in the appropriate places (TypeScript errors should show you where).

    +

    Breaking change (if you use schemas): Thanks to generous sponsorship from Seam, Zapatos now supports schemas properly, prefixing the schema to table and enum names as necessary in the generated types. If you make use of Postgres schemas outside of the default public schema, you’ll need to add schema names in the appropriate places (TypeScript errors should show you where).

    5.0

    Breaking change: The AllTables type (which somewhat arbitrarily included tables, foreign tables, and views, but not materialized views) is gone. In its place you’ll a variety of more and less specific utility types. Also, Updatable and Insertable interfaces for tables and views that aren’t writable are now { [key: string]: never } instead of {}.

    4.0

    @@ -4046,7 +4024,7 @@

    Fixes, feature and contributions

    Scratching my own itch. I’m unlikely to put a lot of free effort into new features I don’t currently need.

    Sponsorship or consultancy. If you’d like to discuss sponsoring work on the project, or possible consultancy, please get in touch.

    Sponsors

    -

    Many thanks to Seam for sponsoring proper multi-schema support.

    +

    Many thanks to Seam for sponsoring proper multi-schema support.

    What’s next

    The roadmap includes: