@aztec/kv-store 0.0.0-test.0

package/src/interfaces/map_test_suite.ts

@@ -0,0 +1,143 @@
+import { toArray } from '@aztec/foundation/iterable';
+
+import { expect } from 'chai';
+
+import type { Key, Range } from './common.js';
+import type { AztecAsyncMap, AztecAsyncMultiMap, AztecMap, AztecMultiMap } from './map.js';
+import type { AztecAsyncKVStore, 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, 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 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

@@ -0,0 +1,48 @@
+import type { Key, Range } from './common.js';
+
+/**
+ * A set backed by a persistent store.
+ */
+interface AztecBaseSet<K extends Key> {
+  /**
+   * Adds the given value.
+   * @param key - The key to add.
+   */
+  add(key: K): Promise<void>;
+
+  /**
+   * Deletes the given 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
+   * @param range - The range of keys to iterate over
+   */
+  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, AztecSet } from './set.js';
+import type { AztecAsyncKVStore, 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

@@ -0,0 +1,29 @@
+/**
+ * Represents a singleton value in the database.
+ * Note: The singleton loses type info so it's recommended to serialize to buffer when storing it.
+ */
+interface AztecBaseSingleton<T> {
+  /**
+   * Sets the value.
+   * @param val - The new value
+   */
+  set(val: T): Promise<boolean>;
+
+  /**
+   * Deletes the value.
+   */
+  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, AztecSingleton } from './singleton.js';
+import type { AztecAsyncKVStore, 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');
+    });
+  });
+}

package/src/interfaces/store.ts

@@ -0,0 +1,177 @@
+import type { AztecArray, AztecAsyncArray } from './array.js';
+import type { Key, StoreSize } from './common.js';
+import type { AztecAsyncCounter, AztecCounter } from './counter.js';
+import type {
+  AztecAsyncMap,
+  AztecAsyncMultiMap,
+  AztecMap,
+  AztecMapWithSize,
+  AztecMultiMap,
+  AztecMultiMapWithSize,
+} from './map.js';
+import type { AztecAsyncSet, AztecSet } from './set.js';
+import type { AztecAsyncSingleton, AztecSingleton } from './singleton.js';
+
+/** A key-value store */
+export interface AztecKVStore {
+  syncGetters: true;
+  /**
+   * Creates a new map.
+   * @param name - The name of the map
+   * @returns The map
+   */
+  openMap<K extends Key, V>(name: string): AztecMap<K, V>;
+
+  /**
+   * Creates a new set.
+   * @param name - The name of the set
+   * @returns The set
+   */
+  openSet<K extends Key>(name: string): AztecSet<K>;
+
+  /**
+   * Creates a new multi-map.
+   * @param name - The name of the multi-map
+   * @returns The multi-map
+   */
+  openMultiMap<K extends Key, V>(name: string): AztecMultiMap<K, V>;
+
+  /**
+   * Creates a new multi-map with size.
+   * @param name - The name of the multi-map
+   * @returns The multi-map
+   */
+  openMultiMapWithSize<K extends Key, V>(name: string): AztecMultiMapWithSize<K, V>;
+
+  /**
+   * Creates a new map with size.
+   * @param name - The name of the map
+   * @returns The map
+   */
+  openMapWithSize<K extends Key, V>(name: string): AztecMapWithSize<K, V>;
+
+  /**
+   * Creates a new array.
+   * @param name - The name of the array
+   * @returns The array
+   */
+  openArray<T>(name: string): AztecArray<T>;
+
+  /**
+   * Creates a new singleton.
+   * @param name - The name of the singleton
+   * @returns The singleton
+   */
+  openSingleton<T>(name: string): AztecSingleton<T>;
+
+  /**
+   * Creates a new count map.
+   * @param name - name of the counter
+   */
+  openCounter<K extends Key>(name: string): AztecCounter<K>;
+
+  /**
+   * Starts a transaction. All calls to read/write data while in a transaction are queued and executed atomically.
+   * @param callback - The callback to execute in a transaction
+   */
+  transaction<T extends Exclude<any, Promise<any>>>(callback: () => T): Promise<T>;
+
+  /**
+   * Clears all entries in the store
+   */
+  clear(): Promise<void>;
+
+  /**
+   * Forks the store.
+   */
+  fork(): Promise<AztecKVStore>;
+
+  /**
+   * Deletes the store
+   */
+  delete(): Promise<void>;
+
+  /**
+   * Estimates the size of the store in bytes.
+   */
+  estimateSize(): Promise<StoreSize>;
+
+  /**
+   * Closes the store
+   */
+  close(): Promise<void>;
+}
+
+export interface AztecAsyncKVStore {
+  /**
+   * Creates a new map.
+   * @param name - The name of the map
+   * @returns The map
+   */
+  openMap<K extends Key, V>(name: string): AztecAsyncMap<K, V>;
+
+  /**
+   * Creates a new set.
+   * @param name - The name of the set
+   * @returns The set
+   */
+  openSet<K extends Key>(name: string): AztecAsyncSet<K>;
+
+  /**
+   * Creates a new multi-map.
+   * @param name - The name of the multi-map
+   * @returns The multi-map
+   */
+  openMultiMap<K extends Key, V>(name: string): AztecAsyncMultiMap<K, V>;
+
+  /**
+   * Creates a new array.
+   * @param name - The name of the array
+   * @returns The array
+   */
+  openArray<T>(name: string): AztecAsyncArray<T>;
+
+  /**
+   * Creates a new singleton.
+   * @param name - The name of the singleton
+   * @returns The singleton
+   */
+  openSingleton<T>(name: string): AztecAsyncSingleton<T>;
+
+  /**
+   * Creates a new count map.
+   * @param name - name of the counter
+   */
+  openCounter<K extends Key>(name: string): AztecAsyncCounter<K>;
+
+  /**
+   * Starts a transaction. All calls to read/write data while in a transaction are queued and executed atomically.
+   * @param callback - The callback to execute in a transaction
+   */
+  transactionAsync<T extends Exclude<any, Promise<any>>>(callback: () => Promise<T>): Promise<T>;
+
+  /**
+   * Clears all entries in the store
+   */
+  clear(): Promise<void>;
+
+  /**
+   * Forks the store.
+   */
+  fork(): Promise<AztecAsyncKVStore>;
+
+  /**
+   * Deletes the store
+   */
+  delete(): Promise<void>;
+
+  /**
+   * Estimates the size of the store in bytes.
+   */
+  estimateSize(): Promise<StoreSize>;
+
+  /**
+   * Closes the store
+   */
+  close(): Promise<void>;
+}

package/src/interfaces/store_test_suite.ts

@@ -0,0 +1,56 @@
+import { expect } from 'chai';
+
+import type { AztecAsyncSingleton, AztecSingleton } from './singleton.js';
+import type { AztecAsyncKVStore, AztecKVStore } from './store.js';
+import { isSyncStore } from './utils.js';
+
+export function describeAztecStore(
+  testName: string,
+  getPersistentStore: () => Promise<AztecKVStore | AztecAsyncKVStore>,
+  getPersistentNoPathStore: () => Promise<AztecKVStore | AztecAsyncKVStore>,
+  getEphemeralStore: () => Promise<AztecKVStore | AztecAsyncKVStore>,
+) {
+  describe(testName, () => {
+    async function get(
+      store: AztecKVStore | AztecAsyncKVStore,
+      singleton: AztecSingleton<string> | AztecAsyncSingleton<string>,
+    ) {
+      return isSyncStore(store)
+        ? (singleton as AztecSingleton<string>).get()
+        : await (singleton as AztecAsyncSingleton<string>).getAsync();
+    }
+
+    const itForks = async (store: AztecKVStore | AztecAsyncKVStore) => {
+      const singleton = store.openSingleton<string>('singleton');
+      await singleton.set('foo');
+
+      const forkedStore = await store.fork();
+      const forkedSingleton = forkedStore.openSingleton<string>('singleton');
+      expect(await get(store, singleton)).to.equal('foo');
+      await forkedSingleton.set('bar');
+      expect(await get(store, singleton)).to.equal('foo');
+      expect(await get(forkedStore, forkedSingleton)).to.equal('bar');
+      await forkedSingleton.delete();
+      expect(await get(store, singleton)).to.equal('foo');
+      await forkedStore.delete();
+    };
+
+    it('forks a persistent store', async () => {
+      const store = await getPersistentStore();
+      await itForks(store);
+      await store.delete();
+    });
+
+    it('forks a persistent store with no path', async () => {
+      const store = await getPersistentNoPathStore();
+      await itForks(store);
+      await store.delete();
+    });
+
+    it('forks an ephemeral store', async () => {
+      const store = await getEphemeralStore();
+      await itForks(store);
+      await store.delete();
+    });
+  });
+}

package/src/interfaces/utils.ts

@@ -0,0 +1,21 @@
+import type { AztecAsyncKVStore, AztecKVStore } from './store.js';
+
+/* eslint-disable no-console */
+export const mockLogger = {
+  debug: (msg: string, data: any) => console.log(msg, data),
+  info: (msg: string, data: any) => console.log(msg, data),
+  warn: (msg: string, data: any) => console.log(msg, data),
+  error: (msg: string, data: any) => console.error(msg, data),
+  fatal: (msg: string, data: any) => console.error(msg, data),
+  silent: (_msg: string, _data: any) => {},
+  verbose: (msg: string, data: any) => console.log(msg, data),
+  trace: (msg: string, data: any) => console.log(msg, data),
+  level: 'trace' as const,
+  isLevelEnabled: (_level: string) => true,
+  module: 'kv-store:mock-logger',
+};
+/* eslint-enable no-console */
+
+export function isSyncStore(store: AztecKVStore | AztecAsyncKVStore): store is AztecAsyncKVStore {
+  return (store as AztecKVStore).syncGetters === true;
+}