libp2r2p 0.10.22 → 0.10.23

package/README.md

@@ -820,6 +820,24 @@ The NIP-94 extension also carries optional `download` intent; see
 
 ## Reliable IndexedDB queue reservations
 
+`queue.putBy(indexName, item, { existingOnly = false })` atomically inserts or
+replaces an item through a declared unique, non-multiEntry index. Its key is
+extracted from the item's index keyPath, including nested paths and compound
+keys. Existing items retain their position; new keys append to the tail. It
+returns `true` after commit, or `false` without inserting when `existingOnly`
+is true and the key is absent. This allows late progress checkpoints to avoid
+recreating a cancelled record. Values are cloned before asynchronous work.
+
+Unknown, non-unique or multiEntry indexes throw `ValidationError` with
+`QUEUE_PUT_INDEX_INVALID`; missing or invalid IndexedDB keys use
+`QUEUE_PUT_KEY_INVALID`. Cloning, storage and other unique-index failures retain
+their operational errors. Lookup, replacement and byte accounting share one
+transaction and roll back together. Capacity policy matches `setAt` for a
+replacement and `push` for an insertion. Replacing a reserved item invalidates
+the old token: its `ack`, `nack` and `renew` return false. Successful writes wake
+local waiting consumers. Like the other indexed methods, `putBy` is exclusive
+to `idb-queue`; the Web Storage queue's common API is unchanged.
+
 `createQueue({ prefix, evictionPolicy: 'reject', maxBytes })` opts out of
 capacity eviction. Oversized items reject with `QUEUE_ITEM_TOO_LARGE`, full
 queues with `QUEUE_CAPACITY_EXCEEDED`; browser quota errors propagate without

package/idb-queue/index.js

@@ -725,6 +725,34 @@ export async function createQueue ({
     })
   }
 
+  async function putBy (indexName, item, { existingOnly = false } = {}) {
+    const definition = indexDefinitions.find(index => index.name === indexName)
+    if (!definition?.unique || definition.multiEntry) throw new ValidationError('QUEUE_PUT_INDEX_INVALID')
+    // Snapshot before awaiting IndexedDB so the lookup key and stored value
+    // cannot diverge if the caller changes its object during the transaction.
+    const value = structuredClone(item)
+    const readKey = path => path.split('.').reduce((part, key) => part?.[key], value)
+    const key = Array.isArray(definition.keyPath) ? definition.keyPath.map(readKey) : readKey(definition.keyPath)
+    try { indexedDB.cmp(key, key) } catch { throw new ValidationError('QUEUE_PUT_KEY_INVALID') }
+    const requiredBytes = itemForStorage(0, value).byteSize
+    const written = await mutate(async (tx, state) => {
+      const { result: previous } = await run('get', [key], ITEMS_STORE, indexName, { tx })
+      if (previous) {
+        const index = previous.position - state.head
+        await putItem(tx, state, previous.position, value, {
+          direction: evictionDirectionFor('setAt', { index, length: state.tail - state.head }),
+          protectedPositions: new Set([previous.position])
+        })
+      } else {
+        if (existingOnly) return false
+        await pushInTransaction(tx, state, value)
+      }
+      return true
+    }, { requiredBytes })
+    if (written) wake()
+    return written
+  }
+
   async function getBy (indexName, query) {
     // Explicit index operations avoid scanning queue values in JavaScript.
     return snapshot(async tx => {
@@ -899,6 +927,7 @@ export async function createQueue ({
     removeWhere,
     some,
     clear,
+    putBy,
     getBy,
     someBy,
     removeBy,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libp2r2p",
-  "version": "0.10.22",
+  "version": "0.10.23",
   "description": "Peer-to-relay-to-peer",
   "keywords": [
     "p2r2p",