Common Scenarios

Scenario-first documentation for real consumer use cases.

Common Scenarios

Use this page when you want the fastest path from “I need X” to working commands and runtime structure.

Choose a scenario

• First SQL CRUD API
• Mongo document app
• Blog with relations
• Soft delete and restore
• Cached GET endpoints
• Test-isolated artifacts
• Many-to-many favorites or tags
• Casts, scopes, and serialization
• Production-safe migrations

Scenario 1: First SQL CRUD API

eloquent make:model User --with-migration
eloquent make:service User
eloquent make:controller User
eloquent make:migration --all
eloquent migrate:run --all-migrations

Register models:

import { registerModels } from "@alpha.consultings/eloquent-orm.js";
import { User } from "./app/models/User";

registerModels([User]);

Wire Express routes with the generated controller and keep CRUD in the service layer.

Recommended service CRUD shape:

const created = await User.create({
  name: "Alice",
  email: "[e-mail]",
});

const found = await User.find(created.id as number);
if (found) {
  found.update({ name: "Alice Updated" });
  await found.save();
}

await User.updateMany([1, 2], { status: "inactive" });

Scenario 2: Mongo document app

eloquent make:model GeoLocation --mongo
eloquent make:service GeoLocation
eloquent make:controller GeoLocation

Use MongoModel and explicit mongo connection names.

Scenario 3: Blog with relations

eloquent make:scenario blog --test --controllers --services --run --force

Use this when you want User, Post, Comment, favorites, and polymorphic comment flows quickly.

Scenario 4: Soft delete and restore

Generate restore-ready controller:

eloquent make:controller User --soft

Use one schema declaration:

deleted_at: column("softDeletes")

or:

softDeletes: mixin("SoftDeletes")

Scenario 5: Cache GET endpoints

Keep cache logic in services:

import { CacheManager, setupCache } from "@alpha.consultings/eloquent-orm.js";

setupCache();

Read from cache before query execution and invalidate after writes.

Recommended write-side invalidation:

async createUser(data: Record<string, unknown>) {
  const created = await User.create(data);
  await CacheManager.delete("users:active:v1");
  return created;
}

Scenario 6: Test-isolated artifacts

eloquent make:model User --test
eloquent make:service User --test
eloquent make:controller User --test
eloquent make:migration --all --test
eloquent migrate:run --test --all-migrations

Scenario 7: Many-to-many favorites or tags

Use service-level attach, detach, and sync flows for pivot management.

Scenario 8: Casts, scopes, and serialization

• casts normalize service reads
• scopes filter all() and find()
• toObject() gives API-safe output

Example:

const user = await User.find(id);
return user?.toObject?.() ?? user;

Scenario 9: Production-safe migrations

Recommended order:

1. eloquent migrate:status
2. eloquent db:seed:precheck --all-connections
3. eloquent migrate:run --all-migrations
4. destructive flows only with explicit --force --yes

Next detailed guides

• Usage Guides
• Cookbook
• Controllers
• Services
• Models
• Mixin Scenarios
• Relations
• NoSQL