Async API

Almost every mutating and reading method has both a synchronous and an asynchronous version. The async versions return Promises and go through the collection’s internal lock/queue so concurrent writes stay safe.

Why both?

• Sync – simple scripts, CLI tools, startup code, tests.
• Async – web servers, Electron main process, any place where you must not block the event loop for long disk I/O.

Naming convention

Async methods end with Async:

How the lock works

Each collection maintains a boolean lock and a FIFO queue. When you call an async method:

1. If the lock is free, the operation runs immediately.
2. If the lock is held, the operation is pushed onto the queue.
3. When the current operation finishes, the next queued one starts.

This guarantees that two async writes on the same collection never interleave and corrupt part files or the index.

Examples

// Express-style route
app.post('/users', async (req, res) => {
  try {
    const user = await users.insertAsync(req.body);
    res.status(201).json(user);
  } catch (err) {
    res.status(500).json({ error: err.message });
  }
});

// Sequential async work
await users.insertAsync({ name: 'Alice' });
await users.insertAsync({ name: 'Bob' });
const all = await users.findAsync({});
console.log(all.toArray());

// Parallel inserts on *different* collections are fine
await Promise.all([
  users.insertAsync({ name: 'Carol' }),
  orders.insertAsync({ total: 49.99 })
]);

findAsync returns a QueryBuilder

findAsync resolves to a normal QueryBuilder. After that you still call the synchronous terminal methods (toArray, first, count):

const builder = await users.findAsync({ active: true });
const page = builder.sort({ name: 1 }).limit(20).toArray();

When to prefer sync

• Short-lived scripts that run to completion
• Unit tests
• Application bootstrap / seed data
• Any context where you already know you are the only writer