🛡️ Corem

Lightweight, Type-safe MySQL ORM & Migration Tool for Modern TypeScript

npm version
TypeScript
License

Corem is a powerful, minimal, and fully type-safe ORM built specifically for TypeScript and MySQL. Inspired by modern tooling like Drizzle, it provides a fluent SQL-like query builder, strong schema inference, and seamless migration commands—all without the bloated overhead.

📚 Read the Official Documentation for in-depth guides, API reference, and examples!

✨ Features

• 🔒 End-to-End Type Safety - Catch errors at compile-time with strong TypeScript inference.
• 🚀 Fluent Query Builder - Write SQL intuitively with a simple, chainable API.
• 📦 Zero-Config Migrations - Automatically sync your schema to your database via CLI.
• 🔗 First-Class Relations - Easily manage foreign keys and perform typed SQL joins.
• 🪶 Lightweight & Fast - Minimal runtime footprint designed for high performance.
• 🛠️ Modern TypeScript - Built for ES Modules, standard TypeScript, and modern tooling.

---

📦 Installation

Install corem alongside its peer dependencies (such as mysql2 if you haven't already):

# Using npm
npm install @himanshupadecha/corem

# Using yarn
yarn add @himanshupadecha/corem

# Using pnpm
pnpm add @himanshupadecha/corem

---

🚀 Quick Start

1. Setup Environment Variables

Create a .env file in the root of your project:

DB_HOST=localhost
DB_USER=root
DB_PASSWORD=password
DB_NAME=my_database

2. Configure Corem

Create a corem.config.ts file in your project root to tell the CLI where your schema lives and how to connect to the database.

import { defineConfig } from "@himanshupadecha/corem/config";

export default defineConfig({
  schema: "src/db/schema.ts",
  database: "mysql",
  credentials: {
    db_name: process.env.DB_NAME!,
    host: process.env.DB_HOST!,
    password: process.env.DB_PASSWORD!,
    user: process.env.DB_USER!,
  },
});

3. Define Your Schema

Define your tables using Corem's type-safe schema builder. Create src/db/schema.ts:

import { int, varchar, text, timestamp } from "@himanshupadecha/corem";
import { sqlTable } from "@himanshupadecha/corem";

export const users = sqlTable("users", {
  id: int("id").primaryKey().autoIncrement().notNull(),
  name: varchar("name", 255).notNull(),
  email: varchar("email", 255).notNull().unique(),
  createdAt: timestamp("created_at").notNull().defaultNow(),
});

export const posts = sqlTable("posts", {
  id: int("id").primaryKey().autoIncrement(),
  title: varchar("title", 255).notNull(),
  userId: int("user_id")
    .references(() => users.columns.id, { onDelete: "cascade" })
    .notNull(),
});

4. Push Schema to Database

Use the Corem CLI to automatically sync your defined schema with your MySQL database:

npx corem push

5. Initialize the Database Client

Create an instance of the database to execute queries. Create src/db/index.ts:

import { corem } from "@himanshupadecha/corem";

// Initialize and export the database connection
export const db = corem();

---

📖 Query Builder API

Corem provides a fluent, SQL-like query builder that is 100% type-safe based on your schema.

Select Queries

Basic Select

const allUsers = await db.select().from(users).execute();
// SELECT * FROM users;

Select Specific Columns

const result = await db
  .select({
    id: users.columns.id,
    username: users.columns.name,
  })
  .from(users)
  .execute();
// SELECT users.id AS id, users.name AS username FROM users;

Where Conditions

import { eq, and } from "@himanshupadecha/corem";

const result = await db
  .select()
  .from(users)
  .where(
    and(
      eq(users.columns.id, 1),
      eq(users.columns.name, "John")
    )
  )
  .execute();

Insert Queries

await db
  .insert(users)
  .values({
    name: "John Doe",
    email: "john@example.com",
  })
  .execute();
// INSERT INTO users (name, email) VALUES ('John Doe', 'john@example.com');

(Note: Bulk inserts are coming in a future update!)

Update Queries

await db
  .update(users)
  .set({ name: "Updated Name" })
  .where(eq(users.columns.id, 1))
  .execute();

Delete Queries

await db
  .delete()
  .from(users)
  .where(eq(users.columns.id, 10))
  .execute();

Advanced Operations

Sorting & Pagination

import { asc, desc } from "@himanshupadecha/corem";

const paginatedUsers = await db
  .select()
  .from(users)
  .orderBy(desc(users.columns.createdAt), asc(users.columns.name))
  .limit(10)
  .execute();

Joins

Corem supports type-safe SQL joins:

// Inner Join
const userPosts = await db
  .select()
  .from(users)
  .innerJoin(posts, eq(users.columns.id, posts.columns.userId))
  .execute();

// Left Join
const usersWithOptionalPosts = await db
  .select()
  .from(users)
  .leftJoin(posts, eq(users.columns.id, posts.columns.userId))
  .execute();

---

🏗️ Supported Column Constraints

Define database constraints smoothly via chained methods:

• .primaryKey() - Sets column as primary key.
• .autoIncrement() - Makes an integer column auto-increment.
• .notNull() - Marks column as required (NOT NULL).
• .unique() - Adds a unique constraint.
• .defaultNow() - Sets the default value to current timestamp.
• .references(() => column, { onDelete: 'cascade' }) - Sets up a foreign key.

---

🗺️ Roadmap

Corem is actively evolving. Here is what we have planned:

• PostgreSQL & SQLite Support
• Advanced Migration History System
• Complex Relational Fetching API
• Query Logging & Profiling
• Database Transactions
• Automatic Schema Introspection

---

🤝 Contributing

We welcome community contributions! To get started:

1. Fork the repository
2. Create a new feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

📄 License

This project is licensed under the ISC License.

---

Built with ❤️ for the TypeScript ecosystem.