@nitronjs/framework 0.2.2 → 0.2.4

package/lib/Build/colors.js

@@ -1,3 +1,7 @@
+/**
+ * ANSI color codes for terminal output.
+ * @type {Object<string, string>}
+ */
 const COLORS = {
     reset: "\x1b[0m",
     dim: "\x1b[2m",

package/lib/Build/plugins.js

@@ -7,39 +7,71 @@ import COLORS from "./colors.js";
 
 const _traverse = traverse.default;
 
+/**
+ * Creates an esbuild plugin for path alias resolution.
+ * Supports @/, @css/, @views/, @models/, @controllers/, @middlewares/ aliases.
+ * @returns {import("esbuild").Plugin}
+ */
 export function createPathAliasPlugin() {
     const root = Paths.project;
+    
+    // Define path aliases for developer convenience
+    const aliases = {
+        "@/": root,                                          // Project root
+        "@css/": path.join(root, "resources/css"),           // CSS files
+        "@views/": path.join(root, "resources/views"),       // View components
+        "@models/": path.join(root, "app/Models"),           // Models
+        "@controllers/": path.join(root, "app/Controllers"), // Controllers
+        "@middlewares/": path.join(root, "app/Middlewares"), // Middlewares
+    };
+    
     return {
         name: "path-alias",
         setup: (build) => {
-            // @ resolves to project root
-            build.onResolve({ filter: /^@\// }, async (args) => {
-                const relativePath = args.path.replace(/^@\//, "");
-                const absolutePath = path.join(root, relativePath);
-
-                const extensions = [".js", ".ts", ".jsx", ".tsx", ""];
-                for (const ext of extensions) {
-                    const fullPath = absolutePath + ext;
-                    if (fs.existsSync(fullPath)) {
-                        return { path: fullPath, external: false };
-                    }
-                }
-
-                if (fs.existsSync(absolutePath) && fs.statSync(absolutePath).isDirectory()) {
-                    for (const ext of [".js", ".ts", ".jsx", ".tsx"]) {
-                        const indexPath = path.join(absolutePath, "index" + ext);
-                        if (fs.existsSync(indexPath)) {
-                            return { path: indexPath, external: false };
+            // Handle all @ prefixed imports
+            build.onResolve({ filter: /^@[a-z]*\// }, async (args) => {
+                // Find matching alias (longest match first)
+                const sortedPrefixes = Object.keys(aliases).sort((a, b) => b.length - a.length);
+                
+                for (const prefix of sortedPrefixes) {
+                    if (args.path.startsWith(prefix)) {
+                        const relativePath = args.path.slice(prefix.length);
+                        const absolutePath = path.join(aliases[prefix], relativePath);
+                        const extensions = [".js", ".ts", ".jsx", ".tsx", ".css", ""];
+
+                        for (const ext of extensions) {
+                            const fullPath = absolutePath + ext;
+
+                            if (fs.existsSync(fullPath)) {
+                                return { path: fullPath, external: false };
+                            }
+                        }
+                        
+                        // Check for directory with index file
+                        if (fs.existsSync(absolutePath) && fs.statSync(absolutePath).isDirectory()) {
+                            for (const ext of [".js", ".ts", ".jsx", ".tsx"]) {
+                                const indexPath = path.join(absolutePath, "index" + ext);
+
+                                if (fs.existsSync(indexPath)) {
+                                    return { path: indexPath, external: false };
+                                }
+                            }
                         }
+                        
+                        return { path: absolutePath, external: false };
                     }
                 }
-
-                return { path: absolutePath + ".js", external: false };
+                
+                return null;
             });
         }
     };
 }
 
+/**
+ * Creates an esbuild plugin for original JSX runtime resolution.
+ * @returns {import("esbuild").Plugin}
+ */
 export function createOriginalJsxPlugin() {
     return {
         name: "original-jsx",
@@ -52,6 +84,11 @@ export function createOriginalJsxPlugin() {
     };
 }
 
+/**
+ * Creates an esbuild plugin that maps React packages to window globals.
+ * Used for client bundles to share React instance across islands.
+ * @returns {import("esbuild").Plugin}
+ */
 export function createVendorGlobalsPlugin() {
     const escapeRegex = (str) => str.replace(/[.*+?^${}()|[\]\\\/]/g, "\\$&");
 
@@ -86,6 +123,11 @@ export function createVendorGlobalsPlugin() {
     };
 }
 
+/**
+ * Creates an esbuild plugin that blocks server-only modules in client bundles.
+ * Provides helpful error messages when server modules are imported incorrectly.
+ * @returns {import("esbuild").Plugin}
+ */
 export function createServerModuleBlockerPlugin() {
     const SERVER_MODULES = /lib\/(DB|Mail|Log|Hash|Environment|Server|Model|Validator|Storage)\.js$/;
 
@@ -118,6 +160,11 @@ export function createServerModuleBlockerPlugin() {
     };
 }
 
+/**
+ * Creates an esbuild plugin that transforms server functions for client use.
+ * Replaces csrf() and route() calls with runtime lookups.
+ * @returns {import("esbuild").Plugin}
+ */
 export function createServerFunctionsPlugin() {
     return {
         name: "server-functions",
@@ -152,6 +199,11 @@ export function createServerFunctionsPlugin() {
     };
 }
 
+/**
+ * Creates an esbuild plugin that stubs CSS imports.
+ * Prevents CSS from being bundled into JS files.
+ * @returns {import("esbuild").Plugin}
+ */
 export function createCssStubPlugin() {
     return {
         name: "css-stub",
@@ -169,6 +221,13 @@ export function createCssStubPlugin() {
     };
 }
 
+/**
+ * Creates an esbuild plugin that marks client components with a symbol.
+ * Used for Islands Architecture to identify hydration boundaries.
+ * @param {import("esbuild").BuildOptions} options - Build options.
+ * @param {boolean} isDev - Whether in development mode.
+ * @returns {import("esbuild").Plugin}
+ */
 export function createMarkerPlugin(options, isDev) {
     return {
         name: "client-marker",
@@ -215,6 +274,11 @@ export function createMarkerPlugin(options, isDev) {
     };
 }
 
+/**
+ * Finds all exported functions/components in an AST.
+ * @param {import("@babel/parser").ParseResult} ast - Parsed AST.
+ * @returns {Array<{name: string}>} Array of export names.
+ */
 function findExports(ast) {
     const exports = [];
 

package/lib/Console/Commands/DevCommand.js

@@ -11,14 +11,16 @@ import Builder from "../../Build/Manager.js";
 dotenv.config({ quiet: true });
 Environment.setDev(true);
 
-const C = { r: "\x1b[0m", d: "\x1b[2m", red: "\x1b[31m", g: "\x1b[32m", y: "\x1b[33m", b: "\x1b[34m", m: "\x1b[35m", c: "\x1b[36m" };
+const C = { r: "\x1b[0m", d: "\x1b[2m", bold: "\x1b[1m", red: "\x1b[31m", g: "\x1b[32m", y: "\x1b[33m", b: "\x1b[34m", m: "\x1b[35m", c: "\x1b[36m" };
+
+// Using consistent-width characters for alignment
 const ICONS = {
-    info:  `${C.b}ℹ${C.r} `,
-    ok:    `${C.g}✓${C.r} `,
-    err:   `${C.red}✗${C.r} `,
-    build: `${C.m}⟳${C.r} `,
-    hmr:   `${C.c}⚡${C.r}`,
-    watch: `${C.y}○${C.r} `
+    info:  `${C.b}i${C.r}`,
+    ok:    `${C.g}✓${C.r}`,
+    err:   `${C.red}✗${C.r}`,
+    build: `${C.y}○${C.r}`,
+    hmr:   `${C.m}●${C.r}`,
+    watch: `${C.c}◐${C.r}`
 };
 
 const PATTERNS = {
@@ -35,8 +37,10 @@ class DevServer {
     #debounce = { build: null, restart: null };
 
     #log(icon, msg, extra) {
-        const t = `${C.d}${new Date().toLocaleTimeString()}${C.r}`;
-        console.log(`${t} ${ICONS[icon] || ICONS.info} ${msg}${extra ? ` ${C.d}(${extra})${C.r}` : ""}`);
+        const time = new Date().toLocaleTimeString("en-US", { hour12: false, hour: "2-digit", minute: "2-digit", second: "2-digit" });
+        const iconStr = ICONS[icon] || ICONS.info;
+        const extraStr = extra ? ` ${C.d}(${extra})${C.r}` : "";
+        console.log(`${C.d}${time}${C.r} ${iconStr} ${msg}${extraStr}`);
     }
 
     async #build(only = null) {

package/lib/Console/Commands/MakeCommand.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
-import fs from 'node:fs';
-import path from 'node:path';
-import Paths from '../../Core/Paths.js';
+import fs from "node:fs";
+import path from "node:path";
+import Paths from "../../Core/Paths.js";
+import Output from "../Output.js";
 
 const baseDirs = {
     controller: 'app/Controllers',
@@ -47,22 +48,30 @@ function toPascalCase(str) {
         .join('');
 }
 
+/**
+ * Creates a new file from a template.
+ * @param {string} type - The type of file (controller, model, etc.).
+ * @param {string} rawName - The name/path of the file to create.
+ * @returns {Promise<boolean>}
+ */
 export default async function make(type, rawName) {
     if (!type || !rawName) {
-        console.error("\x1b[31m%s\x1b[0m", "Usage: njs make:<type> <Name/Path>  (e.g., njs make:controller Admin/HomeController)");
+        Output.error("Usage: njs make:<type> <Name/Path>");
+        Output.dim("  Example: njs make:controller Admin/HomeController");
+
         return false;
     }
 
-    const parts = rawName.split('/');
-    const subDirs = parts.slice(0, -1).join('/');
+    const parts = rawName.split("/");
+    const subDirs = parts.slice(0, -1).join("/");
     const outputDir = path.join(Paths.project, baseDirs[type]);
 
     let className = parts[parts.length - 1];
     let fileName = `${className}.js`;
 
-    if (type === 'migration') {
+    if (type === "migration") {
         const now = new Date();
-        const pad = (n) => n.toString().padStart(2, '0');
+        const pad = (n) => n.toString().padStart(2, "0");
 
         const year = now.getFullYear();
         const month = pad(now.getMonth() + 1);
@@ -78,7 +87,7 @@ export default async function make(type, rawName) {
     const fullPath = path.join(fullDir, fileName);
 
     const templatePath = path.join(Paths.frameworkTemplates, templates[type]);
-    let template = fs.readFileSync(templatePath, 'utf-8');
+    let template = fs.readFileSync(templatePath, "utf-8");
 
     if (type === "model") {
         template = template.replace(/__CLASS__/g, className).replace(/__TABLE__/g, toTableName(className));
@@ -93,7 +102,12 @@ export default async function make(type, rawName) {
     fs.mkdirSync(fullDir, { recursive: true });
     fs.writeFileSync(fullPath, template);
 
-    console.log("\x1b[32m%s\x1b[0m", `${type[0].toUpperCase() + type.slice(1)} successfully created: ${fullPath}`);
+    const typeLabel = type.charAt(0).toUpperCase() + type.slice(1);
+    const relativePath = path.relative(Paths.project, fullPath);
+
+    Output.success(`${typeLabel} created`);
+    Output.dim(`  ${relativePath}`);
+
     return true;
 }
 

package/lib/Console/Commands/MigrateCommand.js

@@ -12,7 +12,8 @@ export default async function migrate(options = {}) {
 
     try {
         await DB.setup();
-    } catch (error) {
+    }
+    catch (error) {
         console.error('❌ Database setup failed:', error.message);
         console.error('Check your .env file and ensure the database exists and is accessible');
         return false;
@@ -27,14 +28,14 @@ export default async function migrate(options = {}) {
         }
 
         if (shouldSeed && result.ran.length > 0) {
-            console.log('\n');
             await seed();
         }
 
         await DB.close();
         return true;
 
-    } catch (error) {
+    }
+    catch (error) {
         console.error('❌ Migration error:', error.message);
         await DB.close();
         return false;

package/lib/Console/Commands/MigrateFreshCommand.js

@@ -2,16 +2,9 @@ import dotenv from 'dotenv';
 import DB from '../../Database/DB.js';
 import Config from '../../Core/Config.js';
 import MigrationRunner from '../../Database/Migration/MigrationRunner.js';
+import Output from '../../Console/Output.js';
 import seed from './SeedCommand.js';
 
-const COLORS = {
-    reset: '\x1b[0m',
-    green: '\x1b[32m',
-    yellow: '\x1b[33m',
-    cyan: '\x1b[36m',
-    dim: '\x1b[2m'
-};
-
 export default async function migrateFresh(options = {}) {
     const { seed: shouldSeed = false } = options;
 
@@ -20,28 +13,29 @@ export default async function migrateFresh(options = {}) {
 
     try {
         await DB.setup();
-    } catch (error) {
-        console.error('❌ Database setup failed:', error.message);
-        console.error('Check your .env file and ensure the database exists and is accessible');
+    }
+    catch (error) {
+        Output.newline();
+        Output.error(`Database setup failed: ${error.message}`);
+        Output.errorDetail('Check your .env file and ensure the database exists and is accessible');
         return false;
     }
 
     try {
-        console.log(`${COLORS.yellow}⚠️  Dropping all tables...${COLORS.reset}\n`);
-
-        const [tableRows] = await DB.query("SHOW TABLES");
-        await DB.rawQuery("SET FOREIGN_KEY_CHECKS = 0");
-
-        for (const row of tableRows) {
-            const tableName = Object.values(row)[0];
-            console.log(`${COLORS.dim}Dropping:${COLORS.reset} ${COLORS.cyan}${tableName}${COLORS.reset}`);
-            await DB.rawQuery(`DROP TABLE IF EXISTS \`${tableName}\``);
-        }
+        const [tableRows] = await DB.rawQuery("SHOW TABLES");
+        
+        if (tableRows.length > 0) {
+            Output.dropTablesHeader();
+            await DB.rawQuery("SET FOREIGN_KEY_CHECKS = 0");
 
-        await DB.rawQuery("SET FOREIGN_KEY_CHECKS = 1");
+            for (const row of tableRows) {
+                const tableName = Object.values(row)[0];
+                Output.droppingTable(tableName);
+                await DB.rawQuery(`DROP TABLE IF EXISTS \`${tableName}\``);
+            }
 
-        if (tableRows.length > 0) {
-            console.log(`\n${COLORS.green}✅ Dropped ${tableRows.length} table(s)${COLORS.reset}\n`);
+            await DB.rawQuery("SET FOREIGN_KEY_CHECKS = 1");
+            Output.dropTablesSuccess(tableRows.length);
         }
 
         const result = await MigrationRunner.run();
@@ -52,15 +46,16 @@ export default async function migrateFresh(options = {}) {
         }
 
         if (shouldSeed && result.ran.length > 0) {
-            console.log('\n');
             await seed();
         }
 
         await DB.close();
         return true;
 
-    } catch (error) {
-        console.error('❌ Fresh migration error:', error.message);
+    }
+    catch (error) {
+        Output.newline();
+        Output.error(`Fresh migration error: ${error.message}`);
         await DB.close();
         return false;
     }

package/lib/Console/Commands/MigrateRollbackCommand.js

@@ -2,6 +2,7 @@ import dotenv from 'dotenv';
 import DB from '../../Database/DB.js';
 import Config from '../../Core/Config.js';
 import MigrationRunner from '../../Database/Migration/MigrationRunner.js';
+import Output from '../../Console/Output.js';
 
 export default async function rollback(options = {}) {
     const { step = 1, all = false } = options;
@@ -11,9 +12,11 @@ export default async function rollback(options = {}) {
 
     try {
         await DB.setup();
-    } catch (error) {
-        console.error('❌ Database setup failed:', error.message);
-        console.error('Check your .env file and ensure the database exists and is accessible');
+    }
+    catch (error) {
+        Output.newline();
+        Output.error(`Database setup failed: ${error.message}`);
+        Output.errorDetail('Check your .env file and ensure the database exists and is accessible');
         return false;
     }
 
@@ -30,7 +33,8 @@ export default async function rollback(options = {}) {
         return result.success;
 
     } catch (error) {
-        console.error('❌ Rollback error:', error.message);
+        Output.newline();
+        Output.error(`Rollback error: ${error.message}`);
         await DB.close();
         return false;
     }

package/lib/Console/Commands/MigrateStatusCommand.js

@@ -2,6 +2,7 @@ import dotenv from 'dotenv';
 import DB from '../../Database/DB.js';
 import Config from '../../Core/Config.js';
 import MigrationRunner from '../../Database/Migration/MigrationRunner.js';
+import Output from '../../Console/Output.js';
 
 export default async function status() {
     dotenv.config({ quiet: true });
@@ -9,9 +10,11 @@ export default async function status() {
 
     try {
         await DB.setup();
-    } catch (error) {
-        console.error('❌ Database setup failed:', error.message);
-        console.error('Check your .env file and ensure the database exists and is accessible');
+    }
+    catch (error) {
+        Output.newline();
+        Output.error(`Database setup failed: ${error.message}`);
+        Output.errorDetail('Check your .env file and ensure the database exists and is accessible');
         return false;
     }
 
@@ -21,7 +24,8 @@ export default async function status() {
         return true;
 
     } catch (error) {
-        console.error('❌ Status error:', error.message);
+        Output.newline();
+        Output.error(`Status error: ${error.message}`);
         await DB.close();
         return false;
     }

package/lib/Console/Commands/SeedCommand.js

@@ -3,39 +3,26 @@ import DB from '../../Database/DB.js';
 import Config from '../../Core/Config.js';
 import SeederRunner from '../../Database/Seeder/SeederRunner.js';
 
-export default async function seed(options = {}) {
-    const { environment = 'prod', status = false } = options;
-
+export default async function seed(seederName = null) {
     dotenv.config({ quiet: true });
     await Config.initialize();
 
     try {
         await DB.setup();
-    } catch (error) {
+    }
+    catch (error) {
         console.error('❌ Database setup failed:', error.message);
         console.error('Check your .env file and ensure the database exists and is accessible');
         return false;
     }
 
     try {
-        if (status) {
-            await SeederRunner.printStatus();
-            await DB.close();
-            return true;
-        }
-
-        let result;
-
-        if (environment === 'all') {
-            result = await SeederRunner.runAll();
-        } else {
-            result = await SeederRunner.run(environment);
-        }
-
+        const result = await SeederRunner.run(seederName);
         await DB.close();
         return result.success;
 
-    } catch (error) {
+    }
+    catch (error) {
         console.error('❌ Seeding error:', error.message);
         await DB.close();
         return false;
@@ -45,16 +32,9 @@ export default async function seed(options = {}) {
 const isMain = process.argv[1]?.endsWith("SeedCommand.js");
 if (isMain) {
     const args = process.argv.slice(2);
+    const seederName = args.find(a => !a.startsWith('--')) || null;
 
-    const showStatus = args.includes('--status');
-    const isDev = args.includes('--dev');
-    const isAll = args.includes('--all');
-
-    let environment = 'prod';
-    if (isDev) environment = 'dev';
-    if (isAll) environment = 'all';
-
-    seed({ environment, status: showStatus })
+    seed(seederName)
         .then(success => process.exit(success ? 0 : 1))
         .catch(err => {
             console.error(err);

package/lib/Console/Commands/StorageLinkCommand.js

@@ -1,21 +1,36 @@
 import fs from "fs";
 import path from "path";
 import os from "os";
+import Output from "../Output.js";
 
+/**
+ * Creates a symbolic link from storage/app/public to public/storage.
+ * @returns {Promise<boolean>}
+ */
 export default async function storageLink() {
     const source = path.join(process.cwd(), "storage", "app", "public");
     const target = path.join(process.cwd(), "public", "storage");
-
-    let linkType = os.platform() === 'win32' ? 'junction' : 'dir';
+    const linkType = os.platform() === "win32" ? "junction" : "dir";
 
     return new Promise((resolve, reject) => {
         fs.symlink(source, target, linkType, (err) => {
             if (err) {
-                console.error('Error creating symbolic link:', err);
-                reject(err);
+                if (err.code === "EEXIST") {
+                    Output.warn("Symbolic link already exists");
+                    Output.dim(`  ${source} → ${target}`);
+                    Output.newline();
+                    resolve(true);
+                }
+                else {
+                    Output.error("Failed to create symbolic link");
+                    Output.dim(`  ${err.message}`);
+                    reject(err);
+                }
             }
             else {
-                console.log('Symbolic link has been created successfully.');
+                Output.success("Symbolic link created");
+                Output.dim(`  ${source} → ${target}`);
+                Output.newline();
                 resolve(true);
             }
         });