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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Database
✓ import { Database } from 'cosmotype'
✗ import Database from 'cosmotype'
The primary class for database interaction is a named export.
EntitySchemaDefinition
✓ import type { EntitySchemaDefinition } from 'cosmotype'
✗ import { EntitySchemaDefinition } from 'cosmotype'
This is a type definition for the schema used in `database.extend()`. Always import types using `import type` for clarity and better tree-shaking.
DriverOptions
✓ import type { DriverOptions } from 'cosmotype'
✗ const DriverOptions = require('cosmotype').DriverOptions
Type definition for database connection options. Cosmotype is primarily designed for modern ESM TypeScript environments.
Demonstrates connecting to a MySQL database, defining a user schema, and performing create and get operations with type safety.
import { Database } from 'cosmotype';
import type { EntitySchemaDefinition } from 'cosmotype';
interface User {
id: number;
name: string;
age: number;
money: number;
}
async function runCosmotypeExample() {
const database = new Database();
// Ensure you have @cosmotype/driver-mysql installed and a MySQL server running
// For demonstration, we'll use a placeholder for environment variables.
try {
await database.connect('mysql', {
host: process.env.DB_HOST ?? 'localhost',
port: parseInt(process.env.DB_PORT ?? '3306'),
user: process.env.DB_USER ?? 'root',
password: process.env.DB_PASSWORD ?? 'password',
database: process.env.DB_NAME ?? 'cosmotype_db',
});
console.log('Connected to MySQL database.');
const userSchema: EntitySchemaDefinition = {
id: 'number',
name: 'string',
age: 'number',
money: { type: 'number', initial: 100 }
};
database.extend<User>('user', userSchema, {
primary: 'id',
autoInc: true,
});
console.log('User schema extended.');
const newUser = await database.create<User>('user', {
name: 'Alice',
age: 30,
});
console.log('Created new user:', newUser);
const retrievedUser = await database.get<User>('user', { id: newUser.id });
console.log('Retrieved user:', retrievedUser);
} catch (error) {
console.error('Cosmotype example failed:', error);
} finally {
// In a real application, you'd likely disconnect or keep the connection alive.
// await database.disconnect();
console.log('Example finished.');
}
}
runCosmotypeExample();
Errors
Common errors & fixes
Error: Driver 'mysql' not found.
The required database driver package (e.g., `@cosmotype/driver-mysql`) was not installed or is not resolvable.
fixInstall the correct driver package: `npm install @cosmotype/driver-mysql` (replace 'mysql' with your desired driver).
Error: Connect failed: Access denied for user '...'@'localhost' (using password: YES)
Incorrect database connection credentials (username, password) or insufficient user permissions.
fixVerify your database host, port, user, password, and database name. Ensure the user has necessary permissions on the database.
Error: Duplicate entry '1' for key 'user.PRIMARY'
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.
fixEnsure `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.
Audit
Dependencies
@cosmotype/driver-mysqloptionalRequired for MySQL, MariaDB database connectivity.
@cosmotype/driver-mongooptionalRequired for MongoDB database connectivity.
@cosmotype/driver-sqliteoptionalRequired for SQLite database connectivity.
@cosmotype/driver-leveloptionalRequired for LevelDB database connectivity.
@cosmotype/driver-memoryoptionalRequired for in-memory database functionality, useful for testing.