Some documentation

Author: simolus3

packages/web/src/db/adapters/memory/client.ts

@@ -13,9 +13,29 @@ function createWriteAheadLogBuffers(): WriteAheadBuffers {
 }
 
 interface InMemoryOptions {
+  /**
+   * The amount of workers to use, must at least be `1`.
+   */
   numWorkers: number;
 }
 
+/**
+ * An in-memory database backed by a pool of workers.
+ *
+ * Multiple workers can execute readonly transactions in parallel, and a single writer is allowed to write to the
+ * database in parallel to readers. To allow multiple workers to access the same database, this is based on shared array
+ * buffers and requires the page to be [cross-origin isolated](https://web.dev/articles/cross-origin-isolation-guide?hl=en).
+ *
+ * This database uses a concept known as a write-ahead log: Instead of writing changes directly to the database (which
+ * would cause conflicts with readers), the writer appends modified database pages into an append-only overlay log. When
+ * readers start a transaction, they consider the main database and items from the log until a specific position,
+ * meaning that future appends won't discrupt existing readers.
+ *
+ * To avoid the write-ahead log from growing indefinitely, it is regularly copied back into the main database file. This
+ * process is called a checkpoint, and in this implementation it blocks all other database access. However, it only
+ * needs to copy between memory and is usually fairly fast. This implementation checkpoints after the write-ahead log
+ * has grown to 512 KiB or larger. We might want to fine-tune that later.
+ */
 export class InMemoryWriteAheadLogPool extends DBAdapter {
   readonly name: string = `in-memory-${crypto.randomUUID()}`;
 

packages/web/src/db/adapters/memory/shared.ts

@@ -26,15 +26,33 @@ export interface WalIndexChange {
   fileSize: number;
   walEnd: number;
 
+  /**
+   * New overlay entries to add, encoded as (key, value) pairs of {@link WriteAheadState.overlay}.
+   */
   added: (number | WalOverlayEntry)[];
+
+  /**
+   * Whether to clear the overlay (meaning that we ran a checkpoint).
+   */
   cleared: boolean;
 }
 
 export interface DatabaseServer {
+  /**
+   * Open a database connection from the given database and write-ahead log buffers.
+   */
   open(buffers: WriteAheadBuffers): Promise<void>;
+
+  /**
+   * Push new wal changes to this worker.
+   */
   updateWalState(overlay: WalIndexChange): Promise<void>;
 
   executeRaw(query: string, params?: any[] | undefined): Promise<RawQueryResult>;
+
+  /**
+   * Takes WAL changes made by this worker during its active write iteration.
+   */
   takeWalChanges(): Promise<WalIndexChange>;
 }
 

packages/web/src/db/adapters/memory/vfs.ts

@@ -6,6 +6,8 @@ import { emptyWalState, WalIndexChange, WalOverlayEntry, WriteAheadBuffers, Writ
 const mainDbSentinel = Symbol();
 
 export class InMemoryWriteAheadLog extends FacadeVFS {
+  // The main /database file is the only file for which we create a write-ahead log. All other files (including the
+  // journal) are local-only.
   #openedFiles = new Map<number, LocalFile | typeof mainDbSentinel>();
   #files = new Map<string, LocalFile | typeof mainDbSentinel>();