About The Project

Zumito DB is a lightweight, decorator-based ORM for Node.js. Define your models with TypeScript decorators and switch between database drivers without changing your application code. Supports MongoDB, SQLite, TingoDB, and an in-memory driver for testing.

Built With

• Node.js
• TypeScript
• MongoDB
• better-sqlite3

Supported Drivers

| Driver | Description | | ------- | ------------------------ | | memory | In-memory (testing/DEV) | | mongo | MongoDB | | sqlite | SQLite via better-sqlite3| | tingo | TingoDB (embedded MongoDB-compatible) |

Getting Started

Prerequisites

• Node.js 18+
• npm

Installation

npm install zumito-db reflect-metadata

Depending on your database:

npm install mongodb        # for MongoDB
npm install better-sqlite3 # for SQLite
npm install tingodb        # for TingoDB

Enable decorator metadata in your tsconfig.json:

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}

Import reflect-metadata at the entry point of your application:

import 'reflect-metadata';

Usage

Define a Model

import { Collection, Field, HasMany, BelongsTo } from 'zumito-db';

@Collection({ name: 'users' })
class User {
  @Field({ type: 'string', primary: true })
  id: string;

  @Field({ type: 'string', unique: true })
  email: string;

  @Field({ type: 'string' })
  name: string;

  @Field({ type: 'number', default: 0 })
  age: number;

  @HasMany(() => Post, { foreignKey: 'userId' })
  posts: Post[];
}

@Collection({ name: 'posts' })
class Post {
  @Field({ type: 'string', primary: true })
  id: string;

  @Field({ type: 'string' })
  title: string;

  @Field({ type: 'string' })
  userId: string;

  @BelongsTo(() => User, { foreignKey: 'userId' })
  user: User;
}

Connect and Use Repositories

import { DatabaseManager } from 'zumito-db';

const db = new DatabaseManager();

await db.connect({
  default: 'mongo',
  drivers: {
    mongo: { url: 'mongodb://localhost:27017', database: 'myapp' },
  },
  models: [User, Post],
});

const userRepo = db.getRepository(User);

// Insert
const user = await userRepo.insert({ email: '[email protected]', name: 'Alice' });

// Find
const users = await userRepo.find({ name: 'Alice' });

// Update
await userRepo.update({ id: user.id }, { age: 30 });

// Delete
await userRepo.delete({ id: user.id });

// Count
const count = await userRepo.count();

Using the Query Builder

const posts = await db.getRepository(Post)
  .query()
  .where('title', 'like', '%typescript%')
  .sort('createdAt', 'desc')
  .limit(10)
  .offset(0)
  .execute();

Migrations

import { Migration } from 'zumito-db';

class CreateUsersTable extends Migration {
  async up(): Promise<void> {
    await this.db.ensureSchemas();
  }

  async down(): Promise<void> {
    await this.db.dropCollection('users');
  }
}

Roadmap

See the open issues for a full list of proposed features.

• [ ] PostgreSQL support
• [ ] MySQL support
• [ ] Redis support
• [ ] Schema sync / auto-migration
• [ ] Hooks / lifecycle events

Contributing

Contributions are what make the open source community amazing. Any contributions are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

Distributed under the ISC License. See LICENSE.txt for more information.