TypeScript Types

The Endee TypeScript SDK provides comprehensive type definitions for full type safety and IntelliSense support. This page documents all available types, interfaces, and enums.

Importing Types

Import types directly from the endee package:


import type {
  SpaceType,
  Precision,
  CreateIndexOptions,
  VectorItem,
  QueryOptions,
  QueryResult,
  IndexInfo,
  IndexDescription,
  VectorInfo,
} from 'endee';

Enums

Precision

Defines the quantization precision levels for vector storage and search.


enum Precision {
  BINARY = 'binary',
  INT8D = 'int8d',
  INT16D = 'int16d',
  FLOAT16 = 'float16',
  FLOAT32 = 'float32',
}

Value	Description
`BINARY`	Binary quantization (1-bit) - smallest storage, fastest search
`INT8D`	8-bit integer quantization (default) - balanced performance
`INT16D`	16-bit integer quantization - higher precision
`FLOAT16`	16-bit floating point - good balance
`FLOAT32`	32-bit floating point - highest precision

Usage:


import { Precision } from 'endee';
 
await client.createIndex({
  name: 'my_index',
  dimension: 384,
  precision: Precision.INT8D,
});

Type Aliases

SpaceType

Defines the distance metric used for similarity calculations.


type SpaceType = 'cosine' | 'l2' | 'ip';

Value	Description
`'cosine'`	Cosine similarity - measures angle between vectors
`'l2'`	Euclidean distance - measures straight-line distance
`'ip'`	Inner product - measures dot product similarity

Interfaces

CreateIndexOptions

Options for creating a new index.


interface CreateIndexOptions {
  name: string;
  dimension: number;
  spaceType?: SpaceType;
  M?: number;
  precision?: Precision;
  efCon?: number;
  version?: number;
  sparseDimension?: number;
}

Property	Type	Required	Description
`name`	`string`	Yes	Unique name for the index
`dimension`	`number`	Yes	Vector dimensionality (must match embedding model output)
`spaceType`	`SpaceType`	No	Distance metric (`'cosine'`, `'l2'`, or `'ip'`)
`M`	`number`	No	Graph connectivity parameter (default: 16)
`precision`	`Precision`	No	Quantization precision (default: `Precision.INT8D`)
`efCon`	`number`	No	Construction-time quality parameter (default: 128)
`version`	`number`	No	Index version
`sparseDimension`	`number`	No	Sparse vector dimension for hybrid indexes

Example:


const options: CreateIndexOptions = {
  name: 'documents',
  dimension: 384,
  spaceType: 'cosine',
  precision: Precision.INT8D,
  M: 16,
  efCon: 128,
};
 
await client.createIndex(options);

VectorItem

Represents a vector to be upserted into an index.


interface VectorItem {
  id: string;
  vector: number[];
  sparseIndices?: number[];
  sparseValues?: number[];
  meta?: Record<string, unknown>;
  filter?: Record<string, unknown>;
}

Property	Type	Required	Description
`id`	`string`	Yes	Unique identifier for the vector
`vector`	`number[]`	Yes	Dense embedding vector
`sparseIndices`	`number[]`	No	Non-zero term positions for hybrid search
`sparseValues`	`number[]`	No	Weights for each sparse index
`meta`	`Record<string, unknown>`	No	Arbitrary metadata object
`filter`	`Record<string, unknown>`	No	Key-value pairs for filtering during queries

For hybrid indexes, sparseIndices and sparseValues must have the same length, and values in sparseIndices must be within [0, sparseDimension).

Example:


const vectors: VectorItem[] = [
  {
    id: 'doc1',
    vector: [0.1, 0.2, 0.3, ...],
    meta: { title: 'Document 1' },
    filter: { category: 'tech' },
  },
  {
    id: 'doc2',
    vector: [0.4, 0.5, 0.6, ...],
    sparseIndices: [10, 50, 200],
    sparseValues: [0.8, 0.5, 0.3],
    meta: { title: 'Document 2' },
  },
];
 
await index.upsert(vectors);

QueryOptions

Options for querying an index.


interface QueryOptions {
  vector?: number[];
  topK: number;
  filter?: Array<Record<string, unknown>> | null;
  ef?: number;
  includeVectors?: boolean;
  sparseIndices?: number[];
  sparseValues?: number[];
}

Property	Type	Required	Description
`vector`	`number[]`	No	Dense query vector
`topK`	`number`	Yes	Number of results to return (max: 512)
`filter`	`Array<Record<string, unknown>> \| null`	No	Filter conditions (combined with AND)
`ef`	`number`	No	Search quality parameter (default: 128, max: 1024)
`includeVectors`	`boolean`	No	Include vector data in results (default: false)
`sparseIndices`	`number[]`	No	Sparse query positions for hybrid search
`sparseValues`	`number[]`	No	Sparse query weights for hybrid search

For hybrid queries, you can provide vector only (dense search), sparseIndices/sparseValues only (sparse search), or all three (hybrid search).

Example:


const options: QueryOptions = {
  vector: [0.15, 0.25, ...],
  topK: 10,
  ef: 128,
  includeVectors: true,
  filter: [
    { category: { $eq: 'tech' } },
    { score: { $range: [80, 100] } },
  ],
};
 
const results = await index.query(options);

QueryResult

Represents a single result from a query.


interface QueryResult {
  id: string;
  similarity: number;
  distance: number;
  meta?: Record<string, unknown>;
  filter?: Record<string, unknown>;
  norm?: number;
  vector?: number[];
}

Property	Type	Description
`id`	`string`	Vector identifier
`similarity`	`number`	Similarity score (higher is more similar)
`distance`	`number`	Distance value (lower is more similar)
`meta`	`Record<string, unknown>`	Metadata attached to the vector
`filter`	`Record<string, unknown>`	Filter fields attached to the vector
`norm`	`number`	Vector norm value
`vector`	`number[]`	Vector data (only if `includeVectors: true`)

Example:


const results: QueryResult[] = await index.query({
  vector: [...],
  topK: 5,
});
 
for (const result of results) {
  console.log(`ID: ${result.id}`);
  console.log(`Similarity: ${result.similarity}`);
  console.log(`Meta: ${JSON.stringify(result.meta)}`);
}

IndexInfo

Detailed information about an index returned from the server.


interface IndexInfo {
  name: string;
  spaceType: SpaceType;
  dimension: number;
  total_elements?: number;
  precision: Precision;
  M?: number;
  checksum?: number;
  libToken?: string;
  version?: number;
  sparseDimension?: number;
}

Property	Type	Description
`name`	`string`	Index name
`spaceType`	`SpaceType`	Distance metric
`dimension`	`number`	Vector dimensionality
`total_elements`	`number`	Total number of vectors in the index
`precision`	`Precision`	Quantization precision
`M`	`number`	Graph connectivity parameter
`checksum`	`number`	Index checksum
`libToken`	`string`	Library token
`version`	`number`	Index version
`sparseDimension`	`number`	Sparse vector dimension (for hybrid indexes)

IndexDescription

Simplified description of an index returned by index.describe().


interface IndexDescription {
  name: string;
  spaceType: SpaceType;
  dimension: number;
  isHybrid: boolean;
  count: number;
  precision: Precision;
  M: number;
  sparseDimension?: number;
}

Property	Type	Description
`name`	`string`	Index name
`spaceType`	`SpaceType`	Distance metric
`dimension`	`number`	Vector dimensionality
`isHybrid`	`boolean`	Whether the index supports hybrid search
`count`	`number`	Number of vectors in the index
`precision`	`Precision`	Quantization precision
`M`	`number`	Graph connectivity parameter
`sparseDimension`	`number`	Sparse vector dimension (for hybrid indexes)

Example:


const info: IndexDescription = index.describe();
 
console.log(`Index: ${info.name}`);
console.log(`Vectors: ${info.count}`);
console.log(`Hybrid: ${info.isHybrid}`);

VectorInfo

Detailed information about a single vector returned by index.getVector().


interface VectorInfo {
  id: string;
  meta: Record<string, unknown>;
  filter: Record<string, unknown>;
  norm: number;
  vector: number[];
}

Property	Type	Description
`id`	`string`	Vector identifier
`meta`	`Record<string, unknown>`	Metadata attached to the vector
`filter`	`Record<string, unknown>`	Filter fields attached to the vector
`norm`	`number`	Vector norm value
`vector`	`number[]`	The full vector data

Example:


const vectorInfo: VectorInfo = await index.getVector('doc1');
 
console.log(`ID: ${vectorInfo.id}`);
console.log(`Norm: ${vectorInfo.norm}`);
console.log(`Meta: ${JSON.stringify(vectorInfo.meta)}`);

Type Summary

Type	Kind	Description
`SpaceType`	Type Alias	Distance metric options
`Precision`	Enum	Quantization precision levels
`CreateIndexOptions`	Interface	Index creation parameters
`VectorItem`	Interface	Vector for upserting
`QueryOptions`	Interface	Query parameters
`QueryResult`	Interface	Single query result
`IndexInfo`	Interface	Detailed index information
`IndexDescription`	Interface	Simplified index description
`VectorInfo`	Interface	Single vector information