Quick Start

This guide walks you through creating a database, inserting documents, querying them, and performing basic updates — everything you need to get productive quickly.

1. Create a Database

The first step is to create an instance of JSONDB. You pass a folder path where the data will be stored.

const { JSONDB } = require('low-json-db');
// or: const { JSONDB } = require('./db');

const db = new JSONDB('./data');

If the folder ./data does not exist, it will be created automatically.

2. Create a Collection

A collection is like a table. You can create one with a simple string or with an options object.

// Simple way
const users = db.collection('users');

// With options (recommended)
const users = db.collection({
  name: 'users',
  autoId: true,               // automatically add _id
  indexes: ['email'],         // create an index on email
  pretty: true                // readable JSON files
});

3. Insert Documents

// Insert one document
const user = users.insert({
  name: 'Alice',
  email: 'alice@example.com',
  age: 28,
  city: 'Lagos'
});

console.log(user);
// {
//   name: 'Alice',
//   email: 'alice@example.com',
//   age: 28,
//   city: 'Lagos',
//   _id: 1
// }

// Insert many documents
users.insertMany([
  { name: 'Bob', email: 'bob@example.com', age: 34, city: 'Abuja' },
  { name: 'Carol', email: 'carol@example.com', age: 22, city: 'Lagos' }
]);

4. Query Documents

// Find all documents
const all = users.find().toArray();

// Find with a filter
const adults = users.find({ age: { $gte: 18 } }).toArray();

// Find one document (uses index if available)
const alice = users.findOne({ email: 'alice@example.com' });

// Chaining: sort + limit + projection
const page = users
  .find({ city: 'Lagos' })
  .sort({ age: -1 })
  .limit(10)
  .project({ name: 1, age: 1, email: 1 })
  .toArray();

5. Update Documents

// Update one document
users.updateOne(
  { name: 'Alice' },
  {
    $set: { age: 29, city: 'Port Harcourt' },
    $push: { tags: 'admin' }
  }
);

// Update many documents
users.updateMany(
  { city: 'Lagos' },
  { $inc: { age: 1 } }
);

6. Delete Documents

// Delete one
users.deleteOne({ name: 'Carol' });

// Delete many
users.deleteMany({ age: { $lt: 18 } });

7. Using Async Methods

Every method has an async version. This is recommended for servers and applications that need non-blocking I/O.

const user = await users.insertAsync({
  name: 'David',
  email: 'david@example.com'
});

const found = await users.findOneAsync({ email: 'david@example.com' });

await users.updateOneAsync(
  { name: 'David' },
  { $set: { verified: true } }
);

Complete Minimal Example

const { JSONDB } = require('low-json-db');

async function main() {
  const db = new JSONDB('./data');

  const users = db.collection({
    name: 'users',
    autoId: true,
    indexes: ['email']
  });

  // Insert
  await users.insertAsync({
    name: 'Alice',
    email: 'alice@example.com',
    age: 28
  });

  // Query
  const user = await users.findOneAsync({ email: 'alice@example.com' });
  console.log(user);

  // Update
  await users.updateOneAsync(
    { email: 'alice@example.com' },
    { $set: { age: 29 } }
  );

  // Count
  console.log('Total users:', users.find().count());
}

main().catch(console.error);