fullstx 1.0.0

package/lib/application.js

@@ -0,0 +1,585 @@
+const EventEmitter = require('events');
+const setupRouting = require('./features/routing');
+const setupHooks = require('./features/hooks');
+const setupJwt = require('./features/jwt');
+const setupPlugins = require('./features/plugins');
+
+class FullstxApplication extends EventEmitter {
+    constructor(opts, router, db, wsRedisPub, wsRedisSub, wss, Sentry, faker, sanitizeHtml, server) {
+        super();
+        this.opts = opts;
+        this.router = router;
+        this.db = db;
+        this.wsRedisPub = wsRedisPub;
+        this.wsRedisSub = wsRedisSub;
+        this.wss = wss;
+        this.sentry = Sentry;
+        this.faker = faker;
+        this.sanitizeHtml = sanitizeHtml;
+        this.server = server;
+
+        this.get = router.get.bind(router);
+        this.post = router.post.bind(router);
+        this.put = router.put.bind(router);
+        this.patch = router.patch.bind(router);
+        this.delete = router.del.bind(router);
+        this.use = router.use.bind(router);
+
+        this.zod = require('zod');
+
+        this.plugins = new Set();
+        this.hooks = {
+            onRequest: [],
+            preValidation: [],
+            preHandler: [],
+            onResponse: []
+        };
+
+        setupRouting(this, this.router);
+        setupHooks(this);
+        setupJwt(this, this.opts);
+        setupPlugins(this);
+
+        const setupUtils = require('./features/utils');
+        setupUtils(this);
+    }
+
+    getServer() {
+        return this.server;
+    }
+
+    dbPoolStats() {
+        if (!this.db) return { error: 'Database is not configured' };
+        if (this.opts.db && this.opts.db.type === 'postgres') {
+            return {
+                totalCount: this.db.totalCount,
+                idleCount: this.db.idleCount,
+                waitingCount: this.db.waitingCount
+            };
+        }
+        if (this.opts.db && (this.opts.db.type === 'mysql' || this.opts.db.type === 'mariadb')) {
+            const pool = this.db.pool || this.db;
+            const internalPool = pool.pool || pool;
+            if (internalPool && internalPool._allConnections) {
+                return {
+                    totalCount: internalPool._allConnections.length,
+                    idleCount: internalPool._freeConnections.length,
+                    waitingCount: internalPool._connectionQueue ? internalPool._connectionQueue.length : 0
+                };
+            }
+        }
+        return { message: 'Pool stats not supported for this database type' };
+    }
+
+    sanitize(html, options) {
+        if (!this.sanitizeHtml) throw new Error('Please install sanitize-html to use sanitize()');
+        return this.sanitizeHtml(html, options);
+    }
+
+    metaTags(tags = {}) {
+        let html = '';
+        for (const [key, value] of Object.entries(tags)) {
+            if (!value) continue;
+            if (key === 'title') {
+                html += `<title>${value}</title>\n`;
+            } else if (key.startsWith('og:') || key.startsWith('twitter:')) {
+                html += `<meta property="${key}" content="${value}">\n`;
+            } else {
+                html += `<meta name="${key}" content="${value}">\n`;
+            }
+        }
+        return html;
+    }
+
+    wsBroadcast(data) {
+        const payload = typeof data === 'string' ? data : JSON.stringify(data);
+        if (this.wsRedisPub && this.wsRedisPub.isOpen) {
+            const channel = this.opts.ws.pubSubChannel || 'fullstx_ws_pubsub';
+            this.wsRedisPub.publish(channel, payload).catch(console.error);
+        } else if (this.wss) {
+            this.wss.clients.forEach((client) => {
+                if (client.readyState === 1) client.send(payload);
+            });
+        }
+    }
+
+    factory(count, generatorFn) {
+        if (!this.faker) throw new Error('Please install @faker-js/faker to use factory()');
+        const items = [];
+        for (let i = 0; i < count; i++) {
+            items.push(generatorFn(this.faker, i));
+        }
+        return items;
+    }
+
+    storage(provider, config) {
+        if (provider === 's3') {
+            try {
+                const { S3Client, PutObjectCommand, GetObjectCommand } = require('@aws-sdk/client-s3');
+                const client = new S3Client(config);
+                return {
+                    async upload(bucket, key, body) {
+                        const command = new PutObjectCommand({ Bucket: bucket, Key: key, Body: body });
+                        return client.send(command);
+                    },
+                    async get(bucket, key) {
+                        const command = new GetObjectCommand({ Bucket: bucket, Key: key });
+                        return client.send(command);
+                    },
+                    client
+                };
+            } catch {
+                console.error("[!] Please install '@aws-sdk/client-s3' to use S3 storage.");
+                return null;
+            }
+        } else if (provider === 'gcs') {
+            try {
+                const { Storage } = require('@google-cloud/storage');
+                const storage = new Storage(config);
+                return {
+                    async upload(bucket, key, fileBuffer) {
+                        const b = storage.bucket(bucket);
+                        const file = b.file(key);
+                        return file.save(fileBuffer);
+                    },
+                    async get(bucket, key) {
+                        const b = storage.bucket(bucket);
+                        const file = b.file(key);
+                        return file.download();
+                    },
+                    client: storage
+                };
+            } catch {
+                console.error("[!] Please install '@google-cloud/storage' to use GCS storage.");
+                return null;
+            }
+        }
+        throw new Error(`Unsupported storage provider: ${provider}`);
+    }
+
+    telemetry(serviceName) {
+        try {
+            const { NodeSDK } = require('@opentelemetry/sdk-node');
+            const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
+            const { ConsoleSpanExporter } = require('@opentelemetry/sdk-trace-node');
+
+            const sdk = new NodeSDK({
+                serviceName: serviceName || 'fullstx-app',
+                traceExporter: new ConsoleSpanExporter(),
+                instrumentations: [getNodeAutoInstrumentations()]
+            });
+            sdk.start();
+            console.log(`[fullstx] OpenTelemetry initialized for service: ${serviceName || 'fullstx-app'}`);
+
+            process.on('SIGTERM', () => {
+                sdk.shutdown()
+                    .then(() => console.log('Tracing terminated'))
+                    .catch(console.error);
+            });
+            return sdk;
+        } catch {
+            console.error(
+                '[!] Please install @opentelemetry/sdk-node, @opentelemetry/auto-instrumentations-node, and @opentelemetry/sdk-trace-node'
+            );
+            return null;
+        }
+    }
+
+    repl() {
+        const repl = require('repl');
+        console.log('[fullstx] Starting Interactive REPL...');
+        const replServer = repl.start({ prompt: 'fullstx> ' });
+        replServer.context.app = this;
+        replServer.context.db = this.db;
+        return replServer;
+    }
+
+    imageResizer(options = { cacheDir: './cache' }) {
+        let sharp;
+        try {
+            sharp = require('sharp');
+        } catch {
+            console.error("[!] Please install 'sharp' to use imageResizer()");
+            return (req, res, next) => next();
+        }
+        const fs = require('fs');
+        const path = require('path');
+        if (!fs.existsSync(options.cacheDir)) fs.mkdirSync(options.cacheDir, { recursive: true });
+
+        return async (req, res, next) => {
+            const w = parseInt(req.query.w);
+            const h = parseInt(req.query.h);
+            if ((!w && !h) || !req.url.match(/\.(jpg|jpeg|png|webp|avif|gif)$/i)) return next();
+
+            const filePath = path.join(this.opts.staticDir, req.url.split('?')[0]);
+            if (!fs.existsSync(filePath)) return next();
+
+            const cacheKey = `${w || 'auto'}x${h || 'auto'}_${path.basename(filePath)}`;
+            const cachePath = path.join(options.cacheDir, cacheKey);
+
+            if (fs.existsSync(cachePath)) {
+                res.setHeader('Content-Type', 'image/' + path.extname(cachePath).slice(1));
+                return fs.createReadStream(cachePath).pipe(res);
+            }
+
+            try {
+                const transformer = sharp(filePath).resize({ width: w || null, height: h || null, fit: 'cover' });
+                await transformer.toFile(cachePath);
+                res.setHeader('Content-Type', 'image/' + path.extname(cachePath).slice(1));
+                return fs.createReadStream(cachePath).pipe(res);
+            } catch (e) {
+                console.error('Image resize error:', e);
+                next();
+            }
+        };
+    }
+
+    inertia(
+        htmlTemplate = (page) => `<div id="app" data-page='${JSON.stringify(page).replace(/'/g, '&apos;')}' ></div>`,
+        version = '1.0'
+    ) {
+        return (req, res, next) => {
+            res.inertia = (component, props = {}) => {
+                const page = {
+                    component,
+                    props,
+                    url: req.url,
+                    version
+                };
+                if (req.headers['x-inertia']) {
+                    res.setHeader('Vary', 'Accept');
+                    res.setHeader('X-Inertia', 'true');
+                    res.writeHead(200, { 'Content-Type': 'application/json' });
+                    return res.end(JSON.stringify(page));
+                }
+                const html = htmlTemplate(page);
+                res.writeHead(200, { 'Content-Type': 'text/html' });
+                return res.end(html);
+            };
+            next();
+        };
+    }
+
+    tenant(options = { resolveBy: 'subdomain' }) {
+        return (req, res, next) => {
+            const host = req.headers.host || '';
+            if (options.resolveBy === 'subdomain') {
+                const parts = host.split('.');
+                if (parts.length > 2) {
+                    req.tenant = parts[0];
+                }
+            } else if (options.resolveBy === 'header') {
+                req.tenant = req.headers['x-tenant-id'];
+            }
+
+            if (!req.tenant && options.requireTenant) {
+                if (res.json) return res.json({ error: 'Tenant not identified' }, 400);
+                res.writeHead(400, { 'Content-Type': 'application/json' });
+                return res.end(JSON.stringify({ error: 'Tenant not identified' }));
+            }
+            next();
+        };
+    }
+
+    apiDocs(endpoint = '/api/docs') {
+        this.get(endpoint, (req, res) => {
+            const docs = this.router.routes.map((r) => ({
+                method: r.method,
+                path: r.path
+            }));
+            if (res.json) return res.json({ routes: docs });
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ routes: docs }));
+        });
+    }
+
+    dbReplica(writeConnection, readConnections = []) {
+        let readIndex = 0;
+        return {
+            get write() {
+                return writeConnection;
+            },
+            get read() {
+                if (readConnections.length === 0) return writeConnection;
+                const conn = readConnections[readIndex];
+                readIndex = (readIndex + 1) % readConnections.length;
+                return conn;
+            }
+        };
+    }
+
+    presence() {
+        const channels = new Map();
+        return {
+            join(channel, user) {
+                if (!channels.has(channel)) channels.set(channel, new Set());
+                channels.get(channel).add(user);
+                return Array.from(channels.get(channel));
+            },
+            leave(channel, user) {
+                if (channels.has(channel)) {
+                    channels.get(channel).delete(user);
+                }
+            },
+            getUsers(channel) {
+                return channels.has(channel) ? Array.from(channels.get(channel)) : [];
+            }
+        };
+    }
+
+    adminPanel(endpoint = '/admin') {
+        this.get(endpoint, (req, res) => {
+            const html = `
+            <!DOCTYPE html>
+            <html>
+            <head>
+                <title>Fullstx Admin Panel</title>
+                <style>
+                    body { font-family: system-ui, sans-serif; background: #f4f4f5; margin: 0; }
+                    header { background: #18181b; color: white; padding: 1rem; }
+                    .container { padding: 2rem; }
+                    .card { background: white; padding: 1rem; border-radius: 8px; box-shadow: 0 1px 3px rgba(0,0,0,0.1); }
+                </style>
+            </head>
+            <body>
+                <header><h2>⚡ Fullstx Admin</h2></header>
+                <div class="container">
+                    <div class="card">
+                        <h3>Dashboard Overview</h3>
+                        <p>Welcome to the built-in admin panel.</p>
+                        <ul>
+                            <li>Registered Routes: ${this.router.routes ? this.router.routes.length : 0}</li>
+                            <li>Plugins Loaded: ${this.plugins ? this.plugins.size : 0}</li>
+                            <li>DB Connected: ${!!this.db}</li>
+                        </ul>
+                    </div>
+                </div>
+            </body>
+            </html>`;
+            if (res.html) return res.html(html);
+            res.writeHead(200, { 'Content-Type': 'text/html' });
+            res.end(html);
+        });
+    }
+
+    async e2eTest(url = 'http://localhost:3000', scriptFn) {
+        let chromium;
+        try {
+            chromium = require('playwright').chromium;
+        } catch {
+            console.error("[!] Please install 'playwright' to run E2E tests.");
+            return;
+        }
+        console.log(`[fullstx] Starting E2E Test on ${url}`);
+        const browser = await chromium.launch();
+        const page = await browser.newPage();
+        try {
+            await page.goto(url);
+            if (typeof scriptFn === 'function') {
+                await scriptFn(page);
+            }
+            console.log('[fullstx] E2E Test passed successfully.');
+        } catch (err) {
+            console.error('[!] E2E Test failed:', err);
+        } finally {
+            await browser.close();
+        }
+    }
+
+    async buildAssets(options = {}) {
+        let esbuild;
+        try {
+            esbuild = require('esbuild');
+        } catch {
+            console.error("[!] Please install 'esbuild' to use the asset bundler.");
+            return;
+        }
+        const config = Object.assign(
+            {
+                entryPoints: ['public/js/app.js'],
+                bundle: true,
+                minify: true,
+                outdir: 'public/dist',
+                sourcemap: true
+            },
+            options
+        );
+        console.log('[fullstx] Bundling assets with esbuild...');
+        return await esbuild.build(config);
+    }
+
+    registerDomain(domainName, { controller, service, repository }) {
+        if (!this.domains) this.domains = new Map();
+        this.domains.set(domainName, { controller, service, repository });
+        if (typeof controller.registerRoutes === 'function') {
+            const srv = typeof service === 'function' ? new service(repository) : service;
+            const ctrl = new controller(srv);
+            ctrl.registerRoutes(this.router);
+        }
+        console.log(`[fullstx] Domain registered: ${domainName}`);
+        return this;
+    }
+
+    cqrs() {
+        const events = [];
+        const handlers = new Map();
+        return {
+            registerHandler(eventType, handlerFn) {
+                if (!handlers.has(eventType)) handlers.set(eventType, []);
+                handlers.get(eventType).push(handlerFn);
+            },
+            async dispatchCommand(commandType, payload) {
+                const event = { type: commandType + 'Executed', payload, timestamp: Date.now() };
+                events.push(event);
+                const funcs = handlers.get(event.type) || [];
+                for (const fn of funcs) {
+                    await fn(event);
+                }
+                return event;
+            },
+            getEvents() {
+                return events;
+            }
+        };
+    }
+
+    validate(schema) {
+        return (req, res, next) => {
+            try {
+                const data = {
+                    body: req.body,
+                    query: req.query,
+                    params: req.params || {}
+                };
+                const parsed = schema.parse(data);
+                if (parsed.body) req.body = parsed.body;
+                if (parsed.query) req.query = parsed.query;
+                if (parsed.params) req.params = parsed.params;
+                next();
+            } catch (e) {
+                console.error('Zod Validation Error:', e);
+                if (res.json) {
+                    return res.json({ error: 'Validation failed', details: e.errors }, 400);
+                }
+                res.writeHead(400, { 'Content-Type': 'application/json' });
+                return res.end(JSON.stringify({ error: 'Validation failed', details: e.errors }));
+            }
+        };
+    }
+
+    knex(config) {
+        return require('knex')(config);
+    }
+
+    mongoose(url, options) {
+        const mongoose = require('mongoose');
+        mongoose.connect(url, options);
+        return mongoose;
+    }
+
+    listen(port, callback) {
+        const userPort = port;
+        const internalPort =
+            typeof this.opts.internalPort === 'number'
+                ? this.opts.internalPort
+                : this.opts.liveReload
+                  ? port + (this.opts.internalPortOffset || 1000)
+                  : port;
+
+        this.router.middlewares.unshift(async (req, res, next) => {
+            try {
+                if (this.executeHooks) await this.executeHooks('onRequest', req, res);
+                if (!res.headersSent) next();
+            } catch (e) {
+                if (res.json) res.json({ error: e.message }, 500);
+                else {
+                    res.writeHead(500);
+                    res.end(e.message);
+                }
+            }
+        });
+
+        this.server.on('error', (err) => {
+            if (err && err.code === 'EADDRINUSE') {
+                console.error(
+                    '\\n[x] Failed to start: port ' + internalPort + ' (internal) is already in use by another process.'
+                );
+                console.error('    Solution:');
+                console.error(
+                    '      1) Stop the process occupying port ' +
+                        internalPort +
+                        '  (check via: netstat -ano | grep ":' +
+                        internalPort +
+                        '")'
+                );
+                console.error('      2) Or manually set internalPort: Framework({ internalPort: 4100 })\\n');
+                process.exit(1);
+            }
+            throw err;
+        });
+
+        try {
+            const { WebSocketServer } = require('ws');
+            this.wss = new WebSocketServer({ server: this.server });
+        } catch {}
+
+        const handleShutdown = () => {
+            if (this.isShuttingDown) return;
+            this.isShuttingDown = true;
+            this.close();
+        };
+
+        process.on('SIGINT', handleShutdown);
+        process.on('SIGTERM', handleShutdown);
+
+        this.server.listen(internalPort, () => {
+            if (typeof callback === 'function') callback();
+
+            if (this.opts.liveReload) {
+                const startBrowserSync = require('./browser-sync');
+                startBrowserSync(userPort, internalPort, this.opts);
+            } else {
+                console.log('Server Running on http://localhost:' + userPort);
+                console.log('Live reload disabled (Framework({ liveReload: false }))');
+            }
+        });
+
+        return this.server;
+    }
+
+    close(callback) {
+        console.log('\\n[fullstx] Initiating graceful shutdown...');
+        let pending = 1;
+        const done = () => {
+            pending--;
+            if (pending === 0) {
+                console.log('[fullstx] Server safely stopped.');
+                if (typeof callback === 'function') callback();
+                else process.exit(0);
+            }
+        };
+
+        if (this.wss) {
+            pending++;
+            this.wss.close(() => {
+                console.log('[fullstx] WebSocket server closed.');
+                done();
+            });
+        }
+
+        if (this.db && typeof this.db.end === 'function') {
+            pending++;
+            this.db.end(() => {
+                console.log('[fullstx] Database connection closed.');
+                done();
+            });
+        }
+
+        this.server.close(() => {
+            console.log('[fullstx] HTTP server closed.');
+            done();
+        });
+    }
+}
+
+module.exports = FullstxApplication;

package/lib/browser-sync.js

@@ -0,0 +1,38 @@
+module.exports = function startBrowserSync(userPort, internalPort, opts) {
+    let bs;
+    try {
+        bs = require('browser-sync').create();
+    } catch {
+        console.warn('[!] browser-sync is not installed, skipping hot-reload.');
+        console.log('Server Running on http://localhost:' + userPort);
+        return;
+    }
+
+    const config = Object.assign(
+        {
+            port: userPort,
+
+            proxy: 'http://localhost:' + internalPort,
+
+            ui: false,
+            host: 'localhost',
+            watch: true,
+            files: opts.watch,
+            notify: false,
+            open: false,
+            reloadDelay: 100,
+            ghostMode: {
+                clicks: true,
+                scroll: true,
+                forms: true
+            },
+            logLevel: 'info'
+        },
+        opts.browserSync
+    );
+
+    console.log('Server Running on http://localhost:' + userPort);
+    console.log('[fullstx] Hot-reload active via browser-sync.');
+
+    bs.init(config);
+};