{"id":17230,"library":"forerunnerdb","title":"ForerunnerDB","description":"ForerunnerDB is a NoSQL JSON document database designed for both browser-based and Node.js applications, offering a MongoDB-like query language. The current stable version is 2.0.24, with a significant rewrite for version 3.0 actively under development in a separate repository (forerunnerdb-core). Key differentiators include its dual-environment support, advanced features like data views, joins, sub-queries, and collection groups, along with optional modules for AngularJS/Ionic integration, real-time data binding to the DOM (browser-only), persistent storage, data compression and encryption, and a built-in REST API server for Node.js. It is production-ready, battle-tested in applications serving millions of users daily, and maintained by Irrelon Software Limited. While no explicit release cadence is published, development is ongoing for the next major version.","status":"active","version":"2.0.24","language":"javascript","source_language":"en","source_url":"git://github.com/irrelon/ForerunnerDB","tags":["javascript","irrelon","forerunnerdb","forerunner","database","nosql","mongodb","document"],"install":[{"cmd":"npm install forerunnerdb","lang":"bash","label":"npm"},{"cmd":"yarn add forerunnerdb","lang":"bash","label":"yarn"},{"cmd":"pnpm add forerunnerdb","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"ForerunnerDB is exported as a default export in CommonJS; for ESM, use a default import. Version 2.x predominantly uses CommonJS.","wrong":"import { ForerunnerDB } from 'forerunnerdb';","symbol":"ForerunnerDB","correct":"import ForerunnerDB from 'forerunnerdb';"},{"note":"CommonJS is the standard module system for ForerunnerDB v2.x and earlier Node.js environments.","symbol":"ForerunnerDB","correct":"const ForerunnerDB = require('forerunnerdb');"},{"note":"After importing the constructor, you must instantiate it with `new` and then call the `.db()` method to get a database instance.","wrong":"const db = require('forerunnerdb').db('myDbName');","symbol":"db instance","correct":"const fdb = new ForerunnerDB();\nconst db = fdb.db('myDbName');"}],"quickstart":{"code":"import ForerunnerDB from 'forerunnerdb';\n\ninterface User { \n  _id?: string; \n  name: string; \n  age: number; \n  city: string; \n}\n\n// Initialize ForerunnerDB and get a database instance\nconst fdb = new ForerunnerDB();\nconst db = fdb.db('myApplicationDB');\n\n// To enable persistence in Node.js, specify a path\n// ForerunnerDB also supports localStorage in browsers automatically\nif (typeof window === 'undefined') { // Node.js environment\n  const path = require('path');\n  db.persist.dataDir(path.resolve(__dirname, 'data'));\n}\n\nasync function runDbOperations() {\n  // Load existing data if any\n  await db.load();\n  console.log('Database loaded.');\n\n  // Get or create a collection\n  const users = db.collection<User>('users');\n\n  // Clear collection for a clean start (optional)\n  users.remove({});\n\n  // Insert some documents\n  const insertedUsers = await users.insert([\n    { name: 'Alice', age: 30, city: 'New York' },\n    { name: 'Bob', age: 24, city: 'London' },\n    { name: 'Charlie', age: 30, city: 'Paris' },\n    { name: 'David', age: 28, city: 'New York' }\n  ]);\n  console.log('Inserted users:', insertedUsers.length);\n\n  // Find all users\n  const allUsers = users.find();\n  console.log('All users:', allUsers);\n\n  // Find users older than 25\n  const olderUsers = users.find({ age: { '$gt': 25 } });\n  console.log('Users older than 25:', olderUsers);\n\n  // Update a user\n  await users.update({ name: 'Bob' }, { $set: { age: 25, city: 'Berlin' } });\n  const updatedBob = users.find({ name: 'Bob' });\n  console.log('Updated Bob:', updatedBob);\n\n  // Save the database state\n  await db.save();\n  console.log('Database saved.');\n\n  // Demonstrate a View (virtual collection)\n  const nyUsersView = db.view('nyUsersView')\n    .from('users')\n    .query({ city: 'New York' });\n\n  console.log('Users in New York (via View):', nyUsersView.find());\n}\n\nrunDbOperations().catch(console.error);\n","lang":"typescript","description":"This quickstart demonstrates the initialization of ForerunnerDB, creating a collection, inserting, querying (including comparisons), updating documents, and saving/loading the database state with basic persistence. It also shows a simple View creation."},"warnings":[{"fix":"Monitor the `forerunnerdb-core` repository for updates and migration guides as v3.0 approaches release. Plan for a substantial refactor if upgrading from 2.x to 3.x.","message":"ForerunnerDB 3.0 is a complete rewrite being developed in a separate repository (`irrelon/forerunnerdb-core`). It is built with a modular architecture and is expected to introduce significant breaking changes, although specific migration paths are not yet defined as it's still in active development. Do not expect direct compatibility with 2.x APIs.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Always call `await db.load()` at application startup to retrieve previous data. Implement strategic `await db.save()` calls after critical data modifications, or use a debounced save mechanism if frequent writes occur.","message":"Persistence in ForerunnerDB v2.x requires explicit `db.load()` and `db.save()` calls. Data is not automatically saved on every change, and forgetting to call `db.save()` will result in data loss upon application shutdown or page refresh.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Consult the documentation for each optional module you intend to use. Ensure you've initialized and configured them correctly, e.g., `db.persist.dataDir('/path/to/data')` for Node.js persistence.","message":"Optional features like data binding, persistence, and the REST server are modules that must be explicitly loaded or configured. For example, persistence needs a `dataDir` configured in Node.js.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Use `const fdb = new ForerunnerDB();` to instantiate the database constructor.","cause":"Attempting to call `ForerunnerDB()` directly without the `new` keyword.","error":"TypeError: ForerunnerDB is not a constructor"},{"fix":"First, instantiate ForerunnerDB with `new ForerunnerDB()`, then call `.db('yourDbName')` on the instance to get a database object: `const fdb = new ForerunnerDB(); const db = fdb.db('myDb');`","cause":"Attempting to call `.collection()` directly on the imported `ForerunnerDB` constructor without first getting a database instance via `fdb.db()`.","error":"TypeError: Cannot read properties of undefined (reading 'collection')"},{"fix":"Ensure the directory specified in `db.persist.dataDir('/your/path')` exists and that your Node.js process has read/write permissions to it. Create the directory manually if necessary.","cause":"In Node.js, the configured `dataDir` for persistence either does not exist, or the application lacks write permissions to that directory.","error":"Error: unable to load data (Path does not exist / permission denied)"}],"ecosystem":"npm","meta_description":null}