create-listablelabs-api 1.0.1

package/templates/base/src/models/example.js

@@ -0,0 +1,117 @@
+const { createModel } = require('../database/baseModel');
+const { z } = require('zod');
+
+/**
+ * Zod schema for validation
+ * Use this in routes for request validation
+ */
+const exampleZodSchema = {
+  create: z.object({
+    name: z.string().min(1).max(255),
+    description: z.string().max(1000).optional(),
+    status: z.enum(['active', 'inactive', 'pending']).default('pending'),
+    tags: z.array(z.string()).max(10).optional(),
+    metadata: z.record(z.any()).optional(),
+  }),
+
+  update: z.object({
+    name: z.string().min(1).max(255).optional(),
+    description: z.string().max(1000).optional(),
+    status: z.enum(['active', 'inactive', 'pending']).optional(),
+    tags: z.array(z.string()).max(10).optional(),
+    metadata: z.record(z.any()).optional(),
+  }),
+
+  query: z.object({
+    page: z.coerce.number().int().min(1).default(1),
+    limit: z.coerce.number().int().min(1).max(100).default(20),
+    status: z.enum(['active', 'inactive', 'pending']).optional(),
+    search: z.string().optional(),
+    sortBy: z.enum(['createdAt', 'updatedAt', 'name']).default('createdAt'),
+    sortOrder: z.enum(['asc', 'desc']).default('desc'),
+  }),
+};
+
+/**
+ * Mongoose model
+ */
+const Example = createModel(
+  'Example',
+  {
+    name: {
+      type: String,
+      required: true,
+      trim: true,
+      maxlength: 255,
+    },
+    description: {
+      type: String,
+      trim: true,
+      maxlength: 1000,
+    },
+    status: {
+      type: String,
+      enum: ['active', 'inactive', 'pending'],
+      default: 'pending',
+    },
+    tags: {
+      type: [String],
+      default: [],
+    },
+    metadata: {
+      type: Map,
+      of: String,
+    },
+  },
+  {
+    // Enable soft delete
+    softDelete: true,
+
+    // Add indexes
+    indexes: [
+      { fields: { name: 'text', description: 'text' } },
+      { fields: { status: 1 } },
+      { fields: { tags: 1 } },
+      { fields: { createdAt: -1 } },
+    ],
+
+    // Custom static methods
+    statics: {
+      async findByStatus(status) {
+        return this.find({ status });
+      },
+
+      async search(query, options = {}) {
+        const filter = {};
+        
+        if (query.search) {
+          filter.$text = { $search: query.search };
+        }
+        
+        if (query.status) {
+          filter.status = query.status;
+        }
+
+        return this.paginate(filter, options);
+      },
+    },
+
+    // Custom instance methods
+    methods: {
+      activate() {
+        this.status = 'active';
+        return this.save();
+      },
+
+      deactivate() {
+        this.status = 'inactive';
+        return this.save();
+      },
+    },
+  }
+);
+
+module.exports = {
+  Example,
+  exampleZodSchema,
+};

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

@@ -0,0 +1,6 @@
+const { Example, exampleZodSchema } = require('./example');
+
+module.exports = {
+  Example,
+  exampleZodSchema,
+};

package/templates/base/src/routes/v1/exampleRoutes.js

@@ -0,0 +1,89 @@
+const { Router } = require('express');
+const exampleController = require('../../controllers/exampleController');
+const { validate, z } = require('../../middlewares');
+const { exampleZodSchema } = require('../../models');
+
+const router = Router();
+
+/**
+ * Validation schemas
+ */
+const schemas = {
+  getById: {
+    params: z.object({
+      id: z.string().regex(/^[0-9a-fA-F]{24}$/, 'Invalid ID format'),
+    }),
+  },
+
+  getAll: {
+    query: exampleZodSchema.query,
+  },
+
+  create: {
+    body: exampleZodSchema.create,
+  },
+
+  update: {
+    params: z.object({
+      id: z.string().regex(/^[0-9a-fA-F]{24}$/, 'Invalid ID format'),
+    }),
+    body: exampleZodSchema.update,
+  },
+
+  delete: {
+    params: z.object({
+      id: z.string().regex(/^[0-9a-fA-F]{24}$/, 'Invalid ID format'),
+    }),
+  },
+};
+
+/**
+ * @route   GET /api/v1/examples
+ * @desc    Get all examples with pagination
+ * @access  Public
+ */
+router.get('/', validate(schemas.getAll), exampleController.getAll);
+
+/**
+ * @route   GET /api/v1/examples/:id
+ * @desc    Get example by ID
+ * @access  Public
+ */
+router.get('/:id', validate(schemas.getById), exampleController.getById);
+
+/**
+ * @route   POST /api/v1/examples
+ * @desc    Create new example
+ * @access  Public
+ */
+router.post('/', validate(schemas.create), exampleController.create);
+
+/**
+ * @route   PUT /api/v1/examples/:id
+ * @desc    Update example
+ * @access  Public
+ */
+router.put('/:id', validate(schemas.update), exampleController.update);
+
+/**
+ * @route   DELETE /api/v1/examples/:id
+ * @desc    Delete example (soft delete)
+ * @access  Public
+ */
+router.delete('/:id', validate(schemas.delete), exampleController.remove);
+
+/**
+ * @route   PATCH /api/v1/examples/:id/activate
+ * @desc    Activate example
+ * @access  Public
+ */
+router.patch('/:id/activate', validate(schemas.getById), exampleController.activate);
+
+/**
+ * @route   PATCH /api/v1/examples/:id/deactivate
+ * @desc    Deactivate example
+ * @access  Public
+ */
+router.patch('/:id/deactivate', validate(schemas.getById), exampleController.deactivate);
+
+module.exports = router;

package/templates/base/src/routes/v1/index.js

@@ -0,0 +1,19 @@
+const { Router } = require('express');
+const exampleRoutes = require('./exampleRoutes');
+
+const router = Router();
+
+/**
+ * Register all route modules here
+ * Each module handles its own sub-routes
+ */
+
+// Example routes - replace with your actual routes
+router.use('/examples', exampleRoutes);
+
+// Add more route modules as needed:
+// router.use('/users', userRoutes);
+// router.use('/products', productRoutes);
+// router.use('/orders', orderRoutes);
+
+module.exports = router;

package/templates/base/src/server.js

@@ -0,0 +1,80 @@
+const app = require('./app');
+const config = require('./config');
+const { logger } = require('./utils/logger');
+const { connectDB, disconnectDB } = require('./database');
+
+/**
+ * Start the server
+ */
+const startServer = async () => {
+  try {
+    // Connect to MongoDB Atlas
+    await connectDB();
+
+    // Start Express server
+    const server = app.listen(config.port, () => {
+      logger.info({
+        port: config.port,
+        env: config.env,
+        service: config.serviceName,
+      }, `🚀 ${config.serviceName} is running on port ${config.port}`);
+    });
+
+    /**
+     * Graceful shutdown handling
+     */
+    const gracefulShutdown = async (signal) => {
+      logger.info({ signal }, 'Received shutdown signal, starting graceful shutdown...');
+
+      // Stop accepting new requests
+      server.close(async (err) => {
+        if (err) {
+          logger.error({ err }, 'Error during server close');
+          process.exit(1);
+        }
+
+        logger.info('Server closed successfully');
+
+        // Close database connection
+        await disconnectDB();
+
+        logger.info('All connections closed, exiting process');
+        process.exit(0);
+      });
+
+      // Force shutdown after timeout
+      setTimeout(() => {
+        logger.error('Forced shutdown due to timeout');
+        process.exit(1);
+      }, 30000); // 30 seconds timeout
+    };
+
+    // Handle shutdown signals
+    process.on('SIGTERM', () => gracefulShutdown('SIGTERM'));
+    process.on('SIGINT', () => gracefulShutdown('SIGINT'));
+
+    return server;
+  } catch (err) {
+    logger.fatal({ err }, 'Failed to start server');
+    process.exit(1);
+  }
+};
+
+/**
+ * Handle uncaught exceptions
+ */
+process.on('uncaughtException', (err) => {
+  logger.fatal({ err }, 'Uncaught exception');
+  process.exit(1);
+});
+
+/**
+ * Handle unhandled promise rejections
+ */
+process.on('unhandledRejection', (reason, promise) => {
+  logger.fatal({ reason, promise }, 'Unhandled promise rejection');
+  process.exit(1);
+});
+
+// Start the server
+startServer();

package/templates/base/src/utils/logger.js

@@ -0,0 +1,61 @@
+const pino = require('pino');
+const config = require('../config');
+
+// Base logger instance
+const logger = pino({
+  name: config.serviceName,
+  level: config.logLevel,
+  
+  // Custom serializers for consistent log format
+  serializers: {
+    req: (req) => ({
+      method: req.method,
+      url: req.url,
+      path: req.path,
+      params: req.params,
+      query: req.query,
+      headers: {
+        'user-agent': req.headers['user-agent'],
+        'content-type': req.headers['content-type'],
+        'x-request-id': req.headers['x-request-id'],
+      },
+    }),
+    res: (res) => ({
+      statusCode: res.statusCode,
+    }),
+    err: pino.stdSerializers.err,
+  },
+
+  // Add base context to all logs
+  base: {
+    service: config.serviceName,
+    env: config.env,
+    pid: process.pid,
+  },
+
+  // Timestamp format
+  timestamp: pino.stdTimeFunctions.isoTime,
+
+  // Pretty print in development
+  transport:
+    config.env === 'development'
+      ? {
+          target: 'pino-pretty',
+          options: {
+            colorize: true,
+            translateTime: 'SYS:standard',
+            ignore: 'pid,hostname',
+          },
+        }
+      : undefined,
+});
+
+// Create child logger with additional context
+const createChildLogger = (context) => {
+  return logger.child(context);
+};
+
+module.exports = {
+  logger,
+  createChildLogger,
+};

package/templates/base/src/utils/response.js

@@ -0,0 +1,117 @@
+const { StatusCodes } = require('http-status-codes');
+
+/**
+ * Standard API response formatter
+ * Ensures all responses follow the same structure
+ */
+
+/**
+ * Send success response
+ * @param {Object} res - Express response object
+ * @param {Object} data - Response data
+ * @param {number} statusCode - HTTP status code (default: 200)
+ * @param {string} message - Optional success message
+ */
+const sendSuccess = (res, data = null, statusCode = StatusCodes.OK, message = null) => {
+  const response = {
+    success: true,
+    ...(message && { message }),
+    ...(data !== null && { data }),
+    timestamp: new Date().toISOString(),
+  };
+
+  return res.status(statusCode).json(response);
+};
+
+/**
+ * Send created response (201)
+ * @param {Object} res - Express response object
+ * @param {Object} data - Created resource data
+ * @param {string} message - Optional message
+ */
+const sendCreated = (res, data, message = 'Resource created successfully') => {
+  return sendSuccess(res, data, StatusCodes.CREATED, message);
+};
+
+/**
+ * Send no content response (204)
+ * @param {Object} res - Express response object
+ */
+const sendNoContent = (res) => {
+  return res.status(StatusCodes.NO_CONTENT).send();
+};
+
+/**
+ * Send paginated response
+ * @param {Object} res - Express response object
+ * @param {Array} data - Array of items
+ * @param {Object} pagination - Pagination info
+ * @param {number} pagination.page - Current page
+ * @param {number} pagination.limit - Items per page
+ * @param {number} pagination.total - Total items
+ */
+const sendPaginated = (res, data, { page, limit, total }) => {
+  const totalPages = Math.ceil(total / limit);
+
+  const response = {
+    success: true,
+    data,
+    pagination: {
+      page,
+      limit,
+      total,
+      totalPages,
+      hasNextPage: page < totalPages,
+      hasPrevPage: page > 1,
+    },
+    timestamp: new Date().toISOString(),
+  };
+
+  return res.status(StatusCodes.OK).json(response);
+};
+
+/**
+ * Response builder for complex responses
+ * Usage: responseBuilder(res).data(users).message('Users fetched').status(200).send()
+ */
+const responseBuilder = (res) => {
+  const response = {
+    success: true,
+    timestamp: new Date().toISOString(),
+  };
+  let statusCode = StatusCodes.OK;
+
+  return {
+    data(data) {
+      response.data = data;
+      return this;
+    },
+    message(msg) {
+      response.message = msg;
+      return this;
+    },
+    status(code) {
+      statusCode = code;
+      return this;
+    },
+    meta(meta) {
+      response.meta = meta;
+      return this;
+    },
+    pagination(paginationData) {
+      response.pagination = paginationData;
+      return this;
+    },
+    send() {
+      return res.status(statusCode).json(response);
+    },
+  };
+};
+
+module.exports = {
+  sendSuccess,
+  sendCreated,
+  sendNoContent,
+  sendPaginated,
+  responseBuilder,
+};

package/templates/base/tests/app.test.js

@@ -0,0 +1,215 @@
+const request = require('supertest');
+const app = require('../src/app');
+const { Example } = require('../src/models');
+
+describe('Health Endpoints', () => {
+  describe('GET /health', () => {
+    it('should return healthy status', async () => {
+      const res = await request(app).get('/health');
+
+      expect(res.statusCode).toBe(200);
+      expect(res.body).toHaveProperty('status', 'healthy');
+      expect(res.body).toHaveProperty('service');
+      expect(res.body).toHaveProperty('timestamp');
+      expect(res.body).toHaveProperty('uptime');
+    });
+  });
+
+  describe('GET /ready', () => {
+    it('should return ready status when DB is connected', async () => {
+      const res = await request(app).get('/ready');
+
+      expect(res.statusCode).toBe(200);
+      expect(res.body).toHaveProperty('status', 'ready');
+      expect(res.body.checks).toHaveProperty('database');
+    });
+  });
+});
+
+describe('Example API Endpoints', () => {
+  describe('GET /api/v1/examples', () => {
+    it('should return empty array when no examples exist', async () => {
+      const res = await request(app).get('/api/v1/examples');
+
+      expect(res.statusCode).toBe(200);
+      expect(res.body).toHaveProperty('success', true);
+      expect(res.body.data).toEqual([]);
+      expect(res.body.pagination.total).toBe(0);
+    });
+
+    it('should return paginated examples', async () => {
+      // Create test data
+      await Example.create([
+        { name: 'Test 1' },
+        { name: 'Test 2' },
+        { name: 'Test 3' },
+      ]);
+
+      const res = await request(app)
+        .get('/api/v1/examples')
+        .query({ page: 1, limit: 2 });
+
+      expect(res.statusCode).toBe(200);
+      expect(res.body.data).toHaveLength(2);
+      expect(res.body.pagination.page).toBe(1);
+      expect(res.body.pagination.limit).toBe(2);
+      expect(res.body.pagination.total).toBe(3);
+      expect(res.body.pagination.totalPages).toBe(2);
+    });
+
+    it('should filter by status', async () => {
+      await Example.create([
+        { name: 'Active 1', status: 'active' },
+        { name: 'Active 2', status: 'active' },
+        { name: 'Inactive', status: 'inactive' },
+      ]);
+
+      const res = await request(app)
+        .get('/api/v1/examples')
+        .query({ status: 'active' });
+
+      expect(res.statusCode).toBe(200);
+      expect(res.body.data).toHaveLength(2);
+      expect(res.body.data.every((item) => item.status === 'active')).toBe(true);
+    });
+  });
+
+  describe('GET /api/v1/examples/:id', () => {
+    it('should return example by ID', async () => {
+      const example = await Example.create({ name: 'Test Example' });
+
+      const res = await request(app).get(`/api/v1/examples/${example._id}`);
+
+      expect(res.statusCode).toBe(200);
+      expect(res.body.success).toBe(true);
+      expect(res.body.data.name).toBe('Test Example');
+    });
+
+    it('should return 404 for non-existent ID', async () => {
+      const fakeId = '507f1f77bcf86cd799439011';
+      const res = await request(app).get(`/api/v1/examples/${fakeId}`);
+
+      expect(res.statusCode).toBe(404);
+      expect(res.body.success).toBe(false);
+      expect(res.body.error.code).toBe('NOT_FOUND');
+    });
+
+    it('should return 422 for invalid ID format', async () => {
+      const res = await request(app).get('/api/v1/examples/invalid-id');
+
+      expect(res.statusCode).toBe(422);
+      expect(res.body.success).toBe(false);
+      expect(res.body.error.code).toBe('VALIDATION_ERROR');
+    });
+  });
+
+  describe('POST /api/v1/examples', () => {
+    it('should create new example', async () => {
+      const res = await request(app)
+        .post('/api/v1/examples')
+        .send({ name: 'New Example', description: 'Test description' });
+
+      expect(res.statusCode).toBe(201);
+      expect(res.body.success).toBe(true);
+      expect(res.body.data.name).toBe('New Example');
+      expect(res.body.data.status).toBe('pending'); // default value
+
+      // Verify it's in the database
+      const example = await Example.findById(res.body.data.id);
+      expect(example).not.toBeNull();
+    });
+
+    it('should return validation error for missing name', async () => {
+      const res = await request(app)
+        .post('/api/v1/examples')
+        .send({ description: 'No name provided' });
+
+      expect(res.statusCode).toBe(422);
+      expect(res.body.success).toBe(false);
+      expect(res.body.error.code).toBe('VALIDATION_ERROR');
+    });
+
+    it('should validate status enum', async () => {
+      const res = await request(app)
+        .post('/api/v1/examples')
+        .send({ name: 'Test', status: 'invalid-status' });
+
+      expect(res.statusCode).toBe(422);
+      expect(res.body.error.code).toBe('VALIDATION_ERROR');
+    });
+  });
+
+  describe('PUT /api/v1/examples/:id', () => {
+    it('should update example', async () => {
+      const example = await Example.create({ name: 'Original' });
+
+      const res = await request(app)
+        .put(`/api/v1/examples/${example._id}`)
+        .send({ name: 'Updated' });
+
+      expect(res.statusCode).toBe(200);
+      expect(res.body.success).toBe(true);
+      expect(res.body.data.name).toBe('Updated');
+    });
+
+    it('should return 404 for non-existent ID', async () => {
+      const fakeId = '507f1f77bcf86cd799439011';
+      const res = await request(app)
+        .put(`/api/v1/examples/${fakeId}`)
+        .send({ name: 'Updated' });
+
+      expect(res.statusCode).toBe(404);
+    });
+  });
+
+  describe('DELETE /api/v1/examples/:id', () => {
+    it('should soft delete example', async () => {
+      const example = await Example.create({ name: 'To Delete' });
+
+      const res = await request(app).delete(`/api/v1/examples/${example._id}`);
+
+      expect(res.statusCode).toBe(204);
+
+      // Verify soft delete (not actually removed)
+      const deleted = await Example.findOne({
+        _id: example._id,
+        includeDeleted: true,
+      });
+      expect(deleted).not.toBeNull();
+    });
+  });
+
+  describe('PATCH /api/v1/examples/:id/activate', () => {
+    it('should activate example', async () => {
+      const example = await Example.create({ name: 'Test', status: 'pending' });
+
+      const res = await request(app).patch(`/api/v1/examples/${example._id}/activate`);
+
+      expect(res.statusCode).toBe(200);
+      expect(res.body.data.status).toBe('active');
+    });
+  });
+
+  describe('PATCH /api/v1/examples/:id/deactivate', () => {
+    it('should deactivate example', async () => {
+      const example = await Example.create({ name: 'Test', status: 'active' });
+
+      const res = await request(app).patch(`/api/v1/examples/${example._id}/deactivate`);
+
+      expect(res.statusCode).toBe(200);
+      expect(res.body.data.status).toBe('inactive');
+    });
+  });
+});
+
+describe('Error Handling', () => {
+  describe('404 Not Found', () => {
+    it('should return 404 for undefined routes', async () => {
+      const res = await request(app).get('/api/v1/nonexistent');
+
+      expect(res.statusCode).toBe(404);
+      expect(res.body.success).toBe(false);
+      expect(res.body.error.code).toBe('NOT_FOUND');
+    });
+  });
+});