@juit/pgproxy-client 1.0.35 → 1.1.0

package/README.md

@@ -6,6 +6,9 @@ implementations _and_ as a registry for them.
 
 * [Connecting](#connecting)
 * [Client](#client)
+* [Result](#result)
+* [Types](#types)
+* [Template Literals](#template-literals)
 * [PGProxy](https://github.com/juitnow/juit-pgproxy/blob/main/README.md)
 * [Copyright Notice](https://github.com/juitnow/juit-pgproxy/blob/main/NOTICE.md)
 * [License](https://github.com/juitnow/juit-pgproxy/blob/main/NOTICE.md)
@@ -101,6 +104,11 @@ const result = await client.connect(async (connection) => {
 The `query(...)` method requires one parameter, the SQL query to run, and allows
 parameters (as an array) to be declared as a second, optional parameter.
 
+A second form of the `query(...)` function accepts an object with two keys:
+
+* `query`: the SQL query to execute optionally containing placeholders
+* `params`: any parameter replacement for `$x` placeholders
+
 The object passed to the `connect(...)` callback provides the following methods:
 
 * `query(...)`: as above
@@ -134,3 +142,50 @@ By manipulating the registry, one can tweak the conversion of PostgreSQL types
 to JavaScript types.
 
 For more informations see the `@juit/pgproxy-types` package.
+
+
+### Template Literals
+
+This client also exposes a `SQL` _template tagging function_, or  * a function
+capable of converting a template string into a query like structure.
+
+For example:
+
+```typescript
+const email = 'user@example.org'
+const query = SQL `SELECT * FROM users WHERE email = ${email}`
+
+// Here "query" will be something like:
+// {
+//   query: 'SELECT * FROM users WHERE email = $1',
+//   params: [ 'user@example.org' ],
+// }
+```
+
+The `SQL` function can also be use with _concatenated_ template strings, for
+example:
+
+```typescript
+const email = 'user@example.org'
+const hash = 'thePasswordHash'
+const query = SQL
+    `SELECT * FROM users WHERE email = ${email}`
+    `AND password_hash = ${hash}`
+
+// Here "query" will be something like:
+// {
+//   query: 'SELECT * FROM users WHERE email = $1 AND password_hash = $2',
+//   params: [ 'user@example.org', 'thePasswordHash' ],
+// }
+```
+
+In this case, multiple template strings will be concatenated with a single
+space character.
+
+This function can be directly used with our query interface, as follows:
+
+```typescript
+const client = new PGClient()
+const email = 'user@example.org'
+const result = await client.query(SQL `SELECT * FROM users WHERE email = ${email}`)
+```

package/dist/client.cjs

@@ -53,7 +53,8 @@ var PGClient = class PGClientImpl {
     }
     this._provider = urlOrProvider instanceof URL ? (0, import_provider.createProvider)(urlOrProvider) : urlOrProvider;
   }
-  async query(text, params = []) {
+  async query(textOrQuery, maybeParams = []) {
+    const [text, params = []] = typeof textOrQuery === "string" ? [textOrQuery, maybeParams] : [textOrQuery.query, textOrQuery.params];
     const result = await this._provider.query(text, serializeParams(params));
     return new import_result.PGResult(result, this.registry);
   }
@@ -63,7 +64,8 @@ var PGClient = class PGClientImpl {
     try {
       const registry = this.registry;
       const consumable = {
-        async query(text, params = []) {
+        async query(textOrQuery, maybeParams = []) {
+          const [text, params = []] = typeof textOrQuery === "string" ? [textOrQuery, maybeParams] : [textOrQuery.query, textOrQuery.params];
           const result = await connection.query(text, serializeParams(params));
           return new import_result.PGResult(result, registry);
         },

package/dist/client.cjs.map

@@ -1,6 +1,6 @@
 {
   "version": 3,
   "sources": ["../src/client.ts"],
-  "mappings": ";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,2BAAoC;AAEpC,oBAAuB;AACvB,sBAA+B;AAC/B,oBAAyB;AAIzB,SAAS,gBAAgB,QAAkC;AACzD,MAAI,OAAO,UAAU,EAAG,QAAO,CAAC;AAEhC,QAAM,SAA4B,IAAI,MAAM,OAAO,MAAM;AACzD,WAAS,IAAI,GAAG,IAAI,OAAO,QAAQ,KAAM;AACvC,WAAO,CAAC,IACN,OAAO,CAAC,MAAM,SAAY,OAC1B,OAAO,CAAC,MAAM,OAAO,WACrB,gCAAU,OAAO,CAAC,CAAC;AAAA,EACvB;AAEA,SAAO;AACT;AAoFO,IAAM,WAAgC,MAAM,aAAiC;AAAA,EACzE,WAAqB,IAAI,8BAAS;AAAA,EAEnC;AAAA,EAIR,YAAY,eAAyD;AACnE,oBAAgB,iBAAmB,YAAoB,SAAS,KAAK;AACrE,8BAAO,eAAe,4DAA4D;AAClF,QAAI,OAAO,kBAAkB,SAAU,iBAAgB,IAAI,IAAI,eAAe,UAAU;AACxF,8BAAO,eAAe,oCAAoC;AAE1D,QAAI,yBAAyB,KAAK;AAChC,UAAI,EAAE,cAAc,YAAY,cAAc,WAAW;AACvD,cAAM,WAAa,YAAoB,SAAS,KAAK,UAAiC;AACtF,cAAM,WAAa,YAAoB,SAAS,KAAK,cAAqC;AAC1F,sBAAc,WAAW,mBAAmB,QAAQ;AACpD,sBAAc,WAAW,mBAAmB,QAAQ;AAAA,MACtD;AAAA,IACF;AAEA,SAAK,YAAY,yBAAyB,UACtC,gCAAe,aAAa,IAC5B;AAAA,EACN;AAAA,EAEA,MAAM,MAGJ,MAAc,SAAgB,CAAC,GAAkC;AACjE,UAAM,SAAS,MAAM,KAAK,UAAU,MAAM,MAAM,gBAAgB,MAAM,CAAC;AACvE,WAAO,IAAI,uBAAqB,QAAQ,KAAK,QAAQ;AAAA,EACvD;AAAA,EAEA,MAAM,QAAW,UAAqC;AACpD,UAAM,aAAa,MAAM,KAAK,UAAU,QAAQ;AAChD,QAAI,cAAc;AAElB,QAAI;AACF,YAAM,WAAW,KAAK;AAEtB,YAAM,aAAgC;AAAA,QACpC,MAAM,MAGJ,MAAc,SAAgB,CAAC,GAAkC;AACjE,gBAAM,SAAS,MAAM,WAAW,MAAM,MAAM,gBAAgB,MAAM,CAAC;AACnE,iBAAO,IAAI,uBAAS,QAAQ,QAAQ;AAAA,QACtC;AAAA,QACA,MAAM,QAA0B;AAC9B,cAAI,YAAa,QAAO;AACxB,gBAAM,WAAW,MAAM,OAAO;AAC9B,iBAAO,cAAc;AAAA,QACvB;AAAA,QACA,MAAM,SAAwB;AAC5B,gBAAM,WAAW,MAAM,QAAQ;AAC/B,wBAAc;AAAA,QAChB;AAAA,QACA,MAAM,WAA0B;AAC9B,gBAAM,WAAW,MAAM,UAAU;AACjC,wBAAc;AAAA,QAChB;AAAA,MACF;AAEA,aAAO,MAAM,SAAS,UAAU;AAAA,IAClC,UAAE;AACA,UAAI,YAAa,OAAM,WAAW,MAAM,UAAU;AAClD,YAAM,KAAK,UAAU,QAAQ,UAAU;AAAA,IACzC;AAAA,EACF;AAAA,EAEA,MAAM,UAAyB;AAC7B,WAAO,MAAM,KAAK,UAAU,QAAQ;AAAA,EACtC;AACF;",
+  "mappings": ";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,2BAAoC;AAEpC,oBAAuB;AACvB,sBAA+B;AAC/B,oBAAyB;AAIzB,SAAS,gBAAgB,QAA2C;AAClE,MAAI,OAAO,UAAU,EAAG,QAAO,CAAC;AAEhC,QAAM,SAA4B,IAAI,MAAM,OAAO,MAAM;AACzD,WAAS,IAAI,GAAG,IAAI,OAAO,QAAQ,KAAM;AACvC,WAAO,CAAC,IACN,OAAO,CAAC,MAAM,SAAY,OAC1B,OAAO,CAAC,MAAM,OAAO,WACrB,gCAAU,OAAO,CAAC,CAAC;AAAA,EACvB;AAEA,SAAO;AACT;AAsHO,IAAM,WAAgC,MAAM,aAAiC;AAAA,EACzE,WAAqB,IAAI,8BAAS;AAAA,EAEnC;AAAA,EAIR,YAAY,eAAyD;AACnE,oBAAgB,iBAAmB,YAAoB,SAAS,KAAK;AACrE,8BAAO,eAAe,4DAA4D;AAClF,QAAI,OAAO,kBAAkB,SAAU,iBAAgB,IAAI,IAAI,eAAe,UAAU;AACxF,8BAAO,eAAe,oCAAoC;AAE1D,QAAI,yBAAyB,KAAK;AAChC,UAAI,EAAE,cAAc,YAAY,cAAc,WAAW;AACvD,cAAM,WAAa,YAAoB,SAAS,KAAK,UAAiC;AACtF,cAAM,WAAa,YAAoB,SAAS,KAAK,cAAqC;AAC1F,sBAAc,WAAW,mBAAmB,QAAQ;AACpD,sBAAc,WAAW,mBAAmB,QAAQ;AAAA,MACtD;AAAA,IACF;AAEA,SAAK,YAAY,yBAAyB,UACtC,gCAAe,aAAa,IAC5B;AAAA,EACN;AAAA,EAaA,MAAM,MAGJ,aAA+B,cAA8B,CAAC,GAAkC;AAChG,UAAM,CAAE,MAAM,SAAS,CAAC,CAAE,IAAI,OAAO,gBAAgB,WACnD,CAAE,aAAa,WAAY,IAAI,CAAE,YAAY,OAAO,YAAY,MAAO;AAGzE,UAAM,SAAS,MAAM,KAAK,UAAU,MAAM,MAAM,gBAAgB,MAAM,CAAC;AACvE,WAAO,IAAI,uBAAqB,QAAQ,KAAK,QAAQ;AAAA,EACvD;AAAA,EAEA,MAAM,QAAW,UAAqC;AACpD,UAAM,aAAa,MAAM,KAAK,UAAU,QAAQ;AAChD,QAAI,cAAc;AAElB,QAAI;AACF,YAAM,WAAW,KAAK;AAEtB,YAAM,aAAgC;AAAA,QACpC,MAAM,MAGJ,aAA+B,cAA8B,CAAC,GAAkC;AAChG,gBAAM,CAAE,MAAM,SAAS,CAAC,CAAE,IAAI,OAAO,gBAAgB,WACjD,CAAE,aAAa,WAAY,IAAI,CAAE,YAAY,OAAO,YAAY,MAAO;AAE3E,gBAAM,SAAS,MAAM,WAAW,MAAM,MAAM,gBAAgB,MAAM,CAAC;AACnE,iBAAO,IAAI,uBAAS,QAAQ,QAAQ;AAAA,QACtC;AAAA,QACA,MAAM,QAA0B;AAC9B,cAAI,YAAa,QAAO;AACxB,gBAAM,WAAW,MAAM,OAAO;AAC9B,iBAAO,cAAc;AAAA,QACvB;AAAA,QACA,MAAM,SAAwB;AAC5B,gBAAM,WAAW,MAAM,QAAQ;AAC/B,wBAAc;AAAA,QAChB;AAAA,QACA,MAAM,WAA0B;AAC9B,gBAAM,WAAW,MAAM,UAAU;AACjC,wBAAc;AAAA,QAChB;AAAA,MACF;AAEA,aAAO,MAAM,SAAS,UAAU;AAAA,IAClC,UAAE;AACA,UAAI,YAAa,OAAM,WAAW,MAAM,UAAU;AAClD,YAAM,KAAK,UAAU,QAAQ,UAAU;AAAA,IACzC;AAAA,EACF;AAAA,EAEA,MAAM,UAAyB;AAC7B,WAAO,MAAM,KAAK,UAAU,QAAQ;AAAA,EACtC;AACF;",
   "names": []
 }

package/dist/client.d.ts

@@ -1,6 +1,13 @@
 import { Registry } from '@juit/pgproxy-types';
 import { PGResult } from './result';
 import type { PGConnection, PGProvider } from './provider';
+/** An interface representing a SQL query to a database */
+export interface PGQuery {
+    /** The SQL query to execute optionally containing placeholders. */
+    readonly query: string;
+    /** Any parameter replacement for `$x` placeholders. */
+    readonly params?: readonly any[];
+}
 /** An interface for an object that can execute queries on a database */
 export interface PGQueryable {
     /**
@@ -9,7 +16,14 @@ export interface PGQueryable {
      * @param text - The SQL query to execute optionally containing placeholders.
      * @param params - Any parameter replacement for `$x` placeholders.
      */
-    query<Row extends Record<string, any> = Record<string, any>, Tuple extends readonly any[] = readonly any[]>(text: string, params?: any[]): Promise<PGResult<Row, Tuple>>;
+    query<Row extends Record<string, any> = Record<string, any>, Tuple extends readonly any[] = readonly any[]>(text: string, params?: readonly any[]): Promise<PGResult<Row, Tuple>>;
+    /**
+     * Execute a query on the database
+     *
+     * @param query - An object containing the query (both the SQL string and its
+     *                related parameters) to execute
+     */
+    query<Row extends Record<string, any> = Record<string, any>, Tuple extends readonly any[] = readonly any[]>(query: PGQuery): Promise<PGResult<Row, Tuple>>;
 }
 /**
  * An interface for an object that can execute queries _and transactions_
@@ -36,14 +50,25 @@ export interface PGClient extends PGQueryable {
     /**
      * Execute a _single_ query on the database.
      *
-     * Invoking the `query` method on a {@link (PGClient:interface)} does NOT guarantee that
-     * the query will be executed on the same connection, therefore things like
-     * _transactions_ will be immediately rolled back after the query.
+     * Invoking the `query` method on a {@link (PGClient:interface)} does NOT
+     * guarantee that the query will be executed on the same connection, therefore
+     * things like _transactions_ will be immediately rolled back after the query.
      *
      * @param text - The SQL query to execute optionally containing placeholders.
      * @param params - Any parameter replacement for `$x` placeholders.
      */
-    query<Row extends Record<string, any> = Record<string, any>, Tuple extends readonly any[] = readonly any[]>(text: string, params?: any[]): Promise<PGResult<Row, Tuple>>;
+    query<Row extends Record<string, any> = Record<string, any>, Tuple extends readonly any[] = readonly any[]>(text: string, params?: readonly any[]): Promise<PGResult<Row, Tuple>>;
+    /**
+     * Execute a _single_ query on the database.
+     *
+     * Invoking the `query` method on a {@link (PGClient:interface)} does NOT
+     * guarantee that the query will be executed on the same connection, therefore
+     * things like _transactions_ will be immediately rolled back after the query.
+     *
+     * @param query - An object containing the query (both the SQL string and its
+     *                related parameters) to execute
+     */
+    query<Row extends Record<string, any> = Record<string, any>, Tuple extends readonly any[] = readonly any[]>(query: PGQuery): Promise<PGResult<Row, Tuple>>;
     /**
      * Connect to the database to execute a number of different queries.
      *

package/dist/client.mjs

@@ -29,7 +29,8 @@ var PGClient = class PGClientImpl {
     }
     this._provider = urlOrProvider instanceof URL ? createProvider(urlOrProvider) : urlOrProvider;
   }
-  async query(text, params = []) {
+  async query(textOrQuery, maybeParams = []) {
+    const [text, params = []] = typeof textOrQuery === "string" ? [textOrQuery, maybeParams] : [textOrQuery.query, textOrQuery.params];
     const result = await this._provider.query(text, serializeParams(params));
     return new PGResult(result, this.registry);
   }
@@ -39,7 +40,8 @@ var PGClient = class PGClientImpl {
     try {
       const registry = this.registry;
       const consumable = {
-        async query(text, params = []) {
+        async query(textOrQuery, maybeParams = []) {
+          const [text, params = []] = typeof textOrQuery === "string" ? [textOrQuery, maybeParams] : [textOrQuery.query, textOrQuery.params];
           const result = await connection.query(text, serializeParams(params));
           return new PGResult(result, registry);
         },

package/dist/client.mjs.map

@@ -1,6 +1,6 @@
 {
   "version": 3,
   "sources": ["../src/client.ts"],
-  "mappings": ";AAAA,SAAS,UAAU,iBAAiB;AAEpC,SAAS,cAAc;AACvB,SAAS,sBAAsB;AAC/B,SAAS,gBAAgB;AAIzB,SAAS,gBAAgB,QAAkC;AACzD,MAAI,OAAO,UAAU,EAAG,QAAO,CAAC;AAEhC,QAAM,SAA4B,IAAI,MAAM,OAAO,MAAM;AACzD,WAAS,IAAI,GAAG,IAAI,OAAO,QAAQ,KAAM;AACvC,WAAO,CAAC,IACN,OAAO,CAAC,MAAM,SAAY,OAC1B,OAAO,CAAC,MAAM,OAAO,OACrB,UAAU,OAAO,CAAC,CAAC;AAAA,EACvB;AAEA,SAAO;AACT;AAoFO,IAAM,WAAgC,MAAM,aAAiC;AAAA,EACzE,WAAqB,IAAI,SAAS;AAAA,EAEnC;AAAA,EAIR,YAAY,eAAyD;AACnE,oBAAgB,iBAAmB,YAAoB,SAAS,KAAK;AACrE,WAAO,eAAe,4DAA4D;AAClF,QAAI,OAAO,kBAAkB,SAAU,iBAAgB,IAAI,IAAI,eAAe,UAAU;AACxF,WAAO,eAAe,oCAAoC;AAE1D,QAAI,yBAAyB,KAAK;AAChC,UAAI,EAAE,cAAc,YAAY,cAAc,WAAW;AACvD,cAAM,WAAa,YAAoB,SAAS,KAAK,UAAiC;AACtF,cAAM,WAAa,YAAoB,SAAS,KAAK,cAAqC;AAC1F,sBAAc,WAAW,mBAAmB,QAAQ;AACpD,sBAAc,WAAW,mBAAmB,QAAQ;AAAA,MACtD;AAAA,IACF;AAEA,SAAK,YAAY,yBAAyB,MACtC,eAAe,aAAa,IAC5B;AAAA,EACN;AAAA,EAEA,MAAM,MAGJ,MAAc,SAAgB,CAAC,GAAkC;AACjE,UAAM,SAAS,MAAM,KAAK,UAAU,MAAM,MAAM,gBAAgB,MAAM,CAAC;AACvE,WAAO,IAAI,SAAqB,QAAQ,KAAK,QAAQ;AAAA,EACvD;AAAA,EAEA,MAAM,QAAW,UAAqC;AACpD,UAAM,aAAa,MAAM,KAAK,UAAU,QAAQ;AAChD,QAAI,cAAc;AAElB,QAAI;AACF,YAAM,WAAW,KAAK;AAEtB,YAAM,aAAgC;AAAA,QACpC,MAAM,MAGJ,MAAc,SAAgB,CAAC,GAAkC;AACjE,gBAAM,SAAS,MAAM,WAAW,MAAM,MAAM,gBAAgB,MAAM,CAAC;AACnE,iBAAO,IAAI,SAAS,QAAQ,QAAQ;AAAA,QACtC;AAAA,QACA,MAAM,QAA0B;AAC9B,cAAI,YAAa,QAAO;AACxB,gBAAM,WAAW,MAAM,OAAO;AAC9B,iBAAO,cAAc;AAAA,QACvB;AAAA,QACA,MAAM,SAAwB;AAC5B,gBAAM,WAAW,MAAM,QAAQ;AAC/B,wBAAc;AAAA,QAChB;AAAA,QACA,MAAM,WAA0B;AAC9B,gBAAM,WAAW,MAAM,UAAU;AACjC,wBAAc;AAAA,QAChB;AAAA,MACF;AAEA,aAAO,MAAM,SAAS,UAAU;AAAA,IAClC,UAAE;AACA,UAAI,YAAa,OAAM,WAAW,MAAM,UAAU;AAClD,YAAM,KAAK,UAAU,QAAQ,UAAU;AAAA,IACzC;AAAA,EACF;AAAA,EAEA,MAAM,UAAyB;AAC7B,WAAO,MAAM,KAAK,UAAU,QAAQ;AAAA,EACtC;AACF;",
+  "mappings": ";AAAA,SAAS,UAAU,iBAAiB;AAEpC,SAAS,cAAc;AACvB,SAAS,sBAAsB;AAC/B,SAAS,gBAAgB;AAIzB,SAAS,gBAAgB,QAA2C;AAClE,MAAI,OAAO,UAAU,EAAG,QAAO,CAAC;AAEhC,QAAM,SAA4B,IAAI,MAAM,OAAO,MAAM;AACzD,WAAS,IAAI,GAAG,IAAI,OAAO,QAAQ,KAAM;AACvC,WAAO,CAAC,IACN,OAAO,CAAC,MAAM,SAAY,OAC1B,OAAO,CAAC,MAAM,OAAO,OACrB,UAAU,OAAO,CAAC,CAAC;AAAA,EACvB;AAEA,SAAO;AACT;AAsHO,IAAM,WAAgC,MAAM,aAAiC;AAAA,EACzE,WAAqB,IAAI,SAAS;AAAA,EAEnC;AAAA,EAIR,YAAY,eAAyD;AACnE,oBAAgB,iBAAmB,YAAoB,SAAS,KAAK;AACrE,WAAO,eAAe,4DAA4D;AAClF,QAAI,OAAO,kBAAkB,SAAU,iBAAgB,IAAI,IAAI,eAAe,UAAU;AACxF,WAAO,eAAe,oCAAoC;AAE1D,QAAI,yBAAyB,KAAK;AAChC,UAAI,EAAE,cAAc,YAAY,cAAc,WAAW;AACvD,cAAM,WAAa,YAAoB,SAAS,KAAK,UAAiC;AACtF,cAAM,WAAa,YAAoB,SAAS,KAAK,cAAqC;AAC1F,sBAAc,WAAW,mBAAmB,QAAQ;AACpD,sBAAc,WAAW,mBAAmB,QAAQ;AAAA,MACtD;AAAA,IACF;AAEA,SAAK,YAAY,yBAAyB,MACtC,eAAe,aAAa,IAC5B;AAAA,EACN;AAAA,EAaA,MAAM,MAGJ,aAA+B,cAA8B,CAAC,GAAkC;AAChG,UAAM,CAAE,MAAM,SAAS,CAAC,CAAE,IAAI,OAAO,gBAAgB,WACnD,CAAE,aAAa,WAAY,IAAI,CAAE,YAAY,OAAO,YAAY,MAAO;AAGzE,UAAM,SAAS,MAAM,KAAK,UAAU,MAAM,MAAM,gBAAgB,MAAM,CAAC;AACvE,WAAO,IAAI,SAAqB,QAAQ,KAAK,QAAQ;AAAA,EACvD;AAAA,EAEA,MAAM,QAAW,UAAqC;AACpD,UAAM,aAAa,MAAM,KAAK,UAAU,QAAQ;AAChD,QAAI,cAAc;AAElB,QAAI;AACF,YAAM,WAAW,KAAK;AAEtB,YAAM,aAAgC;AAAA,QACpC,MAAM,MAGJ,aAA+B,cAA8B,CAAC,GAAkC;AAChG,gBAAM,CAAE,MAAM,SAAS,CAAC,CAAE,IAAI,OAAO,gBAAgB,WACjD,CAAE,aAAa,WAAY,IAAI,CAAE,YAAY,OAAO,YAAY,MAAO;AAE3E,gBAAM,SAAS,MAAM,WAAW,MAAM,MAAM,gBAAgB,MAAM,CAAC;AACnE,iBAAO,IAAI,SAAS,QAAQ,QAAQ;AAAA,QACtC;AAAA,QACA,MAAM,QAA0B;AAC9B,cAAI,YAAa,QAAO;AACxB,gBAAM,WAAW,MAAM,OAAO;AAC9B,iBAAO,cAAc;AAAA,QACvB;AAAA,QACA,MAAM,SAAwB;AAC5B,gBAAM,WAAW,MAAM,QAAQ;AAC/B,wBAAc;AAAA,QAChB;AAAA,QACA,MAAM,WAA0B;AAC9B,gBAAM,WAAW,MAAM,UAAU;AACjC,wBAAc;AAAA,QAChB;AAAA,MACF;AAEA,aAAO,MAAM,SAAS,UAAU;AAAA,IAClC,UAAE;AACA,UAAI,YAAa,OAAM,WAAW,MAAM,UAAU;AAClD,YAAM,KAAK,UAAU,QAAQ,UAAU;AAAA,IACzC;AAAA,EACF;AAAA,EAEA,MAAM,UAAyB;AAC7B,WAAO,MAAM,KAAK,UAAU,QAAQ;AAAA,EACtC;AACF;",
   "names": []
 }

package/dist/index.cjs

@@ -21,6 +21,7 @@ __reExport(src_exports, require("./assert.cjs"), module.exports);
 __reExport(src_exports, require("./client.cjs"), module.exports);
 __reExport(src_exports, require("./provider.cjs"), module.exports);
 __reExport(src_exports, require("./result.cjs"), module.exports);
+__reExport(src_exports, require("./sql.cjs"), module.exports);
 __reExport(src_exports, require("./websocket.cjs"), module.exports);
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
@@ -28,6 +29,7 @@ __reExport(src_exports, require("./websocket.cjs"), module.exports);
   ...require("./client.cjs"),
   ...require("./provider.cjs"),
   ...require("./result.cjs"),
+  ...require("./sql.cjs"),
   ...require("./websocket.cjs")
 });
 //# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1,6 +1,6 @@
 {
   "version": 3,
   "sources": ["../src/index.ts"],
-  "mappings": ";;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA,wBAAc,yBAAd;AACA,wBAAc,yBADd;AAEA,wBAAc,2BAFd;AAGA,wBAAc,yBAHd;AAIA,wBAAc,4BAJd;",
+  "mappings": ";;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA,wBAAc,yBAAd;AACA,wBAAc,yBADd;AAEA,wBAAc,2BAFd;AAGA,wBAAc,yBAHd;AAIA,wBAAc,sBAJd;AAKA,wBAAc,4BALd;",
   "names": []
 }

package/dist/index.d.ts

@@ -2,4 +2,5 @@ export * from './assert';
 export * from './client';
 export * from './provider';
 export * from './result';
+export * from './sql';
 export * from './websocket';

package/dist/index.mjs

@@ -3,5 +3,6 @@ export * from "./assert.mjs";
 export * from "./client.mjs";
 export * from "./provider.mjs";
 export * from "./result.mjs";
+export * from "./sql.mjs";
 export * from "./websocket.mjs";
 //# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -1,6 +1,6 @@
 {
   "version": 3,
   "sources": ["../src/index.ts"],
-  "mappings": ";AAAA,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;",
+  "mappings": ";AAAA,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;",
   "names": []
 }

package/dist/sql.cjs

@@ -0,0 +1,49 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// sql.ts
+var sql_exports = {};
+__export(sql_exports, {
+  SQL: () => SQL
+});
+module.exports = __toCommonJS(sql_exports);
+function makeSQL(parts, params, query = "", start = 0) {
+  const [first = "", ...rest] = parts;
+  if (query) query += " ";
+  query += rest.reduce((q, s, i) => `${q}$${i + start + 1}${s}`, first);
+  const sql = (strings, ...args) => {
+    return makeSQL(strings, [...params, ...args], query, params.length);
+  };
+  return Object.assign(sql, {
+    get query() {
+      return query;
+    },
+    get params() {
+      return [...params];
+    }
+  });
+}
+function SQL(strings, ...args) {
+  return makeSQL(strings, args);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SQL
+});
+//# sourceMappingURL=sql.cjs.map

package/dist/sql.cjs.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../src/sql.ts"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AA+CA,SAAS,QACL,OACA,QACA,QAAgB,IAChB,QAAgB,GACb;AACL,QAAM,CAAE,QAAQ,IAAI,GAAG,IAAK,IAAI;AAEhC,MAAI,MAAO,UAAS;AACpB,WAAS,KAAK,OAAO,CAAC,GAAG,GAAG,MAAM,GAAG,CAAC,IAAI,IAAI,QAAQ,CAAC,GAAG,CAAC,IAAI,KAAK;AAEpE,QAAM,MAAM,CAAC,YAA+B,SAA8B;AACxE,WAAO,QAAQ,SAAS,CAAE,GAAG,QAAQ,GAAG,IAAK,GAAG,OAAO,OAAO,MAAM;AAAA,EACtE;AAEA,SAAO,OAAO,OAAO,KAAK;AAAA,IACxB,IAAI,QAAgB;AAClB,aAAO;AAAA,IACT;AAAA,IACA,IAAI,SAAyB;AAC3B,aAAO,CAAE,GAAG,MAAO;AAAA,IACrB;AAAA,EACF,CAAC;AACH;AAuCO,SAAS,IAAI,YAA+B,MAA2B;AAC5E,SAAO,QAAQ,SAAS,IAAI;AAC9B;",
+  "names": []
+}

package/dist/sql.d.ts

@@ -0,0 +1,79 @@
+import type { PGQuery } from './client';
+/**
+ * A _function_ capable of converting a template string into a {@link PGQuery}
+ * like structure (tagged template literals).
+ *
+ * For example:
+ *
+ * ```typescript
+ * const email = 'user@example.org'
+ * const query = SQL `SELECT * FROM users WHERE email = ${email}`
+ *
+ * // Here "query" will be something like:
+ * // {
+ * //   query: 'SELECT * FROM users WHERE email = $1',
+ * //   params: [ 'user@example.org' ],
+ * // }
+ * ```
+ *
+ * The `SQL` function can also be use with _concatenated_ template strings, for
+ * example:
+ *
+ * ```typescript
+ * const email = 'user@example.org'
+ * const hash = 'thePasswordHash'
+ * const query = SQL
+ *     `SELECT * FROM users WHERE email = ${email}`
+ *     `AND password_hash = ${hash}`
+ *
+ * // Here "query" will be something like:
+ * // {
+ * //   query: 'SELECT * FROM users WHERE email = $1 AND password_hash = $2',
+ * //   params: [ 'user@example.org', 'thePasswordHash' ],
+ * // }
+ * ```
+ *
+ * In this case, multiple template strings will be concatenated with a single
+ * space character.
+ */
+export interface SQL extends Required<PGQuery> {
+    (strings: readonly string[], ...args: any[]): SQL;
+}
+/**
+ * A _function_ capable of converting a template string into a {@link PGQuery}
+ * like structure (tagged template literals).
+ *
+ * For example:
+ *
+ * ```typescript
+ * const email = 'user@example.org'
+ * const query = SQL `SELECT * FROM users WHERE email = ${email}`
+ *
+ * // Here "query" will be something like:
+ * // {
+ * //   query: 'SELECT * FROM users WHERE email = $1',
+ * //   params: [ 'user@example.org' ],
+ * // }
+ * ```
+ *
+ * The `SQL` function can also be use with _concatenated_ template strings, for
+ * example:
+ *
+ * ```typescript
+ * const email = 'user@example.org'
+ * const hash = 'thePasswordHash'
+ * const query = SQL
+ *     `SELECT * FROM users WHERE email = ${email}`
+ *     `AND password_hash = ${hash}`
+ *
+ * // Here "query" will be something like:
+ * // {
+ * //   query: 'SELECT * FROM users WHERE email = $1 AND password_hash = $2',
+ * //   params: [ 'user@example.org', 'thePasswordHash' ],
+ * // }
+ * ```
+ *
+ * In this case, multiple template strings will be concatenated with a single
+ * space character.
+ */
+export declare function SQL(strings: readonly string[], ...args: readonly any[]): SQL;

package/dist/sql.mjs

@@ -0,0 +1,24 @@
+// sql.ts
+function makeSQL(parts, params, query = "", start = 0) {
+  const [first = "", ...rest] = parts;
+  if (query) query += " ";
+  query += rest.reduce((q, s, i) => `${q}$${i + start + 1}${s}`, first);
+  const sql = (strings, ...args) => {
+    return makeSQL(strings, [...params, ...args], query, params.length);
+  };
+  return Object.assign(sql, {
+    get query() {
+      return query;
+    },
+    get params() {
+      return [...params];
+    }
+  });
+}
+function SQL(strings, ...args) {
+  return makeSQL(strings, args);
+}
+export {
+  SQL
+};
+//# sourceMappingURL=sql.mjs.map

package/dist/sql.mjs.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../src/sql.ts"],
+  "mappings": ";AA+CA,SAAS,QACL,OACA,QACA,QAAgB,IAChB,QAAgB,GACb;AACL,QAAM,CAAE,QAAQ,IAAI,GAAG,IAAK,IAAI;AAEhC,MAAI,MAAO,UAAS;AACpB,WAAS,KAAK,OAAO,CAAC,GAAG,GAAG,MAAM,GAAG,CAAC,IAAI,IAAI,QAAQ,CAAC,GAAG,CAAC,IAAI,KAAK;AAEpE,QAAM,MAAM,CAAC,YAA+B,SAA8B;AACxE,WAAO,QAAQ,SAAS,CAAE,GAAG,QAAQ,GAAG,IAAK,GAAG,OAAO,OAAO,MAAM;AAAA,EACtE;AAEA,SAAO,OAAO,OAAO,KAAK;AAAA,IACxB,IAAI,QAAgB;AAClB,aAAO;AAAA,IACT;AAAA,IACA,IAAI,SAAyB;AAC3B,aAAO,CAAE,GAAG,MAAO;AAAA,IACrB;AAAA,EACF,CAAC;AACH;AAuCO,SAAS,IAAI,YAA+B,MAA2B;AAC5E,SAAO,QAAQ,SAAS,IAAI;AAC9B;",
+  "names": []
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juit/pgproxy-client",
-  "version": "1.0.35",
+  "version": "1.1.0",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
@@ -35,7 +35,7 @@
   },
   "homepage": "https://github.com/juitnow/juit-pgproxy#readme",
   "dependencies": {
-    "@juit/pgproxy-types": "1.0.35"
+    "@juit/pgproxy-types": "1.1.0"
   },
   "directories": {
     "test": "test"

package/src/client.ts

@@ -6,7 +6,7 @@ import { PGResult } from './result'
 
 import type { PGConnection, PGProvider } from './provider'
 
-function serializeParams(params: any[]): (string | null)[] {
+function serializeParams(params: readonly any[]): (string | null)[] {
   if (params.length == 0) return []
 
   const result: (string | null)[] = new Array(params.length)
@@ -20,6 +20,14 @@ function serializeParams(params: any[]): (string | null)[] {
   return result
 }
 
+/** An interface representing a SQL query to a database */
+export interface PGQuery {
+  /** The SQL query to execute optionally containing placeholders. */
+  readonly query: string
+  /** Any parameter replacement for `$x` placeholders. */
+  readonly params?: readonly any[]
+}
+
 /** An interface for an object that can execute queries on a database */
 export interface PGQueryable {
   /**
@@ -31,7 +39,18 @@ export interface PGQueryable {
   query<
     Row extends Record<string, any> = Record<string, any>,
     Tuple extends readonly any[] = readonly any [],
-  >(text: string, params?: any[]): Promise<PGResult<Row, Tuple>>
+  >(text: string, params?: readonly any[]): Promise<PGResult<Row, Tuple>>
+
+  /**
+   * Execute a query on the database
+   *
+   * @param query - An object containing the query (both the SQL string and its
+   *                related parameters) to execute
+   */
+  query<
+    Row extends Record<string, any> = Record<string, any>,
+    Tuple extends readonly any[] = readonly any [],
+  >(query: PGQuery): Promise<PGResult<Row, Tuple>>
 }
 
 /**
@@ -63,9 +82,9 @@ export interface PGClient extends PGQueryable {
   /**
    * Execute a _single_ query on the database.
    *
-   * Invoking the `query` method on a {@link (PGClient:interface)} does NOT guarantee that
-   * the query will be executed on the same connection, therefore things like
-   * _transactions_ will be immediately rolled back after the query.
+   * Invoking the `query` method on a {@link (PGClient:interface)} does NOT
+   * guarantee that the query will be executed on the same connection, therefore
+   * things like _transactions_ will be immediately rolled back after the query.
    *
    * @param text - The SQL query to execute optionally containing placeholders.
    * @param params - Any parameter replacement for `$x` placeholders.
@@ -73,7 +92,22 @@ export interface PGClient extends PGQueryable {
   query<
     Row extends Record<string, any> = Record<string, any>,
     Tuple extends readonly any[] = readonly any [],
-  >(text: string, params?: any[]): Promise<PGResult<Row, Tuple>>
+  >(text: string, params?: readonly any[]): Promise<PGResult<Row, Tuple>>
+
+  /**
+   * Execute a _single_ query on the database.
+   *
+   * Invoking the `query` method on a {@link (PGClient:interface)} does NOT
+   * guarantee that the query will be executed on the same connection, therefore
+   * things like _transactions_ will be immediately rolled back after the query.
+   *
+   * @param query - An object containing the query (both the SQL string and its
+   *                related parameters) to execute
+   */
+  query<
+    Row extends Record<string, any> = Record<string, any>,
+    Tuple extends readonly any[] = readonly any [],
+  >(query: PGQuery): Promise<PGResult<Row, Tuple>>
 
   /**
    * Connect to the database to execute a number of different queries.
@@ -132,7 +166,22 @@ export const PGClient: PGClientConstructor = class PGClientImpl implements PGCli
   async query<
     Row extends Record<string, any> = Record<string, any>,
     Tuple extends readonly any[] = readonly any [],
-  >(text: string, params: any[] = []): Promise<PGResult<Row, Tuple>> {
+  >(text: string, params?: readonly any[]): Promise<PGResult<Row, Tuple>>
+
+  async query<
+    Row extends Record<string, any> = Record<string, any>,
+    Tuple extends readonly any[] = readonly any [],
+  >(query: PGQuery): Promise<PGResult<Row, Tuple>>
+
+
+  async query<
+    Row extends Record<string, any> = Record<string, any>,
+    Tuple extends readonly any[] = readonly any [],
+  >(textOrQuery: string | PGQuery, maybeParams: readonly any[] = []): Promise<PGResult<Row, Tuple>> {
+    const [ text, params = [] ] = typeof textOrQuery === 'string' ?
+      [ textOrQuery, maybeParams ] : [ textOrQuery.query, textOrQuery.params ]
+
+
     const result = await this._provider.query(text, serializeParams(params))
     return new PGResult<Row, Tuple>(result, this.registry)
   }
@@ -148,7 +197,10 @@ export const PGClient: PGClientConstructor = class PGClientImpl implements PGCli
         async query<
           Row extends Record<string, any> = Record<string, any>,
           Tuple extends readonly any[] = readonly any [],
-        >(text: string, params: any[] = []): Promise<PGResult<Row, Tuple>> {
+        >(textOrQuery: string | PGQuery, maybeParams: readonly any[] = []): Promise<PGResult<Row, Tuple>> {
+          const [ text, params = [] ] = typeof textOrQuery === 'string' ?
+              [ textOrQuery, maybeParams ] : [ textOrQuery.query, textOrQuery.params ]
+
           const result = await connection.query(text, serializeParams(params))
           return new PGResult(result, registry)
         },

package/src/index.ts

@@ -2,4 +2,5 @@ export * from './assert'
 export * from './client'
 export * from './provider'
 export * from './result'
+export * from './sql'
 export * from './websocket'

package/src/sql.ts

@@ -0,0 +1,112 @@
+import type { PGQuery } from './client'
+
+/**
+ * A _function_ capable of converting a template string into a {@link PGQuery}
+ * like structure (tagged template literals).
+ *
+ * For example:
+ *
+ * ```typescript
+ * const email = 'user@example.org'
+ * const query = SQL `SELECT * FROM users WHERE email = ${email}`
+ *
+ * // Here "query" will be something like:
+ * // {
+ * //   query: 'SELECT * FROM users WHERE email = $1',
+ * //   params: [ 'user@example.org' ],
+ * // }
+ * ```
+ *
+ * The `SQL` function can also be use with _concatenated_ template strings, for
+ * example:
+ *
+ * ```typescript
+ * const email = 'user@example.org'
+ * const hash = 'thePasswordHash'
+ * const query = SQL
+ *     `SELECT * FROM users WHERE email = ${email}`
+ *     `AND password_hash = ${hash}`
+ *
+ * // Here "query" will be something like:
+ * // {
+ * //   query: 'SELECT * FROM users WHERE email = $1 AND password_hash = $2',
+ * //   params: [ 'user@example.org', 'thePasswordHash' ],
+ * // }
+ * ```
+ *
+ * In this case, multiple template strings will be concatenated with a single
+ * space character.
+ */
+export interface SQL extends Required<PGQuery> {
+  (strings: readonly string [], ...args: any[]): SQL,
+}
+
+/**
+ * Entry point to parse a template string, optionally concatenating it to a
+ * previously parsed template (already converted into a `SQL` function)
+ */
+function makeSQL(
+    parts: readonly string [],
+    params: readonly any[],
+    query: string = '',
+    start: number = 0,
+): SQL {
+  const [ first = '', ...rest ] = parts
+
+  if (query) query += ' '
+  query += rest.reduce((q, s, i) => `${q}$${i + start + 1}${s}`, first)
+
+  const sql = (strings: readonly string[], ...args: readonly any[]): SQL => {
+    return makeSQL(strings, [ ...params, ...args ], query, params.length)
+  }
+
+  return Object.assign(sql, {
+    get query(): string {
+      return query
+    },
+    get params(): readonly any[] {
+      return [ ...params ]
+    },
+  })
+}
+
+/**
+ * A _function_ capable of converting a template string into a {@link PGQuery}
+ * like structure (tagged template literals).
+ *
+ * For example:
+ *
+ * ```typescript
+ * const email = 'user@example.org'
+ * const query = SQL `SELECT * FROM users WHERE email = ${email}`
+ *
+ * // Here "query" will be something like:
+ * // {
+ * //   query: 'SELECT * FROM users WHERE email = $1',
+ * //   params: [ 'user@example.org' ],
+ * // }
+ * ```
+ *
+ * The `SQL` function can also be use with _concatenated_ template strings, for
+ * example:
+ *
+ * ```typescript
+ * const email = 'user@example.org'
+ * const hash = 'thePasswordHash'
+ * const query = SQL
+ *     `SELECT * FROM users WHERE email = ${email}`
+ *     `AND password_hash = ${hash}`
+ *
+ * // Here "query" will be something like:
+ * // {
+ * //   query: 'SELECT * FROM users WHERE email = $1 AND password_hash = $2',
+ * //   params: [ 'user@example.org', 'thePasswordHash' ],
+ * // }
+ * ```
+ *
+ * In this case, multiple template strings will be concatenated with a single
+ * space character.
+ */
+export function SQL(strings: readonly string[], ...args: readonly any[]): SQL {
+  return makeSQL(strings, args)
+}