{"id":16318,"library":"cosmotype","title":"Cosmotype Database Framework","description":"Cosmotype is a type-driven database framework designed to offer a unified API for interacting with various database systems, abstracting away driver-specific complexities. It is built with TypeScript, providing comprehensive type support for schema definitions and operations, which helps in preventing common data-related errors at compile time. Currently at version 1.0.10, the project appears to be actively maintained, though no explicit release cadence is specified. A key differentiator is its ability to perform advanced database operations, akin to full SQL capabilities, even when interfacing with NoSQL databases like MongoDB or key-value stores like LevelDB, all through a consistent JavaScript/TypeScript API. This makes it highly versatile and extensible, supporting simultaneous access to different databases and even enabling low-code operations in browser environments.","status":"active","version":"1.0.10","language":"javascript","source_language":"en","source_url":"https://github.com/cosmotype/cosmotype","tags":["javascript","orm","database","typescript"],"install":[{"cmd":"npm install cosmotype","lang":"bash","label":"npm"},{"cmd":"yarn add cosmotype","lang":"bash","label":"yarn"},{"cmd":"pnpm add cosmotype","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for MySQL, MariaDB database connectivity.","package":"@cosmotype/driver-mysql","optional":true},{"reason":"Required for MongoDB database connectivity.","package":"@cosmotype/driver-mongo","optional":true},{"reason":"Required for SQLite database connectivity.","package":"@cosmotype/driver-sqlite","optional":true},{"reason":"Required for LevelDB database connectivity.","package":"@cosmotype/driver-level","optional":true},{"reason":"Required for in-memory database functionality, useful for testing.","package":"@cosmotype/driver-memory","optional":true}],"imports":[{"note":"The primary class for database interaction is a named export.","wrong":"import Database from 'cosmotype'","symbol":"Database","correct":"import { Database } from 'cosmotype'"},{"note":"This is a type definition for the schema used in `database.extend()`. Always import types using `import type` for clarity and better tree-shaking.","wrong":"import { EntitySchemaDefinition } from 'cosmotype'","symbol":"EntitySchemaDefinition","correct":"import type { EntitySchemaDefinition } from 'cosmotype'"},{"note":"Type definition for database connection options. Cosmotype is primarily designed for modern ESM TypeScript environments.","wrong":"const DriverOptions = require('cosmotype').DriverOptions","symbol":"DriverOptions","correct":"import type { DriverOptions } from 'cosmotype'"}],"quickstart":{"code":"import { Database } from 'cosmotype';\nimport type { EntitySchemaDefinition } from 'cosmotype';\n\ninterface User {\n  id: number;\n  name: string;\n  age: number;\n  money: number;\n}\n\nasync function runCosmotypeExample() {\n  const database = new Database();\n\n  // Ensure you have @cosmotype/driver-mysql installed and a MySQL server running\n  // For demonstration, we'll use a placeholder for environment variables.\n  try {\n    await database.connect('mysql', {\n      host: process.env.DB_HOST ?? 'localhost',\n      port: parseInt(process.env.DB_PORT ?? '3306'),\n      user: process.env.DB_USER ?? 'root',\n      password: process.env.DB_PASSWORD ?? 'password',\n      database: process.env.DB_NAME ?? 'cosmotype_db',\n    });\n    console.log('Connected to MySQL database.');\n\n    const userSchema: EntitySchemaDefinition = {\n      id: 'number',\n      name: 'string',\n      age: 'number',\n      money: { type: 'number', initial: 100 }\n    };\n\n    database.extend<User>('user', userSchema, {\n      primary: 'id',\n      autoInc: true,\n    });\n    console.log('User schema extended.');\n\n    const newUser = await database.create<User>('user', {\n      name: 'Alice',\n      age: 30,\n    });\n    console.log('Created new user:', newUser);\n\n    const retrievedUser = await database.get<User>('user', { id: newUser.id });\n    console.log('Retrieved user:', retrievedUser);\n\n  } catch (error) {\n    console.error('Cosmotype example failed:', error);\n  } finally {\n    // In a real application, you'd likely disconnect or keep the connection alive.\n    // await database.disconnect();\n    console.log('Example finished.');\n  }\n}\n\nrunCosmotypeExample();\n","lang":"typescript","description":"Demonstrates connecting to a MySQL database, defining a user schema, and performing create and get operations with type safety."},"warnings":[{"fix":"Ensure `npm install @cosmotype/driver-<database-name>` is run for each database type your application connects to.","message":"Cosmotype relies on separate driver packages for database connectivity. Forgetting to install the specific driver (e.g., `@cosmotype/driver-mysql` for MySQL) will result in runtime errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Consult the official migration guides and documentation when upgrading to a new major version.","message":"Major version updates of Cosmotype or its drivers may introduce changes to the API, particularly around schema definition syntax or driver options. Always review release notes for breaking changes.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Familiarize yourself with the native capabilities and constraints of your specific database system, even when using Cosmotype's abstraction layer.","message":"While Cosmotype aims to provide a unified API, underlying database-specific behaviors and limitations (e.g., transaction support, advanced indexing, specific data types) may still manifest. Developers should be aware of the chosen driver's capabilities.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Install the correct driver package: `npm install @cosmotype/driver-mysql` (replace 'mysql' with your desired driver).","cause":"The required database driver package (e.g., `@cosmotype/driver-mysql`) was not installed or is not resolvable.","error":"Error: Driver 'mysql' not found."},{"fix":"Verify your database host, port, user, password, and database name. Ensure the user has necessary permissions on the database.","cause":"Incorrect database connection credentials (username, password) or insufficient user permissions.","error":"Error: Connect failed: Access denied for user '...'@'localhost' (using password: YES)"},{"fix":"Ensure `autoInc` is set correctly for primary keys if you intend for them to be generated automatically, or handle unique constraint violations explicitly. Use `upsert` if you intend to create or update.","cause":"Attempting to create a record with a primary key value that already exists in the table without `autoInc` enabled or during an `upsert` operation that isn't configured to update.","error":"Error: Duplicate entry '1' for key 'user.PRIMARY'"}],"ecosystem":"npm"}