rqlite-js 2.6.0 → 3.0.0

package/src/api/results/data-result-error.ts

@@ -0,0 +1,41 @@
+/**
+ * Class for handling RQLite data api result error
+ * @module api/results/data-result-error
+ * @see https://rqlite.io/docs/api/api/
+ */
+import { RESULT_FIELD_ERROR, RESULT_FIELD_ERROR_V2 } from './result-fields.js'
+
+/**
+ * A class that represents one data error result from an RQLite query or execute API call
+ * @see https://rqlite.io/docs/api/api/
+ */
+export default class DataResultError extends Error {
+  code: string
+
+  errorV2?: Record<string, unknown>
+
+  constructor (message: string, errorV2?: Record<string, unknown>) {
+    super(message)
+    this.name = this.constructor.name
+    this.code = this.constructor.name
+    if (errorV2) {
+      this.errorV2 = errorV2
+    }
+  }
+
+  getErrorV2 (): Record<string, unknown> | undefined {
+    return this.errorV2
+  }
+
+  toObject (): Record<string, unknown> {
+    const obj: Record<string, unknown> = { [RESULT_FIELD_ERROR]: this.message }
+    if (this.errorV2) {
+      obj[RESULT_FIELD_ERROR_V2] = this.errorV2
+    }
+    return obj
+  }
+
+  toString (): string {
+    return JSON.stringify(this.toObject())
+  }
+}

package/src/api/results/data-result.ts

@@ -0,0 +1,91 @@
+/**
+ * Class for handling single RQLite data api result
+ * @module api/results/data-result
+ * @see https://rqlite.io/docs/api/api/
+ * @see module:api/results/result-fields
+ */
+import {
+  RESULT_FIELD_COLUMNS,
+  RESULT_FIELD_LAST_INSERT_ID,
+  RESULT_FIELD_ROWS_AFFECTED,
+  RESULT_FIELD_TIME,
+  RESULT_FIELD_VALUES,
+} from './result-fields.js'
+
+export type RqliteSingleResult = {
+  [RESULT_FIELD_TIME]?: number | string
+  [RESULT_FIELD_ROWS_AFFECTED]?: number | string
+  [RESULT_FIELD_LAST_INSERT_ID]?: number
+  [RESULT_FIELD_COLUMNS]?: string[]
+  [RESULT_FIELD_VALUES]?: unknown[][]
+  [key: string]: unknown
+}
+
+/**
+ * A class that represents one data result from an RQLite query or execute API call
+ * @see https://rqlite.io/docs/api/api/
+ */
+export default class DataResult {
+  time = 0.0
+
+  lastInsertId?: number
+
+  rowsAffected = 0
+
+  data: Record<string, unknown> = {}
+
+  constructor (result: RqliteSingleResult, valuesIndex?: number) {
+    if (typeof result !== 'object' || result === null) {
+      throw new Error('The result argument is required to be an object')
+    }
+    if (typeof valuesIndex !== 'undefined' && !Number.isFinite(valuesIndex)) {
+      throw new Error('The valuesIndex argument is required to be a finite number when provided')
+    }
+    this.time = parseFloat(String(result[RESULT_FIELD_TIME] || 0.0))
+    this.rowsAffected = parseInt(String(result[RESULT_FIELD_ROWS_AFFECTED] || 0), 10)
+    this.lastInsertId = result[RESULT_FIELD_LAST_INSERT_ID] as number | undefined
+    if (Number.isFinite(valuesIndex)) {
+      const columns = result[RESULT_FIELD_COLUMNS] as string[]
+      const resultValues = (result[RESULT_FIELD_VALUES] as unknown[][])[valuesIndex as number]
+      if (resultValues) {
+        this.data = resultValues.reduce<Record<string, unknown>>((acc, val, i) => {
+          const col = columns[i]
+          acc[col] = val
+          return acc
+        }, {})
+      }
+    }
+  }
+
+  get (property: string): unknown {
+    return this.data[property]
+  }
+
+  getTime (): number {
+    return this.time
+  }
+
+  getLastInsertId (): number | undefined {
+    return this.lastInsertId
+  }
+
+  getRowsAffected (): number {
+    return this.rowsAffected
+  }
+
+  toObject (): Record<string, unknown> {
+    return JSON.parse(JSON.stringify(this.data)) as Record<string, unknown>
+  }
+
+  toArray (): unknown[] {
+    return Object.values(this.data)
+  }
+
+  toColumnsArray (): string[] {
+    return Object.keys(this.data)
+  }
+
+  toString (): string {
+    return JSON.stringify(this.data)
+  }
+}

package/src/api/results/data-results.ts

@@ -0,0 +1,91 @@
+/**
+ * Class for handling many RQLite data api results
+ * @module api/results/data-results
+ * @see https://rqlite.io/docs/api/api/
+ * @see module:api/results/result-fields
+ */
+import DataResult from './data-result.js'
+import type { RqliteSingleResult } from './data-result.js'
+import DataResultError from './data-result-error.js'
+import {
+  RESULT_FIELD_ERROR,
+  RESULT_FIELD_ERROR_V2,
+  RESULT_FIELD_RESULTS,
+  RESULT_FIELD_TIME,
+  RESULT_FIELD_VALUES,
+} from './result-fields.js'
+
+export type RqliteApiData = {
+  [RESULT_FIELD_TIME]?: number | string
+  [RESULT_FIELD_RESULTS]: RqliteSingleResult[]
+}
+
+/**
+ * A class to manage a list of results from an RQLite query or execute API response
+ * @see https://rqlite.io/docs/api/api/
+ */
+export default class DataResults {
+  time = 0.0
+
+  results: Array<DataResult | DataResultError> = []
+
+  constructor (data: RqliteApiData) {
+    this.setApiData(data)
+  }
+
+  setApiData (data: RqliteApiData): void {
+    if (typeof data !== 'object' || data === null) {
+      throw new Error('The data argument is required to be an object')
+    }
+    if (!data[RESULT_FIELD_RESULTS]) {
+      throw new Error('The data object is required to have a results property')
+    }
+    this.time = parseFloat(String(data[RESULT_FIELD_TIME] || 0.0))
+    const results = data[RESULT_FIELD_RESULTS] || []
+    this.results = results.reduce<Array<DataResult | DataResultError>>((acc, result) => {
+      if (typeof result === 'object' && result !== null && result[RESULT_FIELD_ERROR]) {
+        return acc.concat(
+          new DataResultError(
+            String(result[RESULT_FIELD_ERROR]),
+            result[RESULT_FIELD_ERROR_V2] as Record<string, unknown> | undefined,
+          ),
+        )
+      }
+      const vals = result[RESULT_FIELD_VALUES]
+      if (!vals) {
+        return acc.concat(new DataResult(result))
+      }
+      const dataResults = vals.map((_v, valuesIndex) => new DataResult(result, valuesIndex))
+      return acc.concat(dataResults)
+    }, [])
+  }
+
+  hasError (): boolean {
+    return !!this.getFirstError()
+  }
+
+  getFirstError (): DataResultError | undefined {
+    return this.results.find((v) => v instanceof DataResultError) as DataResultError | undefined
+  }
+
+  getTime (): number {
+    return this.time
+  }
+
+  get (index: number): DataResult | DataResultError | undefined {
+    return this.results[index]
+  }
+
+  getResults (): Array<DataResult | DataResultError> {
+    return this.results
+  }
+
+  toArray (): Record<string, unknown>[] {
+    return this.results.map((result) => result.toObject())
+  }
+
+  toString (): string {
+    const list = this.results.map((result) => result.toObject())
+    return JSON.stringify(list)
+  }
+}

package/src/api/results/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Features for handle RQLite data api responses for success and errors
+ * @module api/results
+ */
+export { default as DataResult } from './data-result.js'
+export { default as DataResultError } from './data-result-error.js'
+export { default as DataResults } from './data-results.js'

package/src/api/results/result-fields.ts

@@ -0,0 +1,14 @@
+/**
+ * RQLite JSON response field name constants
+ * @module api/results/result-fields
+ * @see https://rqlite.io/docs/api/api/
+ */
+
+export const RESULT_FIELD_TIME = 'time'
+export const RESULT_FIELD_ROWS_AFFECTED = 'rows_affected'
+export const RESULT_FIELD_LAST_INSERT_ID = 'last_insert_id'
+export const RESULT_FIELD_COLUMNS = 'columns'
+export const RESULT_FIELD_VALUES = 'values'
+export const RESULT_FIELD_ERROR = 'error'
+export const RESULT_FIELD_ERROR_V2 = 'error_v2'
+export const RESULT_FIELD_RESULTS = 'results'

package/src/api/status/index.ts

@@ -0,0 +1,53 @@
+/**
+ * Status api client to perform RQLite status and diagnostics operations
+ * @module api/status
+ * @see https://rqlite.io/docs/guides/monitoring-rqlite/
+ */
+import ApiClient from '../client/index.js'
+import type { HttpResponse } from '../../http-request/index.js'
+import { HTTP_METHOD_GET } from '../../http-request/http-methods.js'
+import { PATH_STATUS } from '../paths.js'
+
+export { PATH_STATUS } from '../paths.js'
+
+export type StatusRequestOptions = {
+  raw?: boolean
+  attemptHostIndex?: number
+  useLeader?: boolean
+}
+
+export type StatusAllHostsResponse = {
+  response: HttpResponse
+  host: string
+}
+
+/**
+ * Data api client to perform RQLite status queries
+ */
+export default class StatusApiClient extends ApiClient {
+  /**
+   * Get the RQLite server status which defaults to the leader host
+   * @see https://rqlite.io/docs/guides/monitoring-rqlite/
+   */
+  async status (options: StatusRequestOptions = {}): Promise<HttpResponse> {
+    return this.fetch({
+      ...options,
+      uri: PATH_STATUS,
+      httpMethod: HTTP_METHOD_GET,
+      useLeader: typeof options.useLeader === 'boolean' ? options.useLeader : true,
+    }) as Promise<HttpResponse>
+  }
+
+  /**
+   * Get the RQLite server status for all hosts
+   * @see https://rqlite.io/docs/guides/monitoring-rqlite/
+   */
+  async statusAllHosts (options: StatusRequestOptions = {}): Promise<StatusAllHostsResponse[]> {
+    const hosts = this.getHosts()
+    const promises = hosts.map(async (_host, attemptHostIndex) => {
+      const response = await this.status({ ...options, useLeader: false, attemptHostIndex })
+      return { response, host: hosts[attemptHostIndex] }
+    })
+    return Promise.all(promises)
+  }
+}

package/src/http-request/auth-keys.ts

@@ -0,0 +1,14 @@
+/**
+ * Authentication Map key constants
+ * @module http-request/auth-keys
+ */
+
+/**
+ * Username key for authentication
+ */
+export const AUTH_USERNAME = 'username'
+
+/**
+ * Password key for authentication
+ */
+export const AUTH_PASSWORD = 'password'

package/src/http-request/content-types.ts

@@ -0,0 +1,4 @@
+export const CONTENT_TYPE_TEXT_PLAIN = 'text/plain'
+export const CONTENT_TYPE_APPLICATION_JSON = 'application/json'
+export const CONTENT_TYPE_APPLICATION_X_WWW_FORM_URLENCODED = 'application/x-www-form-urlencoded'
+export const CONTENT_TYPE_APPLICATION_OCTET_STREAM = 'application/octet-stream'

package/src/http-request/errors.ts

@@ -0,0 +1,17 @@
+/**
+ * Http request errors
+ * @module http-request/errors
+ */
+
+/**
+ * Error when max redirect attempts have been reached
+ */
+export class ERROR_HTTP_REQUEST_MAX_REDIRECTS extends Error {
+  code: string
+
+  constructor (...args: ConstructorParameters<typeof Error>) {
+    super(...args)
+    this.name = this.constructor.name
+    this.code = this.constructor.name
+  }
+}

package/src/http-request/http-headers.ts

@@ -0,0 +1,19 @@
+/**
+ * HTTP header name constants used by RQLite clients
+ * @module http-request/http-headers
+ */
+
+/**
+ * Accept request header
+ */
+export const HTTP_HEADER_ACCEPT = 'Accept'
+
+/**
+ * Content-Type request header
+ */
+export const HTTP_HEADER_CONTENT_TYPE = 'Content-Type'
+
+/**
+ * Location response header (redirects)
+ */
+export const HTTP_HEADER_LOCATION = 'Location'

package/src/http-request/http-methods.ts

@@ -0,0 +1,12 @@
+/**
+ * Http methods
+ * @module http-request/http-methods
+ */
+
+export const HTTP_METHOD_DELETE = 'DELETE'
+export const HTTP_METHOD_GET = 'GET'
+export const HTTP_METHOD_HEAD = 'HEAD'
+export const HTTP_METHOD_OPTIONS = 'OPTIONS'
+export const HTTP_METHOD_PATCH = 'PATCH'
+export const HTTP_METHOD_POST = 'POST'
+export const HTTP_METHOD_PUT = 'PUT'