Registry / database / minimongo

minimongo

JSON →
library0.2.8jsnpmunverified

Minimongo is a client-side, in-memory MongoDB clone designed for browser and Node.js environments, offering a MongoDB-like API for CRUD operations and query syntax. It supports various local storage backends including IndexedDB, WebSQL (legacy), LocalStorage, and a purely in-memory option, with an autoselection utility. Currently at version 7.1.1, the project aims for stable releases without a strict public cadence, evolving from a 2014 fork of Meteor.js's minimongo package to incorporate more geospatial queries and npm-friendliness. Its key differentiators include hybrid local/remote synchronization with conflict resolution using base documents, replication between database instances, and support for Extended JSON (EJSON). While it offers a substantial subset of MongoDB query features, it does not support the full aggregation pipeline or all operators.

npm install minimongo
INSTALL
IMPORT
SIG · MINIMONGO
M
minimongo
databasejavascriptv0.2.8
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

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

MemoryDb
import { MemoryDb } from 'minimongo';
const MemoryDb = require('minimongo').MemoryDb;
Minimongo primarily uses ESM imports for modern JavaScript environments. CommonJS `require` might work in some bundler setups but is not the recommended or officially documented approach.
IndexedDb
import { IndexedDb } from 'minimongo';
const IndexedDb = require('minimongo').IndexedDb;
A named import for the IndexedDB storage backend. Note that the constructor is callback-based.
HybridDb
import { HybridDb } from 'minimongo';
import HybridDb from 'minimongo'; // Incorrect default import
HybridDb is a named export. Ensure to use destructuring for import.
utils
import { utils } from 'minimongo';
import * as utils from 'minimongo'; // Not explicitly documented, might import more than needed const utils = require('minimongo').utils;
The `utils` object containing helper functions like `autoselectLocalDb` is a named export.

This quickstart demonstrates initializing an IndexedDb locally, setting up a mock RemoteDb, creating a HybridDb for combined local/remote operations, and performing basic CRUD and queries with synchronization.

import { IndexedDb, HybridDb, RemoteDb, MemoryDb } from 'minimongo'; interface MyDocument { _id?: string; name: string; age: number; tags?: string[]; } async function setupDatabase() { return new Promise<IndexedDb<MyDocument>>((resolve, reject) => { const indexedDb = new IndexedDb<MyDocument>( { namespace: 'myAppDb', autoCreate: true }, () => { console.log('IndexedDb initialized successfully.'); resolve(indexedDb); }, (error: Error) => { console.error('IndexedDb initialization failed:', error); reject(error); } ); }); } async function runApp() { try { const localDb = await setupDatabase(); const remoteDb = new RemoteDb('/api/collections', 'myAppDb', { // For a real application, replace with a proper HTTP client // This is a minimal mock for demonstration httpClient: { get: async (url: string) => { console.log(`[RemoteDb] GET ${url}`); if (url.includes('myAppDb/items')) { return { status: 200, data: [{ _id: 'remote1', name: 'Remote Item', age: 30 }] }; } return { status: 404, data: { message: 'Not Found' } }; }, put: async (url: string, data: any) => { console.log(`[RemoteDb] PUT ${url}`, data); return { status: 200, data: { ...data, _id: data._id || 'newRemoteId' } }; } }, useQuickFind: true }); const hybridDb = new HybridDb(localDb, remoteDb); hybridDb.addCollection('items'); const itemsCollection = hybridDb.getCollection('items'); // Insert a document locally const newItem: MyDocument = { name: 'Local Item', age: 25, tags: ['frontend'] }; await itemsCollection.upsert(newItem, null, (doc: MyDocument) => { console.log('Inserted local item:', doc); }); // Query local and remote (hybrid sync) console.log('\nQuerying all items (local and remote sync):'); itemsCollection.find({}).fetch((docs: MyDocument[]) => { console.log('Found items:', docs); }); // Demonstrate another local operation const anotherItem: MyDocument = { name: 'Another Item', age: 40 }; await itemsCollection.upsert(anotherItem, null, (doc: MyDocument) => { console.log('Inserted another local item:', doc); }); // Query with selector console.log('\nQuerying items with age > 25:'); itemsCollection.find({ age: { $gt: 25 } }).fetch((docs: MyDocument[]) => { console.log('Found items (age > 25):', docs); }); } catch (error) { console.error('Application failed:', error); } } runApp();
Debug
Known issues
gotchaMinimongo's MongoDB query language support is partial, lacking full aggregation pipeline, `findAndModify`, `map/reduce`, and some specific modifiers like `$pull` with certain selectors. Developers should consult the documentation for supported operators to avoid unexpected query behavior.
fix
Thoroughly test query selectors against Minimongo's capabilities. For unsupported operations, consider performing data manipulation client-side after fetching or implementing server-side logic.
affects: >=1.0.0
deprecatedWebSQL is a deprecated browser technology. While Minimongo offers a WebSQLDb backend, its use is discouraged for new applications and may lead to compatibility issues or removal in future browser versions.
fix
Prefer using the IndexedDb backend for persistent storage in modern browsers. MemoryDb or LocalStorageDb can be used for simpler, less data-intensive persistence needs.
affects: >=1.0.0
gotchaThe `IndexedDb` constructor (and potentially other async operations) uses Node.js-style callbacks (`success`, `error`) rather than modern Promises or async/await. This can be a source of confusion for developers accustomed to Promise-based asynchronous patterns.
fix
Wrap callback-based APIs in Promises for easier integration with `async/await` patterns or explicitly use callbacks as demonstrated in the documentation.
affects: >=1.0.0
gotchaWhen using `HybridDb` for synchronization, conflict resolution relies on 'base documents' provided during `upsert` operations. Incorrectly supplying or omitting base documents can lead to unintended data overwrites or sync issues.
fix
Understand and correctly implement the base document concept for `upsert` operations, especially in multi-user or multi-client environments, to ensure proper conflict resolution. Review the documentation on hybrid sync and conflict handling.
affects: >=1.0.0
gotchaMinimongo, having forked from Meteor.js's minimongo in 2014, may have API differences or behavioral nuances compared to the current official Meteor `minimongo` package. Developers familiar with Meteor's ecosystem should be aware that this standalone package is independently maintained.
fix
Refer exclusively to the `mWater/minimongo` documentation for this specific package. Avoid assuming direct API parity with Meteor's integrated Minimongo.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: collection.find(...).fetch is not a function
The `find` method returns a cursor-like object. To retrieve documents, you must call `.fetch()` on the cursor, usually with a callback.
fix
Ensure you call `.fetch()` on the result of `find()` and provide a callback, e.g., `collection.find(selector).fetch((docs) => { /* handle docs */ });`.
Uncaught DOMException: Failed to execute 'open' on 'IDBFactory': The database connection is already open, or there is a pending upgrade transaction.
Attempting to initialize IndexedDb multiple times or with conflicting options without properly closing previous connections, or a previous operation is still pending.
fix
Ensure that `IndexedDb` is initialized only once per namespace, or handle database closing and reopening carefully. Check for pending transactions or other open connections.
Error: Unsupported query operator: $someUnsupportedOperator
Minimongo only implements a subset of MongoDB's query operators and aggregation features. The operator used is not supported by this library.
fix
Refactor your query to use only the supported logical, comparison, element, and array operators listed in Minimongo's documentation. Complex logic may need to be implemented in client-side code after fetching data.
ReferenceError: require is not defined
This error occurs in modern browser environments or Node.js projects configured for ESM, when attempting to use CommonJS `require()` syntax. Minimongo is primarily designed for ESM imports.
fix
Use ES module `import` syntax (e.g., `import { NamedExport } from 'minimongo';`) instead of `require()`. Ensure your project's `package.json` specifies `"type": "module"` or that files use `.mjs` extension for ESM.
Upgrade
Version history
0.2.8latest on npm
Audit
Dependencies
cordova-sqlite-storageoptionalOptional plugin for SQLite storage backend in hybrid mobile environments.
Agent activity
9 hits · last 30 days
node
8
Resources