numkong 7.0.0

package/javascript/dist/cjs/types.d.ts

@@ -0,0 +1,284 @@
+/**
+ * @brief Custom TypedArray classes for non-native numeric types.
+ * @file javascript/types.ts
+ * @author Ash Vardanian
+ * @date February 3, 2026
+ *
+ * This file provides TypedArray wrappers for numeric types not natively supported
+ * by JavaScript, using NumKong's SIMD-optimized conversion functions from the C library.
+ */
+declare let conversionFunctions: {
+    castF16ToF32: (bits: number) => number;
+    castF32ToF16: (value: number) => number;
+    castBF16ToF32: (bits: number) => number;
+    castF32ToBF16: (value: number) => number;
+    castE4M3ToF32: (bits: number) => number;
+    castF32ToE4M3: (value: number) => number;
+    castE5M2ToF32: (bits: number) => number;
+    castF32ToE5M2: (value: number) => number;
+    cast: (src: TypedArray, srcType: string, dst: TypedArray, dstType: string) => void;
+};
+export declare function setConversionFunctions(fns: typeof conversionFunctions): void;
+export type TypedArray = Float64Array | Float32Array | Int32Array | Int8Array | Uint8Array | Uint16Array | Uint32Array;
+/** @brief Numeric data type enum — integer switch, compiles to jump table. */
+export declare enum DType {
+    F64 = 0,
+    F32 = 1,
+    F16 = 2,
+    BF16 = 3,
+    E4M3 = 4,
+    E5M2 = 5,
+    E2M3 = 6,
+    E3M2 = 7,
+    I8 = 8,
+    U8 = 9,
+    U1 = 10,
+    I32 = 11,
+    U32 = 12
+}
+/** @brief O(1) array lookup for DType → string conversion (needed at N-API/WASM boundaries). */
+export declare const DTYPE_STRINGS: readonly string[];
+/** @brief Convert a DType enum value to its string representation. */
+export declare function dtypeToString(d: DType): string;
+/**
+ * @brief Abstract base class for all tensor types.
+ *
+ * All fields are embedded — zero dynamic allocation. DType is a numeric enum
+ * (integer switch). Mirrors the C++ pattern: buffer + byteOffset + dtype.
+ */
+export declare abstract class TensorBase {
+    readonly buffer: ArrayBuffer;
+    readonly byteOffset: number;
+    readonly dtype: DType;
+    protected constructor(buffer: ArrayBuffer, byteOffset: number, dtype: DType);
+    abstract get length(): number;
+    abstract get rank(): number;
+    /** @brief Bytes per element for this tensor's dtype (compiles to jump table). */
+    get bytesPerElement(): number;
+    /** @brief Total byte length of the tensor data. */
+    get byteLength(): number;
+}
+/**
+ * @brief Abstract rank-1 tensor base class.
+ */
+export declare abstract class VectorBase extends TensorBase {
+    readonly length: number;
+    protected constructor(buffer: ArrayBuffer, byteOffset: number, length: number, dtype: DType);
+    get rank(): 1;
+}
+/**
+ * @brief Non-owning rank-1 tensor view (like std::span<T>).
+ *
+ * Zero-copy wrapper for existing memory. Ideal for cross-module WASM interop
+ * where data already lives on the WASM heap.
+ */
+export declare class VectorView extends VectorBase {
+    constructor(buffer: ArrayBuffer, byteOffset: number, length: number, dtype: DType);
+    /** @brief Create a VectorView from any TypedArray, inferring or accepting dtype. */
+    static from(arr: TypedArray, dtype?: DType): VectorView;
+}
+/**
+ * @brief Owning rank-1 tensor (like std::vector<T>).
+ *
+ * Allocates its own ArrayBuffer. Use for storing results or when you need
+ * independent ownership of the data.
+ */
+export declare class Vector extends VectorBase {
+    constructor(length: number, dtype: DType);
+    constructor(buffer: ArrayBuffer, length: number, dtype: DType);
+    /** @brief Create an owning Vector by copying data from a TypedArray. */
+    static fromTypedArray(arr: TypedArray, dtype?: DType): Vector;
+    /** @brief Create an owning Vector by copying data from any TensorBase. */
+    static fromView(view: TensorBase): Vector;
+    /** @brief Return a TypedArray view over this Vector's owned buffer (zero-copy). */
+    toTypedArray(): TypedArray;
+}
+/**
+ * @brief Abstract rank-2 tensor base class.
+ *
+ * All 4 dimension fields are embedded — no dynamic allocation.
+ * Strides are in bytes to match the C API directly.
+ */
+export declare abstract class MatrixBase extends TensorBase {
+    readonly rows: number;
+    readonly cols: number;
+    readonly rowStride: number;
+    readonly colStride: number;
+    protected constructor(buffer: ArrayBuffer, byteOffset: number, dtype: DType, rows: number, cols: number, rowStride: number, colStride: number);
+    get length(): number;
+    get rank(): 2;
+}
+/**
+ * @brief Owning rank-2 tensor (row-major, C-contiguous by default).
+ *
+ * Strides are byte strides. Default for C-contiguous layout:
+ * rowStride = cols * bytesPerElement, colStride = bytesPerElement.
+ */
+export declare class Matrix extends MatrixBase {
+    constructor(rows: number, cols: number, dtype: DType);
+    constructor(buffer: ArrayBuffer, byteOffset: number, dtype: DType, rows: number, cols: number, rowStride?: number, colStride?: number);
+    static fromTypedArray(array: TypedArray, rows: number, cols: number, dtype?: DType): Matrix;
+    toTypedArray(): TypedArray;
+    row(index: number): VectorView;
+}
+/**
+ * @brief Opaque packed matrix container.
+ *
+ * Packed layout is not indexable — this is a data container for packed GEMM kernels.
+ * N-API path: buffer is a V8-managed ArrayBuffer, auto-freed by GC.
+ * WASM path: stores a heap pointer, dispose() calls Module._free().
+ */
+export declare class PackedMatrix {
+    readonly width: number;
+    readonly depth: number;
+    readonly dtype: DType;
+    readonly byteLength: number;
+    readonly buffer: ArrayBuffer;
+    private _disposed;
+    constructor(buffer: ArrayBuffer, width: number, depth: number, dtype: DType, byteLength: number);
+    dispose(): void;
+    get disposed(): boolean;
+}
+/** @brief Kernel family identifiers for output dtype resolution. */
+export type KernelFamily = 'dots' | 'angulars' | 'euclideans';
+/**
+ * @brief Determines the output dtype for a given kernel family and input dtype.
+ * Mirrors nk_kernel_output_dtype from C.
+ */
+export declare function outputDtype(family: KernelFamily, input: DType): DType;
+/**
+ * @brief IEEE 754 Half Precision Float (f16)
+ *
+ * 16-bit floating point: 1 sign bit, 5 exponent bits, 10 mantissa bits
+ * Range: ~±65504, precision: ~3-4 decimal digits
+ *
+ * Common in GPU inference, model compression, and mixed-precision training.
+ * Supported natively on Apple Silicon, NVIDIA GPUs (fp16), AMD GPUs.
+ */
+export declare class Float16Array extends Uint16Array {
+    constructor(length: number | ArrayLike<number> | ArrayBufferLike, byteOffset?: number, arrayLength?: number);
+    /**
+     * @brief Converts the entire f16 array to f32 (Float32Array).
+     * @returns Float32Array with decoded values
+     */
+    toFloat32Array(): Float32Array;
+    /**
+     * @brief Gets the f32 value at the specified index.
+     * @param index Array index
+     * @returns Decoded f32 value
+     */
+    getFloat32(index: number): number;
+    /**
+     * @brief Sets the value at the specified index from an f32 value.
+     * @param index Array index
+     * @param value f32 value to encode and store
+     */
+    setFloat32(index: number, value: number): void;
+}
+/**
+ * @brief Brain Float 16 (bf16)
+ *
+ * 16-bit floating point: 1 sign bit, 8 exponent bits, 7 mantissa bits
+ * Range: same as f32 (~±3.4e38), precision: ~2-3 decimal digits
+ *
+ * Designed by Google for TPUs, optimized for ML training (wider range than f16).
+ * Supported on Google TPUs, Intel Sapphire Rapids, AMD Genoa, ARM Neoverse V2.
+ * Truncated f32 (top 16 bits), making conversion very cheap.
+ */
+export declare class BFloat16Array extends Uint16Array {
+    constructor(length: number | ArrayLike<number> | ArrayBufferLike, byteOffset?: number, arrayLength?: number);
+    toFloat32Array(): Float32Array;
+    getFloat32(index: number): number;
+    setFloat32(index: number, value: number): void;
+}
+/**
+ * @brief FP8 E4M3 (4-bit exponent, 3-bit mantissa)
+ *
+ * 8-bit floating point: 1 sign bit, 4 exponent bits, 3 mantissa bits
+ * Range: ~±448, precision: ~1 decimal digit
+ *
+ * Optimized for forward pass inference with higher precision than E5M2.
+ * Supported on NVIDIA Hopper H100 GPUs, AMD Instinct MI300.
+ */
+export declare class E4M3Array extends Uint8Array {
+    constructor(length: number | ArrayLike<number> | ArrayBufferLike, byteOffset?: number, arrayLength?: number);
+    toFloat32Array(): Float32Array;
+    getFloat32(index: number): number;
+    setFloat32(index: number, value: number): void;
+}
+/**
+ * @brief FP8 E5M2 (5-bit exponent, 2-bit mantissa)
+ *
+ * 8-bit floating point: 1 sign bit, 5 exponent bits, 2 mantissa bits
+ * Range: ~±57344, precision: <1 decimal digit
+ *
+ * Optimized for backward pass training with wider range than E4M3.
+ * Supported on NVIDIA Hopper H100 GPUs, AMD Instinct MI300.
+ */
+export declare class E5M2Array extends Uint8Array {
+    constructor(length: number | ArrayLike<number> | ArrayBufferLike, byteOffset?: number, arrayLength?: number);
+    toFloat32Array(): Float32Array;
+    getFloat32(index: number): number;
+    setFloat32(index: number, value: number): void;
+}
+/**
+ * @brief Binary Array (u1) - Bit-packed binary vectors
+ *
+ * 1-bit per element, packed into bytes (8 bits per byte)
+ * Used for binary embeddings, hashing, and Hamming/Jaccard distances.
+ *
+ * Common in semantic search with binary quantization (Cohere, Voyage).
+ */
+export declare class BinaryArray extends Uint8Array {
+    private _bitLength;
+    constructor(bitLength: number);
+    /**
+     * @brief Gets the bit value at the specified index.
+     * @param index Bit index (0 to bitLength-1)
+     * @returns 0 or 1
+     */
+    getBit(index: number): number;
+    /**
+     * @brief Sets the bit value at the specified index.
+     * @param index Bit index (0 to bitLength-1)
+     * @param value 0 or 1
+     */
+    setBit(index: number, value: number): void;
+    /**
+     * @brief Returns the logical bit length of the array.
+     */
+    get bitLength(): number;
+    /**
+     * @brief Creates a BinaryArray from a Float32Array (positive values = 1, else 0).
+     * @param vector Source floating-point vector
+     * @returns Binary array with quantized values
+     */
+    static fromFloat32Array(vector: Float32Array): BinaryArray;
+    /**
+     * @brief Creates a BinaryArray from a Float64Array (positive values = 1, else 0).
+     * @param vector Source floating-point vector
+     * @returns Binary array with quantized values
+     */
+    static fromFloat64Array(vector: Float64Array): BinaryArray;
+}
+/**
+ * @brief Type guard to check if an object is a Float16Array.
+ */
+export declare function isFloat16Array(obj: any): obj is Float16Array;
+/**
+ * @brief Type guard to check if an object is a BFloat16Array.
+ */
+export declare function isBFloat16Array(obj: any): obj is BFloat16Array;
+/**
+ * @brief Type guard to check if an object is an E4M3Array.
+ */
+export declare function isE4M3Array(obj: any): obj is E4M3Array;
+/**
+ * @brief Type guard to check if an object is an E5M2Array.
+ */
+export declare function isE5M2Array(obj: any): obj is E5M2Array;
+/**
+ * @brief Type guard to check if an object is a BinaryArray.
+ */
+export declare function isBinaryArray(obj: any): obj is BinaryArray;
+export {};