# Scalar Types

> NumKong for JavaScript

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.
`cast` converts many values between all supported types, naming both sides by their dtype string:

```ts
numkong.cast(f32Source, "f32", bf16Dest, "bf16");
numkong.cast(f32Source, "f32", e4m3Dest, "e4m3");
```

`import * as numkong from 'numkong';`

`import { Float16Array } from 'numkong';`

`import { BFloat16Array } from 'numkong';`

`import { E4M3Array } from 'numkong';`

`import { E5M2Array } from 'numkong';`

`import { BinaryArray } from 'numkong';`

## NumericArray

Numeric arrays supported by distance metrics with auto-detected dtype.

```typescript
type NumericArray = Float64Array | Float32Array | Int8Array | Uint8Array
```

These standard TypedArrays are auto-detected by the N-API binding.

## DistanceArray

Extended array types supported by distance metrics with explicit dtype parameter.

```typescript
type DistanceArray = Float64Array | Float32Array | Int8Array | Uint8Array | Uint16Array
```

Includes Uint16Array, the backing type for Float16Array and BFloat16Array, in addition to the
auto-detected types. Pass a dtype string as the third argument to distance functions when using
custom types.

## NumKongArray

Union type for all array types, including custom types for conversions.

```typescript
type NumKongArray = | Float64Array | Float32Array | Float16Array | BFloat16Array | E4M3Array | E5M2Array | Int8Array | Uint8Array | BinaryArray
```

## DType

Numeric data type enum, an integer switch that compiles to a jump table.

```typescript
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`

## Float16Array

IEEE 754 half-precision float, f16.

```typescript
class Float16Array extends Uint16Array
```

- 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 as fp16, and AMD GPUs.

## Float16Array

```typescript
new Float16Array(
    length: number | ArrayLike<number> | ArrayBufferLike,
    byteOffset?: number,
    arrayLength?: number,
)
```

## toFloat32Array

Converts the entire f16 array to f32.

```typescript
toFloat32Array(): Float32Array
```

## getFloat32

Gets the f32 value at the specified index.

```typescript
getFloat32(index: number): number
```

- `index`: Array index

## setFloat32

Sets the value at the specified index from an f32 value.

```typescript
setFloat32(index: number, value: number): void
```

- `index`: Array index
- `value`: f32 value to encode and store

## to*

```typescript
toString(): string
```

## BFloat16Array

Brain float 16, bf16.

```typescript
class BFloat16Array extends Uint16Array
```

- 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 with a 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.

## BFloat16Array

```typescript
new BFloat16Array(
    length: number | ArrayLike<number> | ArrayBufferLike,
    byteOffset?: number,
    arrayLength?: number,
)
```

## toFloat32*

```typescript
toFloat32Array(): Float32Array
```

## *

```typescript
getFloat32(index: number): number
```

- `getFloat32`
- `setFloat32`
- `getFloat32`
- `setFloat32`
- `getFloat32`
- `setFloat32`

## E4M3Array

FP8 E4M3, 4-bit exponent and 3-bit mantissa.

```typescript
class E4M3Array extends Uint8Array
```

- 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.

## E4M3Array

```typescript
new E4M3Array(
    length: number | ArrayLike<number> | ArrayBufferLike,
    byteOffset?: number,
    arrayLength?: number,
)
```

## E5M2Array

FP8 E5M2, 5-bit exponent and 2-bit mantissa.

```typescript
class E5M2Array extends Uint8Array
```

- 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.

## E5M2Array

```typescript
new E5M2Array(
    length: number | ArrayLike<number> | ArrayBufferLike,
    byteOffset?: number,
    arrayLength?: number,
)
```

## BinaryArray

Bit-packed binary array, dtype u1.

```typescript
class BinaryArray extends Uint8Array
```

- 1-bit per element, packed into bytes: 8 bits per byte, most significant bit first.

- Dimension count must be a multiple of 8, the values per byte.

- Used for binary embeddings, hashing, and Hamming/Jaccard distances.

- Common in semantic search with binary quantization, as in Cohere and Voyage embeddings.

## BinaryArray

```typescript
new BinaryArray(bitLength: number)
```

## fromFloat32Array

Creates a BinaryArray from a Float32Array (positive values = 1, else 0).

```typescript
static fromFloat32Array(vector: Float32Array): BinaryArray
```

- `vector`: Source floating-point vector

## fromFloat64Array

Creates a BinaryArray from a Float64Array (positive values = 1, else 0).

```typescript
static fromFloat64Array(vector: Float64Array): BinaryArray
```

- `vector`: Source floating-point vector

## getBit

Gets the bit value at the specified index.

```typescript
getBit(index: number): number
```

- `index`: Bit index (0 to bitLength-1)

## setBit

Sets the bit value at the specified index.

```typescript
setBit(index: number, value: number): void
```

- `index`: Bit index (0 to bitLength-1)
- `value`: 0 or 1

## bitLength

Returns the logical bit length of the array.

```typescript
readonly bitLength: number
```

## castF16ToF32

Convert a single FP16 value, as uint16 bits, to FP32.

```typescript
const castF16ToF32: (bits: number) => number
```

## castF32ToF16

Convert a single FP32 value to FP16, returning uint16 bits.

```typescript
const castF32ToF16: (value: number) => number
```

## castBF16ToF32

Convert a single BF16 value, as uint16 bits, to FP32.

```typescript
const castBF16ToF32: (bits: number) => number
```

## castF32ToBF16

Convert a single FP32 value to BF16, returning uint16 bits.

```typescript
const castF32ToBF16: (value: number) => number
```

## castE4M3ToF32

Convert a single E4M3 value, as uint8 bits, to FP32.

```typescript
const castE4M3ToF32: (bits: number) => number
```

## castF32ToE4M3

Convert a single FP32 value to E4M3, returning uint8 bits.

```typescript
const castF32ToE4M3: (value: number) => number
```

## castE5M2ToF32

Convert a single E5M2 value, as uint8 bits, to FP32.

```typescript
const castE5M2ToF32: (bits: number) => number
```

## castF32ToE5M2

Convert a single FP32 value to E5M2, returning uint8 bits.

```typescript
const castF32ToE5M2: (value: number) => number
```

## cast

Bulk conversion between different numeric types; modifies the destination array in place.

```typescript
const cast: (src: TypedArray, srcType: string, dst: TypedArray, dstType: string) => void
```