create-rebe 1.0.0

package/template/core/common/string.js

@@ -0,0 +1,137 @@
+'use strict'
+
+const crypto = require('crypto')
+
+// String helpers: casing, slugs, truncation and random tokens.
+class Str {
+	// Uppercase the first character only.
+	static ucfirst(str) {
+		str = String(str ?? '')
+		return str.charAt(0).toUpperCase() + str.slice(1)
+	}
+
+	// Lowercase the first character only.
+	static lcfirst(str) {
+		str = String(str ?? '')
+		return str.charAt(0).toLowerCase() + str.slice(1)
+	}
+
+	// Capitalize every word.
+	static title(str) {
+		return String(str ?? '')
+			.toLowerCase()
+			.replace(/\b\w/g, (c) => c.toUpperCase())
+	}
+
+	// Split words from camelCase, snake_case, kebab-case and spaces.
+	static words(str) {
+		return String(str ?? '')
+			.replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+			.replace(/[_\-]+/g, ' ')
+			.trim()
+			.split(/\s+/)
+			.filter(Boolean)
+	}
+
+	static camel(str) {
+		const words = Str.words(str)
+		return words.map((w, i) => (i === 0 ? w.toLowerCase() : Str.ucfirst(w.toLowerCase()))).join('')
+	}
+
+	static pascal(str) {
+		return Str.words(str)
+			.map((w) => Str.ucfirst(w.toLowerCase()))
+			.join('')
+	}
+
+	static snake(str) {
+		return Str.words(str)
+			.map((w) => w.toLowerCase())
+			.join('_')
+	}
+
+	static kebab(str) {
+		return Str.words(str)
+			.map((w) => w.toLowerCase())
+			.join('-')
+	}
+
+	// URL-friendly slug.
+	static slug(str, separator = '-') {
+		return String(str ?? '')
+			.normalize('NFKD')
+			.replace(/[̀-ͯ]/g, '')
+			.toLowerCase()
+			.replace(/[^a-z0-9]+/g, separator)
+			.replace(new RegExp(`^${separator}+|${separator}+$`, 'g'), '')
+	}
+
+	// Cut a string to length, appending a suffix when truncated.
+	static truncate(str, length = 100, suffix = '...') {
+		str = String(str ?? '')
+		if (str.length <= length) return str
+		return str.slice(0, length - suffix.length).trimEnd() + suffix
+	}
+
+	static limitWords(str, count = 10, suffix = '...') {
+		const words = String(str ?? '').split(/\s+/)
+		if (words.length <= count) return str
+		return words.slice(0, count).join(' ') + suffix
+	}
+
+	static startsWith(str, prefix) {
+		return String(str ?? '').startsWith(prefix)
+	}
+
+	static endsWith(str, suffix) {
+		return String(str ?? '').endsWith(suffix)
+	}
+
+	static contains(str, needle) {
+		return String(str ?? '').includes(needle)
+	}
+
+	// Ensure a string begins with the given prefix exactly once.
+	static start(str, prefix) {
+		str = String(str ?? '')
+		return str.startsWith(prefix) ? str : prefix + str
+	}
+
+	// Ensure a string ends with the given suffix exactly once.
+	static finish(str, suffix) {
+		str = String(str ?? '')
+		return str.endsWith(suffix) ? str : str + suffix
+	}
+
+	static mask(str, char = '*', start = 0, length = null) {
+		str = String(str ?? '')
+		const end = length === null ? str.length : start + length
+		return str
+			.split('')
+			.map((c, i) => (i >= start && i < end ? char : c))
+			.join('')
+	}
+
+	// Cryptographically strong random hex string.
+	static random(length = 16) {
+		return crypto
+			.randomBytes(Math.ceil(length / 2))
+			.toString('hex')
+			.slice(0, length)
+	}
+
+	static uuid() {
+		return crypto.randomUUID()
+	}
+
+	static escapeHtml(str) {
+		const map = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }
+		return String(str ?? '').replace(/[&<>"']/g, (c) => map[c])
+	}
+
+	static isEmpty(str) {
+		return str === null || str === undefined || String(str).trim() === ''
+	}
+}
+
+module.exports = Str

package/template/core/common/url.js

@@ -0,0 +1,81 @@
+'use strict'
+
+// URL helpers built on the WHATWG URL and URLSearchParams APIs.
+class Url {
+	// Join base and path segments without doubling slashes.
+	static join(...parts) {
+		return parts
+			.filter((p) => p !== null && p !== undefined && p !== '')
+			.map((p, i) => {
+				let s = String(p)
+				if (i > 0) s = s.replace(/^\/+/, '')
+				if (i < parts.length - 1) s = s.replace(/\/+$/, '')
+				return s
+			})
+			.join('/')
+	}
+
+	// Serialize an object to a query string (without the leading '?').
+	static buildQuery(params = {}) {
+		const search = new URLSearchParams()
+		for (const [key, value] of Object.entries(params)) {
+			if (value === null || value === undefined) continue
+			if (Array.isArray(value)) {
+				value.forEach((v) => search.append(key, String(v)))
+			} else {
+				search.append(key, String(value))
+			}
+		}
+		return search.toString()
+	}
+
+	// Parse a query string into a plain object, grouping repeated keys.
+	static parseQuery(query = '') {
+		const search = new URLSearchParams(query.replace(/^\?/, ''))
+		const out = {}
+		for (const key of new Set(search.keys())) {
+			const all = search.getAll(key)
+			out[key] = all.length > 1 ? all : all[0]
+		}
+		return out
+	}
+
+	// Append/override query parameters on an existing URL.
+	static withQuery(url, params = {}) {
+		const u = new URL(url)
+		for (const [key, value] of Object.entries(params)) {
+			if (value === null || value === undefined) {
+				u.searchParams.delete(key)
+			} else {
+				u.searchParams.set(key, String(value))
+			}
+		}
+		return u.toString()
+	}
+
+	// Break a URL into its component parts.
+	static parse(url) {
+		const u = new URL(url)
+		return {
+			protocol: u.protocol.replace(':', ''),
+			host: u.host,
+			hostname: u.hostname,
+			port: u.port,
+			path: u.pathname,
+			query: Url.parseQuery(u.search),
+			hash: u.hash.replace('#', ''),
+			origin: u.origin,
+		}
+	}
+
+	static isValid(url) {
+		try {
+			new URL(url)
+			return true
+		} catch {
+			return false
+		}
+	}
+}
+
+module.exports = Url

package/template/core/common.core.js

@@ -0,0 +1,93 @@
+'use strict'
+
+const Arr = require('@core/common/array')
+const Str = require('@core/common/string')
+const Obj = require('@core/common/object')
+const Url = require('@core/common/url')
+const Path = require('@core/common/path')
+const Hash = require('@core/common/hash')
+const Crypt = require('@core/common/crypt')
+const Collection = require('@core/common/collection')
+const DateTime = require('@core/common/date')
+const Cache = require('@core/common/cache')
+const Storage = require('@core/common/storage')
+
+class Common {
+	static getEnv(key, defaultValue = null) {
+		const value = process.env[key]
+		return value !== undefined && value !== '' ? value : defaultValue
+	}
+
+	static getEnvInt(key, defaultValue = null) {
+		const value = process.env[key]
+		if (value === undefined || value === '') return defaultValue
+		const parsed = parseInt(value, 10)
+		return isNaN(parsed) ? defaultValue : parsed
+	}
+
+	static getEnvFloat(key, defaultValue = null) {
+		const value = process.env[key]
+		if (value === undefined || value === '') return defaultValue
+		const parsed = parseFloat(value)
+		return isNaN(parsed) ? defaultValue : parsed
+	}
+
+	static getEnvBool(key, defaultValue = null) {
+		const value = process.env[key]
+		if (value === undefined || value === '') return defaultValue
+		return ['true', '1', 'yes', 'on', 'y', 't', 'enable', 'enabled'].includes(value.toLowerCase())
+	}
+
+	static getEnvArray(key, defaultValue = [], separator = ',') {
+		const value = process.env[key]
+		if (value === undefined || value === '') return defaultValue
+		return value
+			.split(separator)
+			.map((v) => v.trim())
+			.filter(Boolean)
+	}
+
+	static getEnvJson(key, defaultValue = null) {
+		const value = process.env[key]
+		if (value === undefined || value === '') return defaultValue
+		try {
+			return JSON.parse(value)
+		} catch {
+			return defaultValue
+		}
+	}
+
+	static sleep(ms) {
+		return new Promise((resolve) => setTimeout(resolve, ms))
+	}
+
+	static isEmpty(value) {
+		if (value === null || value === undefined) return true
+		if (typeof value === 'string') return value.trim() === ''
+		if (Array.isArray(value)) return value.length === 0
+		if (typeof value === 'object') return Object.keys(value).length === 0
+		return false
+	}
+
+	static async attempt(fn) {
+		try {
+			return [null, await fn()]
+		} catch (error) {
+			return [error, null]
+		}
+	}
+}
+
+Common.Arr = Arr
+Common.Str = Str
+Common.Obj = Obj
+Common.Url = Url
+Common.Path = Path
+Common.Hash = Hash
+Common.Crypt = Crypt
+Common.Collection = Collection
+Common.Date = DateTime
+Common.Cache = Cache
+Common.Storage = Storage
+
+module.exports = Common

package/template/core/cron.core.js

@@ -0,0 +1,141 @@
+'use strict'
+
+const crypto = require('crypto')
+const cron = require('node-cron')
+
+const config = require('@config/index')
+const logger = require('@core/logger.core')
+const Register = require('@core/register.core')
+
+const REGISTER_FILE = Register.path('app', 'jobs', 'register.job.js')
+const TABLE = 'cron_runs'
+
+class Cron {
+	static jobs = new Map()
+	static _db = null
+
+	static define(name, expression, handler, options = {}) {
+		if (Cron.jobs.has(name)) {
+			logger.warn(`Cron job "${name}" is already defined; overwriting`)
+		}
+		if (!cron.validate(expression)) {
+			throw new Error(`Invalid cron expression for "${name}": ${expression}`)
+		}
+
+		Cron.jobs.set(name, {
+			name,
+			expression,
+			handler,
+			timezone: options.timezone || config.cron.timezone,
+			runOnInit: options.runOnInit || false,
+			task: null,
+		})
+
+		return Cron
+	}
+
+	static async start() {
+		if (!config.cron.enabled) {
+			logger.info('Cron is disabled (CRON_ENABLED=false)')
+			return
+		}
+
+		await Register.invoke(REGISTER_FILE, [Cron], { label: 'app/jobs/register.job.js' })
+
+		if (config.cron.history && config.db.enabled) {
+			try {
+				const Database = require('@core/database.core')
+				if (Database.sequelize) {
+					Cron._db = Database.sequelize
+					await Cron._ensureTable()
+				}
+			} catch (err) {
+				logger.warn(`Cron: DB history unavailable: ${err.message}`)
+			}
+		}
+
+		for (const job of Cron.jobs.values()) {
+			job.task = cron.schedule(job.expression, () => Cron._run(job), {
+				timezone: job.timezone,
+			})
+			if (job.runOnInit) Cron._run(job)
+		}
+
+		logger.info(`Cron started ${Cron.jobs.size} job(s)${Cron.jobs.size ? `: ${[...Cron.jobs.keys()].join(', ')}` : ''}`)
+	}
+
+	static async _run(job) {
+		const runId = crypto.randomUUID()
+		const startedAt = new Date()
+
+		if (Cron._db) {
+			await Cron._db
+				.query(`INSERT INTO \`${TABLE}\` (id, job_name, started_at, status, created_at) VALUES (:id, :name, :startedAt, 'running', :now)`, {
+					replacements: { id: runId, name: job.name, startedAt, now: startedAt },
+				})
+				.catch((err) => logger.debug(`Cron: failed to record run start for "${job.name}": ${err.message}`))
+		}
+
+		try {
+			logger.debug(`Cron running: ${job.name}`)
+			await job.handler()
+			const finishedAt = new Date()
+			if (Cron._db) {
+				await Cron._db.query(`UPDATE \`${TABLE}\` SET status = 'completed', finished_at = :finishedAt, duration_ms = :duration WHERE id = :id`, { replacements: { finishedAt, duration: finishedAt - startedAt, id: runId } }).catch(() => {})
+			}
+		} catch (err) {
+			logger.error(`Cron job "${job.name}" failed`, err)
+			const finishedAt = new Date()
+			if (Cron._db) {
+				await Cron._db.query(`UPDATE \`${TABLE}\` SET status = 'failed', finished_at = :finishedAt, duration_ms = :duration, error = :error WHERE id = :id`, { replacements: { finishedAt, duration: finishedAt - startedAt, error: err.message, id: runId } }).catch(() => {})
+			}
+		}
+	}
+
+	static async runNow(name) {
+		const job = Cron.jobs.get(name)
+		if (!job) throw new Error(`Cron job "${name}" is not defined`)
+		return Cron._run(job)
+	}
+
+	static remove(name) {
+		const job = Cron.jobs.get(name)
+		if (job?.task) job.task.stop()
+		return Cron.jobs.delete(name)
+	}
+
+	static stop() {
+		for (const job of Cron.jobs.values()) {
+			if (job.task) job.task.stop()
+		}
+		logger.info('Cron stopped')
+	}
+
+	static list() {
+		return [...Cron.jobs.values()].map(({ name, expression, timezone }) => ({
+			name,
+			expression,
+			timezone,
+		}))
+	}
+
+	static async _ensureTable() {
+		await Cron._db.query(`
+			CREATE TABLE IF NOT EXISTS \`${TABLE}\` (
+				\`id\`          VARCHAR(36)                              NOT NULL,
+				\`job_name\`    VARCHAR(100)                             NOT NULL,
+				\`started_at\`  DATETIME                                 NOT NULL,
+				\`finished_at\` DATETIME                                 NULL,
+				\`status\`      ENUM('running','completed','failed')     NOT NULL DEFAULT 'running',
+				\`error\`       TEXT                                     NULL,
+				\`duration_ms\` INT                                      NULL,
+				\`created_at\`  DATETIME                                 NOT NULL,
+				PRIMARY KEY (\`id\`),
+				INDEX idx_job_name (\`job_name\`),
+				INDEX idx_started_at (\`started_at\`)
+			) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4
+		`)
+	}
+}
+
+module.exports = Cron

package/template/core/database.core.js

@@ -0,0 +1,113 @@
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+const { Sequelize, DataTypes, Model, Op } = require('sequelize')
+
+const config = require('@config/index')
+const logger = require('@core/logger.core')
+
+const MODELS_DIR = path.resolve(process.cwd(), 'database', 'models')
+
+class Database {
+	static sequelize = null
+	static models = new Map()
+
+	// ── Connection ───────────────────────────────────────────────────────────
+	static async connect() {
+		if (Database.sequelize) return Database.sequelize
+
+		const db = config.db
+
+		Database.sequelize = new Sequelize(db.database, db.username, db.password, {
+			host: db.host,
+			port: db.port,
+			dialect: db.dialect,
+			timezone: db.timezone,
+			logging: db.logging ? (msg) => logger.debug(msg) : false,
+			benchmark: db.benchmark,
+			logQueryParameters: db.logQueryParameters,
+			dialectOptions: db.dialectOptions,
+			pool: db.pool,
+			retry: db.retry,
+			define: db.define,
+		})
+
+		try {
+			await Database.sequelize.authenticate()
+			logger.info(`Database connected (${db.dialect}://${db.host}:${db.port}/${db.database})`)
+			Database.loadModels()
+		} catch (err) {
+			logger.error('Database connection failed', err)
+			throw err
+		}
+
+		return Database.sequelize
+	}
+
+	static async disconnect() {
+		if (Database.sequelize) {
+			await Database.sequelize.close()
+			Database.sequelize = null
+			Database.models.clear()
+			logger.info('Database connection closed')
+		}
+	}
+
+	// ── Models ───────────────────────────────────────────────────────────────
+	static loadModels() {
+		if (!fs.existsSync(MODELS_DIR)) {
+			logger.warn(`Models directory not found: ${MODELS_DIR}`)
+			return Database.models
+		}
+
+		const files = fs.readdirSync(MODELS_DIR).filter((file) => file.endsWith('.js') && !file.startsWith('_'))
+
+		for (const file of files) {
+			try {
+				const definition = require(path.join(MODELS_DIR, file))
+				const factory = definition.default || definition
+
+				if (typeof factory !== 'function') {
+					logger.warn(`Skipped model "${file}": expected a (sequelize, DataTypes) factory export`)
+					continue
+				}
+
+				const model = factory(Database.sequelize, DataTypes)
+				if (model?.name) {
+					Database.models.set(model.name, model)
+				}
+			} catch (err) {
+				logger.error(`Failed to load model "${file}"`, err)
+			}
+		}
+
+		// Second pass: wire up associations once all models are loaded.
+		const modelsAsObject = Object.fromEntries(Database.models)
+		for (const model of Database.models.values()) {
+			if (typeof model.associate === 'function') {
+				try {
+					model.associate(modelsAsObject)
+				} catch (err) {
+					logger.error(`Failed to associate model "${model.name}"`, err)
+				}
+			}
+		}
+
+		const names = [...Database.models.keys()]
+		logger.info(`Loaded ${names.length} model(s)${names.length ? `: ${names.join(', ')}` : ''}`)
+		return Database.models
+	}
+
+	static model(name) {
+		if (!Database.models.has(name)) throw new Error(`Model "${name}" is not registered`)
+		return Database.models.get(name)
+	}
+}
+
+Database.Sequelize = Sequelize
+Database.DataTypes = DataTypes
+Database.Model = Model
+Database.Op = Op
+
+module.exports = Database

package/template/core/error.core.js

@@ -0,0 +1,83 @@
+'use strict'
+
+const logger = require('@core/logger.core')
+const config = require('@config/index')
+const Common = require('@core/common.core')
+
+module.exports = class ErrorHandler {
+	static isProd = config.app.env === 'production'
+
+	static setExceptionHandler() {
+		process.on('uncaughtException', (err) => {
+			logger.error('Uncaught exception', err)
+			process.exit(1)
+		})
+	}
+
+	static setRejectionHandler() {
+		process.on('unhandledRejection', (reason) => {
+			const err = reason instanceof Error ? reason : new Error(String(reason))
+			logger.error('Unhandled rejection', err)
+		})
+	}
+
+	static notFoundHandler(req, res, _next) {
+		const status = 404
+		const message = `Cannot ${req.method} ${req.originalUrl}`
+
+		if (ErrorHandler._wantsJson(req)) {
+			return res.status(status).json({
+				success: false,
+				status,
+				message,
+			})
+		}
+
+		return res.status(status).send(`
+            <!DOCTYPE html>
+            <html>
+            <head><title>404 Not Found</title></head>
+            <body>
+                <h1>404 Not Found</h1>
+                <p>${Common.Str.escapeHtml(message)}</p>
+            </body>
+            </html>
+        `)
+	}
+
+	static expressErrorHandler(err, req, res, _next) {
+		const status = err.status || err.statusCode || 500
+		const message = err.message || 'Internal server error'
+		const detail = ErrorHandler.isProd ? undefined : err.stack
+
+		logger.error(err)
+
+		if (ErrorHandler._wantsJson(req)) {
+			return res.status(status).json({
+				success: false,
+				status,
+				message,
+				...(detail && { stack: detail }),
+			})
+		}
+
+		return res.status(status).send(`
+            <!DOCTYPE html>
+            <html>
+            <head><title>${status} Error</title></head>
+            <body>
+                <h1>${status} - ${Common.Str.escapeHtml(message)}</h1>
+                ${detail ? `<pre>${Common.Str.escapeHtml(detail)}</pre>` : ''}
+            </body>
+            </html>
+        `)
+	}
+
+	// Detect whether the client expects JSON:
+	// - Explicit Accept: application/json header
+	// - XHR request (axios, fetch with X-Requested-With)
+	// - API path convention (/api/*)
+	static _wantsJson(req) {
+		return req.xhr || req.path.startsWith('/api') || (req.headers.accept && req.headers.accept.includes('application/json'))
+	}
+}