TingoDB

Common errors

• TypeError: require('tingodb').Db is not a constructor

  cause Attempting to access the `Db` constructor directly from the `tingodb` module without invoking the factory function.
  fix The `tingodb` module exports a function that must be called to return the object containing the `Db` constructor. Use `const Db = require('tingodb')().Db;`

• MongoError: Unsupported operator: $someNewOperator

  cause Using MongoDB query operators or commands that were introduced in versions of MongoDB beyond 1.4.x, which TingoDB does not support.
  fix Consult MongoDB 1.4.x documentation to ensure all queries and operations are compatible with that specific API level. Rewrite queries to use supported operators.

• Error: ENOENT: no such file or directory, open '/nonexistent/path/tingodb.db'

  cause TingoDB is configured to use a filesystem path for storage, but the specified directory does not exist or the application lacks write permissions.
  fix Ensure the directory specified in `new Db('/some/local/path', {})` exists and is writable by the Node.js process, or handle directory creation before initializing the database.

Warnings

• breaking The `apiLevel` configuration parameter was introduced in version 0.6.x. Its default value of `140` (for MongoDB API 1.4.x compatibility) means behavior, such as `findAndModify` return values, might differ if not explicitly set, especially when aiming for experimental 2.x API behavior using `apiLevel: 200`.
  Fix: Explicitly set `apiLevel` in the factory function call, e.g., `require('tingodb')({ apiLevel: 140 })` to ensure consistent behavior with MongoDB 1.4.x, or `apiLevel: 200` for 2.x behaviors.
• gotcha TingoDB is explicitly compatible with MongoDB's v1.4 API level. Many features, commands, or query operators introduced in later MongoDB versions (e.g., 2.x, 3.x, or modern versions) are not supported. Using TingoDB as a drop-in for newer MongoDB drivers will lead to unexpected errors or unsupported operations.
  Fix: Ensure your application only uses MongoDB features and API calls available in MongoDB version 1.4.x. If newer features are required, a full MongoDB instance is necessary.
• gotcha The `require('tingodb')` call does not directly return the module object with classes. Instead, it returns a factory function that must be invoked (`require('tingodb')()`) to get the usable module object containing constructors like `Db`.
  Fix: Always call the required module as a function: `const TingoDBModule = require('tingodb')();` before accessing `TingoDBModule.Db`.
• gotcha As an embedded, in-process database, TingoDB lacks network capabilities, replication, sharding, or advanced security features inherent to a full MongoDB server. It's designed for local storage or in-memory operations, not as a networked database server.
  Fix: TingoDB is suitable for lightweight, local data persistence. For networked, scalable, or production-grade database solutions, a full MongoDB deployment is required.

Install

• npm install tingodb npm
• yarn add tingodb yarn
• pnpm add tingodb pnpm

Imports

• Db
  wrong:

  const { Db } = require('tingodb');
  const Db = require('tingodb').Db;

  correct:

  const Db = require('tingodb')().Db;

  The `tingodb` module exports a factory function, which must be invoked to obtain the object containing the `Db` constructor.
• tingodb (factory function)
  wrong:

  import tingodbFactory from 'tingodb';

  correct:

  const tingodbFactory = require('tingodb');
  // Usage: const { Db } = tingodbFactory({ apiLevel: 140 });

  The direct `require('tingodb')` call returns a function (the factory) that takes configuration options and returns the module object with classes like `Db`.
• Collection

  // Collection instances are obtained from a Db object:
  // const collection = db.collection('mycollection');

  The `Collection` object is not directly imported but instantiated via `db.collection()`. This entry serves to highlight that common MongoDB-like objects are accessed through the `Db` instance rather than direct imports, consistent with MongoDB Node.js driver's 1.x API.

Quickstart

Demonstrates initializing TingoDB to a local file path, creating a collection, inserting multiple documents, and querying for them, mirroring MongoDB's v1.4 API behavior.

const Db = require('tingodb')().Db,
	assert = require('assert');

const dbPath = process.env.TINGODB_PATH || './data'; // Specify a path for persistent storage

// Initialize Db. The second argument is for options, e.g., { apiLevel: 200 }
const db = new Db(dbPath, {});

// Fetch a collection to insert documents into
const collection = db.collection("batch_document_insert_collection_safe");

// Insert multiple documents
collection.insert([{hello:'world_safe1'}, {hello:'world_safe2'}], {w:1}, function(err, result) {
  assert.equal(null, err);
  console.log('Inserted documents:', result);

  // Fetch a document
  collection.findOne({hello:'world_safe2'}, function(err, item) {
	assert.equal(null, err);
	console.log('Found item:', item);
	assert.equal('world_safe2', item.hello);

    // Example of finding all documents
    collection.find({}).toArray(function(err, docs) {
        assert.equal(null, err);
        console.log('All documents:', docs);
        // In a real app, you'd close the DB connection here if it's not reused
    });
  });
});