numkong 7.0.0

package/javascript/README.md

@@ -0,0 +1,246 @@
+# NumKong for JavaScript
+
+NumKong's JavaScript package brings low-latency vector kernels to Node and Bun-style runtimes, targeting the space between handwritten loops over `TypedArray`s and much heavier tensor frameworks.
+It keeps the JS surface intentionally compact: dense distances, dot products, binary metrics, probability divergences, packed GEMM-like matrix multiplication, symmetric Gram matrices, dtype-tagged low-precision storage, typed views, and runtime capability inspection.
+
+## Quickstart
+
+```ts
+import { dot } from "numkong";
+
+const a = new Float32Array([1, 2, 3]);
+const b = new Float32Array([4, 5, 6]);
+console.log(dot(a, b)); // 32
+```
+
+## Highlights
+
+This SDK is deliberately smaller than Python or Rust.
+Its job is to make the hot vector kernels easy to use from modern JavaScript runtimes.
+
+__TypedArray-first API.__
+Standard `Float32Array`, `Float64Array`, `Int8Array`, and `Uint8Array` work directly.
+__DType tags for exotic storage.__
+`f16`, `bf16`, fp8, and packed bits stay explicit.
+__Owned and borrowed views.__
+`Vector`, `VectorView`, and base tensor wrappers preserve dtype metadata.
+__Portable runtime story.__
+The same package can target native addons and WASM runtimes.
+__No fake tensor-framework scope.__
+This binding stays centered on the vector families it actually exports.
+
+## Ecosystem Comparison
+
+| Feature                      | NumKong                                                        | [mathjs](https://github.com/josdejong/mathjs) | [tensorflow.js](https://github.com/tensorflow/tfjs) |
+| ---------------------------- | -------------------------------------------------------------- | --------------------------------------------- | --------------------------------------------------- |
+| Operation families           | dots, distances, binary, probability, cast, packed, symmetric  | general arithmetic, matrix ops, statistics    | matmul, elementwise, reductions                     |
+| Precision                    | BFloat16 through sub-byte; automatic widening; Kahan summation | Float64 only; standard accuracy               | Float32 primarily; no sub-byte; standard accuracy   |
+| Runtime SIMD dispatch        | auto-selects best ISA per-thread across x86, ARM, RISC-V       | none; pure JS                                 | fixed at build time via WASM SIMD or WebGL          |
+| Packed matrix, GEMM-like     | `dotsPack` + `dotsPacked`; persistent packing; amortized       | `math.multiply` — no persistent packing       | `tf.matMul` — no persistent packing                 |
+| Symmetric kernels, SYRK-like | `dotsSymmetric`; upper triangle only; row-range partitioning   | no duplicate-pair skipping                    | no duplicate-pair skipping                          |
+| WASM fallback                | yes — portable, runs in browser without native addon           | yes — pure JS, no native required             | yes — also WebGL/WebGPU                             |
+| Bundle size                  | small                                                          | moderate                                      | large                                               |
+
+## Installation
+
+The package targets Node `>= 22`.
+
+```sh
+npm install numkong
+yarn add numkong
+pnpm add numkong
+bun add numkong
+```
+
+If you build from source, the package uses `node-gyp-build` on install and TypeScript sources under `javascript/`.
+
+## Browser and WASM
+
+NumKong ships pre-built WASM binaries attached to each [GitHub Release](https://github.com/ashvardanian/NumKong/releases).
+Download `numkong.js` and `numkong.wasm` and serve them from the same directory.
+
+```html
+<script type="module">
+  import * as numkong from "./numkong-wasm.js";
+  import NumKongModule from "./numkong.js";
+
+  const wasm = await NumKongModule();
+  numkong.initWasm(wasm);
+
+  // Same API as the native addon
+  const a = new Float32Array([1, 2, 3]);
+  const b = new Float32Array([4, 5, 6]);
+  console.log(numkong.dot(a, b));
+</script>
+```
+
+For Node.js WASM usage without the native addon:
+
+```js
+import * as numkong from "numkong/wasm";
+import NumKongModule from "./numkong.js";
+
+const wasm = await NumKongModule();
+numkong.initWasm(wasm);
+```
+
+## Dot Products
+
+Dot products are separate from distances because dtype tagging and low-precision storage matter more here.
+
+```ts
+import { dot, inner } from "numkong";
+
+const a = new Float32Array([1, 2, 3]);
+const b = new Float32Array([4, 5, 6]);
+
+console.log(dot(a, b));
+console.log(inner(a, b)); // alias for ecosystem familiarity
+```
+
+For non-native numeric layouts, pass an explicit `DType` or wrap the storage in a typed NumKong view.
+
+## Dense Distances
+
+Dense distance entrypoints work directly on the standard numeric `TypedArray` types.
+
+```ts
+import { sqeuclidean, euclidean, angular } from "numkong";
+
+const a = new Float32Array([1, 2, 3]);
+const b = new Float32Array([4, 5, 6]);
+
+console.log(sqeuclidean(a, b)); // equivalent shape to a manual sum((a[i] - b[i]) ** 2)
+console.log(euclidean(a, b));
+console.log(angular(a, b));
+```
+
+When the storage type is one of the standard JS typed arrays, dtype inference is automatic.
+
+## Binary Metrics
+
+Binary metrics operate on packed storage rather than on generic boolean arrays.
+
+```ts
+import { toBinary, hamming, jaccard } from "numkong";
+
+const a = toBinary(new Float32Array([1, -2, 3, -4, 5, -6, 7, -8]));
+const b = toBinary(new Float32Array([1, 2, -3, -4, 5, 6, -7, -8]));
+
+console.log(hamming(a, b));
+console.log(jaccard(a, b));
+```
+
+That is a better model for sign-quantized embeddings and semantic hashes than looping over JS booleans.
+
+## Probability Metrics
+
+```ts
+import { kullbackleibler, jensenshannon } from "numkong";
+
+const p = new Float32Array([0.2, 0.3, 0.5]);
+const q = new Float32Array([0.1, 0.3, 0.6]);
+
+console.log(kullbackleibler(p, q));
+console.log(jensenshannon(p, q));
+```
+
+These are direct divergence kernels, not scalar JS loops hidden behind a helper.
+
+## DType Tags and Low-Precision Arrays
+
+JavaScript has no built-in `f16`, `bf16`, fp8, or packed-bit numeric model.
+NumKong handles that with explicit dtype tags and wrapper arrays.
+
+The supported low-precision types and their bit layouts are:
+
+- `Float16Array`: 1 sign + 5 exponent + 10 mantissa bits, 2 bytes per element, range ±65504, supports Inf and NaN
+- `BFloat16Array`: 1 sign + 8 exponent + 7 mantissa bits, 2 bytes per element, full `f32` dynamic range, supports Inf and NaN
+- `E4M3Array`: 1 sign + 4 exponent + 3 mantissa bits, 1 byte per element, range ±448, no Inf, NaN is 0x7F only
+- `E5M2Array`: 1 sign + 5 exponent + 2 mantissa bits, 1 byte per element, range ±57344, supports Inf and NaN
+- `BinaryArray`: packed bits in bytes, 8 elements per byte
+
+Use `.byteLength` for the exact payload size.
+
+```ts
+import { Float16Array, E4M3Array, DType, dot, angular } from "numkong";
+
+const a16 = new Float16Array([1, 2, 3]);
+const b16 = new Float16Array([4, 5, 6]);
+console.log(dot(a16, b16, DType.F16));
+console.log(a16.byteLength);
+
+const a8 = new E4M3Array([1, 2, 3]);
+const b8 = new E4M3Array([4, 5, 6]);
+console.log(angular(a8, b8, DType.E4M3));
+console.log(a8.byteLength);
+```
+
+If the underlying storage is a raw `Uint16Array` or `Uint8Array`, JS itself cannot know whether those bytes mean integers, `f16`, `bf16`, mini-floats, or packed bits.
+That is exactly when the `DType` tag becomes mandatory.
+You can also pass it to `cast` to convert many values between all supported types:
+
+```ts
+numkong.cast(f32Source, "f32", bf16Dest, "bf16");
+numkong.cast(f32Source, "f32", bf16Dest, DType.E4M3);
+```
+
+## Vector Views and Owned Buffers
+
+The wrapper hierarchy exists to keep dtype and ownership explicit across addon and WASM boundaries.
+
+- `TensorBase` carries `buffer`, `byteOffset`, and `dtype`
+- `VectorBase` adds rank-1 semantics
+- `VectorView` is a zero-copy borrowed wrapper over existing memory
+- `Vector` owns its `ArrayBuffer`
+
+```ts
+import { VectorView, Vector, DType, dot } from "numkong";
+
+const raw = new Uint16Array([0x3c00, 0x4000, 0x4200]); // f16 payload, not uint16 values
+const view = VectorView.from(raw, DType.F16);
+
+const owned = new Vector(3, DType.F32);
+owned.toTypedArray().set(new Float32Array([4, 5, 6]));
+
+console.log(dot(view, view));
+console.log(dot(owned, owned));
+console.log(owned.byteLength);
+```
+
+Use `VectorView` when the bytes already live somewhere else.
+Use `Vector` when NumKong should own the storage.
+
+## Capabilities and Runtime Selection
+
+Capability detection is explicit:
+
+```ts
+import { Capability, getCapabilities, hasCapability } from "numkong";
+
+const caps = getCapabilities();
+
+console.log(caps);
+console.log(hasCapability(Capability.HASWELL));
+console.log(hasCapability(Capability.NEON));
+```
+
+The exact bitmask depends on whether you are running the native addon or a WASM runtime.
+
+There is no `configure_thread` call in the JS binding.
+Thread configuration is managed internally by the native addon or WASM runtime.
+
+## Native Addon and WASM Runtimes
+
+The top-level package is native-first.
+It loads the compiled addon through `node-gyp-build`.
+
+The repository also ships WASM wrappers.
+Those are useful for portable or sandboxed environments.
+They should not be described as feature-complete replacements for the native-heavy SDKs.
+
+Practical guidance:
+
+- Use the native addon for the lowest host-call latency.
+- Use the WASM path when portability matters more than absolute latency.
+- Keep your expectations scoped to the vector and matrix-oriented API that this binding actually exports.

package/javascript/dist/cjs/numkong-wasm.d.ts

@@ -0,0 +1,166 @@
+/**
+ * @brief WASM wrapper for NumKong providing N-API compatible interface
+ * @file javascript/numkong-wasm.ts
+ * @date February 6, 2026
+ *
+ * This module wraps the Emscripten-compiled WASM module to provide the same
+ * TypeScript API as the native N-API bindings. It handles:
+ * - Zero-copy TensorBase interop for cross-module WASM sharing
+ * - TypedArray type detection and dispatch
+ * - Result extraction from WASM heap
+ * - Error handling
+ * - Both wasm32 and wasm64 (memory64) modes
+ */
+import { TensorBase, Matrix, PackedMatrix, DType } from './types.js';
+/**
+ * Emscripten module interface.
+ * In wasm64 (memory64) mode, pointer/size params and returns become bigint.
+ * We use `any` for pointer arguments to support both modes uniformly.
+ */
+interface EmscriptenModule {
+    _malloc(size: any): any;
+    _free(ptr: any): void;
+    wasmMemory: {
+        buffer: ArrayBuffer;
+    };
+    _nk_dot_f32(a: any, b: any, n: any, result: any): void;
+    _nk_angular_f32(a: any, b: any, n: any, result: any): void;
+    _nk_sqeuclidean_f32(a: any, b: any, n: any, result: any): void;
+    _nk_euclidean_f32(a: any, b: any, n: any, result: any): void;
+    _nk_dot_f64(a: any, b: any, n: any, result: any): void;
+    _nk_angular_f64(a: any, b: any, n: any, result: any): void;
+    _nk_sqeuclidean_f64(a: any, b: any, n: any, result: any): void;
+    _nk_euclidean_f64(a: any, b: any, n: any, result: any): void;
+    _nk_dot_f16(a: any, b: any, n: any, result: any): void;
+    _nk_angular_f16(a: any, b: any, n: any, result: any): void;
+    _nk_sqeuclidean_f16(a: any, b: any, n: any, result: any): void;
+    _nk_euclidean_f16(a: any, b: any, n: any, result: any): void;
+    _nk_dot_bf16(a: any, b: any, n: any, result: any): void;
+    _nk_angular_bf16(a: any, b: any, n: any, result: any): void;
+    _nk_sqeuclidean_bf16(a: any, b: any, n: any, result: any): void;
+    _nk_euclidean_bf16(a: any, b: any, n: any, result: any): void;
+    _nk_dot_i8(a: any, b: any, n: any, result: any): void;
+    _nk_angular_i8(a: any, b: any, n: any, result: any): void;
+    _nk_sqeuclidean_i8(a: any, b: any, n: any, result: any): void;
+    _nk_euclidean_i8(a: any, b: any, n: any, result: any): void;
+    _nk_dot_u8(a: any, b: any, n: any, result: any): void;
+    _nk_angular_u8(a: any, b: any, n: any, result: any): void;
+    _nk_sqeuclidean_u8(a: any, b: any, n: any, result: any): void;
+    _nk_euclidean_u8(a: any, b: any, n: any, result: any): void;
+    _nk_hamming_u1(a: any, b: any, n: any, result: any): void;
+    _nk_hamming_u8(a: any, b: any, n: any, result: any): void;
+    _nk_jaccard_u1(a: any, b: any, n: any, result: any): void;
+    _nk_jaccard_u16(a: any, b: any, n: any, result: any): void;
+    _nk_kld_f32(a: any, b: any, n: any, result: any): void;
+    _nk_kld_f64(a: any, b: any, n: any, result: any): void;
+    _nk_jsd_f32(a: any, b: any, n: any, result: any): void;
+    _nk_jsd_f64(a: any, b: any, n: any, result: any): void;
+    _nk_capabilities(): any;
+    [key: string]: any;
+}
+/**
+ * Initializes the WASM backend with an Emscripten module instance.
+ * @param wasmModule - The Emscripten-compiled WASM module to use.
+ */
+export declare function initWasm(wasmModule: EmscriptenModule): void;
+/**
+ * Computes the squared Euclidean distance between two vectors.
+ * @param a - First vector (TypedArray or TensorBase).
+ * @param b - Second vector (must match type and length of a).
+ * @returns The squared Euclidean distance between a and b.
+ */
+export declare function sqeuclidean(a: TensorBase | any, b: TensorBase | any): number;
+/**
+ * Computes the Euclidean distance between two vectors.
+ * @param a - First vector (TypedArray or TensorBase).
+ * @param b - Second vector (must match type and length of a).
+ * @returns The Euclidean distance between a and b.
+ */
+export declare function euclidean(a: TensorBase | any, b: TensorBase | any): number;
+/**
+ * Computes the angular distance between two vectors.
+ * @param a - First vector (TypedArray or TensorBase).
+ * @param b - Second vector (must match type and length of a).
+ * @returns The angular distance between a and b.
+ */
+export declare function angular(a: TensorBase | any, b: TensorBase | any): number;
+/**
+ * Computes the dot product of two vectors.
+ * @param a - First vector (TypedArray or TensorBase).
+ * @param b - Second vector (must match type and length of a).
+ * @returns The dot product of a and b.
+ */
+export declare function dot(a: TensorBase | any, b: TensorBase | any): number;
+/** Alias for {@link dot}. */
+export declare const inner: typeof dot;
+/**
+ * Computes the bitwise Hamming distance between two vectors.
+ *
+ * Following N-API behavior, always treats input as u1 (binary/bit-packed),
+ * even if passed as Uint8Array. Each byte represents 8 bits.
+ *
+ * @param a - First bit-packed vector (Uint8Array or TensorBase).
+ * @param b - Second bit-packed vector (must match length of a).
+ * @returns The Hamming distance (number of differing bits) between a and b.
+ */
+export declare function hamming(a: TensorBase | Uint8Array | any, b: TensorBase | Uint8Array | any): number;
+/**
+ * Computes the bitwise Jaccard distance between two vectors.
+ *
+ * Following N-API behavior, always treats input as u1 (binary/bit-packed),
+ * even if passed as Uint8Array. Each byte represents 8 bits.
+ *
+ * @param a - First bit-packed vector (Uint8Array or TensorBase).
+ * @param b - Second bit-packed vector (must match length of a).
+ * @returns The Jaccard distance (1 - Jaccard similarity) between a and b.
+ */
+export declare function jaccard(a: TensorBase | Uint8Array | any, b: TensorBase | Uint8Array | any): number;
+/**
+ * Computes the Kullback-Leibler divergence between two probability distributions.
+ * @param a - First probability distribution (Float32Array, Float64Array, or TensorBase).
+ * @param b - Second probability distribution (must match type and length of a).
+ * @returns The KL divergence KL(a || b).
+ */
+export declare function kullbackleibler(a: TensorBase | Float64Array | Float32Array, b: TensorBase | Float64Array | Float32Array): number;
+/**
+ * Computes the Jensen-Shannon distance between two probability distributions.
+ * @param a - First probability distribution (Float32Array, Float64Array, or TensorBase).
+ * @param b - Second probability distribution (must match type and length of a).
+ * @returns The Jensen-Shannon distance between a and b.
+ */
+export declare function jensenshannon(a: TensorBase | Float64Array | Float32Array, b: TensorBase | Float64Array | Float32Array): number;
+/**
+ * Returns the runtime-detected SIMD capabilities as a bitmask.
+ * @returns Bitmask of capability flags (use with Capability constants).
+ */
+export declare function getCapabilities(): bigint;
+/**
+ * Checks if a specific SIMD capability is available at runtime.
+ * @param cap - Capability flag to check (from Capability constants).
+ * @returns True if the capability is available.
+ */
+export declare function hasCapability(cap: bigint): boolean;
+/**
+ * Query the packed buffer byte count for a given matrix shape and dtype.
+ */
+export declare function dotsPackedSize(width: number, depth: number, dtype: DType): number;
+/**
+ * Pack a Matrix for use with packed GEMM-like operations.
+ */
+export declare function dotsPack(matrix: Matrix): PackedMatrix;
+export declare function dotsPacked(a: Matrix, packed: PackedMatrix, out?: Matrix): Matrix;
+export declare function angularsPacked(a: Matrix, packed: PackedMatrix, out?: Matrix): Matrix;
+export declare function euclideansPacked(a: Matrix, packed: PackedMatrix, out?: Matrix): Matrix;
+export declare function dotsSymmetric(vectors: Matrix, out?: Matrix, options?: {
+    rowStart?: number;
+    rowCount?: number;
+}): Matrix;
+export declare function angularsSymmetric(vectors: Matrix, out?: Matrix, options?: {
+    rowStart?: number;
+    rowCount?: number;
+}): Matrix;
+export declare function euclideansSymmetric(vectors: Matrix, out?: Matrix, options?: {
+    rowStart?: number;
+    rowCount?: number;
+}): Matrix;
+export {};