@ouim/vectoriadb-server 0.1.3 → 0.1.5

package/README.md

@@ -113,13 +113,69 @@ const bobDocs = await db.query('my-collection', 'farewell', {
 
 ### Server Options
 
-| Option            | Description                            | Default    |
-| :---------------- | :------------------------------------- | :--------- |
-| `port`            | Server listening port                  | `3001`     |
-| `host`            | Server host address                    | `0.0.0.0`  |
-| `apiKey`          | Optional key for client authentication | `null`     |
-| `cors`            | Allowed origins (array)                | `[]` (All) |
-| `streamChunkSize` | Max results per chunk for streaming    | `500`      |
+| Option                    | Description                                                                            | Default    |
+| :------------------------ | :------------------------------------------------------------------------------------- | :--------- |
+| `port`                    | Server listening port                                                                  | `3001`     |
+| `host`                    | Server host address                                                                    | `0.0.0.0`  |
+| `apiKey`                  | Optional key for client authentication                                                 | `null`     |
+| `cors`                    | Allowed origins (array)                                                                | `[]` (All) |
+| `streamChunkSize`         | Max results per chunk for streaming                                                    | `500`      |
+| `autoSaveOnMutationBurst` | Enable automatic saveToStorage after a burst of mutation calls + idle                  | `true`     |
+| `autoSaveOnInactivity`    | Save to storage after `mutationInactivityMs` of no mutations (suitable for small apps) | `true`     |
+| `mutationBurstThreshold`  | Number of mutation calls within `mutationBurstWindowMs` to consider a burst            | `5`        |
+| `mutationBurstWindowMs`   | Time window (ms) used to count burst mutations                                         | `120000`   |
+| `mutationInactivityMs`    | Inactivity window (ms) after last mutation that triggers save                          | `30000`    |
+| `minSaveIntervalMs`       | Minimum time (ms) between automatic saves to avoid thrashing                           | `10000`    |
+
+Auto-save on mutation bursts
+
+A configurable mechanism that detects "mutation bursts" and automatically calls `saveToStorage()` after activity stops. This minimizes write amplification during heavy write periods while ensuring state is persisted shortly after the burst finishes.
+
+How it works:
+
+- A "burst" is detected when at least `mutationBurstThreshold` mutation operations occur within the `mutationBurstWindowMs` time window.
+- When a burst has been detected, the server starts (or resets) an inactivity timer of `mutationInactivityMs` after the last mutation.
+- If the inactivity timer expires and the recent mutation count still meets the threshold, the server calls `saveToStorage()` once.
+- `minSaveIntervalMs` prevents repeated auto-saves from occurring too frequently; overlapping saves are also avoided by an internal in-progress flag.
+- After the inactivity handler runs the mutation history is cleared until new activity occurs.
+
+Behavior timeline (concrete example):
+
+- Settings: `mutationBurstThreshold = 100`, `mutationBurstWindowMs = 120000` (2 min), `mutationInactivityMs = 30000` (30s).
+- If 120 mutations arrive between t=0 and t=90s (burst detected), and no further mutations occur after t=90s, the server waits 30s (inactivity window) and calls `saveToStorage()` at ~t=120s (provided `minSaveIntervalMs` allows it).
+
+Configuration example:
+
+```javascript
+const server = new VectoriaDBServer({
+  port: 3001,
+  autoSaveOnMutationBurst: true,
+  mutationBurstThreshold: 100, // # mutations within the window to mark a burst
+  mutationBurstWindowMs: 2 * 60 * 1000, // window length used to count mutations
+  mutationInactivityMs: 30 * 1000, // wait this long after last mutation before saving
+  minSaveIntervalMs: 10 * 1000, // never auto-save more often than this
+})
+```
+
+Log & testing notes:
+
+- When the auto-save runs the server logs: `[VectoriaDBServer] auto-saved storage (<reason>)` (e.g. `mutation-burst-inactivity` or `inactivity`).
+- To test: simulate mutation calls and assert `saveToStorage()` is invoked after `mutationInactivityMs`; verify `minSaveIntervalMs` prevents frequent saves.
+
+Inactivity-only mode (simpler)
+
+If your application is small or you prefer a simpler policy, enable `autoSaveOnInactivity: true`. With this enabled the server will call `saveToStorage()` after `mutationInactivityMs` of no mutation activity — regardless of how many mutations occurred before the idle period. The inactivity timer resets on each mutation.
+
+Example:
+
+```javascript
+const server = new VectoriaDBServer({
+  autoSaveOnInactivity: true,
+  mutationInactivityMs: 30 * 1000, // save 30s after last mutation
+})
+```
+
+### Client Options
 
 ### Client Options
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ouim/vectoriadb-server",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "type": "module",
   "main": "index.js",
   "scripts": {

package/vectoriadb-server.js

@@ -14,6 +14,35 @@ export default class VectoriaDBServer {
     this.vectoriadbConfig = opts.vectoriadbConfig || {}
     this.streamChunkSize = opts.streamChunkSize || 500
 
+    // --- auto-save / burst-detection (configurable) ---
+    this.autoSaveOnMutationBurst = opts.autoSaveOnMutationBurst !== undefined ? !!opts.autoSaveOnMutationBurst : true
+    // when true the server will save after any inactivity period (see `mutationInactivityMs`) — useful for small apps
+    this.autoSaveOnInactivity = opts.autoSaveOnInactivity !== undefined ? !!opts.autoSaveOnInactivity : false
+    this.mutationBurstThreshold = Number(opts.mutationBurstThreshold) || 5
+    this.mutationBurstWindowMs = Number(opts.mutationBurstWindowMs) || 2 * 60 * 1000 // 2 minutes
+    this.mutationInactivityMs = Number(opts.mutationInactivityMs) || 30 * 1000 // 30s inactivity to trigger save
+    this.minSaveIntervalMs = Number(opts.minSaveIntervalMs) || 10 * 1000 // minimum time between auto-saves
+
+    // internal mutation-tracking state
+    this._mutationMethods = new Set([
+      'add',
+      'addMany',
+      'update',
+      'remove',
+      'removeMany',
+      'clear',
+      'insert',
+      'upsert',
+      'replace',
+      'put',
+      'delete',
+    ])
+    this._mutationTimestamps = []
+    this._inactivityTimer = null
+    this._lastBurstAt = 0
+    this._savingInProgress = false
+    this._lastSaveAt = 0
+
     this._http = null
     this._io = null
     this._vectoria = null
@@ -148,6 +177,15 @@ export default class VectoriaDBServer {
         new Promise((_, reject) => setTimeout(() => reject(new Error('ServerTimeout')), 30000)),
       ])
 
+      // record mutation activity (used to auto-flush after a burst + inactivity)
+      if (this.autoSaveOnMutationBurst && this._isMutationMethod(method)) {
+        try {
+          this._recordMutation()
+        } catch (e) {
+          /* swallow tracking errors */
+        }
+      }
+
       const took = Date.now() - start
 
       // streaming support for very large arrays
@@ -169,8 +207,86 @@ export default class VectoriaDBServer {
     }
   }
 
+  // --- Auto-save on mutation bursts (configurable) ---
+  _isMutationMethod(method) {
+    return this._mutationMethods.has(method)
+  }
+
+  _recordMutation() {
+    const now = Date.now()
+    this._mutationTimestamps.push(now)
+    // purge old timestamps outside the burst window
+    const cutoff = now - this.mutationBurstWindowMs
+    while (this._mutationTimestamps.length && this._mutationTimestamps[0] < cutoff) {
+      this._mutationTimestamps.shift()
+    }
+    if (this._mutationTimestamps.length >= this.mutationBurstThreshold) {
+      this._lastBurstAt = now
+    }
+    this._scheduleInactivityTimer()
+  }
+
+  _scheduleInactivityTimer() {
+    if (this._inactivityTimer) {
+      clearTimeout(this._inactivityTimer)
+    }
+    this._inactivityTimer = setTimeout(() => {
+      // fire-and-forget async
+      this._onInactivityTimeout().catch(err => console.warn('Inactivity flush error:', err.message))
+    }, this.mutationInactivityMs)
+    if (this._inactivityTimer.unref) this._inactivityTimer.unref()
+  }
+
+  async _onInactivityTimeout() {
+    this._inactivityTimer = null
+    const now = Date.now()
+
+    // Simple "inactivity-only" mode: save after any inactivity period if enabled.
+    if (this.autoSaveOnInactivity) {
+      if (this._mutationTimestamps.length > 0) {
+        await this._saveToStorage('inactivity')
+      }
+      // reset history and return early
+      this._mutationTimestamps = []
+      this._lastBurstAt = 0
+      return
+    }
+
+    // count mutations within the burst window (existing burst-detection behavior)
+    const cutoff = now - this.mutationBurstWindowMs
+    const recentCount = this._mutationTimestamps.filter(ts => ts >= cutoff).length
+    if (recentCount >= this.mutationBurstThreshold) {
+      await this._saveToStorage('mutation-burst-inactivity')
+    }
+    // reset history (we only track bursts between inactivity windows)
+    this._mutationTimestamps = []
+    this._lastBurstAt = 0
+  }
+
+  async _saveToStorage(reason = 'manual') {
+    if (!this._vectoria || typeof this._vectoria.saveToStorage !== 'function') return
+    const now = Date.now()
+    if (this._savingInProgress) return
+    if (now - this._lastSaveAt < this.minSaveIntervalMs) return
+    this._savingInProgress = true
+    try {
+      await this._vectoria.saveToStorage()
+      this._lastSaveAt = Date.now()
+      console.log(`[VectoriaDBServer] auto-saved storage (${reason})`)
+    } catch (err) {
+      console.warn('[VectoriaDBServer] auto-save failed:', err.message)
+    } finally {
+      this._savingInProgress = false
+    }
+  }
+
   async close() {
     if (!this._started) return
+    // stop any pending auto-save timer
+    if (this._inactivityTimer) {
+      clearTimeout(this._inactivityTimer)
+      this._inactivityTimer = null
+    }
     // disconnect sockets
     for (const s of Array.from(this._sockets)) {
       try {