{"_id":"@azghr/debias","name":"@azghr/debias","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@azghr/debias","version":"0.1.0","description":"Debias a biased bitstream (e.g. from a hardware/quantum RNG) with the Von Neumann extractor and an optional XOR-fold whitener. Classical, zero deps. NOT a cryptographic RNG.","license":"MIT","type":"module","sideEffects":false,"main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"engines":{"node":">=18"},"scripts":{"build":"tsup src/index.ts --format esm,cjs --dts --sourcemap --clean","test":"vitest run","test:watch":"vitest","typecheck":"tsc --noEmit","lint":"eslint src test examples","demo":"tsx examples/demo.ts","check":"npm run typecheck && npm run lint && npm run test && npm run build","prepublishOnly":"npm run check"},"keywords":["rng","random","bias","debias","von-neumann","whitening","quantum","hardware","entropy","extractor"],"devDependencies":{"@eslint/js":"^9.18.0","eslint":"^9.18.0","tsx":"^4.19.2","typescript":"^5.7.3","typescript-eslint":"^8.19.1","vitest":"^2.1.8","tsup":"^8.3.5"},"gitHead":"462232c5a4462505f98b904b0ef67761c2d12b3d","_id":"@azghr/debias@0.1.0","_nodeVersion":"24.12.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-te5VdkMpfFSjM+QmWcDtzEf0C6w5Url/JACl3DPd5+JLH8lfA3YPSk3PFEZ+liuE5Rh2pX2liiRkUyBM0tLXKA==","shasum":"39370fc7345fd200539d614cd27f42a546db79ba","tarball":"https://registry.npmjs.org/@azghr/debias/-/debias-0.1.0.tgz","fileCount":10,"unpackedSize":41729,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQD4BBjku29xQevwxtUpOcH8pN8KjB+triKAkzr6ApldMAIhAPcow6RkaeXaKgtwjHEy9a67jvsRQNU9qgpiG6/skBi5"}]},"_npmUser":{"name":"azghr","email":"masgharali.eng@gmail.com"},"directories":{},"maintainers":[{"name":"azghr","email":"masgharali.eng@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/debias_0.1.0_1784984348761_0.40324618823427216"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-25T12:59:08.536Z","0.1.0":"2026-07-25T12:59:08.879Z","modified":"2026-07-25T12:59:09.117Z"},"maintainers":[{"name":"azghr","email":"masgharali.eng@gmail.com"}],"description":"Debias a biased bitstream (e.g. from a hardware/quantum RNG) with the Von Neumann extractor and an optional XOR-fold whitener. Classical, zero deps. NOT a cryptographic RNG.","keywords":["rng","random","bias","debias","von-neumann","whitening","quantum","hardware","entropy","extractor"],"license":"MIT","readme":"# @azghr/debias\n\n[![npm](https://img.shields.io/npm/v/@azghr/debias)](https://www.npmjs.com/package/@azghr/debias)\n[![MIT License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)\n\n> Debias a biased bitstream (e.g. from a hardware/quantum RNG) with the Von Neumann extractor and an optional XOR-fold whitener. Classical, zero deps. NOT a cryptographic RNG.\n\n## The problem\n\nHardware and quantum RNGs emit biased bitstreams. You must debias them before use, but the classic Von Neumann extractor is subtle to implement correctly. Standalone debiasing utilities are scarce and often untested on edge cases. This fills that gap for anyone consuming hardware/QRNG feeds in research, IoT, or novelty APIs.\n\n## Install\n\n```bash\nnpm install @azghr/debias\n# or\npnpm add @azghr/debias\n# or\nyarn add @azghr/debias\n```\n\n## Use\n\n```typescript\nimport { vonNeumann, bias } from \"@azghr/debias\";\n\nconst biasedBits = new Uint8Array([1, 1, 1, 0, 0, 0, 1, 0]);\nconsole.log(bias(biasedBits));           // 0.125 (biased)\nconst debiasedBits = vonNeumann(biasedBits);\nconsole.log(bias(debiasedBits));         // 0.0 (unbiased)\n```\n\n### Real-world hardware QRNG processing\n\n```typescript\nimport { vonNeumann, bias, packBytes } from \"@azghr/debias\";\n\nconst qrngBits = generateFromHardwareQRNG(100000);\nconsole.log(\"Raw bias:\", bias(qrngBits));        // 0.201\nconst debiased = vonNeumann(qrngBits);\nconsole.log(\"Debiased:\", bias(debiased));        // 0.002\nconst packed = packBytes(debiased);\nconsole.log(\"Size:\", packed.length, \"bytes\");     // Efficient storage\n```\n\n### XOR-fold for problematic sources\n\n```typescript\nimport { xorFold } from \"@azghr/debias\";\n\n// All equal pairs (Von Neumann produces nothing)\nconst problematic = new Uint8Array([0, 0, 1, 1, 0, 0, 1, 1]);\nconst whitened = xorFold(problematic, 4);\nconsole.log(whitened);  // [0, 0, 0, 0] - still processes data\n```\n\n## API\n\n### `vonNeumann(bits: Bits): Bits`\n\nApplies Von Neumann extractor: `01→0`, `10→1`, equal pairs discarded. Trailing odd bit ignored. Output length varies (≈ input * p(1-p)).\n\n- `bits`: Input bitstream (elements must be `0` or `1`)\n- Returns: Debias bitstream\n- Throws: `InvalidBit` if invalid input\n\n### `xorFold(bits: Bits, blockSize?: number): Bits`\n\nXOR-folds by reshaping into blocks and XORing corresponding positions. Weaker than Von Neumann but handles problematic sources.\n\n- `bits`: Input bitstream (elements must be `0` or `1`)\n- `blockSize`: Block size (default: `2`, must be ≥ 1)\n- Returns: Whitened bitstream\n- Throws: `InvalidBit` if invalid input, `Error` if `blockSize < 1`\n\n### `bias(bits: Bits): number`\n\nReturns `mean(bits) - 0.5` (estimates `P(1) - 0.5`). Returns `0` for empty input.\n\n- `bits`: Input bitstream (elements must be `0` or `1`)\n- Returns: Bias measurement\n- Throws: `InvalidBit` if invalid input\n\n### `packBytes(bits: Bits): Uint8Array` / `unpackBytes(bytes: Uint8Array): Bits`\n\nMSB-first bit packing/unpacking. Non-multiple-of-8 inputs padded with zeros.\n\n- `packBytes`: Returns packed bytes\n- `unpackBytes`: Returns 8 * bytes.length bits\n- Throws: `InvalidBit` if invalid input (packBytes only)\n\n### `InvalidBit extends Error`\n\nThrown when bit value is invalid. Contains `readonly index: number`.\n\n## Security Notice\n\n**NOT FOR CRYPTOGRAPHIC USE** — assumes independent bits. For crypto, use WebCrypto API or `crypto.randomBytes()`.\n\n## Non-goals\n\nThis does NOT: generate random numbers, handle correlated sources (use Toeplitz/hashing), estimate entropy beyond bias, or replace CSPRNGs.\n\n## TypeScript note\n\nFull TypeScript support included. Exported `Bits` type is `Uint8Array` (elements must be `0` or `1`).\n\n## License\n\nMIT","readmeFilename":"README.md","_rev":"1-f484f6e3a4b1fcb098c3f5da527dddfa"}