# Keys

> USearch for JavaScript

A key is __sixteen opaque bytes__, most significant first, and that is the only form a full 128-bit key survives.
Matches carry them as one `Uint8Array` of sixteen bytes per match, which is byte-for-byte what the engine writes, so a batch of results needs no conversion pass and no object per match.
The canonical rendering is the lowercase dashed UUID the ABI fixes, and that is a rendering rather than a second carrier.

```javascript
usearch.keyFromInteger(42n);                 // Uint8Array(16), 42 in the trailing byte
usearch.formatKey(usearch.keyFromInteger(42n)); // '00000000-0000-0000-0000-00000000002a'
usearch.parseKey('f81d4fae-7dec-11d0-a765-00a0c91e6bf6'); // Uint8Array(16)
usearch.keyAt(matches.keys, 0);                           // the first key, as a view rather than a copy
usearch.integerFromKey(usearch.keyAt(matches.keys, 0)); // its integer, when it was inserted as one
```

An integer key parks in the trailing eight bytes with the leading eight zeroed, so `42n` prints as `00000000-0000-0000-0000-00000000002a`.
`integerFromKey` throws on a key whose leading bytes carry anything, since no integer spells it.

Keys are accepted in every one of those spellings, plus a `BigUint64Array` of integer keys, which stays the convenient path for services that number their entries:

```javascript
index.insert(42n, vector);                                     // a BigInt
index.insert(new BigUint64Array([15n, 16n]), vectors);         // a run of integers
index.insert('f81d4fae-7dec-11d0-a765-00a0c91e6bf6', vector);  // a dashed UUID
index.insert(usearch.parseKey('f81d4fae-7dec-11d0-a765-00a0c91e6bf6'), vector); // bytes
```

A single key broadcasts across every row of a batch, and a `Uint8Array` of keys crosses without a copy.

`import * as usearch from 'usearch';`

## Key

Sixteen opaque bytes, most significant first - one identity, losslessly.

```typescript
type Key = Uint8Array
```

A run of several identities is the same type with a length that is a multiple of
[`keyBytes`](#keyBytes), which is what lets one batch of keys cross as one array.

## KeyLike

Every spelling one identity is accepted in.

```typescript
type KeyLike = bigint | number | string | Uint8Array
```

## KeysLike

Every spelling a run of identities is accepted in.

```typescript
type KeysLike = KeyLike | BigUint64Array | Array<bigint | number | string | Uint8Array>
```

## keyFromInteger

Parks an integer identity in the trailing eight bytes, most significant first.

```typescript
function keyFromInteger(value: bigint | number): Key
```

Binding-only.

- `value`: A non-negative integer below 2^64.

## integerFromKey

Reports the integer identity in the trailing eight bytes.

```typescript
function integerFromKey(key: Uint8Array): bigint
```

Binding-only.

- `key`: Sixteen identity bytes.

Throws: Will throw an error if the leading eight bytes carry anything, since no integer
spells that identity.

## formatKey

Renders one identity as a lowercase dashed UUID, which is how every SDK prints it.

```typescript
function formatKey(key: Uint8Array): string
```

Binding-only.

- `key`: Sixteen identity bytes.

## parseKey

Reads the rendering [`formatKey`](#formatKey) produces.

```typescript
function parseKey(text: string): Key
```

Dashes may sit anywhere, or nowhere. Binding-only.

- `text`: Thirty-two hexadecimal digits, dashes ignored.

## keyAt

Borrows the identity at `position` of a run, as a view rather than a copy.

```typescript
function keyAt(keys: Uint8Array, position: number): Key
```

Binding-only.

- `keys`: A run of sixteen-byte identities.
- `position`: Which identity to borrow.

## keyBytes

Bytes one identity occupies, on the wire and in the engine alike.

```typescript
const keyBytes: 16
```