{"id":42545,"library":"cosa","title":"Cosa","description":"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.","status":"active","version":"10.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/Losant/cosa","tags":["javascript"],"install":[{"cmd":"npm install cosa","lang":"bash","label":"npm"},{"cmd":"yarn add cosa","lang":"bash","label":"yarn"},{"cmd":"pnpm add cosa","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Cosa relies on the MongoDB Node.js driver for database connectivity and operations","package":"mongodb","optional":false}],"imports":[{"note":"Cosa is ESM-only since v10; CommonJS require() will fail.","wrong":"const Model = require('cosa')","symbol":"Model","correct":"import { Model } from 'cosa'"},{"note":"Model is a named export, not a default export. Using default import yields undefined.","wrong":"import Model from 'cosa'","symbol":"Model","correct":"import { Model } from 'cosa'"},{"note":"Model.define is a static factory method; Model is not a constructor.","wrong":"const UserModel = new Model(...)","symbol":"Model.define","correct":"const UserModel = Model.define({ name: 'UserModel', ... })"},{"note":"Model.define expects a single options object, not separate arguments.","wrong":"const UserModel = Model.define('UserModel', { ... })","symbol":"Model.define","correct":"const UserModel = Model.define({ name: 'UserModel', ... })"}],"quickstart":{"code":"import { Model } from 'cosa';\nimport { MongoClient } from 'mongodb';\n\n// Connect to MongoDB\nconst client = new MongoClient(process.env.MONGO_URI ?? 'mongodb://localhost:27017');\nawait client.connect();\nconst db = client.db('test');\n\n// Define a model\nconst UserModel = Model.define({\n  name: 'UserModel',\n  collection: 'users',\n  properties: {\n    name: { type: 'string', required: true },\n    email: { type: 'string', required: true, email: true }\n  }\n});\n\n// Use model to create and save a document\nconst newUser = UserModel.create({\n  name: 'John Smith',\n  email: 'jsmith@example.com'\n});\nawait newUser.save();\nconsole.log('User saved:', newUser.toJSON());\n\n// Find users\nconst users = await UserModel.find({}, { array: true });\nconsole.log('Users:', users);\n\nawait client.close();","lang":"javascript","description":"Demonstrates connecting to MongoDB, defining a model, creating and saving a document, and querying all documents."},"warnings":[{"fix":"Use import syntax and ensure Node.js >=20. If using CommonJS, consider transpilation or stay on v9.","message":"Version 10 dropped CommonJS support; the package is now ESM-only.","severity":"breaking","affected_versions":">=10.0.0"},{"fix":"Upgrade Node.js to >=20 or pin to a previous version (e.g., 9.x) if unable.","message":"Model.define now requires Node.js >=20; older versions are unsupported.","severity":"breaking","affected_versions":">=10.0.0"},{"fix":"Consider using Model.create() or direct MongoDB driver operations for more explicit control.","message":"The .save() method on model instances may be deprecated in future in favor of explicit collection operations.","severity":"deprecated","affected_versions":">=1.0.0"},{"fix":"If you need Model methods, avoid { array: true } and iterate over cursor manually.","message":"Model.find() with { array: true } returns plain objects, not Model instances, losing attached methods.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Add a unique index on the email field in MongoDB for duplicate prevention.","message":"Model properties with 'email: true' only validate format; they don't enforce uniqueness.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'10.1.0':25 '20':74 'abstract':14 'activ':33 'api':45 'base':42 'built':48,77 'built-in':47 'clean':39 'cosa':1,2 'current':21 'definit':44 'develop':56 'driver':19,84 'esm':70 'focus':54 'full':63 'helper':53 'javascript':85 'librari':8,68 'licens':30 'lightweight':13 'like':65 'mainten':34 'mit':29 'model':7,43 'mongodb':10,17,83 'mongoos':66 'node.js':18,73 'object':6 'odm':64 'offer':37 'offici':82 'overhead':60 'product':57 'provid':11 'queri':52 'releas':26 'requir':72 'schema':41 'schema-bas':40 'simplifi':5 'stabl':22 'status':35 'support':69 'top':79 'valid':50 'version':23 'without':58","created_at":"2026-06-05T16:55:30.515180+00:00","updated_at":"2026-06-05T16:55:30.515180+00:00","problems":[{"fix":"Replace `const m = new Model(...)` with `const m = Model.define(...)`","cause":"Using `new Model()` instead of `Model.define()`","error":"TypeError: cosa_1.Model is not a constructor"},{"fix":"Change require('cosa') to import { Model } from 'cosa' and ensure Node.js >=20 or add a build step.","cause":"Using CommonJS require() with ESM-only package","error":"ERR_REQUIRE_ESM: require() of ES Module /path/to/cosa/index.js from /path/to/your-file.js not supported."},{"fix":"Replace `import Model from 'cosa'` with `import { Model } from 'cosa'`","cause":"Using default import instead of named import","error":"Import 'Model' not found in 'cosa'"},{"fix":"Ensure you are importing { Model } and using version >=1.0.0. In ancient versions, use `Model.createModel()` instead.","cause":"Importing wrong export or using older version without define method","error":"TypeError: Model.define is not a function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/Losant/cosa#readme","github":"https://github.com/Losant/cosa","docs":null,"changelog":null,"pypi":null,"npm":"cosa","openapi_spec":null,"status_page":null,"smithery":null,"categories":["database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-05","next_check":"2026-09-03","install_tag":null}}