cosa

library10.1.0jsnpmunverified

Cosa is a simplified object modeling library for MongoDB, providing a lightweight abstraction over the MongoDB Node.js driver. The current stable version is 10.1.0, released under the MIT license, with an active maintenance status. It offers a clean, schema-based model definition API with built-in validation and query helpers, focusing on developer productivity without the overhead of a full ODM like Mongoose. The library supports ESM only, requires Node.js >=20, and is built on top of the official MongoDB driver.

database

npm install cosa

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · COSA

cosa

databasejavascriptv10.1.0

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.

Model

✓ import { Model } from 'cosa'

✗ const Model = require('cosa')

Cosa is ESM-only since v10; CommonJS require() will fail.

Model

✓ import { Model } from 'cosa'

✗ import Model from 'cosa'

Model is a named export, not a default export. Using default import yields undefined.

Model.define

✓ const UserModel = Model.define({ name: 'UserModel', ... })

✗ const UserModel = new Model(...)

Model.define is a static factory method; Model is not a constructor.

Model.define

✓ const UserModel = Model.define({ name: 'UserModel', ... })

✗ const UserModel = Model.define('UserModel', { ... })

Model.define expects a single options object, not separate arguments.

Demonstrates connecting to MongoDB, defining a model, creating and saving a document, and querying all documents.

import { Model } from 'cosa'; import { MongoClient } from 'mongodb'; // Connect to MongoDB const client = new MongoClient(process.env.MONGO_URI ?? 'mongodb://localhost:27017'); await client.connect(); const db = client.db('test'); // Define a model const UserModel = Model.define({ name: 'UserModel', collection: 'users', properties: { name: { type: 'string', required: true }, email: { type: 'string', required: true, email: true } } }); // Use model to create and save a document const newUser = UserModel.create({ name: 'John Smith', email: 'jsmith@example.com' }); await newUser.save(); console.log('User saved:', newUser.toJSON()); // Find users const users = await UserModel.find({}, { array: true }); console.log('Users:', users); await client.close();

Debug

Known issues

breakingVersion 10 dropped CommonJS support; the package is now ESM-only.

fix

Use import syntax and ensure Node.js >=20. If using CommonJS, consider transpilation or stay on v9.

affects: >=10.0.0

breakingModel.define now requires Node.js >=20; older versions are unsupported.

fix

Upgrade Node.js to >=20 or pin to a previous version (e.g., 9.x) if unable.

affects: >=10.0.0

deprecatedThe .save() method on model instances may be deprecated in future in favor of explicit collection operations.

fix

Consider using Model.create() or direct MongoDB driver operations for more explicit control.

affects: >=1.0.0

gotchaModel.find() with { array: true } returns plain objects, not Model instances, losing attached methods.

fix

If you need Model methods, avoid { array: true } and iterate over cursor manually.

affects: >=1.0.0

gotchaModel properties with 'email: true' only validate format; they don't enforce uniqueness.

fix

Add a unique index on the email field in MongoDB for duplicate prevention.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: cosa_1.Model is not a constructor

Using `new Model()` instead of `Model.define()`

fix

Replace `const m = new Model(...)` with `const m = Model.define(...)`

ERR_REQUIRE_ESM: require() of ES Module /path/to/cosa/index.js from /path/to/your-file.js not supported.

Using CommonJS require() with ESM-only package

fix

Change require('cosa') to import { Model } from 'cosa' and ensure Node.js >=20 or add a build step.

Import 'Model' not found in 'cosa'

Using default import instead of named import

fix

Replace `import Model from 'cosa'` with `import { Model } from 'cosa'`

TypeError: Model.define is not a function

Importing wrong export or using older version without define method

fix

Ensure you are importing { Model } and using version >=1.0.0. In ancient versions, use `Model.createModel()` instead.

Upgrade

Version history

10.1.0latest on npm

Audit

Dependencies

mongodbrequiredCosa relies on the MongoDB Node.js driver for database connectivity and operations

Agent activity

10 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/Losant/cosa ↗

packagecosa ↗

homepagehttps://github.com/Losant/cosa#readme ↗