Eicrud

<p align="center"> <a href="https://eicrud.com" target="_blank"><img width="200" src="https://raw.githubusercontent.com/eicrud/eicrud/develop/docs/planet.svg" alt="@eicrud/eicrud logo"></a> </p> <p align="center"> <a href="https://docs.eicrud.com" target="_blank"><img alt="Static Badge" src="https://img.shields.io/badge/Documentation-purple"></a> <a href="https://npmjs.com/package/@eicrud/core" target="_blank"><img src="https://img.shields.io/npm/v/%40eicrud%2Fcore?color=%232AAA8A%09" alt="npm package"></a> <!-- <a href="https://npmjs.com/package/@eicrud/core" target="_blank"><img src="https://img.shields.io/npm/dw/%40eicrud%2Fcore.svg" alt="downloads"></a> --> <!--<a href="https://npmjs.com/package/@eicrud/core" target="_blank"><img alt="NPM Unpacked Size" src="https://img.shields.io/npm/unpacked-size/%40eicrud%2Fcore"></a>--> <a href="https://discord.gg/VaGPqE7bn9" target="_blank"><img alt="Static Badge" src="https://img.shields.io/badge/Discord-%235865F2"></a> <a href="https://x.com/eicrud" target="_blank"><img alt="X (formerly Twitter) Follow" src="https://img.shields.io/twitter/follow/eicrud"></a> </p> <p align="center"><b>Eicrud</b> is an opinionated backend framework extending <a href="https://github.com/nestjs/nest" target="_blank">NestJS</a>.<br/> It's a tool for building scalable, secure <a href="https://nodejs.org" target="_blank">Node.js</a> server applications in record time.</p>

[!IMPORTANT] Eicrud is still in beta; expect minor breaking changes with new versions until v1.0.0. However, you can still use it as it is, and the API will not change much. Check out the release notes for migration guides. If you're interested in the project, please leave a star on the repository; it helps a lot 🌟🙏

Philosophy

Most of the time, a web app has some CRUD functionality as its base. Eicrud abstracts this into a simple and easy-to-use API, so you don't have to re-write boilerplate code (controllers, validations, db queries...) whenever you need a new service. By centering everything around CRUD entities, Eicrud provides a framework for writing complex applications that are easy to read, test, and maintain. Eicrud also emphasizes "default security" for its components, where everything is forbidden until allowed.

Features

• ⚙️ Out of the box CRUD services

• 🔑 Authentication & user management

• 🔒 Authorization

• 🖥️ Commands

• ✔️ Validation/Transform

• 🗃️ Database control

• 🚀 Easy to use (RPC) client

• 🌐 Monolithic/Microservices

• And more!

How it works

Under the hood, Eicrud uses MikroOrm entities guarded with CASL and class-validator.

Here's a quick example

You first define your entity with validations and transforms (what the data can be).

@Entity()
export class Profile {
  @PrimaryKey()
  @IsString()
  @IsOptional()
  id: string;

  @OneToOne(() => MyUser, (user) => user.profile)
  @IsString()
  owner: MyUser | string;

  @Property()
  @$Transform((val) => val.toLowerCase())
  @MaxLength(30)
  userName: string;
}

Then define your security (who can access the data).

const security: CrudSecurity = {
  user: {
    async defineCRUDAbility(can, cannot, ctx) {
      const id = ctx.userId;
      // users can crud their own profile
      can('crud', 'profile', { owner: id });
    },
  },
  guest: {
    async defineCRUDAbility(can, cannot, ctx) {
      // guests can read all profiles
      can('read', 'profile');
    },
  },
};

And finally, register your service.

@Injectable()
export class ProfileService extends CrudService<Profile> {
  constructor(protected moduleRef: ModuleRef) {
    super(moduleRef, Profile, security);
  }
}

That's it, profile is now a fully operational CRUD service that you can query with the client.

const client = new CrudClient({ serviceName: 'profile' });

const res = await client.findOne({ userName: 'jon doe' });

You can extend it using commands (for non-CRUD operations).

Monolithic/Microservices duality

Eicrud lets you group your CRUD services into "microservices" with a simple configuration. You can start developing a monolith and easily switch to microservices later on.

msOptions.microServices = {
  "entry": {
    services: [],
    openMsLink: false, openController: true,
    url: "http://localhost:3004",
  },
  "users": {
    services: [User, Profile],
    openMsLink: true, openController: false,
    url: "http://localhost:3005",
  },
  "orders": {
    services: [Order],
    openMsLink: true, openController: false,
    url: "http://localhost:3006",
  },
}

Powerful typed client (remote procedure call)

Eicrud lets you generate a powerful super-client that holds all your DTOs and commands. Allowing auto-completion and type safety directly in your front-end.

// in your profile service
async $say_hello(dto: SayHelloDto, ctx: CrudContext) {
    return `Hello ${dto.myArg}!`
}

// in your frontend
const sp = new SuperClient({url: 'http://localhost:3004'});
sp.profile.say_hello({myArg: 'world'}).then(console.log);

Start building

Eicrud is made for code simplicity, you can build your applications in record time using the CLI that will do the heavy work for you.

Check out the documentation to get started.

Support

Eicrud is in active development and issues are taken seriously. Don't hesitate to create a ticket or join the Discord if you need help.