Minato Database Framework

Common errors

• Error: Cannot find module '@minatojs/driver-mysql' or its corresponding type declarations.

  cause The specific database driver package was not installed.
  fix Install the required driver: `npm install @minatojs/driver-mysql` (replace `mysql` with your database).

• TypeError: minato_1.default is not a constructor

  cause Attempting to instantiate `Database` using named import syntax when it's a default export.
  fix Change your import statement from `import { Database } from 'minato'` to `import Database from 'minato'`.

• Error: EACCES: permission denied, open '/var/run/mysqld/mysqld.sock'

  cause The application lacks necessary permissions to connect to the database socket or the database server is not running or misconfigured.
  fix Ensure your database server is running and accessible from your application's environment. Check database user permissions and connection string details. For local development, verify Docker containers are running or local services are active.

• Error: No database driver provided.

  cause The `connect` method was called without passing a database driver (e.g., `MySQLDriver`).
  fix Pass the appropriate imported driver to the `connect` method: `await database.connect(MySQLDriver, config)`.

Warnings

• breaking Minato v4 introduces significant breaking changes from v3, particularly in API interfaces for database operations, schema definitions, and internal driver implementations. Users upgrading from v3 should carefully review the official migration guide (if available) or anticipate necessary code adjustments.
  Fix: Consult the official Minato v4 release notes and documentation for specific migration instructions. Update method calls and schema definitions accordingly.
• gotcha Minato requires separate driver packages (e.g., `@minatojs/driver-mysql`, `@minatojs/driver-mongodb`) for each database type. Forgetting to install the specific driver for your target database will result in runtime errors.
  Fix: Ensure you install the correct driver package using `npm install @minatojs/driver-<database-name>` in addition to `minato` itself.
• gotcha While Minato simplifies database interactions, complex data access patterns (e.g., deep nested relations, large joins) can still lead to N+1 query problems or inefficient database calls if not optimized. Always be mindful of the generated queries.
  Fix: Utilize Minato's query builder features, population options, and careful schema design to minimize the number of database queries. Profile your application's database interactions in development.
• gotcha Minato leverages TypeScript's powerful type inference. However, incorrect schema definitions or complex query constructs can sometimes lead to obscure TypeScript errors. Ensuring your types align with the actual database structure is crucial.
  Fix: Double-check your `database.extend` calls for accurate type mappings. Utilize IDE features for type hints and ensure your TypeScript configuration (`tsconfig.json`) is correctly set up for the project.
• gotcha The `cordis` package is a peer dependency in Minato v4. If you plan to use Minato within a Cordis application context, you must explicitly install `cordis` to avoid runtime errors related to missing modules or incompatible versions.
  Fix: Install `cordis` in your project: `npm install cordis`. Ensure its version is compatible with the `cordis` peer dependency range specified by Minato.

Install

• npm install minato npm
• yarn add minato yarn
• pnpm add minato pnpm

Imports

• Database
  wrong:

  import { Database } from 'minato'

  correct:

  import Database from 'minato'

  The main Database class is exported as a default export.
• MySQLDriver

  import MySQLDriver from '@minatojs/driver-mysql'

  Database drivers are provided as separate packages and typically exported as default exports from their respective modules. Replace 'mysql' with your desired driver (e.g., 'mongodb', 'sqlite').
• Schema Definition (method)

  database.extend('collectionName', { /* schema */ })

  Schemas are typically defined by calling the `extend` method on an instantiated `Database` object, not by importing a separate `Schema` class.

Quickstart

This quickstart demonstrates how to initialize Minato, define a type-safe schema, connect to a MySQL database using a separate driver, and perform common CRUD (Create, Read, Update, Delete) operations.

import Database from 'minato';
import MySQLDriver from '@minatojs/driver-mysql';
import type { Context } from 'cordis'; // Optional, if using Cordis

interface User {
  id: number;
  name: string;
  age: number;
  email?: string;
}

async function runMinatoExample() {
  // For Cordis integration, you might pass a Context, otherwise, it's optional.
  // const ctx = new Context();
  // const database = new Database(ctx); 
  const database = new Database();

  // Define the schema for the 'user' collection/table
  database.extend('user', {
    id: 'unsigned', // Auto-incrementing primary key
    name: 'string',
    age: 'integer',
    email: { type: 'string', nullable: true, unique: true },
  }, {
    primary: 'id',
    autoInc: true,
  });

  // Connect to the database
  try {
    await database.connect(MySQLDriver, {
      host: 'localhost',
      port: 3306,
      user: 'root',
      password: process.env.DB_PASSWORD ?? '', // Use environment variable for sensitive info
      database: 'minato_test_db',
    });
    console.log('Successfully connected to MySQL database.');

    // Basic CRUD operations
    // Create
    const newUser = await database.create('user', {
      name: 'Alice',
      age: 30,
      email: 'alice@example.com',
    });
    console.log('Created user:', newUser);

    // Find
    const users = await database.get('user', { age: { $gt: 25 } });
    console.log('Users older than 25:', users);

    // Update
    await database.set('user', { id: newUser.id }, { age: 31 });
    const updatedUser = await database.get('user', { id: newUser.id });
    console.log('Updated user:', updatedUser[0]);

    // Delete
    await database.remove('user', { id: newUser.id });
    console.log('Deleted user with ID:', newUser.id);

  } catch (error) {
    console.error('Database operation failed:', error);
  } finally {
    await database.disconnect();
    console.log('Disconnected from database.');
  }
}

runMinatoExample();