mongo-object

library3.0.4jsnpmunverified

mongo-object provides a programmatic API for interacting with MongoDB documents and modifiers, simplifying operations like building query objects, applying modifiers, and validating document structures. The current stable version is 3.0.4, with regular updates from Long Shot Labs. It ships TypeScript types and is ESM-only since v3, requiring Node.js >=20. Key differentiators include a lightweight footprint, explicit support for MongoDB modifiers, and a focus on type safety.

database

npm install mongo-object

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MONGO-OBJECT

mongo-object

databasejavascriptv3.0.4

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

MongoObject

✓ import { MongoObject } from 'mongo-object'

✗ const MongoObject = require('mongo-object')

ESM-only since v3. CommonJS require will fail with ERR_REQUIRE_ESM.

default

✓ import mongoObject from 'mongo-object'

Default export is available for convenience, but named exports are recommended for TypeScript.

MongoObjectConfig

✓ import { MongoObjectConfig } from 'mongo-object'

Type export for configuration options, useful in TypeScript projects.

Demonstrates creating a MongoObject, getting/setting values, applying a $inc modifier, and serializing to JSON.

import { MongoObject } from 'mongo-object'; const doc = { name: 'Alice', age: 30 }; const obj = new MongoObject(doc); // Get a value by dot-notation path console.log(obj.getValue('name')); // 'Alice' // Set a value obj.setValue('age', 31); console.log(obj.toJSON()); // { name: 'Alice', age: 31 } // Apply a MongoDB modifier obj.applyModifier({ $inc: { age: 1 } }); console.log(obj.toJSON()); // { name: 'Alice', age: 32 } // Validate document against a schema (simplified placeholder) // const isValid = obj.validate({ age: { type: 'number' } });

Debug

Known issues

breakingVersion 3.0.0 drops CommonJS support; the package is ESM-only.

fix

Migrate to ESM (i.e., use import instead of require) and ensure Node.js >=20.

affects: >=3.0.0

breakingVersion 3.0.0 requires Node.js >=20.

fix

Upgrade Node.js to version 20 or later.

affects: >=3.0.0

deprecatedThe method `getValue` previously accepted a second `options` parameter; this is deprecated in v3.

fix

Use alternative approaches to pass options, or check documentation for newer API.

affects: >=3.0.0

gotchaSetting a value via `setValue` with a path that doesn't exist will create intermediate objects; this can lead to unintended mutation of the original document reference.

fix

Clone the document before passing if you need to preserve the original unchanged.

affects: *

gotchaThe constructor does not deep-clone the input document; mutations to the original object may affect the MongoObject instance.

fix

Pass a deep clone (e.g., structuredClone(doc)) if you want to isolate modifications.

affects: *

Errors

Common errors & fixes

ERR_REQUIRE_ESM

Trying to require an ESM-only package with CommonJS require().

fix

Use import syntax instead: import { MongoObject } from 'mongo-object' or set type: module in package.json.

TypeError: mongoObject is not a constructor

Using default import incorrectly or mixing named and default imports.

fix

Use named import: import { MongoObject } from 'mongo-object'.

TypeError: Cannot read properties of undefined (reading 'someKey')

Trying to access a nested property that doesn't exist via getValue without checking existence.

fix

Use optional chaining or check with hasKey before accessing: if (obj.hasKey('a.b.c')) { obj.getValue('a.b.c') }.

SyntaxError: Unexpected token 'export'

Using mongo-object in an environment that does not support ES modules (e.g., older Node.js or browser without bundler).

fix

Upgrade to Node.js >=20 or bundle with a tool like webpack/rollup that can handle ESM.

Upgrade

Version history

3.0.4latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/longshotlabs/mongo-object ↗

packagemongo-object ↗

homepagehttps://github.com/longshotlabs/mongo-object ↗