Minor refactorings, types, etc

gionatamettifogo · gionatamettifogo · commit dbbcde865cb7 · 2023-11-16T09:18:02.000+01:00
diff --git a/README.md b/README.md
@@ -20,17 +20,19 @@ npm install sqlitecloud-js
 ```ts
 import { Database } from 'sqlitecloud-js'
 
-let name = 'Ava Jones'
+let database = new Database('sqlitecloud://user:password@xxx.sqlite.cloud:8860/chinook.db')
 
-let results = await database.sql`SELECT * FROM people WHERE name = ${name}`
-// => returns [{ id: 5, name: 'Ava Jones', age: 22, hobby: 'Time traveling' }]
+let name = 'Breaking The Rules'
+
+let results = await database.sql`SELECT * FROM tracks WHERE name = ${name}`
+// => returns [{ AlbumId: 1, Name: 'Breaking The Rules', Composer: 'Angus Young... }]
 ```
 
 Use `Database.sql` for executing both your prepared statements and plain SQL queries asynchronously. This method returns an array of rows for SELECT queries and supports the standard syntax for UPDATE, INSERT, and DELETE.
 
 We aim for full compatibility with the established [sqlite3](https://www.npmjs.com/package/sqlite3) API, with the primary distinction being that our driver connects to SQLiteCloud databases. This allows you to migrate your local SQLite databases to the cloud while continuing to use your existing codebase.
 
-The package is developed entirely in TypeScript and is fully compatible with JavaScript, without requiring any native libraries. This makes it a straightforward and effective tool for managing cloud-based databases in a familiar SQLite environment.
+The package is developed entirely in TypeScript and is fully compatible with JavaScript. It doesn't require any native libraries. This makes it a straightforward and effective tool for managing cloud-based databases in a familiar SQLite environment.
 
 ## API
 
diff --git a/src/connection.ts b/src/connection.ts
@@ -8,6 +8,7 @@ import lz4 from 'lz4'
 import { SQLiteCloudConfig, SQLCloudRowsetMetadata, SQLiteCloudError, SQLiteCloudDataTypes, ErrorCallback, ResultsCallback } from './types'
 import { SQLiteCloudRowset } from './rowset'
 import { parseConnectionString, parseBoolean } from './utilities'
+import { OperationsQueue } from './queue'
 
 /**
  * The server communicates with clients via commands defined
@@ -157,15 +158,15 @@ export class SQLiteCloudConnection {
   }
 
   /* Opens a connection with the server and sends the initialization commands. Will throw in case of errors. */
-  public async connect(callback?: ErrorCallback) {
+  public connect(callback?: ErrorCallback): this {
     if (this.socket) {
       callback?.call(this, null)
-      return
+      return this
     }
 
     this.operations.enqueue(done => {
       // connect to tls socket, initialize connection, setup event handlers
-      let client: tls.TLSSocket = tls.connect(this.config.port as number, this.config.host, this.config.tlsOptions, () => {
+      const client: tls.TLSSocket = tls.connect(this.config.port as number, this.config.host, this.config.tlsOptions, () => {
         if (!client.authorized) {
           this.log('Connection was not authorized', client.authorizationError)
           this.close()
@@ -199,13 +200,15 @@ export class SQLiteCloudConnection {
 
     // send initialization commands (will be enqued in the operations queue)
     const commands = this.initializationCommands
-    this.sendCommands(commands, (error, _results) => {
+    this.sendCommands(commands, error => {
       callback?.call(this, error)
     })
+
+    return this
   }
 
   /** Will send a command and return the resulting rowset or result or throw an error */
-  public sendCommands<T = SQLiteCloudRowset>(commands: string, callback?: ResultsCallback) {
+  public sendCommands(commands: string, callback?: ResultsCallback): this {
     this.operations.enqueue(done => {
       // connection needs to be established?
       if (!this.socket) {
@@ -308,14 +311,18 @@ export class SQLiteCloudConnection {
         finish?.call(this, new SQLiteCloudError('Socket error', { cause: error }))
       })
     })
+
+    return this
   }
 
   /** Disconnect from server, release connection. */
-  public close() {
+  public close(): this {
     if (this.socket) {
       this.socket.destroy()
     }
+    this.operations.clear()
     this.socket = undefined
+    return this
   }
 }
 
@@ -508,7 +515,7 @@ function parseRowsetChunks(buffers: Buffer[]) {
 }
 
 /** Pop one or more space separated integers from beginning of buffer, move buffer forward */
-function popIntegers(buffer: Buffer, numberOfIntegers: number = 1): { data: number[]; fwdBuffer: Buffer } {
+function popIntegers(buffer: Buffer, numberOfIntegers = 1): { data: number[]; fwdBuffer: Buffer } {
   const data: number[] = []
   for (let i = 0; i < numberOfIntegers; i++) {
     const spaceIndex = buffer.indexOf(' ')
@@ -584,42 +591,3 @@ function formatCommand(command: string): string {
   const commandLength = Buffer.byteLength(command, 'utf-8')
   return `+${commandLength} ${command}`
 }
-
-//
-// OperationsQueue is used to linearize operations on the connection
-//
-
-type OperationCallback = (error?: Error) => void
-type Operation = (done: OperationCallback) => void
-
-class OperationsQueue {
-  private queue: Operation[] = []
-  private isProcessing = false
-
-  /** Add operations to the queue, process immediately if possible, else wait for previous operations to complete */
-  enqueue(operation: Operation) {
-    this.queue.push(operation)
-    if (!this.isProcessing) {
-      this.processNext()
-    }
-  }
-
-  /** Process the next operation in the queue */
-  private processNext() {
-    if (this.queue.length === 0) {
-      this.isProcessing = false
-      return
-    }
-
-    this.isProcessing = true
-    const operation = this.queue.shift()
-    operation?.(error => {
-      if (error) {
-        console.warn('OperationQueue.processNext - error in operation', error)
-      }
-
-      // process the next operation in the queue
-      this.processNext()
-    })
-  }
-}
diff --git a/src/database.ts b/src/database.ts
@@ -7,6 +7,9 @@
 // https://github.com/TryGhost/node-sqlite3
 // https://github.com/TryGhost/node-sqlite3/blob/master/lib/sqlite3.d.ts
 
+/* eslint-disable @typescript-eslint/no-unused-vars */
+/* eslint-disable @typescript-eslint/explicit-module-boundary-types */
+
 import { SQLiteCloudConnection } from './connection'
 import { SQLiteCloudRowset } from './rowset'
 import { SQLiteCloudConfig, SQLiteCloudError, RowCountCallback, SQLiteCloudArrayType } from './types'
@@ -29,7 +32,8 @@ export class Database {
     const connection = new SQLiteCloudConnection(this.config)
     this.connections = [connection]
 
-    this.getConnection((error, _connection) => {
+    // get a connection for the only purpose of opening the database
+    this.getConnection(error => {
       if (error) {
         this.handleError(null, error, callback)
       } else {
@@ -133,7 +137,7 @@ export class Database {
   }
 
   /** Set a configuration option for the database */
-  public configure(_option: any, _value: any): this {
+  public configure(_option: string, _value: any): this {
     // https://github.com/TryGhost/node-sqlite3/wiki/API#configureoption-value
     return this
   }
@@ -272,7 +276,7 @@ export class Database {
           } else {
             if (rowset && rowset instanceof SQLiteCloudRowset) {
               if (callback) {
-                for (const row of rowset as SQLiteCloudRowset) {
+                for (const row of rowset) {
                   callback.call(this, null, row)
                 }
               }
@@ -355,13 +359,14 @@ export class Database {
    * and an error occurred, an error event with the error object as the only parameter
    * will be emitted on the database object.
    */
-  public loadExtension(_path: string, callback?: ErrorCallback) {
+  public loadExtension(_path: string, callback?: ErrorCallback): this {
     // TODO sqlitecloud-js / implement database loadExtension #17
     if (callback) {
       callback.call(this, new Error('Database.loadExtension - Not implemented'))
     } else {
       this.emitEvent('error', new Error('Database.loadExtension - Not implemented'))
     }
+    return this
   }
 
   /**
diff --git a/src/queue.ts b/src/queue.ts
@@ -0,0 +1,44 @@
+//
+// queue.ts - OperationsQueue is used to linearize operations on the connection
+//
+
+type OperationCallback = (error?: Error) => void
+type Operation = (done: OperationCallback) => void
+
+export class OperationsQueue {
+  private queue: Operation[] = []
+  private isProcessing = false
+
+  /** Add operations to the queue, process immediately if possible, else wait for previous operations to complete */
+  public enqueue(operation: Operation) {
+    this.queue.push(operation)
+    if (!this.isProcessing) {
+      this.processNext()
+    }
+  }
+
+  /** Clear the queue */
+  public clear() {
+    this.queue = []
+    this.isProcessing = false
+  }
+
+  /** Process the next operation in the queue */
+  private processNext() {
+    if (this.queue.length === 0) {
+      this.isProcessing = false
+      return
+    }
+
+    this.isProcessing = true
+    const operation = this.queue.shift()
+    operation?.(error => {
+      if (error) {
+        console.warn('OperationQueue.processNext - error in operation', error)
+      }
+
+      // process the next operation in the queue
+      this.processNext()
+    })
+  }
+}
diff --git a/src/rowset.ts b/src/rowset.ts
@@ -41,7 +41,7 @@ export class SQLiteCloudRowset extends Array<SQLiteCloudRow> {
     this.#data = data
 
     // adjust missing column names, duplicate column names, etc.
-    let columnNames = this.columnsNames
+    const columnNames = this.columnsNames
     for (let i = 0; i < metadata.numberOfColumns; i++) {
       if (!columnNames[i]) {
         columnNames[i] = `column_${i}`
diff --git a/src/statement.ts b/src/statement.ts
@@ -6,6 +6,8 @@ import { popCallback, prepareSql } from './utilities'
 import { Database } from './database'
 import { ErrorCallback, RowCallback, RowsCallback, RowCountCallback, ResultsCallback } from './types'
 
+/* eslint-disable @typescript-eslint/explicit-module-boundary-types */
+
 /** A statement generated by Database.prepare used to prepare SQL with ? bindings */
 export class Statement<T> {
   constructor(database: Database, sql: string, ...params: any[]) {
@@ -64,7 +66,7 @@ export class Statement<T> {
   public run(callback?: ResultsCallback<T>): this
   public run(params: any, callback?: ResultsCallback<T>): this
   public run(...params: any[]): this {
-    const { args, callback } = popCallback<RowCallback>(params || [])
+    const { args, callback } = popCallback<ResultsCallback>(params || [])
     if (args?.length > 0) {
       // apply new bindings then execute
       this.bind(...args, (error: Error) => {
diff --git a/src/utilities.ts b/src/utilities.ts
@@ -4,6 +4,10 @@
 
 import { SQLiteCloudConfig, SQLiteCloudError, SQLiteCloudDataTypes } from './types'
 
+//
+// utility methods
+//
+
 /** Takes a generic value and escapes it so it can replace ? as a binding in a prepared SQL statement */
 export function escapeSqlParameter(param: SQLiteCloudDataTypes): string {
   if (param === null || param === undefined) {
@@ -89,17 +93,18 @@ export function prepareSql(sql: string, ...params: (SQLiteCloudDataTypes | SQLit
  * as 'completeCallback'.
  */
 export function popCallback<T extends ErrorCallback = ErrorCallback>(
-  args: SQLiteCloudDataTypes[]
+  args: (SQLiteCloudDataTypes | T | ErrorCallback)[]
 ): { args: SQLiteCloudDataTypes[]; callback?: T | undefined; complete?: ErrorCallback } {
+  const remaining = args as SQLiteCloudDataTypes[]
   // at least 1 callback?
   if (args && args.length > 0 && typeof args[args.length - 1] === 'function') {
     // at least 2 callbacks?
     if (args.length > 1 && typeof args[args.length - 2] === 'function') {
-      return { args: args.slice(0, -2), callback: args[args.length - 2] as T, complete: args[args.length - 1] as T }
+      return { args: remaining.slice(0, -2), callback: args[args.length - 2] as T, complete: args[args.length - 1] as T }
     }
-    return { args: args.slice(0, -1), callback: args[args.length - 1] as T }
+    return { args: remaining.slice(0, -1), callback: args[args.length - 1] as T }
   }
-  return { args }
+  return { args: remaining }
 }
 
 /** Parse connectionString like sqlitecloud://usernam:password@host:port/database?option1=xxx&option2=xxx into its components */
diff --git a/test/database.test.ts b/test/database.test.ts
@@ -39,12 +39,18 @@ describe('database', () => {
     }
   })
 
-  afterEach(() => {
+  afterEach(done => {
     if (database) {
-      database.close()
+      database.close(error => {
+        // @ts-expect-error
+        database = undefined
+        done(error)
+      })
+    } else {
+      // @ts-expect-error
+      database = undefined
+      done()
     }
-    // @ts-expect-error
-    database = undefined
   })
 
   describe('run', () => {
@@ -243,21 +249,17 @@ describe('database', () => {
       const chinook = new Database(CHINOOK_DATABASE_URL)
       try {
         chinook.exec('SET BOGUS STATEMENT TO 1;', error => {
-          try {
-            expect(error).toBeInstanceOf(SQLiteCloudError)
-            expect(error).toMatchObject({
-              errorCode: '10002',
-              externalErrorCode: '0',
-              name: 'SQLiteCloudError',
-              offsetCode: -1,
-              message: 'Unable to find command SET BOGUS STATEMENT TO 1;'
-            })
-
-            chinook.close()
-            done()
-          } catch (error) {
-            done(error)
-          }
+          expect(error).toBeInstanceOf(SQLiteCloudError)
+          expect(error).toMatchObject({
+            errorCode: '10002',
+            externalErrorCode: '0',
+            name: 'SQLiteCloudError',
+            offsetCode: -1,
+            message: 'Unable to find command SET BOGUS STATEMENT TO 1;'
+          })
+
+          chinook.close()
+          done()
         })
       } catch (error) {
         done(error)
@@ -266,6 +268,29 @@ describe('database', () => {
   })
 
   describe('sql (async)', () => {
+    it('should select from chinook', async () => {
+      const chinook = new Database(CHINOOK_DATABASE_URL)
+      let name = 'Breaking The Rules'
+      const results = await chinook.sql`SELECT * FROM tracks WHERE name = ${name}`
+      expect(results).toBeDefined()
+
+      const row = results[0]
+      expect(row).toBeDefined()
+      expect(row).toMatchObject({
+        AlbumId: 1,
+        Bytes: 8596840,
+        Composer: 'Angus Young, Malcolm Young, Brian Johnson',
+        GenreId: 1,
+        MediaTypeId: 1,
+        Milliseconds: 263288,
+        Name: 'Breaking The Rules',
+        TrackId: 12,
+        UnitPrice: 0.99
+      })
+
+      chinook.close()
+    })
+
     it('should select and return multiple rows', async () => {
       const results = await database.sql('SELECT * FROM people ORDER BY id')
       expect(results).toBeDefined()
diff --git a/test/statement.test.ts b/test/statement.test.ts
