{"id":17591,"library":"endee","title":"Endee TypeScript Vector Database Client","description":"Endee is a TypeScript client library for interacting with the local Endee vector database server. It provides full type safety, modern ES module support, and optimized utilities for performing Approximate Nearest Neighbor (ANN) searches on vector data. Currently at version 1.7.0, it supports various distance metrics (cosine, L2, inner product), hybrid indexes combining dense and sparse vectors, and allows attaching metadata for filtering queries. The library prioritizes high performance and efficient similarity searches, offering a robust interface for vector database operations like index creation, vector upsertion, and querying. While there isn't a specified release cadence, client updates typically align with server capabilities, ensuring compatibility and leveraging new features, especially regarding its encrypted vector database capabilities.","status":"active","version":"1.7.0","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","vector","database","client","typescript","encrypted","ann","similarity-search"],"install":[{"cmd":"npm install endee","lang":"bash","label":"npm"},{"cmd":"yarn add endee","lang":"bash","label":"yarn"},{"cmd":"pnpm add endee","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"The Endee client library requires a running Endee local server instance to connect to and perform vector database operations. This is a crucial runtime dependency, not an `npm` package.","package":"Endee Local server","optional":false}],"imports":[{"note":"The Endee client library is designed for modern JavaScript environments, explicitly supporting ES Modules (ESM). Native ESM import is the recommended approach for Node.js >= 18.","wrong":"const Endee = require('endee');","symbol":"Endee","correct":"import { Endee } from 'endee';"},{"note":"Precision is an enum for quantization options, directly exported. Use named imports for specific exports rather than importing the entire namespace.","wrong":"import * as endee from 'endee'; const p = endee.Precision;","symbol":"Precision","correct":"import { Precision } from 'endee';"},{"note":"VectorData is a TypeScript type definition used for describing the structure of vectors during upsert operations. Use `import type` to ensure it's a type-only import, which is tree-shakeable and has no runtime impact.","wrong":"import { VectorData } from 'endee';","symbol":"VectorData","correct":"import type { VectorData } from 'endee';"}],"quickstart":{"code":"import { Endee, Precision } from 'endee';\n\nconst authToken = process.env.NDD_AUTH_TOKEN ?? ''; // Use environment variable for auth token if set\nconst client = new Endee(authToken);\n\n// Optionally set a custom base URL if your server is not on the default host/port\n// client.setBaseUrl('http://0.0.0.0:8081/api/v1');\n\nasync function runEndeeDemo() {\n  const indexName = 'my_test_vectors';\n  const vectorDimension = 384; // Matches common embedding models like mini-LM\n\n  try {\n    // Attempt to delete the index first for idempotency, ignore if it doesn't exist\n    await client.deleteIndex(indexName);\n    console.log(`Successfully deleted existing index: ${indexName}`);\n  } catch (error: any) {\n    if (error.message.includes('not found')) {\n      console.log(`Index ${indexName} does not exist, proceeding to create.`);\n    } else {\n      console.error(`Error deleting index ${indexName}:`, error.message);\n    }\n  }\n\n  console.log(`Creating a new index: ${indexName}`);\n  await client.createIndex({\n    name: indexName,\n    dimension: vectorDimension,\n    spaceType: 'cosine',\n    precision: Precision.INT16,\n  });\n  console.log(`Index '${indexName}' created successfully.`);\n\n  const index = await client.getIndex(indexName);\n\n  console.log('Upserting example vectors...');\n  await index.upsert([\n    {\n      id: 'doc1',\n      vector: Array.from({ length: vectorDimension }, () => Math.random() * 2 - 1),\n      meta: { title: 'First Document', author: 'Alice' },\n      filter: { category: 'technology' },\n    },\n    {\n      id: 'doc2',\n      vector: Array.from({ length: vectorDimension }, () => Math.random() * 2 - 1),\n      meta: { title: 'Second Document', author: 'Bob' },\n      filter: { category: 'science' },\n    },\n    {\n      id: 'doc3',\n      vector: Array.from({ length: vectorDimension }, () => Math.random() * 2 - 1),\n      meta: { title: 'Third Document', author: 'Charlie' },\n      filter: { category: 'technology' },\n    },\n  ]);\n  console.log('Vectors upserted successfully.');\n\n  console.log('Querying the index for similar vectors...');\n  const queryVector = Array.from({ length: vectorDimension }, () => Math.random() * 2 - 1);\n  const queryResults = await index.query({\n    vector: queryVector,\n    topK: 2,\n    includeMetadata: true,\n    filter: { category: 'technology' } // Example filter\n  });\n  console.log('Query Results:', JSON.stringify(queryResults, null, 2));\n\n  console.log('Endee client demo finished.');\n}\n\nrunEndeeDemo().catch(error => {\n  console.error('An error occurred during the Endee demo:', error);\n  process.exit(1);\n});","lang":"typescript","description":"This quickstart demonstrates how to initialize the Endee client, create a new vector index with specified parameters, upsert multiple vectors along with their metadata, and perform a filtered similarity search on the index."},"warnings":[{"fix":"Ensure the Endee Local server process is running. Verify the client's base URL configuration (`client.setBaseUrl()`) matches the server's listening address and port.","message":"The Endee client library requires a separate, running Endee Local server. All operations will fail with connection-related errors (e.g., `ECONNREFUSED`) if the server is not active or is unreachable.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Update your Node.js environment to version 18.0.0 or a newer LTS release. Tools like `nvm` (Node Version Manager) can simplify this process.","message":"Endee client versions 1.0.0 and above mandate Node.js 18.0.0 or higher. This requirement is due to the adoption of modern JavaScript features and native ES module support.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"When initializing the client, pass the correct `NDD_AUTH_TOKEN` string: `new Endee('your-secret-token')`. Ensure any environment variable (`process.env.NDD_AUTH_TOKEN`) is correctly set if you are relying on that.","message":"If your Endee Local server is secured with an `NDD_AUTH_TOKEN`, the client *must* be initialized with the identical token. Mismatched or absent tokens will lead to 'Authentication failed' errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always confirm that the `dimension` parameter (and `sparseDimension` if applicable) during index creation exactly corresponds to the output dimension of your embedding model or vector source.","message":"The `dimension` (and `sparseDimension` for hybrid indexes) specified during `createIndex` must precisely match the dimensionality of the vectors you intend to upsert. Inconsistent dimensions will cause upsert and query failures.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Start the Endee Local server. If the server is running on a non-default address or port, configure the client using `client.setBaseUrl('http://your-server:port/api/v1');`.","cause":"The Endee client could not establish a connection to the Endee Local server, typically because the server is not running or is listening on a different address/port.","error":"Error: connect ECONNREFUSED 127.0.0.1:8080"},{"fix":"Initialize the Endee client with the correct authentication token string, e.g., `new Endee(process.env.NDD_AUTH_TOKEN || 'your-auth-token');`. Ensure the token matches the server's `NDD_AUTH_TOKEN` setting.","cause":"The Endee Local server is configured with an authentication token, but the client either provided an incorrect token or no token at all.","error":"Error: Authentication failed."},{"fix":"Choose a unique name for the new index, or explicitly delete the existing index (`await client.deleteIndex('my_index_name');`) before attempting to recreate it.","cause":"An attempt was made to create an index using a name that is already in use by an existing index within the Endee database.","error":"Error: Index 'my_index_name' already exists."},{"fix":"Add robust error handling around `client.createIndex` and `client.getIndex` calls to ensure an index object is successfully retrieved before attempting operations like `upsert()` or `query()`.","cause":"This usually indicates that the `index` variable is `undefined`. This happens if `await client.getIndex('non_existent_index')` failed to retrieve an index, or if `client.createIndex` did not complete successfully before `getIndex` was called.","error":"TypeError: Cannot read properties of undefined (reading 'upsert')"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}