3.0.2

@refkinscallv/create-node-framework

Scaffold a new Node Framework project in seconds.

Usage

# npm
npm create @refkinscallv/node-framework my-app

# npx
npx @refkinscallv/create-node-framework my-app

# pnpm
pnpm create @refkinscallv/node-framework my-app

# yarn
yarn create @refkinscallv/node-framework my-app

If you omit the project name, the CLI will prompt for it interactively.

Options

Flag	Description
--skip-install	Skip dependency installation
--skip-setup	Skip .env generation and JWT key setup
--pm <manager>	Package manager: npm | yarn | pnpm (auto-detected)
-v, --version	Print version

Requirements

• Node.js >= 18.0.0
• npm >= 9.0.0

What it does

1. Downloads the latest node-framework template
2. Installs dependencies with your package manager
3. Runs npm run setup to copy .env.example → .env and generate secure JWT keys
4. Prints next steps

License

MIT © Refkinscallv

3.0.0

Added

• AuthMiddleware (app/http/middlewares/auth.middleware.js) — Ready-to-use JWT authentication and RBAC middleware with four methods:
  • authenticate — Requires valid Bearer token; attaches decoded payload to req.user
  • optional — Sets req.user if token present, null otherwise; never blocks
  • role(...roles) — Gate: user role must be in the allowed roles list
  • can(...permissions) — Gate: user must have all listed permissions in req.user.permissions
• Cache (core/cache.core.js) — In-memory key-value cache with TTL and rich API:
  • set(key, value, ttl), get(key, default), has(key), delete(key), flush()
  • remember(key, ttl, fn) / rememberAsync(key, ttl, fn) — Get-or-set patterns
  • add(key, value, ttl) — Store only if key absent
  • pull(key) — Get and delete in one call
  • increment(key, n) / decrement(key, n) — Atomic counter helpers
• RateLimit helper (core/helpers/rateLimit.helper.js) — Factory for express-rate-limit instances:
  • RateLimit.create(windowMs, max) — Custom limiter
  • RateLimit.strict() — 10 req/15min (for login, OTP endpoints)
  • RateLimit.generous() — 300 req/15min
  • RateLimit.global() — 200 req/15min
• EnvValidator (core/env.validator.js) — Startup validation of required environment variables; throws with a clear list of missing keys instead of cryptic runtime errors.
• Health Check endpoint — GET /health auto-registered by express.core.js; returns app name, env, uptime, timestamp, and memory stats.
• Global Rate Limiter — express.core.js now auto-applies a configurable global rate limiter via config.rateLimit.global.
• Socket.IO JWT Auth (socket.core.js) — Optional JWT middleware for Socket.IO connections. Enable with SOCKET_AUTH_ENABLED=true; sets socket.user on success.
• Database.transaction(callback) — Wraps a Sequelize transaction; auto-commits on success, auto-rollbacks on error.
• Docker support — Added Dockerfile (multi-stage: development + production), docker-compose.yml (app + MySQL with healthcheck), and .dockerignore.
• create-cli v3.0.0 — Fully rewritten for npm publish:
  • Interactive project name prompt when argument is omitted
  • Auto-detects package manager (npm / yarn / pnpm); overridable via --pm
  • --skip-install and --skip-setup flags
  • Node.js version check (>= 18)
  • Removes create-cli/ dir from scaffolded project
  • Complete package.json metadata (keywords, engines, files, repository, bugs)
  • Added README.md for the CLI package
  • Usage: npm create @refkinscallv/node-framework my-app
• New unit tests — 205 tests total (up from 116):
  • auth.middleware.test.js (16 tests)
  • cache.core.test.js (31 tests)
  • env.validator.test.js (7 tests)
  • helpers.test.js (55 tests — Arr, Str, Hash, BaseService, BaseController)

Changed

• app/config.js — Added app.requiredEnv, socket.auth, and rateLimit.global config sections.
• core/boot.core.js — Calls EnvValidator.validateFromConfig() during startup sequence.
• core/express.core.js — Registers health check endpoint and global rate limiter.
• core/socket.core.js — Added #setupAuth() private method for optional JWT middleware.
• core/database.core.js — Added transaction(callback) method.
• core/helpers/hash.helper.js — Replaced uuid package with crypto.randomUUID() (built-in Node.js, removes external ESM-only dependency).
• jest.config.js — Updated collectCoverageFrom to exclude template files (app/models, app/http/validators, core/database, core/helpers/setup.js); raised coverage thresholds (branches: 52%, functions: 65%, lines/statements: 55%).

Removed

• uuid package — Removed from dependencies; replaced by crypto.randomUUID() in Hash.uuid().

2.1.0

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog,
and this project adheres to Semantic Versioning.

[2.1.0] - 2026-04-25

Added

• JWT.signRefresh() & JWT.verifyRefresh() — Support for refresh tokens.
• JWT Security — Added issuer and audience support for tokens based on configuration.
• Setup Script — Added npm run setup command to easily initialize the project, copy .env.example, and generate random JWT keys securely.
• Core Tests — Added comprehensive unit tests for errorHandler, server, socket, hooks, and mailer core modules.

Changed

• logger.core.js — Optimized logging to only create file transports in production environment, saving I/O overhead in development where only console logs are shown.

Fixed

• express.core.js — Added graceful handling (try-catch) when loading custom middlewares and routes to prevent crashes with MODULE_NOT_FOUND if the default files are missing.

---

1.0.5

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog,
and this project adheres to Semantic Versioning.

[1.0.5] - 2026-02-03

Fixed

• Critical: Fixed race condition in graceful shutdown - properly await async operations
• Critical: Fixed database connection not closing properly - made Database.close() async
• Error: Fixed model loading to support subdirectories recursively
• Bug: Fixed 404 handler middleware order - now registered before error handler
• Warning: Improved error handling in hooks - critical errors now propagate properly
• Warning: Routes loading errors now throw instead of silent failure
• Warning: Enhanced socket loading error messages for better debugging
• Warning: Added null checks to Database.getModel() and Database.getInstance()
• Warning: Fixed server listen error handling using proper event listeners

Security

• Added prominent security warning for JWT secret configuration
• Recommended using environment variables for sensitive data

Documentation

• Updated API documentation for Database.close() async behavior
• Added breaking changes notice for async database methods

[1.0.0] - 2026-01-04

Added

• Initial release of Node.js MVC Framework
• Express.js integration with middleware support
• Socket.IO for real-time communication
• Sequelize ORM for database management
• JWT authentication utilities
• Email sending with template support (Mailer)
• File upload support with express-fileupload
• Winston logger with daily file rotation
• Application lifecycle hooks (before, after, shutdown)
• Graceful shutdown handling
• CORS configuration
• Cookie parser integration
• Error handler with API and web response modes
• Static file serving
• EJS view engine support
• Comprehensive test suite with Jest
• Code quality tools (ESLint, Prettier, Husky)
• Complete documentation (README.md, API.md)
• Example routes and configuration

Features

• Core Modules:

  • Boot: Application bootstrapper
  • Database: Sequelize integration with auto model loading
  • Express: Express app with middleware setup
  • Logger: Winston-based logging system
  • JWT: Token generation and verification
  • Mailer: Email sending with EJS templates
  • Hooks: Lifecycle event system
  • Socket: Socket.IO integration
  • Server: HTTP/HTTPS server management
  • Runtime: Environment configuration
  • ErrorHandler: Global error handling

• Security:

  • JWT authentication
  • CORS protection
  • Helmet security headers (ready to use)
  • Rate limiting support (ready to use)
  • Input validation with express-validator

• Developer Experience:

  • Hot reload with nodemon
  • Code formatting with Prettier
  • Linting with ESLint
  • Pre-commit hooks with Husky
  • Comprehensive test coverage
  • Module aliases for clean imports

Configuration

• Centralized configuration in app/config.js
• Support for environment variables
• Flexible database settings
• Customizable CORS policies
• File upload configuration
• Socket.IO options
• Mailer settings

Documentation

• Complete README with quick start guide
• API documentation with examples
• Code comments in English
• Test examples for all core modules

Development

• Jest testing framework
• Unit and integration tests
• Test coverage reporting
• Development and production scripts
• Database migration scripts (skeleton)

[Unreleased]

Planned

• Redis caching support
• Rate limiting middleware
• API versioning
• Request validation decorators
• CLI tool for scaffolding
• Database migrations and seeders
• Session management
• OAuth integration
• Admin panel
• API documentation generator

---

Version History

• 1.0.5 (2026-02-03) - Bug fixes and stability improvements
• 1.0.0 (2026-01-04) - Initial release

Full Changelog: https://github.com/refkinscallv/node-framework/commits/1.0.5