@ouim/vectoriadb-client 0.1.0

package/demo.js

@@ -0,0 +1,33 @@
+import VectoriaDB from './index.js'
+
+async function perfDemo() {
+  const db = new VectoriaDB({ serverUrl: 'http://localhost:3001' })
+
+  console.log('Initializing remote VectoriaDB (server should already be running)...')
+  await db.initialize()
+
+  console.log('Inserting 1,000 small documents in batches of 200...')
+  const docs = Array.from({ length: 1000 }, (_, i) => ({
+    id: `doc:${i}`,
+    text: `Document number ${i}`,
+    metadata: { id: `doc:${i}`, owner: 'demo' },
+  }))
+
+  const start = Date.now()
+  for (let i = 0; i < docs.length; i += 200) {
+    const batch = docs.slice(i, i + 200)
+    await db.addMany(batch)
+  }
+  console.log('Inserted 1000 docs in', Date.now() - start, 'ms')
+
+  console.log('Running a search...')
+  const results = await db.search('Document number 5', { topK: 10 })
+  console.log('Search results:', results.slice(0, 3))
+
+  db.close()
+}
+
+perfDemo().catch(err => {
+  console.error(err)
+  process.exit(1)
+})

package/index.js

@@ -0,0 +1,172 @@
+import SocketClient from './socket-client.js'
+
+// Client SDK that mirrors VectoriaDB API surface (runtime validation + forwarding)
+export default class VectoriaDB {
+  constructor(opts = {}) {
+    if (!opts.serverUrl) throw new Error('serverUrl is required')
+    this.serverUrl = opts.serverUrl
+    this.apiKey = opts.apiKey || null
+    this.requestTimeout = opts.requestTimeout || 30000
+    this._socket = new SocketClient({ serverUrl: this.serverUrl, apiKey: this.apiKey, requestTimeout: this.requestTimeout })
+  }
+
+  // --- helper to serialize function filters ---
+  static _serializeFunction(fn) {
+    if (!fn) return null
+    if (typeof fn === 'function') return { __isFnString: true, fn: fn.toString() }
+    if (typeof fn === 'string') return { __isFnString: true, fn: fn }
+    return null
+  }
+
+  // low-level forwarder
+  async _forward(method, ...params) {
+    return this._socket.sendRequest({ method, params })
+  }
+
+  // --- VectoriaDB API methods (as in docs) ---
+  async initialize() {
+    return this._forward('initialize')
+  }
+
+  async add(id, text, metadata) {
+    if (typeof id !== 'string') throw new TypeError('id must be string')
+    if (typeof text !== 'string') throw new TypeError('text must be string')
+    if (!metadata || typeof metadata !== 'object') throw new TypeError('metadata must be an object')
+    return this._forward('add', id, text, metadata)
+  }
+
+  async addMany(docs) {
+    if (!Array.isArray(docs)) throw new TypeError('docs must be an array')
+    if (docs.length === 0) return { added: 0 }
+    return this._forward('addMany', docs)
+  }
+
+  async has(id) {
+    return this._forward('has', id)
+  }
+
+  async get(id) {
+    return this._forward('get', id)
+  }
+
+  async size() {
+    return this._forward('size')
+  }
+
+  async update(id, updates, opts = {}) {
+    return this._forward('update', id, updates, opts)
+  }
+
+  async updateMetadata(id, metadata) {
+    return this._forward('updateMetadata', id, metadata)
+  }
+
+  async updateMany(updates) {
+    return this._forward('updateMany', updates)
+  }
+
+  async remove(id) {
+    return this._forward('remove', id)
+  }
+
+  async removeMany(ids) {
+    return this._forward('removeMany', ids)
+  }
+
+  async clear() {
+    return this._forward('clear')
+  }
+
+  async saveToStorage() {
+    return this._forward('saveToStorage')
+  }
+
+  async loadFromStorage() {
+    return this._forward('loadFromStorage')
+  }
+
+  async clearStorage() {
+    return this._forward('clearStorage')
+  }
+
+  async filter(fn) {
+    // filter is executed server-side — serialize function
+    if (typeof fn !== 'function') throw new TypeError('filter requires a function')
+    const serialized = VectoriaDB._serializeFunction(fn)
+    return this._forward('filter', serialized)
+  }
+
+  async search(queryOrVector, options = {}) {
+    const opts = { ...options }
+    if (opts.filter && typeof opts.filter === 'function') {
+      opts.filter = VectoriaDB._serializeFunction(opts.filter)
+    }
+    return this._forward('search', queryOrVector, opts)
+  }
+
+  // --- convenience collection-style API (maps to VectoriaDB primitives) ---
+  async createCollection(name) {
+    if (!name || typeof name !== 'string') throw new TypeError('collection name required')
+    // no-op on server side; client manages "collection" via metadata.owner
+    return { ok: true, collection: name }
+  }
+
+  async insert(collection, docs) {
+    if (!collection || typeof collection !== 'string') throw new TypeError('collection required')
+    if (!Array.isArray(docs)) throw new TypeError('docs must be an array')
+
+    const transformed = docs.map(d => {
+      const id = d.id || d.metadata?.id || `${collection}:${Math.random().toString(36).slice(2, 9)}`
+      const metadata = Object.assign({}, d.metadata || {}, { id, owner: collection })
+      return { id, text: d.text || d.vector?.toString() || (d.text ?? ''), metadata, vector: d.vector }
+    })
+
+    // Use addMany for textual documents; for vector-only docs we forward to addMany as well
+    return this.addMany(transformed)
+  }
+
+  async query(collection, queryVectorOrText, opts = {}) {
+    if (!collection || typeof collection !== 'string') throw new TypeError('collection required')
+    const options = { ...opts }
+    const originalFilter = options.filter
+
+    // Build a self-contained, serializable filter that enforces owner === collection
+    // and (optionally) runs the user's filter. We inline the user's filter source
+    // so the resulting function does not rely on outer closures when evaluated
+    // on the server process.
+    const ownerLiteral = JSON.stringify(collection)
+
+    if (originalFilter) {
+      // normalize original filter to a source string
+      let origFnStr
+      if (typeof originalFilter === 'function') {
+        origFnStr = originalFilter.toString()
+      } else if (typeof originalFilter === 'string') {
+        origFnStr = originalFilter
+      } else if (originalFilter && originalFilter.__isFnString && typeof originalFilter.fn === 'string') {
+        origFnStr = originalFilter.fn
+      } else {
+        throw new TypeError('filter must be a function or serialized function')
+      }
+
+      // inline user's filter so the combined function is self-contained server-side
+      const combinedFnStr = `(function(m){ try { const __orig = ${origFnStr}; return !!(__orig(m) && m && m.owner === ${ownerLiteral}); } catch(e) { return false } })`
+      options.filter = VectoriaDB._serializeFunction(combinedFnStr)
+    } else {
+      const ownerFnStr = `(function(m){ return m && m.owner === ${ownerLiteral}; })`
+      options.filter = VectoriaDB._serializeFunction(ownerFnStr)
+    }
+
+    return this.search(queryVectorOrText, options)
+  }
+
+  // close socket
+  close() {
+    try {
+      this._socket.close()
+    } catch (e) {}
+  }
+}
+
+// CommonJS fallback (so `require('./client')` still works in many setups)
+export { VectoriaDB }

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@ouim/vectoriadb-client",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "index.js",
+  "scripts": {
+    "demo": "node demo.js",
+    "publish": "npm publish --access public"
+  },
+  "dependencies": {
+    "socket.io-client": "^4.8.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/socket-client.js

@@ -0,0 +1,120 @@
+import { io } from 'socket.io-client'
+
+function _makeId() {
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 9)}`
+}
+
+export default class SocketClient {
+  constructor({ serverUrl, namespace = '/vectoriadb', apiKey = null, requestTimeout = 30000 } = {}) {
+    if (!serverUrl) throw new Error('serverUrl is required')
+    this.serverUrl = serverUrl.replace(/\/$/, '')
+    this.namespace = namespace.startsWith('/') ? namespace : `/${namespace}`
+    this.url = `${this.serverUrl}${this.namespace}`
+    this.apiKey = apiKey
+    this.requestTimeout = requestTimeout || 30000
+
+    this.socket = io(this.url, {
+      auth: { apiKey },
+      path: '/socket.io',
+      transports: ['websocket'],
+      autoConnect: true,
+      reconnection: true,
+    })
+
+    this._pending = new Map() // id -> { resolve, reject, timer, chunks }
+    this._offlineQueue = []
+
+    this.socket.on('connect', () => {
+      // flush queue
+      while (this._offlineQueue.length) {
+        const payload = this._offlineQueue.shift()
+        this.socket.emit('request', payload)
+      }
+    })
+
+    this.socket.on('connect_error', err => {
+      // reject nothing here; pending requests will timeout or be retried
+      // console.warn('connect_error', err.message)
+    })
+
+    this.socket.on('disconnect', reason => {
+      // keep pending promises alive; they will timeout based on requestTimeout
+    })
+
+    this.socket.on('response', msg => {
+      const { id, result, error } = msg || {}
+      const pending = this._pending.get(id)
+      if (!pending) return
+
+      // If streamed chunks were received, assemble them in index order.
+      if (pending.chunksMap) {
+        const chunksMap = pending.chunksMap
+        const indexes = Object.keys(chunksMap)
+          .map(k => Number(k))
+          .sort((a, b) => a - b)
+        const assembled = indexes.flatMap(i => (Array.isArray(chunksMap[i]) ? chunksMap[i] : []))
+        clearTimeout(pending.timer)
+        pending.resolve(assembled)
+        this._pending.delete(id)
+        return
+      }
+
+      clearTimeout(pending.timer)
+      if (error) pending.reject(new Error(error.message || 'ServerError'))
+      else pending.resolve(result)
+      this._pending.delete(id)
+    })
+
+    this.socket.on('response-chunk', msg => {
+      const { id, chunk, index, totalChunks } = msg || {}
+      const pending = this._pending.get(id)
+      if (!pending) return
+
+      if (!pending.chunksMap) pending.chunksMap = {}
+      pending.chunksMap[index] = chunk
+      pending.receivedChunks = (pending.receivedChunks || 0) + 1
+      if (typeof totalChunks === 'number') pending.totalChunks = totalChunks
+
+      // reset timeout so long streams don't prematurely fail
+      if (pending.timer) {
+        clearTimeout(pending.timer)
+        pending.timer = setTimeout(() => {
+          this._pending.delete(id)
+          pending.reject(new Error('RequestTimeout'))
+        }, pending.timeoutMs || this.requestTimeout)
+      }
+    })
+  }
+
+  sendRequest({ method, params = [], collection = undefined, timeout = undefined } = {}) {
+    const id = _makeId()
+    const payload = { id, method, params, collection, timestamp: Date.now() }
+    const effectiveTimeout = typeof timeout === 'number' ? timeout : this.requestTimeout
+
+    const promise = new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this._pending.delete(id)
+        reject(new Error('RequestTimeout'))
+      }, effectiveTimeout)
+
+      // store extra metadata so streaming chunks can reset the timer and be
+      // assembled in order on final response
+      this._pending.set(id, { resolve, reject, timer, timeoutMs: effectiveTimeout, chunksMap: null, receivedChunks: 0, totalChunks: null })
+
+      if (this.socket.connected) {
+        this.socket.emit('request', payload)
+      } else {
+        // queue for send on reconnect
+        this._offlineQueue.push(payload)
+      }
+    })
+
+    return promise
+  }
+
+  close() {
+    try {
+      this.socket.close()
+    } catch (e) {}
+  }
+}