Merge pull request #88 from malthe/remove-execute-plus-simplify

Remove 'execute' method; simplify 'query' and 'prepare' methods

Author: malthe

CHANGES.md

@@ -2,13 +2,16 @@ In the next release ...
 
 - The `execute` method has been removed.
 
-- The query options now supports an optional `transform` parameter which takes
-  a column name input, allowing the transformation of column names into for
-  example camelcase.
+- The querying options now include an optional `transform` property which must be
+  a function which takes a column name input, allowing the transformation of column
+  names into for example _camel-case_.
 
-- The `query` method now accepts a `Query` object as the
-  first value, in addition to the query string, making it easier to
-  make a query with additional configuration.
+- The `query` method now accepts a `Query` object as the first argument in
+  addition to a string argument, but no longer accepts any additional arguments
+  after `values`. The query options must now be provided using the query argument
+  instead.
+
+  The same change has been made to `prepare`.
 
 1.6.0 (2023-12-13)
 ------------------

src/client.ts

@@ -403,6 +403,13 @@ export class Client {
         });
     }
 
+    /** Connect to the database.
+     *
+     * @remarks
+     * Don't forget to close the connection using {@link end} before exiting.
+     *
+     * @returns The connection encryption status.
+     */
     connect(): Promise<boolean> {
         if (this.connecting) {
             throw new Error('Already connecting');
@@ -446,6 +453,9 @@ export class Client {
         return p;
     }
 
+    /** End the database connection.
+     *
+     */
     end() {
         if (this.ending) {
             throw new Error('Already ending');
@@ -514,13 +524,13 @@ export class Client {
         }
     }
 
-    prepare<T = ResultRecord>(
-        text: Query | string,
-        name?: string,
-        types?: DataType[]): Promise<PreparedStatement<T>> {
-
+    /** Prepare a statement for later execution.
+     *
+     * @returns A prepared statement object.
+     */
+    prepare<T = ResultRecord>(text: Query | string): Promise<PreparedStatement<T>> {
         const query = typeof text === 'string' ? {text} : text;
-        const providedNameOrGenerated = name || (
+        const providedNameOrGenerated = query.name || (
             (this.config.preparedStatementPrefix ||
                 defaults.preparedStatementPrefix) + (
                 this.nextPreparedStatementId++
@@ -530,7 +540,7 @@ export class Client {
             (resolve, reject) => {
                 const errorHandler: ErrorHandler = (error) => reject(error);
                 this.errorHandlerQueue.push(errorHandler);
-                this.writer.parse(providedNameOrGenerated, query.text, types || query.types || []);
+                this.writer.parse(providedNameOrGenerated, query.text, query.types || []);
                 this.writer.describe(providedNameOrGenerated, 'S');
                 this.preFlightQueue.push({
                     descriptionHandler: (description: RowDescription) => {
@@ -598,28 +608,18 @@ export class Client {
      * @param text - The query string, or pass a {@link Query}
      *     object which provides more control (including streaming values into a socket).
      * @param values - The query parameters, corresponding to $1, $2, etc.
-     * @param types - Allows making the database native type explicit for some or all
-     *     columns.
-     * @param format - Whether column data should be transferred using text or binary mode.
-     * @param streams - A mapping from column name to a socket, e.g. an open file.
      * @returns A promise for the query results.
      */
-    query<T = ResultRecord>(
-        text: Query | string,
-        values?: any[],
-        types?: DataType[],
-        format?: DataFormat | DataFormat[],
-        streams?: Record<string, Writable>):
-        ResultIterator<T> {
+    query<T = ResultRecord>(text: Query | string, values?: any[]): ResultIterator<T> {
         const query = typeof text === 'string' ? {text} : text;
 
         if (this.closed && !this.connecting) {
             throw new Error('Connection is closed.');
         }
 
-        format = format || query?.format;
-        types = types || query?.types;
-        streams = streams || query?.streams;
+        const format = query?.format;
+        const types = query?.types;
+        const streams =query?.streams;
         const portal = query?.portal || '';
         const result = makeResult<T>(query?.transform);
 

test/types.test.ts

@@ -35,9 +35,11 @@ function testType<T>(
             const query = expected !== null
                 ? getComparisonQueryFor(dataType, expression)
                 : 'select $1 is null';
-            await client.query(
-                (expected !== null) ? query + ' where $1 is not null' : query,
-                [expected], [dataType], format)
+            await client.query({
+                text: expected !== null ? query + ' where $1 is not null' : query,
+                types: [dataType],
+                format
+            }, [expected])
                 .then(
                     (result) => {
                         const rows = result.rows;
@@ -52,7 +54,7 @@ function testType<T>(
         testWithClient('Value', async (client) => {
             expect.assertions(3);
             const query = 'select ' + expression;
-            await client.query(query, [], [], format).then(
+            await client.query({text: query, format}, []).then(
                 (result) => {
                     const rows = result.rows;
                     expect(rows.length).toEqual(1);