Add nested transforms (#460)

* Add first version of nested transforms

* Fix access before initialization

* Add trailing EOL

* Add higher-order function to reduce repetition

* Fix data structures

* Fix data structures

* Format config

* Add first tests for new transform options

* Pass column

* Update documentation

* Update types

* Document undefined transform option

Author: karlhorky

README.md

@@ -575,32 +575,19 @@ Do note that you can often achieve the same result using [`WITH` queries (Common
 
 ## Data Transformation
 
-Postgres.js comes with a number of built-in data transformation functions that can be used to transform the data returned from a query or when inserting data. They are available under `transform` option in the `postgres()` function connection options.
+Postgres.js allows for transformation of the data passed to or returned from a query by using the `transform` option.
 
-Like - `postgres('connectionURL', { transform: {...} })`
-
-### Parameters
-* `to`: The function to transform the outgoing query column name to, i.e `SELECT ${ sql('aName') }` to `SELECT a_name` when using `postgres.toCamel`.
-* `from`: The function to transform the incoming query result column name to, see example below.
+Built in transformation functions are:
 
-> Both parameters are optional, if not provided, the default transformation function will be used.
+* For camelCase - `postgres.camel`, `postgres.toCamel`, `postgres.fromCamel`
+* For PascalCase - `postgres.pascal`, `postgres.toPascal`, `postgres.fromPascal`
+* For Kebab-Case - `postgres.kebab`, `postgres.toKebab`, `postgres.fromKebab`
 
-Built in transformation functions are:
-* For camelCase - `postgres.toCamel` and `postgres.fromCamel`
-* For PascalCase - `postgres.toPascal` and `postgres.fromPascal`
-* For Kebab-Case - `postgres.toKebab` and `postgres.fromKebab`
+By default, using `postgres.camel`, `postgres.pascal` and `postgres.kebab` will perform a two-way transformation - both the data passed to the query and the data returned by the query will be transformed:
 
-These functions can be passed in as options when calling `postgres()`, for example:
 ```js
 // Transform the column names to and from camel case
-const sql = postgres('connectionURL', {
-  transform: {
-    column: {
-      to: postgres.fromCamel,
-      from: postgres.toCamel,
-    },
-  },
-})
+const sql = postgres({ transform: postgres.camel })
 
 await sql`CREATE TABLE IF NOT EXISTS camel_case (a_test INTEGER, b_test TEXT)`
 await sql`INSERT INTO camel_case ${ sql([{ aTest: 1, bTest: 1 }]) }`
@@ -609,7 +596,98 @@ const data = await sql`SELECT ${ sql('aTest', 'bTest') } FROM camel_case`
 console.log(data) // [ { aTest: 1, bTest: '1' } ]
 ```
 
-> Note that if a column name is originally registered as snake_case in the database then to tranform it from camelCase to snake_case when querying or inserting, the column camelCase name must be put in `sql('columnName')` as it's done in the above example, Postgres.js does not rewrite anything inside the static parts of the tagged templates.
+To only perform half of the transformation (eg. only the transformation **to** or **from** camel case), use the other transformation functions:
+
+```js
+// Transform the column names only to camel case
+// (for the results that are returned from the query)
+postgres({ transform: postgres.toCamel })
+
+await sql`CREATE TABLE IF NOT EXISTS camel_case (a_test INTEGER)`
+await sql`INSERT INTO camel_case ${ sql([{ a_test: 1 }]) }`
+const data = await sql`SELECT a_test FROM camel_case`
+
+console.log(data) // [ { aTest: 1 } ]
+```
+
+```js
+// Transform the column names only from camel case
+// (for interpolated inserts, updates, and selects)
+const sql = postgres({ transform: postgres.fromCamel })
+
+await sql`CREATE TABLE IF NOT EXISTS camel_case (a_test INTEGER)`
+await sql`INSERT INTO camel_case ${ sql([{ aTest: 1 }]) }`
+const data = await sql`SELECT ${ sql('aTest') } FROM camel_case`
+
+console.log(data) // [ { a_test: 1 } ]
+```
+
+> Note that Postgres.js does not rewrite the static parts of the tagged template strings. So to transform column names in your queries, the `sql()` helper must be used - eg. `${ sql('columnName') }` as in the examples above.
+
+### Transform `undefined` Values
+
+By default, Postgres.js will throw the error `UNDEFINED_VALUE: Undefined values are not allowed` when undefined values are passed 
+
+```js
+// Transform the column names to and from camel case
+const sql = postgres({
+  transform: {
+    undefined: null
+  }
+})
+
+await sql`CREATE TABLE IF NOT EXISTS transform_undefined (a_test INTEGER)`
+await sql`INSERT INTO transform_undefined ${ sql([{ a_test: undefined }]) }`
+const data = await sql`SELECT a_test FROM transform_undefined`
+
+console.log(data) // [ { a_test: null } ]
+```
+
+To combine with the built in transform functions, spread the transform in the `transform` object:
+
+```js
+// Transform the column names to and from camel case
+const sql = postgres({
+  transform: {
+    ...postgres.camel,
+    undefined: null
+  }
+})
+
+await sql`CREATE TABLE IF NOT EXISTS transform_undefined (a_test INTEGER)`
+await sql`INSERT INTO transform_undefined ${ sql([{ aTest: undefined }]) }`
+const data = await sql`SELECT ${ sql('aTest') } FROM transform_undefined`
+
+console.log(data) // [ { aTest: null } ]
+```
+
+### Custom Transform Functions
+
+To specify your own transformation functions, you can use the `column`, `value` and `row` options inside of `transform`, each an object possibly including `to` and `from` keys:
+
+* `to`: The function to transform the outgoing query column name to, i.e `SELECT ${ sql('aName') }` to `SELECT a_name` when using `postgres.toCamel`.
+* `from`: The function to transform the incoming query result column name to, see example below.
+
+> Both parameters are optional, if not provided, the default transformation function will be used.
+
+```js
+// Implement your own functions, look at postgres.toCamel, etc
+// as a reference:
+// https://github.com/porsager/postgres/blob/4241824ffd7aa94ffb482e54ca9f585d9d0a4eea/src/types.js#L310-L328
+function transformColumnToDatabase() { /* ... */ }
+function transformColumnFromDatabase() { /* ... */ }
+
+const sql = postgres({
+  transform: {
+    column: {
+      to: transformColumnToDatabase,
+      from: transformColumnFromDatabase,
+    },
+    value: { /* ... */ },
+    row: { /* ... */ }
+  }
+})
+```
 
 ## Listen & notify
 

src/connection.js

@@ -493,8 +493,8 @@ function Connection(options, queues = {}, { onopen = noop, onend = noop, onclose
       query.isRaw
         ? (row[i] = query.isRaw === true
           ? value
-          : transform.value.from ? transform.value.from(value) : value)
-        : (row[column.name] = transform.value.from ? transform.value.from(value) : value)
+          : transform.value.from ? transform.value.from(value, column) : value)
+        : (row[column.name] = transform.value.from ? transform.value.from(value, column) : value)
     }
 
     query.forEachFn

src/index.js

@@ -8,8 +8,11 @@ import {
   Identifier,
   Builder,
   toPascal,
+  pascal,
   toCamel,
+  camel,
   toKebab,
+  kebab,
   fromPascal,
   fromCamel,
   fromKebab
@@ -25,8 +28,11 @@ import largeObject from './large.js'
 Object.assign(Postgres, {
   PostgresError,
   toPascal,
+  pascal,
   toCamel,
+  camel,
   toKebab,
+  kebab,
   fromPascal,
   fromCamel,
   fromKebab,

src/types.js

@@ -322,3 +322,34 @@ export const toKebab = x => x.replace(/_/g, '-')
 export const fromCamel = x => x.replace(/([A-Z])/g, '_$1').toLowerCase()
 export const fromPascal = x => (x.slice(0, 1) + x.slice(1).replace(/([A-Z])/g, '_$1')).toLowerCase()
 export const fromKebab = x => x.replace(/-/g, '_')
+
+function createJsonTransform(fn) {
+  return function jsonTransform(x, column) {
+    return column.type === 114 || column.type === 3802
+     ? Array.isArray(x)
+       ? x.map(jsonTransform)
+       : Object.entries(x).reduce((acc, [k, v]) => Object.assign(acc, { [fn(k)]: v }), {})
+     : x
+  }
+}
+
+toCamel.column = { from: toCamel }
+toCamel.value = { from: createJsonTransform(toCamel) }
+fromCamel.column = { to: fromCamel }
+
+export const camel = { ...toCamel }
+camel.column.to = fromCamel;
+
+toPascal.column = { from: toPascal }
+toPascal.value = { from: createJsonTransform(toPascal) }
+fromPascal.column = { to: fromPascal }
+
+export const pascal = { ...toPascal }
+pascal.column.to = fromPascal
+
+toKebab.column = { from: toKebab }
+toKebab.value = { from: createJsonTransform(toKebab) }
+fromKebab.column = { to: fromKebab }
+
+export const kebab = { ...toKebab }
+kebab.column.to = fromKebab

tests/index.js

@@ -1317,7 +1317,60 @@ t('Transform value', async() => {
 })
 
 t('Transform columns from', async() => {
-  const sql = postgres({ ...options, transform: { column: { to: postgres.fromCamel, from: postgres.toCamel } } })
+  const sql = postgres({
+    ...options,
+    transform: postgres.fromCamel
+  })
+  await sql`create table test (a_test int, b_test text)`
+  await sql`insert into test ${ sql([{ aTest: 1, bTest: 1 }]) }`
+  await sql`update test set ${ sql({ aTest: 2, bTest: 2 }) }`
+  return [
+    2,
+    (await sql`select ${ sql('aTest', 'bTest') } from test`)[0].a_test,
+    await sql`drop table test`
+  ]
+})
+
+t('Transform columns to', async() => {
+  const sql = postgres({
+    ...options,
+    transform: postgres.toCamel
+  })
+  await sql`create table test (a_test int, b_test text)`
+  await sql`insert into test ${ sql([{ a_test: 1, b_test: 1 }]) }`
+  await sql`update test set ${ sql({ a_test: 2, b_test: 2 }) }`
+  return [
+    2,
+    (await sql`select a_test, b_test from test`)[0].aTest,
+    await sql`drop table test`
+  ]
+})
+
+t('Transform columns from and to', async() => {
+  const sql = postgres({
+    ...options,
+    transform: postgres.camel
+  })
+  await sql`create table test (a_test int, b_test text)`
+  await sql`insert into test ${ sql([{ aTest: 1, bTest: 1 }]) }`
+  await sql`update test set ${ sql({ aTest: 2, bTest: 2 }) }`
+  return [
+    2,
+    (await sql`select ${ sql('aTest', 'bTest') } from test`)[0].aTest,
+    await sql`drop table test`
+  ]
+})
+
+t('Transform columns from and to (legacy)', async() => {
+  const sql = postgres({
+    ...options,
+    transform: {
+      column: {
+        to: postgres.fromCamel,
+        from: postgres.toCamel
+      }
+    }
+  })
   await sql`create table test (a_test int, b_test text)`
   await sql`insert into test ${ sql([{ aTest: 1, bTest: 1 }]) }`
   await sql`update test set ${ sql({ aTest: 2, bTest: 2 }) }`