@aztec-labs/kv-store 6.0.0-nightly.20260829

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (246) hide show
  1. package/README.md +19 -0
  2. package/dest/bench/shared_map_bench.d.ts +19 -0
  3. package/dest/bench/shared_map_bench.d.ts.map +1 -0
  4. package/dest/bench/shared_map_bench.js +91 -0
  5. package/dest/deprecated/indexeddb/array.d.ts +22 -0
  6. package/dest/deprecated/indexeddb/array.d.ts.map +1 -0
  7. package/dest/deprecated/indexeddb/array.js +121 -0
  8. package/dest/deprecated/indexeddb/index.d.ts +7 -0
  9. package/dest/deprecated/indexeddb/index.d.ts.map +1 -0
  10. package/dest/deprecated/indexeddb/index.js +8 -0
  11. package/dest/deprecated/indexeddb/map.d.ts +38 -0
  12. package/dest/deprecated/indexeddb/map.d.ts.map +1 -0
  13. package/dest/deprecated/indexeddb/map.js +121 -0
  14. package/dest/deprecated/indexeddb/multi_map.d.ts +14 -0
  15. package/dest/deprecated/indexeddb/multi_map.d.ts.map +1 -0
  16. package/dest/deprecated/indexeddb/multi_map.js +108 -0
  17. package/dest/deprecated/indexeddb/set.d.ts +17 -0
  18. package/dest/deprecated/indexeddb/set.d.ts.map +1 -0
  19. package/dest/deprecated/indexeddb/set.js +24 -0
  20. package/dest/deprecated/indexeddb/singleton.d.ts +17 -0
  21. package/dest/deprecated/indexeddb/singleton.d.ts.map +1 -0
  22. package/dest/deprecated/indexeddb/singleton.js +41 -0
  23. package/dest/deprecated/indexeddb/store.d.ts +98 -0
  24. package/dest/deprecated/indexeddb/store.d.ts.map +1 -0
  25. package/dest/deprecated/indexeddb/store.js +171 -0
  26. package/dest/interfaces/array.d.ts +81 -0
  27. package/dest/interfaces/array.d.ts.map +1 -0
  28. package/dest/interfaces/array.js +1 -0
  29. package/dest/interfaces/array_test_suite.d.ts +3 -0
  30. package/dest/interfaces/array_test_suite.d.ts.map +1 -0
  31. package/dest/interfaces/array_test_suite.js +103 -0
  32. package/dest/interfaces/common.d.ts +25 -0
  33. package/dest/interfaces/common.d.ts.map +1 -0
  34. package/dest/interfaces/common.js +8 -0
  35. package/dest/interfaces/counter.d.ts +59 -0
  36. package/dest/interfaces/counter.d.ts.map +1 -0
  37. package/dest/interfaces/counter.js +1 -0
  38. package/dest/interfaces/index.d.ts +10 -0
  39. package/dest/interfaces/index.d.ts.map +1 -0
  40. package/dest/interfaces/index.js +8 -0
  41. package/dest/interfaces/map.d.ts +106 -0
  42. package/dest/interfaces/map.d.ts.map +1 -0
  43. package/dest/interfaces/map.js +3 -0
  44. package/dest/interfaces/map_test_suite.d.ts +3 -0
  45. package/dest/interfaces/map_test_suite.d.ts.map +1 -0
  46. package/dest/interfaces/map_test_suite.js +261 -0
  47. package/dest/interfaces/multi_map.d.ts +41 -0
  48. package/dest/interfaces/multi_map.d.ts.map +1 -0
  49. package/dest/interfaces/multi_map.js +3 -0
  50. package/dest/interfaces/multi_map_test_suite.d.ts +3 -0
  51. package/dest/interfaces/multi_map_test_suite.d.ts.map +1 -0
  52. package/dest/interfaces/multi_map_test_suite.js +363 -0
  53. package/dest/interfaces/set.d.ts +44 -0
  54. package/dest/interfaces/set.d.ts.map +1 -0
  55. package/dest/interfaces/set.js +1 -0
  56. package/dest/interfaces/set_test_suite.d.ts +3 -0
  57. package/dest/interfaces/set_test_suite.d.ts.map +1 -0
  58. package/dest/interfaces/set_test_suite.js +95 -0
  59. package/dest/interfaces/singleton.d.ts +29 -0
  60. package/dest/interfaces/singleton.d.ts.map +1 -0
  61. package/dest/interfaces/singleton.js +4 -0
  62. package/dest/interfaces/singleton_test_suite.d.ts +3 -0
  63. package/dest/interfaces/singleton_test_suite.d.ts.map +1 -0
  64. package/dest/interfaces/singleton_test_suite.js +29 -0
  65. package/dest/interfaces/store.d.ts +120 -0
  66. package/dest/interfaces/store.d.ts.map +1 -0
  67. package/dest/interfaces/store.js +1 -0
  68. package/dest/interfaces/utils.d.ts +18 -0
  69. package/dest/interfaces/utils.d.ts.map +1 -0
  70. package/dest/interfaces/utils.js +18 -0
  71. package/dest/lmdb/array.d.ts +24 -0
  72. package/dest/lmdb/array.d.ts.map +1 -0
  73. package/dest/lmdb/array.js +119 -0
  74. package/dest/lmdb/counter.d.ts +19 -0
  75. package/dest/lmdb/counter.d.ts.map +1 -0
  76. package/dest/lmdb/counter.js +50 -0
  77. package/dest/lmdb/index.d.ts +12 -0
  78. package/dest/lmdb/index.d.ts.map +1 -0
  79. package/dest/lmdb/index.js +25 -0
  80. package/dest/lmdb/map.d.ts +40 -0
  81. package/dest/lmdb/map.d.ts.map +1 -0
  82. package/dest/lmdb/map.js +156 -0
  83. package/dest/lmdb/multi_map.d.ts +13 -0
  84. package/dest/lmdb/multi_map.d.ts.map +1 -0
  85. package/dest/lmdb/multi_map.js +44 -0
  86. package/dest/lmdb/set.d.ts +18 -0
  87. package/dest/lmdb/set.d.ts.map +1 -0
  88. package/dest/lmdb/set.js +32 -0
  89. package/dest/lmdb/singleton.d.ts +14 -0
  90. package/dest/lmdb/singleton.d.ts.map +1 -0
  91. package/dest/lmdb/singleton.js +26 -0
  92. package/dest/lmdb/store.d.ts +94 -0
  93. package/dest/lmdb/store.d.ts.map +1 -0
  94. package/dest/lmdb/store.js +200 -0
  95. package/dest/lmdb-v2/array.d.ts +19 -0
  96. package/dest/lmdb-v2/array.d.ts.map +1 -0
  97. package/dest/lmdb-v2/array.js +103 -0
  98. package/dest/lmdb-v2/factory.d.ts +35 -0
  99. package/dest/lmdb-v2/factory.d.ts.map +1 -0
  100. package/dest/lmdb-v2/factory.js +126 -0
  101. package/dest/lmdb-v2/index.d.ts +3 -0
  102. package/dest/lmdb-v2/index.d.ts.map +1 -0
  103. package/dest/lmdb-v2/index.js +2 -0
  104. package/dest/lmdb-v2/map.d.ts +53 -0
  105. package/dest/lmdb-v2/map.d.ts.map +1 -0
  106. package/dest/lmdb-v2/map.js +106 -0
  107. package/dest/lmdb-v2/message.d.ts +131 -0
  108. package/dest/lmdb-v2/message.d.ts.map +1 -0
  109. package/dest/lmdb-v2/message.js +20 -0
  110. package/dest/lmdb-v2/multi_map.d.ts +52 -0
  111. package/dest/lmdb-v2/multi_map.d.ts.map +1 -0
  112. package/dest/lmdb-v2/multi_map.js +123 -0
  113. package/dest/lmdb-v2/read_transaction.d.ts +16 -0
  114. package/dest/lmdb-v2/read_transaction.d.ts.map +1 -0
  115. package/dest/lmdb-v2/read_transaction.js +137 -0
  116. package/dest/lmdb-v2/set.d.ts +15 -0
  117. package/dest/lmdb-v2/set.d.ts.map +1 -0
  118. package/dest/lmdb-v2/set.js +23 -0
  119. package/dest/lmdb-v2/singleton.d.ts +12 -0
  120. package/dest/lmdb-v2/singleton.d.ts.map +1 -0
  121. package/dest/lmdb-v2/singleton.js +31 -0
  122. package/dest/lmdb-v2/store.d.ts +43 -0
  123. package/dest/lmdb-v2/store.d.ts.map +1 -0
  124. package/dest/lmdb-v2/store.js +171 -0
  125. package/dest/lmdb-v2/tx-helpers.d.ts +6 -0
  126. package/dest/lmdb-v2/tx-helpers.d.ts.map +1 -0
  127. package/dest/lmdb-v2/tx-helpers.js +21 -0
  128. package/dest/lmdb-v2/utils.d.ts +8 -0
  129. package/dest/lmdb-v2/utils.d.ts.map +1 -0
  130. package/dest/lmdb-v2/utils.js +32 -0
  131. package/dest/lmdb-v2/write_transaction.d.ts +17 -0
  132. package/dest/lmdb-v2/write_transaction.d.ts.map +1 -0
  133. package/dest/lmdb-v2/write_transaction.js +258 -0
  134. package/dest/sqlite-opfs/array.d.ts +21 -0
  135. package/dest/sqlite-opfs/array.d.ts.map +1 -0
  136. package/dest/sqlite-opfs/array.js +128 -0
  137. package/dest/sqlite-opfs/errors.d.ts +54 -0
  138. package/dest/sqlite-opfs/errors.d.ts.map +1 -0
  139. package/dest/sqlite-opfs/errors.js +77 -0
  140. package/dest/sqlite-opfs/index.d.ts +14 -0
  141. package/dest/sqlite-opfs/index.d.ts.map +1 -0
  142. package/dest/sqlite-opfs/index.js +16 -0
  143. package/dest/sqlite-opfs/internal/ordered-binary-browser.d.ts +32 -0
  144. package/dest/sqlite-opfs/internal/ordered-binary-browser.d.ts.map +1 -0
  145. package/dest/sqlite-opfs/internal/ordered-binary-browser.js +448 -0
  146. package/dest/sqlite-opfs/manage.d.ts +22 -0
  147. package/dest/sqlite-opfs/manage.d.ts.map +1 -0
  148. package/dest/sqlite-opfs/manage.js +38 -0
  149. package/dest/sqlite-opfs/map.d.ts +35 -0
  150. package/dest/sqlite-opfs/map.d.ts.map +1 -0
  151. package/dest/sqlite-opfs/map.js +163 -0
  152. package/dest/sqlite-opfs/messages.d.ts +66 -0
  153. package/dest/sqlite-opfs/messages.d.ts.map +1 -0
  154. package/dest/sqlite-opfs/messages.js +5 -0
  155. package/dest/sqlite-opfs/multi_map.d.ts +16 -0
  156. package/dest/sqlite-opfs/multi_map.d.ts.map +1 -0
  157. package/dest/sqlite-opfs/multi_map.js +67 -0
  158. package/dest/sqlite-opfs/pool_integrity.d.ts +20 -0
  159. package/dest/sqlite-opfs/pool_integrity.d.ts.map +1 -0
  160. package/dest/sqlite-opfs/pool_integrity.js +282 -0
  161. package/dest/sqlite-opfs/pool_lock.d.ts +8 -0
  162. package/dest/sqlite-opfs/pool_lock.d.ts.map +1 -0
  163. package/dest/sqlite-opfs/pool_lock.js +47 -0
  164. package/dest/sqlite-opfs/set.d.ts +13 -0
  165. package/dest/sqlite-opfs/set.d.ts.map +1 -0
  166. package/dest/sqlite-opfs/set.js +19 -0
  167. package/dest/sqlite-opfs/singleton.d.ts +13 -0
  168. package/dest/sqlite-opfs/singleton.d.ts.map +1 -0
  169. package/dest/sqlite-opfs/singleton.js +48 -0
  170. package/dest/sqlite-opfs/store.d.ts +84 -0
  171. package/dest/sqlite-opfs/store.d.ts.map +1 -0
  172. package/dest/sqlite-opfs/store.js +318 -0
  173. package/dest/sqlite-opfs/worker.d.ts +2 -0
  174. package/dest/sqlite-opfs/worker.d.ts.map +1 -0
  175. package/dest/sqlite-opfs/worker.js +275 -0
  176. package/dest/stores/index.d.ts +3 -0
  177. package/dest/stores/index.d.ts.map +1 -0
  178. package/dest/stores/index.js +2 -0
  179. package/dest/stores/l2_tips_store.d.ts +23 -0
  180. package/dest/stores/l2_tips_store.d.ts.map +1 -0
  181. package/dest/stores/l2_tips_store.js +64 -0
  182. package/dest/utils.d.ts +15 -0
  183. package/dest/utils.d.ts.map +1 -0
  184. package/dest/utils.js +59 -0
  185. package/package.json +108 -0
  186. package/src/bench/shared_map_bench.ts +111 -0
  187. package/src/deprecated/indexeddb/array.ts +122 -0
  188. package/src/deprecated/indexeddb/index.ts +12 -0
  189. package/src/deprecated/indexeddb/map.ts +137 -0
  190. package/src/deprecated/indexeddb/multi_map.ts +106 -0
  191. package/src/deprecated/indexeddb/set.ts +37 -0
  192. package/src/deprecated/indexeddb/singleton.ts +52 -0
  193. package/src/deprecated/indexeddb/store.ts +214 -0
  194. package/src/interfaces/array.ts +92 -0
  195. package/src/interfaces/array_test_suite.ts +128 -0
  196. package/src/interfaces/common.ts +31 -0
  197. package/src/interfaces/counter.ts +65 -0
  198. package/src/interfaces/index.ts +9 -0
  199. package/src/interfaces/map.ts +117 -0
  200. package/src/interfaces/map_test_suite.ts +198 -0
  201. package/src/interfaces/multi_map.ts +45 -0
  202. package/src/interfaces/multi_map_test_suite.ts +372 -0
  203. package/src/interfaces/set.ts +48 -0
  204. package/src/interfaces/set_test_suite.ts +79 -0
  205. package/src/interfaces/singleton.ts +29 -0
  206. package/src/interfaces/singleton_test_suite.ts +44 -0
  207. package/src/interfaces/store.ts +142 -0
  208. package/src/interfaces/utils.ts +23 -0
  209. package/src/lmdb/array.ts +140 -0
  210. package/src/lmdb/counter.ts +67 -0
  211. package/src/lmdb/index.ts +41 -0
  212. package/src/lmdb/map.ts +177 -0
  213. package/src/lmdb/multi_map.ts +51 -0
  214. package/src/lmdb/set.ts +45 -0
  215. package/src/lmdb/singleton.ts +35 -0
  216. package/src/lmdb/store.ts +242 -0
  217. package/src/lmdb-v2/array.ts +120 -0
  218. package/src/lmdb-v2/factory.ts +184 -0
  219. package/src/lmdb-v2/index.ts +2 -0
  220. package/src/lmdb-v2/map.ts +136 -0
  221. package/src/lmdb-v2/message.ts +169 -0
  222. package/src/lmdb-v2/multi_map.ts +150 -0
  223. package/src/lmdb-v2/read_transaction.ts +156 -0
  224. package/src/lmdb-v2/set.ts +33 -0
  225. package/src/lmdb-v2/singleton.ts +38 -0
  226. package/src/lmdb-v2/store.ts +220 -0
  227. package/src/lmdb-v2/tx-helpers.ts +29 -0
  228. package/src/lmdb-v2/utils.ts +32 -0
  229. package/src/lmdb-v2/write_transaction.ts +315 -0
  230. package/src/sqlite-opfs/array.ts +124 -0
  231. package/src/sqlite-opfs/errors.ts +94 -0
  232. package/src/sqlite-opfs/index.ts +27 -0
  233. package/src/sqlite-opfs/internal/ordered-binary-browser.js +465 -0
  234. package/src/sqlite-opfs/manage.ts +46 -0
  235. package/src/sqlite-opfs/map.ts +163 -0
  236. package/src/sqlite-opfs/messages.ts +39 -0
  237. package/src/sqlite-opfs/multi_map.ts +74 -0
  238. package/src/sqlite-opfs/pool_integrity.ts +327 -0
  239. package/src/sqlite-opfs/pool_lock.ts +62 -0
  240. package/src/sqlite-opfs/set.ts +29 -0
  241. package/src/sqlite-opfs/singleton.ts +48 -0
  242. package/src/sqlite-opfs/store.ts +331 -0
  243. package/src/sqlite-opfs/worker.ts +259 -0
  244. package/src/stores/index.ts +3 -0
  245. package/src/stores/l2_tips_store.ts +67 -0
  246. package/src/utils.ts +98 -0
@@ -0,0 +1,214 @@
1
+ import type { Logger } from '@aztec-labs/foundation/log';
2
+ import { SerialQueue } from '@aztec-labs/foundation/queue';
3
+ import { type DBSchema, type IDBPDatabase, deleteDB, openDB } from 'idb';
4
+
5
+ import type { AztecAsyncArray } from '../../interfaces/array.js';
6
+ import type { Key, StoreSize, Value } from '../../interfaces/common.js';
7
+ import type { AztecAsyncCounter } from '../../interfaces/counter.js';
8
+ import type { AztecAsyncMap } from '../../interfaces/map.js';
9
+ import type { AztecAsyncMultiMap } from '../../interfaces/multi_map.js';
10
+ import type { AztecAsyncSet } from '../../interfaces/set.js';
11
+ import type { AztecAsyncSingleton } from '../../interfaces/singleton.js';
12
+ import type { AztecAsyncKVStore } from '../../interfaces/store.js';
13
+ import { IndexedDBAztecArray } from './array.js';
14
+ import { IndexedDBAztecMap } from './map.js';
15
+ import { IndexedDBAztecMultiMap } from './multi_map.js';
16
+ import { IndexedDBAztecSet } from './set.js';
17
+ import { IndexedDBAztecSingleton } from './singleton.js';
18
+
19
+ export type StoredData<V extends Value> = {
20
+ value: V;
21
+ container: string;
22
+ key: (string | number | Uint8Array)[];
23
+ keyCount: number;
24
+ slot: string;
25
+ hash: string;
26
+ };
27
+
28
+ export interface AztecIDBSchema extends DBSchema {
29
+ data: {
30
+ value: StoredData<any>;
31
+ key: string;
32
+ indexes: {
33
+ container: string;
34
+ key: any; // Runtime: (string | number | Uint8Array)[] - idb types don't support arrays
35
+ keyCount: number;
36
+ hash: string;
37
+ };
38
+ };
39
+ }
40
+
41
+ /**
42
+ * A key-value store backed by IndexedDB.
43
+ *
44
+ * @deprecated The IndexedDB backend is being retired. Use `@aztec-labs/kv-store/sqlite-opfs` instead.
45
+ */
46
+ export class AztecIndexedDBStore implements AztecAsyncKVStore {
47
+ #rootDB: IDBPDatabase<AztecIDBSchema>;
48
+ #name: string;
49
+ #txQueue: SerialQueue;
50
+
51
+ #containers = new Set<
52
+ | IndexedDBAztecArray<any>
53
+ | IndexedDBAztecMap<any, any>
54
+ | IndexedDBAztecMultiMap<any, any>
55
+ | IndexedDBAztecSet<any>
56
+ | IndexedDBAztecSingleton<any>
57
+ >();
58
+
59
+ constructor(
60
+ rootDB: IDBPDatabase<AztecIDBSchema>,
61
+ public readonly isEphemeral: boolean,
62
+ name: string,
63
+ ) {
64
+ this.#rootDB = rootDB;
65
+ this.#name = name;
66
+ this.#txQueue = new SerialQueue();
67
+ this.#txQueue.start();
68
+ }
69
+ /**
70
+ * Creates a new AztecKVStore backed by IndexedDB. The path to the database is optional. If not provided,
71
+ * the database will be stored in a temporary location and be deleted when the process exists.
72
+ *
73
+ *
74
+ * @param path - A path on the disk to store the database. Optional
75
+ * @param ephemeral - true if the store should only exist in memory and not automatically be flushed to disk. Optional
76
+ * @param log - A logger to use. Optional
77
+ * @returns The store
78
+ */
79
+ static async open(log: Logger, name?: string, ephemeral: boolean = false): Promise<AztecIndexedDBStore> {
80
+ name = name && !ephemeral ? name : globalThis.crypto.getRandomValues(new Uint8Array(16)).join('');
81
+ log.debug(`Opening IndexedDB ${ephemeral ? 'temp ' : ''}database with name ${name}`);
82
+ const rootDB = await openDB<AztecIDBSchema>(name, 1, {
83
+ upgrade(db) {
84
+ const objectStore = db.createObjectStore('data', { keyPath: 'slot' });
85
+
86
+ objectStore.createIndex('key', ['container', 'key'], { unique: false });
87
+ // Keep count of the maximum number of keys ever inserted in the container
88
+ // This allows unique slots for repeated keys, which is useful for multi-maps
89
+ objectStore.createIndex('keyCount', ['container', 'key', 'keyCount'], { unique: true });
90
+ // Keep an index on the pair key-hash for a given container, allowing us to efficiently
91
+ // delete unique values from multi-maps
92
+ objectStore.createIndex('hash', ['container', 'key', 'hash'], { unique: true });
93
+ },
94
+ });
95
+
96
+ const kvStore = new AztecIndexedDBStore(rootDB, ephemeral, name);
97
+ return kvStore;
98
+ }
99
+
100
+ /**
101
+ * Creates a new AztecMap in the store.
102
+ * @param name - Name of the map
103
+ * @returns A new AztecMap
104
+ */
105
+ openMap<K extends Key, V extends Value>(name: string): AztecAsyncMap<K, V> {
106
+ const map = new IndexedDBAztecMap<K, V>(this.#rootDB, name);
107
+ this.#containers.add(map);
108
+ return map;
109
+ }
110
+
111
+ /**
112
+ * Creates a new AztecSet in the store.
113
+ * @param name - Name of the set
114
+ * @returns A new AztecSet
115
+ */
116
+ openSet<K extends Key>(name: string): AztecAsyncSet<K> {
117
+ const set = new IndexedDBAztecSet<K>(this.#rootDB, name);
118
+ this.#containers.add(set);
119
+ return set;
120
+ }
121
+
122
+ /**
123
+ * Creates a new AztecMultiMap in the store. A multi-map stores multiple values for a single key automatically.
124
+ * @param name - Name of the map
125
+ * @returns A new AztecMultiMap
126
+ */
127
+ openMultiMap<K extends Key, V extends Value>(name: string): AztecAsyncMultiMap<K, V> {
128
+ const multimap = new IndexedDBAztecMultiMap<K, V>(this.#rootDB, name);
129
+ this.#containers.add(multimap);
130
+ return multimap;
131
+ }
132
+
133
+ openCounter<K extends Key>(_name: string): AztecAsyncCounter<K> {
134
+ throw new Error('Method not implemented.');
135
+ }
136
+
137
+ /**
138
+ * Creates a new AztecArray in the store.
139
+ * @param name - Name of the array
140
+ * @returns A new AztecArray
141
+ */
142
+ openArray<T extends Value>(name: string): AztecAsyncArray<T> {
143
+ const array = new IndexedDBAztecArray<T>(this.#rootDB, name);
144
+ this.#containers.add(array);
145
+ return array;
146
+ }
147
+
148
+ /**
149
+ * Creates a new AztecSingleton in the store.
150
+ * @param name - Name of the singleton
151
+ * @returns A new AztecSingleton
152
+ */
153
+ openSingleton<T extends Value>(name: string): AztecAsyncSingleton<T> {
154
+ const singleton = new IndexedDBAztecSingleton<T>(this.#rootDB, name);
155
+ this.#containers.add(singleton);
156
+ return singleton;
157
+ }
158
+
159
+ /**
160
+ * Runs a callback in a transaction.
161
+ * @param callback - Function to execute in a transaction
162
+ * @returns A promise that resolves to the return value of the callback
163
+ */
164
+ transactionAsync<T>(callback: () => Promise<T>): Promise<T> {
165
+ // We can only have one transaction at a time for the same store
166
+ // So we need to wait for the current one to finish
167
+ return this.#txQueue.put(async () => {
168
+ const tx = this.#rootDB.transaction('data', 'readwrite');
169
+ for (const container of this.#containers) {
170
+ container.db = tx.store;
171
+ }
172
+ // Avoid awaiting this promise so it doesn't get scheduled in the next microtask
173
+ // By then, the tx would be closed
174
+ const runningPromise = callback();
175
+ // Wait for the transaction to finish
176
+ await tx.done;
177
+ for (const container of this.#containers) {
178
+ container.db = undefined;
179
+ }
180
+
181
+ // Return the result of the callback.
182
+ // Tx is guaranteed to already be closed, so the await doesn't hurt anything here
183
+ return await runningPromise;
184
+ });
185
+ }
186
+
187
+ /**
188
+ * Clears all entries in the store & sub DBs.
189
+ */
190
+ async clear() {
191
+ await this.#rootDB.transaction('data', 'readwrite').store.clear();
192
+ }
193
+
194
+ /** Deletes this store and removes the database */
195
+ async delete() {
196
+ this.#containers.clear();
197
+ await this.#txQueue.end();
198
+ this.#rootDB.close();
199
+ await deleteDB(this.#name);
200
+ }
201
+
202
+ estimateSize(): Promise<StoreSize> {
203
+ return Promise.resolve({ mappingSize: 0, physicalFileSize: 0, actualSize: 0, numItems: 0 });
204
+ }
205
+
206
+ async close(): Promise<void> {
207
+ await this.#txQueue.end();
208
+ this.#rootDB.close();
209
+ }
210
+
211
+ backupTo(_dstPath: string, _compact?: boolean): Promise<void> {
212
+ throw new Error('Method not implemented.');
213
+ }
214
+ }
@@ -0,0 +1,92 @@
1
+ import type { Value } from './common.js';
2
+
3
+ /**
4
+ * An array backed by a persistent store. Can not have any holes in it.
5
+ */
6
+ interface BaseAztecArray<T extends Value> {
7
+ /**
8
+ * Pushes values to the end of the array
9
+ * @param vals - The values to push to the end of the array
10
+ * @returns The new length of the array
11
+ */
12
+ push(...vals: T[]): Promise<number>;
13
+
14
+ /**
15
+ * Pops a value from the end of the array.
16
+ * @returns The value that was popped, or undefined if the array was empty
17
+ */
18
+ pop(): Promise<T | undefined>;
19
+
20
+ /**
21
+ * Updates the value at the given index. Index can be in the range [-length, length - 1).
22
+ * @param index - The index to set the value at
23
+ * @param val - The value to set
24
+ * @returns Whether the value was set
25
+ */
26
+ setAt(index: number, val: T): Promise<boolean>;
27
+ }
28
+
29
+ /**
30
+ * An array backed by a persistent store. Can not have any holes in it.
31
+ */
32
+ export interface AztecAsyncArray<T extends Value> extends BaseAztecArray<T> {
33
+ /**
34
+ * The size of the array
35
+ */
36
+ lengthAsync(): Promise<number>;
37
+
38
+ /**
39
+ * Gets the value at the given index. Index can be in the range [-length, length - 1).
40
+ * If the index is negative, it will be treated as an offset from the end of the array.
41
+ *
42
+ * @param index - The index to get the value from
43
+ * @returns The value at the given index or undefined if the index is out of bounds
44
+ */
45
+ atAsync(index: number): Promise<T | undefined>;
46
+
47
+ /**
48
+ * Iterates over the array with indexes.
49
+ */
50
+ entriesAsync(): AsyncIterableIterator<[number, T]>;
51
+
52
+ /**
53
+ * Iterates over the array.
54
+ */
55
+ valuesAsync(): AsyncIterableIterator<T>;
56
+
57
+ /**
58
+ * Iterates over the array.
59
+ */
60
+ [Symbol.asyncIterator](): AsyncIterableIterator<T>;
61
+ }
62
+
63
+ export interface AztecArray<T extends Value> extends BaseAztecArray<T> {
64
+ /**
65
+ * The size of the array
66
+ */
67
+ length: number;
68
+
69
+ /**
70
+ * Gets the value at the given index. Index can be in the range [-length, length - 1).
71
+ * If the index is negative, it will be treated as an offset from the end of the array.
72
+ *
73
+ * @param index - The index to get the value from
74
+ * @returns The value at the given index or undefined if the index is out of bounds
75
+ */
76
+ at(index: number): T | undefined;
77
+
78
+ /**
79
+ * Iterates over the array with indexes.
80
+ */
81
+ entries(): IterableIterator<[number, T]>;
82
+
83
+ /**
84
+ * Iterates over the array.
85
+ */
86
+ values(): IterableIterator<T>;
87
+
88
+ /**
89
+ * Iterates over the array.
90
+ */
91
+ [Symbol.iterator](): IterableIterator<T>;
92
+ }
@@ -0,0 +1,128 @@
1
+ import { toArray } from '@aztec-labs/foundation/iterable';
2
+
3
+ import type { AztecArray, AztecAsyncArray } from './array.js';
4
+ import type { AztecAsyncKVStore, AztecKVStore } from './store.js';
5
+ import { isSyncStore } from './utils.js';
6
+
7
+ export function describeAztecArray(
8
+ testName: string,
9
+ getStore: () => AztecKVStore | Promise<AztecAsyncKVStore>,
10
+ forceAsync: boolean = false,
11
+ ) {
12
+ describe(testName, () => {
13
+ let store: AztecKVStore | AztecAsyncKVStore;
14
+ let arr: AztecArray<number> | AztecAsyncArray<number>;
15
+
16
+ beforeEach(async () => {
17
+ store = await getStore();
18
+ arr = store.openArray<number>('test');
19
+ });
20
+
21
+ afterEach(async () => {
22
+ await store.delete();
23
+ });
24
+
25
+ async function length(sut: AztecAsyncArray<number> | AztecArray<number> = arr) {
26
+ return isSyncStore(store) && !forceAsync
27
+ ? (sut as AztecArray<number>).length
28
+ : await (sut as AztecAsyncArray<number>).lengthAsync();
29
+ }
30
+
31
+ async function at(index: number) {
32
+ return isSyncStore(store) && !forceAsync
33
+ ? (arr as AztecArray<number>).at(index)
34
+ : await (arr as AztecAsyncArray<number>).atAsync(index);
35
+ }
36
+
37
+ async function entries() {
38
+ return isSyncStore(store) && !forceAsync
39
+ ? await toArray((arr as AztecArray<number>).entries())
40
+ : await toArray((arr as AztecAsyncArray<number>).entriesAsync());
41
+ }
42
+
43
+ async function values(sut: AztecAsyncArray<number> | AztecArray<number> = arr) {
44
+ return isSyncStore(store) && !forceAsync
45
+ ? await toArray((sut as AztecArray<number>).values())
46
+ : await toArray((sut as AztecAsyncArray<number>).valuesAsync());
47
+ }
48
+
49
+ it('should be able to push and pop values', async () => {
50
+ await arr.push(1);
51
+ await arr.push(2);
52
+ await arr.push(3);
53
+
54
+ expect(await length()).toBe(3);
55
+
56
+ expect(await arr.pop()).toBe(3);
57
+ expect(await arr.pop()).toBe(2);
58
+ expect(await arr.pop()).toBe(1);
59
+ expect(await arr.pop()).toBe(undefined);
60
+ });
61
+
62
+ it('should be able to get values by index', async () => {
63
+ await arr.push(1);
64
+ await arr.push(2);
65
+ await arr.push(3);
66
+
67
+ expect(await at(0)).toBe(1);
68
+ expect(await at(1)).toBe(2);
69
+ expect(await at(2)).toBe(3);
70
+ expect(await at(3)).toBe(undefined);
71
+ expect(await at(-1)).toBe(3);
72
+ expect(await at(-2)).toBe(2);
73
+ expect(await at(-3)).toBe(1);
74
+ expect(await at(-4)).toBe(undefined);
75
+ });
76
+
77
+ it('should be able to set values by index', async () => {
78
+ await arr.push(1);
79
+ await arr.push(2);
80
+ await arr.push(3);
81
+
82
+ expect(await arr.setAt(0, 4)).toBe(true);
83
+ expect(await arr.setAt(1, 5)).toBe(true);
84
+ expect(await arr.setAt(2, 6)).toBe(true);
85
+
86
+ expect(await arr.setAt(3, 7)).toBe(false);
87
+
88
+ expect(await at(0)).toBe(4);
89
+ expect(await at(1)).toBe(5);
90
+ expect(await at(2)).toBe(6);
91
+ expect(await at(3)).toBe(undefined);
92
+
93
+ expect(await arr.setAt(-1, 8)).toBe(true);
94
+ expect(await arr.setAt(-2, 9)).toBe(true);
95
+ expect(await arr.setAt(-3, 10)).toBe(true);
96
+
97
+ expect(await arr.setAt(-4, 11)).toBe(false);
98
+
99
+ expect(await at(-1)).toBe(8);
100
+ expect(await at(-2)).toBe(9);
101
+ expect(await at(-3)).toBe(10);
102
+ expect(await at(-4)).toBe(undefined);
103
+ });
104
+
105
+ it('should be able to iterate over values', async () => {
106
+ await arr.push(1);
107
+ await arr.push(2);
108
+ await arr.push(3);
109
+
110
+ expect(await values()).toEqual([1, 2, 3]);
111
+ expect(await entries()).toEqual([
112
+ [0, 1],
113
+ [1, 2],
114
+ [2, 3],
115
+ ]);
116
+ });
117
+
118
+ it('should be able to restore state', async () => {
119
+ await arr.push(1);
120
+ await arr.push(2);
121
+ await arr.push(3);
122
+
123
+ const arr2 = store.openArray<number>('test');
124
+ expect(await length(arr2)).toBe(3);
125
+ expect(await values(arr2)).toEqual(await values());
126
+ });
127
+ });
128
+ }
@@ -0,0 +1,31 @@
1
+ /** The key type for use with the kv-store */
2
+ export type Key = string | number | Uint8Array | Array<string | number>;
3
+
4
+ export type Value = NonNullable<any>;
5
+
6
+ /** A range of keys of arbitrary type. */
7
+ export type CustomRange<K> = {
8
+ /** The key of the first item to include */
9
+ start?: K;
10
+ /** The key of the last item to include */
11
+ end?: K;
12
+ /** Whether to iterate in reverse */
13
+ reverse?: boolean;
14
+ /** The maximum number of items to iterate over */
15
+ limit?: number;
16
+ };
17
+
18
+ /** Maps a custom range into a range of valid key types to iterate over. */
19
+ export function mapRange<CK, K extends Key = Key>(range: CustomRange<CK>, mapFn: (key: CK) => K): Range<K> {
20
+ return {
21
+ start: range.start ? mapFn(range.start) : undefined,
22
+ end: range.end ? mapFn(range.end) : undefined,
23
+ reverse: range.reverse,
24
+ limit: range.limit,
25
+ };
26
+ }
27
+
28
+ /** A range of keys to iterate over. */
29
+ export type Range<K extends Key = Key> = CustomRange<K>;
30
+
31
+ export type StoreSize = { mappingSize: number; physicalFileSize: number; actualSize: number; numItems: number };
@@ -0,0 +1,65 @@
1
+ import type { Key, Range } from './common.js';
2
+
3
+ /**
4
+ * A map that counts how many times it sees a key. Once 0 is reached, that key is removed from the map.
5
+ * Iterating over the map will only return keys that have a count over 0.
6
+ *
7
+ * Keys are stored in sorted order
8
+ */
9
+ interface AztecBaseCounter<K extends Key = Key> {
10
+ /**
11
+ * Resets the count of the given key to the given value.
12
+ * @param key - The key to reset
13
+ * @param value - The value to reset the key to
14
+ */
15
+ set(key: K, value: number): Promise<void>;
16
+
17
+ /**
18
+ * Updates the count of the given key by the given delta. This can be used to increment or decrement the count.
19
+ * Once a key's count reaches 0, it is removed from the map.
20
+ *
21
+ * @param key - The key to update
22
+ * @param delta - The amount to modify the key by
23
+ */
24
+ update(key: K, delta: number): Promise<void>;
25
+ }
26
+
27
+ export interface AztecCounter<K extends Key = Key> extends AztecBaseCounter<K> {
28
+ /**
29
+ * Gets the current count.
30
+ * @param key - The key to get the count of
31
+ */
32
+ get(key: K): number;
33
+
34
+ /**
35
+ * Returns keys in the map in sorted order. Only returns keys that have been seen at least once.
36
+ * @param range - The range of keys to iterate over
37
+ */
38
+ keys(range: Range<K>): IterableIterator<K>;
39
+
40
+ /**
41
+ * Returns keys and their counts in the map sorted by the key. Only returns keys that have been seen at least once.
42
+ * @param range - The range of keys to iterate over
43
+ */
44
+ entries(range: Range<K>): IterableIterator<[K, number]>;
45
+ }
46
+
47
+ export interface AztecAsyncCounter<K extends Key = Key> extends AztecBaseCounter<K> {
48
+ /**
49
+ * Gets the current count.
50
+ * @param key - The key to get the count of
51
+ */
52
+ getAsync(key: K): Promise<number>;
53
+
54
+ /**
55
+ * Returns keys in the map in sorted order. Only returns keys that have been seen at least once.
56
+ * @param range - The range of keys to iterate over
57
+ */
58
+ keysAsync(range: Range<K>): AsyncIterableIterator<K>;
59
+
60
+ /**
61
+ * Returns keys and their counts in the map sorted by the key. Only returns keys that have been seen at least once.
62
+ * @param range - The range of keys to iterate over
63
+ */
64
+ entriesAsync(range: Range<K>): AsyncIterableIterator<[K, number]>;
65
+ }
@@ -0,0 +1,9 @@
1
+ export * from './array.js';
2
+ export * from './map.js';
3
+ export * from './counter.js';
4
+ export * from './singleton.js';
5
+ export * from './store.js';
6
+ export * from './set.js';
7
+ export * from './multi_map.js';
8
+ export { mapRange } from './common.js';
9
+ export type { CustomRange, Key, Range, StoreSize } from './common.js';
@@ -0,0 +1,117 @@
1
+ import type { Key, Range, Value } from './common.js';
2
+
3
+ /**
4
+ * A map backed by a persistent store.
5
+ */
6
+ interface AztecBaseMap<K extends Key, V extends Value> {
7
+ /**
8
+ * Sets the value at the given key.
9
+ * @param key - The key to set the value at
10
+ * @param val - The value to set
11
+ */
12
+ set(key: K, val: V): Promise<void>;
13
+
14
+ /**
15
+ * Sets the values at the given keys.
16
+ * @param entries - The entries to set
17
+ */
18
+ setMany(entries: { key: K; value: V }[]): Promise<void>;
19
+
20
+ /**
21
+ * Sets the value at the given key if it does not already exist.
22
+ * @param key - The key to set the value at
23
+ * @param val - The value to set
24
+ */
25
+ setIfNotExists(key: K, val: V): Promise<boolean>;
26
+
27
+ /**
28
+ * Deletes the value at the given key.
29
+ * @param key - The key to delete the value at
30
+ */
31
+ delete(key: K): Promise<void>;
32
+ }
33
+ export interface AztecMap<K extends Key, V extends Value> extends AztecBaseMap<K, V> {
34
+ /**
35
+ * Gets the value at the given key.
36
+ * @param key - The key to get the value from
37
+ */
38
+ get(key: K): V | undefined;
39
+
40
+ /**
41
+ * Gets the current size of the map.
42
+ * @returns The size of the map
43
+ */
44
+ size(): number;
45
+
46
+ /**
47
+ * Checks if a key exists in the map.
48
+ * @param key - The key to check
49
+ * @returns True if the key exists, false otherwise
50
+ */
51
+ has(key: K): boolean;
52
+
53
+ /**
54
+ * Iterates over the map's key-value entries in the key's natural order
55
+ * @param range - The range of keys to iterate over
56
+ */
57
+ entries(range?: Range<K>): IterableIterator<[K, V]>;
58
+
59
+ /**
60
+ * Iterates over the map's values in the key's natural order
61
+ * @param range - The range of keys to iterate over
62
+ */
63
+ values(range?: Range<K>): IterableIterator<V>;
64
+
65
+ /**
66
+ * Iterates over the map's keys in the key's natural order
67
+ * @param range - The range of keys to iterate over
68
+ */
69
+ keys(range?: Range<K>): IterableIterator<K>;
70
+
71
+ /**
72
+ * Clears the map.
73
+ */
74
+ clear(): Promise<void>;
75
+ }
76
+
77
+ /**
78
+ * A map backed by a persistent store.
79
+ */
80
+ export interface AztecAsyncMap<K extends Key, V extends Value> extends AztecBaseMap<K, V> {
81
+ /**
82
+ * Gets the value at the given key.
83
+ * @param key - The key to get the value from
84
+ */
85
+ getAsync(key: K): Promise<V | undefined>;
86
+
87
+ /**
88
+ * Checks if a key exists in the map.
89
+ * @param key - The key to check
90
+ * @returns True if the key exists, false otherwise
91
+ */
92
+ hasAsync(key: K): Promise<boolean>;
93
+
94
+ /**
95
+ * Iterates over the map's key-value entries in the key's natural order
96
+ * @param range - The range of keys to iterate over
97
+ */
98
+ entriesAsync(range?: Range<K>): AsyncIterableIterator<[K, V]>;
99
+
100
+ /**
101
+ * Iterates over the map's values in the key's natural order
102
+ * @param range - The range of keys to iterate over
103
+ */
104
+ valuesAsync(range?: Range<K>): AsyncIterableIterator<V>;
105
+
106
+ /**
107
+ * Iterates over the map's keys in the key's natural order
108
+ * @param range - The range of keys to iterate over
109
+ */
110
+ keysAsync(range?: Range<K>): AsyncIterableIterator<K>;
111
+
112
+ /**
113
+ * Gets the current size of the map.
114
+ * @returns The size of the map
115
+ */
116
+ sizeAsync(): Promise<number>;
117
+ }