Unify connection string parameters with C SDK #68

Author: gionatamettifogo

package.json

@@ -87,4 +87,4 @@
     "arrowParens": "avoid",
     "printWidth": 160
   }
-}
+}

src/drivers/connection-ws.ts

@@ -29,9 +29,9 @@ export class SQLiteCloudWebsocketConnection extends SQLiteCloudConnection {
       console.assert(!this.connected, 'Connection already established')
       if (!this.socket) {
         this.config = config
-        const connectionString = this.config.connectionString as string
-        const gatewayUrl = this.config?.gatewayUrl || `${this.config.host === 'localhost' ? 'ws' : 'wss'}://${this.config.host as string}:4000`
-        this.socket = io(gatewayUrl, { auth: { token: connectionString } })
+        const connectionstring = this.config.connectionstring as string
+        const gatewayUrl = this.config?.gatewayurl || `${this.config.host === 'localhost' ? 'ws' : 'wss'}://${this.config.host as string}:4000`
+        this.socket = io(gatewayUrl, { auth: { token: connectionstring } })
       }
       callback?.call(this, null)
     } catch (error) {

src/drivers/connection.ts

@@ -12,10 +12,10 @@ import { anonimizeCommand, getUpdateResults } from './utilities'
  * Actual connection management and communication with the server in concrete classes.
  */
 export abstract class SQLiteCloudConnection {
-  /** Parse and validate provided connectionString or configuration */
+  /** Parse and validate provided connectionstring or configuration */
   constructor(config: SQLiteCloudConfig | string, callback?: ErrorCallback) {
     if (typeof config === 'string') {
-      this.config = validateConfiguration({ connectionString: config })
+      this.config = validateConfiguration({ connectionstring: config })
     } else {
       this.config = validateConfiguration(config)
     }
@@ -68,7 +68,7 @@ export abstract class SQLiteCloudConnection {
   protected log(message: string, ...optionalParams: any[]): void {
     if (this.config.verbose) {
       message = anonimizeCommand(message)
-      console.log(`${new Date().toISOString()} ${this.config.clientId as string}: ${message}`, ...optionalParams)
+      console.log(`${new Date().toISOString()} ${this.config.clientid as string}: ${message}`, ...optionalParams)
     }
   }
 

src/drivers/database.ts

@@ -34,7 +34,7 @@ export class Database extends EventEmitter {
   constructor(config: SQLiteCloudConfig | string, mode?: number, callback?: ErrorCallback)
   constructor(config: SQLiteCloudConfig | string, mode?: number | ErrorCallback, callback?: ErrorCallback) {
     super()
-    this.config = typeof config === 'string' ? { connectionString: config } : config
+    this.config = typeof config === 'string' ? { connectionstring: config } : config
 
     // mode is optional and so is callback
     // https://github.com/TryGhost/node-sqlite3/wiki/API#new-sqlite3databasefilename--mode--callback
@@ -70,7 +70,7 @@ export class Database extends EventEmitter {
       callback?.call(this, null, this.connections[0])
     } else {
       // connect using websocket if tls is not supported or if explicitly requested
-      const useWebsocket = isBrowser || this.config?.useWebsocket || this.config?.gatewayUrl
+      const useWebsocket = isBrowser || this.config?.usewebsocket || this.config?.gatewayurl
       if (useWebsocket) {
         // socket.io transport works in both node.js and browser environments and connects via SQLite Cloud Gateway
         import('./connection-ws')

src/drivers/types.ts

@@ -9,21 +9,24 @@ export const DEFAULT_TIMEOUT = 300 * 1000
 /** Default tls connection port */
 export const DEFAULT_PORT = 9960
 
-/** Configuration for SQLite cloud connection */
+/**
+ * Configuration for SQLite cloud connection
+ * @note Options are all lowecase so they 1:1 compatible with C SDK
+ */
 export interface SQLiteCloudConfig {
   /** Connection string in the form of sqlitecloud://user:password@host:port/database?options */
-  connectionString?: string
+  connectionstring?: string
 
-  /** User name is required unless connectionString is provided */
+  /** User name is required unless connectionstring is provided */
   username?: string
   /** Password is required unless connection string is provided */
   password?: string
   /** True if password is hashed, default is false */
-  passwordHashed?: boolean
+  password_hashed?: boolean
   /** API key can be provided instead of username and password */
-  apiKey?: string
+  apikey?: string
 
-  /** Host name is required unless connectionString is provided, eg: xxx.sqlitecloud.io */
+  /** Host name is required unless connectionstring is provided, eg: xxx.sqlitecloud.io */
   host?: string
   /** Port number for tls socket */
   port?: number
@@ -36,32 +39,32 @@ export interface SQLiteCloudConfig {
   database?: string
 
   /** Create the database if it doesn't exist? */
-  createDatabase?: boolean
+  create?: boolean
   /** Database will be created in memory */
-  dbMemory?: boolean
+  memory?: boolean
   /* Enable compression */
   compression?: boolean
   /** Request for immediate responses from the server node without waiting for linerizability guarantees */
-  nonlinearizable?: boolean
+  non_linearizable?: boolean
   /** Server should send BLOB columns */
-  noBlob?: boolean
+  noblob?: boolean
   /** Do not send columns with more than max_data bytes */
-  maxData?: number
+  maxdata?: number
   /** Server should chunk responses with more than maxRows */
-  maxRows?: number
+  maxrows?: number
   /** Server should limit total number of rows in a set to maxRowset */
-  maxRowset?: number
+  maxrowset?: number
 
   /** Custom options and configurations for tls socket, eg: additional certificates */
-  tlsOptions?: tls.ConnectionOptions
+  tlsoptions?: tls.ConnectionOptions
 
   /** True if we should force use of SQLite Cloud Gateway and websocket connections, default: true in browsers, false in node.js */
-  useWebsocket?: boolean
+  usewebsocket?: boolean
   /** Url where we can connect to a SQLite Cloud Gateway that has a socket.io deamon waiting to connect, eg. wss://host:4000 */
-  gatewayUrl?: string
+  gatewayurl?: string
 
   /** Optional identifier used for verbose logging */
-  clientId?: string
+  clientid?: string
   /** True if connection should enable debug logs */
   verbose?: boolean
 }

src/drivers/utilities.ts

@@ -39,35 +39,35 @@ export function getInitializationCommands(config: SQLiteCloudConfig): string {
   // first user authentication, then all other commands
   let commands = ''
 
-  if (config.apiKey) {
-    commands = `AUTH APIKEY ${config.apiKey}; `
+  if (config.apikey) {
+    commands = `AUTH APIKEY ${config.apikey}; `
   } else {
-    commands = `AUTH USER ${config.username || ''} ${config.passwordHashed ? 'HASH' : 'PASSWORD'} ${config.password || ''}; `
+    commands = `AUTH USER ${config.username || ''} ${config.password_hashed ? 'HASH' : 'PASSWORD'} ${config.password || ''}; `
   }
 
   if (config.database) {
-    if (config.createDatabase && !config.dbMemory) {
+    if (config.create && !config.memory) {
       commands += `CREATE DATABASE ${config.database} IF NOT EXISTS; `
     }
     commands += `USE DATABASE ${config.database}; `
   }
   if (config.compression) {
     commands += 'SET CLIENT KEY COMPRESSION TO 1; '
   }
-  if (config.nonlinearizable) {
+  if (config.non_linearizable) {
     commands += 'SET CLIENT KEY NONLINEARIZABLE TO 1; '
   }
-  if (config.noBlob) {
+  if (config.noblob) {
     commands += 'SET CLIENT KEY NOBLOB TO 1; '
   }
-  if (config.maxData) {
-    commands += `SET CLIENT KEY MAXDATA TO ${config.maxData}; `
+  if (config.maxdata) {
+    commands += `SET CLIENT KEY MAXDATA TO ${config.maxdata}; `
   }
-  if (config.maxRows) {
-    commands += `SET CLIENT KEY MAXROWS TO ${config.maxRows}; `
+  if (config.maxrows) {
+    commands += `SET CLIENT KEY MAXROWS TO ${config.maxrows}; `
   }
-  if (config.maxRowset) {
-    commands += `SET CLIENT KEY MAXROWSET TO ${config.maxRowset}; `
+  if (config.maxrowset) {
+    commands += `SET CLIENT KEY MAXROWSET TO ${config.maxrowset}; `
   }
 
   return commands
@@ -202,39 +202,39 @@ export function popCallback<T extends ErrorCallback = ErrorCallback>(
 /** Validate configuration, apply defaults, throw if something is missing or misconfigured */
 export function validateConfiguration(config: SQLiteCloudConfig): SQLiteCloudConfig {
   console.assert(config, 'SQLiteCloudConnection.validateConfiguration - missing config')
-  if (config.connectionString) {
+  if (config.connectionstring) {
     config = {
       ...config,
-      ...parseConnectionString(config.connectionString),
-      connectionString: config.connectionString // keep original connection string
+      ...parseconnectionstring(config.connectionstring),
+      connectionstring: config.connectionstring // keep original connection string
     }
   }
 
   // apply defaults where needed
   config.port ||= DEFAULT_PORT
   config.timeout = config.timeout && config.timeout > 0 ? config.timeout : DEFAULT_TIMEOUT
-  config.clientId ||= 'SQLiteCloud'
+  config.clientid ||= 'SQLiteCloud'
 
   config.verbose = parseBoolean(config.verbose)
-  config.noBlob = parseBoolean(config.noBlob)
+  config.noblob = parseBoolean(config.noblob)
   config.compression = parseBoolean(config.compression)
-  config.createDatabase = parseBoolean(config.createDatabase)
-  config.nonlinearizable = parseBoolean(config.nonlinearizable)
+  config.create = parseBoolean(config.create)
+  config.non_linearizable = parseBoolean(config.non_linearizable)
   config.insecure = parseBoolean(config.insecure)
 
-  const hasCredentials = (config.username && config.password) || config.apiKey
+  const hasCredentials = (config.username && config.password) || config.apikey
   if (!config.host || !hasCredentials) {
     console.error('SQLiteCloudConnection.validateConfiguration - missing arguments', config)
-    throw new SQLiteCloudError('The user, password and host arguments or the ?apiKey= must be specified.', { errorCode: 'ERR_MISSING_ARGS' })
+    throw new SQLiteCloudError('The user, password and host arguments or the ?apikey= must be specified.', { errorCode: 'ERR_MISSING_ARGS' })
   }
 
-  if (!config.connectionString) {
+  if (!config.connectionstring) {
     // build connection string from configuration, values are already validated
     // eslint-disable-next-line @typescript-eslint/restrict-template-expressions
-    if (config.apiKey) {
-      config.connectionString = `sqlitecloud://${config.host}:${config.port}/${config.database || ''}?apiKey=${config.apiKey}`
+    if (config.apikey) {
+      config.connectionstring = `sqlitecloud://${config.host}:${config.port}/${config.database || ''}?apikey=${config.apikey}`
     } else {
-      config.connectionString = `sqlitecloud://${encodeURIComponent(config.username || '')}:${encodeURIComponent(config.password || '')}@${config.host}:${
+      config.connectionstring = `sqlitecloud://${encodeURIComponent(config.username || '')}:${encodeURIComponent(config.password || '')}@${config.host}:${
         config.port
       }/${config.database}`
     }
@@ -244,44 +244,24 @@ export function validateConfiguration(config: SQLiteCloudConfig): SQLiteCloudCon
 }
 
 /**
- * Parse connectionString like sqlitecloud://username:password@host:port/database?option1=xxx&option2=xxx
- * or sqlitecloud://host.sqlite.cloud:8860/chinook.sqlite?apiKey=mIiLARzKm9XBVllbAzkB1wqrgijJ3Gx0X5z1Agm3xBo
+ * Parse connectionstring like sqlitecloud://username:password@host:port/database?option1=xxx&option2=xxx
+ * or sqlitecloud://host.sqlite.cloud:8860/chinook.sqlite?apikey=mIiLARzKm9XBVllbAzkB1wqrgijJ3Gx0X5z1Agm3xBo
  * into its basic components.
  */
-export function parseConnectionString(connectionString: string): SQLiteCloudConfig {
+export function parseconnectionstring(connectionstring: string): SQLiteCloudConfig {
   try {
     // The URL constructor throws a TypeError if the URL is not valid.
     // in spite of having the same structure as a regular url
     // protocol://username:password@host:port/database?option1=xxx&option2=xxx)
     // the sqlitecloud: protocol is not recognized by the URL constructor in browsers
     // so we need to replace it with https: to make it work
-    const knownProtocolUrl = connectionString.replace('sqlitecloud:', 'https:')
+    const knownProtocolUrl = connectionstring.replace('sqlitecloud:', 'https:')
     const url = new URL(knownProtocolUrl)
-    const options: { [key: string]: string } = {}
-
-    // properties that are mixed case in the connection string should be accepted even if the
-    // customer mistakenly write them in camelCase or kebab-case or whateverTheCase
-    const mixedCaseProperties = [
-      'connectionString',
-      'passwordHashed',
-      'apiKey',
-      'createDatabase',
-      'dbMemory',
-      'compression',
-      'noBlob',
-      'maxData',
-      'maxRows',
-      'maxRowset',
-      'tlsOptions',
-      'useWebsocket',
-      'gatewayUrl',
-      'clientId'
-    ]
 
+    // all lowecase options
+    const options: { [key: string]: string } = {}
     url.searchParams.forEach((value, key) => {
-      let normalizedKey = key.toLowerCase().replaceAll('-', '').replaceAll('_', '')
-      const mixedCaseKey = mixedCaseProperties.find(mixedCaseProperty => mixedCaseProperty.toLowerCase() == normalizedKey)
-      options[mixedCaseKey || normalizedKey] = value
+      options[key.toLowerCase().replaceAll('-', '_')] = value
     })
 
     const config: SQLiteCloudConfig = {
@@ -292,10 +272,10 @@ export function parseConnectionString(connectionString: string): SQLiteCloudConf
       ...options
     }
 
-    // either you use an apiKey or username and password
-    if (config.apiKey) {
+    // either you use an apikey or username and password
+    if (config.apikey) {
       if (config.username || config.password) {
-        console.warn('SQLiteCloudConnection.parseConnectionString - apiKey and username/password are both specified, using apiKey')
+        console.warn('SQLiteCloudConnection.parseconnectionstring - apikey and username/password are both specified, using apikey')
       }
       delete config.username
       delete config.password
@@ -308,7 +288,7 @@ export function parseConnectionString(connectionString: string): SQLiteCloudConf
 
     return config
   } catch (error) {
-    throw new SQLiteCloudError(`Invalid connection string: ${connectionString}`)
+    throw new SQLiteCloudError(`Invalid connection string: ${connectionstring}`)
   }
 }
 
@@ -319,3 +299,11 @@ export function parseBoolean(value: string | boolean | null | undefined): boolea
   }
   return value ? true : false
 }
+
+/** Returns true if value is 1 or true */
+export function parseBooleanToZeroOne(value: string | boolean | null | undefined): 0 | 1 {
+  if (typeof value === 'string') {
+    return value.toLowerCase() === 'true' || value === '1' ? 1 : 0
+  }
+  return value ? 1 : 0
+}

src/index.ts

@@ -12,4 +12,4 @@ export { Statement } from './drivers/statement'
 export { SQLiteCloudConnection } from './drivers/connection'
 export { type SQLiteCloudConfig, type SQLCloudRowsetMetadata, SQLiteCloudError, type ResultsCallback, type ErrorCallback } from './drivers/types'
 export { SQLiteCloudRowset, SQLiteCloudRow } from './drivers/rowset'
-export { escapeSqlParameter, prepareSql, parseConnectionString, validateConfiguration } from './drivers/utilities'
+export { escapeSqlParameter, prepareSql, parseconnectionstring, validateConfiguration } from './drivers/utilities'