ESPJsonDB is now a thin façade over runtime-owned state

Author: zekageri

CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project are documented in this file.
 The format follows Keep a Changelog and the project adheres to Semantic Versioning.
 
 ## [Unreleased]
+### Changed
+- Moved mutable DB ownership behind an internal runtime and moved file upload / path handling behind a real `FileStore` subsystem.
+- `Collection` now uses an internal backing store, enforces `maxDecodedViews` / `maxRecordsInMemory`, and applies revision-based conflict checks in update paths.
+
+### Removed
+- Compatibility aliases `getDiag()`, `getAllCollectionName()`, and `unRegisterSchema()`.
+- Direct file helper methods from `ESPJsonDB`; use `db.files()` only.
 
 ## [2.0.0] - 2026-03-27
 ### Added
@@ -18,6 +25,7 @@ The format follows Keep a Changelog and the project adheres to Semantic Versioni
 ### Changed
 - Snapshot payloads now include `_meta` alongside `_id` and document fields.
 - `getDiagnostics()` replaces `getDiag()`, `listCollectionNames()` replaces `getAllCollectionName()`, and `unregisterSchema()` replaces `unRegisterSchema()`.
+- File operations now live only behind `db.files()`, with async state access renamed to `cancelUpload()` / `getUploadState()`.
 - Collection persistence now uses `.jdb` files instead of raw `.mp` MessagePack payload files.
 - Unique constraints are enforced through in-memory per-field indexes instead of full collection scans.
 - The top-level CMake build now uses C++17 to match the library metadata.

examples/AsyncFileUpload/AsyncFileUpload.ino

@@ -72,7 +72,7 @@ void setup() {
 	opts.chunkSize = 128;
 	opts.overwrite = true;
 
-	auto start = db.writeFileStreamAsync("uploads/telemetry.bin", uploadPull, opts, onUploadDone);
+	auto start = db.files().writeFileStreamAsync("uploads/telemetry.bin", uploadPull, opts, onUploadDone);
 	if (!start.status.ok()) {
 		Serial.printf("writeFileStreamAsync failed: %s\n", start.status.message);
 		return;
@@ -91,7 +91,7 @@ void loop() {
 	}
 
 	if (!gUploadDone) {
-		auto state = db.getFileUploadState(gUploadId);
+		auto state = db.files().getUploadState(gUploadId);
 		if (state.status.ok()) {
 			Serial.printf("Upload state: %u\n", static_cast<unsigned>(state.value));
 		}
@@ -109,7 +109,7 @@ void loop() {
 			return;
 		}
 
-		auto file = db.readFile("uploads/telemetry.bin");
+		auto file = db.files().readFile("uploads/telemetry.bin");
 		if (!file.status.ok()) {
 			Serial.printf("readFile failed: %s\n", file.status.message);
 			return;

examples/AsyncLargeFileUpload/AsyncLargeFileUpload.ino

@@ -127,7 +127,7 @@ void setup() {
 	opts.chunkSize = kChunkSize;
 	opts.overwrite = true;
 
-	auto start = db.writeFileStreamAsync(
+	auto start = db.files().writeFileStreamAsync(
 	    "uploads/large_payload.bin",
 	    largeUploadPull,
 	    opts,
@@ -153,7 +153,7 @@ void loop() {
 	}
 
 	if (!gUploadDone) {
-		auto state = db.getFileUploadState(gUploadId);
+		auto state = db.files().getUploadState(gUploadId);
 		if (state.status.ok()) {
 			Serial.printf(
 			    "state=%u progress=%u/%u\n",
@@ -175,7 +175,7 @@ void loop() {
 			return;
 		}
 
-		auto sizeRes = db.fileSize("uploads/large_payload.bin");
+		auto sizeRes = db.files().fileSize("uploads/large_payload.bin");
 		if (!sizeRes.status.ok() || sizeRes.value != kPayloadSize) {
 			Serial.printf(
 			    "fileSize mismatch: %s size=%u\n",
@@ -186,7 +186,7 @@ void loop() {
 		}
 
 		HashingSink sink;
-		auto readRes = db.readFileStream("uploads/large_payload.bin", sink, kReadChunkSize);
+		auto readRes = db.files().readFileStream("uploads/large_payload.bin", sink, kReadChunkSize);
 		if (!readRes.status.ok()) {
 			Serial.printf("readFileStream failed: %s\n", readRes.status.message);
 			return;

examples/FileStreaming/FileStreaming.ino

@@ -37,37 +37,37 @@ void setup() {
 	}
 
 	// 1) Plain text file
-	st = db.writeTextFile("docs/readme.txt", "Hello from ESPJsonDB file storage.\nLine #2.");
+	st = db.files().writeTextFile("docs/readme.txt", "Hello from ESPJsonDB file storage.\nLine #2.");
 	if (!st.ok()) {
 		Serial.printf("writeTextFile(txt) failed: %s\n", st.message);
 		return;
 	}
 
 	// 2) JSON file (stored as text payload)
-	st = db.writeTextFile("configs/app.json", "{\"mode\":\"demo\",\"intervalMs\":1000}");
+	st = db.files().writeTextFile("configs/app.json", "{\"mode\":\"demo\",\"intervalMs\":1000}");
 	if (!st.ok()) {
 		Serial.printf("writeTextFile(json) failed: %s\n", st.message);
 		return;
 	}
 
 	// 3) CSV file
-	st = db.writeTextFile("exports/metrics.csv", "ts,temp,humidity\n1,21.4,48\n2,21.7,47\n");
+	st = db.files().writeTextFile("exports/metrics.csv", "ts,temp,humidity\n1,21.4,48\n2,21.7,47\n");
 	if (!st.ok()) {
 		Serial.printf("writeTextFile(csv) failed: %s\n", st.message);
 		return;
 	}
 
 	// 4) Binary file using direct byte write
 	const uint8_t binPayload[] = {0x00, 0xA1, 0xFF, 0x10, 0x22, 0x33, 0x44, 0x55};
-	st = db.writeFile("firmware/chunk.bin", binPayload, sizeof(binPayload));
+	st = db.files().writeFile("firmware/chunk.bin", binPayload, sizeof(binPayload));
 	if (!st.ok()) {
 		Serial.printf("writeFile(bin) failed: %s\n", st.message);
 		return;
 	}
 
 	// 5) Custom extension file (any file type works)
 	const uint8_t customPayload[] = {'M', 'O', 'D', 'L', 0x01, 0x02, 0x03, 0x04};
-	st = db.writeFile("assets/model.dat", customPayload, sizeof(customPayload));
+	st = db.files().writeFile("assets/model.dat", customPayload, sizeof(customPayload));
 	if (!st.ok()) {
 		Serial.printf("writeFile(dat) failed: %s\n", st.message);
 		return;
@@ -83,7 +83,7 @@ void setup() {
 	ESPJsonDBFileOptions opts;
 	opts.overwrite = true;
 	opts.chunkSize = 128;
-	st = db.writeFileFromPath("streams/raw_capture.raw", seedPath, opts);
+	st = db.files().writeFileFromPath("streams/raw_capture.raw", seedPath, opts);
 	if (!st.ok()) {
 		Serial.printf("writeFileFromPath failed: %s\n", st.message);
 		return;
@@ -100,19 +100,19 @@ void setup() {
 		return;
 	}
 
-	auto streamOut = db.readFileStream("streams/raw_capture.raw", sink, 96);
+	auto streamOut = db.files().readFileStream("streams/raw_capture.raw", sink, 96);
 	sink.close();
 	if (!streamOut.status.ok()) {
 		Serial.printf("readFileStream failed: %s\n", streamOut.status.message);
 		return;
 	}
 
 	// 8) Verify with helper reads
-	auto txt = db.readTextFile("docs/readme.txt");
-	auto jsn = db.readTextFile("configs/app.json");
-	auto csv = db.readTextFile("exports/metrics.csv");
-	auto bin = db.readFile("firmware/chunk.bin");
-	auto modelSize = db.fileSize("assets/model.dat");
+	auto txt = db.files().readTextFile("docs/readme.txt");
+	auto jsn = db.files().readTextFile("configs/app.json");
+	auto csv = db.files().readTextFile("exports/metrics.csv");
+	auto bin = db.files().readFile("firmware/chunk.bin");
+	auto modelSize = db.files().fileSize("assets/model.dat");
 
 	if (!txt.status.ok() || !jsn.status.ok() || !csv.status.ok() || !bin.status.ok() ||
 	    !modelSize.status.ok()) {
@@ -128,7 +128,7 @@ void setup() {
 	Serial.printf("model.dat bytes: %u\n", static_cast<unsigned>(modelSize.value));
 	Serial.printf("streamed raw bytes out: %u\n", static_cast<unsigned>(streamOut.value));
 
-	auto exists = db.fileExists("streams/raw_capture.raw");
+	auto exists = db.files().fileExists("streams/raw_capture.raw");
 	Serial.printf(
 	    "streams/raw_capture.raw exists: %s\n",
 	    (exists.status.ok() && exists.value) ? "yes" : "no"

examples/LargeFileStreaming/LargeFileStreaming.ino

@@ -108,13 +108,13 @@ void setup() {
 	opts.chunkSize = kWriteChunkSize;
 
 	const char *path = "firmware/large_payload.bin";
-	st = db.writeFileStream(path, pullCb, opts);
+	st = db.files().writeFileStream(path, pullCb, opts);
 	if (!st.ok()) {
 		Serial.printf("writeFileStream failed: %s\n", st.message);
 		return;
 	}
 
-	auto sizeRes = db.fileSize(path);
+	auto sizeRes = db.files().fileSize(path);
 	if (!sizeRes.status.ok() || sizeRes.value != kPayloadSize) {
 		Serial.printf(
 		    "fileSize mismatch: status=%s size=%u\n",
@@ -125,7 +125,7 @@ void setup() {
 	}
 
 	HashingSink sink;
-	auto readRes = db.readFileStream(path, sink, kReadChunkSize);
+	auto readRes = db.files().readFileStream(path, sink, kReadChunkSize);
 	if (!readRes.status.ok()) {
 		Serial.printf("readFileStream failed: %s\n", readRes.status.message);
 		return;