feat: treat JSON null as a literal null

.README/QUERY_BUILDING.md

@@ -426,7 +426,7 @@ Produces:
 
 ```
 
-Serializes value and binds it as an array, e.g.
+Serializes value and binds it as a JSON string literal, e.g.
 
 ```js
 await connection.query(sql`
@@ -447,14 +447,12 @@ Produces:
 
 ```
 
-This is a convenience function equivalent to:
+#### Difference from `JSON.stringify`
 
-```js
-await connection.query(sql`
-  SELECT (${JSON.stringify([1, 2, 3])}})
-`);
-
-```
+|Input|`sql.json`|`JSON.stringify`|
+|---|---|---|
+|`undefined`|Throws `InvalidInputError` error.|`undefined`|
+|`null`|`null`|`"null"` (string literal)|
 
 ### `sql.raw`
 

README.md

@@ -1568,7 +1568,7 @@ Produces:
 
 ```
 
-Serializes value and binds it as an array, e.g.
+Serializes value and binds it as a JSON string literal, e.g.
 
 ```js
 await connection.query(sql`
@@ -1589,14 +1589,13 @@ Produces:
 
 ```
 
-This is a convenience function equivalent to:
+<a name="slonik-query-building-sql-json-difference-from-json-stringify"></a>
+#### Difference from <code>JSON.stringify</code>
 
-```js
-await connection.query(sql`
-  SELECT (${JSON.stringify([1, 2, 3])}})
-`);
-
-```
+|Input|`sql.json`|`JSON.stringify`|
+|---|---|---|
+|`undefined`|Throws `InvalidInputError` error.|`undefined`|
+|`null`|`null`|`"null"` (string literal)|
 
 <a name="slonik-query-building-sql-raw"></a>
 ### <code>sql.raw</code>

src/sqlFragmentFactories/createJsonSqlFragment.js

@@ -4,13 +4,20 @@ import type {
   JsonSqlTokenType,
   SqlFragmentType,
 } from '../types';
+import {
+  InvalidInputError,
+} from '../errors';
 
 export default (token: JsonSqlTokenType, greatestParameterPosition: number): SqlFragmentType => {
+  if (token.value === undefined) {
+    throw new InvalidInputError('json value must not be undefined.');
+  }
+
   // @todo Do not add `::json` as it will fail if an attempt is made to insert to jsonb-type column.
   return {
     sql: '$' + (greatestParameterPosition + 1),
     values: [
-      JSON.stringify(token.value),
+      token.value === null ? null : JSON.stringify(token.value),
     ],
   };
 };

test/slonik/templateTags/sql/json.js

@@ -20,6 +20,18 @@ test('creates a value list', (t) => {
   });
 });
 
+test('passes null unstringified', (t) => {
+  const query = sql`SELECT ${sql.json(null)}`;
+
+  t.deepEqual(query, {
+    sql: 'SELECT $1',
+    type: SqlToken,
+    values: [
+      null,
+    ],
+  });
+});
+
 test('the resulting object is immutable', (t) => {
   const token = sql.json({
     foo: 'bar',