@ubyjerome/meta-manager

MongoDB entity manager for Express. Define an entity once — get a full REST API, typed service layer, lifecycle events, interceptors, and deep parent/child relations, with no repetitive boilerplate.

---

Install

npm install @ubyjerome/meta-manager mongoose express

---

Quick Start

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

await mongoose.connect("mongodb://localhost:27017/mydb");

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

const booksEntity = new MetaEntity("books", {
  searchableFields: ["title_name", "description"],
  defaultSort: "created_at",
  defaultOrder: "desc",
  defaultLimit: 20,
  softDelete: true,
});

app.use("/books", booksEntity.controller);
app.listen(3000);

That single mount produces the following endpoints:

Method	Path	Description
GET	/books/all	Paginated list with sort, filter, fields
GET	/books/search?q=term	Full-text or regex search
GET	/books/count	Document count with optional filter
GET	/books/by/:field/:value	Find by any field
GET	/books/exists/:field/:value	Existence check
GET	/books/:id	Single record by UUID or _id
GET	/books/:id/children	Record with nested children
POST	/books/create	Create one
POST	/books/create/many	Bulk create
PUT/PATCH	/books/:id	Full or partial update
PATCH	/books/:id/field/:field	Update a single nested field
DELETE	/books/:id	Soft delete (add ?hard=true for hard delete)
POST	/books/:id/restore	Restore a soft-deleted record

---

Default Document Shape

Every entity document inherits these fields automatically:

{
  uuid: string;              // auto-generated UUID v4
  request_id?: string;
  meta_key?: string;
  meta_value?: string;
  data_type?: string;
  title_name?: string;
  description?: string;
  entity_featured_url?: string;
  extra_data?: unknown[];    // schema-less, accepts anything
  meta_data?: unknown[];     // schema-less, accepts anything
  status: "active" | "inactive" | "archived";
  parent_entity_type?: string;
  parent_entity?: string;
  owned_by?: string;
  added_by?: string;
  created_by?: string;
  updated_by?: string;
  slug?: string;             // auto-generated from title_name
  deleted_at?: Date;
  created_at: Date;
  updated_at: Date;
}

---

Entity Options

new MetaEntity("books", {
  // Extra schema fields using Mongoose field definition syntax
  additionalFields: {
    isbn: { type: String, required: true, unique: true },
    pageCount: { type: Number, default: 0 },
    rating: { type: Number, min: 0, max: 5 },
  },

  // Fields to run regex/text search against
  searchableFields: ["title_name", "description", "isbn"],

  // Soft delete behaviour (default: true)
  softDelete: true,

  // Default query settings
  defaultSort: "created_at",
  defaultOrder: "desc",
  defaultLimit: 20,

  // Override the MongoDB collection name
  collectionName: "library_books",

  // Parent relations (adds required foreignKey to the schema)
  parents: [
    {
      entity: () => libraryEntity,
      type: "parent",
      foreignKey: "libraryId",
    },
  ],

  // Sister relations (adds required foreignKey to the schema)
  sisters: [
    {
      entity: () => authorEntity,
      type: "sister",
      foreignKey: "authorId",
    },
  ],

  // Declares which entities are children of this one
  children: [
    {
      entity: () => chaptersEntity,
      foreignKey: "bookId",      // field on the child pointing to this entity's UUID
      alias: "chapters",         // key under which paginated results appear
    },
  ],
});

---

Query Parameters

All GET endpoints accept these query parameters:

Pagination & Sorting

?page=2&limit=10&sort=title_name&order=asc

Field Projection

?fields=uuid,title_name,status,created_at

Arbitrary Filter

?filter[status]=active&filter[owned_by]=some-uuid

Search

GET /books/search?q=tolkien&searchFields=title_name,description

Children

# Include all registered children
GET /books/:id/children?includeChildren=true

# Include specific children only
GET /books/:id/children?includeChildren=chapters,reviews

# Control depth (fetch children of children)
GET /books/:id/children?includeChildren=true&childDepth=2

# Per-child pagination
GET /books/:id/children?includeChildren=chapters&childPage[chapters]=2&childLimit[chapters]=5&childSort[chapters]=created_at&childOrder[chapters]=asc

---

Service Layer

The service exposes all the same logic for use in your own business code:

const bookService = booksEntity.service;

// Paginated list
const { data, pagination } = await bookService.all({ page: 1, limit: 10, sort: "title_name" });

// By ID (UUID or _id)
const book = await bookService.findById("some-uuid");

// Find by any field
const results = await bookService.findBy("status", "active", { page: 1, limit: 5 });

// Search
const found = await bookService.search("tolkien", { searchFields: ["title_name"] });

// Create
const book = await bookService.create({ title_name: "The Hobbit", libraryId: "lib-uuid" });

// Bulk create
const books = await bookService.createMany([{ title_name: "..." }, { title_name: "..." }]);

// Update
const updated = await bookService.update("book-uuid", { status: "inactive" });

// Update a single field (dot-notation safe)
await bookService.updateField("book-uuid", "extra_data.0.tokenName", "NewName");

// Soft delete
await bookService.delete("book-uuid");

// Hard delete
await bookService.delete("book-uuid", { soft: false });

// Restore
await bookService.restore("book-uuid");

// Count
const total = await bookService.count({ status: "active" });

// Existence
const exists = await bookService.exists({ isbn: "978-3-16-148410-0" });

// Record with children
const library = await libraryEntity.service.withChildren("lib-uuid", {
  includeChildren: ["books"],
  childDepth: 2,
  childPagination: { books: { page: 1, limit: 10 } },
});

---

Lifecycle Events

Subscribe to entity events using trigger(). Events fire after the relevant database operation completes.

Available Event Types

Pattern	Fires when
create	A new document is created
update	Any field on a document changes
update.fieldName	The specific field fieldName changes
update.extra_data[*]	Any element in the extra_data array changes
update.extra_data[tokenName].Zugacoin	The array element with tokenName === "Zugacoin" changes
delete	A document is deleted
restore	A soft-deleted document is restored

// New document
booksEntity.trigger(["create"], (whatWas, whatIs, book) => {
  sendEmail(book.owned_by, `New book added: ${book.title_name}`);
});

// Any update
booksEntity.trigger(["update"], (whatWas, whatIs, book) => {
  const changedFields = Object.keys(whatIs);
  console.log(`Fields changed: ${changedFields.join(", ")}`);
});

// Specific field change
booksEntity.trigger(["update.status"], (whatWas, whatIs, book) => {
  console.log(`Status changed from ${whatWas.status} to ${whatIs.status}`);
});

// Array element change (any element)
booksEntity.trigger(["update.extra_data[*]"], (whatWas, whatIs, book) => {
  console.log("A token in extra_data was modified");
});

// Specific named array element
booksEntity.trigger(["update.extra_data[tokenName].Zugacoin"], (whatWas, whatIs, book) => {
  console.log("Zugacoin token data changed", whatWas, whatIs);
});

// Multiple events in one subscription
booksEntity.trigger(["create", "update"], (whatWas, whatIs, book) => {
  rebuildSearchIndex(book.uuid);
});

// Deletion
booksEntity.trigger(["delete"], (whatWas, _whatIs, book) => {
  console.log("Deleted:", book.uuid);
});

Callbacks may be async. Errors inside callbacks are caught and logged — they do not interrupt the HTTP response.

---

Interceptors (Middleware / RBAC)

Mount middleware that runs before specific controller actions:

// Auth guard on delete
booksEntity.intercept("delete", (req, res, next) => {
  if (!req.user?.isAdmin) {
    return res.status(403).json({ message: "Forbidden" });
  }
  next();
});

// Scope reads to the current user
booksEntity.intercept("read", (req, res, next) => {
  req.query["filter[owned_by]"] = req.user.uuid;
  next();
});

// Multiple actions at once
booksEntity.intercept(["create", "update"], async (req, res, next) => {
  req.body.updated_by = req.user?.uuid;
  next();
});

// All actions
booksEntity.intercept("all", (req, res, next) => {
  console.log(`[${new Date().toISOString()}] ${req.method} ${req.originalUrl}`);
  next();
});

Available action values: "create", "read", "update", "delete", "all".

Multiple interceptors for the same action run in registration order.

---

Relations

Parent (owned-by)

// chapters requires bookId on create
const chaptersEntity = new MetaEntity("chapters", {
  parents: [
    { entity: () => booksEntity, type: "parent", foreignKey: "bookId" }
  ],
});

// Creating a chapter requires bookId in the body
await chaptersEntity.service.create({ title_name: "Chapter 1", bookId: "book-uuid" });

Children (populated on parent fetch)

const booksEntity = new MetaEntity("books", {
  children: [
    { entity: () => chaptersEntity, foreignKey: "bookId", alias: "chapters" },
    { entity: () => reviewsEntity, foreignKey: "bookId", alias: "reviews" },
  ],
});

// Via service
const book = await booksEntity.service.withChildren("book-uuid", {
  includeChildren: ["chapters"],
  childDepth: 1,
  childPagination: { chapters: { page: 1, limit: 10, sort: "created_at" } },
});

// Via HTTP
// GET /books/:id/children?includeChildren=chapters&childPage[chapters]=2&childLimit[chapters]=5

Sister (peer relation)

const profileEntity = new MetaEntity("profiles", {
  sisters: [
    { entity: () => userEntity, type: "sister", foreignKey: "userId" }
  ],
});

---

Updating Nested Fields

The PATCH /:id/field/:field endpoint and updateField() method accept dot-notation paths:

# Update a top-level field
PATCH /books/:id/field/status
Body: { "value": "inactive" }

# Update a nested object field
PATCH /books/:id/field/extra_data.0.tokenName
Body: { "value": "NewTokenName" }

await bookService.updateField(id, "extra_data.0.minProcessingAmount", 50);

---

TypeScript

The package ships full .d.ts declarations. When building with TypeScript you can type your entities:

import { MetaEntity, BaseEntityDocument } from "@ubyjerome/meta-manager";

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

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

// service is fully typed as IMetaService<BookDocument>
const book = await booksEntity.service.findById("uuid");
// book is BookDocument | null

---

MongoDB Connection Requirement

MetaEntity checks for an active (connected or connecting) Mongoose connection at instantiation time and throws immediately if none exists. Always call mongoose.connect() before creating entity instances.

await mongoose.connect(process.env.MONGO_URI!);

// Safe to create entities now
const booksEntity = new MetaEntity("books", { ... });