Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Endee
✓ import { Endee } from 'endee';
✗ const Endee = require('endee');
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.
Precision
✓ import { Precision } from 'endee';
✗ import * as endee from 'endee'; const p = endee.Precision;
Precision is an enum for quantization options, directly exported. Use named imports for specific exports rather than importing the entire namespace.
VectorData
✓ import type { VectorData } from 'endee';
✗ import { VectorData } from 'endee';
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.
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.
import { Endee, Precision } from 'endee';
const authToken = process.env.NDD_AUTH_TOKEN ?? ''; // Use environment variable for auth token if set
const client = new Endee(authToken);
// Optionally set a custom base URL if your server is not on the default host/port
// client.setBaseUrl('http://0.0.0.0:8081/api/v1');
async function runEndeeDemo() {
const indexName = 'my_test_vectors';
const vectorDimension = 384; // Matches common embedding models like mini-LM
try {
// Attempt to delete the index first for idempotency, ignore if it doesn't exist
await client.deleteIndex(indexName);
console.log(`Successfully deleted existing index: ${indexName}`);
} catch (error: any) {
if (error.message.includes('not found')) {
console.log(`Index ${indexName} does not exist, proceeding to create.`);
} else {
console.error(`Error deleting index ${indexName}:`, error.message);
}
}
console.log(`Creating a new index: ${indexName}`);
await client.createIndex({
name: indexName,
dimension: vectorDimension,
spaceType: 'cosine',
precision: Precision.INT16,
});
console.log(`Index '${indexName}' created successfully.`);
const index = await client.getIndex(indexName);
console.log('Upserting example vectors...');
await index.upsert([
{
id: 'doc1',
vector: Array.from({ length: vectorDimension }, () => Math.random() * 2 - 1),
meta: { title: 'First Document', author: 'Alice' },
filter: { category: 'technology' },
},
{
id: 'doc2',
vector: Array.from({ length: vectorDimension }, () => Math.random() * 2 - 1),
meta: { title: 'Second Document', author: 'Bob' },
filter: { category: 'science' },
},
{
id: 'doc3',
vector: Array.from({ length: vectorDimension }, () => Math.random() * 2 - 1),
meta: { title: 'Third Document', author: 'Charlie' },
filter: { category: 'technology' },
},
]);
console.log('Vectors upserted successfully.');
console.log('Querying the index for similar vectors...');
const queryVector = Array.from({ length: vectorDimension }, () => Math.random() * 2 - 1);
const queryResults = await index.query({
vector: queryVector,
topK: 2,
includeMetadata: true,
filter: { category: 'technology' } // Example filter
});
console.log('Query Results:', JSON.stringify(queryResults, null, 2));
console.log('Endee client demo finished.');
}
runEndeeDemo().catch(error => {
console.error('An error occurred during the Endee demo:', error);
process.exit(1);
});
Errors
Common errors & fixes
Error: connect ECONNREFUSED 127.0.0.1:8080
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.
fixStart 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');`. Error: Authentication failed.
The Endee Local server is configured with an authentication token, but the client either provided an incorrect token or no token at all.
fixInitialize 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.
Error: Index 'my_index_name' already exists.
An attempt was made to create an index using a name that is already in use by an existing index within the Endee database.
fixChoose a unique name for the new index, or explicitly delete the existing index (`await client.deleteIndex('my_index_name');`) before attempting to recreate it. TypeError: Cannot read properties of undefined (reading 'upsert')
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.
fixAdd 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()`.
Audit
Dependencies
Endee Local serverrequiredThe 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.