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

field resolution per route

When a field-targeted interceptor pattern like update.provider_id is registered, the field name is extracted from the request differently depending on which route is hit.

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)
})

Append Response

example

notes

Append Collection

directive syntax

via HTTP

via service

notes

analysis

common options

analysis types

thresholds

HTTP endpoints

schema-level population

options

example

notes

field policy

read guard

write guard

example

notes

serviceFor()

scopedService options

example

notes

audit log

options

audit record shape

example

notes

virtual fields

example

notes

schema migrations

__schemaVersion

execution

example

notes

webhooks

config options

payload shape

signature

example

notes

serialiser

examples

scope

notes