marsdb

library0.6.11jsnpmunverified

MarsDB is a lightweight client-side database inspired by Meteor's minimongo implementation, providing a MongoDB-like API for JavaScript environments. It offers a Promise-based interface, observable cursors, and reactive joins, making it well-suited for applications requiring real-time data reactivity. Written in ES6, it operates across various JavaScript platforms including browsers, Electron, NW.js, and Node.js. The current stable version is 0.6.11. The project appears to be in a maintenance phase, with recent activity primarily focused on bug fixes rather than significant new feature development. Its key differentiators include a flexible pluggable storage architecture (supporting in-memory, LocalStorage, LevelUP, and even MongoDB wrappers), a powerful pipeline for data transformation, and compatibility with a wide range of MongoDB query and modifier operations.

database

npm install marsdb

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MARSDB

marsdb

databasejavascriptv0.6.11

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Collection

✓ import Collection from 'marsdb';

✗ import { Collection } from 'marsdb'; const Collection = require('marsdb').Collection;

Collection is the default export of the 'marsdb' package. Prior to v0.3.7, ESM import syntax might have been inconsistent.

Polyfills (side effect)

✓ import 'marsdb/polyfills';

✗ import { polyfills } from 'marsdb'; const polyfills = require('marsdb').polyfills;

For non-ES6 environments (e.g., older browsers, Node.js without specific flags), this side-effect import is necessary to provide global `Promise`, `Set`, and `Symbol` implementations.

Demonstrates creating a MarsDB collection, inserting multiple documents, performing find operations with filters and sorting, and updating a document, all using the Promise-based API.

import Collection from 'marsdb'; async function runMarsDBExample() { // Create a new collection named 'users' const users = new Collection('users'); // Clear existing data for a clean run await users.remove({}); // Insert documents const insertResult = await users.insert([ { _id: '1', name: 'Alice', age: 30, city: 'New York' }, { _id: '2', name: 'Bob', age: 24, city: 'Los Angeles' }, { _id: '3', name: 'Charlie', age: 30, city: 'Chicago' }, { _id: '4', name: 'Diana', age: 28, city: 'New York' } ]); console.log(`Inserted ${insertResult.length} users.`); // Find users aged 30 const agedThirty = await users.find({ age: 30 }).fetch(); console.log('Users aged 30:', agedThirty); // Find users in New York, sorted by name const nyUsers = await users.find({ city: 'New York' }) .sort({ name: 1 }) .fetch(); console.log('Users in New York (sorted):', nyUsers); // Update Alice's age await users.update({ name: 'Alice' }, { $set: { age: 31 } }); const updatedAlice = await users.findOne({ name: 'Alice' }); console.log('Updated Alice:', updatedAlice); // In a real application, observable cursors would react to changes. // For a quickstart, we just fetch all current users. const allUsers = await users.find({}).fetch(); console.log('All current users:', allUsers); } runMarsDBExample().catch(console.error);

Debug

Known issues

breakingThe `static` and `method` methods were removed from the Collection class. The internal Document wrapping of objects was also removed for performance improvements.

fix

Remove usages of `static` and `method`. Direct object manipulation is now standard. Adjust code that relied on `Document` wrapping.

affects: >=0.5.0

breakingThe `count()` and `ids()` methods of a Cursor no longer return direct values (a number or an array of IDs) but now return observable cursors themselves.

fix

To retrieve the actual value, you must now call `.fetch()` on the result, e.g., `await users.find({}).count().fetch()`.

affects: >=0.5.0

breakingCore storage implementations (e.g., LevelUP, LocalStorage) and the AngularJS binding were refactored into separate, dedicated npm packages (e.g., `marsdb-levelup`, `marsdb-angular`). They are no longer bundled with the main `marsdb` package.

fix

Install the specific plugin packages you need (e.g., `npm install marsdb-levelup`) and import them separately from `marsdb`.

affects: >=0.4.0

gotchaModifying a Cursor object while it is actively executing (e.g., changing its query or sort parameters) will throw an error. This is to prevent inconsistent states.

fix

Ensure the cursor is not executing by awaiting its `whenNotExecuting()` method before applying changes: `await cursor.whenNotExecuting(); cursor.sort({ name: 1 });`

affects: >=0.3.10

gotchaFor JavaScript environments that lack native ES6 features like `Promise`, `Set`, and `Symbol`, the `marsdb/polyfills` module must be explicitly imported to provide these globals.

fix

Add `import 'marsdb/polyfills';` (ESM) or `require('marsdb/polyfills');` (CommonJS) at the entry point of your application, before any MarsDB usage.

affects: >=0.3.0

Errors

Common errors & fixes

ReferenceError: Promise is not defined

Running MarsDB in an environment that lacks native Promise support (e.g., older browsers or Node.js without specific flags) without including the necessary polyfills.

fix

Add `import 'marsdb/polyfills';` or `require('marsdb/polyfills');` at the top of your main application file to ensure Promises are available.

TypeError: users.count is not a function

Attempting to call `.count()` on a cursor and expecting a direct number return value. Since v0.5.0, `count()` returns another observable cursor, not the number directly.

fix

Chain `.fetch()` to the `count()` call to retrieve the actual number: `await users.find({}).count().fetch()`.

Error: Cursor is executing, cannot modify

A MarsDB Cursor object was modified (e.g., its query or sorting parameters were changed) while it was actively processing a previous data operation.

fix

Use the `whenNotExecuting()` method to safely queue changes: `await cursor.whenNotExecuting(); cursor.sort({ name: 1 });`

TypeError: Cannot read property 'setStorageManager' of undefined

Attempting to use a storage manager like `LocalForageManager` without installing and importing the corresponding `marsdb-localforage` package.

fix

Install the specific storage plugin (e.g., `npm install marsdb-localforage`) and import it separately, then apply it to your collection: `import LocalForageManager from 'marsdb-localforage'; const users = new Collection('users', { StorageManager: LocalForageManager });`

Upgrade

Version history

0.6.11latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/c58/marsdb ↗

packagehttps://www.npmjs.com/package/marsdb ↗

homepagehttp://www.marsdb.org ↗