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.
Datastore
✓ import { Datastore } from 'tedb';
✗ const Datastore = require('tedb').Datastore;
Primary class for interacting with the database. CommonJS `require` works but `import` is preferred for TypeScript projects.
Cursor
✓ import { Cursor } from 'tedb';
✗ import * as tedb from 'tedb'; const cursor = new tedb.Cursor();
Used for chaining queries and operations. Named import is standard.
range
✓ import { range } from 'tedb';
A utility function moved into `tedb-utils` and re-exported. Many other utilities like `isEmpty`, `getDate` are also available as named imports.
* as tedb
✓ import * as tedb from 'tedb';
✗ import tedb from 'tedb';
Useful for accessing all exported members when you prefer a namespace approach, rather than individual named imports. TeDB does not offer a default export.
Demonstrates initializing a TeDB Datastore with a custom in-memory storage driver, inserting, finding, updating, and removing documents, and the recommended `sanitize` operation.
import { Datastore } from 'tedb';
// A minimal in-memory storage driver example
class InMemoryStorageDriver {
private data: Map<string, any> = new Map();
constructor(private collectionName: string) {}
async read(key: string): Promise<any> { return this.data.get(key); }
async write(key: string, value: any): Promise<boolean> { this.data.set(key, value); return true; }
async remove(key: string): Promise<boolean> { return this.data.delete(key); }
async exists(key: string): Promise<boolean> { return this.data.has(key); }
async getAllKeys(): Promise<string[]> { return Array.from(this.data.keys()); }
}
async function runDbExample() {
const storageDriver = new InMemoryStorageDriver('myCollection');
const db = new Datastore({
storage: storageDriver,
collection: 'myCollection'
});
// Load any existing data (for persistent drivers)
await db.loadDatabase();
// Insert a document
const doc1 = await db.insert({ name: 'Alice', age: 30 });
console.log('Inserted doc1:', doc1);
// Find documents
const foundDocs = await db.find({ age: { $gt: 25 } }).exec();
console.log('Found docs (age > 25):', foundDocs);
// Update a document
const updatedCount = await db.update({ _id: doc1._id }, { $set: { age: 31 } });
console.log('Updated documents count:', updatedCount);
// Find the updated document
const updatedDoc = await db.findOne({ _id: doc1._id }).exec();
console.log('Updated doc1:', updatedDoc);
// Remove a document and sanitize indices
const removedCount = await db.remove({ _id: doc1._id });
console.log('Removed documents count:', removedCount);
await db.sanitize(); // Recommended after remove
const allDocs = await db.find({}).exec();
console.log('All remaining docs:', allDocs);
}
runDbExample().catch(console.error);
Errors
Common errors & fixes
RangeError: Maximum call stack size exceeded
This error, especially on database load, indicates that the `binary-type-tree` index structure has become corrupted or excessively large due to a bug in older versions that caused endless appending to non-unique indices.
fixUpgrade TeDB to version 0.5.0 or higher. If the problem persists with existing data, you may need to manually inspect and potentially rebuild your database indices, or restore from a backup.
Query results are incorrect or missing when using $gt, $gte, $lt, $lte, $ne on date fields.
Date objects are compared lexicographically or in unexpected ways if not stored as numerical timestamps, leading to inaccurate range queries.
fixEnsure all date fields in your documents are stored as `number` (e.g., `new Date().getTime()`). When querying, convert your comparison dates to timestamps as well (e.g., `{ dateField: { $gt: new Date('2023-01-01').getTime() } }`). Documents appear in query results after being removed, or index doesn't reflect actual data state.
After `remove` operations, the in-memory indices might still hold references to keys that no longer exist in the underlying storage if `sanitize()` is not called.
fixAlways call `await datastore.sanitize()` after performing `remove` operations to ensure the indices are synchronized with the actual data in your storage driver.
Audit
Dependencies
tedb-utilsrequiredCommon utility methods moved to this package as of v0.5.0 for reusability across TeDB-related projects.
binary-type-treerequiredUnderlying AVL balanced binary tree implementation used for indexing documents.