@misterzik/espressojs 3.3.5 → 3.3.6

package/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 All notable changes to EspressoJS will be documented in this file.
 
+## [3.3.6] - 2024-12-25
+
+### Fixed
+- **Critical**: API routes now load correctly from `routes/api/index.js`
+- API routes properly mounted at root level to support `/v1/` endpoints
+- Catch-all route moved to end to prevent intercepting API routes
+- Route loading path corrected to use proper file structure
+- Programmatic usage now properly supported with exported `startServer()` function
+
+### Changed
+- Replaced static version badge with dynamic npm version shield badge
+- Updated landing page to show live npm version from shields.io
+- Improved code formatting and whitespace consistency in HTML files
+- Updated default API URI to use swapi.info instead of swapi.dev
+- Enhanced module exports for better programmatic usage
+
+### Added
+- Dynamic version badge using shields.io npm API
+- Better visual indication of current package version on landing page
+- Exported `startServer()` function for programmatic usage
+- Exported `gracefulShutdown()` function for custom shutdown handling
+- Exported `server` instance for advanced use cases
+- Comprehensive usage patterns documentation (docs/USAGE-PATTERNS.md)
+- README section explaining different server startup methods
+
+### Documentation
+- Added detailed guide explaining why some users need manual `app.listen()`
+- Documented three usage patterns: CLI, Direct Execution, and Programmatic
+- Explained `require.main === module` behavior and implications
+- Migration guide from manual listen to `startServer()` function
+
 ## [3.3.5] - 2024-12-25
 
 ### Fixed

package/README.md

@@ -93,6 +93,8 @@ require('@misterzik/espressojs/cli');
 
 ### 5. Run Your Server
 
+**Method 1: Using CLI (Recommended)**
+
 ```bash
 # Using the CLI
 node cli run
@@ -101,6 +103,31 @@ node cli run
 npm start
 ```
 
+**Method 2: Direct Execution**
+
+```bash
+node index.js
+```
+
+**Method 3: Programmatic Usage (v3.3.6+)**
+
+If you're requiring EspressoJS as a module in your own code:
+
+```javascript
+// Option A: Use built-in startServer (recommended)
+const { startServer } = require('@misterzik/espressojs');
+startServer();
+
+// Option B: Manual control
+const app = require('@misterzik/espressojs');
+const config = require('@misterzik/espressojs/server');
+app.listen(config.port, () => {
+  console.log(`Server running on port ${config.port}`);
+});
+```
+
+> **Note:** If you're using EspressoJS programmatically (requiring it as a module), the server won't auto-start. You must either call `startServer()` or manually use `app.listen()`. See [Usage Patterns Guide](./docs/USAGE-PATTERNS.md) for details.
+
 ## 🛠️ CLI Commands
 
 EspressoJS comes with a powerful CLI for managing your application:

package/config.json

@@ -2,6 +2,7 @@
   "instance": "development",
   "port": 8080,
   "hostname": "",
+  "publicDirectory": "/public",
   "mongoDB": {
     "enabled": false,
     "port": null,
@@ -10,11 +11,13 @@
   },
   "api": {
     "enabled": false,
-    "uri": "https://swapi.dev/api/people/",
+    "uri": "https://swapi.info/api",
     "url": "",
     "method": "GET",
     "headers": {
       "Content-Type": "application/json"
-    }
+    },
+    "timeout": 30000,
+    "retries": 0
   }
 }

package/docs/USAGE-PATTERNS.md

@@ -0,0 +1,429 @@
+# EspressoJS Usage Patterns
+
+This guide explains the different ways to use EspressoJS and why some users need to manually call `app.listen()`.
+
+## 📖 Table of Contents
+
+- [Understanding the Issue](#understanding-the-issue)
+- [Usage Pattern 1: CLI (Recommended)](#usage-pattern-1-cli-recommended)
+- [Usage Pattern 2: Direct Execution](#usage-pattern-2-direct-execution)
+- [Usage Pattern 3: Programmatic Usage](#usage-pattern-3-programmatic-usage)
+- [Usage Pattern 4: Custom Entry Point](#usage-pattern-4-custom-entry-point)
+- [Troubleshooting](#troubleshooting)
+
+## Understanding the Issue
+
+EspressoJS uses a conditional check to automatically start the server:
+
+```javascript
+if (require.main === module) {
+  startServer();
+}
+```
+
+**This check determines:**
+- `true` = File is run directly → Server auto-starts
+- `false` = File is required as module → Server does NOT auto-start
+
+**When users report needing to add `app.listen()`:**
+- They're using EspressoJS programmatically (Pattern 3 or 4)
+- The `require.main === module` check is `false`
+- The server doesn't auto-start
+- They must manually start it
+
+## Usage Pattern 1: CLI (Recommended)
+
+**Best for:** Production deployments, standard usage
+
+### Setup
+
+```javascript
+// cli.js
+require('@misterzik/espressojs/cli');
+```
+
+```javascript
+// index.js or espresso.js
+require('@misterzik/espressojs');
+```
+
+### Run
+
+```bash
+node cli run
+# or
+npm start
+```
+
+### How It Works
+
+1. CLI spawns: `node index.js`
+2. `require.main === module` is `true`
+3. Server auto-starts via `startServer()`
+4. CLI keeps process alive
+
+**✅ Advantages:**
+- Automatic server startup
+- Process management handled
+- Configuration commands available
+- Graceful shutdown built-in
+
+**❌ Disadvantages:**
+- Extra CLI layer
+- Slightly more complex setup
+
+## Usage Pattern 2: Direct Execution
+
+**Best for:** Simple deployments, quick testing
+
+### Setup
+
+```javascript
+// index.js
+require('@misterzik/espressojs');
+```
+
+### Run
+
+```bash
+node index.js
+```
+
+### How It Works
+
+1. Node runs `index.js` directly
+2. `require.main === module` is `true`
+3. Server auto-starts
+
+**✅ Advantages:**
+- Simple and direct
+- No CLI needed
+- Automatic startup
+
+**❌ Disadvantages:**
+- No CLI commands
+- Manual configuration management
+
+## Usage Pattern 3: Programmatic Usage
+
+**Best for:** Custom applications, advanced integrations
+
+### Setup (OLD - Requires Manual Listen)
+
+```javascript
+// server.js
+const app = require('@misterzik/espressojs');
+const config = require('@misterzik/espressojs/server');
+
+// require.main === module is FALSE
+// Server does NOT auto-start
+// Must manually start:
+app.listen(config.port, () => {
+  console.log(`Server running on port ${config.port}`);
+});
+```
+
+### Setup (NEW - v3.3.6+ - Use startServer)
+
+```javascript
+// server.js
+const { startServer } = require('@misterzik/espressojs');
+
+// Use the exported startServer function
+startServer();
+```
+
+### How It Works
+
+**OLD Method:**
+1. User requires EspressoJS as module
+2. `require.main === module` is `false`
+3. Server doesn't auto-start
+4. User must call `app.listen()` manually
+
+**NEW Method (v3.3.6+):**
+1. User requires EspressoJS
+2. Calls exported `startServer()` function
+3. Server starts with all built-in features
+4. Graceful shutdown and error handling included
+
+**✅ Advantages:**
+- Full control over server lifecycle
+- Can add custom middleware before starting
+- Integration with existing apps
+
+**❌ Disadvantages:**
+- More code required
+- Must understand module system
+
+## Usage Pattern 4: Custom Entry Point
+
+**Best for:** Complex applications, microservices
+
+### Setup
+
+```javascript
+// app.js (custom entry point)
+const express = require('@misterzik/espressojs');
+const { apiManager, config, startServer } = require('@misterzik/espressojs');
+
+// Add custom middleware
+express.use('/custom', (req, res) => {
+  res.json({ message: 'Custom route' });
+});
+
+// Add custom error handling
+express.use((err, req, res, next) => {
+  console.error('Custom error handler:', err);
+  res.status(500).json({ error: err.message });
+});
+
+// Start server with built-in features
+startServer();
+```
+
+### Alternative: Manual Control
+
+```javascript
+// app.js (full manual control)
+const app = require('@misterzik/espressojs');
+const config = require('@misterzik/espressojs/server');
+
+// Add custom routes
+app.use('/health', (req, res) => {
+  res.json({ status: 'ok', version: '1.0.0' });
+});
+
+// Manual server start
+const PORT = process.env.PORT || config.port;
+const server = app.listen(PORT, () => {
+  console.log(`Custom server on port ${PORT}`);
+});
+
+// Manual graceful shutdown
+process.on('SIGTERM', () => {
+  server.close(() => {
+    console.log('Server closed');
+    process.exit(0);
+  });
+});
+```
+
+**✅ Advantages:**
+- Maximum flexibility
+- Full control over everything
+- Custom error handling
+
+**❌ Disadvantages:**
+- Most complex
+- Must implement shutdown logic
+- More maintenance
+
+## Exported Functions (v3.3.6+)
+
+EspressoJS now exports these functions for programmatic usage:
+
+```javascript
+const {
+  startServer,        // Start server with all features
+  gracefulShutdown,   // Graceful shutdown handler
+  apiManager,         // API request manager
+  config,             // Configuration object
+  server              // HTTP server instance (after start)
+} = require('@misterzik/espressojs');
+```
+
+### startServer()
+
+Starts the Express server with all built-in features:
+- Port binding
+- Error handling
+- Graceful shutdown
+- Logging
+
+```javascript
+const { startServer } = require('@misterzik/espressojs');
+startServer();
+```
+
+### gracefulShutdown(signal)
+
+Manually trigger graceful shutdown:
+
+```javascript
+const { gracefulShutdown } = require('@misterzik/espressojs');
+
+// Custom shutdown trigger
+setTimeout(() => {
+  gracefulShutdown('CUSTOM_SHUTDOWN');
+}, 60000);
+```
+
+## Troubleshooting
+
+### Server Doesn't Start
+
+**Symptom:** No output, server not listening
+
+**Cause:** Using programmatic pattern without calling `startServer()` or `app.listen()`
+
+**Solution:**
+
+```javascript
+// Option 1: Use exported startServer
+const { startServer } = require('@misterzik/espressojs');
+startServer();
+
+// Option 2: Manual listen
+const app = require('@misterzik/espressojs');
+const config = require('@misterzik/espressojs/server');
+app.listen(config.port);
+```
+
+### Port Not Exposed
+
+**Symptom:** Server starts but port not accessible
+
+**Cause:** Server started but not bound to correct interface
+
+**Solution:**
+
+```javascript
+// Bind to all interfaces (0.0.0.0)
+const app = require('@misterzik/espressojs');
+app.listen(8080, '0.0.0.0', () => {
+  console.log('Server accessible on all interfaces');
+});
+```
+
+### Server Exits Immediately
+
+**Symptom:** Server starts then exits
+
+**Cause:** No event loop keeping process alive
+
+**Solution:**
+
+Use CLI method or ensure `app.listen()` is called:
+
+```bash
+# Use CLI (recommended)
+node cli run
+
+# Or ensure listen is called in code
+node index.js  # Must have app.listen() somewhere
+```
+
+### "Cannot find module" Error
+
+**Symptom:** Module not found when requiring EspressoJS
+
+**Cause:** Package not installed or wrong path
+
+**Solution:**
+
+```bash
+# Install package
+npm install @misterzik/espressojs
+
+# Verify installation
+npm list @misterzik/espressojs
+```
+
+## Best Practices
+
+### 1. Use CLI for Standard Deployments
+
+```bash
+npm start
+```
+
+### 2. Use startServer() for Programmatic Usage
+
+```javascript
+const { startServer } = require('@misterzik/espressojs');
+startServer();
+```
+
+### 3. Use Manual Listen for Maximum Control
+
+```javascript
+const app = require('@misterzik/espressojs');
+// Add custom middleware
+app.listen(3000);
+```
+
+### 4. Always Handle Errors
+
+```javascript
+const { startServer } = require('@misterzik/espressojs');
+
+try {
+  startServer();
+} catch (error) {
+  console.error('Failed to start:', error);
+  process.exit(1);
+}
+```
+
+### 5. Use Environment Variables
+
+```javascript
+const PORT = process.env.PORT || 8080;
+app.listen(PORT, () => {
+  console.log(`Server on port ${PORT}`);
+});
+```
+
+## Migration Guide
+
+### From Manual Listen to startServer()
+
+**Before (v3.3.5 and earlier):**
+
+```javascript
+const app = require('@misterzik/espressojs');
+const config = require('@misterzik/espressojs/server');
+
+app.listen(config.port, () => {
+  console.log(`Server running on ${config.port}`);
+});
+```
+
+**After (v3.3.6+):**
+
+```javascript
+const { startServer } = require('@misterzik/espressojs');
+
+startServer();
+// Logging and error handling included automatically
+```
+
+### Benefits of Migration
+
+- ✅ Built-in error handling
+- ✅ Graceful shutdown
+- ✅ Consistent logging
+- ✅ Less boilerplate code
+
+## Summary
+
+| Pattern | Auto-Start | Use Case | Complexity |
+|---------|-----------|----------|------------|
+| CLI | ✅ Yes | Production | Low |
+| Direct | ✅ Yes | Testing | Low |
+| Programmatic | ❌ No* | Integration | Medium |
+| Custom | ❌ No* | Advanced | High |
+
+*Use `startServer()` in v3.3.6+ for auto-start with full features
+
+## Support
+
+- **GitHub Issues**: https://github.com/misterzik/Espresso.js/issues
+- **Documentation**: https://github.com/misterzik/Espresso.js
+- **npm Package**: https://www.npmjs.com/package/@misterzik/espressojs
+
+---
+
+**Version:** 3.3.6+  
+**Last Updated:** 2024-12-25

package/index.js

@@ -203,6 +203,7 @@ process.on("uncaughtException", (error) => {
   gracefulShutdown("UNCAUGHT_EXCEPTION");
 });
 
+// Auto-start server if run directly (not required as module)
 if (require.main === module) {
   try {
     startServer();
@@ -213,6 +214,10 @@ if (require.main === module) {
   }
 }
 
+// Export app and utilities for programmatic usage
 module.exports = app;
 module.exports.apiManager = apiManager;
 module.exports.config = configData;
+module.exports.startServer = startServer;
+module.exports.gracefulShutdown = gracefulShutdown;
+module.exports.server = server;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@misterzik/espressojs",
-    "version": "3.3.5",
+    "version": "3.3.6",
     "description": "EspressoJS Introducing Espresso.JS, your ultimate Express configuration starting point and boilerplate. With its simplicity and lack of opinionation, EspressoJS offers plug-and-play configurations built on top of Express.",
     "main": "index.js",
     "scripts": {

package/routes/index.js

@@ -38,8 +38,8 @@ module.exports = (app) => {
 
   if (configuration.api && configuration.api.enabled === true) {
     try {
-      const apiRoutes = require(path.join(rootDir, "routes", "api.js"));
-      app.use("/api", apiRoutes);
+      const apiRoutes = require(path.join(rootDir, "routes", "api", "index.js"));
+      app.use("/", apiRoutes.router);
       logger.info("API routes loaded successfully");
     } catch (error) {
       logger.warn(`API routes not found or failed to load: ${error.message}`);
@@ -56,6 +56,7 @@ module.exports = (app) => {
     }
   }
 
+  // Catch-all route must be last to avoid intercepting API routes
   app.get(
     "/*",
     asyncHandler(async (req, res) => {