create-rebe 1.0.0

package/template/core/redis.core.js

@@ -0,0 +1,75 @@
+'use strict'
+
+const IORedis = require('ioredis')
+
+const config = require('@config/index')
+const logger = require('@core/logger.core')
+
+// Standalone Redis connection (ioredis). A client is only created when
+// REDIS_ENABLED=true; every consumer (cache/queue/socket/session) must gate its
+// usage with isEnabledFor(feature) and provide an in-memory/default fallback, so
+// the application runs unchanged whether or not Redis is present.
+class Redis {
+	static _client = null
+
+	static async connect() {
+		if (!config.redis.enabled) {
+			logger.info('Redis is disabled (REDIS_ENABLED=false)')
+			return null
+		}
+		if (Redis._client) return Redis._client
+
+		const r = config.redis
+
+		Redis._client = new IORedis({
+			host: r.host,
+			port: r.port,
+			username: r.username || undefined,
+			password: r.password || undefined,
+			db: r.db,
+			keyPrefix: r.keyPrefix || undefined,
+			maxRetriesPerRequest: r.maxRetriesPerRequest,
+			connectTimeout: r.connectTimeout,
+			tls: r.tls ? {} : undefined,
+			lazyConnect: true,
+		})
+
+		// Without a listener, a runtime connection drop would emit an unhandled
+		// 'error' and crash the process.
+		Redis._client.on('error', (err) => logger.error('Redis client error', err))
+
+		try {
+			await Redis._client.connect()
+			await Redis._client.ping()
+			logger.info(`Redis connected (${r.host}:${r.port}/${r.db})`)
+		} catch (err) {
+			logger.error('Redis connection failed', err)
+			throw err
+		}
+
+		return Redis._client
+	}
+
+	// Return the live client. Throws when Redis is disabled or not yet connected —
+	// callers should guard with isEnabledFor() first.
+	static client() {
+		if (!config.redis.enabled) throw new Error('Redis is disabled (REDIS_ENABLED=false)')
+		if (!Redis._client) throw new Error('Redis is not connected; call Redis.connect() first')
+		return Redis._client
+	}
+
+	// True when Redis is enabled AND the given feature opts in (use.<feature>).
+	static isEnabledFor(feature) {
+		return Boolean(config.redis.enabled && config.redis.use[feature])
+	}
+
+	static async disconnect() {
+		if (Redis._client) {
+			await Redis._client.quit().catch(() => {})
+			Redis._client = null
+			logger.info('Redis connection closed')
+		}
+	}
+}
+
+module.exports = Redis

package/template/core/register.core.js

@@ -0,0 +1,91 @@
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+
+const logger = require('@core/logger.core')
+
+// Safe bridge loader for application `register.*.js` entry points.
+//
+// The core layer never imports application code statically. Each core instead
+// loads a single, well-known register file at runtime (Inversion of Control), so
+// the dependency arrow stays one-directional: app -> core -> config -> .env.
+//
+//   cron.core    -> app/jobs/register.job.js        module.exports = (Cron)  => {}
+//   queue.core   -> app/queue/register.queue.js     module.exports = (Queue) => {}
+//   express.core -> app/http/middlewares/register.middleware.js  (app) => {}
+//   express.core -> app/routes/register.route.js    side-effect, exports Routes
+//   socket.core  -> app/socket/register.socket.js   (io, Socket) => {}
+//   hooks.core   -> app/hooks/register.hook.js      { before, after, shutdown }
+//
+// This loader centralises the contract: resolve under the project root, tolerate
+// a missing optional file, isolate require()/execution failures, and validate the
+// exported shape so a malformed register fails loudly with a clear message rather
+// than a cryptic stack deep inside a core.
+class Register {
+	// Resolve a path fragment against the project root (process.cwd()).
+	static path(...segments) {
+		return path.resolve(process.cwd(), ...segments)
+	}
+
+	// Require a register module and unwrap an ESM-style default export when present.
+	// Returns null when the file is absent and `optional` is true (the default).
+	static require(file, { optional = true, label } = {}) {
+		const name = label || file
+
+		if (!fs.existsSync(file)) {
+			if (optional) {
+				logger.warn(`Register not found, skipping: ${name}`)
+				return null
+			}
+			throw new Error(`Required register file not found: ${name}`)
+		}
+
+		try {
+			const mod = require(file)
+			return mod && mod.default !== undefined ? mod.default : mod
+		} catch (err) {
+			logger.error(`Failed to load register: ${name}`, err)
+			throw err
+		}
+	}
+
+	// Load and invoke a callable register (a function, or an object exposing
+	// register()). `args` are forwarded to the register (the core facade). Returns
+	// the register's return value, or null when the file is absent.
+	static async invoke(file, args = [], { optional = true, label } = {}) {
+		const name = label || file
+		const mod = Register.require(file, { optional, label: name })
+		if (mod == null) return null
+
+		const fn = typeof mod === 'function' ? mod : typeof mod.register === 'function' ? mod.register.bind(mod) : null
+		if (!fn) {
+			throw new Error(`Register "${name}" must export a function or an object with a register() method`)
+		}
+
+		return fn(...args)
+	}
+
+	// Load a register that must export a plain object (e.g. lifecycle hooks).
+	// Validates that every provided key in `allowed` is a function. Returns the
+	// object, or null when the file is absent.
+	static object(file, allowed = [], { optional = true, label } = {}) {
+		const name = label || file
+		const mod = Register.require(file, { optional, label: name })
+		if (mod == null) return null
+
+		if (typeof mod !== 'object') {
+			throw new Error(`Register "${name}" must export an object`)
+		}
+
+		for (const key of allowed) {
+			if (mod[key] !== undefined && typeof mod[key] !== 'function') {
+				throw new Error(`Register "${name}" key "${key}" must be a function`)
+			}
+		}
+
+		return mod
+	}
+}
+
+module.exports = Register

package/template/core/runtime.core.js

@@ -0,0 +1,27 @@
+'use strict'
+
+const config = require('@config/index')
+
+function bootRuntime() {
+	const { app, runtime } = config
+
+	process.env.TZ = app.timezone
+	process.env.NODE_ENV = app.env
+	process.env.UV_THREADPOOL_SIZE = String(runtime.uvThreadpoolSize)
+
+	process.setMaxListeners(runtime.maxListeners)
+	Error.stackTraceLimit = runtime.stackTraceLimit
+
+	if (!runtime.deprecationWarnings) {
+		process.removeAllListeners('warning')
+	}
+
+	if (runtime.bigintJson) {
+		// eslint-disable-next-line no-extend-native
+		BigInt.prototype.toJSON = function () {
+			return this.toString()
+		}
+	}
+}
+
+bootRuntime()

package/template/core/socket.core.js

@@ -0,0 +1,93 @@
+'use strict'
+
+const { Server } = require('socket.io')
+
+const config = require('@config/index')
+const logger = require('@core/logger.core')
+const Register = require('@core/register.core')
+
+const REGISTER_FILE = Register.path('app', 'socket', 'register.socket.js')
+
+// Socket.IO attached to the Express http.Server (single port). Connection handlers
+// live in app/socket/register.socket.js as (io, Socket) => {}.
+class Socket {
+	static io = null
+
+	static async attach(httpServer) {
+		if (!config.socket.enabled) {
+			logger.info('Socket is disabled (SOCKET_ENABLED=false)')
+			return null
+		}
+		if (Socket.io) return Socket.io
+
+		Socket.io = new Server(httpServer, {
+			path: config.socket.path,
+			serveClient: config.socket.serveClient,
+			connectTimeout: config.socket.connectTimeout,
+			pingInterval: config.socket.pingInterval,
+			pingTimeout: config.socket.pingTimeout,
+			transports: config.socket.transports,
+			allowUpgrades: config.socket.allowUpgrades,
+			maxHttpBufferSize: config.socket.maxHttpBufferSize,
+			cors: config.cors.socket.cors,
+		})
+
+		await Socket._applyRedisAdapter()
+
+		Socket.io.on('connection', (socket) => {
+			logger.debug(`Socket connected: ${socket.id}`)
+			socket.on('disconnect', (reason) => logger.debug(`Socket disconnected: ${socket.id} (${reason})`))
+		})
+
+		await Socket._loadHandlers()
+
+		logger.info(`Socket.IO attached (path ${config.socket.path})`)
+		return Socket.io
+	}
+
+	// Multi-instance fan-out via Redis. Opt-in (REDIS_USE_SOCKET=true) and only when
+	// the optional adapter package is installed; otherwise the default in-memory
+	// adapter is used.
+	static async _applyRedisAdapter() {
+		const Redis = require('@core/redis.core')
+		if (!Redis.isEnabledFor('socket')) return
+
+		let createAdapter
+		try {
+			;({ createAdapter } = require('@socket.io/redis-adapter'))
+		} catch {
+			logger.warn('REDIS_USE_SOCKET=true but @socket.io/redis-adapter is not installed; using default adapter')
+			return
+		}
+
+		const pub = Redis.client()
+		const sub = pub.duplicate()
+		Socket.io.adapter(createAdapter(pub, sub))
+		logger.info('Socket.IO using Redis adapter')
+	}
+
+	static async _loadHandlers() {
+		await Register.invoke(REGISTER_FILE, [Socket.io, Socket], { label: 'app/socket/register.socket.js' })
+	}
+
+	static broadcast(event, payload) {
+		if (Socket.io) Socket.io.emit(event, payload)
+	}
+
+	static toRoom(room, event, payload) {
+		if (Socket.io) Socket.io.to(room).emit(event, payload)
+	}
+
+	static close() {
+		return new Promise((resolve) => {
+			if (!Socket.io) return resolve()
+			Socket.io.close(() => {
+				Socket.io = null
+				logger.info('Socket.IO closed')
+				resolve()
+			})
+		})
+	}
+}
+
+module.exports = Socket

package/template/core/validator.core.js

@@ -0,0 +1,34 @@
+'use strict'
+
+// Adapt a Zod schema into express-routing middleware. Used per-route as:
+//   Routes.post('auth/login', AuthController.login, [Validator.make(loginSchema)])
+//
+// On failure it short-circuits with a 422 using the manual response envelope plus
+// an `errors` array. On success the parsed value is stored on req.validated[source];
+// for the body source it also replaces req.body (req.query/req.params are read-only
+// in Express 5 and must not be reassigned).
+class Validator {
+	static make(schema, source = 'body') {
+		return {
+			handle({ req, res, next }) {
+				const result = schema.safeParse(req[source])
+
+				if (!result.success) {
+					const errors = result.error.issues.map((issue) => ({
+						field: issue.path.join('.'),
+						message: issue.message,
+					}))
+					return res.status(422).json({ status: false, code: 422, message: 'Validation failed', data: null, meta: null, errors })
+				}
+
+				req.validated = req.validated || {}
+				req.validated[source] = result.data
+				if (source === 'body') req.body = result.data
+
+				next()
+			},
+		}
+	}
+}
+
+module.exports = Validator

package/template/database/models/post.model.js

@@ -0,0 +1,26 @@
+'use strict'
+
+// Sample model demonstrating an association (belongsTo User). Remove these sample
+// files when you start modelling your own domain.
+module.exports = (sequelize, DataTypes) => {
+	const Post = sequelize.define(
+		'Post',
+		{
+			id: { type: DataTypes.BIGINT.UNSIGNED, primaryKey: true, autoIncrement: true },
+			user_id: { type: DataTypes.BIGINT.UNSIGNED, allowNull: false },
+			title: { type: DataTypes.STRING(200), allowNull: false },
+			body: { type: DataTypes.TEXT, allowNull: true },
+			published_at: { type: DataTypes.DATE, allowNull: true },
+		},
+		{
+			tableName: 'posts',
+			underscored: true,
+		},
+	)
+
+	Post.associate = (models) => {
+		if (models.User) Post.belongsTo(models.User, { foreignKey: 'user_id', as: 'author' })
+	}
+
+	return Post
+}

package/template/database/models/user.model.js

@@ -0,0 +1,30 @@
+'use strict'
+
+// Sample Sequelize model. database.core loads every file in database/models/*.js
+// when DB_ENABLED=true (files prefixed with "_" are ignored). The factory receives
+// (sequelize, DataTypes) and returns the model; associations are wired in a second
+// pass via the static associate(models).
+module.exports = (sequelize, DataTypes) => {
+	const User = sequelize.define(
+		'User',
+		{
+			id: { type: DataTypes.BIGINT.UNSIGNED, primaryKey: true, autoIncrement: true },
+			name: { type: DataTypes.STRING(100), allowNull: false },
+			email: { type: DataTypes.STRING(190), allowNull: false, unique: true, validate: { isEmail: true } },
+			password: { type: DataTypes.STRING, allowNull: false },
+		},
+		{
+			tableName: 'users',
+			underscored: true,
+			// The password is excluded by default; use the withPassword scope for auth.
+			defaultScope: { attributes: { exclude: ['password'] } },
+			scopes: { withPassword: { attributes: {} } },
+		},
+	)
+
+	User.associate = (models) => {
+		if (models.Post) User.hasMany(models.Post, { foreignKey: 'user_id', as: 'posts' })
+	}
+
+	return User
+}

package/template/docs/Bootstrap.md

@@ -0,0 +1,50 @@
+# Bootstrap API
+
+`@core/bootstrap.core` is the boot orchestrator. It wires every core in a
+deterministic order and registers graceful shutdown. It is the only core called
+directly from `index.js`.
+
+```js
+// index.js
+require('dotenv').config()
+require('module-alias/register')
+require('@core/runtime.core')
+require('@core/bootstrap.core').run()
+```
+
+## Method
+
+`run()` — async. Performs:
+
+1. `ErrorHandler.setExceptionHandler()` / `setRejectionHandler()`
+2. `Hooks.before({ config })`
+3. `Redis.connect()` — only if `REDIS_ENABLED=true`
+4. `Database.connect()` — only if `DB_ENABLED=true`
+5. `Express.create()` → `{ app, server }`
+6. `Socket.attach(server)`
+7. `Cron.start()` + `Queue.start()`
+8. `Express.listen()`
+9. `Hooks.after({ config })`
+10. registers SIGINT/SIGTERM handlers
+
+If any startup step throws, the error is logged and the process exits with code 1.
+
+## Graceful shutdown
+
+On SIGINT/SIGTERM (once), in order, each step isolated so one failure does not block
+the rest:
+
+```
+Hooks.shutdown -> Cron.stop -> Queue.stop -> Socket.close -> Express.close
+  -> Database.disconnect (if enabled) -> Redis.disconnect (if enabled) -> exit(0)
+```
+
+Optional subsystems (Redis, Database) are required lazily, so a project that never
+enables them does not load them.
+
+## Notes
+
+- The server is created before `listen()` so the socket can attach to the same
+  `http.Server` (shared port).
+- `Queue.stop()` drains in-process jobs best-effort (default 10s). PM2's
+  `kill_timeout` (15s) gives it headroom — see `ecosystem.config.js`.

package/template/docs/Common.md

@@ -0,0 +1,48 @@
+# Common API
+
+`@core/common.core` is the facade over shared utilities and the environment readers.
+It is the only place besides `config/*` that reads `process.env`.
+
+```js
+const Common = require('@core/common.core')
+```
+
+## Environment readers
+
+| Method                              | Returns                                      |
+| ----------------------------------- | -------------------------------------------- |
+| `getEnv(key, def=null)`             | string                                       |
+| `getEnvInt(key, def=null)`          | integer                                      |
+| `getEnvFloat(key, def=null)`        | float                                        |
+| `getEnvBool(key, def=null)`         | boolean (`true/1/yes/on/y/t/enable/enabled`) |
+| `getEnvArray(key, def=[], sep=',')` | trimmed, non-empty array                     |
+| `getEnvJson(key, def=null)`         | parsed JSON or the default                   |
+
+These are used inside `config/*.config.js`. Application and core code should read
+values from `config`, not call these directly.
+
+## Generic helpers
+
+| Method           | Notes                                              |
+| ---------------- | -------------------------------------------------- |
+| `sleep(ms)`      | promise that resolves after `ms`                   |
+| `isEmpty(value)` | true for null/undefined, empty string/array/object |
+| `attempt(fn)`    | `Promise<[err, result]>` — wraps try/catch         |
+
+```js
+const [err, result] = await Common.attempt(() => risky())
+if (err) logger.warn(err)
+```
+
+## Utility namespaces
+
+Pure utilities (no dependency on other cores), exposed as `Common.<Namespace>`:
+
+`Arr`, `Str`, `Obj`, `Url`, `Path`, `Hash`, `Crypt`, `Collection`, `Date`, `Cache`,
+`Storage` — implemented under `core/common/*`.
+
+```js
+Common.Str.slug('Hello World')
+Common.Arr.chunk([1, 2, 3, 4], 2)
+Common.Cache.remember('key', 60, () => expensive())
+```

package/template/docs/Cron.md

@@ -0,0 +1,47 @@
+# Cron API
+
+`@core/cron.core` schedules recurring jobs with `node-cron`. Jobs are declared in
+`app/jobs/register.job.js`, which the core loads during boot.
+
+```js
+const Cron = require('@core/cron.core')
+```
+
+## Methods
+
+| Method                                        | Notes                                                                              |
+| --------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `define(name, expression, handler, options?)` | validates the cron expression; `options.timezone`, `options.runOnInit`             |
+| `start()`                                     | loads the register file, optionally prepares the history table, schedules all jobs |
+| `runNow(name)`                                | run a job immediately                                                              |
+| `remove(name)`                                | stop and unregister a job                                                          |
+| `stop()`                                      | stop all jobs                                                                      |
+| `list()`                                      | `[{ name, expression, timezone }]`                                                 |
+
+Expression format (node-cron): `second? minute hour day-of-month month day-of-week`.
+
+## Declaring jobs
+
+```js
+// app/jobs/register.job.js
+module.exports = (Cron) => {
+	Cron.define('cleanup-temp', '0 3 * * *', async () => {
+		// runs daily at 03:00
+	})
+}
+```
+
+Each run is wrapped in a guard, so one failure is logged and does not stop the
+schedule.
+
+## Execution history (optional)
+
+When `CRON_HISTORY=true` and the database is enabled, the core auto-creates a
+`cron_runs` table and records each run (`running`/`completed`/`failed`) with duration.
+
+## Configuration
+
+`CRON_ENABLED` (`true`), `CRON_TIMEZONE` (`Asia/Jakarta`), `CRON_HISTORY` (`true`).
+
+> Single-instance only: with PM2 cluster mode every instance would fire the same
+> schedule. See `ecosystem.config.js`.

package/template/docs/Database.md

@@ -0,0 +1,61 @@
+# Database API
+
+`@core/database.core` manages the Sequelize connection and model loading. It is
+skipped entirely when `DB_ENABLED=false`. Model/migration generators are
+intentionally out of scope for this framework.
+
+```js
+const Database = require('@core/database.core')
+```
+
+## Methods
+
+| Method         | Returns   | Notes                                                 |
+| -------------- | --------- | ----------------------------------------------------- |
+| `connect()`    | Sequelize | idempotent; `authenticate()` then `loadModels()`      |
+| `disconnect()` | Promise   | closes the pool, clears models                        |
+| `loadModels()` | `Map`     | loads `database/models/*.js`, then wires associations |
+| `model(name)`  | Model     | throws if the model is not registered                 |
+
+Static re-exports: `Database.Sequelize`, `Database.DataTypes`, `Database.Model`,
+`Database.Op`.
+
+## Defining a model
+
+```js
+// database/models/user.model.js
+'use strict'
+module.exports = (sequelize, DataTypes) => {
+	const User = sequelize.define(
+		'User',
+		{
+			email: { type: DataTypes.STRING, unique: true, allowNull: false },
+			password: { type: DataTypes.STRING, allowNull: false },
+		},
+		{ tableName: 'users', underscored: true },
+	)
+
+	User.associate = (models) => {
+		// User.hasMany(models.Post)
+	}
+	return User
+}
+```
+
+Files starting with `_` are skipped. Associations run in a second pass after all
+models load, so order does not matter.
+
+## Using a model
+
+```js
+const Database = require('@core/database.core')
+const User = Database.model('User')
+const user = await User.findOne({ where: { email } })
+```
+
+## Configuration
+
+`DB_ENABLED` is the master gate. Dialect, host/port, credentials, pool, retry, and
+`define.*` options come from `config.db` — see `.env.example` for every variable.
+
+> Never run `sync({ force })` or `fresh()` with `APP_ENV=production`.

package/template/docs/Express.md

@@ -0,0 +1,63 @@
+# Express API
+
+`@core/express.core` is the HTTP backbone. It builds the Express app and an
+`http.Server` separately from listening, so `socket.core` can attach to the same
+server before the port opens.
+
+```js
+const Express = require('@core/express.core')
+```
+
+## Methods
+
+| Method           | Returns                    | Notes                                                       |
+| ---------------- | -------------------------- | ----------------------------------------------------------- |
+| `create()`       | `Promise<{ app, server }>` | idempotent; builds the app + server, not listening yet      |
+| `listen()`       | `Promise<server>`          | listens on `APP_PORT`; rejects if `create()` was not called |
+| `close()`        | Promise                    | stops the server                                            |
+| `upload(field?)` | multer middleware/instance | `single(field)` when a field name is given                  |
+
+These are wired by `bootstrap.core`; `upload()` is the one you call from routes.
+
+## Middleware order (built by `create()`)
+
+1. `helmet(config.express.helmet)`
+2. `config.cors.express`
+3. `compression()`
+4. `express.json` / `express.urlencoded` (limit = `EXPRESS_BODY_LIMIT`)
+5. rate limit (when `EXPRESS_RATE_LIMIT_ENABLED`)
+6. user middleware — `app/http/middlewares/register.middleware.js` `(app) => {}`
+7. static — `./public` at `/`, uploads at `/uploads`
+8. routes — `@routes/register.route` then `Routes.apply`
+9. `error.core` 404 + error handlers
+
+`x-powered-by` is disabled. The full `storage/` root is **not** served — only
+`/uploads` and `./public`.
+
+## File uploads
+
+```js
+const Express = require('@core/express.core')
+
+// single file under field "avatar"
+Routes.post('upload', UploadController.store, [Express.upload('avatar')])
+
+// in the controller, req.file holds the stored file
+```
+
+Uploads are constrained by `STORAGE_UPLOAD_MAX_SIZE_MB` and
+`STORAGE_UPLOAD_ALLOWED_TYPES`. Stored filenames are randomized to avoid path
+traversal and collisions.
+
+## Configuration
+
+`EXPRESS_BODY_LIMIT`, `EXPRESS_TRUST_PROXY`, `EXPRESS_RATE_LIMIT_*`, plus the helmet
+block in `express.config.js`, CORS from `cors.config.js`, and storage from
+`storage.config.js`. See `.env.example` for every variable and [SECURITY.md](../SECURITY.md).
+
+## Notes
+
+- Behind a proxy/load balancer, set `EXPRESS_TRUST_PROXY=1` so client IPs and the
+  rate limiter work correctly.
+- Uploaded files are served with `X-Content-Type-Options: nosniff`. SVG and other
+  active content can still carry script — see SECURITY.md before allowing them.