JavaScript / TypeScript API reference

Every public function of the Node.js and Bun package (a native addon; TypeScript types included), with its parameters and results (Kwker 0.1.0).

SortableArray Page

export type SortableArray =
  | Int8Array | Uint8Array | Uint8ClampedArray | Int16Array | Uint16Array | Int32Array | Uint32Array
  | Float32Array | Float64Array | BigInt64Array | BigUint64Array;

Kwker: sorting, selection and top-k of TypedArrays, in place, with the fastest engine for the CPU chosen at run time.

Order Page

export interface Order {
  descending?: boolean;
  nansFirst?: boolean;
}

Order: smallest first unless descending; NaNs last unless nansFirst.

Remarks: Stable (rule 6): equal keys keep their input order, so the same input always gives the same positions. Keys follow the key order: -0.0 before +0.0, every NaN in one block, last unless NaNs-first is asked for.

sort Page

export function sort<T extends SortableArray>(a: T, order?: Order): T;

Sorts a in place and returns it.

Remarks: Not stable (rule 5): keys that are equal but can be told apart (NaNs with different bits) may change places. Keys follow the key order: -0.0 before +0.0, every NaN in one block, last unless NaNs-first is asked for.

select Page

export function select<T extends SortableArray>(a: T, k: number, order?: Order): T;

a[k] gets the key a full sort would put there; every key before it sorts before or equal to it, every key after it after or equal. Neither side is sorted. RangeError unless k < n.

Remarks: Position k holds the key a full sort puts there; the keys before it are ordered before or equal to it, the keys after it after or equal (rule 7). Keys follow the key order: -0.0 before +0.0, every NaN in one block, last unless NaNs-first is asked for.

partialSort Page

export function partialSort<T extends SortableArray>(a: T, k: number, order?: Order): T;

The first min(k, n) keys in order, the rest in any order.

Remarks: The first k positions hold exactly what a full sort puts there; the rest hold the other keys in any order (rule 8). Keys follow the key order: -0.0 before +0.0, every NaN in one block, last unless NaNs-first is asked for.

argsort Page

export function argsort(a: SortableArray, order?: Order): Uint32Array;

The stable sorting permutation (a is not modified).

Remarks: Stable (rule 6): equal keys keep their input order, so the same input always gives the same positions. Keys follow the key order: -0.0 before +0.0, every NaN in one block, last unless NaNs-first is asked for.

topK Page

export function topK<T extends SortableArray>(a: T, k: number, order?: Order & { sorted?: boolean }): { values: T; indices: Uint32Array };

The first min(k, n) keys of the stable order and their indices (ties by index).

Remarks: The first k keys of the stable order and their positions; equal keys keep their input order (rule 9). Keys follow the key order: -0.0 before +0.0, every NaN in one block, last unless NaNs-first is asked for.

sortKV Page

export function sortKV<T extends SortableArray>(keys: T, values: SortableArray, order?: Order): T;

Sorts keys in place and moves values (a TypedArray of the same length) with them.

Remarks: Unless the stable form is asked for, pairs with equal keys may come out in any order; the stable form keeps their input order (rule 6). Keys follow the key order: -0.0 before +0.0, every NaN in one block, last unless NaNs-first is asked for.

searchsorted Page

export function searchsorted<T extends SortableArray>(sorted: T, queries: T, options?: Order & { side?: 'left' | 'right' }): Uint32Array;

Insertion positions of queries in sorted (sorted in order): side "left" (default) before equal keys, "right" after.

Remarks: -0.0 and +0.0 compare equal here, as in NumPy (rule 14).

isa Page

export function isa(): string;

The engine in use: "avx512", "avx2", "sse42", "neon" or "portable".

Remarks: The engine changes only the speed, never a result (rule 11).

setIsa Page

export function setIsa(name?: 'avx512' | 'avx2' | 'neon' | 'simd128' | 'portable' | null): string;

Caps the engine of later calls at run time (null: the best the CPU allows); returns the engine now in use.

Remarks: The engine changes only the speed, never a result (rule 11).

Stage Page

export interface Stage { id: number; name: string; about: string; count: number; cycles: number }

One engine stage a call ran (its name and description from the engines' stage list).

observe Page

export function observe<R>(fn: () => R): { result: R; report: { isa: string; traced: boolean; stages: Stage[] } };

fn() with the engines' path trace on: its result and the stages its calls ran (the x86 engines are traced).

version Page

export function version(): string;

The library version.

setScratchLimit Page

export function setScratchLimit(bytes: number | null): void;

The calling thread's scratch-memory limit in bytes for later calls (null: none; 0: no allocation).

Remarks: The scratch limit changes only the speed and memory use, never a result (rule 12).