esp-nvs-utils 0.1.0

package/LICENSE

@@ -0,0 +1,185 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and
+ distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the
+ copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other
+ entities that control, are controlled by, or are under common control with
+ that entity. For the purposes of this definition, "control" means (i) the
+ power, direct or indirect, to cause the direction or management of such
+ entity, whether by contract or otherwise, or (ii) ownership of fifty percent
+ (50%) or more of the outstanding shares, or (iii) beneficial ownership of
+ such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising
+ permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including
+ but not limited to software source code, documentation source, and
+ configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or
+ translation of a Source form, including but not limited to compiled object
+ code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form,
+ made available under the License, as indicated by a copyright notice that is
+ included in or attached to the work (an example is provided in the Appendix
+ below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that
+ is based on (or derived from) the Work and for which the editorial revisions,
+ annotations, elaborations, or other modifications represent, as a whole, an
+ original work of authorship. For the purposes of this License, Derivative
+ Works shall not include works that remain separable from, or merely link (or
+ bind by name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original
+ version of the Work and any modifications or additions to that Work or
+ Derivative Works thereof, that is intentionally submitted to Licensor for
+ inclusion in the Work by the copyright owner or by an individual or Legal
+ Entity authorized to submit on behalf of the copyright owner. For the purposes
+ of this definition, "submitted" means any form of electronic, verbal, or
+ written communication sent to the Licensor or its representatives, including
+ but not limited to communication on electronic mailing lists, source code
+ control systems, and issue tracking systems that are managed by, or on behalf
+ of, the Licensor for the purpose of discussing and improving the Work, but
+ excluding communication that is conspicuously marked or otherwise designated in
+ writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf
+ of whom a Contribution has been received by Licensor and subsequently
+ incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this
+ License, each Contributor hereby grants to You a perpetual, worldwide,
+ non-exclusive, no-charge, royalty-free, irrevocable copyright license to
+ reproduce, prepare Derivative Works of, publicly display, publicly perform,
+ sublicense, and distribute the Work and such Derivative Works in Source or
+ Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this
+ License, each Contributor hereby grants to You a perpetual, worldwide,
+ non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this
+ section) patent license to make, have made, use, offer to sell, sell, import,
+ and otherwise transfer the Work, where such license applies only to those
+ patent claims licensable by such Contributor that are necessarily infringed by
+ their Contribution(s) alone or by combination of their Contribution(s) with the
+ Work to which such Contribution(s) was submitted. If You institute patent
+ litigation against any entity (including a cross-claim or counterclaim in a
+ lawsuit) alleging that the Work or a Contribution incorporated within the Work
+ constitutes direct or contributory patent infringement, then any patent
+ licenses granted to You under this License for that Work shall terminate as of
+ the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or
+ Derivative Works thereof in any medium, with or without modifications, and in
+ Source or Object form, provided that You meet the following conditions:
+
+ (a) You must give any other recipients of the Work or Derivative Works a copy
+     of this License; and
+
+ (b) You must cause any modified files to carry prominent notices stating that
+     You changed the files; and
+
+ (c) You must retain, in the Source form of any Derivative Works that You
+     distribute, all copyright, patent, trademark, and attribution notices from
+     the Source form of the Work, excluding those notices that do not pertain to
+     any part of the Derivative Works; and
+
+ (d) If the Work includes a "NOTICE" text file as part of its distribution,
+     then any Derivative Works that You distribute must include a readable copy
+     of the attribution notices contained within such NOTICE file, excluding
+     those notices that do not pertain to any part of the Derivative Works, in
+     at least one of the following places: within a NOTICE text file distributed
+     as part of the Derivative Works; within the Source form or documentation,
+     if provided along with the Derivative Works; or, within a display generated
+     by the Derivative Works, if and wherever such third-party notices normally
+     appear. The contents of the NOTICE file are for informational purposes only
+     and do not modify the License. You may add Your own attribution notices
+     within Derivative Works that You distribute, alongside or as an addendum to
+     the NOTICE text from the Work, provided that such additional attribution
+     notices cannot be construed as modifying the License.
+
+ You may add Your own copyright statement to Your modifications and may provide
+ additional or different license terms and conditions for use, reproduction, or
+ distribution of Your modifications, or for any such Derivative Works as a
+ whole, provided Your use, reproduction, and distribution of the Work otherwise
+ complies with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any
+ Contribution intentionally submitted for inclusion in the Work by You to the
+ Licensor shall be under the terms and conditions of this License, without any
+ additional terms or conditions. Notwithstanding the above, nothing herein shall
+ supersede or modify the terms of any separate license agreement you may have
+ executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names,
+ trademarks, service marks, or product names of the Licensor, except as
+ required for reasonable and customary use in describing the origin of the Work
+ and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in
+ writing, Licensor provides the Work (and each Contributor provides its
+ Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied, including, without limitation, any warranties
+ or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+ PARTICULAR PURPOSE. You are solely responsible for determining the
+ appropriateness of using or redistributing the Work and assume any risks
+ associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in
+ tort (including negligence), contract, or otherwise, unless required by
+ applicable law (such as deliberate and grossly negligent acts) or agreed to in
+ writing, shall any Contributor be liable to You for damages, including any
+ direct, indirect, special, incidental, or consequential damages of any
+ character arising as a result of this License or out of the use or inability to
+ use the Work (including but not limited to damages for loss of goodwill, work
+ stoppage, computer failure or malfunction, or any and all other commercial
+ damages or losses), even if such Contributor has been advised of the
+ possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or
+ Derivative Works thereof, You may choose to offer, and charge a fee for,
+ acceptance of support, warranty, indemnity, or other liability obligations
+ and/or rights consistent with this License. However, in accepting such
+ obligations, You may act only on Your own behalf and on Your sole
+ responsibility, not on behalf of any other Contributor, and only if You agree
+ to indemnify, defend, and hold each Contributor harmless for any liability
+ incurred by, or claims asserted against, such Contributor by reason of your
+ accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+ To apply the Apache License to your work, attach the following boilerplate
+ notice, with the fields enclosed by brackets "[]" replaced with your own
+ identifying information. (Don't include the brackets!)  The text should be
+ enclosed in the appropriate comment syntax for the file format. We also
+ recommend that a file or class name and description of purpose be included on
+ the same "printed page" as the copyright notice for easier identification
+ within third-party archives.
+
+ Copyright [yyyy] [name of copyright owner]
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.

package/README.md

@@ -0,0 +1,111 @@
+# esp-nvs-utils-js
+
+NVS (Non-volatile storage) partition parser and encoder for [Espressif's](https://www.espressif.com/) ESP32 line of chips. It is written in TypeScript and supports running in the browser and node.js
+
+
+See the official [esp-idf documentation about the NVS library](https://docs.espressif.com/projects/esp-idf/en/stable/esp32/api-reference/storage/nvs_flash.html) for more information about NVS.
+
+## Installation
+
+```sh
+npm i --save esp-nvs-utils
+```
+
+## API
+
+```ts
+
+/**
+ * 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[]>;
+
+/**
+ * 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 function encodeNVS(namespaces: NVSNamespaces): Uint8Array;
+
+/**
+ * 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;
+
+```
+
+## Usage
+
+Consult the following example:
+
+```ts
+import { decodeNVS, encodeNVS, type NVSNamespaces } from "esp-nvs-utils";
+
+const input: NVSNamespaces = {
+    namespace1: [
+        { name: "my_blob", encoding: "blob_data", value: new Uint8Array([1, 2, 3, 4]) },
+    ],
+    namespace2: [
+        { name: "my_int", encoding: "u32", value: 42 },
+        { name: "a_str", encoding: "string", value: "ExampleNetwork" },
+       
+    ],
+};
+
+const binary = encodeNVS(input);
+
+const decoded = decodeNVS(binary);
+
+console.log(decoded.namespace1[0]);
+
+console.log(decoded.namespace2[0]);
+console.log(decoded.namespace2[1]);
+
+```
+
+## Development
+
+```sh
+# Install dev dependenciess
+npm install
+
+# Run unit-tests (requires Python and python-cryptography)
+npm run test
+
+# Build
+npm run build
+
+# Format
+npm run format
+
+# Lint
+npm run lint
+
+```
+
+
+## License
+
+Apache-2.0, see [./LICENSE](./LICENSE). This project includes the original Python NVS parser/generator pulled from esp-idf under `./python_original`, which is used during unit-tests. It is licensed under the same license.

package/bin/esp-nvs-decode.cjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const cliPath = path.resolve(__dirname, "..", "dist", "cjs", "esp-nvs-decode.cjs");
+
+if (!fs.existsSync(cliPath)) {
+  console.error("Build output not found. Run `npm run build` first.");
+  process.exit(1);
+}
+
+require(cliPath).main(process.argv.slice(2));

package/dist/cjs/decoder-C-ve19I_.js

@@ -0,0 +1,284 @@
+//#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/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);
+			payload.subarray(0, size).filter((_, idx) => {
+				const slice = payload.subarray(0, size);
+				let last = slice.length - 1;
+				while (last >= 0 && slice[last] === 0) last--;
+				return idx <= last;
+			});
+			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, "crc32", {
+	enumerable: true,
+	get: function() {
+		return crc32;
+	}
+});
+Object.defineProperty(exports, "decodeNVS", {
+	enumerable: true,
+	get: function() {
+		return decodeNVS;
+	}
+});