Add rowmode and changed default bigint serialization to number

Author: Georg Traar

.prettierrc

@@ -2,5 +2,12 @@
   "semi": true,
   "singleQuote": true,
   "trailingComma": "es5",
-  "printWidth": 120
+  "printWidth": 120,
+  "tabWidth": 2,
+  "useTabs": false,
+  "bracketSpacing": true,
+  "arrowParens": "always",
+  "endOfLine": "lf",
+  "quoteProps": "as-needed",
+  "proseWrap": "preserve"
 }

README.md

@@ -76,18 +76,21 @@ The `CrateDBClient` can be configured with either environment variables or direc
 
 #### Configuration Options
 
-| Option             | Type                    | Default Value                                  | Description                                                  |
-| ------------------ | ----------------------- | ---------------------------------------------- | ------------------------------------------------------------ |
-| `user`             | `string`                | `'crate'` or `process.env.CRATEDB_USER`        | Database user.                                               |
-| `password`         | `string` or `null`      | `''` or `process.env.CRATEDB_PASSWORD`         | Database password.                                           |
-| `host`             | `string`                | `'localhost'` or `process.env.CRATEDB_HOST`    | Database host.                                               |
-| `port`             | `number`                | `4200` or `process.env.CRATEDB_PORT`           | Database port.                                               |
-| `defaultSchema`    | `string`                | `null` or `process.env.CRATEDB_DEFAULT_SCHEMA` | Default schema for queries.                                  |
-| `connectionString` | `string`                | `null`                                         | Connection string, e.g., `https://user:password@host:port/`. |
-| `ssl`              | `object` or `null`      | `null`                                         | SSL configuration;                                           |
-| `keepAlive`        | `boolean`               | `true`                                         | Enables HTTP keep-alive for persistent connections.          |
-| `maxConnections`   | `number`                | `20`                                           | Limits the maximum number of concurrent connections.         |
-| `deserialization`  | `DeserializationConfig` | see deserialization section                    | Controls deserialization behaviour                           |
+| Option     | Type               | Default Value                           | Description                          |
+| ---------- | ------------------ | --------------------------------------- | ------------------------------------ |
+| `user`     | `string`           | `'crate'` or `process.env.CRATEDB_USER` | Database user.                       |
+| `password` | `string` or `null` | `''` or `process.env.CRATEDB_PASSWORD`  | Database password.                   |
+| `jwt`      | `string \| null`   | `null`                                  | JWT token for Bearer authentication. |
+
+| `host` | `string` | `'localhost'` or `process.env.CRATEDB_HOST` | Database host. |
+| `port` | `number` | `4200` or `process.env.CRATEDB_PORT` | Database port. |
+| `defaultSchema` | `string` | `null` or `process.env.CRATEDB_DEFAULT_SCHEMA` | Default schema for queries. |
+| `connectionString` | `string` | `null` | Connection string, e.g., `https://user:password@host:port/`. |
+| `ssl` | `object` or `null` | `null` | SSL configuration; |
+| `keepAlive` | `boolean` | `true` | Enables HTTP keep-alive for persistent connections. |
+| `maxConnections` | `number` | `20` | Limits the maximum number of concurrent connections. |
+| `deserialization` | `DeserializationConfig` | `{ long: 'number', timestamp: 'date', date: 'date' }` | Controls deserialization behaviour |
+| `rowMode` | `'array' \| 'object'` | `'array'` | Controls the format of returned rows. |
 
 #### Environment Variables
 
@@ -107,13 +110,34 @@ export CRATEDB_DEFAULT_SCHEMA=doc
 
 ### General Operations
 
-#### execute(sql, [args])
+#### execute(sql, args?, config?)
 
-Execute a raw SQL query.
+Execute a SQL query with optional parameters and configuration.
 
-```js
+```typescript
+// Basic query
 await client.execute('SELECT * FROM my_table';);
-await client.execute('SELECT ?;', ['Hello World!']);
+// Parameterized query
+await client.execute('SELECT FROM my_table WHERE id = ?', [123]);
+// Query with row mode configuration
+await client.execute('SELECT FROM my_table', undefined, { rowMode: 'object' });
+```
+
+The `rowMode` configuration determines how rows are returned:
+
+- `'array'` (default): Returns rows as arrays of values
+- `'object'`: Returns rows as objects with column names as keys
+
+Example responses:
+
+```typescript
+// Basic query
+const result = await client.execute('SELECT * FROM my_table');
+console.log(result.rows); // [[1, 'Alice', 30], [2, 'Bob', 25]]
+
+// Query with row mode configuration
+const result = await client.execute('SELECT * FROM my_table', undefined, { rowMode: 'object' });
+console.log(result.rows); // [{id: 1, name: 'Alice', age: 30}, {id: 2, name: 'Bob', age: 25}]
 ```
 
 #### executeMany(sql, bulk_args)

eslint.config.js

@@ -23,4 +23,4 @@ export default [
       // (The "plugin:prettier/recommended" config normally does this.)
     },
   },
-];
+];

examples/test.js

@@ -0,0 +1,46 @@
+import http from 'http';
+import zlib from 'zlib';
+
+const requestData = JSON.stringify({
+  stmt: 'SELECT * FROM sys.summits',
+});
+
+// Compress request data using gzip
+zlib.deflate(requestData, (err, compressedData) => {
+  if (err) {
+    console.error('Compression failed:', err);
+    return;
+  }
+
+  const options = {
+    hostname: 'localhost',
+    port: 4200,
+    path: '/_sql',
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Content-Encoding': 'deflate', // Tell CrateDB the request is compressed
+      Accept: 'application/json',
+      'Accept-Encoding': 'gzip',
+    },
+  };
+
+  const req = http.request(options, (res) => {
+    let responseData = '';
+
+    res.on('data', (chunk) => {
+      responseData += chunk;
+    });
+
+    res.on('end', () => {
+      console.log('Response:', responseData);
+    });
+  });
+
+  req.on('error', (error) => {
+    console.error('Request error:', error);
+  });
+
+  req.write(compressedData); // Send gzipped request body
+  req.end();
+});

package.json

@@ -25,7 +25,9 @@
     "lint": "eslint 'src/**/*.{ts,tsx}' 'tests/**/*.{ts,tsx}'",
     "test": "vitest",
     "test:watch": "vitest --watch",
-    "ci": "npm run check-format && npm run lint && npm test && npm run build"
+    "ci": "npm run check-format && npm run lint && npm test && npm run build",
+    "release": "npm run ci && npm version",
+    "postrelease": "git push && git push --tags && npm publish"
   },
   "repository": {
     "type": "git",
@@ -63,4 +65,4 @@
   "engines": {
     "node": ">=21.0.0"
   }
-}
+}

src/CrateDBClient.ts

@@ -14,6 +14,7 @@ import {
   OptimizeOptions,
   ColumnDefinition,
   TableOptions,
+  QueryConfig,
 } from './interfaces';
 import { CrateDBError, DeserializationError, RequestError } from './utils/Error.js';
 import { StatementGenerator } from './StatementGenerator.js';
@@ -25,16 +26,17 @@ const defaultConfig: CrateDBConfig = {
   jwt: null, // JWT token for Bearer authentication
   host: process.env.CRATEDB_HOST || 'localhost',
   port: process.env.CRATEDB_PORT ? parseInt(process.env.CRATEDB_PORT, 10) : 4200, // Default CrateDB port
-  defaultSchema: process.env.CRATEDB_DEFAULT_SCHEMA || null, // Default schema for queries
   connectionString: null,
   ssl: false,
+  defaultSchema: process.env.CRATEDB_DEFAULT_SCHEMA || null, // Default schema for queries
   keepAlive: true, // Enable persistent connections by default
   maxConnections: 20,
   deserialization: {
-    long: 'bigint',
+    long: 'number',
     timestamp: 'date',
     date: 'date',
   },
+  rowMode: 'array',
 };
 
 export class CrateDBClient {
@@ -110,7 +112,7 @@ export class CrateDBClient {
     }
   }
 
-  async execute(stmt: string, args?: unknown[]): Promise<CrateDBResponse> {
+  async execute(stmt: string, args?: unknown[], config?: QueryConfig): Promise<CrateDBResponse> {
     const startRequestTime = Date.now();
     const payload = args ? { stmt, args } : { stmt };
     let body: string;
@@ -121,11 +123,16 @@ export class CrateDBClient {
       throw new RequestError(`Serialization failed: ${msg}`);
     }
 
-    const options = { ...this.httpOptions, body };
+    const options = {
+      ...this.httpOptions,
+      ...config?.httpOptions,
+      body,
+    };
 
     try {
       const response = await this._makeRequest(options);
-      return this._addDurations(startRequestTime, response) as CrateDBResponse;
+      const transformedResponse = this._transformResponse(response, config?.rowMode ?? this.cfg.rowMode);
+      return this._addDurations(startRequestTime, transformedResponse) as CrateDBResponse;
     } catch (error: unknown) {
       if (error instanceof CrateDBError || error instanceof DeserializationError) {
         throw error;
@@ -231,7 +238,7 @@ export class CrateDBClient {
   }
 
   async update(tableName: string, options: Record<string, unknown>, whereClause: string): Promise<CrateDBResponse> {
-    const { keys, values, args } = this._prepareOptions(options);
+    const { args } = this._prepareOptions(options);
     const query = StatementGenerator.update(tableName, options, whereClause);
     return this.execute(query, args);
   }
@@ -362,6 +369,41 @@ export class CrateDBClient {
     });
   }
 
+  protected _transformResponse(
+    response: CrateDBBaseResponse,
+    rowMode: 'array' | 'object' = 'object'
+  ): CrateDBBaseResponse {
+    // Return early if not transforming to object mode
+    if (rowMode !== 'object') {
+      return response;
+    }
+
+    // Create a shallow copy of the response
+    const transformedResponse = { ...response };
+
+    // Only transform if we have both rows and column names
+    if (Array.isArray(transformedResponse.rows) && Array.isArray(transformedResponse.cols)) {
+      transformedResponse.rows = transformedResponse.rows.map((row) => {
+        // Skip transformation if row is null or not an array
+        if (!Array.isArray(row)) {
+          return row;
+        }
+
+        const obj: Record<string, unknown> = {};
+        transformedResponse.cols?.forEach((col, index) => {
+          // Only set property if column name is a string
+          if (typeof col === 'string') {
+            // Preserve null/undefined values
+            obj[col] = row[index];
+          }
+        });
+        return obj;
+      });
+    }
+
+    return transformedResponse;
+  }
+
   public getConfig(): Readonly<CrateDBConfig> {
     return this.cfg;
   }

src/Cursor.ts

@@ -3,31 +3,34 @@
 import http from 'http';
 import https from 'https';
 import { CrateDBClient } from './CrateDBClient.js';
-import { CrateDBResponse, CrateDBRecord } from './interfaces.js';
-import { Serializer } from './Serializer.js';
+import { CrateDBRecord } from './interfaces.js';
+import { CrateDBError, RequestError } from './utils/Error.js';
 
 export class Cursor {
   public client: CrateDBClient;
   public sql: string;
   public cursorName: string;
   public isOpen: boolean;
   public agent: http.Agent | https.Agent;
-  public connectionOptions: http.RequestOptions;
+  private cursorOptions: http.RequestOptions;
 
   constructor(client: CrateDBClient, sql: string) {
-    this.client = client; // Reference to the CrateDBClient instance
-    this.sql = sql; // The SQL statement for the cursor
-    this.cursorName = `cursor_${Date.now()}`; // Unique cursor name
-    this.isOpen = false; // Cursor state
+    this.client = client;
+    this.sql = sql;
+    this.cursorName = `cursor_${Date.now()}`;
+    this.isOpen = false;
 
     const agentOptions = {
       keepAlive: true,
       maxSockets: 1,
     };
 
-    // Create a new agent with its own socket for this cursor
     this.agent = client.getConfig().ssl ? new https.Agent(agentOptions) : new http.Agent(agentOptions);
-    this.connectionOptions = { ...client.getHttpOptions(), agent: this.agent };
+
+    this.cursorOptions = {
+      ...client.getHttpOptions(),
+      agent: this.agent,
+    };
   }
 
   async open(): Promise<void> {
@@ -87,16 +90,24 @@ export class Cursor {
   }
 
   async _execute(sql: string): Promise<Array<CrateDBRecord>> {
-    const options = { ...this.connectionOptions, body: Serializer.serialize({ stmt: sql }) };
     try {
-      const response: CrateDBResponse = (await this.client._makeRequest(options)) as CrateDBResponse;
-      const { cols, rows, rowcount } = response;
-      return rowcount && rowcount > 0 ? this._rebuildObjects(cols || [], rows as unknown[]) : [];
-    } catch (error: unknown) {
-      if (error instanceof Error) {
-        throw new Error(`Error executing SQL: ${sql}. Details: ${error.message}`);
+      const response = await this.client.execute(sql, undefined, {
+        rowMode: 'object',
+        httpOptions: this.cursorOptions,
+      });
+
+      if (!response.rows || !response.rowcount) {
+        return [];
+      }
+
+      return response.rows as unknown as Array<Record<string, unknown>>;
+    } catch (error) {
+      if (error instanceof CrateDBError) {
+        throw error;
+      } else if (error instanceof Error) {
+        throw new RequestError(`Error executing SQL: ${sql}. Details: ${error.message}`, { cause: error });
       }
-      throw error;
+      throw new RequestError('CrateDB request failed with an unknown error');
     }
   }
 

src/interfaces.ts

@@ -1,3 +1,5 @@
+import type { RequestOptions } from 'http';
+
 export interface CrateDBConfig {
   user: string;
   password: string;
@@ -10,6 +12,7 @@ export interface CrateDBConfig {
   keepAlive: boolean;
   maxConnections: number;
   deserialization: DeserializationConfig;
+  rowMode?: 'array' | 'object';
 }
 
 export type DeserializationConfig = {
@@ -18,11 +21,17 @@ export type DeserializationConfig = {
   date: 'date' | 'number';
 };
 
+export type QueryConfig = {
+  rowMode?: 'array' | 'object';
+  httpOptions?: RequestOptions;
+};
+
 export interface CrateDBBaseResponse {
+  rows?: unknown[];
   cols?: string[];
   col_types?: number[];
-  rows?: Array<Array<unknown>>;
   duration?: number;
+  rowcount?: number;
   durations: {
     cratedb?: number;
     request: number;