@reddb-io/client 1.0.7 → 1.1.0

package/src/index.js

@@ -28,6 +28,7 @@
 
 import { RedDBError } from './protocol.js'
 import { HttpRpcClient } from './http.js'
+import { GrpcRpcClient } from './grpc.js'
 import { connectRedwire } from './redwire.js'
 import { parseUri, deriveLoginUrl } from './url.js'
 import {
@@ -38,16 +39,22 @@ import {
 } from './embedded-rejection.js'
 import { CacheClient } from './cache.js'
 import { KvClient } from './kv.js'
+import { QueueClient } from './queue.js'
 import { ConfigClient } from './config.js'
 import { VaultClient } from './vault.js'
+import { TypedQueryBuilder, collectionExists, listCollections } from './db-helpers.js'
 
 export { RedDBError, EmbeddedNotSupported, EMBEDDED_REJECTION_MESSAGE, isEmbeddedUri }
 export { CacheClient } from './cache.js'
 export { KvClient } from './kv.js'
+export { QueueClient } from './queue.js'
 export { ConfigClient } from './config.js'
 export { VaultClient } from './vault.js'
+export { TypedQueryBuilder } from './db-helpers.js'
 export { parseUri, deriveLoginUrl } from './url.js'
 
+const MIN_INSERT_ID_ENGINE_VERSION = '1.0.9'
+
 /**
  * Connect to a remote RedDB instance.
  *
@@ -90,16 +97,29 @@ export async function connect(uri, options = {}) {
       token = session.token
     }
     const client = new HttpRpcClient({ baseUrl, token })
-    await client.call('health', {})
+    await client.call('query', { sql: 'SELECT 1' })
     return new RedDB(client)
   }
 
-  if (
-    parsed.kind === 'red'
-    || parsed.kind === 'reds'
-    || parsed.kind === 'grpc'
-    || parsed.kind === 'grpcs'
-  ) {
+  if (parsed.kind === 'grpc' || parsed.kind === 'grpcs') {
+    let token = merged.token
+    if (!token && merged.username && merged.password) {
+      const loginUrl = merged.loginUrl ?? deriveLoginUrl(parsed)
+      const session = await login(loginUrl, {
+        username: merged.username,
+        password: merged.password,
+      })
+      token = session.token
+    }
+    const scheme = parsed.kind === 'grpcs' ? 'https' : 'http'
+    const client = new GrpcRpcClient({
+      baseUrl: `${scheme}://${parsed.host}:${parsed.port}`,
+      token,
+    })
+    return new RedDB(client)
+  }
+
+  if (parsed.kind === 'red' || parsed.kind === 'reds') {
     let token = merged.token
     if (!token && merged.username && merged.password) {
       const loginUrl = merged.loginUrl ?? deriveLoginUrl(parsed)
@@ -135,6 +155,89 @@ export async function connect(uri, options = {}) {
   )
 }
 
+function serializeParam(value) {
+  assertSupportedParam(value)
+  if (value instanceof Float32Array || value instanceof Float64Array) {
+    return Array.from(value)
+  }
+  if (value instanceof Date) {
+    return { $ts: String(BigInt(value.getTime()) * 1_000_000n) }
+  }
+  if (value instanceof Uint8Array || (typeof Buffer !== 'undefined' && value instanceof Buffer)) {
+    return { $bytes: bytesToBase64(value) }
+  }
+  if (typeof value === 'number' && !Number.isFinite(value)) {
+    if (Number.isNaN(value)) return { $float: 'NaN' }
+    return { $float: value > 0 ? 'Infinity' : '-Infinity' }
+  }
+  if (typeof value === 'string' && isUuidString(value)) {
+    return { $uuid: value }
+  }
+  return value
+}
+
+function assertSupportedParam(value) {
+  if (value == null) return
+  if (
+    typeof value === 'boolean'
+    || typeof value === 'number'
+    || typeof value === 'string'
+  ) {
+    return
+  }
+  if (value instanceof Date) {
+    if (Number.isNaN(value.getTime())) {
+      throw new RedDBError('UNSUPPORTED_PARAM', 'cannot encode invalid Date query parameter')
+    }
+    return
+  }
+  if (
+    value instanceof Uint8Array
+    || value instanceof Float32Array
+    || value instanceof Float64Array
+    || (typeof Buffer !== 'undefined' && value instanceof Buffer)
+  ) {
+    return
+  }
+  if (Array.isArray(value)) {
+    if (value.every((item) => typeof item === 'number')) return
+    throw new RedDBError(
+      'UNSUPPORTED_PARAM',
+      'array query parameters must contain only numbers',
+    )
+  }
+  if (typeof value === 'object' && Object.getPrototypeOf(value) === Object.prototype) {
+    return
+  }
+  throw new RedDBError(
+    'UNSUPPORTED_PARAM',
+    `cannot encode query parameter of type ${typeof value}`,
+  )
+}
+
+function normalizeQueryParams(args) {
+  if (args.length === 0) return null
+  if (args.length === 1 && Array.isArray(args[0])) return args[0].map(serializeParam)
+  return args.map(serializeParam)
+}
+
+function bytesToBase64(value) {
+  const bytes = value instanceof Uint8Array
+    ? value
+    : new Uint8Array(value.buffer, value.byteOffset, value.byteLength)
+  if (typeof Buffer !== 'undefined') {
+    return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString('base64')
+  }
+  let text = ''
+  for (const byte of bytes) text += String.fromCharCode(byte)
+  // eslint-disable-next-line no-undef
+  return btoa(text)
+}
+
+function isUuidString(value) {
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value)
+}
+
 /**
  * Resolve TLS options for a redwire(s) connection. Source order:
  *   1. caller-supplied `options.tls` object.
@@ -255,6 +358,7 @@ export class RedDB {
   constructor(client) {
     this.client = client
     this.cache = new CacheClient(client)
+    this.queue = new QueueClient(client)
     const defaultKv = new KvClient(client)
     this.kv = Object.assign((collection = 'kv_default') => new KvClient(client, collection), {
       put: defaultKv.put.bind(defaultKv),
@@ -267,18 +371,52 @@ export class RedDB {
   }
 
   /** Execute a SQL query. Returns `{ statement, affected, columns, rows }`. */
-  query(sql) {
-    return this.client.call('query', { sql })
+  query(sql, ...params) {
+    const wireParams = normalizeQueryParams(params)
+    if (wireParams == null) {
+      return this.client.call('query', { sql })
+    }
+    return this.client.call('query', { sql, params: wireParams })
+  }
+
+  /** Execute a SQL statement. Alias for `query`, including parameter binding. */
+  execute(sql, ...params) {
+    return this.query(sql, ...params)
+  }
+
+  /** Insert one row. Returns `{ affected, id }`. */
+  async insert(collection, payload) {
+    let result = await this.client.call('insert', { collection, payload })
+    if (
+      result &&
+      typeof result === 'object' &&
+      !('affected' in result) &&
+      'id' in result
+    ) {
+      result = { ...result, affected: 1 }
+    }
+    return requireInsertId(result, 'insert')
   }
 
-  /** Insert one row. Returns `{ affected, id? }`. */
-  insert(collection, payload) {
-    return this.client.call('insert', { collection, payload })
+  /** Insert many rows in one call. Returns `{ affected, ids }`. */
+  async bulkInsert(collection, payloads) {
+    const result = await this.client.call('bulk_insert', { collection, payloads })
+    return requireInsertIds(result, payloads.length)
   }
 
-  /** Insert many rows in one call. Returns `{ affected }`. */
-  bulkInsert(collection, payloads) {
-    return this.client.call('bulk_insert', { collection, payloads })
+  /** Return true when a collection is visible in the catalog. */
+  exists(collection) {
+    return collectionExists(this, collection)
+  }
+
+  /** List visible collections using SHOW COLLECTIONS. */
+  list() {
+    return listCollections(this)
+  }
+
+  /** Return a caller-typed query builder for a collection. */
+  from(collection) {
+    return new TypedQueryBuilder(this, collection)
   }
 
   /** Get an entity by id. Returns `{ entity }` (entity is `null` if not found). */
@@ -334,3 +472,29 @@ export class RedDB {
     return this.client.close()
   }
 }
+
+function requireInsertId(result, method) {
+  if (!result || typeof result !== 'object' || result.id == null) {
+    throw new RedDBError(
+      'ENGINE_TOO_OLD',
+      `${method}() requires RedDB engine >= ${MIN_INSERT_ID_ENGINE_VERSION} with insert id support`,
+    )
+  }
+  return result
+}
+
+function requireInsertIds(result, expected) {
+  if (!result || typeof result !== 'object' || !Array.isArray(result.ids)) {
+    throw new RedDBError(
+      'ENGINE_TOO_OLD',
+      `bulkInsert() requires RedDB engine >= ${MIN_INSERT_ID_ENGINE_VERSION} with bulk insert id support`,
+    )
+  }
+  if (result.ids.length !== expected) {
+    throw new RedDBError(
+      'INVALID_RESPONSE',
+      `bulkInsert() expected ${expected} ids, got ${result.ids.length}`,
+    )
+  }
+  return result
+}

package/src/kv.js

@@ -17,6 +17,20 @@ export class KvClient {
     })
   }
 
+  async get(key, options = {}) {
+    const collection = options.collection ?? this.collection
+    const result = await this.client.call('query', {
+      sql: `KV GET ${kvPath(collection, key)}`,
+    })
+    return result?.rows?.[0]?.value ?? null
+  }
+
+  async getMany(keys, options = {}) {
+    const values = []
+    for (const key of keys) values.push(await this.get(key, options))
+    return values
+  }
+
   async invalidateTags(tags, options = {}) {
     const collection = options.collection ?? this.collection
     const result = await this.client.call('query', {
@@ -56,7 +70,15 @@ function kvPath(collection, key) {
 }
 
 function kvIdentifier(value) {
-  return String(value).replace(/[^A-Za-z0-9_]/g, '_')
+  const ident = String(value)
+  const invalid = ident.match(/[^A-Za-z0-9_]/)
+  if (invalid) {
+    throw new RedDBError(
+      'INVALID_KV_KEY',
+      `invalid KV key "${ident}": character "${invalid[0]}" is not supported`,
+    )
+  }
+  return ident
 }
 
 function kvValueLiteral(value) {

package/src/queue.js

@@ -0,0 +1,78 @@
+import { RedDBError } from './protocol.js'
+
+export class QueueClient {
+  constructor(client) {
+    this.client = client
+  }
+
+  push(queue, value, options = {}) {
+    const priority = options.priority != null ? ` PRIORITY ${queuePriority(options.priority)}` : ''
+    return this.client.call('query', {
+      sql: `QUEUE PUSH ${queueIdentifier(queue)} ${queueValueLiteral(value)}${priority}`,
+    })
+  }
+
+  async pop(queue, count) {
+    const result = await this.client.call('query', {
+      sql: `QUEUE POP ${queueIdentifier(queue)}${queueCount(count)}`,
+    })
+    return queuePayloads(result)
+  }
+
+  async peek(queue, count) {
+    const result = await this.client.call('query', {
+      sql: `QUEUE PEEK ${queueIdentifier(queue)}${queueCount(count)}`,
+    })
+    return queuePayloads(result)
+  }
+
+  async len(queue) {
+    const result = await this.client.call('query', {
+      sql: `QUEUE LEN ${queueIdentifier(queue)}`,
+    })
+    return Number(result?.rows?.[0]?.len ?? 0)
+  }
+
+  purge(queue) {
+    return this.client.call('query', {
+      sql: `QUEUE PURGE ${queueIdentifier(queue)}`,
+    })
+  }
+}
+
+function queueIdentifier(value) {
+  const ident = String(value)
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(ident)) {
+    throw new RedDBError(
+      'INVALID_QUEUE_NAME',
+      `invalid queue name "${ident}": expected an SQL identifier`,
+    )
+  }
+  return ident
+}
+
+function queueCount(count) {
+  if (count == null) return ''
+  if (!Number.isInteger(count) || count < 0) {
+    throw new RedDBError('INVALID_QUEUE_COUNT', 'queue count must be a non-negative integer')
+  }
+  return ` COUNT ${count}`
+}
+
+function queuePriority(priority) {
+  if (!Number.isInteger(priority)) {
+    throw new RedDBError('INVALID_QUEUE_PRIORITY', 'queue priority must be an integer')
+  }
+  return String(priority)
+}
+
+function queueValueLiteral(value) {
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value)
+  if (value == null) return 'NULL'
+  if (typeof value === 'string') return `'${value.replace(/'/g, "''")}'`
+  return JSON.stringify(value)
+}
+
+function queuePayloads(result) {
+  return Array.isArray(result?.rows) ? result.rows.map((row) => row.payload) : []
+}