@aztec/kv-store 0.66.0 → 0.67.1-devnet

package/src/interfaces/array_test_suite.ts

@@ -0,0 +1,130 @@
+import { toArray } from '@aztec/foundation/iterable';
+
+import { expect } from 'chai';
+
+import { type AztecArray, type AztecAsyncArray } from './array.js';
+import { type AztecAsyncKVStore, type AztecKVStore } from './store.js';
+import { isSyncStore } from './utils.js';
+
+export function describeAztecArray(
+  testName: string,
+  getStore: () => AztecKVStore | Promise<AztecAsyncKVStore>,
+  forceAsync: boolean = false,
+) {
+  describe(testName, () => {
+    let store: AztecKVStore | AztecAsyncKVStore;
+    let arr: AztecArray<number> | AztecAsyncArray<number>;
+
+    beforeEach(async () => {
+      store = await getStore();
+      arr = store.openArray<number>('test');
+    });
+
+    afterEach(async () => {
+      await store.delete();
+    });
+
+    async function length(sut: AztecAsyncArray<number> | AztecArray<number> = arr) {
+      return isSyncStore(store) && !forceAsync
+        ? (sut as AztecArray<number>).length
+        : await (sut as AztecAsyncArray<number>).lengthAsync();
+    }
+
+    async function at(index: number) {
+      return isSyncStore(store) && !forceAsync
+        ? (arr as AztecArray<number>).at(index)
+        : await (arr as AztecAsyncArray<number>).atAsync(index);
+    }
+
+    async function entries() {
+      return isSyncStore(store) && !forceAsync
+        ? await toArray((arr as AztecArray<number>).entries())
+        : await toArray((arr as AztecAsyncArray<number>).entriesAsync());
+    }
+
+    async function values(sut: AztecAsyncArray<number> | AztecArray<number> = arr) {
+      return isSyncStore(store) && !forceAsync
+        ? await toArray((sut as AztecArray<number>).values())
+        : await toArray((sut as AztecAsyncArray<number>).valuesAsync());
+    }
+
+    it('should be able to push and pop values', async () => {
+      await arr.push(1);
+      await arr.push(2);
+      await arr.push(3);
+
+      expect(await length()).to.equal(3);
+
+      expect(await arr.pop()).to.equal(3);
+      expect(await arr.pop()).to.equal(2);
+      expect(await arr.pop()).to.equal(1);
+      expect(await arr.pop()).to.equal(undefined);
+    });
+
+    it('should be able to get values by index', async () => {
+      await arr.push(1);
+      await arr.push(2);
+      await arr.push(3);
+
+      expect(await at(0)).to.equal(1);
+      expect(await at(1)).to.equal(2);
+      expect(await at(2)).to.equal(3);
+      expect(await at(3)).to.equal(undefined);
+      expect(await at(-1)).to.equal(3);
+      expect(await at(-2)).to.equal(2);
+      expect(await at(-3)).to.equal(1);
+      expect(await at(-4)).to.equal(undefined);
+    });
+
+    it('should be able to set values by index', async () => {
+      await arr.push(1);
+      await arr.push(2);
+      await arr.push(3);
+
+      expect(await arr.setAt(0, 4)).to.equal(true);
+      expect(await arr.setAt(1, 5)).to.equal(true);
+      expect(await arr.setAt(2, 6)).to.equal(true);
+
+      expect(await arr.setAt(3, 7)).to.equal(false);
+
+      expect(await at(0)).to.equal(4);
+      expect(await at(1)).to.equal(5);
+      expect(await at(2)).to.equal(6);
+      expect(await at(3)).to.equal(undefined);
+
+      expect(await arr.setAt(-1, 8)).to.equal(true);
+      expect(await arr.setAt(-2, 9)).to.equal(true);
+      expect(await arr.setAt(-3, 10)).to.equal(true);
+
+      expect(await arr.setAt(-4, 11)).to.equal(false);
+
+      expect(await at(-1)).to.equal(8);
+      expect(await at(-2)).to.equal(9);
+      expect(await at(-3)).to.equal(10);
+      expect(await at(-4)).to.equal(undefined);
+    });
+
+    it('should be able to iterate over values', async () => {
+      await arr.push(1);
+      await arr.push(2);
+      await arr.push(3);
+
+      expect(await values()).to.deep.equal([1, 2, 3]);
+      expect(await entries()).to.deep.equal([
+        [0, 1],
+        [1, 2],
+        [2, 3],
+      ]);
+    });
+
+    it('should be able to restore state', async () => {
+      await arr.push(1);
+      await arr.push(2);
+      await arr.push(3);
+
+      const arr2 = store.openArray<number>('test');
+      expect(await length(arr2)).to.equal(3);
+      expect(await values(arr2)).to.deep.equal(await values());
+    });
+  });
+}

package/src/interfaces/counter.ts

@@ -6,7 +6,7 @@ import { type Key, type Range } from './common.js';
  *
  * Keys are stored in sorted order
  */
-export interface AztecCounter<K extends Key = Key> {
+interface AztecBaseCounter<K extends Key = Key> {
   /**
    * Resets the count of the given key to the given value.
    * @param key - The key to reset
@@ -22,7 +22,9 @@ export interface AztecCounter<K extends Key = Key> {
    * @param delta - The amount to modify the key by
    */
   update(key: K, delta: number): Promise<void>;
+}
 
+export interface AztecCounter<K extends Key = Key> extends AztecBaseCounter<K> {
   /**
    * Gets the current count.
    * @param key - The key to get the count of
@@ -41,3 +43,23 @@ export interface AztecCounter<K extends Key = Key> {
    */
   entries(range: Range<K>): IterableIterator<[K, number]>;
 }
+
+export interface AztecAsyncCounter<K extends Key = Key> extends AztecBaseCounter<K> {
+  /**
+   * Gets the current count.
+   * @param key - The key to get the count of
+   */
+  getAsync(key: K): Promise<number>;
+
+  /**
+   * Returns keys in the map in sorted order. Only returns keys that have been seen at least once.
+   * @param range - The range of keys to iterate over
+   */
+  keysAsync(range: Range<K>): AsyncIterableIterator<K>;
+
+  /**
+   * Returns keys and their counts in the map sorted by the key. Only returns keys that have been seen at least once.
+   * @param range - The range of keys to iterate over
+   */
+  entriesAsync(range: Range<K>): AsyncIterableIterator<[K, number]>;
+}

package/src/interfaces/map.ts

@@ -3,20 +3,7 @@ import { type Key, type Range } from './common.js';
 /**
  * A map backed by a persistent store.
  */
-export interface AztecMap<K extends Key, V> {
-  /**
-   * Gets the value at the given key.
-   * @param key - The key to get the value from
-   */
-  get(key: K): V | undefined;
-
-  /**
-   * Checks if a key exists in the map.
-   * @param key - The key to check
-   * @returns True if the key exists, false otherwise
-   */
-  has(key: K): boolean;
-
+interface AztecBaseMap<K extends Key, V> {
   /**
    * Sets the value at the given key.
    * @param key - The key to set the value at
@@ -43,6 +30,20 @@ export interface AztecMap<K extends Key, V> {
    * @param key - The key to delete the value at
    */
   delete(key: K): Promise<void>;
+}
+export interface AztecMap<K extends Key, V> extends AztecBaseMap<K, V> {
+  /**
+   * Gets the value at the given key.
+   * @param key - The key to get the value from
+   */
+  get(key: K): V | undefined;
+
+  /**
+   * Checks if a key exists in the map.
+   * @param key - The key to check
+   * @returns True if the key exists, false otherwise
+   */
+  has(key: K): boolean;
 
   /**
    * Iterates over the map's key-value entries in the key's natural order
@@ -61,6 +62,19 @@ export interface AztecMap<K extends Key, V> {
    * @param range - The range of keys to iterate over
    */
   keys(range?: Range<K>): IterableIterator<K>;
+
+  /**
+   * Clears the map.
+   */
+  clear(): Promise<void>;
+}
+
+export interface AztecMapWithSize<K extends Key, V> extends AztecMap<K, V> {
+  /**
+   * Gets the size of the map.
+   * @returns The size of the map
+   */
+  size(): number;
 }
 
 /**
@@ -80,3 +94,65 @@ export interface AztecMultiMap<K extends Key, V> extends AztecMap<K, V> {
    */
   deleteValue(key: K, val: V): Promise<void>;
 }
+
+export interface AztecMultiMapWithSize<K extends Key, V> extends AztecMultiMap<K, V> {
+  /**
+   * Gets the size of the map.
+   * @returns The size of the map
+   */
+  size(): number;
+}
+
+/**
+ * A map backed by a persistent store.
+ */
+export interface AztecAsyncMap<K extends Key, V> extends AztecBaseMap<K, V> {
+  /**
+   * Gets the value at the given key.
+   * @param key - The key to get the value from
+   */
+  getAsync(key: K): Promise<V | undefined>;
+
+  /**
+   * Checks if a key exists in the map.
+   * @param key - The key to check
+   * @returns True if the key exists, false otherwise
+   */
+  hasAsync(key: K): Promise<boolean>;
+
+  /**
+   * Iterates over the map's key-value entries in the key's natural order
+   * @param range - The range of keys to iterate over
+   */
+  entriesAsync(range?: Range<K>): AsyncIterableIterator<[K, V]>;
+
+  /**
+   * Iterates over the map's values in the key's natural order
+   * @param range - The range of keys to iterate over
+   */
+  valuesAsync(range?: Range<K>): AsyncIterableIterator<V>;
+
+  /**
+   * Iterates over the map's keys in the key's natural order
+   * @param range - The range of keys to iterate over
+   */
+  keysAsync(range?: Range<K>): AsyncIterableIterator<K>;
+}
+
+/**
+ * A map backed by a persistent store that can have multiple values for a single key.
+ */
+export interface AztecAsyncMultiMap<K extends Key, V> extends AztecAsyncMap<K, V> {
+  /**
+   * Gets all the values at the given key.
+   * @param key - The key to get the values from
+   */
+  getValuesAsync(key: K): AsyncIterableIterator<V>;
+
+  /**
+   * Deletes a specific value at the given key.
+   * @param key - The key to delete the value at
+   * @param val - The value to delete
+   */
+  deleteValue(key: K, val: V): Promise<void>;
+}

package/src/interfaces/map_test_suite.ts

@@ -0,0 +1,158 @@
+import { toArray } from '@aztec/foundation/iterable';
+
+import { expect } from 'chai';
+
+import { type Key, type Range } from './common.js';
+import { type AztecAsyncMap, type AztecAsyncMultiMap, type AztecMap, type AztecMultiMap } from './map.js';
+import { type AztecAsyncKVStore, type AztecKVStore } from './store.js';
+import { isSyncStore } from './utils.js';
+
+export function describeAztecMap(
+  testName: string,
+  getStore: () => AztecKVStore | Promise<AztecAsyncKVStore>,
+  forceAsync: boolean = false,
+) {
+  describe(testName, () => {
+    let store: AztecKVStore | AztecAsyncKVStore;
+    let map: AztecMultiMap<Key, string> | AztecAsyncMultiMap<Key, string>;
+
+    beforeEach(async () => {
+      store = await getStore();
+      map = store.openMultiMap<string | [number, string], string>('test');
+    });
+
+    afterEach(async () => {
+      await store.delete();
+    });
+
+    async function get(key: Key, sut: AztecAsyncMap<any, any> | AztecMap<any, any> = map) {
+      return isSyncStore(store) && !forceAsync
+        ? (sut as AztecMultiMap<any, any>).get(key)
+        : await (sut as AztecAsyncMultiMap<any, any>).getAsync(key);
+    }
+
+    async function entries() {
+      return isSyncStore(store) && !forceAsync
+        ? await toArray((map as AztecMultiMap<any, any>).entries())
+        : await toArray((map as AztecAsyncMultiMap<any, any>).entriesAsync());
+    }
+
+    async function values() {
+      return isSyncStore(store) && !forceAsync
+        ? await toArray((map as AztecMultiMap<any, any>).values())
+        : await toArray((map as AztecAsyncMultiMap<any, any>).valuesAsync());
+    }
+
+    async function keys(range?: Range<Key>, sut: AztecAsyncMap<any, any> | AztecMap<any, any> = map) {
+      return isSyncStore(store) && !forceAsync
+        ? await toArray((sut as AztecMultiMap<any, any>).keys(range))
+        : await toArray((sut as AztecAsyncMultiMap<any, any>).keysAsync(range));
+    }
+
+    async function getValues(key: Key) {
+      return isSyncStore(store) && !forceAsync
+        ? await toArray((map as AztecMultiMap<any, any>).getValues(key))
+        : await toArray((map as AztecAsyncMultiMap<any, any>).getValuesAsync(key));
+    }
+
+    it('should be able to set and get values', async () => {
+      await map.set('foo', 'bar');
+      await map.set('baz', 'qux');
+
+      expect(await get('foo')).to.equal('bar');
+      expect(await get('baz')).to.equal('qux');
+      expect(await get('quux')).to.equal(undefined);
+    });
+
+    it('should be able to set values if they do not exist', async () => {
+      expect(await map.setIfNotExists('foo', 'bar')).to.equal(true);
+      expect(await map.setIfNotExists('foo', 'baz')).to.equal(false);
+
+      expect(await get('foo')).to.equal('bar');
+    });
+
+    it('should be able to delete values', async () => {
+      await map.set('foo', 'bar');
+      await map.set('baz', 'qux');
+
+      await map.delete('foo');
+
+      expect(await get('foo')).to.equal(undefined);
+      expect(await get('baz')).to.equal('qux');
+    });
+
+    it('should be able to iterate over entries when there are no keys', async () => {
+      expect(await entries()).to.deep.equal([]);
+    });
+
+    it('should be able to iterate over entries', async () => {
+      await map.set('foo', 'bar');
+      await map.set('baz', 'qux');
+
+      expect(await entries()).to.deep.equal([
+        ['baz', 'qux'],
+        ['foo', 'bar'],
+      ]);
+    });
+
+    it('should be able to iterate over values', async () => {
+      await map.set('foo', 'bar');
+      await map.set('baz', 'quux');
+
+      expect(await values()).to.deep.equal(['quux', 'bar']);
+    });
+
+    it('should be able to iterate over keys', async () => {
+      await map.set('foo', 'bar');
+      await map.set('baz', 'qux');
+
+      expect(await keys()).to.deep.equal(['baz', 'foo']);
+    });
+
+    it('should be able to get multiple values for a single key', async () => {
+      await map.set('foo', 'bar');
+      await map.set('foo', 'baz');
+
+      expect(await getValues('foo')).to.deep.equal(['bar', 'baz']);
+    });
+
+    it('should be able to delete individual values for a single key', async () => {
+      await map.set('foo', 'bar');
+      await map.set('foo', 'baz');
+
+      await map.deleteValue('foo', 'bar');
+
+      expect(await getValues('foo')).to.deep.equal(['baz']);
+    });
+
+    it('supports tuple keys', async () => {
+      // Use a new map because key structure has changed
+      const tupleMap = store.openMap<[number, string], string>('test-tuple');
+
+      await tupleMap.set([5, 'bar'], 'val');
+      await tupleMap.set([0, 'foo'], 'val');
+
+      expect(await keys(undefined, tupleMap)).to.deep.equal([
+        [0, 'foo'],
+        [5, 'bar'],
+      ]);
+
+      expect(await get([5, 'bar'], tupleMap)).to.equal('val');
+    });
+
+    it('supports range queries', async () => {
+      await map.set('a', 'a');
+      await map.set('b', 'b');
+      await map.set('c', 'c');
+      await map.set('d', 'd');
+
+      expect(await keys({ start: 'b', end: 'c' })).to.deep.equal(['b']);
+      expect(await keys({ start: 'b' })).to.deep.equal(['b', 'c', 'd']);
+      expect(await keys({ end: 'c' })).to.deep.equal(['a', 'b']);
+      expect(await keys({ start: 'b', end: 'c', reverse: true })).to.deep.equal(['c']);
+      expect(await keys({ start: 'b', limit: 1 })).to.deep.equal(['b']);
+      expect(await keys({ start: 'b', reverse: true })).to.deep.equal(['d', 'c']);
+      expect(await keys({ end: 'b', reverse: true })).to.deep.equal(['b', 'a']);
+    });
+  });
+}

package/src/interfaces/set.ts

@@ -3,14 +3,7 @@ import { type Key, type Range } from './common.js';
 /**
  * A set backed by a persistent store.
  */
-export interface AztecSet<K extends Key> {
-  /**
-   * Checks if a key exists in the set.
-   * @param key - The key to check
-   * @returns True if the key exists, false otherwise
-   */
-  has(key: K): boolean;
-
+interface AztecBaseSet<K extends Key> {
   /**
    * Adds the given value.
    * @param key - The key to add.
@@ -22,6 +15,15 @@ export interface AztecSet<K extends Key> {
    * @param key - The key to delete.
    */
   delete(key: K): Promise<void>;
+}
+
+export interface AztecSet<K extends Key> extends AztecBaseSet<K> {
+  /**
+   * Checks if a key exists in the set.
+   * @param key - The key to check
+   * @returns True if the key exists, false otherwise
+   */
+  has(key: K): boolean;
 
   /**
    * Iterates over the sets's keys entries in the key's natural order
@@ -29,3 +31,18 @@ export interface AztecSet<K extends Key> {
    */
   entries(range?: Range<K>): IterableIterator<K>;
 }
+
+export interface AztecAsyncSet<K extends Key> extends AztecBaseSet<K> {
+  /**
+   * Checks if a key exists in the set.
+   * @param key - The key to check
+   * @returns True if the key exists, false otherwise
+   */
+  hasAsync(key: K): Promise<boolean>;
+
+  /**
+   * Iterates over the sets's keys entries in the key's natural order
+   * @param range - The range of keys to iterate over
+   */
+  entriesAsync(range?: Range<K>): AsyncIterableIterator<K>;
+}

package/src/interfaces/set_test_suite.ts

@@ -0,0 +1,81 @@
+import { toArray } from '@aztec/foundation/iterable';
+
+import { expect } from 'chai';
+
+import { type Range } from './common.js';
+import { type AztecAsyncSet, type AztecSet } from './set.js';
+import { type AztecAsyncKVStore, type AztecKVStore } from './store.js';
+import { isSyncStore } from './utils.js';
+
+export function describeAztecSet(
+  testName: string,
+  getStore: () => AztecKVStore | Promise<AztecAsyncKVStore>,
+  forceAsync: boolean = false,
+) {
+  describe(testName, () => {
+    let store: AztecKVStore | AztecAsyncKVStore;
+    let set: AztecSet<string> | AztecAsyncSet<string>;
+
+    beforeEach(async () => {
+      store = await getStore();
+      set = store.openSet<string>('test');
+    });
+
+    afterEach(async () => {
+      await store.delete();
+    });
+
+    async function has(key: string) {
+      return isSyncStore(store) && !forceAsync
+        ? (set as AztecSet<string>).has(key)
+        : await (set as AztecAsyncSet<string>).hasAsync(key);
+    }
+
+    async function entries(range?: Range<any>) {
+      return isSyncStore(store) && !forceAsync
+        ? await toArray((set as AztecSet<string>).entries(range))
+        : await toArray((set as AztecAsyncSet<string>).entriesAsync(range));
+    }
+
+    it('should be able to set and get values', async () => {
+      await set.add('foo');
+      await set.add('baz');
+
+      expect(await has('foo')).to.equal(true);
+      expect(await has('baz')).to.equal(true);
+      expect(await has('bar')).to.equal(false);
+    });
+
+    it('should be able to delete values', async () => {
+      await set.add('foo');
+      await set.add('baz');
+
+      await set.delete('foo');
+
+      expect(await has('foo')).to.equal(false);
+      expect(await has('baz')).to.equal(true);
+    });
+
+    it('should be able to iterate over entries', async () => {
+      await set.add('baz');
+      await set.add('foo');
+
+      expect(await entries()).to.deep.equal(['baz', 'foo']);
+    });
+
+    it('supports range queries', async () => {
+      await set.add('a');
+      await set.add('b');
+      await set.add('c');
+      await set.add('d');
+
+      expect(await entries({ start: 'b', end: 'c' })).to.deep.equal(['b']);
+      expect(await entries({ start: 'b' })).to.deep.equal(['b', 'c', 'd']);
+      expect(await entries({ end: 'c' })).to.deep.equal(['a', 'b']);
+      expect(await entries({ start: 'b', end: 'c', reverse: true })).to.deep.equal(['c']);
+      expect(await entries({ start: 'b', limit: 1 })).to.deep.equal(['b']);
+      expect(await entries({ start: 'b', reverse: true })).to.deep.equal(['d', 'c']);
+      expect(await entries({ end: 'b', reverse: true })).to.deep.equal(['b', 'a']);
+    });
+  });
+}

package/src/interfaces/singleton.ts

@@ -2,12 +2,7 @@
  * Represents a singleton value in the database.
  * Note: The singleton loses type info so it's recommended to serialize to buffer when storing it.
  */
-export interface AztecSingleton<T> {
-  /**
-   * Gets the value.
-   */
-  get(): T | undefined;
-
+interface AztecBaseSingleton<T> {
   /**
    * Sets the value.
    * @param val - The new value
@@ -19,3 +14,16 @@ export interface AztecSingleton<T> {
    */
   delete(): Promise<boolean>;
 }
+export interface AztecSingleton<T> extends AztecBaseSingleton<T> {
+  /**
+   * Gets the value.
+   */
+  get(): T | undefined;
+}
+
+export interface AztecAsyncSingleton<T> extends AztecBaseSingleton<T> {
+  /**
+   * Gets the value.
+   */
+  getAsync(): Promise<T | undefined>;
+}

package/src/interfaces/singleton_test_suite.ts

@@ -0,0 +1,46 @@
+import { expect } from 'chai';
+
+import { type AztecAsyncSingleton, type AztecSingleton } from './singleton.js';
+import { type AztecAsyncKVStore, type AztecKVStore } from './store.js';
+import { isSyncStore } from './utils.js';
+
+export function describeAztecSingleton(
+  testName: string,
+  getStore: () => AztecKVStore | Promise<AztecAsyncKVStore>,
+  forceAsync: boolean = false,
+) {
+  describe(testName, () => {
+    let store: AztecKVStore | AztecAsyncKVStore;
+    let singleton: AztecSingleton<string> | AztecAsyncSingleton<string>;
+
+    beforeEach(async () => {
+      store = await getStore();
+      singleton = store.openSingleton<string>('test');
+    });
+
+    afterEach(async () => {
+      await store.delete();
+    });
+
+    async function get() {
+      return isSyncStore(store) && !forceAsync
+        ? (singleton as AztecSingleton<string>).get()
+        : await (singleton as AztecAsyncSingleton<string>).getAsync();
+    }
+
+    it('returns undefined if the value is not set', async () => {
+      expect(await get()).to.equal(undefined);
+    });
+
+    it('should be able to set and get values', async () => {
+      expect(await singleton.set('foo')).to.equal(true);
+      expect(await get()).to.equal('foo');
+    });
+
+    it('overwrites the value if it is set again', async () => {
+      expect(await singleton.set('foo')).to.equal(true);
+      expect(await singleton.set('bar')).to.equal(true);
+      expect(await get()).to.equal('bar');
+    });
+  });
+}