TeDB: TypeScript Embedded Database

Common errors

• RangeError: Maximum call stack size exceeded

  cause 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.
  fix Upgrade 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.

  cause Date objects are compared lexicographically or in unexpected ways if not stored as numerical timestamps, leading to inaccurate range queries.
  fix Ensure 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.

  cause 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.
  fix Always call `await datastore.sanitize()` after performing `remove` operations to ensure the indices are synchronized with the actual data in your storage driver.

Warnings

• gotcha When querying with date fields using comparison operators like `$gt`, `$gte`, `$lt`, or `$lte`, dates must be saved as numbers (e.g., using `Date.prototype.getTime()`) to ensure proper comparison within the index.
  Fix: When storing dates, save them as `dateObject.getTime()`. When querying, convert comparison dates to timestamps using `new Date().getTime()`.
• breaking Older versions (prior to 0.5.0) of TeDB had a major bug in the underlying `binary-type-tree` which could cause endless appending to non-unique indices, leading to stack overflows upon loading the index after sufficient data accumulation.
  Fix: Upgrade TeDB to version 0.5.0 or newer to get the fix. Rebuilding indices might be necessary if data corruption occurred.
• gotcha After removing documents, indices might retain references to non-existent keys. It is recommended to call `datastore.sanitize()` to clean up these orphaned index entries.
  Fix: Explicitly call `await datastore.sanitize()` after performing `remove` operations to ensure index integrity and prevent potential issues with querying or memory usage.
• gotcha In versions prior to 0.2.16, attempting to update a document by matching on its own `_id` could incorrectly cause the document to be removed from indices before the update was applied, leading to data inconsistencies.
  Fix: Upgrade TeDB to version 0.2.16 or newer. If on an older version, avoid updating by matching on the same `_id` and ensure `sanitize()` is run regularly.

Install

• npm install tedb npm
• yarn add tedb yarn
• pnpm add tedb pnpm

Imports

• Datastore
  wrong:

  const Datastore = require('tedb').Datastore;

  correct:

  import { Datastore } from 'tedb';

  Primary class for interacting with the database. CommonJS `require` works but `import` is preferred for TypeScript projects.
• Cursor
  wrong:

  import * as tedb from 'tedb'; const cursor = new tedb.Cursor();

  correct:

  import { Cursor } from 'tedb';

  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
  wrong:

  import tedb from 'tedb';

  correct:

  import * as 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.

Quickstart

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);