usearch 2.9.1 → 2.10.0

package/javascript/dist/esm/usearch.d.ts

@@ -0,0 +1,212 @@
+type Vector = Float32Array | Float64Array | Int8Array;
+type Matrix = Vector[];
+type VectorOrMatrix = Vector | Matrix;
+/**
+ * Enumeration representing the various metric kinds used to measure the distance between vectors in the index.
+ * @enum {string}
+ * @readonly
+ */
+export declare enum MetricKind {
+    Unknown = "unknown",
+    Cos = "cos",
+    IP = "ip",
+    L2sq = "l2sq",
+    Haversine = "haversine",
+    Divergence = "divergence",
+    Pearson = "pearson",
+    Jaccard = "jaccard",
+    Hamming = "hamming",
+    Tanimoto = "tanimoto",
+    Sorensen = "sorensen"
+}
+/**
+ * Enumeration representing the various scalar kinds used to define the type of scalar values in vectors.
+ * @enum {string}
+ * @readonly
+ */
+export declare enum ScalarKind {
+    Unknown = "unknown",
+    F32 = "f32",
+    F64 = "f64",
+    F16 = "f16",
+    I8 = "i8",
+    B1 = "b1"
+}
+/**
+ * Represents a set of search results.
+ */
+export declare class Matches {
+    keys: BigUint64Array;
+    distances: Float32Array;
+    /**
+     * Constructs a Matches object.
+     *
+     * @param {BigUint64Array} keys - The keys of the nearest neighbors found.
+     * @param {Float32Array} distances - The distances of the nearest neighbors found.
+     */
+    constructor(keys: BigUint64Array, distances: Float32Array);
+}
+/**
+ * Represents a set of batched search results.
+ */
+export declare class BatchMatches {
+    keys: BigUint64Array;
+    distances: Float32Array;
+    counts: BigUint64Array;
+    k: number;
+    /**
+     * Constructs a BatchMatches object.
+     *
+     * @param {BigUint64Array} keys - The keys of the nearest neighbors found in the batch.
+     * @param {Float32Array} distances - The distances of the nearest neighbors found in the batch.
+     * @param {BigUint64Array} counts - The number of neighbors found for each query in the batch.
+     * @param {number} k - The limit for search results per query in the batch.
+     */
+    constructor(keys: BigUint64Array, distances: Float32Array, counts: BigUint64Array, k: number);
+    /**
+     * Retrieves a Matches object at the specified index in the batch.
+     *
+     * @param {number} i - The index at which to retrieve the Matches object.
+     * @returns {Matches} - A Matches object representing the search results at the specified index in the batch.
+     */
+    get(i: number): Matches;
+}
+export interface IndexCongif {
+    dimensions: number;
+    metric: MetricKind;
+    quantization: ScalarKind;
+    connectivity: number;
+    expansion_add: number;
+    expansion_search: number;
+    multi: boolean;
+}
+export declare class Index {
+    #private;
+    /**
+     * Constructs a new index.
+     *
+     * @param {(number | {dimensions: number, metric: MetricKind = MetricKind.Cos, quantization: ScalarKind = ScalarKind.F32, connectivity: number = 0, expansion_add: number = 0, expansion_search: number = 0, multi: boolean = false})} dimensionsOrConfigs
+     * @param {MetricKind} [metric=MetricKind.Cos] - Optional, default is 'cos'.
+     * @param {ScalarKind} [quantization=ScalarKind.F32] - Optional, default is 'f32'.
+     * @param {number} [connectivity=0] - Optional, default is 0.
+     * @param {number} [expansion_add=0] - Optional, default is 0.
+     * @param {number} [expansion_search=0] - Optional, default is 0.
+     * @param {boolean} [multi=false] - Optional, default is false.
+     * @throws Will throw an error if any of the parameters are of incorrect type or invalid value.
+     */
+    constructor(dimensionsOrConfigs: number | bigint | IndexCongif, metric?: MetricKind, quantization?: ScalarKind, connectivity?: number, expansion_add?: number, expansion_search?: number, multi?: boolean);
+    /**
+     * Add vectors to the index.
+     *
+     * This method accepts vectors and their corresponding keys for indexing.
+     * Each key should correspond to a vector. If a single key is provided,
+     * it is broadcasted to match the number of provided vectors.
+     *
+     * Vectors should be provided as a flat typed array representing a matrix
+     * where each row is a vector to be indexed. The matrix should have a size
+     * of n * d, where n is the number of vectors, and d is the dimensionality
+     * of the vectors.
+     *
+     * Keys should be provided as a BigInt or an array-like object of BigInts
+     * representing the unique identifier for each vector.
+     *
+     * @param {bigint|bigint[]|BigUint64Array} keys - Input identifiers for every vector.
+     *        If a single key is provided, it is associated with all provided vectors.
+     * @param {Float32Array|Float64Array|Int8Array} vectors - Input matrix representing vectors,
+     *        matrix of size n * d, where n is the number of vectors, and d is their dimensionality.
+     * @throws Will throw an error if the length of keys doesn't match the number of vectors
+     *         or if it's not a single key.
+     */
+    add(keys: bigint | bigint[] | BigUint64Array, vectors: Vector): void;
+    /**
+     * Perform a k-nearest neighbor search on the index.
+     *
+     * This method accepts a matrix of query vectors and returns the closest vectors
+     * from the index for each query. The method returns an object containing the keys,
+     * distances, and counts of the matches found.
+     *
+     * Vectors should be provided as a flat typed array representing a matrix where
+     * each row is a vector. The matrix should be of size n * d, where n is the
+     * number of query vectors, and d is their dimensionality.
+     *
+     * The parameter `k` specifies the number of nearest neighbors to return for each
+     * query vector. If there are not enough results for a query, the result array is
+     * padded with -1s.
+     *
+     * @param {Float32Array|Float64Array|Int8Array|Array<Array<number>>} vectors - Input matrix representing query vectors, can be a TypedArray or an array of TypedArray.
+     * @param {number} k - The number of nearest neighbors to search for each query vector.
+     * @return {Matches|BatchMatches} - Search results for one or more queries, containing keys, distances, and counts of the matches found.
+     * @throws Will throw an error if `k` is not a positive integer or if the size of the vectors is not a multiple of dimensions.
+     * @throws Will throw an error if `vectors` is not a valid input type (TypedArray or an array of TypedArray) or if its flattened size is not a multiple of dimensions.
+     */
+    search(vectors: VectorOrMatrix, k: number): Matches | BatchMatches;
+    /**
+     * Verifies the presence of one or more keys in the index.
+     *
+     * This method accepts one or multiple keys as input and returns a boolean or
+     * an array of booleans indicating whether each key is present in the index.
+     *
+     * @param {bigint|bigint[]|BigUint64Array} keys - The identifier(s) of the vector(s) to be checked for presence in the index.
+     * @return {boolean|boolean[]} - Returns true if a single key is contained in the index, false otherwise. Returns an array of booleans corresponding to the presence of each key in the index when multiple keys are provided.
+     * @throws Will throw an error if keys are not integers.
+     */
+    contains(keys: bigint | bigint[] | BigUint64Array): boolean | boolean[];
+    /**
+     * Counts the number of times keys shows up in the index.
+     *
+     * @param {bigint|bigint[]|BigUint64Array} keys - The identifier(s) of the vector(s) to be enumerated.
+     * @return {number|number[]} - Returns the number of vectors found when a single key is provided. Returns an array of big integers corresponding to the number of vectors found for each key when multiple keys are provided.
+     * @throws Will throw an error if keys are not integers.
+     */
+    count(keys: bigint | bigint[] | BigUint64Array): number | number[];
+    /**
+     * Removes one or multiple vectors from the index.
+     *
+     * This method accepts one or multiple keys as input and removes the corresponding vectors from the index.
+     * It returns the number of vectors actually removed for each key provided.
+     *
+     * @param {bigint|bigint[]|BigUint64Array} keys - The identifier(s) of the vector(s) to be removed.
+     * @return {number|number[]} - Returns the number of vectors deleted when a single key is provided. Returns an array of big integers corresponding to the number of vectors deleted for each key when multiple keys are provided.
+     * @throws Will throw an error if keys are not integers.
+     */
+    remove(keys: bigint | bigint[] | BigUint64Array): number | number[];
+    /**
+     * Returns the dimensionality of vectors.
+     * @return {number} The dimensionality of vectors.
+     */
+    dimensions(): number;
+    /**
+     * Returns connectivity.
+     * @return {number} The connectivity of index.
+     */
+    connectivity(): number;
+    /**
+     * Returns the number of vectors currently indexed.
+     * @return {number} The number of vectors currently indexed.
+     */
+    size(): number;
+    /**
+     * Returns index capacity.
+     * @return {number} The capacity of index.
+     */
+    capacity(): number;
+    /**
+     * Write index to a file.
+     * @param {string} path File path to write.
+     * @throws Will throw an error if `path` is not a string.
+     */
+    save(path: string): void;
+    /**
+     * Load index from a file.
+     * @param {string} path File path to read.
+     * @throws Will throw an error if `path` is not a string.
+     */
+    load(path: string): void;
+    /**
+     * View index from a file, without loading into RAM.
+     * @param {string} path File path to read.
+     * @throws Will throw an error if `path` is not a string.
+     */
+    view(path: string): void;
+}
+export {};