numkong 7.0.0

package/javascript/dist/esm/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 {};