mongodb-models-visualizer 0.1.0

package/README.md

@@ -0,0 +1,212 @@
+# mongodb-visualizer
+
+🚀 **Swagger-like Analyzer for MongoDB (Mongoose) Models**
+
+Automatically analyze, visualize, and document your MongoDB models in a Node.js + Express application.
+
+---
+
+## ✨ What is mongodb-visualizer?
+
+`mongodb-visualizer` is a developer tool that introspects your **Mongoose models** and provides:
+
+- List of all registered models
+- Schema fields with types & validations
+- Model relationships (`ref`)
+- Collection names
+- Optional sample documents
+- Swagger-like web UI
+- JSON APIs for documentation & automation
+
+Think of it as **Swagger, but for MongoDB schemas**.
+
+---
+
+## 🔧 Supported Stack
+
+- Node.js ≥ 16
+- Express ≥ 4
+- Mongoose ≥ 6
+
+---
+
+## 📦 Installation
+
+```bash
+npm install mongodb-visualizer
+```
+
+or
+
+```bash
+yarn add mongodb-visualizer
+```
+
+## 🚀 Quick Start
+
+### 1️⃣ Setup Express & Mongoose
+
+```javascript
+import express from 'express'
+import mongoose from 'mongoose'
+import { modelAnalyzer } from 'mongodb-visualizer'
+
+const app = express()
+
+mongoose.connect(process.env.MONGO_URI)
+```
+
+### 2️⃣ Mount the Analyzer Middleware
+
+```javascript
+app.use(
+  '/models-analyzer',
+  modelAnalyzer({
+    mongoose
+  })
+)
+```
+
+### 3️⃣ Start the Server
+
+```javascript
+app.listen(3000, () => {
+  console.log('Server running on http://localhost:3000')
+})
+```
+
+### 4️⃣ Open in Browser 🎉
+
+Navigate to `http://localhost:3000/models-analyzer`
+
+## 📊 API Endpoints
+
+### 🔹 Get all models
+
+```
+GET /models-analyzer/api/models
+```
+
+**Example Response:**
+
+```json
+[
+  {
+    "name": "User",
+    "collection": "users",
+    "fields": [
+      {
+        "name": "email",
+        "instance": "String",
+        "required": true,
+        "enum": [],
+        "ref": null
+      }
+    ]
+  }
+]
+```
+
+### 🔹 Get a single model
+
+```
+GET /models-analyzer/api/models/:modelName
+```
+
+## ⚙️ Configuration Options
+
+```javascript
+modelAnalyzer({
+  mongoose,          // required
+  sampleDocs: true,  // optional (default: false)
+  auth: false        // optional (default: false)
+})
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| mongoose | Object | Mongoose instance |
+| sampleDocs | Boolean | Include sample documents |
+| auth | Boolean | Enable auth middleware |
+
+## ## 🔐 Security (Recommended for Production)
+
+Do NOT expose this endpoint publicly without authentication.
+
+**Example using basic auth:**
+
+```javascript
+import basicAuth from 'express-basic-auth'
+
+app.use(
+  '/models-analyzer',
+  basicAuth({
+    users: { admin: 'password' },
+    challenge: true
+  }),
+  modelAnalyzer({ mongoose })
+)
+```
+
+## 🧠 How It Works
+
+1. Scans all registered Mongoose models
+2. Extracts schema metadata
+3. Parses fields, types, refs, and indexes
+4. Builds structured JSON output
+5. Serves data via API & UI
+
+## 🗺️ Roadmap
+
+### ✅ v0.1 (Current)
+
+- Model scanner
+- Schema parser
+- JSON APIs
+
+### 🚀 v0.2
+
+- Swagger-like UI
+- Relationship graph
+- Index analyzer
+
+### 🧠 v1.0
+
+- Performance suggestions
+- Migration hints
+- CLI support
+- Fastify & NestJS adapters
+
+## 🤝 Contributing
+
+Contributions are welcome!
+
+```bash
+git clone https://github.com/Hibbanur-Rahman/mongodb-visualizer.git
+cd mongodb-visualizer
+npm install
+npm run build
+```
+
+Feel free to open issues or pull requests 🚀
+
+## 📄 License
+
+MIT License © 2026
+
+## ❤️ Why This Tool?
+
+- MongoDB has no built-in schema visualization
+- Helps onboarding new developers
+- Great for documentation & debugging
+- Inspired by Swagger & Prisma Studio
+
+---
+
+**Next steps you can take:**
+- Add npm badges
+- Write a CONTRIBUTING.md
+- Create a docs website
+- Prepare a demo GIF
+
+Let me know what's next! 🚀

package/dist/index.cjs

@@ -0,0 +1,85 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  modelAnalyzer: () => modelAnalyzer
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/express/middleware.ts
+var import_express = __toESM(require("express"), 1);
+
+// src/core/scanModels.ts
+var import_mongoose = require("mongoose");
+function scanModels(mongoose) {
+  return mongoose.modelNames().map((name) => {
+    const model = mongoose.model(name);
+    return {
+      name,
+      collection: model.collection.name,
+      schema: model.schema
+    };
+  });
+}
+
+// src/core/parseSchema.ts
+var import_mongoose2 = require("mongoose");
+function parseSchema(schema) {
+  const fields = [];
+  schema.eachPath((path, type) => {
+    fields.push({
+      name: path,
+      instance: type.instance,
+      required: !!type.isRequired,
+      enum: type.enumValues || [],
+      ref: type.options?.ref
+    });
+  });
+  return fields;
+}
+
+// src/express/middleware.ts
+function modelAnalyzer(options) {
+  const router = import_express.default.Router();
+  router.get("/api/models", (req, res) => {
+    const models = scanModels(options.mongoose).map((m) => ({
+      name: m.name,
+      collection: m.collection,
+      fields: parseSchema(m.schema)
+    }));
+    res.json(models);
+  });
+  return router;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  modelAnalyzer
+});

package/dist/index.d.cts

@@ -0,0 +1,7 @@
+import * as express_serve_static_core from 'express-serve-static-core';
+
+declare function modelAnalyzer(options: {
+    mongoose: any;
+}): express_serve_static_core.Router;
+
+export { modelAnalyzer };

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+import * as express_serve_static_core from 'express-serve-static-core';
+
+declare function modelAnalyzer(options: {
+    mongoose: any;
+}): express_serve_static_core.Router;
+
+export { modelAnalyzer };

package/dist/index.js

@@ -0,0 +1,48 @@
+// src/express/middleware.ts
+import express from "express";
+
+// src/core/scanModels.ts
+import "mongoose";
+function scanModels(mongoose) {
+  return mongoose.modelNames().map((name) => {
+    const model = mongoose.model(name);
+    return {
+      name,
+      collection: model.collection.name,
+      schema: model.schema
+    };
+  });
+}
+
+// src/core/parseSchema.ts
+import "mongoose";
+function parseSchema(schema) {
+  const fields = [];
+  schema.eachPath((path, type) => {
+    fields.push({
+      name: path,
+      instance: type.instance,
+      required: !!type.isRequired,
+      enum: type.enumValues || [],
+      ref: type.options?.ref
+    });
+  });
+  return fields;
+}
+
+// src/express/middleware.ts
+function modelAnalyzer(options) {
+  const router = express.Router();
+  router.get("/api/models", (req, res) => {
+    const models = scanModels(options.mongoose).map((m) => ({
+      name: m.name,
+      collection: m.collection,
+      fields: parseSchema(m.schema)
+    }));
+    res.json(models);
+  });
+  return router;
+}
+export {
+  modelAnalyzer
+};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "mongodb-models-visualizer",
+  "version": "0.1.0",
+  "description": "MongoDB Database Visualizer and models relationships between collections",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "peerDependencies": {
+    "mongoose": ">=6",
+    "express": ">=4"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "build": "tsup",
+    "prepublishOnly": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Hibbanur-Rahman/mongodb-visualizer.git"
+  },
+  "keywords": [],
+  "author": "Hibbanur Rahman",
+  "license": "ISC",
+  "type": "module",
+  "bugs": {
+    "url": "https://github.com/Hibbanur-Rahman/mongodb-visualizer/issues"
+  },
+  "homepage": "https://github.com/Hibbanur-Rahman/mongodb-visualizer#readme",
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/node": "^25.2.2",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "express": "^5.2.1",
+    "mongoose": "^9.1.6"
+  }
+}

package/src/core/parseSchema.ts

@@ -0,0 +1,17 @@
+import { Schema } from 'mongoose'
+
+export function parseSchema(schema: Schema) {
+  const fields: any[] = []
+
+  schema.eachPath((path, type: any) => {
+    fields.push({
+      name: path,
+      instance: type.instance,
+      required: !!type.isRequired,
+      enum: type.enumValues || [],
+      ref: type.options?.ref
+    })
+  })
+
+  return fields
+}

package/src/core/scanModels.ts

@@ -0,0 +1,12 @@
+import { Mongoose } from 'mongoose'
+
+export function scanModels(mongoose: Mongoose) {
+  return mongoose.modelNames().map((name) => {
+    const model = mongoose.model(name)
+    return {
+      name,
+      collection: model.collection.name,
+      schema: model.schema
+    }
+  })
+}

package/src/express/index.ts

@@ -0,0 +1 @@
+export { modelAnalyzer } from './middleware'

package/src/express/middleware.ts

@@ -0,0 +1,21 @@
+import express from 'express'
+import { scanModels } from '../core/scanModels'
+import { parseSchema } from '../core/parseSchema'
+
+export function modelAnalyzer(options: {
+  mongoose: any
+}) {
+  const router = express.Router()
+
+  router.get('/api/models', (req, res) => {
+    const models = scanModels(options.mongoose).map((m) => ({
+      name: m.name,
+      collection: m.collection,
+      fields: parseSchema(m.schema)
+    }))
+
+    res.json(models)
+  })
+
+  return router
+}

package/src/index.ts

@@ -0,0 +1 @@
+export { modelAnalyzer } from './express'

package/tsconfig.json

@@ -0,0 +1,45 @@
+{
+  // Visit https://aka.ms/tsconfig to read more about this file
+  "compilerOptions": {
+    // File Layout
+    // "rootDir": "./src",
+    "outDir": "./dist",
+
+    // Environment Settings
+    // See also https://aka.ms/tsconfig/module
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "target": "ES2020",
+    "types": [],
+    // For nodejs:
+    // "lib": ["esnext"],
+    // "types": ["node"],
+    // and npm install -D @types/node
+
+    // Other Outputs
+    "sourceMap": true,
+    "declaration": true,
+    "declarationMap": true,
+
+    // Stricter Typechecking Options
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+
+    // Style Options
+    // "noImplicitReturns": true,
+    // "noImplicitOverride": true,
+    // "noUnusedLocals": true,
+    // "noUnusedParameters": true,
+    // "noFallthroughCasesInSwitch": true,
+    // "noPropertyAccessFromIndexSignature": true,
+
+    // Recommended Options
+    "strict": true,
+    "jsx": "react-jsx",
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "noUncheckedSideEffectImports": true,
+    "moduleDetection": "force",
+    "skipLibCheck": true,
+  }
+}

package/tsup.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from 'tsup'
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['cjs', 'esm'],
+  dts: true,
+  clean: true
+})