Merge pull request #86 from malthe/name-transform

Column name transformation

Author: malthe

CHANGES.md

@@ -1,3 +1,13 @@
+In the next release ...
+
+- 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 `query` method now accepts a `QueryParameter` object as the
+  first value, in addition to the query string, making it easier to
+  make a query with additional configuration.
+
 1.6.0 (2023-12-13)
 ------------------
 

README.md

@@ -260,6 +260,13 @@ The copy commands are not supported.
    pool.use(...)
    ```
 
+2. _How do I convert column names to camelcase?_ Use the `transform` option:
+
+   ```typescript
+   const camelcase = (s: string) => s.replace(/(_\w)/g, k => k[1].toUpperCase());
+   const result = client.query({text: ..., transform: camelcase})
+   ```
+
 ## Benchmarking
 
 Use the following environment variable to run tests in "benchmark" mode.

src/client.ts

@@ -9,7 +9,7 @@ import * as logger from './logging';
 
 import { postgresqlErrorCodes } from './errors';
 import { Queue } from './queue';
-import { Query } from './query';
+import { Query, QueryParameter } from './query';
 
 import { ConnectionOptions, TLSSocket, connect as tls, createSecureContext } from 'tls';
 
@@ -515,10 +515,11 @@ export class Client {
     }
 
     prepare<T = ResultRecord>(
-        text: string,
+        text: QueryParameter | string,
         name?: string,
         types?: DataType[]): Promise<PreparedStatement<T>> {
 
+        const query = typeof text === 'string' ? {text} : text;
         const providedNameOrGenerated = name || (
             (this.config.preparedStatementPrefix ||
                 defaults.preparedStatementPrefix) + (
@@ -529,7 +530,7 @@ export class Client {
             (resolve, reject) => {
                 const errorHandler: ErrorHandler = (error) => reject(error);
                 this.errorHandlerQueue.push(errorHandler);
-                this.writer.parse(providedNameOrGenerated, text, types || []);
+                this.writer.parse(providedNameOrGenerated, query.text, types || query.types || []);
                 this.writer.describe(providedNameOrGenerated, 'S');
                 this.preFlightQueue.push({
                     descriptionHandler: (description: RowDescription) => {
@@ -557,7 +558,7 @@ export class Client {
                                 format?: DataFormat | DataFormat[],
                                 streams?: Record<string, Writable>,
                             ) => {
-                                const result = makeResult<T>();
+                                const result = makeResult<T>(query?.transform);
                                 result.nameHandler(description.names);
                                 const info = {
                                     handler: {
@@ -568,11 +569,11 @@ export class Client {
                                 };
                                 this.bindAndExecute(info, {
                                     name: providedNameOrGenerated,
-                                    portal: portal || '',
-                                    format: format || DataFormat.Binary,
+                                    portal: portal || query.portal || '',
+                                    format: format || query.format || DataFormat.Binary,
                                     values: values || [],
                                     close: false
-                                }, types);
+                                }, types || query.types);
 
                                 return result.iterator
                             }
@@ -588,23 +589,35 @@ export class Client {
             });
     }
 
+    /**
+     * Send a query to the database.
+     *
+     * The query string is given as the first argument, or pass a {@link QueryParameter}
+     * object which provides more control.
+     *
+     * @param text - The query string, or pass a {@link QueryParameter}
+     *     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: string,
+        text: QueryParameter | string,
         values?: any[],
         types?: DataType[],
         format?: DataFormat | DataFormat[],
         streams?: Record<string, Writable>):
         ResultIterator<T> {
-        const query =
-            (typeof text === 'string') ?
-                new Query(
-                    text,
-                    values, {
-                    types: types,
-                    format: format,
-                    streams: streams,
-                }) :
-                text;
+        const query = new Query(
+            text,
+            values, {
+            types: types,
+            format: format,
+            streams: streams,
+        });
         return this.execute<T>(query);
     }
 
@@ -651,11 +664,11 @@ export class Client {
         const text = query.text;
         const values = query.values || [];
         const options = query.options;
-        const format = options ? options.format : undefined;
-        const types = options ? options.types : undefined;
-        const streams = options ? options.streams : undefined;
-        const portal = (options ? options.portal : undefined) || '';
-        const result = makeResult<T>();
+        const format = options?.format;
+        const types = options?.types;
+        const streams = options?.streams;
+        const portal = options?.portal || '';
+        const result = makeResult<T>(options?.transform);
 
         const descriptionHandler = (description: RowDescription) => {
             result.nameHandler(description.names);
@@ -667,7 +680,7 @@ export class Client {
         };
 
         if (values && values.length) {
-            const name = (options ? options.name : undefined) || (
+            const name = (options?.name) || (
                 (this.config.preparedStatementPrefix ||
                     defaults.preparedStatementPrefix) + (
                     this.nextPreparedStatementId++

src/query.ts

@@ -5,17 +5,46 @@ import {
 } from './types';
 
 export interface QueryOptions {
+    /** The query name. */
     readonly name: string;
+    /** Whether to use the default portal (i.e. unnamed) or provide a name. */
     readonly portal: string;
+    /** Allows making the database native type explicit for some or all columns. */
     readonly types: DataType[];
+    /** Whether column data should be transferred using text or binary mode. */
     readonly format: DataFormat | DataFormat[];
+    /** A mapping from column name to a socket, e.g. an open file. */
     readonly streams: Record<string, Writable>;
+    /** Allows the transformation of column names as returned by the database. */
+    readonly transform: (name: string) => string;
 }
 
+/**
+ * A query parameter can be used in place of a query text as the first argument
+ * to the {@link Client.query} method.
+ * @interface
+ */
+export type QueryParameter = Partial<QueryOptions> & { text: string };
+
+/**
+ * A complete query object, ready to send to the database.
+ */
 export class Query {
+    public readonly text: string;
+    public readonly values?: any[];
+    public readonly options?: Partial<QueryOptions>;
+
     constructor(
-        public readonly text: string,
-        public readonly values?: any[],
-        public readonly options?: Partial<QueryOptions>
-    ) { }
+        text: QueryParameter | string,
+        values?: any[],
+        options?: Partial<QueryOptions>
+    ) {
+        this.values = values;
+        this.options = options;
+        if (typeof text === 'string') {
+            this.text = text;
+        } else {
+            ({ text: this.text, ...this.options } = {...this.options, ...text});
+        }
+    }
 }

src/result.ts

@@ -7,7 +7,7 @@ type Callback<T> = (item: T) => void;
 type ResultHandler = (resolve: Callback<Resolution>, reject: Callback<Error | DatabaseError>) => void;
 
 /** The default result type, used if no generic type parameter is specified. */
-export type ResultRecord = Record<string, any>
+export type ResultRecord<T = any> = Record<string, T>;
 
 
 function makeRecord<T>(names: string[], data: ReadonlyArray<any>): T {
@@ -209,7 +209,7 @@ export type NameHandler = Callback<string[]>;
 
 ResultIterator.prototype.constructor = Promise
 
-export function makeResult<T>() {
+export function makeResult<T>(transform?: (name: string) => string) {
     let dataHandler: DataHandler | null = null;
 
     const names: string[] = [];
@@ -232,6 +232,9 @@ export function makeResult<T>() {
 
     const nameHandler = (ns: string[]) => {
         names.length = 0;
+        if (transform) {
+            ns = ns.map(transform);
+        }
         names.push(...ns);
     }
 

test/client.test.ts

@@ -239,16 +239,11 @@ describe('Query', () => {
         expect(result.rows.length).toEqual(1);
     });
 
-    testWithClient('Prepared statement', async (client) => {
-        const count = 5;
-        expect.assertions(count * 2);
-        await client.query('prepare test (int) as select $1');
-        for (let i = 0; i < count; i++) {
-            const result = await client.query('execute test(1)');
-            const rows = result.rows;
-            expect(rows.length).toEqual(1);
-            expect(rows[0]).toEqual([1]);
-        }
+    testWithClient('Name transform', async (client) => {
+        expect.assertions(1);
+        const query = {text: 'select 1 as foo', transform: (s: string) => s.toUpperCase()};
+        const result = await client.query(query);
+        expect(result.names).toEqual(['FOO']);
     });
 
     testWithClient('Listen/notify', async (client) => {
@@ -487,6 +482,19 @@ describe('Query', () => {
             await stmt.close();
         });
 
+    testWithClient(
+        'Prepare and execute (SELECT)',
+        async (client) => {
+            const query = {text: 'select $1::int as i', transform: (s: string) => s.toUpperCase()};
+            const stmt = await client.prepare(query);
+            await expect(stmt.execute([1])).resolves.toEqual(
+                { names: ['I'], rows: [[1]], status: 'SELECT 1' }
+            );
+            const result = await stmt.execute([2]);
+            expect(result.rows).toEqual([[2]]);
+            await stmt.close();
+        });
+
     testWithClient(
         'Prepare and execute (INSERT)',
         async (client) => {