feat: support opt-out of updating timestamp for individual set calls (#415)

Author: AlCalzone

README.md

@@ -128,7 +128,14 @@ The following options exist (all optional) and can be combined:
 
 ### Keeping track of timestamps
 
-The DB can automatically keep track of the last time a key was accessed or modified. To do so, set the `enableTimestamps` option to `true`. Every `set` call will update the timestamp of a value, which can be retrieved using `getTimestamp(key)`.
+The DB can automatically keep track of the last time a key was written. To do so, set the `enableTimestamps` option to `true`. Every `set` call will then update the timestamp of a value, which can be retrieved using `getTimestamp(key)`. To opt out of this behavior for individual writes, pass `false` as the 3rd argument to `set`.
+
+```ts
+db.set("key", "value", false); // Don't update the timestamp
+```
+
+> **Note**
+> Recording timestamps decreases the DB throughput by ~10...30% depending on how it is used.
 
 ### Import / Export
 

src/lib/db.test.ts

@@ -1534,7 +1534,7 @@ describe("lib/db", () => {
 			expect(actual).toBe(content);
 		}
 
-		it("should be recorded and read", async () => {
+		it("should be recorded and can be read back", async () => {
 			mockFs({
 				[testFilename]: ``,
 			});
@@ -1556,6 +1556,27 @@ describe("lib/db", () => {
 			expect(db.getTimestamp("1")).toBe(1000);
 		});
 
+		it("should not be updated when the 3rd argument to `set()` is false", async () => {
+			mockFs({
+				[testFilename]: ``,
+			});
+
+			db = new JsonlDB(testFilename, {
+				enableTimestamps: true,
+			});
+			await db.open();
+
+			vi.useFakeTimers({
+				now: 0,
+			});
+			db.set("0", "0");
+			vi.advanceTimersByTime(1000);
+
+			db.set("0", "1", false);
+
+			expect(db.getTimestamp("0")).toBe(0);
+		});
+
 		it("should be stored in the db file", async () => {
 			mockFs({
 				[testFilename]: ``,

src/lib/db.ts

@@ -579,14 +579,20 @@ export class JsonlDB<V = unknown> {
 		return ret;
 	}
 
-	public set(key: string, value: V): this {
+	public set(key: string, value: V, updateTimestamp: boolean = true): this {
 		if (!this._isOpen) {
 			throw new Error("The database is not open!");
 		}
 		this._db.set(key, value);
 		if (this.options.enableTimestamps) {
-			const ts = Date.now();
-			this._timestamps.set(key, ts);
+			// If the timestamp should updated, use the current time, otherwise try to preserve the old one
+			let ts: number | undefined;
+			if (updateTimestamp) {
+				ts = Date.now();
+				this._timestamps.set(key, ts);
+			} else {
+				ts = this._timestamps.get(key);
+			}
 			this._journal.push(this.makeLazyWrite(key, value, ts));
 		} else {
 			this._journal.push(this.makeLazyWrite(key, value));