Cosmotype Database Framework

Common errors

• Error: Driver 'mysql' not found.

  cause The required database driver package (e.g., `@cosmotype/driver-mysql`) was not installed or is not resolvable.
  fix Install 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)

  cause Incorrect database connection credentials (username, password) or insufficient user permissions.
  fix Verify 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'

  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.
  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.

Warnings

• gotcha 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.
  Fix: Ensure `npm install @cosmotype/driver-<database-name>` is run for each database type your application connects to.
• breaking 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.
  Fix: Consult the official migration guides and documentation when upgrading to a new major version.
• gotcha 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.
  Fix: Familiarize yourself with the native capabilities and constraints of your specific database system, even when using Cosmotype's abstraction layer.

Install

• npm install cosmotype npm
• yarn add cosmotype yarn
• pnpm add cosmotype pnpm

Imports

• Database
  wrong:

  import Database from 'cosmotype'

  correct:

  import { Database } from 'cosmotype'

  The primary class for database interaction is a named export.
• EntitySchemaDefinition
  wrong:

  import { EntitySchemaDefinition } from 'cosmotype'

  correct:

  import type { 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
  wrong:

  const DriverOptions = require('cosmotype').DriverOptions

  correct:

  import type { DriverOptions } from 'cosmotype'

  Type definition for database connection options. Cosmotype is primarily designed for modern ESM TypeScript environments.

Quickstart

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();