@fwd/server - NodeJS Full-Stack Framework

A powerful, easy-to-use Node.js framework that gives you everything you need to build web applications quickly. Think of it as your Swiss Army knife for web development - it includes a web server, database, file operations, caching, and much more, all in one package.

🚀 What Makes This Special?

Zero Configuration: Get started in seconds, not hours
Everything Included: Web server, database, file operations, caching, and more
Natural Language: Use human-friendly syntax for dates, times, and cron jobs
Production Ready: Built-in security features and comprehensive testing
Beginner Friendly: Simple examples that anyone can understand

📦 What's Included

🌐 Full Web Server (ExpressJS) - Handle HTTP requests and responses
🔗 HTTP Client (Axios) - Make API calls to other services
💾 In-Memory Caching - Store data temporarily for faster access
🗄️ SQL-Like Database - Store and query data without complex setup
🔐 UUID Generator - Create unique identifiers for your data
📅 Smart Date Parsing - Use natural language like "next friday"
⏰ Timestamps - Easy time formatting and timezone handling
📁 File Operations - Read, write, append, and manage files
⏲️ Cron Jobs - Schedule tasks with natural language
🖥️ Shell Commands - Run system commands from Node.js

🛠️ Installation

npm install @fwd/server

🎯 Quick Start (Your First Web App)

Let's build a simple web application that greets visitors:

const server = require('@fwd/server')

// Create a route that responds to GET requests to the homepage
server.get('/', (req, res) => {
    res.send("Hello, World! Welcome to my website!")
})

// Start the server on port 8080
server.start(8080)

That's it! Your web server is now running at http://localhost:8080. When someone visits your site, they'll see "Hello, World! Welcome to my website!"

💡 Tip: Static files (like CSS, images, JavaScript) are automatically served from the /public folder. You can change this with server.start(8080, { publicFolder: '/dist' }).

🌟 Real-World Examples

Example 1: User Registration System

Let's build a complete user registration system:

const server = require('@fwd/server')

// Serve the registration form
server.get('/register', (req, res) => {
    res.send(`
        <form method="POST" action="/register">
            <h2>Create Your Account</h2>
            <input type="text" name="name" placeholder="Your Name" required>
            <input type="email" name="email" placeholder="Your Email" required>
            <button type="submit">Register</button>
        </form>
    `)
})

// Handle the registration form submission
server.post('/register', async (req, res) => {
    const { name, email } = req.body
    
    // Validate email format
    if (!server.isEmail(email)) {
        return res.send("Please enter a valid email address!")
    }
    
    // Create a new user in the database
    const user = await server.database.create('users', {
        id: server.uuid(),           // Generate unique ID
        name: name,
        email: email,
        created_at: server.timestamp() // Current timestamp
    })
    
    res.send(`Welcome ${name}! Your account has been created.`)
})

// View all registered users
server.get('/users', async (req, res) => {
    const users = await server.database.get('users')
    res.send({ users: users })
})

server.start(8080)

Example 2: Blog with File Storage

Create a simple blog that stores posts in files:

const server = require('@fwd/server')

// Display all blog posts
server.get('/', async (req, res) => {
    const posts = await server.list('./posts')
    let html = '<h1>My Blog</h1>'
    
    for (const post of posts) {
        const content = await server.read(`./posts/${post}`)
        html += `<div><h3>${post.replace('.txt', '')}</h3><p>${content}</p></div>`
    }
    
    html += '<a href="/new">Write New Post</a>'
    res.send(html)
})

// Show form to create new post
server.get('/new', (req, res) => {
    res.send(`
        <form method="POST" action="/new">
            <h2>Write New Post</h2>
            <input type="text" name="title" placeholder="Post Title" required>
            <textarea name="content" placeholder="Post Content" required></textarea>
            <button type="submit">Publish Post</button>
        </form>
    `)
})

// Save new blog post
server.post('/new', async (req, res) => {
    const { title, content } = req.body
    
    // Create filename from title (replace spaces with dashes)
    const filename = title.toLowerCase().replace(/\s+/g, '-') + '.txt'
    
    // Save post to file
    await server.write(`./posts/${filename}`, content)
    
    res.send(`Post "${title}" has been published! <a href="/">View all posts</a>`)
})

server.start(8080)

Example 3: API Integration with External Services

Build an app that fetches data from external APIs:

const server = require('@fwd/server')

// Get random joke from external API
server.get('/joke', async (req, res) => {
    try {
        const response = await server.http.get('https://api.chucknorris.io/jokes/random')
        const joke = response.data
        
        res.send(`
            <h2>Random Chuck Norris Joke</h2>
            <p>${joke.value}</p>
            <a href="/joke">Get Another Joke</a>
        `)
    } catch (error) {
        res.send("Sorry, couldn't fetch a joke right now.")
    }
})

// Weather information (example with caching)
server.get('/weather/:city', async (req, res) => {
    const city = req.params.city
    
    // Check if we have cached weather data
    let weather = server.cache(`weather_${city}`)
    
    if (!weather) {
        // Fetch fresh data from API
        try {
            const response = await server.http.get(`https://api.openweathermap.org/data/2.5/weather?q=${city}&appid=YOUR_API_KEY`)
            weather = response.data
            
            // Cache for 10 minutes (600 seconds)
            server.cache(`weather_${city}`, weather, 600)
        } catch (error) {
            return res.send(`Could not fetch weather for ${city}`)
        }
    }
    
    res.send(`
        <h2>Weather in ${city}</h2>
        <p>Temperature: ${weather.main.temp}°F</p>
        <p>Description: ${weather.weather[0].description}</p>
    `)
})

server.start(8080)

🗄️ Database Operations Made Simple

The built-in database works like a simple JSON database - perfect for prototypes and small applications:

const server = require('@fwd/server')

// Create a new record
const user = await server.database.create('users', {
    name: 'John Doe',
    email: 'john@example.com',
    age: 30
})

// Find all users
const allUsers = await server.database.get('users')

// Find users with specific criteria
const youngUsers = await server.database.find('users', { age: { $lt: 25 } })

// Find one specific user
const john = await server.database.findOne('users', { name: 'John Doe' })

// Update a user
await server.database.update('users', john.id, { age: 31 })

// Delete a user
await server.database.remove('users', john.id)

📁 File Operations

Handle files easily with built-in methods:

const server = require('@fwd/server')

// Read a file
const content = await server.read('./data.txt')
console.log(content)

// Write to a file
await server.write('./output.txt', 'Hello, World!')

// Append to a file
await server.append('./log.txt', 'New log entry\n')

// Prepend to a file (add content at the beginning)
await server.prepend('./notes.txt', 'Important: ')

// Copy a file
await server.copy('./source.txt', './backup.txt')

// Delete a file
await server.unlink('./old-file.txt')

// List files in a directory
const files = await server.list('./documents')
console.log(files) // ['file1.txt', 'file2.txt', 'folder1']

⏰ Time and Date Magic

Work with dates using natural language:

const server = require('@fwd/server')

// Natural language date parsing
console.log(server.date('next friday'))        // Next Friday's date
console.log(server.date('tomorrow'))           // Tomorrow's date
console.log(server.date('in 3 days'))          // Date 3 days from now
console.log(server.date('last monday'))        // Last Monday's date

// Timestamps
console.log(server.timestamp())                // Current Unix timestamp
console.log(server.timestamp('LLLL'))          // "Monday, September 28, 2020 4:30 PM"
console.log(server.timestamp('LL'))            // "September 28, 2020"
console.log(server.timestamp('LLL', 'America/New_York')) // With timezone

// Time conversions
console.log(server.time(5, 'seconds'))         // 5000 (milliseconds)
console.log(server.time(1, 'hour'))            // 3600000 (milliseconds)
console.log(server.time(2, 'days'))            // 172800000 (milliseconds)

⏲️ Scheduled Tasks (Cron Jobs)

Schedule tasks using natural language:

const server = require('@fwd/server')

// Run every hour
server.cron(() => {
    console.log('Hourly backup completed')
}, 'every 1 hour')

// Run every 30 minutes
server.cron(() => {
    console.log('Checking for updates...')
}, 'every 30 minutes')

// Run daily at midnight
server.cron(() => {
    console.log('Daily cleanup started')
}, 'every 1 day')

// Run immediately and then every 5 minutes
server.cron(() => {
    console.log('Health check performed')
}, 'every 5 minutes', true) // true = run immediately

🔐 Generate Unique IDs

Create unique identifiers for your data:

const server = require('@fwd/server')

// Generate a full UUID
const id = server.uuid()
console.log(id) // "9e471b08-38fe-11eb-adc1-0242ac120002"

// Generate a shorter UUID
const shortId = server.uuid(8)
console.log(shortId) // "9e471b08"

// Generate UUID with prefix
const prefixedId = server.uuid(16, 'user_')
console.log(prefixedId) // "user_9e471b08-38fe"

// Generate UUID without dashes
const cleanId = server.uuid(32, '', true)
console.log(cleanId) // "9e471b0838fe11ebadc10242ac120002"

🖥️ Execute System Commands

Run shell commands from your Node.js application:

const server = require('@fwd/server')

// Get system information
const cpuUsage = await server.exec('top -l 1 | grep "CPU usage"')
console.log(cpuUsage)

// List files in current directory
const files = await server.exec('ls -la')
console.log(files)

// Get disk usage
const diskUsage = await server.exec('df -h')
console.log(diskUsage)

// Execute with options
const result = await server.exec('long-running-command', {
    timeout: 60000,    // 60 second timeout
    maxBuffer: 1024 * 1024 // 1MB buffer limit
})

💾 Caching for Performance

Store data temporarily to improve performance:

const server = require('@fwd/server')

// Store data in cache
server.cache('user_123', { name: 'John', email: 'john@example.com' })

// Retrieve from cache
const user = server.cache('user_123')
console.log(user) // { name: 'John', email: 'john@example.com' }

// Store with expiration (expires in 300 seconds = 5 minutes)
server.cache('api_data', { data: 'some data' }, 300)

// Cache will automatically expire after 5 minutes

🔍 Data Validation

Validate user input with built-in validators:

const server = require('@fwd/server')

// Email validation
console.log(server.isEmail('user@example.com'))    // true
console.log(server.isEmail('invalid-email'))       // false

// Phone number validation
console.log(server.isPhone({ value: '555-123-4567' }))  // true
console.log(server.isPhone({ value: '123' }))            // false

🌐 Advanced Server Configuration

Configure your server with security and performance options:

const server = require('@fwd/server')

server.get('/', (req, res) => {
    res.send('Hello, World!')
})

server.start(8080, './my-app', {
    // Security settings
    cors: {
        origin: ['https://mywebsite.com', 'https://app.mywebsite.com'],
        credentials: true
    },
    
    // File size limits
    jsonLimit: '50mb',
    
    // Timezone for timestamps
    timezone: 'America/New_York',
    
    // Static file settings
    publicFolder: './public',
    maxAge: '1d', // Cache static files for 1 day
    
    // Upload settings
    uploadFolder: './uploads',
    
    // View engine
    viewEngine: 'ejs',
    viewsFolder: './views'
})

🧪 Testing

The framework includes comprehensive testing to ensure reliability and security. All tests pass to maintain API compatibility.

Running Tests

# Run all tests
npm test

# Run tests in watch mode (reruns when files change)
npm run test:watch

# Run tests with coverage report
npm run test:coverage

Test Coverage

The test suite covers:

✅ File Operations - Read, write, append, prepend, delete, copy, list
✅ Utility Functions - Command execution, sleep, UUID generation, time/date functions
✅ Validation Functions - Email and phone number validation
✅ Cron Functionality - Scheduled task execution
✅ Caching - Data storage and retrieval with expiration
✅ Server Setup - HTTP method registration and routing
✅ Integration Tests - End-to-end functionality testing

Test Structure

__tests__/
├── file-operations.test.js      # File system operations
├── utility-functions.test.js    # Core utility functions
├── validation-functions.test.js  # Input validation
├── cron-functionality.test.js   # Scheduled tasks
├── cache-functionality.test.js  # Caching system
├── server-setup.test.js        # Server configuration
└── integration.test.js          # End-to-end tests

🔒 Security Features

The framework includes comprehensive security measures to protect your applications:

🛡️ Built-in Security Protections

Command Injection Prevention

Input validation and sanitization
Dangerous character filtering (;&|$(){}[]`)
Command length limits (1000 characters)
Execution timeouts (30 seconds default)
Buffer size limits (1MB)

Path Traversal Protection

Path normalization and validation
Prevention of .. directory traversal attacks
Secure file operation handling

File Operation Security

File size limits (50MB for files, 1MB for append/prepend)
Input type validation
Proper error handling without information disclosure

Web Security Headers

X-Frame-Options: DENY - Prevents clickjacking attacks
X-Content-Type-Options: nosniff - Prevents MIME sniffing attacks
X-XSS-Protection: 1; mode=block - Enables XSS protection
Strict-Transport-Security - Enforces HTTPS connections
Content-Security-Policy - Restricts script and style sources

CORS Security

Disabled by default (requires explicit configuration)
Configurable allowed origins
Credentials disabled by default

Input Validation

Enhanced email validation with length limits (254 characters)
Improved phone validation with proper error handling
UUID generation with parameter validation
Cron job validation with interval limits (1 second minimum)

Resource Protection

JSON payload size limits (1GB default, configurable)
URL-encoded data limits
Cron interval limits to prevent resource exhaustion

🔐 Security Best Practices Implemented

Defense in Depth - Multiple layers of security controls
Fail Secure - Default to secure configurations
Input Validation - Comprehensive validation at all entry points
Error Handling - Graceful error handling without information disclosure
Resource Limits - Protection against resource exhaustion attacks

🚨 Security Recommendations

When using this framework in production:

Configure CORS properly - Only allow trusted origins
Set appropriate file size limits - Based on your application needs
Use HTTPS - Enable SSL/TLS for secure communications
Validate all inputs - Use the built-in validators and add custom validation
Monitor logs - Keep an eye on error logs for suspicious activity
Regular updates - Keep dependencies updated for security patches

🤝 Contributing

We welcome contributions! Here's how you can help:

Report Issues - Found a bug? Let us know!
Suggest Features - Have an idea? We'd love to hear it!
Submit Pull Requests - Fix bugs or add features
Improve Documentation - Help others learn

Development Setup

# Clone the repository
git clone https://github.com/fwd/server.git

# Install dependencies
npm install

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

📝 License

MIT License - feel free to use this in your projects!

⭐ Show Your Support

Give a ⭐️ if this project helped you! It motivates us to keep improving.

📊 Project Stats

Ready to build something amazing? Start with the Quick Start example above and let your creativity flow! 🚀

Name		Name	Last commit message	Last commit date
Latest commit History 137 Commits
.github		.github
__tests__		__tests__
coverage		coverage
dependencies		dependencies
.gitignore		.gitignore
README.md		README.md
index.js		index.js
package.json		package.json
tests.js		tests.js

fwd/server

Folders and files

Latest commit

History

Repository files navigation