Query result (and related objects) is now generic on the row type

Author: malthe

.eslintrc.json

@@ -15,5 +15,6 @@
         "@typescript-eslint"
     ],
     "rules": {
+        "@typescript-eslint/no-explicit-any": 0
     }
 }

CHANGES.md

@@ -1,5 +1,16 @@
 In next release ...
 
+- The `Value` type has been replaced with `any`, motivated by the new
+  generic result type as well as the possibility to implement custom
+  value readers which could return objects of any type.
+
+- Query results are now generic with typing support for the `get`
+  method on each row.
+
+  In addition, a new `map` method now produces records which conform
+  to the specified type. This method is available on all of the result
+  objects.
+
 - Use lookup table to optimize `get` method.
 
 - The `connect` method now returns a boolean status of whether the

README.md

@@ -35,14 +35,17 @@ The client uses an async/await-based programming model.
 ```typescript
 import { Client } from 'ts-postgres';
 
+interface Greeting {
+    message: string;
+}
+
 async function main() {
     const client = new Client();
     await client.connect();
 
     try {
-        // Querying the client returns a query result promise
-        // which is also an asynchronous result iterator.
-        const result = client.query(
+        // The query method is generic on the result row.
+        const result = client.query<Greeting>(
             "SELECT 'Hello ' || $1 || '!' AS message",
             ['world']
         );
@@ -112,9 +115,14 @@ const query = new Query(
     "SELECT 'Hello ' || $1 || '!' AS message",
     ['world']
 );
-const result = await client.execute(query);
+const result = await client.execute<Greeting>(query);
 ```
 
+If the row type is omitted, it defaults to `Record<string, any>`, but
+providing a type ensures that the row values are typed, both when
+accessed via the `get` method or if the row is mapped to a record
+using the `map` method.
+
 ### Passing query parameters
 
 Query parameters use the format `$1`, `$2` etc.

package-lock.json

@@ -15,9 +15,8 @@ import { ConnectionOptions, TLSSocket, connect as tls, createSecureContext } fro
 
 import {
     DataHandler,
-    Result as _Result,
-    ResultIterator as _ResultIterator,
-    ResultRow as _ResultRow,
+    ResultIterator,
+    ResultRecord,
     makeResult
 } from './result';
 
@@ -37,19 +36,11 @@ import {
 import {
     DataFormat,
     DataType,
-    Row,
-    Value,
     ValueTypeReader
 } from './types';
 
 import { md5 } from './utils';
 
-export type Result = _Result<Value>;
-
-export type ResultIterator = _ResultIterator<Value>;
-
-export type ResultRow = _ResultRow<Value>;
-
 export type Connect = Error | null;
 
 export type End = void;
@@ -67,7 +58,7 @@ export interface ClientNotice extends DatabaseError {
 
 export interface DataTypeError {
     dataType: DataType,
-    value: Value
+    value: any
 }
 
 export enum SSLMode {
@@ -100,14 +91,14 @@ export interface Notification {
     payload?: string
 }
 
-export interface PreparedStatement {
+export interface PreparedStatement<T = ResultRecord> {
     close: (portal?: string) => Promise<void>;
     execute: (
-        values?: Value[],
+        values?: any[],
         portal?: string,
         format?: DataFormat | DataFormat[],
         streams?: Record<string, Writable>,
-    ) => ResultIterator
+    ) => ResultIterator<T>
 }
 
 type Callback<T> = (data: T) => void;
@@ -127,7 +118,7 @@ type Event = (
 type CloseHandler = () => void;
 
 interface RowDataHandler {
-    callback: DataHandler<Row>,
+    callback: DataHandler<any[]>,
     streams: Record<string, Writable>,
 }
 
@@ -154,7 +145,7 @@ interface Bind {
     name: string;
     format: DataFormat | DataFormat[]
     portal: string;
-    values: Value[],
+    values: any[],
     close: boolean
 }
 
@@ -188,7 +179,7 @@ export class Client {
     private expect = 5;
     private stream = new Socket();
     private mustDrain = false;
-    private activeRow: Array<Value> | null = null;
+    private activeRow: Array<any> | null = null;
 
     private bindQueue = new Queue<RowDataHandlerInfo | null>();
     private closeHandlerQueue = new Queue<CloseHandler | null>();
@@ -513,18 +504,18 @@ export class Client {
         }
     }
 
-    prepare(
+    prepare<T = ResultRecord>(
         text: string,
         name?: string,
-        types?: DataType[]): Promise<PreparedStatement> {
+        types?: DataType[]): Promise<PreparedStatement<T>> {
 
         const providedNameOrGenerated = name || (
             (this.config.preparedStatementPrefix ||
                 defaults.preparedStatementPrefix) + (
                 this.nextPreparedStatementId++
             ));
 
-        return new Promise<PreparedStatement>(
+        return new Promise<PreparedStatement<T>>(
             (resolve, reject) => {
                 const errorHandler: ErrorHandler = (error) => reject(error);
                 this.errorHandlerQueue.push(errorHandler);
@@ -551,12 +542,12 @@ export class Client {
                                 );
                             },
                             execute: (
-                                values?: Value[],
+                                values?: any[],
                                 portal?: string,
                                 format?: DataFormat | DataFormat[],
                                 streams?: Record<string, Writable>,
                             ) => {
-                                const result = makeResult<Value>();
+                                const result = makeResult<T>();
                                 result.nameHandler(description.names);
                                 const info = {
                                     handler: {
@@ -587,13 +578,13 @@ export class Client {
             });
     }
 
-    query(
+    query<T = ResultRecord>(
         text: string,
-        values?: Value[],
+        values?: any[],
         types?: DataType[],
         format?: DataFormat | DataFormat[],
         streams?: Record<string, Writable>):
-        ResultIterator {
+        ResultIterator<T> {
         const query =
             (typeof text === 'string') ?
                 new Query(
@@ -604,7 +595,7 @@ export class Client {
                     streams: streams,
                 }) :
                 text;
-        return this.execute(query);
+        return this.execute<T>(query);
     }
 
     private bindAndExecute(
@@ -642,7 +633,7 @@ export class Client {
         this.send();
     }
 
-    execute(query: Query): ResultIterator {
+    execute<T = ResultRecord>(query: Query): ResultIterator<T> {
         if (this.closed && !this.connecting) {
             throw new Error('Connection is closed.');
         }
@@ -654,7 +645,7 @@ export class Client {
         const types = options ? options.types : undefined;
         const streams = options ? options.streams : undefined;
         const portal = (options ? options.portal : undefined) || '';
-        const result = makeResult<Value>();
+        const result = makeResult<T>();
 
         const descriptionHandler = (description: RowDescription) => {
             result.nameHandler(description.names);
@@ -877,7 +868,7 @@ export class Client {
 
                     if (row === null) {
                         const count = buffer.readInt16BE(start);
-                        row = new Array<Value>(count);
+                        row = new Array<any>(count);
                     }
 
                     const startRowData = start + 2;

src/client.ts

@@ -1,4 +1,5 @@
 export * from './client';
 export * from './types';
 export * from './query';
+export * from './result';
 export { DatabaseError } from './protocol';

src/index.ts

@@ -7,11 +7,8 @@ import { sum } from './utils';
 import {
     arrayDataTypeMapping,
     isPoint,
-    ArrayValue,
     DataFormat,
     DataType,
-    Primitive,
-    Value,
     ValueTypeReader
 } from './types';
 
@@ -278,7 +275,7 @@ export function readRowDescription(
 
 export function readRowData(
     buffer: Buffer,
-    row: Array<Value>,
+    row: Array<any>,
     columnSpecification: Uint32Array,
     encoding: BufferEncoding,
     types: ReadonlyMap<DataType, ValueTypeReader> | null,
@@ -309,7 +306,7 @@ export function readRowData(
         const remaining = end - bufferLength;
         const partial = remaining > 0;
 
-        let value: Value = null;
+        let value: any = null;
 
         if (start < end) {
             const spec = columnSpecification[j];
@@ -449,7 +446,7 @@ export function readRowData(
                         let offset = start;
 
                         const readArray = (size: number) => {
-                            const array: ArrayValue<Primitive> =
+                            const array: any[] =
                                 new Array(size);
 
                             for (let j = 0; j < size; j++) {
@@ -476,7 +473,7 @@ export function readRowData(
                             offset += 8;
                             value = readArray(size);
                         } else {
-                            const arrays: ArrayValue<Primitive>[] =
+                            const arrays: any[][] =
                                 new Array(dimCount);
                             const dims = new Uint32Array(dimCount);
 
@@ -624,7 +621,7 @@ export class Reader {
     }
 
     readRowData(
-        row: Array<Value>,
+        row: any[],
         columnSpecification: Uint32Array,
         encoding: BufferEncoding,
         types: ReadonlyMap<DataType, ValueTypeReader> | null,
@@ -654,7 +651,7 @@ export class Writer {
         name: string,
         portal: string,
         format: DataFormat | DataFormat[] = DataFormat.Binary,
-        values: Value[] = [],
+        values: any[] = [],
         types: DataType[] = []) {
         // We silently ignore any mismatch here, assuming that the
         // query will fail and make the error evident.
@@ -690,7 +687,7 @@ export class Writer {
             }
         };
 
-        const addBinaryValue = (value: Value, dataType: DataType): number => {
+        const addBinaryValue = (value: any, dataType: DataType): number => {
             let size = -1;
             const setSize = reserve(SegmentType.Int32BE);
 
@@ -836,7 +833,7 @@ export class Writer {
         };
 
         const addBinaryArray = (
-            value: Value[],
+            value: any[],
             dataType: DataType): number => {
             const setDimCount = reserve(SegmentType.Int32BE);
             add(SegmentType.Int32BE, 1);
@@ -845,7 +842,7 @@ export class Writer {
             let bytes = 12;
             let dimCount = 0;
 
-            const go = (level: number, value: Value[]) => {
+            const go = (level: number, value: any[]) => {
                 const length = value.length;
                 if (length === 0) return;
 
@@ -874,7 +871,7 @@ export class Writer {
         }
 
         const getTextFromValue = (
-            value: Value,
+            value: any,
             dataType: DataType): null | string | string[] => {
             if (value === null) return null;
 
@@ -929,7 +926,7 @@ export class Writer {
         }
 
         const getTextFromArray = (
-            value: Value[],
+            value: any[],
             dataType: DataType): string[] => {
             const strings: string[] = [];
             strings.push('{');

src/protocol.ts

@@ -2,7 +2,6 @@ import { Writable } from 'stream';
 import {
     DataFormat,
     DataType,
-    Value
 } from './types';
 
 export interface QueryOptions {
@@ -16,7 +15,7 @@ export interface QueryOptions {
 export class Query {
     constructor(
         public readonly text: string,
-        public readonly values?: Value[],
+        public readonly values?: any[],
         public readonly options?: Partial<QueryOptions>
     ) { }
 }