namune

A production-ready Express.js library with built-in authentication, middleware configuration, and route management.

---

Features

• 🔐 Built-in authentication system (register, login, logout, verification)
• ⚙️ Configurable middleware stack (CORS, sessions, body parsing)
• 🗃️ MongoDB integration with Mongoose
• 🛣️ Automatic route loading and management
• 🔒 Passport.js integration for local authentication
• 🚀 Production-ready error handling and security practices
• 🧩 Modular architecture for easy extension
• 🖂 Mail Sending
• < > Advanced Pagination
• 💳 Payments with payfast
• 📁 Cloud File Uploads (To AWS S3)

---

Installation

1npm install -g namune
2# or
3yarn global add namune

---

Quick Start

1nmn create
2# or
3nmn create myproject

1# For hot reload when you save changes
2npm run dev
3# or for manual reload
4npm start

---

API Reference

Middleware Configuration (MidsConfigs)

new MidsConfigs(app)

• app (Express): Express application instance

Methods

registerMiddlewares(options)

Registers all middleware.

1options = {
2  dbConfig: { database_name: "myapp" },
3  usePassportLogin: true,
4  passportConfig: {
5    // Add your seperate custom local strategies for login authentication to the list
6    // Make sure to seperate strategyName with one dash (e.g user-local)
7    strategyList: [
8      {
9        strategyName: "user-local",
10        model: sharedDependencies.models.User, // Make sure this is included in shared.deps.js file
11        usernameField: "email", // Change relevant logic in routes/auth/api.routes.js to match your username field
12        verifyAccount: (user) => {
13          if (!user.accountActive) return "Please verify your email first.";
14          return null;
15        },
16      },
17    ],
18  },
19};

Authentication Middleware

ensureAuthenticated(req, res, next)

Middleware that checks if a user is authenticated. Returns 401 if not.

Authentication Routes (Can't be overwritten)

• POST /v1/auth/register - User registration
• POST /v1/auth/verify/account - Account verification
• POST /v1/auth/login - User login
• GET /v1/auth/logout - User logout
• POST /v1/auth/verify-email - Email verification for password reset
• POST /v1/auth/reset-password - Password reset
• POST /v1/auth/delete-account - Account deletion

---

Hooks

AUTH Hooks: Returns a response

Response Structure: {success: boolean, message: string, data: any}

onSuccessRegister

onFailRegister

onSuccessVerifyUser

onFailVerifyUser

onSuccessLogin

onFailLogin

onSuccessLogout

onFailLogout

onSuccessDeleteUser

onFailDeleteUser

onSuccessVerify

onFailVerify

onSuccessChangePassword

onFailChangePassword

Example

1// deps.js
2module.exports = {
3  global: {},
4  models: {},
5  utils: {},
6  hooks: {
7    onSuccessRegister: yourCustomFunction, // Fires when user successfully registers (/auth/register)
8    onFailRegister: yourCustomFunction, // Fires when user fails to register (/auth/register)
9  },
10};

Route Management

Routes are automatically loaded from the routes directory. Use this pattern:

1// routes/example/api.routes.js
2class ExampleRoute {
3  constructor(router, dependencies) {
4    this.router = router;
5    this.dependencies = dependencies;
6  }
7
8  exampleHandler(req, res) {
9    res.json({ message: "Success" });
10  }
11
12  registerRoutes() {
13    this.router.get("/", this.exampleHandler);
14  }
15}
16
17module.exports = ExampleRoute;

---

Configuration

Environment Variables

GENERAL

Variable	Default	Description
PORT	8000	Server port
MONGODB_URI	mongodb://localhost:27017	MongoDB connection string
DATABASE_NAME	example-db	Database name
NODE_ENV	development	Runtime environment
STAGING_ENV	undefined	Runtime environment
STAGING_URL	undefined	URL for your staging client/frontend
PROD_URL	undefined	URL for your production client/frontend
DEV_URL	http://localhost:3000	URL for your development client/frontend

PAYMENTS (Using Payfast)

Variable	Default	Description
NGROK_SERVER_URL	http://localhost:8000/v1	ngrok server url
NGROK_CLIENT_URL	http://localhost:3000	ngrok client url
PAYFAST_PASS_PHRASE	undefined	Payfast Pass Phrase
PAYFAST_MERCHANT_ID	10000100	Payfast Merchant ID
PAYFAST_MERCHANT_KEY	46f0cd694581a	Payfast Merchant Key
PROD_API_URL	undefined	Production Api URL
PAYFAST_PAYMENT_CONFIRM_EMAIL	undefined	Email to send payment confirmation to
process.env.PAYFAST_PAYMENT_METHOD	cc	Payfast Payment method

Middleware Options

You can configure:

• Database name
• Passport.js integration
• Session storage
• CORS settings
• Body parser limits

---

Error Handling

• Authentication failures return 401
• Database errors return 500
• Invalid requests return 400
• Route not found returns 404
• JSON responses include success and message fields
• Detailed errors in development environment

---

Examples

Custom Route Implementation

1// routes/custom/api.routes.js
2const { Router } = require("express");
3
4class CustomRoute {
5  constructor(router, dependencies) {
6    this.router = router;
7    this.dependencies = dependencies;
8  }
9
10  getData(req, res) {
11    res.json({ data: "Protected resource", user: req.user });
12  }
13
14  registerRoutes() {
15    const { authenticate } = this.dependencies.global;
16    this.router.get("/data", authenticate, this.getData);
17  }
18}
19
20module.exports = CustomRoute;

Generating Hash (for any string)

1// namune/utils/gen-hash.js
2const genHash = require("namune/utils/gen-hash.js");
3const hash = genHash({ password: "12345" });

Send an email (Uses nodemailer)

1// namune/utils/sendMail.js
2const sendMail = require("namune/utils/sendMail.js");
3
4// Optional: Transport options. (Below is the dafault setup)
5const transportOptions = {
6  host: "mail.smtp2go.com",
7  port: 80, // 25, 587, and 8025 can also be used (or 2525).
8};
9
10// IMPRTANT:
11// Make sure you have USER and PASS in the .env file for authenticating your email for transport
12
13// Options
14const from = "fromexample@gmail.co";
15const to = "toexample@gmail.co";
16const subject = "Verify account";
17const subject = "Verify account";
18const attachments = [
19  {
20    filename: "emailBanner.png",
21    path: process.cwd() + "/public/img/emailBanner.png",
22    cid: "emailBanner@domiher.com",
23  },
24];
25const html = "<h1> Hi, please verify your account </h1>";
26
27const mailOptions = {
28  from,
29  to,
30  subject,
31  attachments,
32  html,
33};
34
35sendMail(mailOptions);

Lazy-Load Dependencies to avoid circular loop errors

1module.exports = {
2  global: {},
3  models: {},
4  utils: {
5    get myUtil() {
6      return require("./utils/myUtil");
7    },
8  },
9  hooks: {
10    get onFailRegister() {
11      return require("./hooks/register.fail");
12    },
13  },
14};

Pagination

Input

1// For non-routes
2const paginate = require('namune/utils/paginate');
3
4// For routes (api.routes.js)
5// const paginate = this.dependencies.utils.paginate
6
7const data = [
8  { user: { name: "Alice" }, score: 91 },
9  { user: { name: "Charlie" }, score: 82 },
10  { user: { name: "Bob" }, score: 75 },
11];
12
13// Sort by nested property `user.name`
14const result = paginate(data, {
15  page: 1,
16  limit: 2,
17  sortBy: 'user.name',
18  order: 'asc'
19  filterFn: (item) => item.score > 50
20});
21
22console.log(result);

✅ Output Sample

1{
2  data: [
3    { user: { name: "Alice" }, score: 91 },
4    { user: { name: "Bob" }, score: 75 }
5  ],
6  paginationMeta: {
7    page: 1,
8    limit: 2,
9    totalItems: 3,
10    totalPages: 2,
11    hasNext: true,
12    hasPrevious: false,
13    nextPage: 2,
14    previousPage: null
15  }
16}

Options

page: Number Page to go to - Optional (Default is 0) limit: Number Number of items - Optional (Default is 10) sortBy: String Sort the data. Allows for nested properties - Optional (Default is null) order Order the Items by "asc" or "desc" - Optional (Default is "asc") filterFn Filter Function to filter data - Optional (Default is null)

Upload Files to cloud (Uses AWS S3)

1// Non routes
2const { uploadBase64ImageToS3 } = require("namune/utils/cloudFileUpload");
3
4// For routes (api.routes.js)
5// const {uploadBase64ImageToS3} = this.dependencies.utils.cloudFileUpload
6
7let base64 = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA..."; // A base64 image
8uploadBase64ImageToS3(base64).then(console.log);

Options (Second Parameter after base64)

ACL: String For Access Control - Optional (Default is "public-read") appendKey: String Folder in bucket - Optional (Default is "image-upload") region: String Your S3 bucket region - Optional (Default is "eu-north-1")

Other functions (supports multipart/form-data)

uploadImage uploadVideo uploadAudio

Example

1const multer = require("multer");
2const upload = multer(); // memoryStorage by default
3
4// ... Class logic for routes
5registerRoutes(){
6  this.router.post("/upload/image", upload.single("file"), async (req, res) => {
7    const result = await this.dependencies.utils.cloudFileUpload.uploadImage(req.file);
8    res.json(result);
9  });
10
11  this.router.post("/upload/video", upload.single("file"), async (req, res) => {
12    const result = await this.dependencies.utils.cloudFileUpload.uploadVideo(req.file);
13    res.json(result);
14  });
15
16  this.router.post("/upload/audio", upload.single("file"), async (req, res) => {
17    const result = await this.dependencies.utils.cloudFileUpload.uploadAudio(req.file);
18    res.json(result);
19  });
20}

Options for the above functions:

buffer: Buffer - File buffer originalName: String - Original file name (e.g. image.jpg) folder: String - Folder in bucket (e.g. images, audio, videos) options: {ACL: String, ContentType: String} - Optional: ACL, ContentType

Delete uploaded files

deleteFile - Expects a file param deleteMultipleFiles - Expects an array of AWS keys (e.g. ['images/image.jpg', 'images/image2.jpg']) deleteAllFilesInFolder - Expects a prefix (e.g. "images/user123/")

Options

file: {Key: String, VersionId: any, Location: String} - File object uploaded. versionId is optional keys: String[] - Array of Keys

Example

1// Delete specific files
2await deleteMultipleFiles(["images/abc.jpg", "videos/test.mp4"]);
3
4// Delete everything under a folder
5await deleteAllFilesInFolder("images/user123/");

Payments Using Payfast

Example

1// In Routes context
2
3// Making the payment signature
4this.router.get("/order", (req, res) => {
5  const payfast = this.dependencies.utils.payfast;
6
7  const { data, html } = payfast.sig({
8    firstname: order.customerFirstName, // Required
9    lastname: order.customerLastName, // Required
10    email: order.customerEmail, // Required
11    payment_id: `${order.orderNumber}`, // Required
12    amount: `${order.totalPrice}`, // Required
13    order_num: `#${order.orderNumber}`, // Required
14    phone: order.customerPhoneNumber, // Optional
15    address: order.customerAddress, // Optional
16  });
17
18  return res.status(200).json({
19    success: true,
20    message: "Successful!",
21    data: { data, html },
22  });
23
24  /* Data returned from payfast.sig:
25  merchant_id,
26  merchant_key,
27  return_url,
28  cancel_url,
29  notify_url,
30  name_first,
31  name_last,
32  email_address,
33  m_payment_id,
34  amount,
35  item_name,
36  email_confirmation,
37  confirmation_address,
38  payment_method,
39  signature
40  */
41});
42
43// Request from Payfast after cancellation or successful payment
44this.router.post("/notify", async (req, res) => {
45  const { m_payment_id, amount_gross } = await req.body;
46  const payfast = this.dependencies.utils.payfast;
47
48  // Notify/Confirmation
49  payfast.confirm(req, amount_gross);
50
51  return res.status(200).json({
52    success: true,
53    message: "Successful!",
54    data: null,
55  });
56});

Minimal Working Example

1// server.js
2require("dotenv").config();
3const express = require("express");
4const app = express();
5const http = require("http").createServer(app);
6const MidsConfigs = require("namune/config/mids-configs");
7
8const mids = new MidsConfigs(app);
9mids.registerMiddlewares({
10  dbConfig: { database_name: "myapp" },
11  usePassportLogin: true,
12  passportConfig: {
13    userModel: require("./models/User"),
14    usernameField: "email",
15  },
16});
17
18app.use("/api", require("namune/routes/api"));
19
20const PORT = process.env.PORT || 8000;
21http.listen(PORT, () => console.log(`Server running on port ${PORT}`));

---

Contributing

Contributions are welcome!

1. Fork the repository
2. Create your feature branch: git checkout -b feature/your-feature
3. Commit your changes: git commit -am 'Add some feature'
4. Push to the branch: git push origin feature/your-feature
5. Open a pull request

---

License

This project is licensed under the MIT License.