fullstx 1.0.0

package/lib/database.js

@@ -0,0 +1,150 @@
+module.exports = function setupDatabase(opts, router) {
+    let db = null;
+
+    if (opts.sqlite && !opts.db) {
+        opts.db = { type: 'sqlite', url: opts.sqlite };
+    }
+
+    if (!opts.db) return db;
+
+    const { type, url, options = {}, dbName } = opts.db;
+
+    if (type === 'sqlite') {
+        try {
+            const { DatabaseSync } = require('node:sqlite');
+            db = new DatabaseSync(url);
+        } catch (e) {
+            console.warn(`[!] Failed to load SQLite database: ${e.message}`);
+            console.warn(`    If you are using Node < 22.5.0, node:sqlite might not be available.`);
+        }
+    } else if (type === 'postgres') {
+        try {
+            const { Pool } = require('pg');
+            db = new Pool(Object.assign({ connectionString: url }, options));
+        } catch (e) {
+            if (e.code === 'MODULE_NOT_FOUND') {
+                console.error('\n[x] Missing driver for PostgreSQL.');
+                console.error('    Please install it by running: npm install pg\n');
+                process.exit(1);
+            }
+            throw e;
+        }
+    } else if (type === 'mysql' || type === 'mariadb') {
+        try {
+            const mysql = require('mysql2/promise');
+            db = mysql.createPool(Object.assign({ uri: url }, options));
+        } catch (e) {
+            if (e.code === 'MODULE_NOT_FOUND') {
+                console.error(`\n[x] Missing driver for ${type}.`);
+                console.error('    Please install it by running: npm install mysql2\n');
+                process.exit(1);
+            }
+            throw e;
+        }
+    } else if (type === 'mongo') {
+        try {
+            const { MongoClient } = require('mongodb');
+            const client = new MongoClient(url, options);
+            client
+                .connect()
+                .then(() => {
+                    console.log(`[fullstx] Connected to MongoDB (${dbName || 'default'})`);
+                })
+                .catch((err) => {
+                    console.error(`[!] MongoDB connection error:`, err);
+                });
+            db = client.db(dbName);
+        } catch (e) {
+            if (e.code === 'MODULE_NOT_FOUND') {
+                console.error('\n[x] Missing driver for MongoDB.');
+                console.error('    Please install it by running: npm install mongodb\n');
+                process.exit(1);
+            }
+            throw e;
+        }
+    } else if (type === 'redis') {
+        try {
+            const { createClient } = require('redis');
+            db = createClient(Object.assign({ url }, options));
+            db.on('error', (err) => console.error('[!] Redis Client Error', err));
+            db.connect()
+                .then(() => {
+                    console.log(`[fullstx] Connected to Redis`);
+                })
+                .catch((err) => {
+                    console.error(`[!] Redis connection error:`, err);
+                });
+        } catch (e) {
+            if (e.code === 'MODULE_NOT_FOUND') {
+                console.error('\n[x] Missing driver for Redis.');
+                console.error('    Please install it by running: npm install redis\n');
+                process.exit(1);
+            }
+            throw e;
+        }
+    } else if (type === 'chroma') {
+        try {
+            const { ChromaClient } = require('chromadb');
+            db = new ChromaClient(Object.assign({ path: url }, options));
+            console.log(`[fullstx] Initialized ChromaDB client`);
+        } catch (e) {
+            if (e.code === 'MODULE_NOT_FOUND') {
+                console.error('\n[x] Missing driver for ChromaDB.');
+                console.error('    Please install it by running: npm install chromadb\n');
+                process.exit(1);
+            }
+            throw e;
+        }
+    } else if (type === 'firebase') {
+        try {
+            const admin = require('firebase-admin');
+            const app = admin.initializeApp(options);
+            db = app.firestore();
+            console.log(`[fullstx] Initialized Firebase Firestore`);
+        } catch (e) {
+            if (e.code === 'MODULE_NOT_FOUND') {
+                console.error('\n[x] Missing driver for Firebase.');
+                console.error('    Please install it by running: npm install firebase-admin\n');
+                process.exit(1);
+            }
+            throw e;
+        }
+    } else if (type === 'supabase') {
+        try {
+            const { createClient } = require('@supabase/supabase-js');
+            db = createClient(url, options.key, options);
+            console.log(`[fullstx] Initialized Supabase client`);
+        } catch (e) {
+            if (e.code === 'MODULE_NOT_FOUND') {
+                console.error('\n[x] Missing driver for Supabase.');
+                console.error('    Please install it by running: npm install @supabase/supabase-js\n');
+                process.exit(1);
+            }
+            throw e;
+        }
+    } else if (type === 'elasticsearch' || type === 'elastic') {
+        try {
+            const { Client } = require('@elastic/elasticsearch');
+            db = new Client(Object.assign({ node: url }, options));
+            console.log(`[fullstx] Initialized Elasticsearch client`);
+        } catch (e) {
+            if (e.code === 'MODULE_NOT_FOUND') {
+                console.error('\n[x] Missing driver for Elasticsearch.');
+                console.error('    Please install it by running: npm install @elastic/elasticsearch\n');
+                process.exit(1);
+            }
+            throw e;
+        }
+    } else {
+        console.warn(`[!] Unsupported database type: ${type}`);
+    }
+
+    if (db) {
+        router.use((req, res, next) => {
+            req.db = db;
+            next();
+        });
+    }
+
+    return db;
+};

package/lib/errors.js

@@ -0,0 +1,23 @@
+class FullstxError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'FullstxError';
+    }
+}
+
+const Errors = {
+    ROUTE_NOT_FOUND: (path) => new FullstxError('FSTX_ERR_ROUTE_NOT_FOUND', `Route not found: ${path}`),
+    PLUGIN_INVALID: (msg) =>
+        new FullstxError(
+            'FSTX_ERR_PLUGIN_INVALID',
+            msg || 'Invalid plugin format. Must be a function or an object with a register method.'
+        ),
+    DB_NOT_CONFIGURED: () => new FullstxError('FSTX_ERR_DB_NOT_CONFIGURED', 'Database is not configured.'),
+    DEPENDENCY_MISSING: (pkg, feature) =>
+        new FullstxError('FSTX_ERR_DEPENDENCY_MISSING', `Please install '${pkg}' to use ${feature}.`),
+    INTERNAL_SERVER_ERROR: (msg) => new FullstxError('FSTX_ERR_INTERNAL', msg || 'Internal Server Error'),
+    INVALID_CONFIGURATION: (msg) => new FullstxError('FSTX_ERR_CONFIG', msg || 'Invalid configuration provided.')
+};
+
+module.exports = { FullstxError, Errors };

package/lib/features/hooks.js

@@ -0,0 +1,22 @@
+module.exports = function setupHooks(appInstance) {
+    appInstance.hooks = {
+        onRequest: [],
+        preValidation: [],
+        preHandler: [],
+        onResponse: []
+    };
+
+    appInstance.addHook = function (name, handler) {
+        if (this.hooks[name]) {
+            this.hooks[name].push(handler);
+        }
+        return this;
+    };
+
+    appInstance.executeHooks = async function (name, req, res) {
+        if (!this.hooks[name]) return;
+        for (const hook of this.hooks[name]) {
+            await hook(req, res);
+        }
+    };
+};

package/lib/features/jwt.js

@@ -0,0 +1,43 @@
+const jwt = require('jsonwebtoken');
+
+module.exports = function setupJwt(appInstance, opts) {
+    appInstance.jwt = {
+        sign(payload, expiresIn = '1h') {
+            return jwt.sign(payload, opts.jwtSecret, { expiresIn });
+        },
+        verify(token) {
+            try {
+                return jwt.verify(token, opts.jwtSecret);
+            } catch {
+                return null;
+            }
+        },
+        middleware(req, res, next) {
+            const authHeader = req.headers.authorization;
+            let token = null;
+            if (authHeader && authHeader.startsWith('Bearer ')) {
+                token = authHeader.split(' ')[1];
+            } else if (req.cookies && req.cookies.token) {
+                token = decodeURIComponent(req.cookies.token);
+            }
+            if (!token) {
+                if (res.json) {
+                    return res.json({ error: 'Unauthorized: No token provided' }, 401);
+                }
+                res.writeHead(401, { 'Content-Type': 'application/json' });
+                return res.end(JSON.stringify({ error: 'Unauthorized: No token provided' }));
+            }
+            try {
+                const decoded = jwt.verify(token, opts.jwtSecret);
+                req.user = decoded;
+                next();
+            } catch {
+                if (res.json) {
+                    return res.json({ error: 'Unauthorized: Invalid token' }, 401);
+                }
+                res.writeHead(401, { 'Content-Type': 'application/json' });
+                return res.end(JSON.stringify({ error: 'Unauthorized: Invalid token' }));
+            }
+        }
+    };
+};

package/lib/features/plugins.js

@@ -0,0 +1,29 @@
+module.exports = function setupPlugins(appInstance) {
+    appInstance.plugins = new Set();
+
+    appInstance.registerPlugin = function (plugin, options = {}) {
+        if (this.plugins.has(plugin)) return this;
+        this.plugins.add(plugin);
+
+        const pluginMeta = Symbol.for('plugin-meta');
+        let pluginContext = this;
+
+        const isGlobal = plugin[pluginMeta] && plugin[pluginMeta].global === true;
+        if (!isGlobal) {
+            pluginContext = Object.create(this);
+        }
+
+        try {
+            if (typeof plugin === 'function') {
+                plugin(pluginContext, options);
+            } else if (typeof plugin === 'object' && typeof plugin.register === 'function') {
+                plugin.register(pluginContext, options);
+            } else {
+                throw new Error('Invalid plugin format. Must be a function or an object with a register method.');
+            }
+        } catch (err) {
+            console.error(`[fullstx] Error registering plugin:`, err);
+        }
+        return this;
+    };
+};

package/lib/features/routing.js

@@ -0,0 +1,42 @@
+const fs = require('fs');
+const path = require('path');
+
+module.exports = function setupRouting(appInstance, router) {
+    appInstance.autoload = function (directory, prefix = '') {
+        const walk = (dir, currentPath = '') => {
+            const files = fs.readdirSync(dir);
+            for (const file of files) {
+                const fullPath = path.join(dir, file);
+                const stat = fs.statSync(fullPath);
+                if (stat.isDirectory()) {
+                    walk(fullPath, `${currentPath}/${file}`);
+                } else if (file.endsWith('.js')) {
+                    let routePath = `${currentPath}/${file.replace('.js', '')}`;
+                    routePath = routePath.replace(/\[([^\]]+)\]/g, ':$1');
+                    if (routePath.endsWith('/index')) routePath = routePath.replace('/index', '');
+                    if (routePath === '') routePath = '/';
+
+                    let finalPath = prefix + routePath;
+                    if (finalPath.length > 1 && finalPath.endsWith('/')) {
+                        finalPath = finalPath.slice(0, -1);
+                    }
+
+                    const routeModule = require(fullPath);
+
+                    if (typeof routeModule === 'function') {
+                        router.get(finalPath, routeModule);
+                    } else if (typeof routeModule === 'object') {
+                        if (routeModule.get) router.get(finalPath, routeModule.get);
+                        if (routeModule.post) router.post(finalPath, routeModule.post);
+                        if (routeModule.put) router.put(finalPath, routeModule.put);
+                        if (routeModule.delete) router.delete(finalPath, routeModule.delete);
+                    }
+                    console.log(`[fullstx] Autoloaded route: ${finalPath}`);
+                }
+            }
+        };
+        if (fs.existsSync(directory)) walk(directory);
+        else console.warn(`[fullstx] Autoload directory not found: ${directory}`);
+        return this;
+    };
+};

package/lib/features/utils.js

@@ -0,0 +1,377 @@
+module.exports = function setupUtils(app) {
+    const opts = app.opts;
+    const router = app.router;
+    const createServer = require('../../server');
+    let Sentry = app.sentry;
+    let faker = app.faker;
+    let sanitizeHtml = app.sanitizeHtml;
+    let wsRedisPub = app.wsRedisPub;
+
+    [
+        'apiKey',
+        'basicAuth',
+        'authorize',
+        'requirePermission',
+        'rateLimit',
+        'session',
+        'csrf',
+        'i18n',
+        'redisCache',
+        'csp',
+        'htmx',
+        'routeLocalization'
+    ].forEach((name) => {
+        Object.defineProperty(app, name, {
+            get() {
+                return require('../middlewares/' + name);
+            }
+        });
+    });
+
+    Object.assign(app, {
+        dbPoolStats() {
+            if (!app.db) return { error: 'Database is not configured' };
+            if (opts.db && opts.db.type === 'postgres') {
+                return {
+                    totalCount: app.db.totalCount,
+                    idleCount: app.db.idleCount,
+                    waitingCount: app.db.waitingCount
+                };
+            }
+            if (opts.db && (opts.db.type === 'mysql' || opts.db.type === 'mariadb')) {
+                const pool = app.db.pool || app.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 (!sanitizeHtml) throw new Error('Please install sanitize-html to use sanitize()');
+            return 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;
+        },
+
+        sentry: Sentry,
+
+        faker,
+
+        wsBroadcast(data) {
+            const payload = typeof data === 'string' ? data : JSON.stringify(data);
+            if (wsRedisPub && wsRedisPub.isOpen) {
+                const channel = opts.ws.pubSubChannel || 'fullstx_ws_pubsub';
+                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 (!faker) throw new Error('Please install @faker-js/faker to use factory()');
+            const items = [];
+            for (let i = 0; i < count; i++) {
+                items.push(generatorFn(faker, i));
+            }
+            return items;
+        },
+
+        zod: require('zod'),
+
+        container: {
+            services: new Map(),
+            register(name, instance) {
+                this.services.set(name, instance);
+            },
+            get(name) {
+                if (!this.services.has(name)) {
+                    throw new Error(`Service ${name} not found in IoC container`);
+                }
+                return this.services.get(name);
+            }
+        },
+
+        cache: new Map(),
+
+        upload(options = { dest: 'uploads/' }) {
+            const multer = require('multer');
+            return multer(options);
+        },
+
+        knex(config) {
+            const knexLib = require('knex');
+            return knexLib(config);
+        },
+
+        queue(name, connection) {
+            const { Queue } = require('bullmq');
+            return new Queue(name, { connection });
+        },
+
+        worker(name, processor, connection) {
+            const { Worker } = require('bullmq');
+            return new Worker(name, processor, { connection });
+        },
+
+        swagger(docPath = '/api-docs', swaggerDoc = {}) {
+            const swaggerUiDistPath = require('swagger-ui-dist').getAbsoluteFSPath();
+            const fs = require('fs');
+            const path = require('path');
+
+            router.get(docPath + '/swagger.json', (req, res) => {
+                if (res.json) return res.json(swaggerDoc);
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify(swaggerDoc));
+            });
+
+            router.use((req, res, next) => {
+                if (req.url.startsWith(docPath + '/assets/')) {
+                    const filePath = req.url.replace(docPath + '/assets/', '');
+                    const absPath = path.join(swaggerUiDistPath, filePath);
+
+                    if (absPath.startsWith(swaggerUiDistPath) && fs.existsSync(absPath)) {
+                        const content = fs.readFileSync(absPath);
+                        const ext = path.extname(absPath);
+                        const mimes = { '.css': 'text/css', '.js': 'application/javascript', '.png': 'image/png' };
+                        res.writeHead(200, { 'Content-Type': mimes[ext] || 'text/plain' });
+                        return res.end(content);
+                    }
+                }
+                next();
+            });
+
+            router.get(docPath, (req, res) => {
+                const html = `
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8">
+    <title>Swagger UI</title>
+    <link rel="stylesheet" type="text/css" href="${docPath}/assets/swagger-ui.css" />
+    <link rel="stylesheet" type="text/css" href="${docPath}/assets/index.css" />
+    <link rel="icon" type="image/png" href="${docPath}/assets/favicon-32x32.png" />
+  </head>
+  <body>
+    <div id="swagger-ui"></div>
+    <script src="${docPath}/assets/swagger-ui-bundle.js"></script>
+    <script src="${docPath}/assets/swagger-ui-standalone-preset.js"></script>
+    <script>
+      window.onload = function() {
+        window.ui = SwaggerUIBundle({
+          url: "${docPath}/swagger.json",
+          dom_id: '#swagger-ui',
+          deepLinking: true,
+          presets: [SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset],
+          plugins: [SwaggerUIBundle.plugins.DownloadUrl],
+          layout: "StandaloneLayout"
+        });
+      };
+    </script>
+  </body>
+</html>`;
+                if (res.html) return res.html(html);
+                res.writeHead(200, { 'Content-Type': 'text/html' });
+                res.end(html);
+            });
+        },
+
+        mailer(config) {
+            const nodemailer = require('nodemailer');
+            return nodemailer.createTransport(config);
+        },
+
+        cdn(url, cdnBaseUrl = opts.cdn) {
+            if (!cdnBaseUrl) return url;
+            const base = cdnBaseUrl.endsWith('/') ? cdnBaseUrl.slice(0, -1) : cdnBaseUrl;
+            const path = url.startsWith('/') ? url : '/' + url;
+            return base + path;
+        },
+
+        sitemap(urls = [], hostname = 'http://localhost') {
+            return (req, res) => {
+                let xml = '<?xml version="1.0" encoding="UTF-8"?>\n';
+                xml += '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n';
+                for (const url of urls) {
+                    const loc = typeof url === 'string' ? { url } : url;
+                    xml += '  <url>\n';
+                    xml += `    <loc>${hostname}${loc.url.startsWith('/') ? loc.url : '/' + loc.url}</loc>\n`;
+                    if (loc.lastmod) xml += `    <lastmod>${loc.lastmod}</lastmod>\n`;
+                    if (loc.changefreq) xml += `    <changefreq>${loc.changefreq}</changefreq>\n`;
+                    if (loc.priority) xml += `    <priority>${loc.priority}</priority>\n`;
+                    xml += '  </url>\n';
+                }
+                xml += '</urlset>';
+                res.writeHead(200, { 'Content-Type': 'application/xml' });
+                res.end(xml);
+            };
+        },
+
+        featureFlags: new Map(),
+        setFeature(name, isEnabled) {
+            this.featureFlags.set(name, isEnabled);
+        },
+        isFeatureEnabled(name) {
+            return !!this.featureFlags.get(name);
+        },
+        requireFeature(name) {
+            return (req, res, next) => {
+                if (!this.isFeatureEnabled(name)) {
+                    if (res.json) return res.json({ error: `Feature '${name}' is disabled or not found.` }, 404);
+                    res.writeHead(404, { 'Content-Type': 'application/json' });
+                    return res.end(JSON.stringify({ error: `Feature '${name}' is disabled or not found.` }));
+                }
+                next();
+            };
+        },
+
+        async loadTest(options = {}) {
+            let autocannon;
+            try {
+                autocannon = require('autocannon');
+            } catch {
+                console.error("[!] Please install 'autocannon' to use loadTest()");
+                return;
+            }
+            const config = Object.assign(
+                {
+                    url: 'http://localhost:3000',
+                    connections: 10,
+                    pipelining: 1,
+                    duration: 10
+                },
+                options
+            );
+            console.log(`[fullstx] Starting load test on ${config.url} for ${config.duration}s...`);
+            const result = await autocannon(config);
+            console.log(autocannon.printResult(result));
+            return result;
+        },
+
+        edgeCache({ maxAge = 60, swr = 300 } = {}) {
+            return (req, res, next) => {
+                if (req.method === 'GET') {
+                    res.setHeader('Cache-Control', `public, max-age=${maxAge}, stale-while-revalidate=${swr}`);
+                }
+                next();
+            };
+        },
+
+        queueDashboard(queues = [], endpoint = '/admin/queues') {
+            router.get(endpoint, async (req, res) => {
+                const stats = [];
+                for (const q of queues) {
+                    try {
+                        const [waiting, active, completed, failed, delayed] = await Promise.all([
+                            q.getWaitingCount(),
+                            q.getActiveCount(),
+                            q.getCompletedCount(),
+                            q.getFailedCount(),
+                            q.getDelayedCount()
+                        ]);
+                        stats.push({ name: q.name, waiting, active, completed, failed, delayed });
+                    } catch {
+                        stats.push({ name: q.name, error: 'Could not fetch stats' });
+                    }
+                }
+                if (res.json) return res.json({ queues: stats });
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ queues: stats }));
+            });
+        },
+
+        exportHandler() {
+            const server = createServer(router.routes, router.middlewares, { staticDir: opts.staticDir });
+            return (req, res) => {
+                server.emit('request', req, res);
+            };
+        },
+
+        graphql(endpoint = '/graphql', schema, rootValue) {
+            let createHandler;
+            try {
+                createHandler = require('graphql-http/lib/use/http').createHandler;
+            } catch {
+                console.error("[!] Please install 'graphql' and 'graphql-http' to use graphql()");
+                return;
+            }
+            const handler = createHandler({ schema, rootValue });
+            router.use((req, res, next) => {
+                if (req.url.startsWith(endpoint) && (req.method === 'GET' || req.method === 'POST')) {
+                    return handler(req, res);
+                }
+                next();
+            });
+        },
+
+        twoFactor() {
+            let otplib, qrcode;
+            try {
+                otplib = require('otplib');
+                qrcode = require('qrcode');
+            } catch {
+                console.error("[!] Please install 'otplib' and 'qrcode' to use twoFactor()");
+                return {};
+            }
+            return {
+                generateSecret(user = 'user', service = 'fullstx') {
+                    const secret = otplib.authenticator.generateSecret();
+                    const otpauth = otplib.authenticator.keyuri(user, service, secret);
+                    return { secret, otpauth };
+                },
+                async generateQRCode(otpauth) {
+                    return await qrcode.toDataURL(otpauth);
+                },
+                verify(token, secret) {
+                    return otplib.authenticator.check(token, secret);
+                }
+            };
+        },
+
+        grpc() {
+            let grpcJs, protoLoader;
+            try {
+                grpcJs = require('@grpc/grpc-js');
+                protoLoader = require('@grpc/proto-loader');
+            } catch {
+                console.error("[!] Please install '@grpc/grpc-js' and '@grpc/proto-loader' to use gRPC.");
+                return {};
+            }
+            return {
+                loadProto(
+                    protoPath,
+                    options = { keepCase: true, longs: String, enums: String, defaults: true, oneofs: true }
+                ) {
+                    const packageDefinition = protoLoader.loadSync(protoPath, options);
+                    return grpcJs.loadPackageDefinition(packageDefinition);
+                },
+                createServer() {
+                    return new grpcJs.Server();
+                },
+                ServerCredentials: grpcJs.ServerCredentials,
+                credentials: grpcJs.credentials
+            };
+        }
+    });
+};