# Tensors and Views

> NumKong for JavaScript

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.

Owned `Vector` and `Matrix` are fixed-capacity resizable.
`capacity` reports the allocated element ceiling.
`tryResize(...)` reshapes within capacity without moving the `ArrayBuffer`, so a `toTypedArray()` result stays valid.
`reserve(elements)` may allocate a new `ArrayBuffer` to grow, which __invalidates__ any `TypedArray` or `row()` handed out earlier.
`clear()` empties the length while keeping capacity.

`import { TensorBase } from 'numkong';`

`import { VectorBase } from 'numkong';`

`import { VectorView } from 'numkong';`

`import { Vector } from 'numkong';`

`import { MatrixBase } from 'numkong';`

`import { Matrix } from 'numkong';`

## TensorBase

Abstract base class for all tensor types.

```typescript
abstract class TensorBase
```

All fields are embedded, with zero dynamic allocation. DType is a numeric enum, letting a switch
over it compile to a jump table. Mirrors the C++ pattern: buffer + byteOffset + dtype.

## buffer

```typescript
buffer: ArrayBuffer
```

## byteOffset

```typescript
byteOffset: number
```

## dtype

```typescript
readonly dtype: DType
```

## length

```typescript
readonly length: number
```

## rank

```typescript
readonly rank: number
```

## bytesPerElement

Bytes per element for this tensor's dtype; the switch compiles to a jump table.

```typescript
readonly bytesPerElement: number
```

## byteLength

Total byte length of the tensor data.

```typescript
readonly byteLength: number
```

## VectorBase

Abstract rank-1 tensor base class.

```typescript
abstract class VectorBase extends TensorBase
```

## length

```typescript
length: number
```

## rank

```typescript
readonly rank: 1
```

## buffer

```typescript
buffer: ArrayBuffer
```

## byteOffset

```typescript
byteOffset: number
```

## dtype

```typescript
readonly dtype: DType
```

## bytesPerElement

Bytes per element for this tensor's dtype; the switch compiles to a jump table.

```typescript
readonly bytesPerElement: number
```

## byteLength

Total byte length of the tensor data.

```typescript
readonly byteLength: number
```

## VectorView

Non-owning rank-1 tensor view (like std::span<T>).

```typescript
class VectorView extends VectorBase
```

Zero-copy wrapper for existing memory. Ideal for cross-module WASM interop where data already
lives on the WASM heap.

## VectorView

```typescript
new VectorView(
    buffer: ArrayBuffer,
    byteOffset: number,
    length: number,
    dtype: DType,
)
```

## from

Create a VectorView from any TypedArray, inferring or accepting dtype.

```typescript
static from(arr: TypedArray, dtype?: DType): VectorView
```

## to*

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

## length

```typescript
length: number
```

## rank

```typescript
readonly rank: 1
```

## buffer

```typescript
buffer: ArrayBuffer
```

## byteOffset

```typescript
byteOffset: number
```

## dtype

```typescript
readonly dtype: DType
```

## bytesPerElement

Bytes per element for this tensor's dtype; the switch compiles to a jump table.

```typescript
readonly bytesPerElement: number
```

## byteLength

Total byte length of the tensor data.

```typescript
readonly byteLength: number
```

## Vector

Owning rank-1 tensor (like std::vector<T>).

```typescript
class Vector extends VectorBase
```

Allocates its own ArrayBuffer. Use for storing results or when you need independent ownership of
the data.

## Vector

```typescript
new Vector(length: number, dtype: DType)
```

```typescript
new Vector(buffer: ArrayBuffer, length: number, dtype: DType)
```

## fromTypedArray

Create an owning Vector by copying data from a TypedArray.

```typescript
static fromTypedArray(arr: TypedArray, dtype?: DType): Vector
```

## fromView

Create an owning Vector by copying data from any TensorBase.

```typescript
static fromView(view: TensorBase): Vector
```

## toTypedArray

Return a TypedArray view over this Vector's owned buffer, zero-copy.

```typescript
toTypedArray(): TypedArray
```

## tryResize

Resize within capacity without moving storage — `toTypedArray()` views stay valid.

```typescript
tryResize(length: number): boolean
```

## reserve

Grow the allocated capacity to at least `elements`, reallocating and copying the live elements.

```typescript
reserve(elements: number): boolean
```

A no-op when already large enough; otherwise it invalidates any TypedArray already returned by `toTypedArray()`, which keeps pointing at the old buffer.

## clear

Reset to length 0 while keeping the allocated capacity.

```typescript
clear(): void
```

## capacity

Allocated element capacity (>= length) — the ceiling [`tryResize`](#tryResize) honors.

```typescript
readonly capacity: number
```

## length

```typescript
length: number
```

## rank

```typescript
readonly rank: 1
```

## buffer

```typescript
buffer: ArrayBuffer
```

## byteOffset

```typescript
byteOffset: number
```

## dtype

```typescript
readonly dtype: DType
```

## bytesPerElement

Bytes per element for this tensor's dtype; the switch compiles to a jump table.

```typescript
readonly bytesPerElement: number
```

## byteLength

Total byte length of the tensor data.

```typescript
readonly byteLength: number
```

## MatrixBase

Abstract rank-2 tensor base class.

```typescript
abstract class MatrixBase extends TensorBase
```

All 4 dimension fields are embedded — no dynamic allocation.
Strides are in bytes to match the C API directly.

## rows

```typescript
rows: number
```

## columns

```typescript
columns: number
```

## rowStride

```typescript
rowStride: number
```

## colStride

```typescript
colStride: number
```

## length

```typescript
readonly length: number
```

## rank

```typescript
readonly rank: 2
```

## buffer

```typescript
buffer: ArrayBuffer
```

## byteOffset

```typescript
byteOffset: number
```

## dtype

```typescript
readonly dtype: DType
```

## bytesPerElement

Bytes per element for this tensor's dtype; the switch compiles to a jump table.

```typescript
readonly bytesPerElement: number
```

## byteLength

Total byte length of the tensor data.

```typescript
readonly byteLength: number
```

## Matrix

Owning rank-2 tensor, row-major and C-contiguous by default.

```typescript
class Matrix extends MatrixBase
```

Strides are byte strides. Default for C-contiguous layout:
rowStride = columns * bytesPerElement, colStride = bytesPerElement.

## Matrix

```typescript
new Matrix(rows: number, columns: number, dtype: DType)
```

```typescript
new Matrix(
    buffer: ArrayBuffer,
    byteOffset: number,
    dtype: DType,
    rows: number,
    columns: number,
    rowStride?: number,
    colStride?: number,
)
```

## fromTypedArray

```typescript
static fromTypedArray(
    array: TypedArray,
    rows: number,
    columns: number,
    dtype?: DType,
): Matrix
```

## toTypedArray

```typescript
toTypedArray(): TypedArray
```

## row

```typescript
row(index: number): VectorView
```

## tryResize

Resize within capacity without moving storage (`row()`/`toTypedArray()` views stay valid), re-deriving C-contiguous strides.

```typescript
tryResize(rows: number, columns: number): boolean
```

## reserve

Grow the allocated capacity to at least `elements`, reallocating and copying the live rows*columns elements.

```typescript
reserve(elements: number): boolean
```

A no-op when already large enough; otherwise it invalidates any prior `toTypedArray()` / `row()` view. Intended for the C-contiguous owning layout.

## clear

Reset to an empty 0x0 matrix while keeping the allocated capacity.

```typescript
clear(): void
```

## capacity

Allocated element capacity (>= rows*columns) — the ceiling [`tryResize`](#tryResize) honors.

```typescript
readonly capacity: number
```

## rows

```typescript
rows: number
```

## columns

```typescript
columns: number
```

## rowStride

```typescript
rowStride: number
```

## colStride

```typescript
colStride: number
```

## length

```typescript
readonly length: number
```

## rank

```typescript
readonly rank: 2
```

## buffer

```typescript
buffer: ArrayBuffer
```

## byteOffset

```typescript
byteOffset: number
```

## dtype

```typescript
readonly dtype: DType
```

## bytesPerElement

Bytes per element for this tensor's dtype; the switch compiles to a jump table.

```typescript
readonly bytesPerElement: number
```

## byteLength

Total byte length of the tensor data.

```typescript
readonly byteLength: number
```