feat: add suport for entries() returning results in descending order (#46)

* feat: add suport for entries() returning results in descending order

* updates based on review by @alanshaw

---------

Co-authored-by: Chris Hafey <chafey@Chriss-MBP.localdomain>

Author: chafey

src/api.ts

@@ -86,6 +86,14 @@ export interface KeyUpperBoundRangeInclusiveOption {
   lte: string
 }
 
+export interface KeyOrderOption {
+  /** Order to return results: 'asc' for ascending (default), 'desc' for descending. */
+  order: 'asc' | 'desc'
+}
+
 export type EntriesOptions =
   | KeyPrefixOption
   | KeyRangeOption
+  | KeyOrderOption
+  | (KeyPrefixOption & KeyOrderOption)
+  | (KeyRangeOption & KeyOrderOption)

src/index.js

@@ -294,6 +294,15 @@ const isKeyUpperBoundRangeInclusiveOption = options => 'lte' in options && Boole
  */
 const isKeyUpperBoundRangeExclusiveOption = options => 'lt' in options && Boolean(options.lt)
 
+/**
+ * @param {API.EntriesOptions} [options]
+ * @returns {options is API.KeyOrderOption}
+ */
+const isKeyOrderOption = options => {
+  const opts = options ?? {}
+  return 'order' in opts && (opts.order === 'asc' || opts.order === 'desc')
+}
+
 /**
  * List entries in the bucket.
  *
@@ -305,6 +314,8 @@ const isKeyUpperBoundRangeExclusiveOption = options => 'lt' in options && Boolea
 export const entries = async function * (blocks, root, options) {
   const hasKeyPrefix = isKeyPrefixOption(options)
   const hasKeyRange = isKeyRangeOption(options)
+  const hasKeyOrder = isKeyOrderOption(options)
+  const isDescending = hasKeyOrder && options.order === 'desc'
   const hasKeyLowerBoundRange = hasKeyRange && isKeyLowerBoundRangeOption(options)
   const hasKeyLowerBoundRangeInclusive = hasKeyLowerBoundRange && isKeyLowerBoundRangeInclusiveOption(options)
   const hasKeyLowerBoundRangeExclusive = hasKeyLowerBoundRange && isKeyLowerBoundRangeExclusiveOption(options)
@@ -319,7 +330,12 @@ export const entries = async function * (blocks, root, options) {
   yield * (
     /** @returns {AsyncIterableIterator<API.ShardValueEntry>} */
     async function * ents (shard) {
-      for (const entry of shard.value.entries) {
+      const entriesLength = shard.value.entries.length
+
+      for (let idx = 0; idx < entriesLength; idx++) {
+        // Calculate the actual index based on order
+        const i = isDescending ? entriesLength - 1 - idx : idx
+        const entry = shard.value.entries[i]
         const key = shard.value.prefix + entry[0]
 
         // if array, this is a link to a shard

test/entries.test.js

@@ -242,4 +242,145 @@ describe('entries', () => {
       assert.equal(results[i][0], key)
     }
   })
+
+  it('lists entries in ascending order (explicit)', async () => {
+    const empty = await ShardBlock.create()
+    const blocks = new Blockstore()
+    await blocks.put(empty.cid, empty.bytes)
+
+    /** @type {Array<[string, API.UnknownLink]>} */
+    const testdata = [
+      ['c', await randomCID(32)],
+      ['d', await randomCID(32)],
+      ['a', await randomCID(32)],
+      ['b', await randomCID(32)]
+    ]
+
+    /** @type {API.ShardLink} */
+    let root = empty.cid
+    for (const [k, v] of testdata) {
+      const res = await put(blocks, root, k, v)
+      for (const b of res.additions) {
+        await blocks.put(b.cid, b.bytes)
+      }
+      root = res.root
+    }
+
+    const results = []
+    for await (const entry of entries(blocks, root, { order: 'asc' })) {
+      results.push(entry)
+    }
+
+    const sortedKeys = testdata.map(d => d[0]).sort()
+    for (const [i, key] of sortedKeys.entries()) {
+      assert.equal(results[i][0], key)
+    }
+  })
+
+  it('lists entries in descending order', async () => {
+    const empty = await ShardBlock.create()
+    const blocks = new Blockstore()
+    await blocks.put(empty.cid, empty.bytes)
+
+    /** @type {Array<[string, API.UnknownLink]>} */
+    const testdata = [
+      ['c', await randomCID(32)],
+      ['d', await randomCID(32)],
+      ['a', await randomCID(32)],
+      ['b', await randomCID(32)]
+    ]
+
+    /** @type {API.ShardLink} */
+    let root = empty.cid
+    for (const [k, v] of testdata) {
+      const res = await put(blocks, root, k, v)
+      for (const b of res.additions) {
+        await blocks.put(b.cid, b.bytes)
+      }
+      root = res.root
+    }
+
+    const results = []
+    for await (const entry of entries(blocks, root, { order: 'desc' })) {
+      results.push(entry)
+    }
+
+    const sortedKeys = testdata.map(d => d[0]).sort().reverse()
+    for (const [i, key] of sortedKeys.entries()) {
+      assert.equal(results[i][0], key)
+    }
+  })
+
+  it('lists entries by prefix in descending order', async () => {
+    const empty = await ShardBlock.create()
+    const blocks = new Blockstore()
+    await blocks.put(empty.cid, empty.bytes)
+
+    /** @type {Array<[string, API.UnknownLink]>} */
+    const testdata = [
+      ['dccc', await randomCID(32)],
+      ['deee', await randomCID(32)],
+      ['dooo', await randomCID(32)],
+      ['daaa', await randomCID(32)],
+      ['beee', await randomCID(32)]
+    ]
+
+    /** @type {API.ShardLink} */
+    let root = empty.cid
+    for (const [k, v] of testdata) {
+      const res = await put(blocks, root, k, v)
+      for (const b of res.additions) {
+        await blocks.put(b.cid, b.bytes)
+      }
+      root = res.root
+    }
+
+    const prefix = 'd'
+    const results = []
+    for await (const entry of entries(blocks, root, { prefix, order: 'desc' })) {
+      results.push(entry)
+    }
+
+    const filteredAndSorted = testdata.map(d => d[0]).filter(k => k.startsWith(prefix)).sort().reverse()
+    for (const [i, key] of filteredAndSorted.entries()) {
+      assert.equal(results[i][0], key)
+    }
+  })
+
+  it('lists entries by range in descending order', async () => {
+    const empty = await ShardBlock.create()
+    const blocks = new Blockstore()
+    await blocks.put(empty.cid, empty.bytes)
+
+    /** @type {Array<[string, API.UnknownLink]>} */
+    const testdata = [
+      ['aaaa', await randomCID(32)],
+      ['cccc', await randomCID(32)],
+      ['deee', await randomCID(32)],
+      ['dooo', await randomCID(32)],
+      ['eeee', await randomCID(32)]
+    ]
+
+    /** @type {API.ShardLink} */
+    let root = empty.cid
+    for (const [k, v] of testdata) {
+      const res = await put(blocks, root, k, v)
+      for (const b of res.additions) {
+        await blocks.put(b.cid, b.bytes)
+      }
+      root = res.root
+    }
+
+    const gte = 'c'
+    const lt = 'e'
+    const results = []
+    for await (const entry of entries(blocks, root, { gte, lt, order: 'desc' })) {
+      results.push(entry)
+    }
+
+    const filteredAndSorted = testdata.map(d => d[0]).filter(k => k >= gte && k < lt).sort().reverse()
+    for (const [i, key] of filteredAndSorted.entries()) {
+      assert.equal(results[i][0], key)
+    }
+  })
 })