esp-nvs-utils 0.1.0

package/dist/cjs/decoder.cjs

@@ -0,0 +1,248 @@
+//#region src/constants.ts
+/** NVS page size in bytes. */
+const PAGE_SIZE = 4096;
+/** Page state: page is currently being written. */
+const PAGE_STATE_ACTIVE = 4294967294;
+/** Page state: page is full, no more entries can be written. */
+const PAGE_STATE_FULL = 4294967292;
+/** Map from NVS encoding string to type code. */
+const ENCODING_TO_TYPE_CODE = {
+	u8: 1,
+	i8: 17,
+	u16: 2,
+	i16: 18,
+	u32: 4,
+	i32: 20,
+	u64: 8,
+	i64: 24,
+	string: 33,
+	blob_data: 66
+};
+//#endregion
+//#region src/decoder.ts
+function readKey(entry) {
+	let end = 8;
+	while (end < 24 && entry[end] !== 0) end++;
+	return new TextDecoder().decode(entry.subarray(8, end));
+}
+function entryBitmapState(bitmap, idx) {
+	const bitNum = idx * 2;
+	const byteIdx = bitNum >> 3;
+	const bitOffset = bitNum & 7;
+	return bitmap[byteIdx] >> bitOffset & 3;
+}
+function parsePrimitive(typeCode, inlineData) {
+	const view = new DataView(inlineData.buffer, inlineData.byteOffset, inlineData.byteLength);
+	switch (typeCode) {
+		case 1: return view.getUint8(0);
+		case 17: return view.getInt8(0);
+		case 2: return view.getUint16(0, true);
+		case 18: return view.getInt16(0, true);
+		case 4: return view.getUint32(0, true);
+		case 20: return view.getInt32(0, true);
+		case 8: return view.getBigUint64(0, true);
+		case 24: return view.getBigInt64(0, true);
+		default: throw new Error(`Unknown primitive type code: 0x${typeCode.toString(16)}`);
+	}
+}
+const PRIMITIVE_TYPES = new Set([
+	1,
+	17,
+	2,
+	18,
+	4,
+	20,
+	8,
+	24
+]);
+const VARLEN_TYPES = new Set([
+	33,
+	65,
+	66,
+	72
+]);
+/**
+* Parse all valid written entries from a single 4096-byte page.
+* Returns entries in slot order, including namespace entries.
+*/
+function parsePage(pageData) {
+	const bitmap = pageData.subarray(32, 64);
+	const entries = [];
+	let i = 0;
+	while (i < 126) {
+		if (entryBitmapState(bitmap, i) !== 2) {
+			i++;
+			continue;
+		}
+		const entryOff = 64 + i * 32;
+		const entry = pageData.subarray(entryOff, entryOff + 32);
+		const nsIdx = entry[0];
+		const typeCode = entry[1];
+		let span = entry[2];
+		const chunkIndex = entry[3];
+		const safeSpan = span === 0 || span === 255 ? 1 : span;
+		const parsed = {
+			nsIdx,
+			typeCode,
+			span: safeSpan,
+			chunkIndex,
+			key: readKey(entry),
+			raw: entry,
+			inlineData: entry.subarray(24, 32),
+			entryIndex: i
+		};
+		if (VARLEN_TYPES.has(typeCode) && typeCode !== 72) {
+			const childCount = safeSpan - 1;
+			if (childCount > 0) {
+				const childStart = 64 + (i + 1) * 32;
+				const childEnd = childStart + childCount * 32;
+				parsed.childData = pageData.subarray(childStart, childEnd);
+			}
+		}
+		entries.push(parsed);
+		i += safeSpan;
+	}
+	return entries;
+}
+/**
+* Decode an NVS partition binary into structured namespaces.
+*
+* Handles V1 (single-page blobs) and V2 (multi-page blobs).
+* Does not support encrypted partitions.
+*/
+function decodeNVS(data) {
+	const buf = data instanceof Uint8Array ? data : new Uint8Array(data);
+	if (buf.length % 4096 !== 0) throw new Error(`Partition data length ${buf.length} is not aligned to page size ${PAGE_SIZE}`);
+	const allEntries = [];
+	for (let pageOff = 0; pageOff < buf.length; pageOff += PAGE_SIZE) {
+		const page = buf.subarray(pageOff, pageOff + PAGE_SIZE);
+		const pageStateRaw = (page[0] | page[1] << 8 | page[2] << 16 | page[3] << 24) >>> 0;
+		if (pageStateRaw === 4294967295 || pageStateRaw === 0) continue;
+		const version = page[8];
+		if (version !== 255 && version !== 254) continue;
+		allEntries.push(...parsePage(page));
+	}
+	const nsIdxToName = /* @__PURE__ */ new Map();
+	for (const e of allEntries) if (e.nsIdx === 0 && e.typeCode === 1) {
+		const assignedIdx = e.inlineData[0];
+		nsIdxToName.set(assignedIdx, e.key);
+	}
+	const blobDataChunks = /* @__PURE__ */ new Map();
+	const blobIndex = /* @__PURE__ */ new Map();
+	const v1Blobs = /* @__PURE__ */ new Map();
+	for (const e of allEntries) {
+		if (e.nsIdx === 0) continue;
+		const bk = `${e.nsIdx}:${e.key}`;
+		if (e.typeCode === 66) {
+			if (!blobDataChunks.has(bk)) blobDataChunks.set(bk, /* @__PURE__ */ new Map());
+			const payload = e.childData ?? new Uint8Array(0);
+			blobDataChunks.get(bk).set(e.chunkIndex, payload);
+		} else if (e.typeCode === 72) {
+			const view = new DataView(e.inlineData.buffer, e.inlineData.byteOffset, 8);
+			blobIndex.set(bk, {
+				totalSize: view.getUint32(0, true),
+				chunkCount: e.inlineData[4],
+				chunkStart: e.inlineData[5]
+			});
+		} else if (e.typeCode === 65) {
+			const size = new DataView(e.inlineData.buffer, e.inlineData.byteOffset, 8).getUint16(0, true);
+			const payload = e.childData ?? new Uint8Array(0);
+			v1Blobs.set(bk, {
+				size,
+				data: payload
+			});
+		}
+	}
+	const result = {};
+	for (const e of allEntries) {
+		if (e.nsIdx === 0) continue;
+		if (e.typeCode === 66 || e.typeCode === 72) continue;
+		const nsName = nsIdxToName.get(e.nsIdx);
+		if (nsName === void 0) continue;
+		if (!result[nsName]) result[nsName] = [];
+		const bk = `${e.nsIdx}:${e.key}`;
+		if (PRIMITIVE_TYPES.has(e.typeCode)) {
+			const val = parsePrimitive(e.typeCode, e.inlineData);
+			const enc = e.typeCode === 1 ? "u8" : e.typeCode === 17 ? "i8" : e.typeCode === 2 ? "u16" : e.typeCode === 18 ? "i16" : e.typeCode === 4 ? "u32" : e.typeCode === 20 ? "i32" : e.typeCode === 8 ? "u64" : "i64";
+			result[nsName].push({
+				name: e.key,
+				encoding: enc,
+				value: val
+			});
+		} else if (e.typeCode === 33) {
+			const size = new DataView(e.inlineData.buffer, e.inlineData.byteOffset, 8).getUint16(0, true);
+			const payload = e.childData ?? new Uint8Array(0);
+			const str = new TextDecoder().decode(payload.subarray(0, Math.max(0, size - 1)));
+			result[nsName].push({
+				name: e.key,
+				encoding: "string",
+				value: str
+			});
+		} else if (e.typeCode === 65) {
+			const v1 = v1Blobs.get(bk);
+			if (v1) {
+				const data = v1.data.subarray(0, v1.size);
+				result[nsName].push({
+					name: e.key,
+					encoding: "blob_data",
+					value: new Uint8Array(data)
+				});
+			}
+		}
+	}
+	for (const [bk, chunks] of blobDataChunks) {
+		const [nsIdxStr, ...keyParts] = bk.split(":");
+		const nsIdx = parseInt(nsIdxStr);
+		const key = keyParts.join(":");
+		const nsName = nsIdxToName.get(nsIdx);
+		if (nsName === void 0) continue;
+		const idx = blobIndex.get(bk);
+		const allChunkData = [...chunks.keys()].sort((a, b) => a - b).map((k) => chunks.get(k));
+		const totalRaw = allChunkData.reduce((acc, c) => acc + c.length, 0);
+		const assembled = new Uint8Array(totalRaw);
+		let off = 0;
+		for (const c of allChunkData) {
+			assembled.set(c, off);
+			off += c.length;
+		}
+		const trimmed = idx ? assembled.subarray(0, idx.totalSize) : assembled;
+		if (!result[nsName]) result[nsName] = [];
+		result[nsName].push({
+			name: key,
+			encoding: "blob_data",
+			value: new Uint8Array(trimmed)
+		});
+	}
+	return result;
+}
+//#endregion
+Object.defineProperty(exports, "ENCODING_TO_TYPE_CODE", {
+	enumerable: true,
+	get: function() {
+		return ENCODING_TO_TYPE_CODE;
+	}
+});
+Object.defineProperty(exports, "PAGE_SIZE", {
+	enumerable: true,
+	get: function() {
+		return PAGE_SIZE;
+	}
+});
+Object.defineProperty(exports, "PAGE_STATE_ACTIVE", {
+	enumerable: true,
+	get: function() {
+		return PAGE_STATE_ACTIVE;
+	}
+});
+Object.defineProperty(exports, "PAGE_STATE_FULL", {
+	enumerable: true,
+	get: function() {
+		return PAGE_STATE_FULL;
+	}
+});
+Object.defineProperty(exports, "decodeNVS", {
+	enumerable: true,
+	get: function() {
+		return decodeNVS;
+	}
+});

package/dist/cjs/esp-nvs-decode.cjs

@@ -0,0 +1,56 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+//#endregion
+const require_decoder = require("./decoder.cjs");
+let node_fs = require("node:fs");
+node_fs = __toESM(node_fs, 1);
+let node_path = require("node:path");
+node_path = __toESM(node_path, 1);
+//#region src/cli/esp-nvs-decode.ts
+function printUsage() {
+	console.error("Usage: esp-nvs-decode <partition.bin>");
+	console.error("       npm run decode -- <partition.bin>");
+}
+function toJsonFriendly(value) {
+	if (value instanceof Uint8Array) return Buffer.from(value).toString("base64");
+	if (typeof value === "bigint") return value.toString();
+	if (Array.isArray(value)) return value.map((item) => toJsonFriendly(item));
+	if (value && typeof value === "object") return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, toJsonFriendly(item)]));
+	return value ?? null;
+}
+function main(args) {
+	const inputPath = args[0];
+	if (!inputPath || inputPath === "-h" || inputPath === "--help") {
+		printUsage();
+		process.exit(inputPath ? 0 : 1);
+	}
+	const absoluteInputPath = node_path.resolve(process.cwd(), inputPath);
+	if (!node_fs.existsSync(absoluteInputPath)) {
+		console.error(`Input file not found: ${absoluteInputPath}`);
+		process.exit(1);
+	}
+	const decoded = require_decoder.decodeNVS(node_fs.readFileSync(absoluteInputPath));
+	process.stdout.write(`${JSON.stringify(toJsonFriendly(decoded), null, 2)}\n`);
+}
+//#endregion
+exports.main = main;

package/dist/cjs/index.cjs

@@ -0,0 +1,278 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_decoder = require("./decoder.cjs");
+//#region src/crc.ts
+/**
+* Pure CRC-32 implementation compatible with zlib.crc32 (polynomial 0xEDB88320).
+* Browser-safe: no Node.js dependencies.
+*/
+const CRC32_TABLE = (() => {
+	const table = new Uint32Array(256);
+	for (let i = 0; i < 256; i++) {
+		let c = i;
+		for (let j = 0; j < 8; j++) c = c & 1 ? 3988292384 ^ c >>> 1 : c >>> 1;
+		table[i] = c;
+	}
+	return table;
+})();
+/**
+* Compute CRC-32 of data, matching Python's `zlib.crc32(data, seed)`.
+* The default seed of 0xFFFFFFFF matches the NVS usage pattern.
+*/
+function crc32(data, seed = 4294967295) {
+	let crc = seed >>> 0;
+	for (let i = 0; i < data.length; i++) crc = CRC32_TABLE[(crc ^ data[i]) & 255] ^ crc >>> 8;
+	return crc >>> 0;
+}
+//#endregion
+//#region src/encoder.ts
+var PageFullError = class extends Error {
+	constructor() {
+		super("Page is full");
+	}
+};
+/** A single 4096-byte NVS page being written. */
+var PageWriter = class {
+	constructor(pageNum) {
+		this.entryNum = 0;
+		this.buf = new Uint8Array(require_decoder.PAGE_SIZE).fill(255);
+		this.view = new DataView(this.buf.buffer);
+		this.initHeader(pageNum);
+		this.initBitmap();
+	}
+	initHeader(pageNum) {
+		this.view.setUint32(0, require_decoder.PAGE_STATE_ACTIVE, true);
+		this.view.setUint32(4, pageNum, true);
+		this.buf[8] = 254;
+		const checksum = crc32(this.buf.subarray(4, 28));
+		this.view.setUint32(28, checksum, true);
+	}
+	initBitmap() {
+		this.buf.subarray(32, 64).fill(255);
+	}
+	markBitmapWritten(idx) {
+		const bitNum = idx * 2;
+		const byteIdx = 32 + (bitNum >> 3);
+		const bitOffset = bitNum & 7;
+		this.buf[byteIdx] &= ~(1 << bitOffset);
+	}
+	hasRoom(span) {
+		return this.entryNum + span <= 126;
+	}
+	/**
+	* Write `span` 32-byte chunks starting from entryNum.
+	* First chunk is the entry header; subsequent ones are data chunks.
+	*/
+	writeRawEntry(header, dataChunks) {
+		const span = 1 + (dataChunks?.length ?? 0);
+		if (!this.hasRoom(span)) throw new PageFullError();
+		const off = 64 + this.entryNum * 32;
+		this.buf.set(header.subarray(0, 32), off);
+		this.markBitmapWritten(this.entryNum++);
+		if (dataChunks) for (const chunk of dataChunks) {
+			const chunkOff = 64 + this.entryNum * 32;
+			this.buf.set(chunk.subarray(0, Math.min(32, chunk.length)), chunkOff);
+			this.markBitmapWritten(this.entryNum++);
+		}
+	}
+	markFull() {
+		this.view.setUint32(0, require_decoder.PAGE_STATE_FULL, true);
+	}
+	getData() {
+		return this.buf;
+	}
+};
+function buildEntryHeader(nsIdx, typeCode, span, chunkIndex, key) {
+	const header = new Uint8Array(32).fill(255);
+	header[0] = nsIdx;
+	header[1] = typeCode;
+	header[2] = span;
+	header[3] = chunkIndex;
+	header.subarray(8, 24).fill(0);
+	const keyBytes = new TextEncoder().encode(key);
+	header.set(keyBytes.subarray(0, 15), 8);
+	return header;
+}
+function computeAndSetHeaderCrc(header) {
+	const crcData = new Uint8Array(28);
+	crcData.set(header.subarray(0, 4), 0);
+	crcData.set(header.subarray(8, 32), 4);
+	const checksum = crc32(crcData);
+	new DataView(header.buffer, header.byteOffset).setUint32(4, checksum, true);
+}
+/** Split data into 32-byte-aligned chunks for NVS storage. */
+function toDataChunks(data) {
+	const chunks = [];
+	const roundedSize = data.length + 31 & -32;
+	const padded = new Uint8Array(roundedSize).fill(255);
+	padded.set(data);
+	for (let i = 0; i < roundedSize; i += 32) chunks.push(padded.subarray(i, i + 32));
+	return chunks;
+}
+/** NVS partition writer — manages pages and entry placement. */
+var NVSWriter = class {
+	constructor() {
+		this.pages = [];
+		this.pageNum = 0;
+		this.curPage = this.newPage();
+	}
+	newPage() {
+		const p = new PageWriter(this.pageNum++);
+		this.pages.push(p);
+		return p;
+	}
+	ensureRoom(span) {
+		if (!this.curPage.hasRoom(span)) {
+			this.curPage.markFull();
+			this.curPage = this.newPage();
+		}
+	}
+	writeEntry(header, dataChunks) {
+		const span = 1 + (dataChunks?.length ?? 0);
+		this.ensureRoom(span);
+		this.curPage.writeRawEntry(header, dataChunks);
+	}
+	/** Write a namespace entry at ns_idx=0. Returns the namespace index assigned. */
+	writeNamespace(key, nsIdx) {
+		const header = buildEntryHeader(0, 1, 1, 255, key);
+		new DataView(header.buffer, header.byteOffset).setUint8(24, nsIdx);
+		computeAndSetHeaderCrc(header);
+		this.writeEntry(header);
+	}
+	/** Write a primitive-encoded entry. */
+	writePrimitive(nsIdx, key, encoding, value) {
+		const typeCode = require_decoder.ENCODING_TO_TYPE_CODE[encoding];
+		if (typeCode === void 0) throw new Error(`Unknown encoding: ${encoding}`);
+		const header = buildEntryHeader(nsIdx, typeCode, 1, 255, key);
+		const view = new DataView(header.buffer, header.byteOffset);
+		switch (encoding) {
+			case "u8":
+				view.setUint8(24, Number(value));
+				break;
+			case "i8":
+				view.setInt8(24, Number(value));
+				break;
+			case "u16":
+				view.setUint16(24, Number(value), true);
+				break;
+			case "i16":
+				view.setInt16(24, Number(value), true);
+				break;
+			case "u32":
+				view.setUint32(24, Number(value), true);
+				break;
+			case "i32":
+				view.setInt32(24, Number(value), true);
+				break;
+			case "u64":
+				view.setBigUint64(24, BigInt(value), true);
+				break;
+			case "i64":
+				view.setBigInt64(24, BigInt(value), true);
+				break;
+		}
+		computeAndSetHeaderCrc(header);
+		this.writeEntry(header);
+	}
+	/** Write a string entry (NUL-terminated). */
+	writeString(nsIdx, key, value) {
+		const encoded = new TextEncoder().encode(value);
+		const data = new Uint8Array(encoded.length + 1);
+		data.set(encoded);
+		data[encoded.length] = 0;
+		const chunks = toDataChunks(data);
+		const header = buildEntryHeader(nsIdx, 33, 1 + chunks.length, 255, key);
+		const hView = new DataView(header.buffer, header.byteOffset);
+		hView.setUint16(24, data.length, true);
+		const payloadCrc = crc32(data);
+		hView.setUint32(28, payloadCrc, true);
+		computeAndSetHeaderCrc(header);
+		this.writeEntry(header, chunks);
+	}
+	/** Write a blob (binary data) as V2 blob_data chunks + blob_index. */
+	writeBlobV2(nsIdx, key, data) {
+		let chunkStart = 0;
+		let chunkCount = 0;
+		let offset = 0;
+		let remainingSize = data.length;
+		while (remainingSize > 0 || chunkCount === 0) {
+			const tailroomBytes = (126 - this.curPage.entryNum - 1) * 32;
+			let chunkSize;
+			if (tailroomBytes < remainingSize) chunkSize = tailroomBytes;
+			else chunkSize = remainingSize;
+			if (chunkSize < 0) chunkSize = 0;
+			const chunkData = data.subarray(offset, offset + chunkSize);
+			const chunks = toDataChunks(chunkData);
+			const header = buildEntryHeader(nsIdx, 66, 1 + chunks.length, chunkStart + chunkCount, key);
+			const hView = new DataView(header.buffer, header.byteOffset);
+			hView.setUint16(24, chunkSize, true);
+			const payloadCrc = crc32(chunkData.length > 0 ? chunkData : new Uint8Array(0));
+			hView.setUint32(28, payloadCrc, true);
+			computeAndSetHeaderCrc(header);
+			this.writeEntry(header, chunks);
+			chunkCount++;
+			offset += chunkSize;
+			remainingSize -= chunkSize;
+			if (remainingSize > 0) {
+				this.curPage.markFull();
+				this.curPage = this.newPage();
+			}
+			if (chunkSize === 0 && remainingSize === 0) break;
+		}
+		const idxHeader = buildEntryHeader(nsIdx, 72, 1, 255, key);
+		new DataView(idxHeader.buffer, idxHeader.byteOffset).setUint32(24, data.length, true);
+		idxHeader[28] = chunkCount;
+		idxHeader[29] = chunkStart;
+		computeAndSetHeaderCrc(idxHeader);
+		this.writeEntry(idxHeader);
+	}
+	getData() {
+		const totalSize = this.pages.length * require_decoder.PAGE_SIZE;
+		const result = new Uint8Array(totalSize);
+		for (let i = 0; i < this.pages.length; i++) result.set(this.pages[i].getData(), i * require_decoder.PAGE_SIZE);
+		return result;
+	}
+};
+/**
+* Encode an NVSNamespaces object into a binary NVS partition.
+* Output is always V2 (multipage blob support enabled).
+* Partition size is auto-calculated based on data volume.
+*/
+function encodeNVS(namespaces) {
+	const writer = new NVSWriter();
+	const nsMap = /* @__PURE__ */ new Map();
+	let nextNsIdx = 1;
+	for (const [nsName, values] of Object.entries(namespaces)) {
+		let nsIdx = nsMap.get(nsName);
+		if (nsIdx === void 0) {
+			nsIdx = nextNsIdx++;
+			nsMap.set(nsName, nsIdx);
+			writer.writeNamespace(nsName, nsIdx);
+		}
+		for (const entry of values) {
+			const { name: key, encoding, value } = entry;
+			switch (encoding) {
+				case "u8":
+				case "i8":
+				case "u16":
+				case "i16":
+				case "u32":
+				case "i32":
+				case "u64":
+				case "i64":
+					writer.writePrimitive(nsIdx, key, encoding, value);
+					break;
+				case "string":
+					writer.writeString(nsIdx, key, value);
+					break;
+				case "blob_data":
+					writer.writeBlobV2(nsIdx, key, value);
+					break;
+				default: throw new Error(`Unsupported encoding: ${encoding}`);
+			}
+		}
+	}
+	return writer.getData();
+}
+//#endregion
+exports.decodeNVS = require_decoder.decodeNVS;
+exports.encodeNVS = encodeNVS;