{"_id":"@darwins-cat/namz","_rev":"2-e17dca8ffa45f3bda5061ed621fc2263","name":"@darwins-cat/namz","dist-tags":{"latest":"1.1.0"},"versions":{"1.0.0":{"name":"@darwins-cat/namz","version":"1.0.0","keywords":["nam","neural-amp-modeler","codec","float32","guitar","audio","dsp"],"author":{"name":"Oleh Tsymaienko","email":"oleh@darwinscat.com"},"license":"MIT","_id":"@darwins-cat/namz@1.0.0","maintainers":[{"name":"darwins-cat","email":"tsyma@lafox.net"}],"homepage":"https://github.com/darwinscat/namz#readme","bugs":{"url":"https://github.com/darwinscat/namz/issues"},"bin":{"namz":"bin/namz.js"},"dist":{"shasum":"1daa8c1db98ab862b8dd4d7ab75307663b76ec58","tarball":"https://registry.npmjs.org/@darwins-cat/namz/-/namz-1.0.0.tgz","fileCount":7,"integrity":"sha512-jSxj8A9vosToU41bNaAAD6JiczNCK0T97CAPhXQnZi/YPIn/NPVthTcj8BFuvLWNKpJJZtMvh8enO/lLKGAIuw==","signatures":[{"sig":"MEYCIQC0djFowNntX9byOQHOVDs/4hzDiO5jpYbQi1TcfEd1rQIhAO9jIBSnWoGBvfTOkElg8v5yspJ4obrKr1QYDsbi37bR","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":33317},"type":"module","engines":{"node":">=18"},"exports":{".":"./src/index.js"},"gitHead":"2ff42171c2b32333e9c55d4d135adfc8eb2bf3c4","scripts":{"test":"node --test"},"_npmUser":{"name":"darwins-cat","email":"tsyma@lafox.net"},"repository":{"url":"git+https://github.com/darwinscat/namz.git","type":"git","directory":"js"},"_npmVersion":"10.9.8","description":"Lossless codec for NeuralAmpModeler .nam files — ~5.5x smaller, bit-exact float32, deterministic. Byte-identical to the C++ reference.","directories":{},"_nodeVersion":"22.23.1","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/namz_1.0.0_1783242891521_0.6329443660023293","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@darwins-cat/namz","version":"1.1.0","description":"Lossless codec for NeuralAmpModeler .nam files — ~5.5x smaller, bit-exact float32, deterministic. Byte-identical to the C++ reference.","type":"module","exports":{".":"./src/index.js"},"bin":{"namz":"bin/namz.js"},"engines":{"node":">=18"},"scripts":{"test":"node --test"},"keywords":["nam","neural-amp-modeler","codec","float32","guitar","audio","dsp"],"author":{"name":"Oleh Tsymaienko","email":"oleh@darwinscat.com"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/darwinscat/namz.git","directory":"js"},"homepage":"https://github.com/darwinscat/namz#readme","bugs":{"url":"https://github.com/darwinscat/namz/issues"},"_id":"@darwins-cat/namz@1.1.0","gitHead":"691ee2b5cb93a4908aef68a2367d7d1093740937","_nodeVersion":"22.23.2","_npmVersion":"10.9.8","dist":{"integrity":"sha512-bFyds2Fa1vNEciWAeWyRRWVbhs8yjkLd1LDobHrUA1BEbqMgFpX4XQ9s6wH3UPwOCB+j6H92qsA0jTZU6N8ubA==","shasum":"305af598de0eccbe5c39d8b2db6c0223f260897e","tarball":"https://registry.npmjs.org/@darwins-cat/namz/-/namz-1.1.0.tgz","fileCount":7,"unpackedSize":33459,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIC4LzNRIq5gReEyJ438YwTsWXU1kMwMw6O+SLxXa9pFQAiB44tzzrrh44WPPy+KtskU1+PczVq9fa3EkREu0De3TTw=="}]},"_npmUser":{"name":"darwins-cat","email":"tsyma@lafox.net"},"directories":{},"maintainers":[{"name":"darwins-cat","email":"tsyma@lafox.net"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/namz_1.1.0_1788342132407_0.5084793433072359"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-05T09:14:51.369Z","modified":"2026-09-02T09:42:12.741Z","1.0.0":"2026-07-05T09:14:51.664Z","1.1.0":"2026-09-02T09:42:12.548Z"},"bugs":{"url":"https://github.com/darwinscat/namz/issues"},"author":{"name":"Oleh Tsymaienko","email":"oleh@darwinscat.com"},"license":"MIT","homepage":"https://github.com/darwinscat/namz#readme","keywords":["nam","neural-amp-modeler","codec","float32","guitar","audio","dsp"],"repository":{"type":"git","url":"git+https://github.com/darwinscat/namz.git","directory":"js"},"description":"Lossless codec for NeuralAmpModeler .nam files — ~5.5x smaller, bit-exact float32, deterministic. Byte-identical to the C++ reference.","maintainers":[{"name":"darwins-cat","email":"tsyma@lafox.net"}],"readme":"<!-- SPDX-License-Identifier: MIT -->\n# namz (JavaScript)\n\nLossless codec for [NeuralAmpModeler](https://github.com/sdatkinson/neural-amp-modeler) `.nam` files.\n\nA `.nam` is JSON whose bulk is one or more flat `\"weights\"` arrays written as ~20-character decimal\nstrings — which the NAM engine loads into `float32` **anyway**. `.namz` stores each weight as a 4-byte\nfloat32 instead: **≈5.5× smaller**, **bit-exact** to what the engine computes, and **deterministic**\n(no compression → byte-identical across runs, platforms, and languages). A small readable header exposes\ntone/gear/device metadata without decoding the weights.\n\nThis package is a **native JavaScript port** (zero dependencies, pure ESM) of the C++ reference and is\n**byte-for-byte compatible** with it and with every other port — validated against the shared\n[conformance vectors](https://github.com/darwinscat/namz/tree/main/conformance) (the cross-language TCK)\nplus a live differential fuzz against the reference binary.\n\n## Install\n\n```bash\nnpm install @darwins-cat/namz\n```\n\nNode ≥ 18. Works in browsers/bundlers too (uses only `TextEncoder`/`DataView`/`Float32Array`).\n\n## Library\n\n```js\nimport { pack, unpack, readMeta, isNamz } from \"@darwins-cat/namz\";\n\nconst nam = new TextEncoder().encode('{\"architecture\":\"WaveNet\",\"weights\":[0.5,-0.5,0.25]}');\n\nconst blob = pack(nam);               // -> Uint8Array (.namz)\nisNamz(blob);                         // true\nnew TextDecoder().decode(unpack(blob)); // '{\"architecture\":\"WaveNet\",\"weights\":[0.5,-0.5,0.25]}'\n\n// Stamp a readable metadata header (typed: \"true\"/\"false\" -> bool, digits -> int, else string;\n// a leading zero keeps it a string, so an identifier such as \"0012345\" survives intact):\nconst withMeta = pack(nam, { metadata: { tone_type: \"hi-gain\", boost: \"true\", device: \"tube:1,pnp:1\" } });\nreadMeta(withMeta); // { tone_type: 'hi-gain', boost: 'true', device: 'tube:1,pnp:1' } — no weight decode\n```\n\n### API\n\n| function | description |\n|---|---|\n| `pack(namJson, options?) -> Uint8Array` | `.nam` (Uint8Array/ArrayBuffer/string) → `.namz`. Empty on invalid JSON. |\n| `unpack(data, maxJsonBytes?) -> Uint8Array` | `.namz` → `.nam` JSON. Empty on corruption / over-cap. Never throws. |\n| `readMeta(data) -> object` | display header without touching weights. `{}` for v1 / non-`.namz`. |\n| `isNamz(data) -> boolean` | cheap magic check. |\n\n`options`: `{ shuffle = true, metadata = {} }`. `unpack` is total: for **any** input it returns a\n`Uint8Array` (empty on failure) and never throws.\n\n## CLI\n\n```bash\nnamz encode in.nam out.namz [--no-shuffle] [--set key=value ...]\nnamz decode in.namz out.nam\nnamz map    in.namz [--json]        # print the metadata header (no weight decode)\nnamz verify in.nam                  # pack->unpack round-trip check + ratio\n```\n\n## Guarantees\n\n- **Lossless to float32** — `unpack(pack(x))` is bit-exact at any nesting depth, including `-0.0`,\n  subnormals, and `FLT_MAX`.\n- **Deterministic** — `pack(x)` is byte-identical across runs and platforms; the codec is idempotent.\n- **Robust** — every malformed input (bad magic, unknown version/codec/dtype, truncation, trailing junk,\n  a lying `metaLen`/`numArrays`, an over-cap body) is rejected cleanly.\n\n### Byte-match note\n\nJavaScript has a single `Number` type, so this port ships its own JSON parse/serialize that (a) preserves\nthe integer-vs-float distinction the reference relies on (so `-18.0` stays `-18.0`, not `-18`), (b) sorts\nobject keys by UTF-8 byte order like nlohmann's `std::map`, and (c) reproduces nlohmann's exact\ndouble-to-string formatting (fixed vs scientific thresholds, `e±XX` exponents). Integer literals are kept\nexact via `BigInt` across the full int64/uint64 range. This is validated byte-for-byte against the\nreference over the whole NAM domain. Two documented edges, both outside that domain:\n\n- Non-finite weights (`NaN`/`±Inf`) are out of contract and are **rejected**, exactly as the reference\n  rejects them.\n- A *non-weight* number whose magnitude exceeds ~1e21 (or an integer past `uint64`) may differ by one ULP\n  — not from formatting, but because nlohmann's own number *parser* is not correctly rounded there. Such\n  values never occur in NAM config.\n\n## Development\n\n```bash\nnpm test        # runs the shared conformance vectors + property fuzz + adversarial suite\n```\n\nVersioned independently of the C++ reference; tracks **wire format version 2**.\n\n## License\n\nMIT — see [LICENSE](LICENSE). © 2026 Oleh Tsymaienko &lt;oleh@darwinscat.com&gt; &amp; Alisa Lafoks\n&lt;alisa@darwinscat.com&gt; (Darwin's Cat).\n","readmeFilename":"README.md"}