# Inputs and Outputs > USearch for JavaScript ### Arenas Every output whose length only the call knows, such as matches, rows, products, monoliths and cursor or stream batches, lands in an `Arena` you pass, and the verb answers a view over it without copying. `new Arena(executor)` places it where that executor computes, decided once, and `new Arena()` makes host pages for the calling thread. Each call rewinds its arena, so the previous call's views die and a steady loop allocates once. To keep a result past the next call, or to read one while making the next, pass that call another arena. An arena serves one call at a time, so each deferred call needs its own. A deferred call borrows its arena as a blocking one does: another call naming it before the first is final finishes with `Status.Contended`, and `free()` waits for it. A rewind or a `free()` detaches every buffer over the previous outputs, so a stale view throws `Status.Uninitialized` and typed arrays taken from it read as empty. An arena from a VRAM executor holds device memory, which host accessors refuse with `Status.Device`. It grows, fills and frees on that executor's first stream, so it serves only calls on that executor and keeps it alive until freed, and the executor's `free()` refuses with `Status.Contended` while such an arena lives; a host arena may outlive its executor. ```javascript const { Arena, keyAt } = usearch; using arena = new Arena(executor); // new Arena() is host pages for the calling thread for (const batch of batches) { const matches = index.on(executor).search(batch, 10, arena); // rewinds: last batch's matches are gone total += matches.scores.reduce((sum, score) => sum + score, 0); } using found = new Arena(), fetched = new Arena(); // two live results, two arenas const nearest = index.search(query, 10, found).get(0); for (let position = 0; position < nearest.count; position++) rerank(keyAt(nearest.keys, position), index.get(keyAt(nearest.keys, position), fetched)); // One executor and one arena per submitted call const calls = shards.map((shard, at) => shard.deferred(executors[at]).search(queries, 10, arenas[at])); const results = []; for (const call of calls) results.push(await call); // or: call.wait() ``` Only fixed-size reports, like `describe` and the telemetry readings, come back as plain objects. ### Rows & Scalars A bare `TypedArray` is one row, and a `RowsView` is a run of them borrowed in place. It names the array, the row count, the columns, the bytes between rows, and the scalar kind, so a memory-mapped dataset reaches the index with no reshape and no copy. `RowsView.of` reads a packed array as rows of the width it is given: ```javascript const keys = new BigUint64Array([15n, 16n]); const vectors = usearch.RowsView.of(new Float32Array([10, 20, 10, 25]), 2); // two rows of two index.insert(keys, vectors); const padded = new usearch.RowsView(mapped, rows, 768, 1024 * 4, usearch.Scalar.F32); // a pitch of 1024 floats const matches = index.search(vectors, 2, arena); ``` The engine converts rows on ingest, so what a caller holds is independent of what the index stores. A `Float64Array`, `Float32Array`, `Float16Array`, `Int8Array` or `Uint8Array` names its own scalar kind; every other kind travels as bytes in a `RowsView` naming what they mean: ```javascript const bits = usearch.DenseIndex.initRam({ metric: usearch.DenseMetric.Hamming, dimensions: 64, quantization: usearch.Scalar.U1x8 }); const packed = usearch.RowsView.of(new Uint8Array([0b10101010, 0, 0, 0, 0, 0, 0, 0]), 64, usearch.Scalar.U1x8); bits.insert(1n, packed); bits.search(packed, 2, arena); const halves = usearch.RowsView.of(new Uint16Array([0x3f80, 0x3f80, 0x3f80, 0x3f80]), 4, usearch.Scalar.BF16); ``` A row run claiming more bytes than its array holds is refused before it crosses. ### Search `search` lands its matches in the arena as `Matches`, three views: the keys, the scores, and how many matches every query actually found. ```javascript const matches = index.search(queries, 10, arena); matches.queries; // Queries in the run matches.columns; // Columns per query the call wrote, at most its 'k' matches.counts; // BigUint64Array, the matches every query found matches.keys; // Uint8Array, sixteen bytes per cell, queries laid end to end matches.scores; // Float64Array, one distance per cell const found = matches.get(0); // A QueryMatches, borrowed out of the run rather than copied found.count; // Matches this query found, never above `wanted` found.keys; // Sixteen bytes per match found found.scores; // One distance per match found ``` Every view reads the arena's own memory rather than a copy, so reading a query costs nothing. Scores come back as a `Float64Array`, which is the width the ABI writes. The breadth of the candidates rides every call rather than the construction, so a recall sweep runs against one immutable index with no mutation between points: ```javascript index.on(executor).insert(keys, vectors, { expansionFactor: 128 }); index.on(executor).search(queries, 10, arena, { expansionFactor: 64 }); index.on(executor).search(queries, 10, arena, { traversal: usearch.Traversal.Scan }); // exact, on RAM and NVMe handles ``` `insert`, `refine`, `search`, `maxsim`, `multiply` and `attend` each report how much graph they walked, into a `DenseTraversalStats` reading passed through the config: ```javascript const stats = new usearch.DenseTraversalStats(); index.on(executor).search(queries, 10, arena, { stats }); stats.visitedMembers; // entries whose neighborhoods the walk expanded stats.computedDistances; // distance evaluations the walk paid for stats.restarts; // times the walk fell back to a fresh entry point const total = new usearch.DenseTraversalStats(); // sweeping, and reading the whole sweep's cost for (const expansionFactor of [16, 32, 64, 128]) { index.on(executor).search(queries, 10, arena, { expansionFactor, stats }); total.accumulate(stats); } ``` Telemetry travels through the reading rather than the return value, so `refine` still answers with its report and a ranked verb with its matches, and passing none costs nothing. A reading is a pure output that each call fully overwrites, so one `DenseTraversalStats` handed to several calls holds the last of them, and a deferred call writes it once it settles. Use `accumulate` to fold readings together: `expansionFactor` buys recall in distance computations, and only the counters say how many, so a sweep reusing one arena allocates once and reads its cost between the points. `import * as usearch from 'usearch';` `import { DenseTraversalStats } from 'usearch';` `import { RowsView } from 'usearch';` `import { Arena } from 'usearch';` `import { ArenaView } from 'usearch';` `import { QueryMatches } from 'usearch';` `import { Matches } from 'usearch';` ## DenseInsertConfig Optional per-call settings of an insertion. ```typescript interface DenseInsertConfig ``` - `expansionFactor?` `number`: Breadth of the candidates the build walk explores; absent lets the engine derive it. - `stats?` `DenseTraversalStats`: The reading this call overwrites with its own telemetry; absent skips reporting. ## DenseSearchConfig Optional per-call settings of a search. ```typescript interface DenseSearchConfig ``` - `expansionFactor?` `number`: Breadth of the candidates the walk explores; absent lets the engine derive it, and a scan ignores it. - `traversal?` `Traversal`: Walks the graph when absent; [`Traversal.Scan`](#Scan) scores every entry exactly, on RAM and NVMe handles. - `stats?` `DenseTraversalStats`: The reading this call overwrites with its own telemetry; absent skips reporting. ## Traversal How a search reaches the entries it scores. ```typescript enum Traversal ``` - `Walk` = `"walk"`: Walks the graph, scoring the entries the expansion reaches - approximate, the default. - `Scan` = `"scan"`: Scores every entry published when the query's scan starts - exact, on RAM and NVMe handles. ## Scalar Enumeration representing the scalar kinds vectors are stored and exchanged in. ```typescript enum Scalar ``` - `F64` = `"f64"`: IEEE-754 binary64: ±1.80e308, epsilon 2.22e-16, with infinities and NaNs. - `F32` = `"f32"`: IEEE-754 binary32: ±3.40e38, epsilon 1.19e-7, with infinities and NaNs. - `BF16` = `"bf16"`: Truncated `f32` with a 7-bit mantissa: `f32`'s range at epsilon 7.81e-3. - `F16` = `"f16"`: IEEE-754 binary16: ±65504, epsilon 9.77e-4, with infinities and NaNs. - `E5M2` = `"e5m2"`: FP8 with a 5-bit exponent: ±57344, epsilon 0.25, with infinities and NaNs. - `E4M3` = `"e4m3"`: FP8 with a 4-bit exponent: ±448, epsilon 0.125, no infinities. - `E3M2` = `"e3m2"`: FP6 with a 3-bit exponent in one byte: ±28, every code a number. - `E2M3` = `"e2m3"`: FP6 with a 2-bit exponent in one byte: ±7.5, every code a number. - `I8` = `"i8"`: 8-bit signed integer spanning -128 to 127. - `I4x2` = `"i4x2"`: Two signed nibbles per byte spanning -8 to 7, even dimensions in the low nibble. - `I32` = `"i32"`: The coordinates of geospatial points, which vectors refuse. - `U8` = `"u8"`: 8-bit unsigned integer spanning 0 to 255. - `U4x2` = `"u4x2"`: Two unsigned nibbles per byte spanning 0 to 15, even dimensions in the low nibble. - `U1x8` = `"u1x8"`: Eight single-bit dimensions per byte, the form the Hamming and Jaccard metrics score. ## Vector One row of scalars, in whatever numeric TypedArray the caller already holds. ```typescript type Vector = Float64Array | Float32Array | Float16Array | Int8Array | Uint8Array | Uint16Array ``` The engine converts on ingest, so this is independent of the index's own quantization: an `Int8Array` reaches an `f16` index unchanged. The kinds no TypedArray spells on its own - `bf16`, the mini-floats, the packed nibbles and bits - travel as bytes in a `Uint8Array` or `Uint16Array`, inside a [`RowsView`](#RowsView) naming their [`Scalar`](#Scalar). ## DenseTraversalStats Traversal telemetry from one call, a pure output the call fully overwrites. ```typescript class DenseTraversalStats ``` One reading handed to several calls holds the last of them, so a sweep that wants totals folds them with [`accumulate`](#accumulate) rather than expecting the calls to sum themselves. ## accumulate Folds another reading into this one, which is how a sweep gathers totals. ```typescript accumulate(other: DenseTraversalStats): void ``` Binding-only. ## visitedMembers Entries whose neighborhoods the walk expanded. ```typescript visitedMembers: number ``` ## computedDistances Distance evaluations the walk paid for, diversity re-selections included. ```typescript computedDistances: number ``` ## restarts Times the walk fell back to a fresh entry point after the frontier drained early. ```typescript restarts: number ``` ## RowsView A borrowed run of rows of one width - what every batch argument is, and what a single row is when it travels as a bare TypedArray. ```typescript class RowsView ``` Its row count travels beside it as the call's [`count`](https://www.unum.cloud/docs/usearch/javascript/metrics.md#count). ## RowsView Borrows [`rows`](https://www.unum.cloud/docs/usearch/javascript/retrieval-and-streaming.md#rows) rows of [`columns`](https://www.unum.cloud/docs/usearch/javascript/retrieval-and-streaming.md#columns) values of [`scalar`](https://www.unum.cloud/docs/usearch/javascript/retrieval-and-streaming.md#scalar), [`stride`](https://www.unum.cloud/docs/usearch/javascript/retrieval-and-streaming.md#stride) bytes apart; a zero stride repeats the first row. ```typescript new RowsView( data: Vector, rows: number, columns: number, stride: number, scalar: Scalar, ) ``` - `data`: The array holding every row; never copied. - `rows`: Rows the run holds, which the call reads as its batch. - `columns`: Values per row, as the index counts its dimensions. - `stride`: Bytes between the starts of consecutive rows. - `scalar`: What the bytes hold, converted by the engine where it differs from storage. ## of Borrows a packed run, every row [`columns`](https://www.unum.cloud/docs/usearch/javascript/retrieval-and-streaming.md#columns) values wide and laid end to end. ```typescript static of( data: Vector, columns: number, scalar: Scalar = scalarOf(data), ): RowsView ``` Binding-only sugar. - `data`: The rows, end to end. - `columns`: Values per row. - `scalar`: What the bytes hold; defaults to the kind the array spells. Throws: Will throw when the array does not split into whole rows. ## Arena Memory the library writes every output whose length scales with a call into, reused across calls. ```typescript interface Arena extends Disposable ``` Every verb with such an output takes one and answers a view into it rather than a copy, so a steady loop allocates once. Each call rewinds the arena it is handed and detaches every buffer over the previous call's outputs: a view refuses its reads with [`Status.Uninitialized`](https://www.unum.cloud/docs/usearch/javascript/errors.md#Uninitialized) from then on, and every array already taken out of one reads empty rather than another call's memory. To keep one result past the next call, give that call another arena. A deferred call borrows it as a blocking one does: another call naming it before the first is final finishes [`Status.Contended`](https://www.unum.cloud/docs/usearch/javascript/errors.md#Contended) and leaves the first call's outputs alone, and [`free`](https://www.unum.cloud/docs/usearch/javascript/retrieval-and-streaming.md#free) waits for it. The collector frees the arena once nothing views it; [`free`](https://www.unum.cloud/docs/usearch/javascript/retrieval-and-streaming.md#free) releases it now. A [`Vram`](https://www.unum.cloud/docs/usearch/javascript/residency.md#Vram) arena grows, fills and frees on its executor's first stream, so it serves only calls on that executor and keeps it alive until freed; host pages may outlive their executor. ## Arena Makes an arena where [`executor`](https://www.unum.cloud/docs/usearch/javascript/metrics.md#executor) computes, or host pages for calls on the calling thread when absent. ```typescript new Arena(executor?: Executor): Arena ``` ## free Releases the memory now, once every deferred call writing it is final, detaching every view into it; a second call does nothing. ```typescript free(): void ``` ## residency The residency of the executor that made it; a [`Vram`](https://www.unum.cloud/docs/usearch/javascript/residency.md#Vram) arena's views refuse host reads with [`Status.Device`](https://www.unum.cloud/docs/usearch/javascript/errors.md#Device). ```typescript readonly residency: Residency ``` ## ArenaView Outputs a call wrote into an arena, readable until the arena's next call rewinds it. ```typescript abstract class ArenaView ``` The rewind detaches the buffer under every array, so each accessor refuses once the arena moved on, with [`Status.Uninitialized`](https://www.unum.cloud/docs/usearch/javascript/errors.md#Uninitialized), and refuses device memory with [`Status.Device`](https://www.unum.cloud/docs/usearch/javascript/errors.md#Device), so a view never reads memory its call did not write. ## QueryMatches The matches of one query, borrowed out of a run rather than copied. ```typescript class QueryMatches ``` Both arrays are subarrays of the run's own storage, so reading a query costs nothing. ## QueryMatches ```typescript new QueryMatches(keys: Uint8Array, scores: Float64Array) ``` ## count Matches this query found, which may be fewer than the run asked for. ```typescript readonly count: number ``` ## Matches The ranked matches a search or a stream pull wrote into its arena: [`queries`](https://www.unum.cloud/docs/usearch/javascript/linear-algebra.md#queries) rows of [`columns`](https://www.unum.cloud/docs/usearch/javascript/retrieval-and-streaming.md#columns) cells, query `i` holding `counts[i]` matches. ```typescript class Matches extends ArenaView ``` ## Matches Made by a ranked verb, never directly. ```typescript new Matches(outputs: CompiledMatches, queries: number) ``` ## get Borrows the matches of one query, without copying. ```typescript get(queryIndex: number): QueryMatches ``` Binding-only. - `queryIndex`: Which query of the run to read. ## queries Queries the call resolved. ```typescript readonly queries: number ``` ## columns Columns per query the call wrote, at most its `wanted` - the "k" in "kANN". ```typescript readonly columns: number ``` ## keys The `queries × columns` identity matrix, rows contiguous, sixteen bytes per key. ```typescript readonly keys: Uint8Array ``` ## scores The `queries × columns` distance matrix, rows contiguous. ```typescript readonly scores: Float64Array ``` ## counts Matches written per query, one count per query. ```typescript readonly counts: BigUint64Array ```