create-listablelabs-api 1.0.1

package/templates/base/README.md

@@ -0,0 +1,295 @@
+# ListableLabs Microservice Template
+
+A production-ready Node.js/Express microservice template with MongoDB Atlas, Zod validation, Pino logging, and best practices.
+
+## 🚀 Quick Start
+
+```bash
+# Clone and setup
+git clone <repo-url> my-service
+cd my-service
+npm install
+
+# Configure environment
+cp .env.example .env
+# Edit .env with your MongoDB Atlas URI and service name
+
+# Start development
+npm run dev
+```
+
+## 📁 Project Structure
+
+```
+├── src/
+│   ├── config/           # Configuration (env vars)
+│   ├── controllers/      # Request handlers
+│   ├── database/         # MongoDB connection & base model
+│   ├── middlewares/      # Express middlewares
+│   │   ├── errorHandler.js   # Centralized error handling
+│   │   ├── rateLimiter.js    # Rate limiting
+│   │   ├── requestLogger.js  # Pino HTTP logging
+│   │   └── validator.js      # Zod validation
+│   ├── models/           # Mongoose models + Zod schemas
+│   ├── routes/v1/        # API routes
+│   ├── utils/
+│   │   ├── logger.js     # Pino logger
+│   │   └── response.js   # Standard responses
+│   ├── app.js            # Express setup
+│   └── server.js         # Entry point
+├── tests/                # Jest tests with mongodb-memory-server
+├── Dockerfile
+└── docker-compose.yml
+```
+
+## 🔧 Scripts
+
+```bash
+npm start         # Production server
+npm run dev       # Development with nodemon
+npm test          # Run tests with coverage
+npm run lint      # ESLint check
+npm run lint:fix  # Auto-fix lint errors
+```
+
+## 📝 Creating New Endpoints
+
+### 1. Create Model with Zod Schema
+
+```javascript
+// src/models/user.js
+const { createModel } = require('../database/baseModel');
+const { z } = require('zod');
+
+// Zod schemas for validation
+const userZodSchema = {
+  create: z.object({
+    email: z.string().email(),
+    name: z.string().min(1).max(100),
+    role: z.enum(['user', 'admin']).default('user'),
+  }),
+  update: z.object({
+    name: z.string().min(1).max(100).optional(),
+    role: z.enum(['user', 'admin']).optional(),
+  }),
+};
+
+// Mongoose model
+const User = createModel('User', {
+  email: { type: String, required: true, unique: true },
+  name: { type: String, required: true },
+  role: { type: String, enum: ['user', 'admin'], default: 'user' },
+}, {
+  softDelete: true, // enables soft delete
+  indexes: [{ fields: { email: 1 }, options: { unique: true } }],
+});
+
+module.exports = { User, userZodSchema };
+```
+
+### 2. Create Controller
+
+```javascript
+// src/controllers/userController.js
+const { asyncHandler, NotFoundError } = require('../middlewares');
+const { sendSuccess, sendCreated, sendPaginated } = require('../utils/response');
+const { User } = require('../models');
+
+const getAll = asyncHandler(async (req, res) => {
+  const result = await User.paginate({}, req.query);
+  sendPaginated(res, result.data, result.pagination);
+});
+
+const create = asyncHandler(async (req, res) => {
+  const user = await User.create(req.body);
+  sendCreated(res, user);
+});
+
+module.exports = { getAll, create };
+```
+
+### 3. Create Routes with Validation
+
+```javascript
+// src/routes/v1/userRoutes.js
+const { Router } = require('express');
+const { validate, z } = require('../../middlewares');
+const { userZodSchema } = require('../../models');
+const userController = require('../../controllers/userController');
+
+const router = Router();
+
+router.get('/', userController.getAll);
+router.post('/', validate({ body: userZodSchema.create }), userController.create);
+
+module.exports = router;
+```
+
+### 4. Register in routes/v1/index.js
+
+```javascript
+const userRoutes = require('./userRoutes');
+router.use('/users', userRoutes);
+```
+
+## ✅ Validation with Zod
+
+```javascript
+const { validate, z, schemas } = require('./middlewares');
+
+// Custom schema
+const schema = {
+  body: z.object({
+    email: z.string().email(),
+    age: z.number().int().min(18),
+  }),
+  query: z.object({
+    page: z.coerce.number().int().min(1).default(1),
+  }),
+  params: z.object({
+    id: schemas.mongoId, // reusable pattern
+  }),
+};
+
+router.post('/users/:id', validate(schema), controller.update);
+```
+
+### Reusable Schema Patterns
+
+```javascript
+const { schemas } = require('./middlewares');
+
+schemas.mongoId      // MongoDB ObjectId validation
+schemas.email        // Email with lowercase trim
+schemas.pagination   // page, limit, sortBy, sortOrder
+schemas.dateRange    // startDate, endDate validation
+```
+
+## 🪵 Logging with Pino
+
+```javascript
+const { logger, createChildLogger } = require('./utils/logger');
+
+// Direct logging
+logger.info({ userId: 123 }, 'User logged in');
+logger.error({ err }, 'Database error');
+
+// Child logger with context
+const log = createChildLogger({ module: 'paymentService' });
+log.info({ orderId: 456 }, 'Processing payment');
+```
+
+**Log Output (JSON in production):**
+```json
+{
+  "level": 30,
+  "time": "2024-01-15T10:30:00.000Z",
+  "service": "my-service",
+  "module": "paymentService",
+  "orderId": 456,
+  "msg": "Processing payment"
+}
+```
+
+## ❌ Error Handling
+
+```javascript
+const {
+  BadRequestError,      // 400
+  UnauthorizedError,    // 401
+  ForbiddenError,       // 403
+  NotFoundError,        // 404
+  ConflictError,        // 409
+  ValidationError,      // 422
+  TooManyRequestsError, // 429
+} = require('./middlewares');
+
+// Throw anywhere - caught by error handler
+throw new NotFoundError('User not found');
+throw new ValidationError('Invalid input', [
+  { field: 'email', message: 'Invalid format' }
+]);
+```
+
+**Error Response:**
+```json
+{
+  "success": false,
+  "error": {
+    "code": "NOT_FOUND",
+    "message": "User not found"
+  },
+  "requestId": "abc-123",
+  "timestamp": "2024-01-15T10:30:00.000Z"
+}
+```
+
+## 📊 Standard Responses
+
+```javascript
+const { sendSuccess, sendCreated, sendPaginated, sendNoContent } = require('./utils/response');
+
+sendSuccess(res, data);                    // 200
+sendCreated(res, newUser);                 // 201
+sendPaginated(res, items, pagination);     // 200 with pagination
+sendNoContent(res);                        // 204
+```
+
+## 🗄️ MongoDB Atlas Setup
+
+1. Create cluster at [MongoDB Atlas](https://www.mongodb.com/atlas)
+2. Get connection string: `mongodb+srv://<user>:<pass>@cluster.mongodb.net/<db>`
+3. Add to `.env`:
+   ```
+   MONGODB_URI=mongodb+srv://username:password@cluster.mongodb.net/mydb?retryWrites=true&w=majority
+   ```
+4. Whitelist your IP in Atlas Network Access
+
+## 🧪 Testing
+
+Tests use `mongodb-memory-server` for isolated in-memory MongoDB:
+
+```bash
+npm test              # Run all tests
+npm run test:watch    # Watch mode
+```
+
+```javascript
+// tests/user.test.js
+const request = require('supertest');
+const app = require('../src/app');
+const { User } = require('../src/models');
+
+describe('POST /api/v1/users', () => {
+  it('should create user', async () => {
+    const res = await request(app)
+      .post('/api/v1/users')
+      .send({ email: 'test@example.com', name: 'Test' });
+
+    expect(res.status).toBe(201);
+    expect(res.body.data.email).toBe('test@example.com');
+  });
+});
+```
+
+## 🐳 Docker
+
+```bash
+docker build -t my-service .
+docker run -p 3000:3000 -e MONGODB_URI=... my-service
+```
+
+## 🏥 Health Checks
+
+- `GET /health` - Liveness (always 200 if running)
+- `GET /ready` - Readiness (checks DB connection)
+
+## 📋 New Service Checklist
+
+- [ ] Update `SERVICE_NAME` in `.env`
+- [ ] Update `name` in `package.json`
+- [ ] Configure `MONGODB_URI` for your database
+- [ ] Remove example routes/models
+- [ ] Add your models in `src/models/`
+- [ ] Add your routes in `src/routes/v1/`
+- [ ] Write tests

package/templates/base/docker-compose.yml

@@ -0,0 +1,55 @@
+version: '3.8'
+
+services:
+  api:
+    build:
+      context: .
+      target: production
+    ports:
+      - "3000:3000"
+    environment:
+      - NODE_ENV=production
+      - PORT=3000
+      - SERVICE_NAME=my-service
+      - LOG_LEVEL=info
+    healthcheck:
+      test: ["CMD", "node", "-e", "require('http').get('http://localhost:3000/health', (r) => process.exit(r.statusCode === 200 ? 0 : 1))"]
+      interval: 30s
+      timeout: 3s
+      retries: 3
+      start_period: 5s
+    restart: unless-stopped
+
+  # Uncomment and configure as needed:
+  
+  # redis:
+  #   image: redis:7-alpine
+  #   ports:
+  #     - "6379:6379"
+  #   volumes:
+  #     - redis-data:/data
+  #   healthcheck:
+  #     test: ["CMD", "redis-cli", "ping"]
+  #     interval: 10s
+  #     timeout: 5s
+  #     retries: 5
+
+  # postgres:
+  #   image: postgres:15-alpine
+  #   ports:
+  #     - "5432:5432"
+  #   environment:
+  #     - POSTGRES_USER=user
+  #     - POSTGRES_PASSWORD=password
+  #     - POSTGRES_DB=mydb
+  #   volumes:
+  #     - postgres-data:/var/lib/postgresql/data
+  #   healthcheck:
+  #     test: ["CMD-SHELL", "pg_isready -U user -d mydb"]
+  #     interval: 10s
+  #     timeout: 5s
+  #     retries: 5
+
+# volumes:
+#   redis-data:
+#   postgres-data:

package/templates/base/jest.config.js

@@ -0,0 +1,24 @@
+module.exports = {
+  testEnvironment: 'node',
+  coverageDirectory: 'coverage',
+  collectCoverageFrom: [
+    'src/**/*.js',
+    '!src/server.js',
+  ],
+  coverageThreshold: {
+    global: {
+      branches: 70,
+      functions: 70,
+      lines: 70,
+      statements: 70,
+    },
+  },
+  testMatch: ['**/tests/**/*.test.js'],
+  setupFilesAfterEnv: ['./tests/setup.js'],
+  verbose: true,
+  forceExit: true,
+  clearMocks: true,
+  resetMocks: true,
+  restoreMocks: true,
+  testTimeout: 30000,
+};

package/templates/base/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "listablelabs-service",
+  "version": "1.0.0",
+  "description": "Microservice template - replace service-name with your service",
+  "main": "src/server.js",
+  "scripts": {
+    "start": "node src/server.js",
+    "dev": "nodemon src/server.js",
+    "test": "jest --coverage",
+    "test:watch": "jest --watch",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
+    "docker:build": "docker build -t service-name .",
+    "docker:run": "docker run -p 3000:3000 service-name"
+  },
+  "dependencies": {
+    "express": "^4.18.2",
+    "helmet": "^7.1.0",
+    "cors": "^2.8.5",
+    "compression": "^1.7.4",
+    "pino": "^8.17.2",
+    "pino-http": "^9.0.0",
+    "zod": "^3.22.4",
+    "dotenv": "^16.3.1",
+    "express-rate-limit": "^7.1.5",
+    "uuid": "^9.0.1",
+    "http-status-codes": "^2.3.0",
+    "mongoose": "^8.0.3"
+  },
+  "devDependencies": {
+    "nodemon": "^3.0.2",
+    "jest": "^29.7.0",
+    "supertest": "^6.3.3",
+    "eslint": "^8.56.0",
+    "pino-pretty": "^10.3.1",
+    "mongodb-memory-server": "^9.1.6"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/templates/base/src/app.js

@@ -0,0 +1,103 @@
+const express = require('express');
+const helmet = require('helmet');
+const cors = require('cors');
+const compression = require('compression');
+const config = require('./config');
+const {
+  requestLogger,
+  errorHandler,
+  notFoundHandler,
+  defaultLimiter,
+} = require('./middlewares');
+const { healthCheck, getConnectionStatus } = require('./database');
+const routes = require('./routes/v1');
+
+const app = express();
+
+/**
+ * Security middleware
+ */
+app.use(helmet()); // Security headers
+app.use(cors()); // CORS handling
+
+/**
+ * Request parsing
+ */
+app.use(express.json({ limit: '10kb' })); // Parse JSON bodies
+app.use(express.urlencoded({ extended: true, limit: '10kb' })); // Parse URL-encoded bodies
+
+/**
+ * Compression
+ */
+app.use(compression());
+
+/**
+ * Request logging - logs all incoming requests
+ */
+app.use(requestLogger);
+
+/**
+ * Rate limiting - applies to all routes
+ */
+app.use(defaultLimiter);
+
+/**
+ * Health check endpoint (liveness probe)
+ * Returns 200 if the service is running
+ */
+app.get('/health', (req, res) => {
+  res.json({
+    status: 'healthy',
+    service: config.serviceName,
+    timestamp: new Date().toISOString(),
+    uptime: process.uptime(),
+  });
+});
+
+/**
+ * Readiness check endpoint (readiness probe)
+ * Returns 200 only if all dependencies are ready
+ */
+app.get('/ready', async (req, res) => {
+  const dbHealthy = await healthCheck();
+  
+  const status = {
+    service: config.serviceName,
+    timestamp: new Date().toISOString(),
+    checks: {
+      database: {
+        status: dbHealthy ? 'healthy' : 'unhealthy',
+        connection: getConnectionStatus(),
+      },
+    },
+  };
+
+  if (!dbHealthy) {
+    return res.status(503).json({
+      status: 'not ready',
+      ...status,
+    });
+  }
+
+  res.json({
+    status: 'ready',
+    ...status,
+  });
+});
+
+/**
+ * API routes
+ */
+app.use('/api/v1', routes);
+
+/**
+ * 404 handler for undefined routes
+ */
+app.use(notFoundHandler);
+
+/**
+ * Global error handler - must be last
+ */
+app.use(errorHandler);
+
+module.exports = app;

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

@@ -0,0 +1,36 @@
+require('dotenv').config();
+
+const config = {
+  // Application
+  env: process.env.NODE_ENV || 'development',
+  port: parseInt(process.env.PORT, 10) || 3000,
+  serviceName: process.env.SERVICE_NAME || 'unknown-service',
+
+  // Logging
+  logLevel: process.env.LOG_LEVEL || 'info',
+
+  // Rate Limiting
+  rateLimit: {
+    windowMs: parseInt(process.env.RATE_LIMIT_WINDOW_MS, 10) || 60000,
+    maxRequests: parseInt(process.env.RATE_LIMIT_MAX_REQUESTS, 10) || 100,
+  },
+
+  // MongoDB Atlas
+  mongoUri: process.env.MONGODB_URI,
+
+  // JWT (configure as needed)
+  // jwt: {
+  //   secret: process.env.JWT_SECRET,
+  //   expiresIn: process.env.JWT_EXPIRES_IN || '1d',
+  // },
+};
+
+// Validate required config
+const requiredEnvVars = ['SERVICE_NAME', 'MONGODB_URI'];
+const missingEnvVars = requiredEnvVars.filter((envVar) => !process.env[envVar]);
+
+if (missingEnvVars.length > 0 && process.env.NODE_ENV !== 'test') {
+  throw new Error(`Missing required environment variables: ${missingEnvVars.join(', ')}`);
+}
+
+module.exports = config;

package/templates/base/src/controllers/exampleController.js

@@ -0,0 +1,148 @@
+const { asyncHandler, NotFoundError } = require('../middlewares');
+const { sendSuccess, sendCreated, sendPaginated, sendNoContent } = require('../utils/response');
+const { createChildLogger } = require('../utils/logger');
+const { Example } = require('../models');
+
+const log = createChildLogger({ module: 'exampleController' });
+
+/**
+ * Get all examples with pagination
+ * GET /api/v1/examples
+ */
+const getAll = asyncHandler(async (req, res) => {
+  const { page, limit, status, search, sortBy, sortOrder } = req.query;
+
+  log.info({ page, limit, status, search }, 'Fetching examples');
+
+  const result = await Example.search(
+    { status, search },
+    { page, limit, sortBy, sortOrder }
+  );
+
+  sendPaginated(res, result.data, result.pagination);
+});
+
+/**
+ * Get example by ID
+ * GET /api/v1/examples/:id
+ */
+const getById = asyncHandler(async (req, res) => {
+  const { id } = req.params;
+
+  log.info({ id }, 'Fetching example by ID');
+
+  const example = await Example.findById(id);
+
+  if (!example) {
+    throw new NotFoundError(`Example with ID ${id} not found`);
+  }
+
+  sendSuccess(res, example);
+});
+
+/**
+ * Create new example
+ * POST /api/v1/examples
+ */
+const create = asyncHandler(async (req, res) => {
+  const data = req.body;
+
+  log.info({ data }, 'Creating new example');
+
+  const example = await Example.create(data);
+
+  sendCreated(res, example);
+});
+
+/**
+ * Update example
+ * PUT /api/v1/examples/:id
+ */
+const update = asyncHandler(async (req, res) => {
+  const { id } = req.params;
+  const data = req.body;
+
+  log.info({ id, data }, 'Updating example');
+
+  const example = await Example.findByIdAndUpdate(
+    id,
+    data,
+    { new: true, runValidators: true }
+  );
+
+  if (!example) {
+    throw new NotFoundError(`Example with ID ${id} not found`);
+  }
+
+  sendSuccess(res, example, 200, 'Example updated successfully');
+});
+
+/**
+ * Delete example (soft delete)
+ * DELETE /api/v1/examples/:id
+ */
+const remove = asyncHandler(async (req, res) => {
+  const { id } = req.params;
+
+  log.info({ id }, 'Deleting example');
+
+  const example = await Example.findById(id);
+
+  if (!example) {
+    throw new NotFoundError(`Example with ID ${id} not found`);
+  }
+
+  await example.softDelete();
+
+  sendNoContent(res);
+});
+
+/**
+ * Activate example
+ * PATCH /api/v1/examples/:id/activate
+ */
+const activate = asyncHandler(async (req, res) => {
+  const { id } = req.params;
+
+  log.info({ id }, 'Activating example');
+
+  const example = await Example.findById(id);
+
+  if (!example) {
+    throw new NotFoundError(`Example with ID ${id} not found`);
+  }
+
+  await example.activate();
+
+  sendSuccess(res, example, 200, 'Example activated');
+});
+
+/**
+ * Deactivate example
+ * PATCH /api/v1/examples/:id/deactivate
+ */
+const deactivate = asyncHandler(async (req, res) => {
+  const { id } = req.params;
+
+  log.info({ id }, 'Deactivating example');
+
+  const example = await Example.findById(id);
+
+  if (!example) {
+    throw new NotFoundError(`Example with ID ${id} not found`);
+  }
+
+  await example.deactivate();
+
+  sendSuccess(res, example, 200, 'Example deactivated');
+});
+
+module.exports = {
+  getAll,
+  getById,
+  create,
+  update,
+  remove,
+  activate,
+  deactivate,
+};