polar_codec_wasm 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,389 @@
+//#region pkg/polar_codec_wasm.d.ts
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * Description of a user-defined CRC algorithm.
+ *
+ * Fields follow the [Catalogue of parametrised CRC algorithms](https://reveng.sourceforge.io/crc-catalogue/all.htm).
+ * Instances are created from JavaScript via the `new Algorithm(...)` constructor.
+ */
+declare class Algorithm {
+  free(): void;
+  [Symbol.dispose](): void;
+  /**
+   * Construct a new CRC algorithm descriptor.
+   *
+   * This is the JavaScript-callable constructor.
+   */
+  constructor(width: number, poly: bigint, init: bigint, refin: boolean, refout: boolean, xorout: bigint);
+  /**
+   * The settings of the bit cells at the start of each calculation,
+   * before reading the first message bit.
+   */
+  init: bigint;
+  /**
+   * The generator polynomial that sets the feedback tap positions of the
+   * shift register.  The least significant bit corresponds to the inward
+   * end of the shift register and is always set.  The highest-order term
+   * is omitted.
+   */
+  poly: bigint;
+  /**
+   * If `true`, the characters of the message are read bit-by-bit,
+   * **least** significant bit first.  If `false`, most significant bit
+   * first.
+   */
+  refin: boolean;
+  /**
+   * If `true`, the register contents are reflected before the final XOR.
+   */
+  refout: boolean;
+  /**
+   * The number of bit cells in the linear feedback shift register; the
+   * degree of the generator polynomial, minus one.
+   */
+  width: number;
+  /**
+   * The XOR value applied to the register after the last message bit has
+   * been read (and after the optional reflection).
+   */
+  xorout: bigint;
+}
+/**
+ * WebAssembly-exported Polar Codec.
+ *
+ * Wraps the Rust `polar_codec::PolarCodec` and provides encode/decode
+ * methods that accept and return flat arrays suitable for JavaScript.
+ */
+declare class Codec {
+  free(): void;
+  [Symbol.dispose](): void;
+  /**
+   * Decode LLRs back to a byte array.
+   *
+   * The inverse of [`encode`](Codec::encode): decodes the LLRs to bits and
+   * packs them into bytes.  The returned array has length `k / 8` (rounded up).
+   */
+  decode(llr: Float32Array): Uint8Array;
+  /**
+   * Decode a codeword given as **log-likelihood ratios** back to information bits.
+   *
+   * `llr` must contain `n` floats.  A negative value represents bit 1,
+   * a positive value represents bit 0 (higher magnitude = higher confidence).
+   * Returns a `Uint8Array` of length `k` with the decoded information bits.
+   */
+  decode_bit(llr: Float32Array): Uint8Array;
+  /**
+   * Encode a byte array into a codeword.
+   *
+   * Internally converts bytes to bits, encodes, and returns the result as
+   * packed bytes.  `src.len() * 8` must equal `k`.
+   */
+  encode(src: Uint8Array): Uint8Array;
+  /**
+   * Encode a sequence of **information bits** into a codeword of `n` bits.
+   *
+   * `src` must contain exactly `k` elements, each `0` or `1`.
+   * Returns a `Uint8Array` of length `n` with the encoded bits (0/1).
+   */
+  encode_bit(src: Uint8Array): Uint8Array;
+  /**
+   * Create a new Polar Codec instance.
+   *
+   * # Arguments
+   *
+   * * `k`       - Number of information bits per codeword.
+   * * `n`       - Total codeword length (power of two, >= k).
+   * * `l`       - SCL list size (higher = better but slower).
+   * * `crc`     - CRC algorithm selector (see [`Crc`]).
+   * * `fb`      - Frozen-bits construction method (see [`FrozenBits`]).
+   * * `user_crc`- Optional custom CRC algorithm (used when `crc == Crc::UserDefined`).
+   * * `sigma`   - Optional sigma for the GA method (defaults to 0.5).
+   */
+  constructor(k: number, n: number, l: number, crc: Crc, fb: FrozenBits, user_crc?: Algorithm | null, sigma?: number | null);
+}
+/**
+ * Enumeration of all CRC algorithms available in the `crc` crate.
+ *
+ * Each variant maps 1-to-1 with a constant in the `crc` crate (e.g.
+ * `crc::CRC_16_UMTS`).  The numeric values are explicit to keep the
+ * JavaScript enum stable.
+ */
+declare enum Crc {
+  /**
+   * No CRC -- pass-through.
+   */
+  None = 0,
+  /**
+   * Marker: use the user-supplied [`Algorithm`] instead of a built-in.
+   */
+  UserDefined = 1,
+  CRC_3_GSM = 2,
+  CRC_3_ROHC = 3,
+  CRC_4_G_704 = 4,
+  CRC_4_INTERLAKEN = 5,
+  CRC_5_EPC_C1G2 = 6,
+  CRC_5_G_704 = 7,
+  CRC_5_USB = 8,
+  CRC_6_CDMA2000_A = 9,
+  CRC_6_CDMA2000_B = 10,
+  CRC_6_DARC = 11,
+  CRC_6_G_704 = 12,
+  CRC_6_GSM = 13,
+  CRC_7_MMC = 14,
+  CRC_7_ROHC = 15,
+  CRC_7_UMTS = 16,
+  CRC_8_AUTOSAR = 17,
+  CRC_8_BLUETOOTH = 18,
+  CRC_8_CDMA2000 = 19,
+  CRC_8_DARC = 20,
+  CRC_8_DVB_S2 = 21,
+  CRC_8_GSM_A = 22,
+  CRC_8_GSM_B = 23,
+  CRC_8_HITAG = 24,
+  CRC_8_I_432_1 = 25,
+  CRC_8_I_CODE = 26,
+  CRC_8_LTE = 27,
+  CRC_8_MAXIM_DOW = 28,
+  CRC_8_MIFARE_MAD = 29,
+  CRC_8_NRSC_5 = 30,
+  CRC_8_OPENSAFETY = 31,
+  CRC_8_ROHC = 32,
+  CRC_8_SAE_J1850 = 33,
+  CRC_8_SMBUS = 34,
+  CRC_8_TECH_3250 = 35,
+  CRC_8_WCDMA = 36,
+  CRC_10_ATM = 37,
+  CRC_10_CDMA2000 = 38,
+  CRC_10_GSM = 39,
+  CRC_11_FLEXRAY = 40,
+  CRC_11_UMTS = 41,
+  CRC_12_CDMA2000 = 42,
+  CRC_12_DECT = 43,
+  CRC_12_GSM = 44,
+  CRC_12_UMTS = 45,
+  CRC_13_BBC = 46,
+  CRC_14_DARC = 47,
+  CRC_14_GSM = 48,
+  CRC_15_CAN = 49,
+  CRC_15_MPT1327 = 50,
+  CRC_16_ARC = 51,
+  CRC_16_CDMA2000 = 52,
+  CRC_16_CMS = 53,
+  CRC_16_DDS_110 = 54,
+  CRC_16_DECT_R = 55,
+  CRC_16_DECT_X = 56,
+  CRC_16_DNP = 57,
+  CRC_16_EN_13757 = 58,
+  CRC_16_GENIBUS = 59,
+  CRC_16_GSM = 60,
+  CRC_16_IBM_3740 = 61,
+  CRC_16_IBM_SDLC = 62,
+  CRC_16_ISO_IEC_14443_3_A = 63,
+  CRC_16_KERMIT = 64,
+  CRC_16_LJ1200 = 65,
+  CRC_16_M17 = 66,
+  CRC_16_MAXIM_DOW = 67,
+  CRC_16_MCRF4XX = 68,
+  CRC_16_MODBUS = 69,
+  CRC_16_NRSC_5 = 70,
+  CRC_16_OPENSAFETY_A = 71,
+  CRC_16_OPENSAFETY_B = 72,
+  CRC_16_PROFIBUS = 73,
+  CRC_16_RIELLO = 74,
+  CRC_16_SPI_FUJITSU = 75,
+  CRC_16_T10_DIF = 76,
+  CRC_16_TELEDISK = 77,
+  CRC_16_TMS37157 = 78,
+  CRC_16_UMTS = 79,
+  CRC_16_USB = 80,
+  CRC_16_XMODEM = 81,
+  CRC_17_CAN_FD = 82,
+  CRC_21_CAN_FD = 83,
+  CRC_24_BLE = 84,
+  CRC_24_FLEXRAY_A = 85,
+  CRC_24_FLEXRAY_B = 86,
+  CRC_24_INTERLAKEN = 87,
+  CRC_24_LTE_A = 88,
+  CRC_24_LTE_B = 89,
+  CRC_24_OPENPGP = 90,
+  CRC_24_OS_9 = 91,
+  CRC_30_CDMA = 92,
+  CRC_31_PHILIPS = 93,
+  CRC_32_AIXM = 94,
+  CRC_32_AUTOSAR = 95,
+  CRC_32_BASE91_D = 96,
+  CRC_32_BZIP2 = 97,
+  CRC_32_CD_ROM_EDC = 98,
+  CRC_32_CKSUM = 99,
+  CRC_32_ISCSI = 100,
+  CRC_32_ISO_HDLC = 101,
+  CRC_32_JAMCRC = 102,
+  CRC_32_MEF = 103,
+  CRC_32_MPEG_2 = 104,
+  CRC_32_XFER = 105,
+  CRC_40_GSM = 106,
+  CRC_64_ECMA_182 = 107,
+  CRC_64_GO_ISO = 108,
+  CRC_64_MS = 109,
+  CRC_64_NVME = 110,
+  CRC_64_REDIS = 111,
+  CRC_64_WE = 112,
+  CRC_64_XZ = 113,
+  CRC_82_DARC = 114
+}
+/**
+ * Frozen-bits construction method exposed to JavaScript.
+ */
+declare enum FrozenBits {
+  /**
+   * 5G NR frozen-bits pattern (default for N <= 1024).
+   */
+  _5G = 0,
+  /**
+   * Gaussian Approximation -- sigma can be tuned.
+   */
+  GA = 1,
+  /**
+   * Reed-Muller based construction (default for N > 1024).
+   */
+  RM = 2
+}
+interface InitOutput {
+  readonly memory: WebAssembly.Memory;
+  readonly __wbg_algorithm_free: (a: number, b: number) => void;
+  readonly __wbg_get_algorithm_init: (a: number) => [bigint, bigint];
+  readonly __wbg_get_algorithm_poly: (a: number) => [bigint, bigint];
+  readonly __wbg_get_algorithm_refin: (a: number) => number;
+  readonly __wbg_get_algorithm_refout: (a: number) => number;
+  readonly __wbg_get_algorithm_width: (a: number) => number;
+  readonly __wbg_get_algorithm_xorout: (a: number) => [bigint, bigint];
+  readonly __wbg_set_algorithm_init: (a: number, b: bigint, c: bigint) => void;
+  readonly __wbg_set_algorithm_poly: (a: number, b: bigint, c: bigint) => void;
+  readonly __wbg_set_algorithm_refin: (a: number, b: number) => void;
+  readonly __wbg_set_algorithm_refout: (a: number, b: number) => void;
+  readonly __wbg_set_algorithm_width: (a: number, b: number) => void;
+  readonly __wbg_set_algorithm_xorout: (a: number, b: bigint, c: bigint) => void;
+  readonly algorithm_new: (a: number, b: bigint, c: bigint, d: bigint, e: bigint, f: number, g: number, h: bigint, i: bigint) => number;
+  readonly __wbg_codec_free: (a: number, b: number) => void;
+  readonly codec_decode: (a: number, b: number, c: number) => [number, number];
+  readonly codec_decode_bit: (a: number, b: number, c: number) => [number, number];
+  readonly codec_encode: (a: number, b: number, c: number) => [number, number];
+  readonly codec_encode_bit: (a: number, b: number, c: number) => [number, number];
+  readonly codec_new: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => number;
+  readonly __wbindgen_externrefs: WebAssembly.Table;
+  readonly __wbindgen_malloc: (a: number, b: number) => number;
+  readonly __wbindgen_free: (a: number, b: number, c: number) => void;
+  readonly __wbindgen_start: () => void;
+}
+//#endregion
+//#region lib/index.d.ts
+/**
+ * Synchronously initialize the WebAssembly environment.
+ *
+ * This function is idempotent -- it is safe to call multiple times; subsequent
+ * calls will return the cached module immediately.
+ *
+ * @returns The initialized Wasm module ready for use.
+ *
+ * @example
+ * ```ts
+ * import { initWasmSync } from 'polar_codec_wasm';
+ * initWasmSync();
+ * // Now PolarCodec can be instantiated.
+ * ```
+ */
+declare function initWasmSync(): InitOutput;
+/**
+ * Description of a user-defined CRC algorithm.
+ *
+ * Fields follow the [Catalogue of parametrised CRC algorithms](https://reveng.sourceforge.io/crc-catalogue/all.htm).
+ */
+interface DefinedCrc {
+  /** Optional human-readable name (e.g. `"CRC-16/USB"`). */
+  name?: string;
+  /** Polynomial degree in bits (e.g. 16 for CRC-16). */
+  width: number;
+  /** Generator polynomial (without the leading x^width term). */
+  poly: number | bigint;
+  /** Initial value of the CRC register. */
+  init: number | bigint;
+  /** Reflect input bytes before processing?  Defaults to `refout` if omitted. */
+  refin?: boolean;
+  /** Reflect the register before final XOR?  Defaults to `refin` if omitted. */
+  refout?: boolean;
+  /** XOR mask applied after processing all bytes. */
+  xorout?: number | bigint;
+}
+/**
+ * Frozen-bits selection method.
+ *
+ * | Value | Description |
+ * |-------|-------------|
+ * | `"5G"` | 5G NR (default for N <= 1024) |
+ * | `"RM"` | Reed-Muller (default for N > 1024) |
+ * | `"GA"` | Gaussian Approximation with configurable sigma |
+ */
+type FrozenBitsMethod = "5G" | "RM" | {
+  type: "5G" | "RM";
+} | {
+  type: "GA";
+  sigma?: number;
+};
+/**
+ * Configuration options accepted by {@link PolarCodec}.
+ */
+interface PolarCodecOptions {
+  /** Frozen-bits construction method. */
+  frozenBits?: FrozenBitsMethod;
+  /** CRC scheme -- pass `null` / `undefined` for no CRC, a `Crc` enum value, or a {@link DefinedCrc} object. */
+  crc?: Crc | DefinedCrc | null;
+}
+declare function bits_to_llr(bits: Uint8Array): Float32Array;
+/**
+ * High-level wrapper around the Rust-backed {@link Codec}.
+ *
+ * `PolarCodec` manages Wasm initialization and provides a convenient
+ * constructor that translates human-readable option names into the
+ * low-level enum values expected by the Wasm layer.
+ *
+ * @typeParam K - Number of information bits (set at construction time).
+ * @typeParam N - Codeword length (must be a power of two, >= K).
+ *
+ * @example
+ * ```ts
+ * // 5G-style frozen bits, no CRC, list-size L=4 (default)
+ * const codec = new PolarCodec(96, 128);
+ *
+ * // With CRC-16 and GA frozen bits
+ * const codec2 = new PolarCodec(96, 128, 4, {
+ *   frozenBits: { type: "GA", sigma: 0.5 },
+ *   crc: Crc.CRC_16_UMTS,
+ * });
+ * ```
+ */
+declare class PolarCodec extends Codec {
+  /** Number of information bits per codeword. */
+  readonly K: number;
+  /** Total codeword length (information + frozen bits). */
+  readonly N: number;
+  /** SCL list size used during decoding. */
+  readonly L: number;
+  /** Frozen-bits construction method name. */
+  readonly METHOD: "5G" | "RM" | "GA";
+  /** Resolved CRC parameters, or `undefined` when no CRC is used. */
+  readonly CRC: Required<DefinedCrc> | undefined;
+  /**
+   * Create a new Polar Codec instance.
+   *
+   * @param k  Number of information bits (must be <= n).
+   * @param n  Codeword length, must be a power of two.
+   * @param l  SCL list size (default `4`).  Larger values improve error
+   *           correction at the cost of higher latency and memory.
+   * @param options  Optional CRC and frozen-bits configuration.
+   */
+  constructor(k: number, n?: number, l?: number, options?: Partial<PolarCodecOptions>);
+  static bits_to_llr(bits: Uint8Array): Float32Array;
+}
+//#endregion
+export { Crc, DefinedCrc, FrozenBitsMethod, PolarCodec, PolarCodecOptions, bits_to_llr, initWasmSync };