@juit/pgproxy-client - npm Package Compare versions

Comparing version 1.0.35 to 1.1.0

dist/client.d.ts

 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 */
@@ -12,3 +19,10 @@ 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>>;
+    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>>;
 }
@@ -40,5 +54,5 @@ /**
      *
-     * 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.
      *
@@ -48,4 +62,15 @@ * @param text - The SQL query to execute optionally containing 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.
@@ -52,0 +77,0 @@ *

dist/index.d.ts

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

package.json

 {
   "name": "@juit/pgproxy-client",
-  "version": "1.0.35",
+  "version": "1.1.0",
   "main": "./dist/index.cjs",
@@ -38,3 +38,3 @@ "module": "./dist/index.mjs",
   "dependencies": {
-    "@juit/pgproxy-types": "1.0.35"
+    "@juit/pgproxy-types": "1.1.0"
   },
@@ -41,0 +41,0 @@ "directories": {

README.md

@@ -9,2 +9,5 @@ # PostgreSQL Proxy Client (Base Package)
 * [Client](#client)
+* [Result](#result)
+* [Types](#types)
+* [Template Literals](#template-literals)
 * [PGProxy](https://github.com/juitnow/juit-pgproxy/blob/main/README.md)
@@ -105,2 +108,7 @@ * [Copyright Notice](https://github.com/juitnow/juit-pgproxy/blob/main/NOTICE.md)
 
+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:
@@ -139,1 +147,48 @@
 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 = '[e-mail]'
+const query = SQL `SELECT * FROM users WHERE email = ${email}`
+
+// Here "query" will be something like:
+// {
+//   query: 'SELECT * FROM users WHERE email = $1',
+//   params: [ '[e-mail]' ],
+// }
+```
+
+The `SQL` function can also be use with _concatenated_ template strings, for
+example:
+
+```typescript
+const email = '[e-mail]'
+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: [ '[e-mail]', '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 = '[e-mail]'
+const result = await client.query(SQL `SELECT * FROM users WHERE email = ${email}`)
+```

src/client.ts

@@ -9,3 +9,3 @@ import { Registry, serialize } from '@juit/pgproxy-types'
 
-function serializeParams(params: any[]): (string | null)[] {
+function serializeParams(params: readonly any[]): (string | null)[] {
   if (params.length == 0) return []
@@ -24,2 +24,10 @@
 
+/** 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 */
@@ -36,3 +44,14 @@ export interface PGQueryable {
     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>>
 }
@@ -69,5 +88,5 @@
    *
-   * 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.
    *
@@ -80,5 +99,20 @@ * @param text - The SQL query to execute optionally containing placeholders.
     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.
@@ -140,3 +174,18 @@ *
     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))
@@ -157,3 +206,6 @@ return new PGResult<Row, Tuple>(result, this.registry)
           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))
@@ -160,0 +212,0 @@ return new PGResult(result, registry)

src/index.ts

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

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

94455

increased by18.61%

Number of package files

44

increased by15.79%

Lines of code

1815

increased by22.55%

Number of lines in readme file

192

increased by40.15%

Dependency changes

• + Added@juit/pgproxy-types@1.1.0(transitive)

• - Removed@juit/pgproxy-types@1.0.35(transitive)

• Updated@juit/pgproxy-types@1.1.0