quick start

Connect to MongoDB, create an entity, mount its controller. That is the complete setup.

import mongoose from "mongoose"
import express from "express"
import Joi from "joi"
import { MetaEntity } from "@ubyjerome/meta-manager"

// 1. connect first - MetaEntity checks this at construction
await mongoose.connect("mongodb://localhost:27017/mydb")

const app = express()
app.use(express.json())

// 2. define the entity
const booksEntity = new MetaEntity("books", {
  createSchema: {
    title_name: Joi.string().required(),
    isbn:       Joi.string().optional(),
    libraryId:  Joi.string().required()
  },
  searchableFields: ["title_name", "description"],
  softDelete: true,
  defaultSort: "created_at",
  defaultLimit: 20
})

// 3. mount the controller
app.use("/books", booksEntity.controller)

app.listen(3000)

That single mount registers 14+ endpoints. You can also reach every operation programmatically via booksEntity.service.

typescript interface extension

Extend BaseEntityDocument and pass it as the generic to get fully typed service methods and event callbacks.

interface BookDocument extends BaseEntityDocument {
  isbn:      string
  pageCount: number
  libraryId: string
}

const booksEntity = new MetaEntity<BookDocument>("books", { ... })

// service is IMetaService<BookDocument>
const book = await booksEntity.service.findById(id)
// book is BookDocument | null

entity options reference

entity

MetaEntity is the single constructor. It validates the MongoDB connection, compiles the Mongoose schema, creates the service and controller, and exposes the event emitter.

const entity = new MetaEntity(name: string, options: MetaEntityOptions)

// exposed properties
entity.entityName  // string
entity.model       // Mongoose Model<T>
entity.service     // IMetaService<T>
entity.controller  // Express Router
entity.nestedOps   // NestedOpsService<T>

// methods
entity.trigger(events, callback)
entity.intercept(action, callback)
entity.nested(id, payload)
entity.nestedBatch(id, payloads)

additionalFields

Declare extra schema fields using Mongoose field definition syntax. The base fields are always present and cannot be overridden.

const profileEntity = new MetaEntity("profiles", {
  additionalFields: {
    userId:       { type: String, required: true, unique: true },
    bio:          { type: String, default: null },
    rating_average: { type: Number, min: 0, max: 5, default: 0 },
    is_vetted:    { type: Boolean, default: false },
    services:     { type: Array, default: [] },
    personal_information: { type: Object, default: {} }
  }
})

service

The service layer exposes every data operation as an async method. Accessing entity.service gives you the same logic that powers the HTTP controller, usable directly in your business code.

endpoints

events

event types

callback nullability

examples

interceptors

action types

notes

examples

nested operations

operators

usage examples

// set a nested object property
await profileEntity.nested(id, {
  field:     "personal_information.email",
  operation: "set",
  value:     "new@email.com"
})

// update a specific services[] item by _mmid
await profileEntity.nested(id, {
  field:     "services",
  operation: "patch_item",
  value:     { _mmid: "mmid-cleaning", category: "Premium Cleaning" }
})

// remove a service by _mmid
await profileEntity.nested(id, {
  field:     "services",
  operation: "pull_id",
  value:     "mmid-laundry"
})

// batch - applied in minimum round-trips
await profileEntity.nestedBatch(id, [
  { field: "rating_average",             operation: "increment", value: 0.5 },
  { field: "tags",                        operation: "push",      value: "verified" },
  { field: "personal_information.phone",  operation: "set",       value: "08012345678" }
])

relations

validation

schema setup

options

TypeScript

document extension

key types exported

event path inference

// EventPath<BookDocument> produces a union including:
//   "create" | "update" | "delete" | "restore"
//   "update.isbn" | "update.pageCount" | "update.libraryId"
//   "update.extra_data" | "update.extra_data[*]"

booksEntity.trigger(["update.isbn"], (whatWas, whatIs, book) => {
  // whatWas: Partial<BookDocument>  -- no null check needed
  // whatIs:  Partial<BookDocument>  -- no null check needed
  console.log(whatWas.isbn, "=>", whatIs.isbn)
})