polar_codec_wasm 1.0.0 → 1.0.2

package/LICENSE

@@ -1,7 +1,7 @@
-Copyright 2026 Aluria
-
-Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
-
+Copyright 2026 Aluria
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
 THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,84 +1,139 @@
 # polar_codec_wasm
 
-A WebAssembly implementation of **Polar Codes** -- a class of error-correcting codes that achieve the capacity of symmetric binary-input discrete memoryless channels.
+[![npm version](https://img.shields.io/npm/v/polar_codec_wasm.svg)](https://www.npmjs.com/package/polar_codec_wasm)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-blue.svg)](https://www.typescriptlang.org/)
 
-The codec is written in Rust ([`polar_codec`](https://crates.io/crates/polar_codec)), compiled to WebAssembly via [wasm-pack](https://rustwasm.github.io/wasm-pack/), and wrapped in a zero-dependency TypeScript package that works in **Node.js**, **browsers**, and **Deno**.
+A high-performance, **zero-dependency** WebAssembly implementation of **Polar Codes** — a class of Forward Error Correction (FEC) codes that achieve the capacity of symmetric binary-input discrete memoryless channels.
+
+The heavy-lifting core is written in Rust ([`polar_codec`](https://crates.io/crates/polar_codec)), compiled to WebAssembly, and embedded directly via Base64. This architectural design completely eliminates runtime garbage collection (GC) overhead during intensive decoding arrays, while bypassing the headache of asynchronous `.wasm` file fetching. 
+
+It works entirely synchronously out-of-the-box in **Node.js**, **Browsers**, and **Deno**.
+
+## Features
+
+- **Zero Dependencies:** The Wasm binary is base64-inlined. Import it and run it synchronously anywhere.
+- **High Performance:** Core SCL decoding operations are executed in Rust, circumventing JS engine limitations and GC pauses.
+- **SCL Decoding:** Successive Cancellation List decoding with a configurable list size `L`.
+- **CRC-Aided:** 80+ built-in CRC algorithms (CRC-8 through CRC-82) + full support for user-defined polynomials.
+- **Frozen Bits Generation:** Out-of-the-box support for 5G NR, Reed-Muller, and Gaussian Approximation (GA) construction methods.
+- **Bit & Byte APIs:** Effortlessly encode/decode raw byte arrays (`Uint8Array`) or specific 0/1 bit arrays.
 
 ## Install
 
+### Package Managers
+
 ```bash
 npm install polar_codec_wasm
 # or
 pnpm add polar_codec_wasm
-# or
-yarn add polar_codec_wasm
+
+```
+
+### Via CDN (Direct Browser Usage)
+
+For native browser environments without bundlers, you can include the IIFE bundle directly via **jsDelivr** or **unpkg**. The package will automatically expose a global `PolarCodec` constructor on the `window` object.
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/polar_codec_wasm@1.0.0/dist/index.iife.min.js"></script>
+
+<script src="https://unpkg.com/polar_codec_wasm@1.0.0/dist/index.iife.js"></script>
+
 ```
 
 ## Quick Start
 
+### 1. Browser Environment (via CDN)
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/polar_codec_wasm/dist/index.iife.js"></script>
+<script>
+  // Encode string data at byte-level
+  const inputString = "Hello, Polar Codec!";
+  const data = new TextEncoder().encode(inputString);
+
+  // Initialize Codec (K = data.length * 8 bits)
+  const codec = new PolarCodec(data.length * 8);
+  const encoded = codec.encode(data);
+
+  // Simulate BPSK channel (bits to Log-Likelihood Ratios)
+  const llr = PolarCodec.bits_to_llr(encoded);
+
+  // Decode back to bytes
+  const decoded = codec.decode(llr);
+  console.log("Decoded:", new TextDecoder().decode(decoded)); // "Hello, Polar Codec!"
+</script>
+
+```
+
+### 2. Bundler / Node.js Environment (Byte-Level)
+
 ```ts
-import { PolarCodec, Crc } from "polar_codec_wasm";
+import { PolarCodec } from "polar_codec_wasm";
 
-// K=96 information bits, N=128 codeword length (default 5G frozen bits, no CRC)
-const codec = new PolarCodec(96, 128);
+const data = new Uint8Array([72, 101, 108, 108, 111]); // "Hello"
+const codec = new PolarCodec(data.length * 8, 64);
 
-// Encode
-const data    = new Uint8Array([1, 0, 1, 1, 0, 0, 1, 0 /* ... */]);
-const encoded = codec.encode_bit(data);
+const encoded = codec.encode(data);
+const llr = PolarCodec.bits_to_llr(encoded);
+const decoded = codec.decode(llr);
 
-// Decode (LLR: negative = bit 1, positive = bit 0)
-const llr     = to_llr(encoded);
-const decoded = codec.decode_bit(llr);
 ```
 
-## Features
+### 3. Bit-Level Communication Simulation
 
-| Feature | Description |
-|---------|-------------|
-| **SCL decoding** | Successive Cancellation List decoding with configurable list size `L` |
-| **CRC-aided** | 80+ built-in CRC algorithms (CRC-8 through CRC-82) + user-defined |
-| **Frozen bits** | 5G NR, Reed-Muller, and Gaussian Approximation construction methods |
-| **Byte & bit APIs** | `encode` / `decode` for byte arrays, `encode_bit` / `decode_bit` for 0/1 arrays |
-| **Zero deps** | The Wasm binary is embedded as Base64 -- no file loading at runtime |
-| **Cross-platform** | Node.js >= 16, browsers (ESM / IIFE), Deno |
+```ts
+import { PolarCodec, Crc } from "polar_codec_wasm";
+
+// K=96 info bits, N=128 codeword length, List Size=4, 5G Frozen bits + CRC-16
+const codec = new PolarCodec(96, 128, 4, { 
+  frozenBits: "5G",
+  crc: Crc.CRC_16_UMTS 
+});
+
+const dataBits = new Uint8Array([1, 0, 1, 1, 0, 0, 1, 0 /* ... up to 96 bits */]);
+const encodedBits = codec.encode_bit(dataBits);
+
+// Receiver side LLR mapping: negative = bit 1, positive = bit 0
+const llr = PolarCodec.bits_to_llr(encodedBits);
+const decodedBits = codec.decode_bit(llr);
 
-## API
+```
+
+## API Reference
 
-### `new PolarCodec(k, n, l?, options?)`
+### `new PolarCodec(k, n?, l?, options?)`
 
 | Param | Type | Default | Description |
-|-------|------|---------|-------------|
-| `k` | `number` | | Information bits per codeword |
-| `n` | `number` | | Codeword length (power of two, >= k) |
-| `l` | `number` | `4` | SCL list size (higher = better correction, slower) |
-| `options.frozenBits` | `FrozenBitsMethod` | auto | `"5G"`, `"RM"`, or `{ type: "GA", sigma?: number }` |
-| `options.crc` | `Crc \| DefinedCrc \| null` | `null` | CRC algorithm or `null` for none |
+| --- | --- | --- | --- |
+| `k` | `number` |  | Information bits per codeword |
+| `n` | `number` | `2^ceil(log2(k))` | Codeword length (must be power of two, $\ge k$) |
+| `l` | `number` | `4` | SCL list size (higher = better correction, slower execution) |
+| `options.frozenBits` | `FrozenBitsMethod` | `auto` | `"5G"`, `"RM"`, or `{ type: "GA", sigma?: number }` |
+| `options.crc` | `Crc | DefinedCrc | null` | `null` | CRC algorithm or `null` for none |
+
+> **Note on Browser (CDN) Built-in CRCs:** When using the global CDN script, built-in CRC enums can be accessed via `polar_codec.Crc` (e.g., `polar_codec.Crc.CRC_16_UMTS`).
 
-### Methods
+### Core Methods
 
 | Method | Input | Output | Description |
-|--------|-------|--------|-------------|
-| `encode_bit(src)` | `Uint8Array` of 0/1 | `Uint8Array` of 0/1 (length n) | Encode information bits |
-| `decode_bit(llr)` | `Float32Array` (length n) | `Uint8Array` of 0/1 (length k) | Decode LLRs to information bits |
+| --- | --- | --- | --- |
 | `encode(src)` | `Uint8Array` (bytes) | `Uint8Array` (packed bytes) | Byte-level encode |
-| `decode(llr)` | `Float32Array` (length n) | `Uint8Array` (packed bytes) | Byte-level decode |
+| `decode(llr)` | `Float32Array` (length n) | `Uint8Array` (packed bytes) | Byte-level SCL decode |
+| `encode_bit(src)` | `Uint8Array` of 0/1 | `Uint8Array` of 0/1 | Bit-level encode |
+| `decode_bit(llr)` | `Float32Array` (length n) | `Uint8Array` of 0/1 | Bit-level SCL decode |
+| `PolarCodec.bits_to_llr(bits)` | `Uint8Array` | `Float32Array` | Utility: Maps `0 -> +10.0`, `1 -> -10.0` |
 
-### Frozen-bits Methods
+### User-Defined CRC
 
-| Method | Description |
-|--------|-------------|
-| `"5G"` | 5G NR standard frozen-bits pattern (default for N <= 1024) |
-| `"RM"` | Reed-Muller based construction (default for N > 1024) |
-| `"GA"` | Gaussian Approximation with configurable `sigma` parameter |
-
-### User-defined CRC
+You can strictly define custom polynomials if the built-in standards don't match your protocol:
 
 ```ts
-import { PolarCodec, Crc } from "polar_codec_wasm";
+import { PolarCodec } from "polar_codec_wasm";
 
 const codec = new PolarCodec(96, 128, 4, {
   crc: {
-    name: "My CRC",
+    name: "My Custom CRC",
     width: 16,
     poly: 0x8005,
     init: 0xFFFF,
@@ -87,64 +142,48 @@ const codec = new PolarCodec(96, 128, 4, {
     xorout: 0xFFFF,
   },
 });
-```
 
-### Built-in CRC Algorithms
-
-All variants from the `crc` crate are available via the `Crc` enum:
-
-```ts
-import { Crc } from "polar_codec_wasm";
-
-new PolarCodec(96, 128, 4, { crc: Crc.CRC_16_UMTS });
-new PolarCodec(96, 128, 4, { crc: Crc.CRC_24_LTE_A });
-new PolarCodec(96, 128, 4, { crc: Crc.CRC_32_ISCSI });
 ```
 
 ## Examples
 
-The `examples/` directory contains runnable demos:
+Runnable demos are located in the `examples/` directory. Clone the repo and run:
 
 ```bash
 # Basic round-trip (bit-level and byte-level)
 npx tsx examples/basic.ts
 
 # Frozen-bits and CRC parameter combinations
-npx tsx examples/paramaters.ts
+npx tsx examples/parameters.ts
 
-# BER simulation under Gaussian noise
+# BER (Bit Error Rate) simulation under Gaussian noise
 npx tsx examples/noise.ts
 
-# Encode/decode latency benchmark
-npx tsx examples/performanec.ts
+# Encode/decode latency and throughput benchmark
+npx tsx examples/performance.ts
+
 ```
 
-## Architecture
+##  Architecture & Build
 
-```
+```text
 TypeScript API  ──►  wasm-bindgen  ──►  Rust Codec  ──►  polar_codec crate
        │
-       └──  Wasm binary embedded as Base64 (no file I/O needed)
-```
-
-The build pipeline (`pnpm run build`):
-
-1. Compiles Rust to `wasm32-unknown-unknown` via `wasm-pack build --target web`.
-2. Converts the `.wasm` file to a Base64 string embedded in `lib/wasm-b64.ts`.
-3. Bundles three output formats via esbuild: **ESM**, **CJS**, and **IIFE** (for `<script>` tags).
-4. Generates `.d.ts` declaration files with `tsc`.
+       └──  Wasm binary embedded as Base64 (No asynchronous file I/O)
 
-## Build from Source
+```
 
-Requires: [Rust](https://rustup.rs/), [wasm-pack](https://rustwasm.github.io/wasm-pack/), [pnpm](https://pnpm.io/).
+Building from source:
 
 ```bash
-git clone https://github.com/Wu-Yijun/polar-codec-wasm.git
-cd polar-codec-wasm
+git clone https://github.com/Wu-Yijun/polar_codec_wasm.git
+cd polar_codec_wasm
 pnpm install
-pnpm run build     # compiles Rust -> wasm -> Base64 -> ESM/CJS/IIFE bundles
+pnpm run build
+
 ```
 
 ## License
 
-MIT
+[MIT](LICENSE) © Aluria
+