feat: bulk insert records

Expose a method to run an array of prepared queries in a transaction.

docs: bulk

buffer benches

Author: gregdaynes

README.md

@@ -145,3 +145,33 @@ holder.set('accounts', 'account-123:user-123:name', 'Alice')
 console.log(holder.get('accounts', 'account-123:*:name'))
 // => [['account-123:user-123:name', 'Alice']]
 ```
+
+### Bulk Insertion
+
+Bulk insertion leverages transactions to insert a batch of records, prepared ahead of time.
+
+> [!CAUTION]
+> When using transactions, if one insert fails, the batch is discarded.
+
+```js
+import hold from 'hold-this'
+
+const holder = hold({ turbo: true })
+
+const entries = Array.from(Array(3))
+	.map((_, i) => holder.prepare('bulk', `key:${i}`, `value${i}`))
+
+holder.setBulk('bulk', 'key', entries)
+
+console.log(holder.get('bulk', 'key:*'))
+// => [['key:0', 'value0'], ['key:1', 'value1'], ['key:2', 'value2']]
+```
+
+| Run | Time (ms) | Record Count | Records (per ms)|
+|-----|-----------|--------------|-----------------|
+| 9   | 309.484   | 402861       | 1301.718        |
+| 3   | 290.291   | 377501       | 1300.425        |
+| 5   | 295.262   | 377501       | 1278.528        |
+
+_Using Turbo Mode_
+_Performed on Macbook Pro M1 with 16 GB Memory_

index.js

@@ -160,6 +160,25 @@ export class KVStore {
     }
   }
 
+  /**
+   * Set multiple values in the key-value store.
+   * @param {string} topic The topic to set the values in.
+   * @param {string} key The key to set the values for.
+   * @param {Array.<Array.<string, string>>} entries The entries to set. Each entry should be a valid sql query.
+   * @returns {boolean} True if the values were set.
+   */
+  setBulk (topic = 'topic', key, entries) {
+    if (!this.#topics[topic]) this.init(topic, key)
+
+    this.#connection.tx((transaction) => {
+      for (const entry of entries) {
+        transaction.query(entry)
+      }
+    })
+
+    return true
+  }
+
   /**
    * Get a value from the key-value store.
    * @param {string} topic The topic to get the value from.