create-listablelabs-api 1.0.1

package/templates/base/src/database/baseModel.js

@@ -0,0 +1,160 @@
+const mongoose = require('mongoose');
+
+/**
+ * Base schema options applied to all models
+ */
+const baseSchemaOptions = {
+  timestamps: true,
+  toJSON: {
+    virtuals: true,
+    transform: (doc, ret) => {
+      ret.id = ret._id.toString();
+      delete ret._id;
+      delete ret.__v;
+      return ret;
+    },
+  },
+  toObject: {
+    virtuals: true,
+  },
+};
+
+/**
+ * Common plugins for all schemas
+ */
+const paginatePlugin = (schema) => {
+  /**
+   * Paginate query results
+   * @param {Object} filter - Mongoose filter query
+   * @param {Object} options - Pagination options
+   * @param {number} options.page - Current page (default: 1)
+   * @param {number} options.limit - Results per page (default: 20)
+   * @param {string} options.sortBy - Sort field (default: createdAt)
+   * @param {string} options.sortOrder - Sort order 'asc' or 'desc' (default: desc)
+   * @param {string} options.populate - Fields to populate
+   */
+  schema.statics.paginate = async function (filter = {}, options = {}) {
+    const {
+      page = 1,
+      limit = 20,
+      sortBy = 'createdAt',
+      sortOrder = 'desc',
+      populate = '',
+    } = options;
+
+    const skip = (page - 1) * limit;
+    const sort = { [sortBy]: sortOrder === 'asc' ? 1 : -1 };
+
+    const [data, total] = await Promise.all([
+      this.find(filter)
+        .sort(sort)
+        .skip(skip)
+        .limit(limit)
+        .populate(populate)
+        .lean(),
+      this.countDocuments(filter),
+    ]);
+
+    return {
+      data,
+      pagination: {
+        page,
+        limit,
+        total,
+        totalPages: Math.ceil(total / limit),
+        hasNextPage: page < Math.ceil(total / limit),
+        hasPrevPage: page > 1,
+      },
+    };
+  };
+};
+
+/**
+ * Soft delete plugin
+ */
+const softDeletePlugin = (schema) => {
+  schema.add({
+    isDeleted: { type: Boolean, default: false },
+    deletedAt: { type: Date, default: null },
+  });
+
+  // Override find methods to exclude soft-deleted docs by default
+  schema.pre(/^find/, function (next) {
+    if (this.getQuery().includeDeleted !== true) {
+      this.where({ isDeleted: false });
+    }
+    next();
+  });
+
+  schema.methods.softDelete = async function () {
+    this.isDeleted = true;
+    this.deletedAt = new Date();
+    return this.save();
+  };
+
+  schema.methods.restore = async function () {
+    this.isDeleted = false;
+    this.deletedAt = null;
+    return this.save();
+  };
+
+  schema.statics.findDeleted = function () {
+    return this.find({ isDeleted: true, includeDeleted: true });
+  };
+};
+
+/**
+ * Create a model with common plugins
+ * @param {string} name - Model name
+ * @param {Object} schemaDefinition - Schema fields
+ * @param {Object} options - Additional options
+ */
+const createModel = (name, schemaDefinition, options = {}) => {
+  const schema = new mongoose.Schema(schemaDefinition, {
+    ...baseSchemaOptions,
+    ...options.schemaOptions,
+  });
+
+  // Apply plugins
+  schema.plugin(paginatePlugin);
+  
+  if (options.softDelete) {
+    schema.plugin(softDeletePlugin);
+  }
+
+  // Add indexes if provided
+  if (options.indexes) {
+    options.indexes.forEach((index) => {
+      schema.index(index.fields, index.options);
+    });
+  }
+
+  // Add methods if provided
+  if (options.methods) {
+    Object.assign(schema.methods, options.methods);
+  }
+
+  // Add statics if provided
+  if (options.statics) {
+    Object.assign(schema.statics, options.statics);
+  }
+
+  // Add virtuals if provided
+  if (options.virtuals) {
+    Object.entries(options.virtuals).forEach(([name, config]) => {
+      const virtual = schema.virtual(name);
+      if (config.get) virtual.get(config.get);
+      if (config.set) virtual.set(config.set);
+    });
+  }
+
+  return mongoose.model(name, schema);
+};
+
+module.exports = {
+  baseSchemaOptions,
+  paginatePlugin,
+  softDeletePlugin,
+  createModel,
+  mongoose,
+};

package/templates/base/src/database/index.js

@@ -0,0 +1,108 @@
+const mongoose = require('mongoose');
+const { logger } = require('../utils/logger');
+const config = require('../config');
+
+/**
+ * MongoDB Atlas Connection
+ * 
+ * Connection string format:
+ * mongodb+srv://<username>:<password>@<cluster>.mongodb.net/<database>?retryWrites=true&w=majority
+ */
+
+const connectDB = async () => {
+  try {
+    const conn = await mongoose.connect(config.mongoUri, {
+      // Connection pool settings
+      maxPoolSize: 10,
+      minPoolSize: 2,
+      
+      // Timeouts
+      serverSelectionTimeoutMS: 5000,
+      socketTimeoutMS: 45000,
+      
+      // Buffering
+      bufferCommands: false,
+    });
+
+    logger.info({
+      host: conn.connection.host,
+      name: conn.connection.name,
+    }, '✅ MongoDB Atlas connected');
+
+    return conn;
+  } catch (err) {
+    logger.fatal({ err }, '❌ MongoDB connection failed');
+    process.exit(1);
+  }
+};
+
+/**
+ * Connection event handlers
+ */
+mongoose.connection.on('connected', () => {
+  logger.debug('Mongoose connected to MongoDB');
+});
+
+mongoose.connection.on('disconnected', () => {
+  logger.warn('Mongoose disconnected from MongoDB');
+});
+
+mongoose.connection.on('error', (err) => {
+  logger.error({ err }, 'Mongoose connection error');
+});
+
+/**
+ * Graceful shutdown
+ */
+const disconnectDB = async () => {
+  try {
+    await mongoose.connection.close();
+    logger.info('MongoDB connection closed');
+  } catch (err) {
+    logger.error({ err }, 'Error closing MongoDB connection');
+  }
+};
+
+/**
+ * Health check
+ */
+const healthCheck = async () => {
+  return mongoose.connection.readyState === 1;
+};
+
+/**
+ * Get connection status for health endpoints
+ */
+const getConnectionStatus = () => {
+  const state = mongoose.connection.readyState;
+  const states = {
+    0: 'disconnected',
+    1: 'connected',
+    2: 'connecting',
+    3: 'disconnecting',
+  };
+  
+  return states[state] || 'unknown';
+};
+
+/**
+ * Get connection stats
+ */
+const getStats = () => {
+  const { connection } = mongoose;
+  return {
+    readyState: connection.readyState,
+    host: connection.host,
+    name: connection.name,
+    collections: Object.keys(connection.collections),
+  };
+};
+
+module.exports = {
+  connectDB,
+  disconnectDB,
+  healthCheck,
+  getConnectionStatus,
+  getStats,
+  mongoose,
+};

package/templates/base/src/middlewares/errorHandler.js

@@ -0,0 +1,155 @@
+const { StatusCodes, ReasonPhrases } = require('http-status-codes');
+const { logger } = require('../utils/logger');
+
+/**
+ * Custom Application Error class
+ * Use this for all operational errors (expected errors)
+ */
+class AppError extends Error {
+  constructor(message, statusCode, errorCode = null) {
+    super(message);
+    this.statusCode = statusCode;
+    this.errorCode = errorCode || this.constructor.name;
+    this.isOperational = true; // Distinguishes operational errors from programming errors
+    this.timestamp = new Date().toISOString();
+
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+
+/**
+ * Common error types for consistent error handling
+ */
+class BadRequestError extends AppError {
+  constructor(message = 'Bad Request') {
+    super(message, StatusCodes.BAD_REQUEST, 'BAD_REQUEST');
+  }
+}
+
+class UnauthorizedError extends AppError {
+  constructor(message = 'Unauthorized') {
+    super(message, StatusCodes.UNAUTHORIZED, 'UNAUTHORIZED');
+  }
+}
+
+class ForbiddenError extends AppError {
+  constructor(message = 'Forbidden') {
+    super(message, StatusCodes.FORBIDDEN, 'FORBIDDEN');
+  }
+}
+
+class NotFoundError extends AppError {
+  constructor(message = 'Resource not found') {
+    super(message, StatusCodes.NOT_FOUND, 'NOT_FOUND');
+  }
+}
+
+class ConflictError extends AppError {
+  constructor(message = 'Resource conflict') {
+    super(message, StatusCodes.CONFLICT, 'CONFLICT');
+  }
+}
+
+class ValidationError extends AppError {
+  constructor(message = 'Validation failed', details = []) {
+    super(message, StatusCodes.UNPROCESSABLE_ENTITY, 'VALIDATION_ERROR');
+    this.details = details;
+  }
+}
+
+class TooManyRequestsError extends AppError {
+  constructor(message = 'Too many requests') {
+    super(message, StatusCodes.TOO_MANY_REQUESTS, 'RATE_LIMIT_EXCEEDED');
+  }
+}
+
+class InternalServerError extends AppError {
+  constructor(message = 'Internal server error') {
+    super(message, StatusCodes.INTERNAL_SERVER_ERROR, 'INTERNAL_ERROR');
+  }
+}
+
+/**
+ * Centralized error handler middleware
+ * Must be registered LAST in middleware chain
+ */
+const errorHandler = (err, req, res, next) => {
+  // Default values for unknown errors
+  let statusCode = err.statusCode || StatusCodes.INTERNAL_SERVER_ERROR;
+  let message = err.message || ReasonPhrases.INTERNAL_SERVER_ERROR;
+  let errorCode = err.errorCode || 'INTERNAL_ERROR';
+
+  // Log the error
+  const errorLog = {
+    requestId: req.id,
+    method: req.method,
+    path: req.originalUrl,
+    statusCode,
+    errorCode,
+    message: err.message,
+    stack: err.stack,
+    isOperational: err.isOperational || false,
+  };
+
+  // Log level based on error type
+  if (err.isOperational) {
+    logger.warn(errorLog, 'Operational error occurred');
+  } else {
+    logger.error(errorLog, 'Unexpected error occurred');
+  }
+
+  // Don't leak internal details in production
+  if (process.env.NODE_ENV === 'production' && !err.isOperational) {
+    message = ReasonPhrases.INTERNAL_SERVER_ERROR;
+    errorCode = 'INTERNAL_ERROR';
+  }
+
+  // Build error response
+  const errorResponse = {
+    success: false,
+    error: {
+      code: errorCode,
+      message,
+      ...(err.details && { details: err.details }),
+    },
+    requestId: req.id,
+    timestamp: new Date().toISOString(),
+  };
+
+  // Include stack trace in development
+  if (process.env.NODE_ENV === 'development') {
+    errorResponse.error.stack = err.stack;
+  }
+
+  res.status(statusCode).json(errorResponse);
+};
+
+/**
+ * Async handler wrapper to catch errors in async route handlers
+ * Usage: router.get('/path', asyncHandler(async (req, res) => { ... }))
+ */
+const asyncHandler = (fn) => (req, res, next) => {
+  Promise.resolve(fn(req, res, next)).catch(next);
+};
+
+/**
+ * 404 Not Found handler for undefined routes
+ */
+const notFoundHandler = (req, res, next) => {
+  next(new NotFoundError(`Route ${req.method} ${req.originalUrl} not found`));
+};
+
+module.exports = {
+  AppError,
+  BadRequestError,
+  UnauthorizedError,
+  ForbiddenError,
+  NotFoundError,
+  ConflictError,
+  ValidationError,
+  TooManyRequestsError,
+  InternalServerError,
+  errorHandler,
+  asyncHandler,
+  notFoundHandler,
+};

package/templates/base/src/middlewares/index.js

@@ -0,0 +1,49 @@
+const requestLogger = require('./requestLogger');
+const {
+  AppError,
+  BadRequestError,
+  UnauthorizedError,
+  ForbiddenError,
+  NotFoundError,
+  ConflictError,
+  ValidationError,
+  TooManyRequestsError,
+  InternalServerError,
+  errorHandler,
+  asyncHandler,
+  notFoundHandler,
+} = require('./errorHandler');
+const { validate, schemas, z, makePartial, pick, omit } = require('./validator');
+const { defaultLimiter, strictLimiter, createLimiter } = require('./rateLimiter');
+
+module.exports = {
+  // Logging
+  requestLogger,
+
+  // Error handling
+  AppError,
+  BadRequestError,
+  UnauthorizedError,
+  ForbiddenError,
+  NotFoundError,
+  ConflictError,
+  ValidationError,
+  TooManyRequestsError,
+  InternalServerError,
+  errorHandler,
+  asyncHandler,
+  notFoundHandler,
+
+  // Validation (Zod)
+  validate,
+  schemas,
+  z,
+  makePartial,
+  pick,
+  omit,
+
+  // Rate limiting
+  defaultLimiter,
+  strictLimiter,
+  createLimiter,
+};

package/templates/base/src/middlewares/rateLimiter.js

@@ -0,0 +1,85 @@
+const rateLimit = require('express-rate-limit');
+const config = require('../config');
+const { TooManyRequestsError } = require('./errorHandler');
+const { logger } = require('../utils/logger');
+
+/**
+ * Default rate limiter
+ * Applies to all routes unless overridden
+ */
+const defaultLimiter = rateLimit({
+  windowMs: config.rateLimit.windowMs,
+  max: config.rateLimit.maxRequests,
+  standardHeaders: true, // Return rate limit info in headers
+  legacyHeaders: false, // Disable X-RateLimit headers
+
+  // Custom key generator - can be modified for user-based limiting
+  keyGenerator: (req) => {
+    return req.ip || req.headers['x-forwarded-for'] || 'unknown';
+  },
+
+  // Skip rate limiting for health checks
+  skip: (req) => {
+    return req.path === '/health' || req.path === '/ready';
+  },
+
+  // Custom handler when limit is exceeded
+  handler: (req, res, next) => {
+    logger.warn({
+      requestId: req.id,
+      ip: req.ip,
+      path: req.originalUrl,
+    }, 'Rate limit exceeded');
+
+    next(new TooManyRequestsError('Too many requests, please try again later'));
+  },
+});
+
+/**
+ * Strict rate limiter for sensitive endpoints (auth, etc.)
+ */
+const strictLimiter = rateLimit({
+  windowMs: 15 * 60 * 1000, // 15 minutes
+  max: 5, // 5 requests per window
+  standardHeaders: true,
+  legacyHeaders: false,
+
+  handler: (req, res, next) => {
+    logger.warn({
+      requestId: req.id,
+      ip: req.ip,
+      path: req.originalUrl,
+    }, 'Strict rate limit exceeded');
+
+    next(new TooManyRequestsError('Too many attempts, please try again later'));
+  },
+});
+
+/**
+ * Create custom rate limiter with specific options
+ * 
+ * @param {Object} options - Rate limiter options
+ * @returns {Function} Rate limiter middleware
+ */
+const createLimiter = (options) => {
+  return rateLimit({
+    standardHeaders: true,
+    legacyHeaders: false,
+    handler: (req, res, next) => {
+      logger.warn({
+        requestId: req.id,
+        ip: req.ip,
+        path: req.originalUrl,
+      }, 'Custom rate limit exceeded');
+
+      next(new TooManyRequestsError(options.message || 'Rate limit exceeded'));
+    },
+    ...options,
+  });
+};
+
+module.exports = {
+  defaultLimiter,
+  strictLimiter,
+  createLimiter,
+};

package/templates/base/src/middlewares/requestLogger.js

@@ -0,0 +1,50 @@
+const pinoHttp = require('pino-http');
+const { v4: uuidv4 } = require('uuid');
+const { logger } = require('../utils/logger');
+
+const requestLogger = pinoHttp({
+  logger,
+
+  // Generate unique request ID
+  genReqId: (req) => {
+    return req.headers['x-request-id'] || uuidv4();
+  },
+
+  // Custom log level based on response status
+  customLogLevel: (req, res, err) => {
+    if (res.statusCode >= 500 || err) return 'error';
+    if (res.statusCode >= 400) return 'warn';
+    return 'info';
+  },
+
+  // Custom success message
+  customSuccessMessage: (req, res) => {
+    return `${req.method} ${req.url} completed`;
+  },
+
+  // Custom error message
+  customErrorMessage: (req, res, err) => {
+    return `${req.method} ${req.url} failed: ${err.message}`;
+  },
+
+  // Custom attributes to add to log
+  customAttributeKeys: {
+    req: 'request',
+    res: 'response',
+    err: 'error',
+    responseTime: 'duration',
+  },
+
+  // Custom props to add to each log
+  customProps: (req, res) => ({
+    requestId: req.id,
+    userAgent: req.headers['user-agent'],
+  }),
+
+  // Don't log health checks to reduce noise
+  autoLogging: {
+    ignore: (req) => req.url === '/health' || req.url === '/ready',
+  },
+});
+
+module.exports = requestLogger;

package/templates/base/src/middlewares/validator.js

@@ -0,0 +1,107 @@
+const { z } = require('zod');
+const { ValidationError } = require('./errorHandler');
+
+/**
+ * Validation middleware factory using Zod
+ * Creates middleware that validates request data against Zod schemas
+ * 
+ * @param {Object} schema - Object containing Zod schemas for body, query, params
+ * @returns {Function} Express middleware
+ * 
+ * Usage:
+ * const schema = {
+ *   body: z.object({ name: z.string().min(1) }),
+ *   params: z.object({ id: z.string().uuid() }),
+ *   query: z.object({ page: z.coerce.number().int().min(1).optional() }),
+ * };
+ * router.post('/users/:id', validate(schema), controller.updateUser);
+ */
+const validate = (schema) => {
+  return (req, res, next) => {
+    const validationErrors = [];
+
+    // Validate each part of the request
+    ['body', 'query', 'params'].forEach((key) => {
+      if (schema[key]) {
+        const result = schema[key].safeParse(req[key]);
+
+        if (!result.success) {
+          result.error.errors.forEach((err) => {
+            validationErrors.push({
+              field: err.path.join('.'),
+              message: err.message,
+              location: key,
+            });
+          });
+        } else {
+          // Replace with validated/transformed values
+          req[key] = result.data;
+        }
+      }
+    });
+
+    if (validationErrors.length > 0) {
+      return next(new ValidationError('Validation failed', validationErrors));
+    }
+
+    next();
+  };
+};
+
+/**
+ * Common Zod schema patterns for reuse
+ */
+const schemas = {
+  // Common field patterns
+  id: z.string().min(1),
+  mongoId: z.string().regex(/^[0-9a-fA-F]{24}$/, 'Invalid MongoDB ObjectId'),
+  uuid: z.string().uuid(),
+  email: z.string().email().toLowerCase().trim(),
+  password: z.string().min(8).max(128),
+  phone: z.string().regex(/^\+?[1-9]\d{1,14}$/, 'Invalid phone number'),
+  
+  // Pagination
+  pagination: z.object({
+    page: z.coerce.number().int().min(1).default(1),
+    limit: z.coerce.number().int().min(1).max(100).default(20),
+    sortBy: z.string().optional(),
+    sortOrder: z.enum(['asc', 'desc']).default('desc'),
+  }),
+
+  // Date range
+  dateRange: z.object({
+    startDate: z.coerce.date(),
+    endDate: z.coerce.date(),
+  }).refine((data) => data.endDate > data.startDate, {
+    message: 'End date must be after start date',
+    path: ['endDate'],
+  }),
+
+  // Common string transformations
+  trimmedString: z.string().trim(),
+  nonEmptyString: z.string().min(1).trim(),
+};
+
+/**
+ * Helper to make all fields in a schema optional (for PATCH requests)
+ */
+const makePartial = (schema) => schema.partial();
+
+/**
+ * Helper to pick specific fields from a schema
+ */
+const pick = (schema, keys) => schema.pick(keys.reduce((acc, key) => ({ ...acc, [key]: true }), {}));
+
+/**
+ * Helper to omit specific fields from a schema
+ */
+const omit = (schema, keys) => schema.omit(keys.reduce((acc, key) => ({ ...acc, [key]: true }), {}));
+
+module.exports = {
+  validate,
+  schemas,
+  makePartial,
+  pick,
+  omit,
+  z, // Re-export Zod for convenience
+};