@reddb-io/sdk 1.0.1

package/src/internal/version-compare/index.js

@@ -0,0 +1,163 @@
+/**
+ * @reddb-io/internal-version-compare — install/upgrade/skip verdict for
+ * the CLI postinstall.
+ *
+ * Asymmetry vs SDK/client (per ADR 0006):
+ *   - SDK/client postinstalls *always* download a pinned binary because
+ *     the wire format is version-coupled to the driver.
+ *   - The CLI is a launcher. Users typically already have `red` on PATH
+ *     and would resent each `npm i -g @reddb-io/cli` re-downloading.
+ *     We compare versions and only fetch when strictly newer.
+ *
+ * Verdict table:
+ *   exec throws                            → action='install'  (no binary detected)
+ *   exec returns unparseable output        → action='install'  (warn, fetch fresh)
+ *   PATH version  <  packageVersion        → action='upgrade'
+ *   PATH version  >= packageVersion        → action='skip'
+ *
+ * Prerelease ordering follows semver 2.0.0 §11: a normal release ranks
+ * above any prerelease of the same MAJOR.MINOR.PATCH.
+ */
+
+const SEMVER_RE = /\b(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?\b/
+
+/**
+ * Extract a semver-shaped version string from arbitrary `red --version`
+ * output. Accepts `reddb 0.2.9`, bare `0.2.9`, or `red 1.0.0-rc.1`.
+ *
+ * @param {string} text
+ * @returns {string|null} normalised `MAJOR.MINOR.PATCH[-prerelease]` or null
+ */
+export function parseVersion(text) {
+  if (typeof text !== 'string') return null
+  const m = text.match(SEMVER_RE)
+  if (!m) return null
+  const [, maj, min, pat, pre] = m
+  return pre ? `${maj}.${min}.${pat}-${pre}` : `${maj}.${min}.${pat}`
+}
+
+/**
+ * semver 2.0.0 ordering. Returns -1 / 0 / 1.
+ *
+ * Throws TypeError if either side is not parseable — this is a
+ * programmer error, not a runtime fallback path.
+ */
+export function compareSemver(a, b) {
+  const pa = parseVersion(a)
+  const pb = parseVersion(b)
+  if (pa === null) throw new TypeError(`compareSemver: invalid version "${a}"`)
+  if (pb === null) throw new TypeError(`compareSemver: invalid version "${b}"`)
+
+  const [coreA, preA] = splitCore(pa)
+  const [coreB, preB] = splitCore(pb)
+
+  for (let i = 0; i < 3; i++) {
+    if (coreA[i] !== coreB[i]) return coreA[i] < coreB[i] ? -1 : 1
+  }
+
+  // Cores equal — apply §11: no-prerelease ranks above any prerelease.
+  if (preA === null && preB === null) return 0
+  if (preA === null) return 1
+  if (preB === null) return -1
+
+  return comparePrerelease(preA, preB)
+}
+
+function splitCore(v) {
+  const dash = v.indexOf('-')
+  const core = dash === -1 ? v : v.slice(0, dash)
+  const pre = dash === -1 ? null : v.slice(dash + 1)
+  const parts = core.split('.').map((n) => Number(n))
+  return [parts, pre]
+}
+
+function comparePrerelease(a, b) {
+  const sa = a.split('.')
+  const sb = b.split('.')
+  const len = Math.min(sa.length, sb.length)
+  for (let i = 0; i < len; i++) {
+    const c = compareIdentifier(sa[i], sb[i])
+    if (c !== 0) return c
+  }
+  if (sa.length === sb.length) return 0
+  return sa.length < sb.length ? -1 : 1
+}
+
+function compareIdentifier(a, b) {
+  const aNum = /^\d+$/.test(a)
+  const bNum = /^\d+$/.test(b)
+  if (aNum && bNum) {
+    const na = Number(a)
+    const nb = Number(b)
+    return na === nb ? 0 : na < nb ? -1 : 1
+  }
+  if (aNum) return -1 // numeric < alphanumeric per §11
+  if (bNum) return 1
+  return a === b ? 0 : a < b ? -1 : 1
+}
+
+/**
+ * Decide what the CLI postinstall should do.
+ *
+ * @param {{ packageVersion: string, exec: () => string }} opts
+ *   `exec` is called with no arguments and is expected to return the
+ *   stdout of `red --version` (sync). It may throw — that signals "no
+ *   PATH binary detected" and routes to action='install'.
+ * @returns {{ action: 'install'|'upgrade'|'skip', reason: string }}
+ */
+export function compareInstalled(opts) {
+  if (!opts || typeof opts !== 'object') {
+    throw new TypeError('compareInstalled: options object required')
+  }
+  const { packageVersion, exec } = opts
+  if (typeof packageVersion !== 'string' || packageVersion === '') {
+    throw new TypeError('compareInstalled: `packageVersion` must be a non-empty string')
+  }
+  if (typeof exec !== 'function') {
+    throw new TypeError('compareInstalled: `exec` must be a function')
+  }
+  if (parseVersion(packageVersion) === null) {
+    throw new TypeError(`compareInstalled: \`packageVersion\` "${packageVersion}" is not parseable semver`)
+  }
+
+  let raw
+  try {
+    raw = exec()
+  } catch (err) {
+    return {
+      action: 'install',
+      reason: `no PATH \`red\` binary detected (${err.message || 'exec failed'})`,
+    }
+  }
+
+  const installed = parseVersion(typeof raw === 'string' ? raw : '')
+  if (installed === null) {
+    return {
+      action: 'install',
+      reason: `unparseable PATH \`red --version\` output (${truncate(String(raw))})`,
+    }
+  }
+
+  const cmp = compareSemver(installed, packageVersion)
+  if (cmp < 0) {
+    return {
+      action: 'upgrade',
+      reason: `PATH \`red\` ${installed} is older than package ${packageVersion}`,
+    }
+  }
+  if (cmp > 0) {
+    return {
+      action: 'skip',
+      reason: `PATH \`red\` ${installed} is newer than package ${packageVersion}`,
+    }
+  }
+  return {
+    action: 'skip',
+    reason: `PATH \`red\` already at ${installed}`,
+  }
+}
+
+function truncate(s) {
+  const oneLine = s.replace(/\s+/g, ' ').trim()
+  return oneLine.length > 80 ? `${oneLine.slice(0, 77)}...` : oneLine
+}

package/src/kv.js

@@ -0,0 +1,70 @@
+import { RedDBError } from './protocol.js'
+
+export class KvClient {
+  constructor(client, collection = 'kv_default') {
+    this.client = client
+    this.collection = collection
+  }
+
+  put(key, value, options = {}) {
+    const collection = options.collection ?? this.collection
+    const tags = Array.isArray(options.tags) && options.tags.length > 0
+      ? ` TAGS [${options.tags.map(kvTagLiteral).join(', ')}]`
+      : ''
+    const expire = options.expireMs != null ? ` EXPIRE ${Number(options.expireMs)} ms` : ''
+    return this.client.call('query', {
+      sql: `KV PUT ${kvPath(collection, key)} = ${kvValueLiteral(value)}${expire}${tags}`,
+    })
+  }
+
+  async invalidateTags(tags, options = {}) {
+    const collection = options.collection ?? this.collection
+    const result = await this.client.call('query', {
+      sql: `INVALIDATE TAGS [${tags.map(kvTagLiteral).join(', ')}] FROM ${kvIdentifier(collection)}`,
+    })
+    return result.affected ?? result.affected_rows ?? result.rows?.[0]?.invalidated ?? 0
+  }
+
+  async *watch(key, options = {}) {
+    if (!this.client.baseUrl) {
+      throw new RedDBError('UNSUPPORTED_TRANSPORT', 'kv.watch requires the HTTP transport')
+    }
+    const collection = options.collection ?? this.collection
+    const params = new URLSearchParams()
+    if (options.sinceLsn != null) params.set('since_lsn', String(options.sinceLsn))
+    if (options.limit != null) params.set('limit', String(options.limit))
+    const suffix = params.toString() ? `?${params}` : ''
+    const url = `${this.client.baseUrl}/collections/${encodeURIComponent(collection)}/kv/${encodeURIComponent(String(key))}/watch${suffix}`
+    const response = await fetch(url, this.client.attachAuth({ method: 'GET' }))
+    if (!response.ok) {
+      throw new RedDBError('HTTP_ERROR', `kv.watch failed with HTTP ${response.status}`)
+    }
+    const text = await response.text()
+    for (const block of text.split('\n\n')) {
+      const line = block.split('\n').find((entry) => entry.startsWith('data: '))
+      if (line) yield JSON.parse(line.slice(6))
+    }
+  }
+
+  watchPrefix(prefix, options = {}) {
+    return this.watch(`${prefix}.*`, options)
+  }
+}
+
+function kvPath(collection, key) {
+  return `${kvIdentifier(collection)}.${kvIdentifier(key)}`
+}
+
+function kvIdentifier(value) {
+  return String(value).replace(/[^A-Za-z0-9_]/g, '_')
+}
+
+function kvValueLiteral(value) {
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value)
+  if (value == null) return 'NULL'
+  return `'${String(value).replace(/'/g, "''")}'`
+}
+
+function kvTagLiteral(value) {
+  return `'${String(value).replace(/'/g, "''")}'`
+}

package/src/protocol.js

@@ -0,0 +1,157 @@
+/**
+ * JSON-RPC 2.0 line-delimited client.
+ *
+ * Maintains a map of pending requests keyed by id. Reads stdout one
+ * line at a time, parses each line as a response envelope, looks up
+ * the pending promise by id and resolves/rejects it.
+ *
+ * Spec: PLAN_DRIVERS.md, "Spec do protocolo stdio".
+ */
+
+const NEWLINE = 0x0a // '\n'
+const encoder = new TextEncoder()
+const decoder = new TextDecoder('utf-8')
+
+/**
+ * RedDB-shaped error. Drivers in other languages should expose an
+ * equivalent class with the same `code` field.
+ */
+export class RedDBError extends Error {
+  constructor(code, message, data) {
+    super(message)
+    this.name = 'RedDBError'
+    this.code = code
+    this.data = data ?? null
+  }
+}
+
+export class RpcClient {
+  /** @param {import('./spawn.js').RedProcess} child */
+  constructor(child) {
+    this.child = child
+    this.nextId = 1
+    /** @type {Map<number|string, { resolve: Function, reject: Function }>} */
+    this.pending = new Map()
+    this.closed = false
+    this.closeReason = null
+    this.readerPromise = this.#readLoop()
+  }
+
+  /**
+   * Send a JSON-RPC 2.0 request and resolve with the result, or reject
+   * with a `RedDBError` if the server returned an error envelope.
+   */
+  call(method, params = {}) {
+    if (this.closed) {
+      return Promise.reject(
+        new RedDBError('CLIENT_CLOSED', `client is closed: ${this.closeReason ?? 'unknown'}`),
+      )
+    }
+    const id = this.nextId++
+    const envelope = JSON.stringify({ jsonrpc: '2.0', id, method, params })
+    return new Promise((resolve, reject) => {
+      this.pending.set(id, { resolve, reject })
+      this.child.stdin.write(encoder.encode(envelope + '\n')).catch((err) => {
+        this.pending.delete(id)
+        reject(err)
+      })
+    })
+  }
+
+  /** Drain pending requests, send `close`, wait for the binary to exit. */
+  async close() {
+    if (this.closed) return
+    try {
+      await this.call('close', {})
+    } catch {
+      // best effort — server may already be gone
+    }
+    this.#shutdown('close requested')
+    try {
+      this.child.stdin.end()
+    } catch {
+      // ignore
+    }
+    await this.child.wait()
+  }
+
+  // -------------------------------------------------------------------------
+  // Internal: stdout reader loop
+  // -------------------------------------------------------------------------
+
+  async #readLoop() {
+    let buffer = new Uint8Array(0)
+    try {
+      for await (const chunk of this.child.stdout) {
+        const merged = new Uint8Array(buffer.length + chunk.length)
+        merged.set(buffer, 0)
+        merged.set(chunk, buffer.length)
+        buffer = merged
+
+        // Split on \n, dispatch each complete line.
+        let start = 0
+        for (let i = 0; i < buffer.length; i++) {
+          if (buffer[i] === NEWLINE) {
+            const lineBytes = buffer.subarray(start, i)
+            this.#dispatchLine(decoder.decode(lineBytes))
+            start = i + 1
+          }
+        }
+        if (start > 0) {
+          buffer = buffer.subarray(start)
+        }
+      }
+    } catch (err) {
+      this.#shutdown(`stdout reader error: ${err.message}`)
+      return
+    }
+    // EOF — server exited.
+    this.#shutdown('server stdout closed')
+  }
+
+  #dispatchLine(line) {
+    if (!line.trim()) return
+    let envelope
+    try {
+      envelope = JSON.parse(line)
+    } catch (err) {
+      // Malformed line from the server is fatal to the protocol —
+      // we cannot map it to any pending request.
+      this.#shutdown(`malformed server response: ${err.message}`)
+      return
+    }
+    const id = envelope.id
+    if (id === null || id === undefined) {
+      // No id → cannot route. Treat as protocol violation.
+      return
+    }
+    const pending = this.pending.get(id)
+    if (!pending) {
+      // Unknown id — server bug or duplicate response. Ignore.
+      return
+    }
+    this.pending.delete(id)
+    if (envelope.error) {
+      pending.reject(
+        new RedDBError(
+          envelope.error.code ?? 'UNKNOWN',
+          envelope.error.message ?? 'unknown error',
+          envelope.error.data,
+        ),
+      )
+    } else {
+      pending.resolve(envelope.result)
+    }
+  }
+
+  #shutdown(reason) {
+    if (this.closed) return
+    this.closed = true
+    this.closeReason = reason
+    const err = new RedDBError('CLIENT_CLOSED', reason)
+    for (const { reject } of this.pending.values()) {
+      reject(err)
+    }
+    this.pending.clear()
+  }
+}