ForerunnerDB

Common errors

• TypeError: ForerunnerDB is not a constructor

  cause Attempting to call `ForerunnerDB()` directly without the `new` keyword.
  fix Use `const fdb = new ForerunnerDB();` to instantiate the database constructor.

• TypeError: Cannot read properties of undefined (reading 'collection')

  cause Attempting to call `.collection()` directly on the imported `ForerunnerDB` constructor without first getting a database instance via `fdb.db()`.
  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');`

• Error: unable to load data (Path does not exist / permission denied)

  cause In Node.js, the configured `dataDir` for persistence either does not exist, or the application lacks write permissions to that directory.
  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.

Warnings

• breaking 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install forerunnerdb npm
• yarn add forerunnerdb yarn
• pnpm add forerunnerdb pnpm

Imports

• ForerunnerDB
  wrong:

  import { ForerunnerDB } from 'forerunnerdb';

  correct:

  import ForerunnerDB from 'forerunnerdb';

  ForerunnerDB is exported as a default export in CommonJS; for ESM, use a default import. Version 2.x predominantly uses CommonJS.
• ForerunnerDB

  const ForerunnerDB = require('forerunnerdb');

  CommonJS is the standard module system for ForerunnerDB v2.x and earlier Node.js environments.
• db instance
  wrong:

  const db = require('forerunnerdb').db('myDbName');

  correct:

  const fdb = new ForerunnerDB();
  const db = fdb.db('myDbName');

  After importing the constructor, you must instantiate it with `new` and then call the `.db()` method to get a database instance.

Quickstart

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.

import ForerunnerDB from 'forerunnerdb';

interface User { 
  _id?: string; 
  name: string; 
  age: number; 
  city: string; 
}

// Initialize ForerunnerDB and get a database instance
const fdb = new ForerunnerDB();
const db = fdb.db('myApplicationDB');

// To enable persistence in Node.js, specify a path
// ForerunnerDB also supports localStorage in browsers automatically
if (typeof window === 'undefined') { // Node.js environment
  const path = require('path');
  db.persist.dataDir(path.resolve(__dirname, 'data'));
}

async function runDbOperations() {
  // Load existing data if any
  await db.load();
  console.log('Database loaded.');

  // Get or create a collection
  const users = db.collection<User>('users');

  // Clear collection for a clean start (optional)
  users.remove({});

  // Insert some documents
  const insertedUsers = await users.insert([
    { name: 'Alice', age: 30, city: 'New York' },
    { name: 'Bob', age: 24, city: 'London' },
    { name: 'Charlie', age: 30, city: 'Paris' },
    { name: 'David', age: 28, city: 'New York' }
  ]);
  console.log('Inserted users:', insertedUsers.length);

  // Find all users
  const allUsers = users.find();
  console.log('All users:', allUsers);

  // Find users older than 25
  const olderUsers = users.find({ age: { '$gt': 25 } });
  console.log('Users older than 25:', olderUsers);

  // Update a user
  await users.update({ name: 'Bob' }, { $set: { age: 25, city: 'Berlin' } });
  const updatedBob = users.find({ name: 'Bob' });
  console.log('Updated Bob:', updatedBob);

  // Save the database state
  await db.save();
  console.log('Database saved.');

  // Demonstrate a View (virtual collection)
  const nyUsersView = db.view('nyUsersView')
    .from('users')
    .query({ city: 'New York' });

  console.log('Users in New York (via View):', nyUsersView.find());
}

runDbOperations().catch(console.error);