esp-nvs-utils 0.1.0

package/dist/esm/index.js

@@ -0,0 +1,276 @@
+import { a as PAGE_STATE_FULL, i as PAGE_STATE_ACTIVE, n as ENCODING_TO_TYPE_CODE, r as PAGE_SIZE, t as decodeNVS } from "./decoder.js";
+//#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(PAGE_SIZE).fill(255);
+		this.view = new DataView(this.buf.buffer);
+		this.initHeader(pageNum);
+		this.initBitmap();
+	}
+	initHeader(pageNum) {
+		this.view.setUint32(0, 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, 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 = 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 * PAGE_SIZE;
+		const result = new Uint8Array(totalSize);
+		for (let i = 0; i < this.pages.length; i++) result.set(this.pages[i].getData(), i * 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
+export { decodeNVS, encodeNVS };

package/dist/types/cli/esp-nvs-decode.d.ts

@@ -0,0 +1 @@
+export declare function main(args: string[]): void;

package/dist/types/constants.d.ts

@@ -0,0 +1,49 @@
+/** NVS page size in bytes. */
+export declare const PAGE_SIZE = 4096;
+/** Size of a single NVS entry in bytes. */
+export declare const ENTRY_SIZE = 32;
+/** Offset of the entry state bitmap within a page. */
+export declare const BITMAP_OFFSET = 32;
+/** Size of the entry state bitmap in bytes. */
+export declare const BITMAP_SIZE = 32;
+/** Offset of the first entry within a page. */
+export declare const FIRST_ENTRY_OFFSET = 64;
+/** Maximum number of data entries per page (126; last 2 bitmap slots are unused). */
+export declare const MAX_ENTRIES = 126;
+/** Chunk index value meaning "any chunk" (used for strings, V1 blobs, and blob_index). */
+export declare const CHUNK_ANY = 255;
+/** Page state: all bytes 0xFF, page not yet written. */
+export declare const PAGE_STATE_EMPTY = 4294967295;
+/** Page state: page is currently being written. */
+export declare const PAGE_STATE_ACTIVE = 4294967294;
+/** Page state: page is full, no more entries can be written. */
+export declare const PAGE_STATE_FULL = 4294967292;
+/** Page state: page is being erased. */
+export declare const PAGE_STATE_ERASING = 4294967288;
+/** Page state: page is corrupted. */
+export declare const PAGE_STATE_CORRUPTED = 0;
+/** NVS version byte for V1 (multipage blob disabled). */
+export declare const VERSION1 = 255;
+/** NVS version byte for V2 (multipage blob enabled). */
+export declare const VERSION2 = 254;
+/** Entry bitmap bit-pair values. */
+export declare const ENTRY_STATE_EMPTY = 3;
+export declare const ENTRY_STATE_WRITTEN = 2;
+export declare const ENTRY_STATE_ERASED = 0;
+/** Item type codes (byte 1 of entry header). */
+export declare const TYPE_U8 = 1;
+export declare const TYPE_I8 = 17;
+export declare const TYPE_U16 = 2;
+export declare const TYPE_I16 = 18;
+export declare const TYPE_U32 = 4;
+export declare const TYPE_I32 = 20;
+export declare const TYPE_U64 = 8;
+export declare const TYPE_I64 = 24;
+export declare const TYPE_STRING = 33;
+export declare const TYPE_BLOB = 65;
+export declare const TYPE_BLOB_DATA = 66;
+export declare const TYPE_BLOB_INDEX = 72;
+/** Map from type code to NVS encoding string. */
+export declare const TYPE_CODE_TO_ENCODING: Readonly<Record<number, string>>;
+/** Map from NVS encoding string to type code. */
+export declare const ENCODING_TO_TYPE_CODE: Readonly<Record<string, number>>;

package/dist/types/crc.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Pure CRC-32 implementation compatible with zlib.crc32 (polynomial 0xEDB88320).
+ * Browser-safe: no Node.js dependencies.
+ */
+/**
+ * Compute CRC-32 of data, matching Python's `zlib.crc32(data, seed)`.
+ * The default seed of 0xFFFFFFFF matches the NVS usage pattern.
+ */
+export declare function crc32(data: Uint8Array, seed?: number): number;

package/dist/types/decoder.d.ts

@@ -0,0 +1,8 @@
+import type { NVSNamespaces } from "./types.js";
+/**
+ * Decode an NVS partition binary into structured namespaces.
+ *
+ * Handles V1 (single-page blobs) and V2 (multi-page blobs).
+ * Does not support encrypted partitions.
+ */
+export declare function decodeNVS(data: ArrayBuffer | Uint8Array): NVSNamespaces;

package/dist/types/encoder.d.ts

@@ -0,0 +1,7 @@
+import type { NVSNamespaces } from "./types.js";
+/**
+ * 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.
+ */
+export declare function encodeNVS(namespaces: NVSNamespaces): Uint8Array;

package/dist/types/index.d.ts

@@ -0,0 +1,3 @@
+export { decodeNVS } from "./decoder.js";
+export { encodeNVS } from "./encoder.js";
+export type { NVSEncoding, NVSNamespaces, NVSValue } from "./types.js";

package/dist/types/types.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Encoding/type of an NVS entry value.
+ */
+export type NVSEncoding = "u8" | "i8" | "u16" | "i16" | "u32" | "i32" | "u64" | "i64" | "string" | "blob_data";
+/**
+ * A single key-value entry within a namespace.
+ *
+ * value type by encoding:
+ *   u8/i8/u16/i16/u32/i32 → number
+ *   u64/i64               → bigint (full 64-bit range)
+ *   string                → string
+ *   blob_data             → Uint8Array
+ */
+export interface NVSValue {
+    name: string;
+    encoding: NVSEncoding;
+    value: number | bigint | string | Uint8Array;
+}
+/**
+ * A decoded NVS partition.
+ * Keys are namespace names, values are the entries within that namespace.
+ */
+export type NVSNamespaces = Record<string, NVSValue[]>;

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "esp-nvs-utils",
+  "version": "0.1.0",
+  "description": "ESP-IDF NVS partition encoder/decoder for Node.js and browsers",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/cjs/index.cjs",
+  "module": "./dist/esm/index.js",
+  "bin": {
+    "esp-nvs-decode": "bin/esp-nvs-decode.cjs"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.cjs",
+      "types": "./dist/types/index.d.ts"
+    }
+  },
+  "types": "./dist/types/index.d.ts",
+  "files": [
+    "bin",
+    "dist"
+  ],
+  "scripts": {
+    "build": "npm run build:types && rolldown -c rolldown.config.ts",
+    "build:types": "tsc -p tsconfig.build.json",
+    "decode": "node ./bin/esp-nvs-decode.cjs",
+    "test": "node --experimental-vm-modules node_modules/.bin/jest --config jest.config.cjs",
+    "lint": "oxlint --deny-warnings src test",
+    "format": "oxfmt src test",
+    "format:check": "oxfmt --check src test",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.14",
+    "@types/node": "^22.15.18",
+    "jest": "^29.7.0",
+    "oxfmt": "^0.48.0",
+    "oxlint": "^0.16.7",
+    "rolldown": "^1.0.0-beta.9",
+    "ts-jest": "^29.3.2",
+    "typescript": "^5.8.3"
+  }
+}